# Module B：开班计划与排课（核心业务模块）API 契约

> **模块定位：** 智慧培训业务核心流转引擎，贯穿“立项建班 → 课程配置 → 名单确定 → 课次编排与冲突检测 → 课程表生成 → 学员报到”。
> **设计原则：** 禁止退化为 5 张表的独立 CRUD，全面以“开班计划聚合工作台”与“业务 Command”为主线。
> **优先级统计：** 共 25 个 API (P0: 17个, P1: 7个, P2: 1个)。

---

## 1. 培训计划与聚合工作台 (ClassPlan & Workbench)

### 1.1 分页查询培训计划列表 【P0】【确认】
- **业务目的：** 管理员分页检索开班班次，支持按状态、开班时间范围筛选。
- **HTTP Method：** `GET`
- **Path：** `/train/plans`
- **Permission：** `train:plan:list`
- **Request (Query)：** `pageNum`, `pageSize`, `planName`, `planStatus`, `startTimeBegin`, `startTimeEnd`
- **Response (TableDataInfo)：** 返回包含计划基本信息、课程门数、实际参训人数的概览卡片数据。

### 1.2 创建培训计划 (UC-01) 【P0】【确认】
- **业务目的：** 立项创建新的培训班，明确培训起止时间、计划人数与报到截止规则。
- **HTTP Method：** `POST`
- **Path：** `/train/plans`
- **Permission：** `train:plan:add`
- **Request (PlanCreateDTO)：**
  ```json
  {
    "planName": "沈阳局2026年第1期高速铁路信号检修专项培训班",
    "startTime": "2026-10-10 08:30:00",
    "endTime": "2026-10-24 17:30:00",
    "trainAddress": "沈阳培训基地第3教学楼",
    "recruitNum": 40,
    "applyCondition": "各电务段在岗信号工，具备2年以上工作经验",
    "reportDeadline": "2026-10-09 18:00:00",
    "remark": "全脱产封闭培训"
  }
  ```
- **核心校验：**
  - `startTime < endTime` 起止时间有效性；
  - `reportDeadline <= startTime` 报到截止时间不得晚于开班时间；
  - `recruitNum > 0`；
  - 初始 `plan_status` 强制设为 `0` (未开始)。
- **错误码：** `PLAN_TIME_INVALID (40010)`, `PLAN_NAME_DUPLICATED (40011)`

### 1.3 获取培训计划基本信息 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/plans/{planId}`
- **Permission：** `train:plan:query`

### 1.4 编辑培训计划 (UC-02) 【P0】【确认】
- **HTTP Method：** `PUT`
- **Path：** `/train/plans/{planId}`
- **Permission：** `train:plan:edit`
- **Request (PlanUpdateDTO)：** 包含名称、地址、人数、报到截止时间、备注。已结训计划不可修改。

### 1.5 结束培训计划 (UC-29) 【P0】【确认】
- **业务目的：** 标志本期培训结束，将计划状态置为“已结束”，参训学员状态批量归档为“已完成”，历史签到、学习、成绩锁定留存。
- **HTTP Method：** `POST`
- **Path：** `/train/plans/{planId}/complete`
- **Permission：** `train:plan:complete`
- **事务边界：** 强事务。更新 `train_class_plan.plan_status = 2`，更新该班所有未退学学员的 `train_enrollment.enrollment_status = 4` (已完成) 及 `complete_time = NOW()`。

### 1.6 获取培训计划综合工作台 (PlanWorkbenchVO) 【P0】【确认】
- **业务目的：** 核心枢纽接口！管理员打开某个计划时调用，一次性获取计划生命周期阶段看板与各维度指标摘要，作为后续操作决策入口。
- **HTTP Method：** `GET`
- **Path：** `/train/plans/{planId}/workbench`
- **Permission：** `train:plan:query`
- **Response (AjaxResult<PlanWorkbenchVO>)：** 聚合返回开班基础信息、课程概览、参训人数统计、排课状态概览、住宿需求与预分配统计、成绩配置概览及下一步操作引导文本。

---

## 2. 本期课程配置 (Plan Course)

### 2.1 查询本期已配置课程列表 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/plans/{planId}/courses`
- **Permission：** `train:plan:query`

### 2.2 配置本期课程 (UC-03) 【P0】【确认】
- **业务目的：** 引入课程库中的一门或多门公共课程作为本期培训内容。
- **HTTP Method：** `POST`
- **Path：** `/train/plans/{planId}/courses`
- **Permission：** `train:plan:edit`
- **Request (PlanCourseAddDTO)：** `{"cIds": ["C001", "C002"], "remark": "专业必修"}`
- **核心校验：** 基于 `UNIQUE(plan_id, c_id)` 防重复添加。

### 2.3 移除本期课程 【P1】【确认】
- **HTTP Method：** `DELETE`
- **Path：** `/train/plans/{planId}/courses/{planCourseId}`
- **Permission：** `train:plan:edit`
- **核心校验：** 若该课程已排定课次 (`train_lesson`) 或已关联成绩项目 (`train_score_item`)，严禁删除。

---

## 3. 参训人员管理 (Enrollment)

### 3.1 查看本期参训名单 (UC-06) 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/plans/{planId}/enrollments`
- **Permission：** `train:enrollment:list`
- **Request (Query)：** `pageNum`, `pageSize`, `studentName`, `enrollmentStatus`, `accommodationRequired`

### 3.2 添加单名参训人员 (UC-04) 【P0】【确认】
- **业务目的：** 管理员从已有学员库中选择某位学员加入本班。
- **HTTP Method：** `POST`
- **Path：** `/train/plans/{planId}/enrollments`
- **Permission：** `train:enrollment:add`
- **Request (EnrollmentAddDTO)：** `{"studentId": "S2026001", "sourceType": 1, "accommodationRequired": 1}`
- **核心校验：** 防重复参训 (`UNIQUE(plan_id, student_id)`)；人数上限告警。

### 3.3 Excel批量导入参训人员 (UC-05) 【P0】【确认】
- **业务目的：** 基地通过各站段汇总上报的名单 Excel 一次性批量导入本班学员。
- **HTTP Method：** `POST`
- **Path：** `/train/plans/{planId}/enrollments/batch`
- **Permission：** `train:enrollment:import`
- **Request (Multipart)：** Excel 文件 (`file`)，参数 `autoCreateStudent=true`。
- **事务边界：** 批量事务入库。

### 3.4 获取参训档案详情 【P0】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/enrollments/{enrollmentId}`
- **Permission：** `train:enrollment:query`
- **Response (AjaxResult<EnrollmentDetailVO>)：** 聚合返回参训状态、脱敏身份证、宿舍分配、报到记录、门禁授权状态。

### 3.5 变更参训状态 【P1】【确认】
- **HTTP Method：** `PUT`
- **Path：** `/train/enrollments/{enrollmentId}/status`
- **Permission：** `train:enrollment:edit`
- **Request (JSON)：** `{"enrollmentStatus": 2, "remark": "因公请假"}` (2 请假，3 放弃)

### 3.6 移除参训人员 【P1】【确认】
- **HTTP Method：** `DELETE`
- **Path：** `/train/enrollments/{enrollmentId}`
- **Permission：** `train:enrollment:remove`
- **核心校验：** 若学员已产生考勤或成绩记录，禁止物理删除，提示转为放弃状态。

---

## 4. 课次编排与冲突检查 (Lesson & Timetable)

### 4.1 新增课次 (UC-07) 【P0】【确认】
- **业务目的：** 排定一次具体的教学活动，指定课程、授课教师、上课时间段及教室或实训场地。
- **HTTP Method：** `POST`
- **Path：** `/train/plans/{planId}/lessons`
- **Permission：** `train:lesson:add`
- **Request (LessonCreateDTO)：** `planCourseId`, `tId`, `startTime`, `endTime`, `venueType`, `classRoomId`, `siteId`, `remark`
- **核心校验：** 课次时间落在计划起止时间内；场地二选一；行锁保护下的教师/教室/场地/本班四维排课冲突检查。
- **错误码：** `LESSON_TEACHER_CONFLICT (40040)`, `LESSON_CLASSROOM_CONFLICT (40041)`, `LESSON_SITE_CONFLICT (40042)`, `LESSON_PLAN_OVERLAP (40043)`

### 4.2 修改课次 (UC-08) 【P0】【确认】
- **HTTP Method：** `PUT`
- **Path：** `/train/lessons/{lessonId}`
- **Permission：** `train:lesson:edit`
- **核心校验：** 排除自身后重新进行冲突检查；已有考勤记录时禁止修改时段。

### 4.3 删除课次 (UC-09) 【P1】【确认】
- **HTTP Method：** `DELETE`
- **Path：** `/train/lessons/{lessonId}`
- **Permission：** `train:lesson:remove`
- **核心校验：** 已有打卡考勤记录时严禁删除。

### 4.4 排课冲突检查接口 (UC-10) 【P0】【确认】
- **业务目的：** 管理员在排课弹窗中选择好教师、场地、时间后，前端失焦实时调用该接口进行冲突预检，无需真正入库，返回友好的冲突原因与冲突课次列表。
- **HTTP Method：** `POST`
- **Path：** `/train/lessons/check-conflict`
- **Permission：** `train:lesson:query`
- **Response (AjaxResult<LessonConflictVO>)：** 返回是否存在冲突、冲突类型、冲突详细信息及冲突课次列表。

### 4.5 获取计划完整课表 (UC-11) 【P0】【确认】
- **业务目的：** 按时间轴返回本期培训的所有课次集合，供工作台日历视图展示与打印。
- **HTTP Method：** `GET`
- **Path：** `/train/plans/{planId}/timetable`
- **Permission：** `train:plan:query`
- **Response (AjaxResult<PlanTimetableVO>)**

### 4.6 获取教师个人课表 【P1】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/teacher/{tId}/timetable`
- **Permission：** `train:teacher:query`

---

## 5. 学员报到 (Class Report)

### 5.1 学员报到确认 (UC-15) 【P0】【确认】
- **业务目的：** 学员到达基地后，通过刷身份证、人脸识别或管理员人工核验完成到班报到。完成报到后，立即向学员展示其宿舍安排、课程表与首课教室场地。
- **HTTP Method：** `POST`
- **Path：** `/train/enrollments/{enrollmentId}/report`
- **Permission：** `train:report:confirm`
- **Request (ReportConfirmDTO)：**
  ```json
  {
    "reportWay": 1,
    "reportDeviceSn": "FACE-PAD-EAST-01",
    "verifyNote": "身份证核验通过",
    "forceOverride": false
  }
  ```
- **生命周期策略 (Report Lifecycle Policy)：**
  - 【确认】：`report_deadline` 配置在 `train_class_plan` 上；报到时必须读取并检查该截止时间；
  - 【默认/建议方案（待现场确认）】：若当前时间晚于 `report_deadline`，当 `forceOverride=false` 时返回警告（`REPORT_DEADLINE_WARNING`），提示管理员确认；若 `forceOverride=true` 或系统策略为宽松模式，则允许完成报到，并在报到流水中标记 `is_overdue = true`；
  - 兼容现场确认可能收敛为三种模式：严格阻断 (`BLOCK`)、提示警告 (`WARNING`) 或管理员强制覆盖 (`ADMIN_OVERRIDE`)。
- **Response (AjaxResult<ReportResultVO>)：**
  ```json
  {
    "code": 200,
    "msg": "报到成功！",
    "data": {
      "enrollmentId": 1001,
      "studentName": "张三",
      "reportTime": "2026-10-09 14:20:00",
      "isOverdue": false,
      "policyAction": "NORMAL",
      "dormitory": {
        "building": "南区2号宿舍楼",
        "room": "305室",
        "bedNo": "1号床"
      },
      "nextLesson": {
        "courseName": "信号基础理论",
        "startTime": "2026-10-10 09:00:00",
        "location": "CR101教室"
      }
    }
  }
  ```
- **错误码：** `REPORT_ALREADY_CONFIRMED (40050)`, `REPORT_DEADLINE_WARNING (40051)`

### 5.2 查询计划报到流水列表 【P1】【确认】
- **HTTP Method：** `GET`
- **Path：** `/train/plans/{planId}/reports`
- **Permission：** `train:report:list`

### 5.3 学员端获取个人当前培训信息 【P2】【待现场确认】
- **业务目的：** 学员登录后通过手机端或平板查看本人所在培训班、报到状态、宿舍及课表。
- **HTTP Method：** `GET`
- **Path：** `/train/student/my-training`
- **Permission：** 登录学员默认可见本人信息。
- **分级理由：** 依赖学员端专用界面的排期建设，不作为一期基地管理端闭环的 P0 阻塞项，标记为 P2。