huertian/jinduguanli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs:删除文档

Browse Source
This commit is contained in:
huertian 2025-01-06 16:15:16 +08:00
parent a19102f4d4
commit 4f645c6e78
5 changed files with 0 additions and 839 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

645
API文档.md
View File

@ -1,645 +0,0 @@
# 进度管理系统 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: 禁用
4. **Spring Security 相关字段**
- `enabled`: 账号是否启用（true: 启用，false: 禁用）
- `accountNonExpired`: 账号是否未过期（true: 未过期，false: 已过期）
- `accountNonLocked`: 账号是否未锁定（true: 未锁定，false: 已锁定）
- `credentialsNonExpired`: 密码是否未过期（true: 未过期，false: 已过期）
- `authorities`: 用户权限列表，包含用户被授予的所有权限（如 "ROLE_USER"）
### 课程任务相关字段
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
}
```
### 8. 搜索教师信息
- **接口**：`GET /api/users/teacher/search`
- **描述**：通过邮箱搜索教师信息
- **认证**：需要
- **查询参数**：
- `email`: 教师邮箱
- **成功响应**：
```json
{
"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"
}
]
}
}
```
- **错误响应**：
```json
{
"code": 10009,
"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,
"advise": "任务说明"
}
```
- **成功响应**：
```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": "任务说明",
"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. 批量导入用户
- **接口**：`POST /api/import/users`
- **描述**：通过 Excel 文件批量导入用户
- **认证**：需要
- **请求体**：
- `Content-Type`: `multipart/form-data`
- `file`: Excel 文件（.xlsx）
- **Excel 文件格式**：
| 用户名 | 邮箱 | 密码 | 部门名称 |
|--------|------|------|----------|
| 张三 | zhangsan@example.com | 123456 | 技术部 |
- **成功响应**：
```json
{
"code": 10000,
"message": "成功",
"data": "成功导入2条数据"
}
```
- **错误响应**：
```json
{
"code": 10012,
"message": "成功导入0条数据。错误信息：第2行邮箱已存在;第3行部门不存在;",
"data": null
}
```
### 2. 批量导入课程任务
- **接口**：`POST /api/import/lesson-tasks`
- **描述**：通过 Excel 文件批量导入课程任务
- **认证**：需要
- **请求体**：
- `Content-Type`: `multipart/form-data`
- `file`: Excel 文件（.xlsx）
- **Excel 文件格式**：
| 课程名称 | 微课名称 | 教师邮箱 |
|----------|----------|-----------|
| 数学课程 | 第一章 | teacher@example.com |
- **成功响应**：
```json
{
"code": 10000,
"message": "成功",
"data": "成功导入3条数据"
}
```
- **错误响应**：
```json
{
"code": 10012,
"message": "成功导入0条数据。错误信息：第2行未找到教师用户（teacher@example.com）;",
"data": null
}
```
### 3. 批量导入部门
- **接口**：`POST /api/import/departments`
- **描述**：通过 Excel 文件批量导入部门
- **认证**：需要
- **请求体**：
- `Content-Type`: `multipart/form-data`
- `file`: Excel 文件（.xlsx）
- **Excel 文件格式**：
| 部门名称 | 部门描述 |
|----------|----------|
| 技术部 | 负责技术研发 |
- **成功响应**：
```json
{
"code": 10000,
"message": "成功",
"data": "成功导入2条数据"
}
```
- **错误响应**：
```json
{
"code": 10012,
"message": "成功导入0条数据。错误信息：第2行部门名称已存在;",
"data": null
}
```
## 注意事项
1. 所有时间戳字段均使用秒级时间戳（10 位）
2. 课程任务状态变更时会自动记录相应的时间戳
3. 部门课程任务列表会额外返回用户名信息
4. 分页参数中的页码从 1 开始
5. 批量导入时，Excel 文件必须严格按照模板格式填写
6. 批量导入时，如果某行数据导入失败，会在返回信息中说明具体原因
7. 批量导入时，如果全部数据导入失败，会返回错误状态码（10012）

BIN
批量添加用户模版.xlsx
View File

Binary file not shown.

BIN
批量添加课程模版.xlsx
View File

Binary file not shown.

BIN
批量添加部门模版.xlsx
View File

Binary file not shown.

194
数据库.md
View File

@ -1,194 +0,0 @@
# 数据库设计文档
## 1. 部门表 (departments)
用于存储组织的部门信息。
```sql
CREATE TABLE departments (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL COMMENT '部门名称',
description TEXT DEFAULT NULL COMMENT '部门描述',
created_at BIGINT NOT NULL COMMENT '创建时间（时间戳）',
updated_at BIGINT NOT NULL COMMENT '更新时间（时间戳）'
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='部门表';
```
### 字段说明
- `id`: 部门 ID，自增主键
- `name`: 部门名称，不可为空
- `description`: 部门描述，可为空
- `created_at`: 创建时间，毫秒级时间戳
- `updated_at`: 更新时间，毫秒级时间戳
## 2. 用户表 (users)
存储系统用户信息，包括教师、管理员等角色。
```sql
CREATE TABLE users (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50) NOT NULL COMMENT '用户名',
email VARCHAR(100) NOT NULL UNIQUE COMMENT '邮箱',
password VARCHAR(100) NOT NULL COMMENT '密码',
department_id BIGINT NOT NULL COMMENT '所属部门',
roles INT NOT NULL COMMENT '角色: 1-教师, 2-普通管理员, 3-沟通联络人, 4-系统管理员',
jobs INT NOT NULL COMMENT '岗位: 1-课程制作教师, 2-课程购买方项目负责人, 3-课程制作方沟通联络人, 4-系统制作方项目负责人',
avatar VARCHAR(255) DEFAULT NULL COMMENT '头像',
creator_id BIGINT NOT NULL DEFAULT 1 COMMENT '创建用户的管理员ID',
status INT NOT NULL DEFAULT 1 COMMENT '用户状态: 1-正常, 0-禁用',
created_at BIGINT NOT NULL COMMENT '创建时间（时间戳）',
updated_at BIGINT NOT NULL COMMENT '更新时间（时间戳）',
FOREIGN KEY (department_id) REFERENCES departments (id) ON DELETE RESTRICT,
INDEX idx_users_department_id (department_id)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='用户表';
```
### 字段说明
- `id`: 用户 ID，自增主键
- `username`: 用户名，不可为空
- `email`: 邮箱地址，不可为空，唯一索引
- `password`: 密码（加密存储），不可为空
- `department_id`: 所属部门 ID，外键关联 departments 表
- `roles`: 用户角色，整数枚举：
- 1: 教师
- 2: 普通管理员
- 3: 沟通联络人
- 4: 系统管理员
- `jobs`: 用户岗位，整数枚举：
- 1: 课程制作教师
- 2: 课程购买方项目负责人
- 3: 课程制作方沟通联络人
- 4: 系统制作方项目负责人
- `avatar`: 用户头像 URL，可为空
- `creator_id`: 创建该用户的管理员 ID
- `status`: 用户状态：
- 1: 正常
- 0: 禁用
- `created_at`: 创建时间，毫秒级时间戳
- `updated_at`: 更新时间，毫秒级时间戳
### 索引
- 主键索引：`id`
- 外键索引：`idx_users_department_id (department_id)`
- 唯一索引：`email`
## 3. 课程任务表 (lesson_tasks)
存储课程制作任务的信息和进度。
```sql
CREATE TABLE lesson_tasks
(
id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID，系统自动生成的唯一标识',
course_name VARCHAR(100) NOT NULL COMMENT '所属课程名称，标识任务所属的主课程',
micro_lesson_name VARCHAR(100) NOT NULL COMMENT '具体微课名称，标识任务所属的具体微课单元',
user_id BIGINT NOT NULL COMMENT '任务负责人ID，关联users表的主键id',
progress_status INT NOT NULL DEFAULT 0 COMMENT '任务进度状态：
0-未开始：任务创建后的初始状态
1-脚本制作：正在编写课程脚本
2-脚本审核：脚本提交审核阶段
3-脚本确认：脚本审核通过确认
4-视频拍摄与制作：进行视频录制和后期制作
5-视频确认：最终视频审核确认',
script_create_time BIGINT DEFAULT NULL COMMENT '脚本开始制作的时间戳，状态1时记录',
script_review_time BIGINT DEFAULT NULL COMMENT '脚本提交审核的时间戳，状态2时记录',
script_confirm_time BIGINT DEFAULT NULL COMMENT '脚本审核通过的时间戳，状态3时记录',
video_create_time BIGINT DEFAULT NULL COMMENT '开始视频制作的时间戳，状态4时记录',
video_confirm_time BIGINT DEFAULT NULL COMMENT '视频审核通过的时间戳，状态5时记录',
finish_time BIGINT DEFAULT NULL COMMENT '整个任务完成的时间戳，最终确认后记录',
advise TEXT DEFAULT NULL COMMENT '任务相关的建议、修改意见或其他重要备注信息',
created_at BIGINT NOT NULL COMMENT '记录创建的时间戳，系统自动生成',
updated_at BIGINT NOT NULL COMMENT '记录最后更新的时间戳，系统自动更新',
-- 外键约束：确保user_id关联到users表的有效用户
CONSTRAINT fk_lesson_tasks_user FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE ON UPDATE CASCADE,
-- 索引设计：
-- 1. 用户ID索引：用于快速查找特定用户的所有任务
INDEX idx_user_id (user_id),
-- 2. 进度状态索引：用于按状态筛选和统计任务
INDEX idx_progress_status (progress_status),
-- 3. 课程名称索引：用于按课程分组和查询
INDEX idx_course_name (course_name),
-- 4. 复合索引：用于同时按用户和状态查询
INDEX idx_user_progress (user_id, progress_status)
) ENGINE=InnoDB
DEFAULT CHARSET=utf8mb4
COMMENT='课程任务管理表：记录微课制作的完整流程，包括脚本编写、审核、视频制作等各个环节的进度和时间节点';
```
### 字段说明
- `id`: 任务 ID，自增主键
- `course_name`: 课程名称，不可为空
- `micro_lesson_name`: 微课名称，不可为空
- `user_id`: 负责人 ID，外键关联 users 表
- `progress_status`: 任务进度状态：
- 0: 未开始
- 1: 脚本制作
- 2: 脚本审核
- 3: 脚本确认
- 4: 视频拍摄与制作
- 5: 视频确认
- `script_create_time`: 脚本开始制作的时间戳，状态 1 时记录
- `script_review_time`: 脚本提交审核的时间戳，状态 2 时记录
- `script_confirm_time`: 脚本审核通过的时间戳，状态 3 时记录
- `video_create_time`: 开始视频制作的时间戳，状态 4 时记录
- `video_confirm_time`: 视频审核通过的时间戳，状态 5 时记录
- `finish_time`: 整个任务完成的时间戳，最终确认后记录
- `advise`: 任务相关的建议、修改意见或其他重要备注信息
- `created_at`: 记录创建的时间戳，系统自动生成
- `updated_at`: 记录最后更新的时间戳，系统自动更新
### 索引
- 主键索引：`id`
- 外键索引：`idx_user_id (user_id)`
- 普通索引：`idx_progress_status (progress_status)`
- 普通索引：`idx_course_name (course_name)`
- 复合索引：`idx_user_progress (user_id, progress_status)`
## 数据库关系
1. `users.department_id` -> `departments.id`
- 一个部门可以有多个用户
- 一个用户只能属于一个部门
- 使用 RESTRICT 约束，防止删除仍有用户的部门
2. `lesson_tasks.user_id` -> `users.id`
- 一个用户可以负责多个课程任务
- 一个课程任务只能有一个负责人
- 使用 CASCADE 约束，删除用户时自动删除其负责的课程任务
3. `lesson_tasks` 和 `users` 表关系:
- 一对多关系：一个用户（users）可以负责多个课程任务（lesson_tasks）
- 通过 `user_id` 外键关联，确保任务负责人的有效性
- 使用 CASCADE 级联删除：当用户被删除时，相关任务也会被自动删除
- 使用 CASCADE 级联更新：当用户 ID 更新时，相关任务的 user_id 也会自动更新
4. 索引说明：
- `idx_user_id`: 优化按负责人查询任务的性能
- `idx_progress_status`: 优化按任务状态筛选和统计的性能
- `idx_course_name`: 优化按课程名称查询和分组的性能
- `idx_user_progress`: 优化同时按用户和任务状态查询的性能，适用于查看特定用户的特定状态任务
5. 时间节点追踪：
- 系统通过各个时间戳字段（script_create_time, script_review_time 等）完整记录任务的每个阶段
- 可以通过这些时间戳计算各阶段的耗时，用于任务进度分析和效率优化
## 注意事项
1. 所有时间戳字段使用 BIGINT 类型，存储毫秒级时间戳
2. 字符编码统一使用 utf8mb4，支持完整的 Unicode 字符集
3. 所有表都使用 InnoDB 引擎，支持事务和外键
4. 关键字段都建立了适当的索引以提高查询性能
5. 用户密码在存储前需要进行加密处理
6. 删除用户时会自动删除其关联的课程任务，但不会影响部门数据