502 lines
12 KiB
Markdown
502 lines
12 KiB
Markdown
# 进度管理系统 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
|
||
}
|
||
```
|
||
|
||
### 6. 按部门ID查询课程任务
|
||
|
||
- **接口**：`GET /api/lesson-tasks/department/{departmentId}`
|
||
- **描述**：获取指定部门下正常状态用户的课程任务列表（分页）
|
||
- **认证**：需要
|
||
- **路径参数**：
|
||
- `departmentId`: 部门ID
|
||
- **查询参数**：
|
||
- `page`: 页码（从1开始）
|
||
- `size`: 每页数量（默认10）
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": {
|
||
"content": [
|
||
{
|
||
"id": 1,
|
||
"courseName": "物理",
|
||
"microLessonName": "微课1-1",
|
||
"userId": 1,
|
||
"username": "教师账号1", // 新增：用户名字段
|
||
"progressStatus": 4,
|
||
"scriptUploadTime": 1734498510000,
|
||
"scriptConfirmTime": 1734498510000,
|
||
"videoCaptureTime": 1734498510000,
|
||
"videoConfirmTime": 1734498510000,
|
||
"finishTime": 1734498510000,
|
||
"advise": null,
|
||
"createdAt": 1734578081000,
|
||
"updatedAt": 1734580393000
|
||
}
|
||
],
|
||
"totalElements": 10,
|
||
"totalPages": 1,
|
||
"size": 10,
|
||
"number": 0,
|
||
"first": true,
|
||
"last": true,
|
||
"empty": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 更新课程任务进度
|
||
|
||
- **接口**：`PUT /api/lesson-tasks/{id}`
|
||
- **描述**：更新课程任务的进度状态和建议
|
||
- **认证**：需要
|
||
- **路径参数**：
|
||
- `id`: 课程任务ID
|
||
- **请求体**：
|
||
```json
|
||
{
|
||
"progressStatus": 2, // 进度状态（可选）
|
||
"advise": "{\"method\":\"wechat\",\"uploaded\":true}" // 建议（可选）
|
||
}
|
||
```
|
||
- **说明**：
|
||
- 更新进度状态时会自动更新对应的时间戳：
|
||
- 状态1：更新scriptUploadTime
|
||
- 状态2：更新scriptConfirmTime
|
||
- 状态3：更新videoCaptureTime
|
||
- 状态4：更新videoConfirmTime
|
||
- 状态5：更新finishTime
|
||
- 只会更新请求体中包含的字段，未提供的字段保持不变
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": 10,
|
||
"courseName": "测试课程",
|
||
"microLessonName": "测试微课",
|
||
"userId": 1,
|
||
"progressStatus": 2,
|
||
"scriptUploadTime": null,
|
||
"scriptConfirmTime": 1734663755667,
|
||
"videoCaptureTime": null,
|
||
"videoConfirmTime": null,
|
||
"finishTime": null,
|
||
"advise": "{\"method\":\"wechat\",\"uploaded\":true}",
|
||
"createdAt": 1734602440561,
|
||
"updatedAt": 1734663755000
|
||
}
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 所有需要认证的接口必须在请求头中携带有效的 JWT 令牌
|
||
2. 所有时间戳字段均为毫秒级时间戳
|
||
3. 分页接口的页码从 1 开始
|
||
4. 用户密码在传输和存储时都会进行加密处理
|
||
5. 课程任务的 progressStatus 字段状态码说明：
|
||
- 0: 脚本上传
|
||
- 1: 脚本确认
|
||
- 2: 视频拍摄
|
||
- 3: 后期制作
|
||
- 4: 任务完成
|
||
6. 用户状态说明：
|
||
- 1: 正常
|
||
- 0: 禁用
|