添加API调用文档以及数据库结构sql文件（后续可能会改）

2 years ago · 57e1567977
parent 01b389ac1a
commit 57e1567977
3 changed files with 539 additions and 14 deletions
--- a/API-Document.md
+++ b/API-Document.md
@ -0,0 +1,439 @@
+# 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 | 参数错误
+| 40300 | 权限不足 |
+| 40000 | 非法请求 |
+| 50000 | 服务器内部错误 |
+
+---
+
+## 1. 登录认证
+
+### 用户登录
+
+- URL路径：`/user/login`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 说明 |
+    | --- | --- | --- | 
+    | userName | string | 用户登录名，非空 |
+    | password | string | 用户登录密码，非空，其值为明文密码两次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 | 用户已被封禁 |
+
+---
+
+### 用户注册
+
+> 普通用户并不提供注册功能，只能由管理员添加
+>
+> 在系统中首次注册的用户即为管理员，管理员注册后注册接口将不会处理任何非管理员请求，只能由管理员用户请求
+
+- URL路径：`/user/register`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 说明 |
+    | --- | --- | --- | 
+    | userName | string | 用户登录名，非空 |
+    | password | string | 用户登录密码，非空，其值为明文密码两次sha256加密 |
+    | role | int | 用户角色，该选项只能由管理员使用，其他用户提供不生效 |
+    | 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 | 权限不足 |
+
+---
+
+## 2. 计算相关
+
+### 请求计算
+
+- URL路径：`/compute/add`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 说明 |
+    | --- | --- | --- | 
+    | pid | string | 患者数据id |
+    | ctdna | int | 患者ctDNA长度 |
+    | cpg | int | 患者甲基化位点数 |
+    | token | string(header) | 请求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) | 需要获取记录的用户uid |
+    | offset | int(url) | 分页数据偏移量 |
+    | limit | int(url) | 每页数据数量 |
+    | page | int(url) | 分页页码 |
+    | token | string(header) | 请求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) | 欲删除的计算历史记录 |
+    | token | string(header) | 当前登录用户的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 | 计算任务的id |
+    | token | string(header) | 当前登录用户的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/modifyPassword/{uid}`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 说明 |
+    | --- | --- | --- | 
+    | uid | string(url) | 欲修改密码的用户uid |
+    | old_password | string | 原始密码，其值为明文密码两次sha256加密，若不提供，则token拥有者应当为管理员 |
+    | new_password | string | 新密码，其值为明文密码两次sha256加密 |
+    | token | string(header) | 当前对应用户的uid |
+
+    例如：
+    ``` json
+    {
+        "old_password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
+        "new_password": "384fde3636e6e01e0194d2976d8f26410af3e846e573379cb1a09e2f0752d8cc"
+    }
+    ```
+
+- 返回数据
+  
+    > data部分无返回数据
+
+    例如：
+    ``` json
+    {
+        "code": 20000,
+        "msg": "success",
+        "data" : null
+    }
+    ```
+
+- 错误信息
+
+    | code | 错误 |
+    | --- | --- |
+    | 40300 | 权限不足 |
+
+---
+
+### 封禁、删除用户
+
+- URL路径：`/user/modifyStatus/{uid}`
+- 方法：`POST`
+
+- 请求参数：
+
+    | 参数 | 值类型 | 说明 |
+    | --- | --- | --- | 
+    | uid | string(url) | 欲修的用户uid |
+    | status | int | 修改状态，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 | 权限不足 |
--- a/pom.xml
+++ b/pom.xml
@ -59,19 +59,8 @@
        </dependency>

        <dependency>
-            <groupId>com.fasterxml.jackson.core</groupId>
-            <artifactId>jackson-core</artifactId>
-            <version>2.13.3</version>
-        </dependency>
-        <dependency>
-            <groupId>com.fasterxml.jackson.core</groupId>
-            <artifactId>jackson-databind</artifactId>
-            <version>2.13.3</version>
-        </dependency>
-        <dependency>
-            <groupId>com.fasterxml.jackson.core</groupId>
-            <artifactId>jackson-annotations</artifactId>
-            <version>2.13.3</version>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
        </dependency>

        <dependency>
@ -92,7 +81,7 @@
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
-            <artifactId>jjwt-jackson</artifactId>
+            <artifactId>jjwt-gson</artifactId>
            <version>0.11.5</version>
        </dependency>

--- a/src/main/resources/database.sql
+++ b/src/main/resources/database.sql
@ -0,0 +1,97 @@
+/*
+MariaDB Backup
+Database: dscape
+Backup Time: 2022-07-10 22:20:06
+*/
+
+SET FOREIGN_KEY_CHECKS=0;
+DROP TABLE IF EXISTS `dscape`.`black_list`;
+DROP TABLE IF EXISTS `dscape`.`compute_history`;
+DROP TABLE IF EXISTS `dscape`.`patient_data`;
+DROP TABLE IF EXISTS `dscape`.`role_permission`;
+DROP TABLE IF EXISTS `dscape`.`user_basic`;
+CREATE TABLE `black_list` (
+  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
+  `type` tinyint(1) NOT NULL COMMENT '黑名单数据类型；\r\n0：ip；\r\n1：uid',
+  `name` varchar(255) NOT NULL COMMENT '黑名单条目名称，可空',
+  `data` varchar(255) NOT NULL COMMENT '黑名单数据',
+  `create_time` datetime NOT NULL DEFAULT current_timestamp(),
+  `edit_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),
+  `del` tinyint(1) DEFAULT 0,
+  PRIMARY KEY (`id`,`data`) USING BTREE,
+  UNIQUE KEY `index_id` (`id`) USING BTREE,
+  KEY `index_data` (`data`) USING BTREE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE TABLE `compute_history` (
+  `id` int(11) NOT NULL,
+  `uid` char(36) NOT NULL COMMENT '计算数据记录对应的用户uid',
+  `rid` int(11) NOT NULL COMMENT '计算数据记录对应的患者数据id',
+  PRIMARY KEY (`id`,`uid`,`rid`) USING BTREE,
+  UNIQUE KEY `index_id` (`id`) USING BTREE,
+  KEY `index_uid` (`uid`) USING BTREE,
+  KEY `index_pid` (`rid`) USING BTREE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE TABLE `patient_data` (
+  `id` int(11) unsigned NOT NULL AUTO_INCREMENT COMMENT '数据id',
+  `pid` int(15) NOT NULL COMMENT '病人id',
+  `ctDNA_length` int(4) NOT NULL COMMENT 'ctDNA长度',
+  `CpG` int(5) NOT NULL COMMENT '甲基化位点数',
+  `hcc_status` tinyint(1) NOT NULL COMMENT '是否为HCC，0: 否, 1: 是',
+  `hcc_infer_status` tinyint(1) NOT NULL COMMENT '通过推断得出的HCC状态',
+  `create_time` datetime NOT NULL DEFAULT current_timestamp(),
+  `edit_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),
+  `delete` tinyint(1) unsigned NOT NULL DEFAULT 0,
+  PRIMARY KEY (`id`,`pid`) USING BTREE,
+  UNIQUE KEY `id` (`id`) USING BTREE,
+  KEY `pid` (`pid`) USING BTREE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE TABLE `role_permission` (
+  `id` int(4) unsigned NOT NULL AUTO_INCREMENT,
+  `name` varchar(255) NOT NULL COMMENT '权限名称',
+  `permit` varchar(255) NOT NULL COMMENT '许可的用户角色，角色之间用";"（分号）隔开',
+  `create_time` datetime NOT NULL DEFAULT current_timestamp(),
+  `edit_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),
+  `del` tinyint(1) NOT NULL DEFAULT 0,
+  PRIMARY KEY (`id`,`name`),
+  UNIQUE KEY `index_id` (`id`) USING BTREE,
+  UNIQUE KEY `index_name` (`name`) USING BTREE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE TABLE `user_basic` (
+  `id` int(11) NOT NULL AUTO_INCREMENT,
+  `uid` char(36) NOT NULL COMMENT '用户唯一uuid',
+  `user_name` varchar(32) NOT NULL COMMENT '用户用户名',
+  `password` varchar(60) NOT NULL COMMENT '用户密码',
+  `role` tinyint(1) unsigned NOT NULL DEFAULT 0 COMMENT '用户身份，默认为0；\r\n0：普通用户，\r\n1：管理员\r\n',
+  `status` tinyint(1) unsigned NOT NULL DEFAULT 0 COMMENT '用户状态；0：正常；1：封禁；2：注销（销号）',
+  `create_time` datetime NOT NULL DEFAULT current_timestamp(),
+  `edit_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),
+  PRIMARY KEY (`id`,`uid`,`user_name`),
+  UNIQUE KEY `id` (`id`) USING BTREE,
+  UNIQUE KEY `uid` (`uid`) USING BTREE,
+  UNIQUE KEY `user_name` (`user_name`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+BEGIN;
+LOCK TABLES `dscape`.`black_list` WRITE;
+DELETE FROM `dscape`.`black_list`;
+UNLOCK TABLES;
+COMMIT;
+BEGIN;
+LOCK TABLES `dscape`.`compute_history` WRITE;
+DELETE FROM `dscape`.`compute_history`;
+UNLOCK TABLES;
+COMMIT;
+BEGIN;
+LOCK TABLES `dscape`.`patient_data` WRITE;
+DELETE FROM `dscape`.`patient_data`;
+UNLOCK TABLES;
+COMMIT;
+BEGIN;
+LOCK TABLES `dscape`.`role_permission` WRITE;
+DELETE FROM `dscape`.`role_permission`;
+UNLOCK TABLES;
+COMMIT;
+BEGIN;
+LOCK TABLES `dscape`.`user_basic` WRITE;
+DELETE FROM `dscape`.`user_basic`;
+UNLOCK TABLES;
+COMMIT;