# 进度管理系统 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: 禁用