1
0
mirror of https://gitee.com/tawords/tawords-docs synced 2025-09-01 23:43:27 +08:00
Code Issues Projects Releases Wiki Activity GitHub Gitee

网站使用相对路径;整理 [三、接口文档] 部分文档

This commit is contained in:
2021-08-07 04:11:07 +08:00
parent 5b6bfdbb41
commit be48289d54
53 changed files with 142 additions and 409 deletions

View File

@@ -1,33 +0,0 @@
# 创建第一个主题
> 在开始之前你需要掌握HTML CSS JavaScript以及PHP的相关知识。在主题的开发过程中会涉及到这些知识。本文档是基于你已经掌握这些知识的基础上撰写的。
让我们开始吧。
## 应用介绍
- 应用分为主题和插件;
- 可以同时启用多个应用(但是需要考虑是否兼容);
- 按照规范组织目录结构;
- 在后台统一安装、删除、启用、关闭;
- 「自述文件」为 `intro.json`
- 应用放置目录为 `/system`
### 主题
- 主题是网站前端的显示效果,同时只能启用一个主题;
- 通过提供的统一接口获取需要显示的内容;
- 主题可以内置1个应用也可不内置对主题的能力进行扩展启用状态与主题保持一致
- 所在目录为 `/system/plugin`
### 插件
- 主要作用为扩展网站的某项功能;
- 可以同时启用多个应用(但是需要考虑是否兼容);
- 所在目录为 `/system/plugin`

View File

@@ -1,80 +0,0 @@
## 下载应用模板
| 主题模板 | 插件模板 |
| ---------------------- | ---------------------- |
| [点击下载]()【待完善】 | [点击下载]()【待完善】 |
## 文件结构
```conf
/path/system/theme/themeName
screenshot.png [必需]缩略图500×400像素
intro.json [必需]自述文件【该文件由系统生成】;
README.md [不需要]应用开发模板说明文件,可以删除。
—————————————— 下面的待更新 ——————————————
main.php [可选]应用内置管理页,在创建主题时填写才会生成;
include.php [可选]应用嵌入页,在创建主题时填写才会生成;
include [可选]主题自带「文件模块」,使用{module:abc}「嵌入调用」该目录下的abc.php文件
script [可选]JS目录
style [必需]样式目录, 内存样式表及所需图片;
style.css [必需]不限于这个文件名,一套主题也可以拥有多个样式(各自独立使用);
css [可选]并不会自动创建用于不应该放在style文件夹中的样式内容
template 用于存放模板文件;建议优先确立以下 6 个模板文件及内容;
index.php 首页及列表页
single.php 文章页(单页)
search.php 搜索结果页不存在时使用index.php
header.php 公共头部文件
footer.php 公共尾部文件
404.php 建议设置
```
## 应用配置文件
### intro.json
> 注意建议使用工具生成或修改该文件。如果手动修改特殊字符或符号可能会导致JSON解析失败。
>
> [点击使用工具]()【待完善】
```
{
"plug": {
"plugId": "应用Id [必填]",
"name": "应用名称 [必填]",
"description": "应用简介 [必填]",
"pubDate": "发布日期格式2022-01-01 [必填]",
"update": "升级时间格式2022-01-01 [必填]",
"version": "版本号格式“1.0.0”或“1.0”。请严格按照格式填写,以免用户无法正常升级 [必填]",
"adapted": "最低兼容的系统版本数字代号(可在文档 关于 版本信息 发行版本 找到),此处请填写数字,不要填写字符串 [必填]",
"screenShot": "./preview.png 主题的缩略图所在相对路径 [必填]"
},
"author": {
"authorId": "作者Id后台创建应用时生成 [必填]",
"name": "作者姓名 [必填]",
"email": "作者邮箱 [选填]",
"url": "作者网站 [选填]"
}
}
```
| 字段 | 说明 / 格式 | 是否必填 | intro.json |
| -------- | -------------- | ---------------------------- | ---------------------------- |
| 应用Id | 创建应用时生成 | 必填 | plug.plugId |
| 应用名称 | | 必填 | plug.name |
| 应用简介 | | | plug.description |
| | | | plug.update |
| | | | plug.version |
| | | | plug.adapted |
| | | | plug.screenShot |
| | | | plug. |
| | | | |

View File

@@ -1,31 +0,0 @@
> `@since` 表示从那个版本开始就有这个类/接口/方法
> `@deprecated` 表示不建议使用该类/接口/方法
> `@exception` 标注Runtime异常
> `@throws` 标注非Runtime异常
类、接口
```php
/**
* 〈一句话功能简述〉LogManager 类集中控制对日志读写的操作。
* 〈功能详细描述〉全部为静态变量和静态方法,对外提供统一接口。分配对应日志类型的读写器,读取或写入符合条件的日志纪录。
* @author [作者]张三,李四,王五
* @version [版本号, YYYY-MM-DD]1.2, 2001-03-25
* @see [相关类/方法]LogIteraotor
* @see [相关类/方法]BasicLog
* @since [产品/模块版本]CommonLog1.0
*/
```
方法
```php
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @param [参数1] [参数1说明]
* @param [参数2] [参数2说明]
* @return [返回类型说明]
* @exception/throws [违例类型] [违例说明]
* @see [类、类#方法、类#成员]
* @deprecated
*/
```

View File

@@ -1,118 +0,0 @@
#### 1.在有处理逻辑的代码中源程序有效注释量必须在20以上。
> 说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。
#### 2.文件注释:文件注释写入文件头部。
> 说明:以`/**`开始
示例:
```php
/**
* 文件名:[文件名]
* 作者:〈版权〉
* 描述:〈描述〉
* 修改人:〈修改人〉
* 修改时间YYYY-MM-DD
* 修改内容:〈修改内容〉
*/
```
> 说明:每次修改后在文件头部写明修改信息。
示例:
```php
/**
* 文件名LogManager.java
* 版权Copyright 2000-2001 Huawei Tech. Co. Ltd. All Rights Reserved.
* 描述: WIN V200R002 WEBSMAP 通用日志系统
* 修改人:张三
* 修改时间2001-02-16
* 修改内容:新增
* 修改人:李四
* 修改时间2001-02-26
* 修改内容:。。。。。。
* 修改人:王五
* 修改时间2001-03-25
* 修改内容:。。。。。。
*/
```
#### 3.类和接口的注释:该注释放在 `class` 定义之前,`using` 或 `package` 关键字之后。
示例:
```php
package com.websmap.comm;
/**
* 注释内容
*/
public class CommManager
```
#### 4.类和接口的注释内容:类的注释主要是一句话功能简述、功能详细描述,说明:可根据需要列出:版本号、生成日期、作者、内容、功能、与其它类的关系等。
格式:
```php
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @author [作者]
* @version [版本号, YYYY-MM-DD]
* @see [相关类/方法]
* @since [产品/模块版本]
* @deprecated
*/
```
> 说明:描述部分说明该类或者接口的功能、作用、使用方法和注意事项,每次修改后增加作者和更新版本号和日期,`@since` 表示从那个版本开始就有这个类或者接口,`@deprecated` 表示不建议使用该类或者接口。
示例:
```php
/**
* LogManager 类集中控制对日志读写的操作。
* 全部为静态变量和静态方法,对外提供统一接口。分配对应日志类型的读写器,读取或写入符合条件的日志纪录。
* @author 张三,李四,王五
* @version 1.2, 2001-03-25
* @see LogIteraotor
* @see BasicLog
* @since CommonLog1.0
*/
```
#### 5.类属性、公有和保护方法注释:写在类属性、公有和保护方法上面。用 `// ` 来注释,需要对齐被注释代码。
示例:
```php
// 注释内容
private String logType
```
#### 6.成员变量注释内容:成员变量的意义、目的、功能,可能被用到的地方。用 `// ` 来注释,需要对齐被注释代码。
#### 7.公有和保护方法注释内容:列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
格式:
```php
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @param [参数1] [参数1说明]
* @param [参数2] [参数2说明]
* @return [返回类型说明]
* @exception/throws [违例类型] [违例说明]
* @see [类、类#方法、类#成员]
* @deprecated
*/
```
> 说明:`@since` 表示从那个版本开始就有这个方法;`@exception`或 `throws` 列出可能出现的异常;`@deprecated` 表示不建议使用该方法。
#### 8.对于方法内部用 `throw` 语句抛出的异常,必须在方法的注释中标明,对于所调用的其他方法所抛出的异常,选择主要的在注释中说明。对于非 `RuntimeException` ,即 `throws` 子句声明会抛出的异常,必须在方法的注释中标明。
> 说明:异常注释用 `@exception`或 `@throws` 表示在JavaDoc中两者等价但推荐用 `@exception` 标注Runtime异常`@throws` 标注非Runtime异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。
#### 9.注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
#### 10.注释的排版,按照上述示例来展示。
#### 11.注释应该放在被注释的代码前面,分行展示,但中间不留空行。
#### 12.对变量的定义和分支语句(条件分支、循环语句等)必须编写注释。
> 说明:分支语句往往是程序实现某一特定功能的关键。
#### 13.边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除。
#### 14.注释的内容要清楚、明了,含义准确,防止注释二义性。说明:错误的注释不但无益反而有害。
#### 15.避免在注释中使用缩写,特别是不常用缩写。说明:在使用缩写时或之前,应对缩写进行必要的说明。

View File

@@ -1,2 +0,0 @@
为避免重复及便于识别,应用名中不能出现特殊字符,应用识别名须遵循驼峰式书写规范,只能包含`大小写字母`和下划线`_`,应用目录名为应用识别名,定义的所有函数需要以应用识别名加`_`作为前缀;
所有目录及文件名,全部小写,不得出现大写字母;

View File

@@ -1,13 +0,0 @@
# 登录:
> 使用`密码加盐`生成不可逆哈希,**他人无法获取密码原文**。
```javascript
md5.hex(pwd + md5.hex(pwd));
```
# 注册:
> 使用密码倒序`Base64`加密,再倒序`Base64`加密,避免密码在网上裸奔。
```javascript
Base64.encode(Base64.encode(pwd.split('').reverse().join('')).split('').reverse().join(''));
```
网站使用`SSL证书`即网址前面的https数据传输`非对称加密`(即使用“公钥”加密,“私钥”解密,公钥大家都知道,私钥仅服务器知道),确保中间人无法获得您的密码。

View File

@@ -1,99 +0,0 @@
# 发布应用
> 在编写并测试好代码后,可以将应用上传至应用中心进行审核。审核通过后即可发布。
>
> 应用期将视应用中心实际情况适时开发上线。
以下是发布应用的流程。
### 1. 成为开发者
成为开发者的条件:①有开发者账号;②绑定手机号;③等待通过审核
首先,你需要注册一个开发者应用账号。
然后,在用户中心绑定您的手机号,并完善账户信息。
最后,点击提交审核按钮,等待审核通过。审核期间,您可以上传应用以及配置相关信息,也可同时提交应用审核,但只有审核通过后,你的应用才可以发布至应用中心。
> **请注意,账号一旦注册,用户名等账户重要信息暂时不可修改。所以注册账号时一定要想好。**
> 根据《互联网用户账号名称管理规定》等相关规定,您只有绑定手机号才可以进行后续操作。
### 2. 在后台创建一个应用
创建应用后,系统会为你生成一个**应用ID**`plugId`)和**应用密钥**`plugSecret`)。`plugSecret`将只显示一次,请保存好这两个密钥,如果您忘记了,则需要重置`plugSecret`
- `plugId`用于唯一标识应用。在用户下载应用,或者更新应用的时候会用到。该值由系统生成,无法修改。
- `plugSecret`的用处还没想好,但是是有用的【待更新】
> **请一定保管好plugSecret不要泄露给任何人如果已发生泄露请立即重置plugSecret**
### 3. 上传你的应用
根据页面提示上传您的应用。
上传应用后,应用信息将默认使用`intro.json`文件中的信息。如需修改,可修改`intro.json`文件,然后重新上传。
> `intro.json`编写规范请[查看这里]()【待完善】
- 应用发布日期(与配置文件中`pubDate`保持一致,且不能填写还未到的日期,一旦首次审核通过,将不能更改)
- 选择你的应用风格
-
- 上传应用缩略图
-
### 4. 阅读并同意应用中心相关条款
在认真阅读并同意应用中心服务协议、隐私政策等条款内容后,勾选“我已阅读并同意上述条款”,然后点击下一步。
### 5. 提交审核
确认应用信息填写无误后,即可提交审核。
> 第一次审核通过日期显示为<u>应用发布日期</u>,开发者无法手动修改。
若审核未通过,您可以根据提示信息修改对应信息,并再次提交。
> 请注意,若审核未通过,请修改后再次提交。请不要不经修改反复提交。否则您的账号将可能受到相应处罚,甚至封号。
# 应用更新
主题更新时,你需要做以下几步:
上传新的主题包,填写更新说明,并提交审核
## 1.上传新的应用包
登录后台,选择账号中需要更新的应用,然后点击修改。
## 2. 填写更新说明
上传应用包后,填写版本更新说明。
如果需要修改应用的其他信息,也可在当前页一并更改,更改后提交即可。
## 3. 提交审核
点击提交审核按钮,等待审核结果。

View File

@@ -1 +0,0 @@
如果有页面在当前主题中不存在,将使用默认页面展示。

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,12 @@
## 用户登录
<!-- 引入“Admin--login-status.md” -->
[用户登录](Admin--login-status.md ':include')
-----
## 用户注册
<!-- 引入“Admin--account-registration.md” -->
[用户注册](Admin--account-registration.md ':include')

View File

@@ -0,0 +1,2 @@
### (待完成)

View File

@@ -0,0 +1,5 @@
## 通用参数
<!-- 引入“General--parameters.md” -->
[通用参数](General--parameters.md ':include')

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,5 @@
## xxx
<!-- 引入“xxx” -->
[xxx](Notice--xxx.md ':include')

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,19 @@
## 检查更新
<!-- 引入“Site--check-update.md” -->
[检查更新](Site--check-update.md ':include')
-----
## 上传logo
<!-- 引入“Site--upload-logo.md” -->
[上传logo](Site--upload-logo.md ':include')
-----
## 站点基本信息
<!-- 引入“Site--basic-Information.md” -->
[站点基本信息](Site--basic-Information.md ':include')

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -1,7 +1,5 @@
> **密码禁止明文传输!** 加密方法见:开发文档 > 规范 > 注册、登录时密码使用的加密技术
## 接口列表
> api基础路径为 `./api/v1/users`
<!-- ################################## ################################## -->
@@ -76,6 +74,7 @@ $.ajax({
</details>
<!-- ################################## ################################## -->
--------------------------------------------------------------------------------
### ● 获取用户登录状态
@@ -124,6 +123,7 @@ $.getJSON("api/v1/users/get-status.php",function (res) {
</details>
<!-- ################################## ################################## -->
--------------------------------------------------------------------------------
### ● 退出登录

View File

@@ -1,7 +1,5 @@
> **密码禁止明文传输!** 加密方法见:开发文档 > 规范 > 注册、登录时密码使用的加密技术
## 接口列表
> api基础路径为 `./api/v1/users`
<!-- ################################## ################################## -->
@@ -63,6 +61,7 @@ $.ajax({
</details>
<!-- ################################## ################################## -->
--------------------------------------------------------------------------------
### ● 修改密码

View File

@@ -0,0 +1,19 @@
## 修改账户信息
<!-- 引入“User--modify-account-information.md” -->
[修改账户信息](User--modify-account-information.md ':include')
-----
## 用户登录、注销、获取状态
<!-- 引入“User--login-status.md” -->
[用户登录、注销、获取状态](User--login-status.md ':include')
-----
## 用户注册
<!-- 引入“User--account-registration.md” -->
[用户注册](User--account-registration.md ':include')

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,5 @@
## xxx
<!-- 引入“xxx” -->
[xxx](Wordbooks--xxx.md ':include')

View File

@@ -0,0 +1,2 @@
### (待完善)

View File

@@ -0,0 +1,5 @@
## xxx
<!-- 引入“xxx” -->
[xxx](Words--xxx.md ':include')

View File

@@ -0,0 +1,7 @@
- [0. 通用参数](./General)
- [1. 站点](./Site)
- [2. 管理员](./Admin)
- [3. 用户](./User)
- [4. 单词](./Words)
- [5. 词书](./Wordbooks)
- [6. 通知](./Notice)