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

main
lensfrex 2 years ago
parent 01b389ac1a
commit 57e1567977
Signed by: lensfrex
GPG Key ID: 0F69A0A2FBEE98A0
  1. 439
      API-Document.md
  2. 17
      pom.xml
  3. 97
      src/main/resources/database.sql

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

@ -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>

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