# Dscape Restful API文档

这里是Dscape服务端的API文档。这里定义了该服务的接口以及调用方式。

若无特殊说明，请求均以json格式发送，参数字段对应为json的key，值为value

值类型中若有`(header)`，则代表该字段应放在请求header中，而`(url)`则代表该字段放置在URL请求路径中

这里并的接口并不完全遵照REST

注意，所有的请求都是在https下进行的

所有接口的Base URL：`https://dscape.lensfrex.net/api/v1`

---

## 0. 通用信息（非http状态码）

| code | 信息 |
| --- | --- |
| 20000 | 成功 |
| 30000 | 参数错误 |
| 30001 | token过期 |
| 40300 | 权限不足 |
| 40000 | 非法请求 |
| 50000 | 服务器内部错误 |

---

## 1. 登录认证

### 用户登录

- URL路径：`/user/login`
- 方法：`POST`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | userName | string | false |用户登录名，非空 |
    | password | string | false |用户登录密码，非空，其值为明文密码两次sha256加密 |

    例如：
    ``` json
    {
        "userName": "admin",
        "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052"
    }
    ```

- 返回数据
  
    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | uid | string | 用户对应的uid |
    | role | int | 用户权限类型，0：普通用户，1：管理员 |
    | access_token | string | 本次登录得到的token，过期后应当用refresh_token重新获取 |
    | refresh_token | string | 刷新用的token，过期后应当重新登录 |
    | expired | long | access_token过期时间 |

    例如：(token为精简过的jwt)
    ``` json
    {
        "code": 20000,
        "msg": "success",
        "data": {
            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
            "role": 0,
            "access_token": "eyJ0NiJ9.eyJ1aWQijEwOH0.3CHJSQH1cD24",
            "refresh_token": "eyJ0NiJ9.eyJ1aWQijEwOH0.3CHJSQH1cD24",
            "expired": 1658676108943
        }
    }
    ```
- 错误信息

    | code | 错误 |
    | --- | --- |
    | 40301 | 用户名或密码错误 |
    | 40302 | 用户已被封禁 |
    | 40305 | 上级管理员未认证该用户 |

---

### 用户注册（公共）

> 用户注册可由管理员手动创建，也可以由用户自行注册，但是需要提供管理员名称，并且由管理员确认信息后才能使用
>
> 在系统中首次注册的用户即为管理员，管理员注册后普通用户必须要提供上级管理员才能注册

- URL路径：`/user/register`
- 方法：`POST`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | userName | string | false | 用户登录名，非空 |
    | password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
    | superior | string | true | 上级管理员用户名 |

    例如：
    ``` json
    {
        "userName": "admin",
        "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
        "superior": "lensfrex"
    }
    ```

- 返回数据
  
    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | uid | string | 用户对应的uid |

    例如：
    ``` json
    {
        "code": 20000,
        "msg": "success",
        "data" : {
            "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0"
        }
    }
    ```

- 错误信息

    | code | 错误 |
    | --- | --- |
    | 40300 | 权限不足 |
    | 20001 | 用户已存在 |

> 管理员添加用户，详见[添加用户](#添加用户)

---

## 2. 计算相关

### 请求计算

- URL路径：`/compute/add`
- 方法：`POST`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | pid | string | false | 患者数据id |
    | ctdna | int | false | 患者ctDNA长度 |
    | cpg | int | false | 患者甲基化位点数 |
    | token | string(header) | false |请求token，必须提供 |

    例如：
    ``` json
    {
        "pid": "2333",
        "ctdna": "213",
        "cpg": "4"
    }
    ```

- 返回数据
  
    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | id | string | 本次计算请求的任务id |

    例如：
    ``` json
    {
        "code": 20000,
        "msg": "success",
        "data" : {
            "id": "33168d5f3d8658f25ae17724d00b6fd0"
        }
    }
    ```

    > 计算状态信息的获取，详见[计算状态查询](#计算状态查询)

- 错误信息

    | code | 错误 |
    | --- | --- |
    | 40300 | 权限不足 |
    | 40303 | 计算请求的ip已被封禁 |
    | 40304 | 计算请求的用户已被封禁 |
    | 40305 | 用户的计算配额到达上限 |

---

### 计算记录查询

- URL路径：`/history/query/{uid}?offset={offset}&limit={limit}&page={page}`
- 方法：`GET`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | 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条数据：
    ``` 
    https://dscape.lensfrex.net/api/v1/history/query/9a6d777c-997d-a7e5-35f4-8471b7582ac0?offset=20&limit=10&page=3
    ```

- 返回数据
  
    > data部分以数组的形式返回

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | id | int | 数据id |
    | pid | int | 患者id |
    | ctdna | int | 患者ctDNA长度 |
    | cpg | int | 患者甲基化位点数 |
    | hcc | boolean | 患者是否为HCC |
    | hcc_infer | boolean | 推算得出的HCC状态 |
    | 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路径：`/history/delete/{rid}`
- 方法：`DELETE` 或 `GET`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | rid | int(url) | false | 欲删除的计算历史记录 |
    | token | string(header) | false |当前登录用户的token |

    例如，需要获取id为`1145`的记录：
    ``` 
    https://dscape.lensfrex.net/api/v1/history/delete/1145
    ```

- 返回数据

    > data部分无返回数据    
    
    例如：
    ``` json
    {
        "code": 20000,
        "msg": "success",
        "data" : null
    }
    ```

- 错误信息

    | code | 错误 |
    | --- | --- |
    | 40300 | 权限不足 |

---

### 计算状态查询

- URL路径：`/compute/status/{tid}`
- 方法：`GET`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | tid | string | false | 计算任务的id |
    | token | string(header) | false | 当前登录用户的token |

    例如：
    ``` 
    https://dscape.lensfrex.net/api/v1/compute/status/33168d5f3d8658f25ae17724d00b6fd0
    ```

- 返回数据
  
    | 参数 | 值类型 | 说明 |
    | --- | --- | --- | 
    | id | string | 本次计算请求的任务id |
    | status | int | 计算状态，0：完成，1：计算中，3：排队中，4：已被终止或未被运行 |

    例如：
    ``` json
    {
        "code": 20000,
        "msg": "success",
        "data" : {
            "id": "33168d5f3d8658f25ae17724d00b6fd0",
            "status": 0
        }
    }
    ```

- 错误信息

    | code | 错误 |
    | --- | --- |
    | 40300 | 权限不足 |

---

## 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 | 用户已存在 |

---

### 修改密码

> 修改密码只能由用户自己修改，或者管理员重置密码

- URL路径：`/user/modifyPassword/{uid}`
- 方法：`POST`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | uid | string(url) | false |欲修改密码的用户uid |
    | old_password | string | true |原始密码，其值为明文密码两次sha256加密，若不提供，则token拥有者应当为管理员 |
    | new_password | string | false | 新密码，其值为明文密码两次sha256加密 |
    | token | string(header) | false | 当前对应用户的uid |

    例如：
    ``` json
    {
        "old_password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
        "new_password": "384fde3636e6e01e0194d2976d8f26410af3e846e573379cb1a09e2f0752d8cc"
    }
    ```

- 返回数据
  
    > data部分无返回数据

    例如：
    ``` json
    {
        "code": 20000,
        "msg": "success",
        "data" : null
    }
    ```

- 错误信息

    | code | 错误 |
    | --- | --- |
    | 40300 | 权限不足 |

---

### 封禁、删除用户

- URL路径：`/user/admin/modifyStatus/{uid}`
- 方法：`POST`

- 请求参数：

    | 参数 | 值类型 | 可空 | 说明 |
    | --- | --- | --- | --- | 
    | uid | string(url) | false | 欲修改状态的用户uid |
    | status | int | false |修改状态，0：正常；1：彻底封禁（无法登录）；2：注销（销号）；3：计算封禁 |
    | token | string(header) | 当前对应用户的uid |

    例如：
    ``` json
    {
        "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
        "new_password": 1
    }
    ```

- 返回数据
  
    > data部分无返回数据

    例如：
    ``` json
    {
        "code": 20000,
        "msg": "success",
        "data" : null
    }
    ```

- 错误信息

    | code | 错误 |
    | --- | --- |
    | 40300 | 权限不足 |

---

### 管理员获取待审批注册用户

- URL路径：`/user/admin/application/list?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,
                "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
                "name": "lensfrex2",
                "ip": "127.0.0.1",
                "time": "2022-07-10 08:00:00"
            },            
            {
                "id": 64889,
                "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac1",
                "name": "lensfrex2",
                "ip": "127.0.0.1",
                "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 | 权限不足 |

---