jinduguanli/API文档.md

# 进度管理系统 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）