blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bd2d5b03c3c0e1cebe90b48918c81fd77b88baee
railwaysystem/docs/issues-v1/00_readme.md
T

117 lines
9.2 KiB
Markdown
Raw Normal View History

持续集成：新增GitLab CI/CD自动化流水线配置与环境支持
2026-09-14 09:31:42 +08:00
# RailwaySystem Phase 3：P0 Epic / Issue 任务拆分总纲
> **阶段状态：** Phase 3 任务分解完成稿 (正式基线)
> **业务最高基线：** `doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md`
> **数据库基线：** `db-v2-migration-passed-20260914` (21张表 KingbaseES 物理迁移验证通过)
> **代码生成器基线：** `generator-v2-ready-20260914` (Kingbase 只读验证通过)
> **API 契约基线：** `api-v2-contract-v1.0` (Review Round 1 修订版，91 个 API)
> **本阶段原则：** **业务能力驱动拆分，严禁一张表机械对应一个 Issue；只拆 P0，P1/P2 仅作 Backlog 登记；严禁编写业务代码与修改数据库。**
---
## 1. 拆分目标与核心原则
本阶段旨在将 `api-v2-contract-v1.0` 中的 **49 个 P0 API** 以及支撑业务运转的核心基础设施，转化为**可独立开发、可代码审查 (Review)、可自动化测试、可业务验收**的 Epic 与 Issue。
### 1.1 最高拆分原则
1. **业务能力驱动，拒绝单表 CRUD：**
- 错误做法：拆分为 `开发 train_enrollment 表 CRUD`、`开发 train_lesson 表 CRUD`。
- 正确做法：拆分为 `实现培训计划参训人员管理 (含防重与名单)`、`实现课次排课与四维冲突排他锁检测`。
2. **只拆 P0 闭环，严格控制范围：**
- 锁定 49 个 P0 API 作为本轮研发唯一核心目标；
- 40 个 P1 辅助 API 与 2 个 P2 远期 API 仅在 [`07_p1_p2_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/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 总数** | **21 个** | 每个 Issue 为 0.5~2 个开发日的独立可验收业务能力 |
| **P0 API 覆盖率** | **100% (49/49)** | 完整映射 API Contract 中全部 49 个 P0 API（且涵盖 Module A 全部 20 个接口） |
| **Contract Gap 数量** | **2 项** | 详见本文档第 4 节及 Risk Register，技术风险完全可控 |
| **开发 Wave 数量** | **8 个** | Wave 0 (准备) ~ Wave 7 (验收)，层层递进 |
| **首批可立即开发 Issue** | **8 个** | Wave 0 (3个) + Wave 1 中不依赖 Plan 的基础数据 (5个) |
| **必须等待 Module B 的 Issue** | **10 个** | 涵盖排课、住宿分配、报到、考勤、成绩配置/录入、学习记录、工作台与端到端验收 |
| **Generator 策略分布** | YES: **4**, PARTIAL: **10**, NO: **7** | 基础表用 YES/PARTIAL 生成骨架，核心领域逻辑与聚合手写 |
| **Recommended Agent 分工** | Gemini: **9**, Codex: **12** | Gemini 负责基础 CRUD/VO/权限字典；Codex 负责高并发锁/复杂事务/不变量/端到端 |
---
## 4. 契约偏差审查 (Contract Gap Analysis)
在对齐 `api-v2-contract-v1.0` 与 Issue 拆分过程中，识别并登记了 2 项契约统计与定义的细微偏差（Contract Gap）：
### 4.1 Gap 1：Module A P0 统计数字与正文标注偏差 (16 vs 20)
- **现象：** `00_readme.md` 与 `02_module_a_base_resource_api.md` 概览统计声明 Module A 拥有 16 个 P0 API、22 个 P1 API（总数 38）。但正文中带有【P0】标记的条目实际有 20 个（教师 4 个、学员 3 个、课程 3 个、教室 3 个、场地 3 个、宿舍 4 个）。
- **根因：** 宿舍管理的 4 个接口（`GET /train/dormitory/list`, `GET /train/dormitory/{dormId}`, `POST /train/dormitory`, `GET /train/dormitory/options`）在正文中被标记为 P0，但概览统计口径中未将其计入主数据最小必要集合（4+3+3+3+3 = 16）。
- **处理策略：**
- 本次 Issue 拆分采取**最大化安全覆盖原则**：设立独立 `ISSUE-01-05` 完整实现宿舍 4 个基础维护接口，保证无论是按 16 还是 20 统计口径，实际业务均不受任何阻塞；
- 正式 API 覆盖率判定中，49/49 个 P0 API 实现 100% 全覆盖。
### 4.2 Gap 2：Module B 课次单查接口定义缺失
- **现象：** `00_readme.md` 第 136 行概览描述写有“课次详情”，但 `03_module_b_plan_enrollment_schedule_api.md` 正文中未独立定义 `GET /train/lessons/{lessonId}` 接口。
- **根因：** 排课界面的数据回显完全由 `GET /train/plans/{planId}/timetable`（完整课表 VO）及冲突预检接口支撑，不需要对单课次频繁发起独立的详情 HTTP 请求。
- **处理策略：** 严格遵循“不得在 Issue 阶段擅自发明新 API”铁律，暂不新增独立的课次详情接口，排课回显通过现有 Timetable 接口与课次列表解决；若后续前端组件有强诉求，由技术负责人走 API Contract Change 流程统一增补。
---
## 5. 文档索引导航 (docs/issues-v1/)
本套 Issue 任务分解规范包含以下 9 篇文档：
| 序号 | 文档名称 | 核心内容 |
|:---|:---|:---|
| 00 | [`00_readme.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/00_readme.md) | 阶段总纲、最高原则、主链路、统计总览、Contract Gap 分析与文档索引 |
| 01 | [`01_epic_overview.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/01_epic_overview.md) | 12 个业务 Epic 概览、目标、业务边界与包含的 Issue 对应清单 |
| 02 | [`02_p0_issue_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/02_p0_issue_backlog.md) | 21 个 P0 Issue 详细技术卡片（严格包含 22 项技术定义与 Given/When/Then 验收准则） |
| 03 | [`03_dependency_graph.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/03_dependency_graph.md) | Mermaid DAG 依赖图，清晰展示串行依赖与并行泳道 |
| 04 | [`04_wave_plan.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/04_wave_plan.md) | Wave 0 ~ Wave 7 开发推进批次计划、进入条件、产出目标与退出准则 |
| 05 | [`05_agent_assignment.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/05_agent_assignment.md) | Gemini Flash 与 Codex 研发分工建议及 Generator (YES/PARTIAL/NO) 执行策略 |
| 06 | [`06_acceptance_matrix.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/06_acceptance_matrix.md) | 全链路追踪矩阵 (UC → API → Issue → Test) 及 5 大 Invariant / 1 项生命周期策略归属矩阵 |
| 07 | [`07_p1_p2_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/07_p1_p2_backlog.md) | 40 个 P1 辅助 API 与 2 个 P2 远期 API 的统一登记与后续演进规划 |
| 08 | [`08_risk_register.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/08_risk_register.md) | 技术风险登记册、并发防死锁策略、外部 Mock 隔离与现场确认事项应对策略 |
Reference in new issue Copy Permalink