From 9b92a98749b158c7bcd3dd86b39d72333355f7db Mon Sep 17 00:00:00 2001
From: lensferno <lensferno@outlook.com>
Date: Mon, 11 Jul 2022 08:15:37 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0api=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 API-Document.md | 282 +++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 222 insertions(+), 60 deletions(-)

diff --git a/API-Document.md b/API-Document.md
index 7246715..09ffb0f 100644
--- a/API-Document.md
+++ b/API-Document.md
@@ -19,7 +19,8 @@
 | code | 信息 |
 | --- | --- |
 | 20000 | 成功 |
-| 30000 | 参数错误
+| 30000 | 参数错误 |
+| 30001 | token过期 |
 | 40300 | 权限不足 |
 | 40000 | 非法请求 |
 | 50000 | 服务器内部错误 |
@@ -35,10 +36,10 @@
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | userName | string | 用户登录名，非空 |
-    | password | string | 用户登录密码，非空，其值为明文密码两次sha256加密 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | userName | string | false |用户登录名，非空 |
+    | password | string | false |用户登录密码，非空，其值为明文密码两次sha256加密 |
 
     例如：
     ``` json
@@ -50,7 +51,7 @@
 
 - 返回数据
   
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
     | --- | --- | --- | 
     | uid | string | 用户对应的uid |
     | role | int | 用户权限类型，0：普通用户，1：管理员 |
@@ -78,43 +79,41 @@
     | --- | --- |
     | 40301 | 用户名或密码错误 |
     | 40302 | 用户已被封禁 |
+    | 40305 | 上级管理员未认证该用户 |
 
 ---
 
-### 用户注册
+### 用户注册（公共）
 
-> 普通用户并不提供注册功能，只能由管理员添加
+> 用户注册可由管理员手动创建，也可以由用户自行注册，但是需要提供管理员名称，并且由管理员确认信息后才能使用
 >
-> 在系统中首次注册的用户即为管理员，管理员注册后注册接口将不会处理任何非管理员请求，只能由管理员用户请求
+> 在系统中首次注册的用户即为管理员，管理员注册后普通用户必须要提供上级管理员才能注册
 
 - URL路径：`/user/register`
 - 方法：`POST`
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | userName | string | 用户登录名，非空 |
-    | password | string | 用户登录密码，非空，其值为明文密码两次sha256加密 |
-    | role | int | 用户角色，该选项只能由管理员使用，其他用户提供不生效 |
-    | token | string(header) | 管理员的access_token，如不提供且已经有初始管理员则会导致请求失败（权限不足） |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | userName | string | false | 用户登录名，非空 |
+    | password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
+    | superior | string | true | 上级管理员用户名 |
 
     例如：
     ``` json
     {
         "userName": "admin",
         "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
-        "role": 0
+        "superior": "lensfrex"
     }
     ```
 
 - 返回数据
   
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
     | --- | --- | --- | 
     | uid | string | 用户对应的uid |
-    | role | int | 用户权限类型，0：普通用户，1：管理员 |
-
 
     例如：
     ``` json
@@ -122,16 +121,19 @@
         "code": 20000,
         "msg": "success",
         "data" : {
-            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
-            "role": 0
+            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0"
         }
     }
     ```
+
 - 错误信息
 
     | code | 错误 |
     | --- | --- |
     | 40300 | 权限不足 |
+    | 20001 | 用户已存在 |
+
+> 管理员添加用户，详见[添加用户](#添加用户)
 
 ---
 
@@ -144,12 +146,12 @@
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | pid | string | 患者数据id |
-    | ctdna | int | 患者ctDNA长度 |
-    | cpg | int | 患者甲基化位点数 |
-    | token | string(header) | 请求token，必须提供 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | pid | string | false | 患者数据id |
+    | ctdna | int | false | 患者ctDNA长度 |
+    | cpg | int | false | 患者甲基化位点数 |
+    | token | string(header) | false |请求token，必须提供 |
 
     例如：
     ``` json
@@ -162,7 +164,7 @@
 
 - 返回数据
   
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
     | --- | --- | --- | 
     | id | string | 本次计算请求的任务id |
 
@@ -197,13 +199,13 @@
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | uid | string(url) | 需要获取记录的用户uid |
-    | offset | int(url) | 分页数据偏移量 |
-    | limit | int(url) | 每页数据数量 |
-    | page | int(url) | 分页页码 |
-    | token | string(header) | 请求token，必须提供 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false | 需要获取记录的用户uid |
+    | offset | int(url) | false | 分页数据偏移量 |
+    | limit | int(url) | false | 每页数据数量 |
+    | page | int(url) | false | 分页页码 |
+    | token | string(header) | false | 请求token，必须提供 |
 
     例如，需要获取用户uid为`9a6d777c-997d-a7e5-35f4-8471b7582ac0`记录的第三页数据，每页10条数据：
     ``` 
@@ -214,8 +216,8 @@
   
     > data部分以数组的形式返回
 
-    | 字段 | 值类型 | 说明 |
-    | --- | --- | --- | 
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
     | id | int | 数据id |
     | pid | int | 患者id |
     | ctdna | int | 患者ctDNA长度 |
@@ -269,10 +271,10 @@
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | rid | int(url) | 欲删除的计算历史记录 |
-    | token | string(header) | 当前登录用户的token |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | rid | int(url) | false | 欲删除的计算历史记录 |
+    | token | string(header) | false |当前登录用户的token |
 
     例如，需要获取id为`1145`的记录：
     ``` 
@@ -292,7 +294,6 @@
     }
     ```
 
-
 - 错误信息
 
     | code | 错误 |
@@ -308,10 +309,10 @@
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | tid | string | 计算任务的id |
-    | token | string(header) | 当前登录用户的token |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | tid | string | false | 计算任务的id |
+    | token | string(header) | false | 当前登录用户的token |
 
     例如：
     ``` 
@@ -320,7 +321,7 @@
 
 - 返回数据
   
-    | 字段 | 值类型 | 说明 |
+    | 参数 | 值类型 | 说明 |
     | --- | --- | --- | 
     | id | string | 本次计算请求的任务id |
     | status | int | 计算状态，0：完成，1：计算中，3：排队中，4：已被终止或未被运行 |
@@ -347,9 +348,57 @@
 
 ## 3. 用户管理相关
 
+> 这部分的的大部分接口只能由管理员调用使用
+
 ### 添加用户
 
-> 该项与注册接口相同
+- URL路径：`/user/admin/add`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | userName | string | false | 用户登录名，非空 |
+    | password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
+    | role | int | true | 用户角色 |
+    | token | string(header) | 管理员的access_token |
+
+    例如：
+    ``` json
+    {
+        "userName": "admin",
+        "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
+        "role": 0
+    }
+    ```
+
+- 返回数据
+  
+    | 字段 | 值类型 | 说明 |
+    | --- | --- | --- | 
+    | uid | string | 用户对应的uid |
+    | role | int | 用户权限类型，0：普通用户，1：管理员 |
+
+
+    例如：
+    ``` json
+    {
+        "code": 20000,
+        "msg": "success",
+        "data" : {
+            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
+            "role": 0
+        }
+    }
+    ```
+
+- 错误信息
+
+    | code | 错误 |
+    | --- | --- |
+    | 40300 | 权限不足 |
+    | 20001 | 用户已存在 |
 
 ---
 
@@ -362,12 +411,12 @@
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | uid | string(url) | 欲修改密码的用户uid |
-    | old_password | string | 原始密码，其值为明文密码两次sha256加密，若不提供，则token拥有者应当为管理员 |
-    | new_password | string | 新密码，其值为明文密码两次sha256加密 |
-    | token | string(header) | 当前对应用户的uid |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false |欲修改密码的用户uid |
+    | old_password | string | true |原始密码，其值为明文密码两次sha256加密，若不提供，则token拥有者应当为管理员 |
+    | new_password | string | false | 新密码，其值为明文密码两次sha256加密 |
+    | token | string(header) | false | 当前对应用户的uid |
 
     例如：
     ``` json
@@ -400,15 +449,15 @@
 
 ### 封禁、删除用户
 
-- URL路径：`/user/modifyStatus/{uid}`
+- URL路径：`/user/admin/modifyStatus/{uid}`
 - 方法：`POST`
 
 - 请求参数：
 
-    | 参数 | 值类型 | 说明 |
-    | --- | --- | --- | 
-    | uid | string(url) | 欲修的用户uid |
-    | status | int | 修改状态，0：正常；1：彻底封禁（无法登录）；2：注销（销号）；3：计算封禁 |
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false | 欲修改状态的用户uid |
+    | status | int | false |修改状态，0：正常；1：彻底封禁（无法登录）；2：注销（销号）；3：计算封禁 |
     | token | string(header) | 当前对应用户的uid |
 
     例如：
@@ -436,4 +485,117 @@
 
     | code | 错误 |
     | --- | --- |
-    | 40300 | 权限不足 |
\ No newline at end of file
+    | 40300 | 权限不足 |
+
+---
+
+### 管理员获取待审批注册用户
+
+- URL路径：`/user/admin/application/query?offset={offset}&limit={limit}&page={page}`
+- 方法：`GET`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | offset | int(url) | false | 分页数据偏移量 |
+    | limit | int(url) | false | 每页数据数量 |
+    | page | int(url) | false | 分页页码 |
+    | token | string(header) | false | 请求token，必须提供 |
+
+    例如，需要第三页数据，每页10条数据：
+    ``` 
+    https://dscape.lensfrex.net/api/v1/user/admin/apply?offset=20&limit=10&page=3
+    ```
+
+- 返回数据
+  
+    > data部分以数组的形式返回
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | id | int | 审批记录id |
+    | uid | string | 待审批用户uid |
+    | name | string | 待审批用户名 |
+    | ip | string | 用户发送审批时的ip |
+    | time | datetime(string) | 申请时间 |
+    
+    例如：
+    ``` json
+    {
+        "code": 20000,
+        "msg": "success",
+        "data" : [
+            {
+                "id": 64888,
+                "pid": 2333,
+                "ctdna": 209,
+                "cpg": 5,
+                "hcc": true,
+                "hcc_infer": true,
+                "time": "2022-07-10 08:00:00"
+            },            
+            {
+                "id": 648888,
+                "pid": 23333,
+                "ctdna": 209,
+                "cpg": 5,
+                "hcc": true,
+                "hcc_infer": true,
+                "time": "2022-07-10 08:00:00"
+            },
+            // ...
+        ]
+    }
+    ```
+
+
+- 错误信息
+
+    | code | 错误 |
+    | --- | --- |
+    | 40300 | 权限不足 |
+
+---
+
+### 审核用户注册
+
+- URL路径：`/user/admin/application/deal/{uid}`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 可空 | 说明 |
+    | --- | --- | --- | --- | 
+    | uid | string(url) | false | 处理的用户uid |
+    | idea | boolean | false | 处理意见，true：通过；false：拒绝 |
+    | token | string(header) | 当前对应用户的uid |
+
+    例如：
+    ``` json
+    {
+        "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
+        "idea": true
+    }
+    ```
+
+- 返回数据
+  
+    > data部分无返回数据
+
+    例如：
+    ``` json
+    {
+        "code": 20000,
+        "msg": "success",
+        "data" : null
+    }
+    ```
+
+- 错误信息
+
+    | code | 错误 |
+    | --- | --- |
+    | 40300 | 权限不足 |
+
+---