feat: 项目整体提交
- 更新项目配置文件 - 更新API文档 - 更新数据库文档 - 优化Redis配置 - 优化课程任务服务
This commit is contained in:
hvemi_han
411
API文档.md
Normal file
411
API文档.md
Normal file
@ -0,0 +1,411 @@
|
||||
# 进度管理系统 API 文档
|
||||
|
||||
## 基础信息
|
||||
|
||||
- 基础 URL: `http://localhost:1218`
|
||||
- 所有请求和响应均使用 JSON 格式
|
||||
- 所有需要认证的接口都需要在请求头中携带 `Authorization: Bearer {token}`
|
||||
|
||||
## 通用响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 10000, // 响应码
|
||||
"message": "成功", // 响应消息
|
||||
"data": {} // 响应数据
|
||||
}
|
||||
```
|
||||
|
||||
### 响应码说明
|
||||
|
||||
| 响应码 | 说明 | 消息 |
|
||||
| ------ | ---------- | ---------- |
|
||||
| 10000 | 成功 | 成功 |
|
||||
| 10001 | 参数错误 | 参数无效 |
|
||||
| 10002 | 邮箱重复 | 邮箱已存在 |
|
||||
| 10003 | 用户不存在 | 用户不存在 |
|
||||
| 10004 | 密码错误 | 密码错误 |
|
||||
| 10005 | 邮箱已存在 | 邮箱已存在 |
|
||||
| 10006 | 未授权 | 未授权 |
|
||||
| 10007 | 令牌过期 | 令牌已过期 |
|
||||
| 10008 | 令牌无效 | 无效的令牌 |
|
||||
| 10009 | 系统错误 | 系统错误 |
|
||||
|
||||
## 字段说明
|
||||
|
||||
### 用户相关字段
|
||||
|
||||
1. **角色 (roles)**
|
||||
|
||||
- 1: 教师
|
||||
- 2: 普通管理员
|
||||
- 3: 沟通联络人
|
||||
- 4: 系统管理员
|
||||
|
||||
2. **岗位 (jobs)**
|
||||
|
||||
- 1: 课程制作教师
|
||||
- 2: 课程购买方项目负责人
|
||||
- 3: 课程制作方沟通联络人
|
||||
- 4: 系统制作方项目负责人
|
||||
|
||||
3. **用户状态 (status)**
|
||||
- 1: 正常
|
||||
- 0: 禁用
|
||||
|
||||
### 课程任务相关字段
|
||||
|
||||
1. **进度状态 (progressStatus)**
|
||||
- 0: 脚本上传
|
||||
- 1: 脚本确认
|
||||
- 2: 视频拍摄
|
||||
- 3: 后期制作
|
||||
- 4: 任务完成
|
||||
|
||||
## 用户接口
|
||||
|
||||
### 1. 用户注册
|
||||
|
||||
- **接口**：`POST /api/users`
|
||||
- **描述**：创建新用户
|
||||
- **认证**：不需要
|
||||
- **请求体**：
|
||||
```json
|
||||
{
|
||||
"username": "testuser", // 用户名，不可为空
|
||||
"email": "test@example.com", // 邮箱，不可为空且唯一
|
||||
"password": "password123", // 密码，不可为空
|
||||
"departmentId": 1, // 部门ID，不可为空，关联departments表
|
||||
"roles": 1, // 角色：1-教师，2-普通管理员，3-沟通联络人，4-系统管理员
|
||||
"jobs": 1, // 岗位：1-课程制作教师，2-课程购买方项目负责人，3-课程制作方沟通联络人，4-系统制作方项目负责人
|
||||
"avatar": "http://example.com/avatar.jpg", // 头像URL，可选
|
||||
"creatorId": 1 // 创建者ID，不可为空
|
||||
}
|
||||
```
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
- **错误响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10005,
|
||||
"message": "邮箱已存在",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 用户登录
|
||||
|
||||
- **接口**：`POST /api/users/login`
|
||||
- **描述**：用户登录获取 token
|
||||
- **认证**：不需要
|
||||
- **请求体**：
|
||||
```json
|
||||
{
|
||||
"email": "test@example.com", // 邮箱
|
||||
"password": "password123", // 密码
|
||||
"remember": true // 是否记住登录（可选）
|
||||
}
|
||||
```
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzM4NCJ9..." // JWT令牌
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 用户登出
|
||||
|
||||
- **接口**：`POST /api/users/logout`
|
||||
- **描述**：用户登出，使当前 token 失效
|
||||
- **认证**：需要
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": "登出成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 获取当前用户信息
|
||||
|
||||
- **接口**：`GET /api/users/current`
|
||||
- **描述**：获取当前登录用户信息
|
||||
- **认证**：需要
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"id": 12,
|
||||
"username": "testuser",
|
||||
"email": "test@example.com",
|
||||
"departmentId": 1,
|
||||
"roles": 1,
|
||||
"jobs": 1,
|
||||
"avatar": null,
|
||||
"creatorId": 1,
|
||||
"status": 1,
|
||||
"createdAt": 1734498503690,
|
||||
"updatedAt": 1734498503690,
|
||||
"enabled": true,
|
||||
"authorities": [
|
||||
{
|
||||
"authority": "ROLE_USER"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 获取用户列表
|
||||
|
||||
- **接口**：`GET /api/users/list`
|
||||
- **描述**：分页获取用户列表
|
||||
- **认证**：需要
|
||||
- **查询参数**：
|
||||
- `page`: 页码（从 1 开始）
|
||||
- `limit`: 每页数量（默认 10）
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"departmentId": 1,
|
||||
"roles": 4,
|
||||
"jobs": 4,
|
||||
"avatar": null,
|
||||
"creatorId": 1,
|
||||
"status": 1,
|
||||
"createdAt": 1734491549,
|
||||
"updatedAt": 1734491549
|
||||
}
|
||||
],
|
||||
"total": 12,
|
||||
"currentPage": 1,
|
||||
"pageSize": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 禁用用户
|
||||
|
||||
- **接口**：`POST /api/users/disable/{userId}`
|
||||
- **描述**：禁用指定用户
|
||||
- **认证**：需要
|
||||
- **路径参数**：
|
||||
- `userId`: 用户 ID
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": "用户已禁用"
|
||||
}
|
||||
```
|
||||
|
||||
## 课程任务接口
|
||||
|
||||
### 1. 获取课程任务列表
|
||||
|
||||
- **接口**：`GET /api/lesson-tasks`
|
||||
- **描述**：分页获取课程任务列表
|
||||
- **认证**：需要
|
||||
- **查询参数**：
|
||||
- `page`: 页码（从 1 开始）
|
||||
- `size`: 每页数量（默认 10）
|
||||
- `userId`: 用户 ID（可选）
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"content": [
|
||||
{
|
||||
"id": 6,
|
||||
"courseName": "Test Course",
|
||||
"microLessonName": "Test Lesson",
|
||||
"userId": 12,
|
||||
"progressStatus": 1,
|
||||
"scriptUploadTime": 1734498510000,
|
||||
"scriptConfirmTime": 1734498510000,
|
||||
"videoCaptureTime": 1734498510000,
|
||||
"videoConfirmTime": 1734498510000,
|
||||
"finishTime": 1734498510000,
|
||||
"advise": "Test advice",
|
||||
"createdAt": 1734498546322,
|
||||
"updatedAt": 1734498546322
|
||||
}
|
||||
],
|
||||
"totalElements": 4,
|
||||
"totalPages": 1,
|
||||
"size": 10,
|
||||
"number": 0,
|
||||
"first": true,
|
||||
"last": true,
|
||||
"empty": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取单个课程任务
|
||||
|
||||
- **接口**：`GET /api/lesson-tasks/{id}`
|
||||
- **描述**：获取指定 ID 的课程任务
|
||||
- **认证**：需要
|
||||
- **路径参数**：
|
||||
- `id`: 课程任务 ID
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"id": 6,
|
||||
"courseName": "Test Course",
|
||||
"microLessonName": "Test Lesson",
|
||||
"userId": 12,
|
||||
"progressStatus": 1,
|
||||
"scriptUploadTime": 1734498510000,
|
||||
"scriptConfirmTime": 1734498510000,
|
||||
"videoCaptureTime": 1734498510000,
|
||||
"videoConfirmTime": 1734498510000,
|
||||
"finishTime": 1734498510000,
|
||||
"advise": "Test advice",
|
||||
"createdAt": 1734498546322,
|
||||
"updatedAt": 1734498546322
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 创建课程任务
|
||||
|
||||
- **接口**：`POST /api/lesson-tasks`
|
||||
- **描述**：创建新的课程任务
|
||||
- **认证**：需要
|
||||
- **请求体**：
|
||||
```json
|
||||
{
|
||||
"courseName": "Java基础", // 课程名称，不可为空
|
||||
"microLessonName": "Java变量", // 微课名称，不可为空
|
||||
"userId": 1, // 负责人ID，不可为空，关联users表
|
||||
"advise": "请注意讲解速度" // 任务建议或备注，可选
|
||||
}
|
||||
```
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"id": 6,
|
||||
"courseName": "Java基础",
|
||||
"microLessonName": "Java变量",
|
||||
"userId": 1,
|
||||
"progressStatus": 1,
|
||||
"scriptUploadTime": ,
|
||||
"scriptConfirmTime": ,
|
||||
"videoCaptureTime": ,
|
||||
"videoConfirmTime": ,
|
||||
"finishTime": ,
|
||||
"advise": "请注意讲解速度",
|
||||
"createdAt": 1734498546322,
|
||||
"updatedAt": 1734498546322
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 更新课程任务
|
||||
|
||||
- **接口**：`PUT /api/lesson-tasks/{id}`
|
||||
- **描述**：更新指定 ID 的课程任务
|
||||
- **认证**：需要
|
||||
- **路径参数**：
|
||||
- `id`: 课程任务 ID
|
||||
- **请求体**：
|
||||
```json
|
||||
{
|
||||
"courseName": "Updated Course", // 课程名称
|
||||
"microLessonName": "Updated Lesson", // 微课名称
|
||||
"userId": 12, // 用户ID
|
||||
"progressStatus": 2, // 进度状态
|
||||
"scriptUploadTime": 1734498510000, // 脚本上传时间
|
||||
"scriptConfirmTime": 1734498510000, // 脚本确认时间
|
||||
"videoCaptureTime": 1734498510000, // 视频录制时间
|
||||
"videoConfirmTime": 1734498510000, // 视频确认时间
|
||||
"finishTime": 1734498510000, // 完成时间
|
||||
"advise": "Updated advice" // 建议
|
||||
}
|
||||
```
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"id": 6,
|
||||
"courseName": "Updated Course",
|
||||
"microLessonName": "Updated Lesson",
|
||||
"userId": 12,
|
||||
"progressStatus": 2,
|
||||
"scriptUploadTime": 1734498510000,
|
||||
"scriptConfirmTime": 1734498510000,
|
||||
"videoCaptureTime": 1734498510000,
|
||||
"videoConfirmTime": 1734498510000,
|
||||
"finishTime": 1734498510000,
|
||||
"advise": "Updated advice",
|
||||
"createdAt": 1734498546322,
|
||||
"updatedAt": 1734498586574
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 删除课程任务
|
||||
|
||||
- **接口**：`DELETE /api/lesson-tasks/{id}`
|
||||
- **描述**：删除指定 ID 的课程任务
|
||||
- **认证**：需要
|
||||
- **路径参数**：
|
||||
- `id`: 课程任务 ID
|
||||
- **成功响应**：
|
||||
```json
|
||||
{
|
||||
"code": 10000,
|
||||
"message": "成功",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 所有需要认证的接口必须在请求头中携带有效的 JWT 令牌
|
||||
2. 所有时间戳字段均为毫秒级时间戳
|
||||
3. 分页接口的页码从 1 开始
|
||||
4. 用户密码在传输和存储时都会进行加密处理
|
||||
5. 课程任务的 progressStatus 字段状态码说明：
|
||||
- 0: 脚本上传
|
||||
- 1: 脚本确认
|
||||
- 2: 视频拍摄
|
||||
- 3: 后期制作
|
||||
- 4: 任务完成
|
||||
6. 用户状态说明：
|
||||
- 1: 正常
|
||||
- 0: 禁用
|
||||
Reference in New Issue
Block a user