499 lines
11 KiB
Markdown
499 lines
11 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: 视频拍摄与制作
|
||
- 5: 视频确认
|
||
|
||
## 用户接口
|
||
|
||
### 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": 1734578081,
|
||
"updatedAt": 1734578081,
|
||
"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": 1734578081,
|
||
"updatedAt": 1734578081
|
||
}
|
||
],
|
||
"total": 12,
|
||
"currentPage": 1,
|
||
"pageSize": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 禁用用户
|
||
|
||
- **接口**：`POST /api/users/disable/{userId}`
|
||
- **描述**：禁用指定用户
|
||
- **认证**：需要
|
||
- **路径参数**：
|
||
- `userId`: 用户 ID
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": "用户已禁用"
|
||
}
|
||
```
|
||
|
||
### 7. 查询部门用户列表
|
||
|
||
- **接口**：`GET /api/users/department/{departmentId}`
|
||
- **描述**：获取指定部门下的所有正常状态用户列表
|
||
- **认证**：需要
|
||
- **路径参数**：
|
||
- `departmentId`: 部门 ID
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": [
|
||
{
|
||
"id": 2,
|
||
"username": "普通管理员账号2",
|
||
"email": "user2@qq.com",
|
||
"password": null,
|
||
"departmentId": 1,
|
||
"roles": 2,
|
||
"jobs": 2,
|
||
"avatar": null,
|
||
"creatorId": 1,
|
||
"status": 1,
|
||
"createdAt": 1734504506,
|
||
"updatedAt": 1734504506,
|
||
"enabled": true,
|
||
"authorities": [
|
||
{
|
||
"authority": "ROLE_USER"
|
||
}
|
||
],
|
||
"accountNonExpired": true,
|
||
"accountNonLocked": true,
|
||
"credentialsNonExpired": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
- **错误响应**：
|
||
```json
|
||
{
|
||
"code": 50000,
|
||
"message": "获取部门用户列表失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 课程任务接口
|
||
|
||
### 1. 获取课程任务列表
|
||
|
||
- **接口**：`GET /api/lesson-tasks`
|
||
- **描述**：分页获取课程任务列表，可按用户筛选
|
||
- **认证**：需要
|
||
- **查询参数**：
|
||
- `page`: 页码（从 1 开始）
|
||
- `size`: 每页数量（默认 10）
|
||
- `userId`: 用户 ID（可选）
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": {
|
||
"content": [
|
||
{
|
||
"id": 1,
|
||
"courseName": "数学",
|
||
"microLessonName": "数学1-1",
|
||
"userId": 1,
|
||
"progressStatus": 4,
|
||
"scriptCreateTime": 1734940587,
|
||
"scriptReviewTime": null,
|
||
"scriptConfirmTime": 1734940825,
|
||
"videoCreateTime": 1734940832,
|
||
"videoConfirmTime": 1734940837,
|
||
"finishTime": 1734940837,
|
||
"advise": "",
|
||
"createdAt": 1734674726,
|
||
"updatedAt": 1734940837
|
||
}
|
||
],
|
||
"pageable": {
|
||
"pageNumber": 0,
|
||
"pageSize": 10,
|
||
"sort": {
|
||
"empty": true,
|
||
"unsorted": true,
|
||
"sorted": false
|
||
}
|
||
},
|
||
"totalElements": 7,
|
||
"totalPages": 1,
|
||
"last": true,
|
||
"first": true,
|
||
"empty": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取单个课程任务
|
||
|
||
- **接口**：`GET /api/lesson-tasks/{id}`
|
||
- **描述**：根据 ID 获取课程任务详情
|
||
- **认证**：需要
|
||
- **路径参数**：
|
||
- `id`: 课程任务 ID
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": 1,
|
||
"courseName": "数学",
|
||
"microLessonName": "数学1-1",
|
||
"userId": 1,
|
||
"progressStatus": 4,
|
||
"scriptCreateTime": 1734940587,
|
||
"scriptReviewTime": null,
|
||
"scriptConfirmTime": 1734940825,
|
||
"videoCreateTime": 1734940832,
|
||
"videoConfirmTime": 1734940837,
|
||
"finishTime": 1734940837,
|
||
"advise": "",
|
||
"createdAt": 1734674726,
|
||
"updatedAt": 1734940837
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 创建课程任务
|
||
|
||
- **接口**：`POST /api/lesson-tasks`
|
||
- **描述**：创建新的课程任务
|
||
- **认证**：需要
|
||
- **请求体**：
|
||
```json
|
||
{
|
||
"courseName": "测试课程",
|
||
"microLessonName": "测试微课",
|
||
"userId": 1
|
||
}
|
||
```
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": 11,
|
||
"courseName": "测试课程",
|
||
"microLessonName": "测试微课",
|
||
"userId": 1,
|
||
"progressStatus": 0,
|
||
"scriptCreateTime": null,
|
||
"scriptReviewTime": null,
|
||
"scriptConfirmTime": null,
|
||
"videoCreateTime": null,
|
||
"videoConfirmTime": null,
|
||
"finishTime": null,
|
||
"advise": null,
|
||
"createdAt": 1735003870,
|
||
"updatedAt": 1735003870
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 更新课程任务
|
||
|
||
- **接口**：`PUT /api/lesson-tasks/{id}`
|
||
- **描述**：更新课程任务信息
|
||
- **认证**：需要
|
||
- **路径参数**：
|
||
- `id`: 课程任务 ID
|
||
- **请求体**：
|
||
```json
|
||
{
|
||
"progressStatus": 1,
|
||
"advise": "更新的任务说明"
|
||
}
|
||
```
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": 11,
|
||
"courseName": "测试课程",
|
||
"microLessonName": "测试微课",
|
||
"userId": 1,
|
||
"progressStatus": 1,
|
||
"scriptCreateTime": 1735003922,
|
||
"scriptReviewTime": null,
|
||
"scriptConfirmTime": null,
|
||
"videoCreateTime": null,
|
||
"videoConfirmTime": null,
|
||
"finishTime": null,
|
||
"advise": "更新的任务说明",
|
||
"createdAt": 1735003870,
|
||
"updatedAt": 1735003922
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 获取部门课程任务
|
||
|
||
- **接口**：`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,
|
||
"scriptCreateTime": 1734940587,
|
||
"scriptReviewTime": null,
|
||
"scriptConfirmTime": 1734940825,
|
||
"videoCreateTime": 1734940832,
|
||
"videoConfirmTime": 1734940837,
|
||
"finishTime": 1734940837,
|
||
"advise": "",
|
||
"createdAt": 1734674726,
|
||
"updatedAt": 1734940837
|
||
}
|
||
],
|
||
"pageable": {
|
||
"pageNumber": 0,
|
||
"pageSize": 10
|
||
},
|
||
"totalElements": 11,
|
||
"totalPages": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 删除课程任务
|
||
|
||
- **接口**：`DELETE /api/lesson-tasks/{id}`
|
||
- **描述**：删除指定的课程任务
|
||
- **认证**：需要
|
||
- **路径参数**：
|
||
- `id`: 课程任务 ID
|
||
- **成功响应**：
|
||
```json
|
||
{
|
||
"code": 10000,
|
||
"message": "成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 所有时间戳字段均使用秒级时间戳（10 位）
|
||
2. 课程任务状态变更时会自动记录相应的时间戳
|
||
3. 部门课程任务列表会额外返回用户名信息
|
||
4. 分页参数中的页码从 1 开始
|