11 KiB
11 KiB
Module B：开班计划与排课（核心业务模块）API 契约
模块定位： 智慧培训业务核心流转引擎，贯穿“立项建班 → 课程配置 → 名单确定 → 课次编排与冲突检测 → 课程表生成 → 学员报到”。 设计原则： 禁止退化为 5 张表的独立 CRUD，全面以“开班计划聚合工作台”与“业务 Command”为主线。 优先级统计： 共 24 个 API (P0: 17个, P1: 6个, 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)：
{ "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)： 聚合返回开班基础信息、课程概览、参训人数统计、排课状态概览、住宿需求与预分配统计、成绩配置概览及下一步操作引导文本。
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)： 聚合返回参训状态、脱敏身份证、宿舍分配、报到记录、门禁授权状态。
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)： 返回是否存在冲突、冲突类型、冲突详细信息及冲突课次列表。
4.5 获取计划完整课表 (UC-11) 【P0】【确认】
- 业务目的： 按时间轴返回本期培训的所有课次集合，供工作台日历视图展示与打印。
- HTTP Method：
GET - Path：
/train/plans/{planId}/timetable - Permission：
train:plan:query - Response (AjaxResult)
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)：
{ "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)：
{ "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。