lensfrex
/
dscape-server
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source
main
lensfrex 3 years ago
parent 01b389ac1a
commit 57e1567977
Signed by: lensfrex
GPG Key ID: 0F69A0A2FBEE98A0
3 changed files with 539 additions and 14 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 439
      API-Document.md
  2. 17
      pom.xml
  3. 97
      src/main/resources/database.sql

439
API-Document.md
Unescape View File

@ -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 | 权限不足 |

17
pom.xml
Unescape View File

@ -59,19 +59,8 @@
</dependency> </dependency>
<dependency> <dependency>
<groupId>com.fasterxml.jackson.core</groupId> <groupId>com.google.code.gson</groupId>
<artifactId>jackson-core</artifactId> <artifactId>gson</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>
</dependency> </dependency>
<dependency> <dependency>
@ -92,7 +81,7 @@
</dependency> </dependency>
<dependency> <dependency>
<groupId>io.jsonwebtoken</groupId> <groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-jackson</artifactId> <artifactId>jjwt-gson</artifactId>
<version>0.11.5</version> <version>0.11.5</version>
</dependency> </dependency>

97
src/main/resources/database.sql
Unescape View File

@ -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;
Write Preview
Loading…
Cancel
Save