接口说明
- 请求基地址：baseUrl= www.cfm.com(前端暂时先不加，因为可能没钱申请域名)
- 服务器开启CORS跨域访问
- 对于需要授权的操作，请前端提前主动调用授权接口(见后述)
- 使用HTTP状态码作为响应标识
- 返回数据为JSON字符串，且以ResultBean为容器
- 对于接口里面的<a>格式的数据，表示它是一个占位符，a代表变量。
支持的请求方式
- GET
- POST
通用返回状态说明(仅包含用得上的)
信息响应
100 Continue
这个临时响应表明，迄今为止的所有内容都是可行的，客户端应该继续请求，如果已经完成，则忽略它。
101 Switching Protocol
该代码是响应客户端的 Upgrade 标头发送的，并且指示服务器也正在切换的协议。
102 Processing
此代码表示服务器已收到并正在处理该请求，但没有响应可用。
103 Early Hints
此状态代码主要用于与Link 链接头一起使用，以允许用户代理在服务器仍在准备响应时开始预加载资源。
成功响应
200 OK
请求成功。成功的含义取决于HTTP方法：
GET：资源已被提取并在消息正文中传输。
HEAD：实体标头位于消息正文中。
POST：描述动作结果的资源在消息体中传输。
TRACE：消息正文包含服务器收到的请求消息。
重定向
300 Multiple Choice
被请求的资源有一系列可供选择的回馈信息，每个都有自己特定的地址和浏览器驱动的商议信息。用户或浏览器能够自行选择一个首选的地址进行重定向。
301 Moved Permanently
被请求的资源已永久移动到新位置，并且将来任何对此资源的引用都应该使用本响应返回的若干个 URI 之一。如果可能，拥有链接编辑功能的客户端应当自动把请求的地址修改为从服务器反馈回来的地址。除非额外指定，否则这个响应也是可缓存的。
302 Found
请求的资源现在临时从不同的 URI 响应请求。由于这样的重定向是临时的，客户端应当继续向原有地址发送以后的请求。只有在Cache-Control或Expires中进行了指定的情况下，这个响应才是可缓存的。
303 See Other
对应当前请求的响应可以在另一个 URI 上被找到，而且客户端应当采用 GET 的方式访问那个资源。这个方法的存在主要是为了允许由脚本激活的POST请求输出重定向到一个新的资源。
304 Not Modified
如果客户端发送了一个带条件的 GET 请求且该请求已被允许，而文档的内容（自上次访问以来或者根据请求的条件）并没有改变，则服务器应当返回这个状态码。304 响应禁止包含消息体，因此始终以消息头后的第一个空行结尾。
305 Use Proxy
被请求的资源必须通过指定的代理才能被访问。Location 域中将给出指定的代理所在的 URI 信息，接收者需要重复发送一个单独的请求，通过这个代理才能访问相应资源。只有原始服务器才能建立305响应。
400 Bad Request
1、语义有误，当前请求无法被服务器理解。除非进行修改，否则客户端不应该重复提交这个请求。
2、请求参数有误。
401 Unauthorized
当前请求需要用户验证。该响应必须包含一个适用于被请求资源的 WWW-Authenticate 信息头用以询问用户信息。客户端可以重复提交一个包含恰当的 Authorization 头信息的请求。如果当前请求已经包含了 Authorization 证书，那么401响应代表着服务器验证已经拒绝了那些证书。如果401响应包含了与前一个响应相同的身份验证询问，且浏览器已经至少尝试了一次验证，那么浏览器应当向用户展示响应中包含的实体信息，因为这个实体信息中可能包含了相关诊断信息。
403 Forbidden
服务器已经理解请求，但是拒绝执行它。与 401 响应不同的是，身份验证并不能提供任何帮助，而且这个请求也不应该被重复提交。如果这不是一个 HEAD 请求，而且服务器希望能够讲清楚为何请求不能被执行，那么就应该在实体内描述拒绝的原因。当然服务器也可以返回一个 404 响应，假如它不希望让客户端获得任何信息。
404 Not Found
访问的资源不存在。
服务端响应
500 Internal Server Error
服务器遇到了不知道如何处理的情况。
1. 登录接口
1.1. 登录验证
URL = baseUrl+/login
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| username | String | 非空 |
| password | String | 非空 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| token | String | 唯一用户标识符 |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":{
"token":iasvnjgviuevjnwebciouhsewiuveqvfe2w1v8v44,
}
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
1.2. 登出
URL = baseUrl+/logout
METHOD = GET
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
2. 注册接口
2.1. 提交注册
URL = baseUrl+/sign
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| username | String | 用户名 |
| password | String | 密码 |
| nickname | String | 昵称 |
| studentNumber | Long | 学号 |
| school | String | 学校代号 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
3. 验证邮箱
3.1. 请求发送验证码
URL = baseUrl+/sign/sendVerificationCode/<username>
METHOD = GET
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
3.2. 验证验证码
URL = baseUrl+/sign/verityCode/<username>
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| verificationCode | String | 验证码 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
4. 用户信息请求
4.1. 用户到学生映射关系
URL = baseUrl+/user/toStudent
METHOD = GET
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | String | 可为空 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | Long | 用户ID |
| studentNumber | String | 学号 |
| name | String | 真实姓名 |
| classroom | Integer | 班级 |
| institude | String | 学院 |
| major | String | 专业 |
| grade | Integer | 年级 |
| school | String | 学校 |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":{
"userId":1L,
"studentNumber":"1812001000",
"name":"Somebody",
"classroom":1,
"institude":"Software",
"major":"C.S.",
"grade":"2018",
"school":"JIT"
}
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
4.2. 用户扩展信息
URL = baseUrl+/user/extension
METHOD = GET
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | String | 可为空 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | Long | 用户ID |
| icon | String | 头像 |
| Long | QQ号码 | |
| String | 微信ID | |
| alipay | String | 支付宝信息 |
| phoneNumber | Long | 手机号 |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":{
"userId":1L,
"icon":"https://q1.qlogo.cn/g?b=qq&nk=2508826394&s=640",
"qq":2508826394L,
"wechat":"d2508826394",
"alipay":"MyALiPay",
"phoneNumber":15651731700L
}
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
4.3. 用户任务概览
URL = baseUrl+/user/userTasks
METHOD = GET
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | String | 可为空 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | Long | 用户ID |
| undoTasks | List<String> | 未提交任务ID |
| doneTasks | List<String> | 已提交任务ID |
| launchedTasks | List<String> | 已发布任务ID |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":{
"userId":1L,
"undoTasks":["1","2"],
"doneTasks":["3","4"],
"launchedTasks":["2","3"]
}
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
4.4. 任务ID与任务映射
URL = baseUrl+/user/taskIdToTask
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | String | 可为空 |
| taskId | Long | 任务ID |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| taskId | Long | 任务ID |
| launcherId | Long | 发布者ID |
| taskBeginTime | String | 任务开始时间 |
| taskEndTime | String | 任务结束时间 |
| undoIds | List<Long> | 未完成的用户ID |
| doneIds | List<Long> | 已完成的用户ID |
| taskName | String | 任务名 |
| taskFileDirectory | String | 任务文件保存路径(前端不应该用到这个) |
| taskFileTemplate | String | 任务模板位置 |
| taskFileSample | String | 任务示例文件位置 |
| format | String | 提交格式 |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":{
"taskId":1L,
"launcherId":2L,
"taskBeginTime":"2020_9_6_20_20",
"taskEndTime":"2020_9_12_20_20",
"undoIds":[],
"doneIds":[],
"taskName":"班级文档管理接口文档",
"taskFileDirectory":"",
"taskFileTemplate":"/home/file/template/qwer.txt",
"taskFileSample":"/home/file/sample/asdf.txt",
"format":""
}
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
4.5. 更新用户个人扩展信息
URL = baseUrl+/userInfo/updateExtension
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| icon | File | 头像图片 |
| String | ||
| String | 微信号 | |
| alipay | String | 支付宝账号 |
| phoneNumber | String | 手机号 |
上述参数均可为空，当某一项为空时，表示不进行修改。
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
4.6. 更新用户信息
URL = baseUrl+/userInfo/update
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| newUsername | String | 邮箱地址(如果更换邮箱前端首先要求输入密码并进行新的邮箱验证) |
| oldPassword | String | 旧密码 |
| newPassword | String | 新密码(要求输入原密码或忘记密码时进行邮箱验证) |
| newNickname | String | 昵称 |
上述参数均可为空，当某一项为空时，表示不进行修改。暂不支持邮箱更新。
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
4.7. 名称映射
URL = baseUrl+/base/nameMap
METHOD = GET
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
上述参数均可为空，当某一项为空时，表示不进行修改。
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
{
"code": 200,
"msg": "",
"data": {
"CS": "计算机科学与技术",
"InformationSecurity(Embedded)": "信息安全嵌入式",
"SoftWare(Z)": "软件工程(Z)",
"JIT": "金陵科技学院",
"InformationSecurity(Changed)": "信息安全(专转本)",
"SoftWare": "软件工程",
"IntelligentScienceAndTechnology": "智能科学与技术",
"InformationSecurity": "信息安全",
"SoftWare(Embedded)": "软件工程嵌入式"
}
}
5. 文件接口
5.1. 任意文件下载接口(RFD API)
URL = baseUrl+/file/randomAccess
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| filepath | String | 文件路径 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
5.2. 任务文件上传
URL = baseUrl+/file/upload
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| taskId | Long | 任务ID |
| file | <N/A> | 上传的文件 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
5.3. 文件下载
URL = baseUrl+/file/download
METHOD = POST
| 参数名 | 类型 | 说明 |
|---|---|---|
| userId | String | 可为空 |
| taskId | Long | 任务ID |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| uuid | String | 路径参数 |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":"qhjvbswjhcdjnkbfhjkablmviseepauqnfcsdfngh"
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
5.4. 打包下载
URL = baseUrl+/file/package/download
METHOD = POST
| 参数名 | 类型 | 说明 |
|---|---|---|
| taskId | Long | 任务ID |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| uuid | String | 路径参数 |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":"qhjvbswjhcdjnkbfhjkablmviseepauqnfcsdfngh"
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
5.5. A标签下载
URL = baseUrl+/file/a/download/<uuid>
METHOD = GET
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
文件
6. 任务接口
6.1. 发布任务
URL = baseUrl+/task/launch
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| taskName | String | 任务名 |
| format | String | 命名格式 |
| taskBeginTime | String | 起始时间(前端格式化为:YYYY_MM_DD_HH_MM的格式) |
| taskEndTime | String | 结束时间(前端格式化为:YYYY_MM_DD_HH_MM的格式) |
| taskFileTemplate | <文件类型> | 模板文件(可为空) |
| taskFileSample | <文件类型> | 示例文件(可为空) |
| scope | String | 此任务作用的范围(格式为:<school>_<major>_<institude>_<grade>_<classroom>如果某项有多个值，使用';'隔开。暂时不做) |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
6.2. 删除任务
此操作需要进行验证身份，前端记得重新调用身份检验接口进行判断(其实就是登录接口)
URL = baseUrl+/task/delete
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| taskId | Long | 任务ID |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
6.3. 更新任务
此操作需要验证身份
URL = baseUrl+/task/update
METHOD = POST
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| taskId | String | 任务ID |
| taskName | String | 任务名(可为空) |
| format | String | 命名格式(可为空) |
| taskBeginTime | String | 起始时间(前端格式化为:YYYY_MM_DD_HH_MM的格式，可为空) |
| taskEndTime | String | 结束时间(前端格式化为:YYYY_MM_DD_HH_MM的格式，可为空) |
| taskFileTemplate | <文件类型> | 模板文件(可为空) |
| taskFileSample | <文件类型> | 示例文件(可为空) |
| scope | String | 此任务作用的范围(格式为:<school>_<major>_<institude>_<grade>_<classroom>如果某项有多个值，使用';'隔开，可为空。暂时不做) |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
7. 用户身份变更(非管理员操作)
7.1. 添加班委
URL = baseUrl+/user/committee/appointment
METHOD = POST
| 参数名 | 类型 | 说明 |
|---|---|---|
| school | String | 学校 |
| studentNumber | String | 学号 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
7.2. 撤职班委
URL = baseUrl+/user/committee/dismiss
METHOD = POST
| 参数名 | 类型 | 说明 |
|---|---|---|
| school | String | 学校 |
| studentNumber | String | 学号 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
7.3. 添加教师
URL = baseUrl+/user/teacher/appointment
METHOD = POST
| 参数名 | 类型 | 说明 |
|---|---|---|
| school | String | 学校 |
| studentNumber | String | 学号 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
7.4. 撤职教师
URL = baseUrl+/user/teacher/dismiss
METHOD = POST
| 参数名 | 类型 | 说明 |
|---|---|---|
| school | String | 学校 |
| studentNumber | String | 学号 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
7.5. 判断是否为管理员
URL = baseUrl+/user/isAdmin
METHOD = GET
| 参数名 | 类型 | 说明 |
|---|
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":true/false
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
8. 后台接口
8.1. 导入用户学生信息
URL = baseUrl+/user/data/export
METHOD = POST
| 参数名 | 类型 | 说明 |
|---|---|---|
| file | 文件 | 包含用户信息的Excel表格 |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 成功
{
"code":200,
"msg":"",
"data":null
}
// 失败
{
"code":XXX,
"msg":"<失败原因>",
"data":null
}
8.2. 新增用户/删除用户
先不写
9、权限管理
9.1、左侧菜单权限
URL = baseUrl+/menu
METHOD = GET
请求参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| <N/A> | <N/A> | <N/A> |
响应数据：
// 管理员
{
"code": 200,
"msg": '',
"data": {
{
authname: "志愿服务",
icon: "el-icon-s-order",
id: 1,
path: "tasks",
children: [
{
authname: "添加",
icon: "el-icon-circle-plus",
id: 11,
path: "tasklaunch",
},
{
authname: "删除",
icon: "el-icon-remove",
id: 12,
path: "taskdelete",
},
{
authname: "已完成",
icon: "el-icon-check",
id: 13,
path: "taskfinished",
},
{
authname: "未完成",
icon: "el-icon-close",
id: 14,
path: "taskunfinished",
},
],
},
{
authname: "个人信息",
icon: "el-icon-user-solid",
id: 2,
path: "info",
children: [
{
authname: "查看个人信息",
icon: "el-icon-info",
id: 20,
path: "lookinfo",
},
],
}
}
// 普通用户
{
"code": 200,
"msg": '',
"data": {
{
authname: "志愿服务",
icon: "el-icon-s-order",
id: 1,
path: "tasks",
children: [
{
authname: "已完成",
icon: "el-icon-check",
id: 13,
path: "taskfinished",
},
{
authname: "未完成",
icon: "el-icon-close",
id: 14,
path: "taskunfinished",
},
],
},
{
authname: "个人信息",
icon: "el-icon-user-solid",
id: 2,
path: "info",
children: [
{
authname: "查看个人信息",
icon: "el-icon-info",
id: 20,
path: "lookinfo",
},
],
}
}
