diff --git a/API-Document.md b/API-Document.md new file mode 100644 index 0000000..7246715 --- /dev/null +++ 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 | 权限不足 | \ No newline at end of file diff --git a/pom.xml b/pom.xml index e165b85..c58e22d 100644 --- a/pom.xml +++ b/pom.xml @@ -59,19 +59,8 @@ - com.fasterxml.jackson.core - jackson-core - 2.13.3 - - - com.fasterxml.jackson.core - jackson-databind - 2.13.3 - - - com.fasterxml.jackson.core - jackson-annotations - 2.13.3 + com.google.code.gson + gson @@ -92,7 +81,7 @@ io.jsonwebtoken - jjwt-jackson + jjwt-gson 0.11.5 diff --git a/src/main/resources/database.sql b/src/main/resources/database.sql new file mode 100644 index 0000000..e60e05b --- /dev/null +++ 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;