113 lines
8.7 KiB
Markdown
113 lines
8.7 KiB
Markdown
# 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 个
|
||
|
||
```mermaid
|
||
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 演进策略建议
|
||
|
||
1. **版本冻结铁律：** 在 Phase 3 研发及后续集成验收通过之前，上述 36 个 P1/P2 项严禁立项开工；
|
||
2. **Phase 4 准入：** 当 Phase 3 验收通过，且基地管理员试运行 P0 主链路顺畅后，优先开放 Phase 4 中的“基础数据修改”与“Excel 批量导入/流水查询”类辅助项；
|
||
3. **Phase 5 准入：** 学员画像深度计算与学员移动端入口统一在 Phase 5 根据甲方现场业务实测反馈决定上线节奏。
|