122 lines
8.4 KiB
Markdown
122 lines
8.4 KiB
Markdown
# RailwaySystem Phase 3：P0 Epic / Issue 任务拆分总纲
|
||
|
||
> **阶段状态：** Phase 3 任务分解完成稿 (正式基线)
|
||
> **业务最高基线：** [一期 PRD V1.0](../requirements/一期PRD-V1.0.md)
|
||
> **数据库基线：** `db-v2-migration-passed-20260914` (21张表 KingbaseES 物理迁移验证通过)
|
||
> **代码生成器基线：** `generator-v2-ready-20260914` (Kingbase 只读验证通过)
|
||
> **API 契约基线：** `api-v2-contract-v1.0.1` (89 个物理 API 端点，P0: 53, P1: 34, P2: 2)
|
||
> **审查基线：** `docs/issues-v1/09_issue_review_round1.md` (Review Round 1 Final = A)
|
||
> **实施策略：** 严格以 PRD V1.0 业务闭环为主线，以 Database V2 为持久化底座，聚焦 P0 最小闭环。
|
||
|
||
---
|
||
|
||
## 1. 拆分目标与核心原则
|
||
|
||
本阶段旨在将 `api-v2-contract-v1.0.1` 中的 **53 个 P0 API** 以及支撑业务运转的核心基础设施，转化为**可独立开发、可代码审查 (Review)、可自动化测试、可业务验收**的 Epic 与 Issue。
|
||
|
||
本阶段**严禁编写任何业务代码**，所有拆解严格以 `api-v2-contract-v1.0`（commit `67543e04`）及 V1.0.1 修订为基线展开。
|
||
|
||
### 1.1 核心原则与硬约束
|
||
1. **业务能力驱动，拒绝单表 CRUD：** 严禁以数据库物理表为单位拆分 Issue（如禁止设立“开发 train_lesson CRUD”），必须按“可独立交付与验收的业务动作/能力”进行拆分（如“实现课次排课与三类资源冲突检测”）；
|
||
2. **只拆 P0，严格范围控制：**
|
||
- 锁定 53 个 P0 API 作为本轮研发唯一核心目标；
|
||
- 34 个 P1 辅助 API 与 2 个 P2 远期 API 仅在 [`07_p1_p2_backlog.md`](07_p1_p2_backlog.md) 中登记备查，不计入开发排期。
|
||
3. **主数据最小必要集合原则：**
|
||
- 基础主数据不作为全量阻塞项，仅建设支撑主业务链路所必需的最小集合（Teacher, Student, Course, Classroom, TrainingSite, Dormitory）。
|
||
4. **不变量与并发控制强行绑定：**
|
||
- 5 大跨表业务硬不变量（INV-01 ~ INV-05）与 1 项报到生命周期策略，责任落实到唯一的责任 Issue；
|
||
- 排课并发冲突（教师/教室/场地/班级）与宿舍分配防超卖（行锁 `SELECT FOR UPDATE` + 性别隔离），必须在 Issue 中明确 SQL 与锁策略。
|
||
5. **外部对接 Mock 优先与事务轻量解耦：**
|
||
- 外部硬件系统（班牌、门禁、VR/3D）一期一律采用 SPI + Mock 桩实现，严禁引入 MQ、Kafka、RabbitMQ、Outbox 等重型中间件；
|
||
- 外部调用一律置于数据库本地事务之外，通过事务提交后（`afterCommit`）轻量解耦触发，外部失败绝不回滚已提交的业务数据，支持手动重试。
|
||
|
||
---
|
||
|
||
## 2. 主链路业务开发优先级
|
||
|
||
系统的所有 Issue 依赖与开发批次（Wave），均严格围绕以下**最短业务闭环主链路**展开推进：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
M1[基础数据: 教师 / 学员 / 课程 / 空间] --> M2[创建培训计划 Plan]
|
||
M2 --> M3[配置本期课程 PlanCourse]
|
||
M3 --> M4[添加参训名单 Enrollment]
|
||
M4 --> M5[课次排课与冲突检测 Lesson]
|
||
M5 --> M6[聚合生成完整课表 Timetable]
|
||
M4 --> M7[住宿批量预分配 Accommodation]
|
||
M7 --> M8[学员报到确认 Report]
|
||
M5 --> M9[电子班牌打卡考勤 Attendance]
|
||
M8 --> M9
|
||
M9 --> M10[成绩项目与打分台账 Score]
|
||
M4 --> M11[外部实训记录接入 StudyRecord]
|
||
M10 --> M12[培训综合统计与工作台 Statistics/Workbench]
|
||
M11 --> M12
|
||
M12 --> M13[结束培训计划 Complete Plan]
|
||
|
||
style M1 fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
|
||
style M2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
|
||
style M4 fill:#fff3e0,stroke:#f57c00,stroke-width:2px
|
||
style M5 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
|
||
style M7 fill:#e0f2f1,stroke:#00796b,stroke-width:2px
|
||
style M9 fill:#fbe9e7,stroke:#d84315,stroke-width:2px
|
||
style M10 fill:#fffde7,stroke:#fbc02d,stroke-width:2px
|
||
style M13 fill:#ede7f6,stroke:#512da8,stroke-width:2px
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 全局核心统计指标
|
||
|
||
经严密分解与审查，Phase 3 输出的核心统计指标如下：
|
||
|
||
| 统计维度 | 指标数值 | 备注说明 |
|
||
|:---|:---|:---|
|
||
| **Epic 总数** | **12 个** | 覆盖主数据、核心计划、排课、住宿、门禁、考勤、成绩、学习、统计、权限字典与端到端验收 |
|
||
| **P0 Issue 总数** | **26 个** | 每个 Issue 为 0.5~2 个开发日的独立可验收业务能力 |
|
||
| **P0 API 覆盖率** | **53 / 53 (100%)** | 契约逐条提取 53 个 P0 API 全量映射闭环，无遗漏无多余 |
|
||
| **Contract Gap 状态** | **CG-01: RESOLVED<br/>CG-02: RESOLVED** | CG-01 采纳 53 个逐 API 正式口径；CG-02 扩展 VO 回显字段闭环 |
|
||
| **开发 Wave 数量** | **8 个** | Wave 0 (准备) ~ Wave 7 (验收)，层层递进 |
|
||
| **首批可立即开发 Issue** | **8 个** | Wave 0 (3个) + Wave 1 中不依赖 Plan 的基础数据 (5个) |
|
||
| **必须等待 Module B 的 Issue** | **13 个** | 涵盖排课、住宿分配、报到、考勤、成绩配置/录入、学习记录、工作台与端到端验收 |
|
||
| **Generator 策略分布** | **YES: 4, PARTIAL: 11, NO: 11** | 机器校验：4 + 11 + 11 = 26 (符合 P0 Issue 总数 26) |
|
||
| **Recommended Agent 分工** | **Gemini: 11, Codex: 15** | Gemini 负责基础 CRUD/VO/权限字典；Codex 负责高并发锁/复杂事务/不变量/端到端 |
|
||
|
||
---
|
||
|
||
## 4. 契约偏差审查与裁决落地 (Contract Gap Analysis)
|
||
|
||
在对齐 `api-v2-contract-v1.0` 与 Issue 拆分过程中登记的 2 项契约偏差，技术负责人已作出正式裁决并全部闭环：
|
||
|
||
### 4.1 CG-01：Module A P0 统计数字与逐 API 标注矛盾【状态：RESOLVED】
|
||
- **裁决结论：** **详细 API 标记优先于错误摘要统计；P0 正式集合以 53 个逐 API 标记为准。**
|
||
- **落地执行：**
|
||
- 宿舍 4 个基础维护 API（列表、详情、新增、选项）属于一期 P0，因为 Accommodation 住宿主流程强依赖可维护的宿舍房间基础资源、核定容量与性别隔离属性；
|
||
- Module A P0 确认为 20 个，全局 P0 集合确定为 53 个（Module A: 20, Module B: 17, Module C: 9, Module D: 7）；
|
||
- 由 `ISSUE-01-05` 完整承揽，P0 覆盖率正式达成 **53/53 (100%)**。
|
||
|
||
### 4.2 CG-02：课次编辑所需字段与单查接口缺失【状态：RESOLVED】
|
||
- **裁决结论：** **通过扩展 TimetableLessonItemVO 解决；不新增 Lesson 详情 API。**
|
||
- **落地执行：**
|
||
- 严禁在 Issue 阶段或契约中新增 `GET /train/lessons/{lessonId}` 端点，保持 API Contract 接口数量稳定；
|
||
- 在 `docs/api-v2/06_dto_vo_catalog.md` 中补齐 `TimetableLessonItemVO` 的关键外键关联字段（`planCourseId`、`tId`、`venueType`、`classRoomId`、`classRoomName`、`siteId`、`siteName`、`remark`）；
|
||
- 前端通过完整课表 `PlanTimetableVO` 直接回显 Lesson 编辑表单，随后调用既有的 `PUT /train/lessons/{lessonId}`，流程完全自洽闭环。
|
||
|
||
---
|
||
|
||
## 5. 文档索引导航 (docs/issues-v1/)
|
||
|
||
本套 Issue 任务分解规范包含以下 10 篇文档：
|
||
|
||
| 序号 | 文档名称 | 核心内容 |
|
||
|:---|:---|:---|
|
||
| 00 | [`00_readme.md`](00_readme.md) | 阶段总纲、最高原则、主链路、统计总览、Contract Gap 分析与文档索引 |
|
||
| 01 | [`01_epic_overview.md`](01_epic_overview.md) | 12 个业务 Epic 概览、目标、业务边界与包含的 Issue 对应清单 |
|
||
| 02 | [`02_p0_issue_backlog.md`](02_p0_issue_backlog.md) | 26 个 P0 Issue 详细技术卡片（严格包含 22 项技术定义与 Given/When/Then 验收准则） |
|
||
| 03 | [`03_dependency_graph.md`](03_dependency_graph.md) | Mermaid DAG 依赖图，清晰展示串行依赖与并行泳道 |
|
||
| 04 | [`04_wave_plan.md`](04_wave_plan.md) | Wave 0 ~ Wave 7 开发推进批次计划、进入条件、产出目标与退出准则 |
|
||
| 05 | [`05_agent_assignment.md`](05_agent_assignment.md) | Gemini Flash 与 Codex 研发分工建议及 Generator (YES/PARTIAL/NO) 执行策略 |
|
||
| 06 | [`06_acceptance_matrix.md`](06_acceptance_matrix.md) | 全链路追踪矩阵 (UC → API → Issue → Test) 及 5 大 Invariant / 1 项生命周期策略归属矩阵 |
|
||
| 07 | [`07_p1_p2_backlog.md`](07_p1_p2_backlog.md) | 34 个 P1 辅助 API 与 2 个 P2 远期 API 的统一登记与后续演进规划 |
|
||
| 08 | [`08_risk_register.md`](08_risk_register.md) | 技术风险登记册、稳定资源锁策略、外部 Mock 隔离与 CG-01 裁决辅助表 |
|
||
| 09 | [`09_issue_review_round1.md`](09_issue_review_round1.md) | Phase 3 Issue Review Round 1 审查整改记录与结论报告 |
|