15 KiB
15 KiB
进度管理系统 API 文档
基础信息
- 基础 URL:
http://localhost:1218 - 所有请求和响应均使用 JSON 格式
- 所有需要认证的接口都需要在请求头中携带
Authorization: Bearer {token}
通用响应格式
{
"code": 10000, // 响应码
"message": "成功", // 响应消息
"data": {} // 响应数据
}
响应码说明
| 响应码 | 说明 | 消息 |
|---|---|---|
| 10000 | 成功 | 成功 |
| 10001 | 参数错误 | 参数无效 |
| 10002 | 非教师用户 | 非教师用户 |
| 10003 | 用户不存在 | 用户不存在 |
| 10004 | 密码错误 | 密码错误 |
| 10005 | 邮箱已存在 | 邮箱已存在 |
| 10006 | 未授权 | 未授权 |
| 10007 | 令牌过期 | 令牌已过期 |
| 10008 | 令牌无效 | 无效的令牌 |
| 10009 | 系统错误 | 系统错误 |
字段说明
用户相关字段
-
角色 (roles)
- 1: 教师
- 2: 普通管理员
- 3: 沟通联络人
- 4: 系统管理员
-
岗位 (jobs)
- 1: 课程制作教师
- 2: 课程购买方项目负责人
- 3: 课程制作方沟通联络人
- 4: 系统制作方项目负责人
-
用户状态 (status)
- 1: 正常
- 0: 禁用
-
Spring Security 相关字段
enabled: 账号是否启用（true: 启用，false: 禁用）accountNonExpired: 账号是否未过期（true: 未过期，false: 已过期）accountNonLocked: 账号是否未锁定（true: 未锁定，false: 已锁定）credentialsNonExpired: 密码是否未过期（true: 未过期，false: 已过期）authorities: 用户权限列表，包含用户被授予的所有权限（如 "ROLE_USER"）
课程任务相关字段
- 进度状态 (progressStatus)
- 0: 未开始
- 1: 脚本制作
- 2: 脚本审核
- 3: 脚本确认
- 4: 视频拍摄与制作
- 5: 视频确认
用户接口
1. 用户注册
- 接口：
POST /api/users - 描述：创建新用户
- 认证：不需要
- 请求体：
{ "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，不可为空 } - 成功响应：
{ "code": 10000, "message": "成功", "data": null } - 错误响应：
{ "code": 10005, "message": "邮箱已存在", "data": null }
2. 用户登录
- 接口：
POST /api/users/login - 描述：用户登录获取 token
- 认证：不需要
- 请求体：
{ "email": "test@example.com", // 邮箱 "password": "password123", // 密码 "remember": true // 是否记住登录（可选） } - 成功响应：
{ "code": 10000, "message": "成功", "data": { "token": "eyJhbGciOiJIUzM4NCJ9..." // JWT令牌 } }
3. 用户登出
- 接口：
POST /api/users/logout - 描述：用户登出，使当前 token 失效
- 认证：需要
- 成功响应：
{ "code": 10000, "message": "成功", "data": "登出成功" }
4. 获取当前用户信息
- 接口：
GET /api/users/current - 描述：获取当前登录用户信息
- 认证：需要
- 成功响应：
{ "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）
- 成功响应：
{ "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
- 成功响应：
{ "code": 10000, "message": "成功", "data": "用户已禁用" }
7. 查询部门用户列表
- 接口：
GET /api/users/department/{departmentId} - 描述：获取指定部门下的所有正常状态用户列表
- 认证：需要
- 路径参数：
departmentId: 部门 ID
- 成功响应：
{ "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 } ] } - 错误响应：
{ "code": 50000, "message": "获取部门用户列表失败", "data": null }
8. 搜索教师信息
- 接口：
GET /api/users/teacher/search - 描述：通过邮箱搜索教师信息
- 认证：需要
- 查询参数：
email: 教师邮箱
- 成功响应：
{ "code": 10000, "message": "成功", "data": { "id": 1, "username": "张三", "email": "user1@qq.com", "password": null, "departmentId": 2, "roles": 1, "jobs": 1, "avatar": null, "creatorId": 1, "status": 1, "createdAt": 1734504506, "updatedAt": 1734504506, "enabled": true, "accountNonExpired": true, "accountNonLocked": true, "credentialsNonExpired": true, "authorities": [ { "authority": "ROLE_USER" } ] } } - 错误响应：
{ "code": 10009, "message": "系统错误", "data": null }
课程任务接口
1. 获取课程任务列表
- 接口：
GET /api/lesson-tasks - 描述：分页获取课程任务列表，可按用户筛选
- 认证：需要
- 查询参数：
page: 页码（从 1 开始）size: 每页数量（默认 10）userId: 用户 ID（可选）
- 成功响应：
{ "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
- 成功响应：
{ "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 - 描述：创建新的课程任务
- 认证：需要
- 请求体：
{ "courseName": "测试课程", "microLessonName": "测试微课", "userId": 1, "advise": "任务说明" } - 成功响应：
{ "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": "任务说明", "createdAt": 1735003870, "updatedAt": 1735003870 } }
4. 更新课程任务
- 接口：
PUT /api/lesson-tasks/{id} - 描述：更新课程任务信息
- 认证：需要
- 路径参数：
id: 课程任务 ID
- 请求体：
{ "progressStatus": 1, "advise": "更新的任务说明" } - 成功响应：
{ "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）
- 成功响应：
{ "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
- 成功响应：
{ "code": 10000, "message": "成功", "data": null }
批量导入接口
1. 批量导入用户
- 接口：
POST /api/import/users - 描述：通过 Excel 文件批量导入用户
- 认证：需要
- 请求体：
Content-Type:multipart/form-datafile: Excel 文件（.xlsx）
- Excel 文件格式：
用户名 邮箱 密码 部门名称 张三 zhangsan@example.com 123456 技术部 - 成功响应：
{ "code": 10000, "message": "成功", "data": "成功导入2条数据" } - 错误响应：
{ "code": 10012, "message": "成功导入0条数据。错误信息：第2行邮箱已存在;第3行部门不存在;", "data": null }
2. 批量导入课程任务
- 接口：
POST /api/import/lesson-tasks - 描述：通过 Excel 文件批量导入课程任务
- 认证：需要
- 请求体：
Content-Type:multipart/form-datafile: Excel 文件（.xlsx）
- Excel 文件格式：
课程名称 微课名称 教师邮箱 数学课程 第一章 teacher@example.com - 成功响应：
{ "code": 10000, "message": "成功", "data": "成功导入3条数据" } - 错误响应：
{ "code": 10012, "message": "成功导入0条数据。错误信息：第2行未找到教师用户（teacher@example.com）;", "data": null }
3. 批量导入部门
- 接口：
POST /api/import/departments - 描述：通过 Excel 文件批量导入部门
- 认证：需要
- 请求体：
Content-Type:multipart/form-datafile: Excel 文件（.xlsx）
- Excel 文件格式：
部门名称 部门描述 技术部 负责技术研发 - 成功响应：
{ "code": 10000, "message": "成功", "data": "成功导入2条数据" } - 错误响应：
{ "code": 10012, "message": "成功导入0条数据。错误信息：第2行部门名称已存在;", "data": null }
注意事项
- 所有时间戳字段均使用秒级时间戳（10 位）
- 课程任务状态变更时会自动记录相应的时间戳
- 部门课程任务列表会额外返回用户名信息
- 分页参数中的页码从 1 开始
- 批量导入时，Excel 文件必须严格按照模板格式填写
- 批量导入时，如果某行数据导入失败，会在返回信息中说明具体原因
- 批量导入时，如果全部数据导入失败，会返回错误状态码（10012）