8.7 KiB
8.7 KiB
RailwaySystem Phase 3：P1 / P2 需求储备池 (Backlog Register)
最高原则： 本轮研发聚焦于 53 个 P0 API 的最小闭环，严禁将任何 P1 或 P2 需求混入当前研发排期与测试范围。 文档定位： 本文档作为系统后续演进阶段（Phase 4 / Phase 5）的正式需求储备池，确保设计资产连续，防止需求流失。 数据基线： 严格对齐 API Contract V1.0.1 真实物理端点定义，P1 共 34 个，P2 共 2 个，合计 36 个非核心接口全部封存入库。
1. P1 / P2 规模与模块分布统计
API Contract V1.0.1 中定义的 89 个 API 优先级分布为：
- P0 (核心闭环，本轮必做)： 53 个
- P1 (辅助支撑，登记备查)： 34 个
- P2 (待现场确认，远期建设)： 2 个
pie title API 全局物理端点分布 (总数 89)
"P0 核心闭环 (本轮开发)" : 53
"P1 辅助能力 (Backlog 储备)" : 34
"P2 远期待定 (现场确认)" : 2
| 业务模块 | 物理总数 | P0 数量 | P1 数量 | P2 数量 | P1/P2 规划定位 |
|---|---|---|---|---|---|
| Module A 人员与基础资源 | 38 | 20 | 18 | 0 | 主数据全功能闭环、资源载体绑定、班牌硬件入库 |
| Module B 开班计划与排课 | 24 | 17 | 6 | 1 | 计划反向删除/移除、教师个人课表、学员移动端门户 |
| Module C 住宿/门禁/考勤 | 13 | 9 | 4 | 0 | 房态实时看板、门禁下发流水、考勤人工补录、考勤综合汇总 |
| Module D 成绩/学习/统计/画像 | 14 | 7 | 6 | 1 | 成绩Excel导入、学习记录流水、学员训练详情、学员综合画像、成绩下钻分布 |
| 合计 | 89 | 53 | 34 | 2 | P1 (34) + P2 (2) = 36 全部封存入库 |
2. 34 个 P1 辅助能力清单 (Backlog Register)
2.1 Module A：人员与基础资源辅助能力 (18 个 API)
| 序号 | HTTP Method & Path | API 业务描述 | 所属领域 | 计划演进阶段 |
|---|---|---|---|---|
| 1 | PUT /train/teacher/{tId}/status |
修改教师启停用状态 (0停用, 1启用) | 教师管理 | Phase 4 基础功能增强 |
| 2 | PUT /train/student/{sId} |
修改学员主档基础信息 | 学员管理 | Phase 4 基础功能增强 |
| 3 | POST /train/student/import |
学员库 Excel 批量全局导入 | 学员管理 | Phase 4 基础功能增强 |
| 4 | PUT /train/course/{cId} |
修改公共课程库基础资料 | 课程库 | Phase 4 基础功能增强 |
| 5 | POST /train/course/{cId}/resources |
课程绑定教学资源 (文档/视频/VR) | 课程资源 | Phase 4 教学资源深化 |
| 6 | DELETE /train/course/{cId}/resources/{resourceId} |
课程解绑教学资源 | 课程资源 | Phase 4 教学资源深化 |
| 7 | GET /train/resource/list |
分页查询教学资源列表 | 教学资源 | Phase 4 教学资源深化 |
| 8 | GET /train/resource/{resourceId} |
获取指定教学资源详情与预览地址 | 教学资源 | Phase 4 教学资源深化 |
| 9 | POST /train/resource |
新增教学资源 (支持文档、视频、VR、3D、链接) | 教学资源 | Phase 4 教学资源深化 |
| 10 | PUT /train/resource/{resourceId} |
修改教学资源描述与类型 | 教学资源 | Phase 4 教学资源深化 |
| 11 | DELETE /train/resource/{resourceId} |
删除教学资源 (引用时校验阻断) | 教学资源 | Phase 4 教学资源深化 |
| 12 | PUT /train/classroom/{classRoomId} |
修改教室容纳人数与位置 | 教室管理 | Phase 4 基础功能增强 |
| 13 | PUT /train/training-site/{siteId} |
修改实训场地设备类型与容量 | 实训场地 | Phase 4 基础功能增强 |
| 14 | GET /train/electronic-board/list |
分页查询电子班牌硬件设备列表 | 电子班牌 | Phase 4 硬件运维管理 |
| 15 | GET /train/electronic-board/{boardId} |
获取电子班牌绑定教室与网络配置 | 电子班牌 | Phase 4 硬件运维管理 |
| 16 | POST /train/electronic-board |
注册录入电子班牌 SN 与网络端点 | 电子班牌 | Phase 4 硬件运维管理 |
| 17 | PUT /train/electronic-board/{boardId} |
修改电子班牌参数配置 | 电子班牌 | Phase 4 硬件运维管理 |
| 18 | PUT /train/dormitory/{dormId} |
修改宿舍房间核定容量与状态 (容量不可小于当前已住人数) | 宿舍管理 | Phase 4 基础功能增强 |
2.2 Module B：开班计划与排课辅助能力 (6 个 API)
| 序号 | HTTP Method & Path | API 业务描述 | 所属领域 | 计划演进阶段 |
|---|---|---|---|---|
| 19 | DELETE /train/plans/{planId}/courses/{planCourseId} |
移除本期课程 (已有排课时强校验阻断) | 选课管理 | Phase 4 计划运维 |
| 20 | PUT /train/enrollments/{enrollmentId}/status |
手工变更参训状态 (2请假, 3放弃) | 参训管理 | Phase 4 学员生命周期 |
| 21 | DELETE /train/enrollments/{enrollmentId} |
移除参训人员 (已有打卡或成绩时阻断) | 参训管理 | Phase 4 学员生命周期 |
| 22 | DELETE /train/lessons/{lessonId} |
删除排课课次 (已有考勤打卡记录时阻断) | 排课管理 | Phase 4 教学日程调整 |
| 23 | GET /train/teacher/{tId}/timetable |
获取指定教师跨班个人周课表日历 | 课表视图 | Phase 4 教师协同服务 |
| 24 | GET /train/plans/{planId}/reports |
查询全班学员报到流水详细明细列表 | 报到管理 | Phase 4 报到精细运维 |
2.3 Module C：住宿、门禁与考勤辅助能力 (4 个 API)
| 序号 | HTTP Method & Path | API 业务描述 | 所属领域 | 计划演进阶段 |
|---|---|---|---|---|
| 25 | GET /train/dormitory/occupancy-board |
宿舍楼层网格实时房态占用看板 | 住宿管理 | Phase 4 宿管大屏可视化 |
| 26 | GET /train/plans/{planId}/dorm-auths |
查询全班门禁授权下发流水与下发状态 | 门禁同步 | Phase 4 硬件运维管理 |
| 27 | POST /train/attendance/manual-add |
人工直接补录课次漏打卡考勤记录 | 考勤管理 | Phase 4 考勤特批运维 |
| 28 | GET /train/plans/{planId}/attendance/summary |
查询计划考勤汇总概况与缺勤率统计 | 考勤统计 | Phase 4 统计报表增强 |
2.4 Module D：成绩、学习、统计与画像辅助能力 (6 个 API)
| 序号 | HTTP Method & Path | API 业务描述 | 所属领域 | 计划演进阶段 |
|---|---|---|---|---|
| 29 | POST /train/plans/{planId}/scores/import |
Excel 批量导入全班单科成绩 | 成绩管理 | Phase 4 成绩快速录入 |
| 30 | GET /train/plans/{planId}/study-records |
多维分页查询全班外部自主实训流水 | 学习记录 | Phase 4 实训记录审计 |
| 31 | GET /train/enrollments/{enrollmentId}/study-records |
查询单学员自主实训时长明细流水 | 学习记录 | Phase 4 学员档案深化 |
| 32 | GET /train/enrollments/{enrollmentId}/training-detail |
查询学员个人全流程训练详情 (出勤/单科成绩/实训流水) | 综合成效 | Phase 4 学员档案深化 |
| 33 | POST /train/enrollments/{enrollmentId}/portrait/generate |
结课前后手动触发 / 重新刷新生成学员简单画像 | 学员画像 | Phase 4 画像计算引擎 |
| 34 | GET /train/enrollments/{enrollmentId}/portrait |
查询学员综合画像数据 (弹性指标集与标签集展示) | 学员画像 | Phase 4 学员多维分析 |
3. 2 个 P2 远期/待现场确认能力 (Deferred Register)
以下 2 个 API 明确属于 PRD V-01 ~ V-14 现场确认范围或面向移动端/学员端的远期接口，严禁在一期管理端闭环中盲目推进：
| 序号 | HTTP Method & Path | 接口名称与业务目的 | 暂缓原因与现场确认事项 | 激活准入条件 |
|---|---|---|---|---|
| P2-01 | GET /train/student/my-training |
学员端移动端个人当前培训日程与成绩查看 | 属于面向学员独立移动端/小程序的门户接口，目前一期定位于基地管理端运转。 | 现场完成学员端 UI 规划与移动端技术选型确认。 |
| P2-02 | GET /train/plans/{planId}/statistics/score-distribution |
计划成绩分段直方图与下钻区间统计 | PRD V-07/V-08 明确提出“是否设立固定分数线或区间待现场确认”，避免过度预设区间。 | 现场最终确认成绩分段规则与及格线标准。 |
4. Backlog 演进策略建议
- 版本冻结铁律： 在 Phase 3 研发及后续集成验收通过之前，上述 36 个 P1/P2 项严禁立项开工；
- Phase 4 准入： 当 Phase 3 验收通过，且基地管理员试运行 P0 主链路顺畅后，优先开放 Phase 4 中的“基础数据修改”与“Excel 批量导入/流水查询”类辅助项；
- Phase 5 准入： 学员画像深度计算与学员移动端入口统一在 Phase 5 根据甲方现场业务实测反馈决定上线节奏。