Merge branch 'master' into feature/validate-email

ProjectAnni · Dec 15, 2021 · d3761a2 · d3761a2
2 parents 0fd9fb5 + c3f2252
commit d3761a2
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 47 deletions.
diff --git a/src/06.anniv/02.user.md b/src/06.anniv/02.user.md
@@ -6,15 +6,14 @@
 
 | 错误代码 | 详情             |
 | -------- | ---------------- |
-| `102000` | 注册用户名不可用 |
 | `102001` | 注册邮箱不可用   |
 | `102010` | 邮箱或密码错误   |
-| `102020` | 待注销用户不存在 |
+| `102020` | 用户不存在 |
 | `102030` | 验证邮件发送失败 |
 
-## 对用户密码的预处理（建议）
+## 对用户密码的预处理
 
-为格式统一考虑，建议客户端在向服务端发送密码之前，对用户的明文密码进行一次 `sha256` 处理。该步骤仅在一定程度上减少用户原文密码的泄露，但仍可以通过诸如彩虹表的方式破解。
+客户端在向服务端发送密码之前，须对用户的明文密码进行一次 `sha256` 处理。该步骤仅在一定程度上减少用户原文密码的泄露，但仍可以通过诸如彩虹表的方式破解。
 
 ## 用户信息
 
@@ -33,7 +32,6 @@
 | 参数名     | 类型      | 详情                 |
 | ---------- | --------- | -------------------- |
 | `user_id`  | `string`  | 用户 ID              |
-| `username` | `string`  | 用户名               |
 | `email`    | `string`  | 邮箱                 |
 | `nickname` | `string`  | 昵称                 |
 | `avatar`   | `string`  | 头像链接             |
@@ -44,13 +42,55 @@
 ```typescript
 interface UserInfo {
   user_id: string;
-  username: string;
   email: string;
   nickname: string;
   avatar: string;
   verified: boolean;
 }
 ```
+
+## 用户简介
+
+### Endpoint
+
+`GET /api/user/intro`
+
+### 请求
+
+#### 请求参数
+
+| 参数名    | 类型     | 详情    |
+| --------- | -------- | ------- |
+| `user_id` | `string` | 用户 ID |
+
+### 返回
+
+返回指定用户的用户简介（`UserIntro`）。
+
+#### 返回参数
+
+| 参数名     | 类型     | 详情     |
+| ---------- | -------- | -------- |
+| `user_id`  | `string` | 用户 ID  |
+| `nickname` | `string` | 昵称     |
+| `avatar`   | `string` | 头像链接 |
+
+### 参数表示
+
+```typescript
+interface UserIntro {
+  user_id: string;
+  nickname: string;
+  avatar: string;
+}
+```
+
+### 错误列表
+
+| 错误代码 | 详情       |
+| -------- | ---------- |
+| `102020` | 用户不存在 |
+
 ## 用户注册
 
 ### Endpoint
@@ -63,7 +103,6 @@ interface UserInfo {
 
 | 参数名     | 类型     | 详情     |
 | ---------- | -------- | -------- |
-| `username` | `string` | 用户名   |
 | `password` | `string` | 密码     |
 | `email`    | `string` | 邮箱     |
 | `nickname` | `string` | 昵称     |
@@ -77,9 +116,8 @@ interface UserInfo {
 
 ```typescript
 interface UserRegisterBody {
-  username: string;
-  password: string;
   email: string;
+  password: string;
   nickname: string;
   avatar: string;
 }
@@ -89,7 +127,6 @@ interface UserRegisterBody {
 
 | 错误代码 | 详情             |
 | -------- | ---------------- |
-| `102000` | 注册用户名不可用 |
 | `102001` | 注册邮箱不可用   |
 
 ## 用户登录
@@ -132,10 +169,6 @@ interface UserLoginBody {
 
 `POST /api/user/logout`
 
-### 返回
-
-当退出成功时，返回 `204 No Content`。
-
 ### 客户端设计指引
 
 当用户退出成功时，建议清理对应客户端的 `Cookie`。
@@ -154,10 +187,6 @@ interface UserLoginBody {
 
 `POST /api/user/revoke`
 
-### 返回
-
-当注销成功时，返回 `204 No Content`。
-
 ### 参数表示
 
 ```typescript
@@ -172,9 +201,9 @@ interface UserRevokeBody {
 
 ### 错误列表
 
-| 错误代码 | 详情                                                       |
-| -------- | ---------------------------------------------------------- |
-| `102020` | 待注销用户不存在，该错误可能出现于客户端保留了注销前的凭据 |
+| 错误代码 | 详情                                                 |
+| -------- | ---------------------------------------------------- |
+| `102020` | 用户不存在，该错误可能出现于客户端保留了注销前的凭据 |
 
 ## 使用情况
 
@@ -189,13 +218,11 @@ interface UserRevokeBody {
 | 参数       | 类型     | 详情   |
 | ---------- | -------- | ------ |
 | `email`    | `string` | 邮箱   |
-| `username` | `string` | 用户名 |
 
 ### 错误列表
 
 | 错误代码 | 详情             |
 | -------- | ---------------- |
-| `102000` | 注册用户名不可用 |
 | `102001` | 注册邮箱不可用   |
 
 ## 验证邮箱
@@ -211,4 +238,4 @@ interface UserRevokeBody {
 | 错误代码 | 详情                     |
 | -------- | ------------------------ |
 | `102030` | 验证邮件发送失败         |
-| `903000` | 超出频率限制，请稍后再试 |
+| `903000` | 超出频率限制，请稍后再试 |
diff --git a/src/06.anniv/04.credential.md b/src/06.anniv/04.credential.md
@@ -25,32 +25,24 @@
 
 | 参数名     | 类型     | 详情                     |
 | ---------- | -------- | ------------------------ |
+| `id`       | `string` | `Token` 的 `ID`          |
 | `name`     | `string` | `Annil` 名称             |
 | `url`      | `string` | `Annil` 站点地址         |
 | `token`    | `string` | `Annil Token` 内容       |
 | `priority` | `number` | 客户端尝试访问时的优先级 |
 
-`Id` 的定义如下：
-
-| 参数名 | 类型     | 详情            |
-| ------ | -------- | --------------- |
-| `id`   | `string` | `Token` 的 `ID` |
-
 ### 参数表示
 
 ```typescript
 type GetTokensResponse = Token[];
 
 interface Token {
+  id: string;
   name: string;
   url: string;
   token: string;
   priority: number;
 }
-
-interface Id {
-  id: string;
-}
 ```
 
 ## 新增 Token
@@ -63,10 +55,6 @@ interface Id {
 
 新增请求的类型为 `Token`。
 
-### 返回
-
-请求成功时，返回 `204 No Content`。
-
 #### 客户端实现指引
 
 每次请求成功后，客户端需重新获取一遍 `Token` 列表。
@@ -85,11 +73,7 @@ interface Id {
 
 ### 请求
 
-修改请求的类型为 `Token & Id`，其中 `Token` 部分各属性均为可选。
-
-### 返回
-
-请求成功时，返回 `204 No Content`。
+修改请求的类型为 `Token`，除 `id` 以外的各属性均可修改。
 
 ### 错误列表
 
@@ -111,10 +95,6 @@ interface Id {
 | ------ | -------- | ---------------------- |
 | `id`   | `string` | 待删除 `Token` 的 `ID` |
 
-### 返回
-
-请求成功时，返回 `204 No Content`。
-
 ### 错误列表
 
 | 错误代码 | 详情           |

diff --git a/src/06.anniv/features/02.2fa.md b/src/06.anniv/features/02.2fa.md
@@ -18,6 +18,7 @@
 - 用户注册（`POST /api/user/register`）
 - 用户登录（`POST /api/user/login`）
 - 用户注销（`POST /api/user/revoke`）
+- 用户信息（`POST /api/user/info`）
 
 TODO: 列举出用到 `2FA` 的所有位置
 
@@ -64,6 +65,15 @@ interface UserRevokeBody {
 }
 ```
 
+### 用户信息
+
+```typescript
+interface UserInfo {
+  // ...
+  "2fa_enabled"?: boolean;
+}
+```
+
 ## 绑定 `2FA`
 
 当 `2FA` 为可选项时，用户可以使用该接口绑定两步验证。当 `2fa_enforced` 启用时，未开启两步验证的用户可以通过该接口开启两步验证。