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

9.2 KiB
Raw Blame History

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 中登记备查，不计入开发排期。
  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），均严格围绕以下最短业务闭环主链路展开推进：

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 阶段总纲、最高原则、主链路、统计总览、Contract Gap 分析与文档索引
01 01_epic_overview.md 12 个业务 Epic 概览、目标、业务边界与包含的 Issue 对应清单
02 02_p0_issue_backlog.md 21 个 P0 Issue 详细技术卡片（严格包含 22 项技术定义与 Given/When/Then 验收准则）
03 03_dependency_graph.md Mermaid DAG 依赖图，清晰展示串行依赖与并行泳道
04 04_wave_plan.md Wave 0 ~ Wave 7 开发推进批次计划、进入条件、产出目标与退出准则
05 05_agent_assignment.md Gemini Flash 与 Codex 研发分工建议及 Generator (YES/PARTIAL/NO) 执行策略
06 06_acceptance_matrix.md 全链路追踪矩阵 (UC → API → Issue → Test) 及 5 大 Invariant / 1 项生命周期策略归属矩阵
07 07_p1_p2_backlog.md 40 个 P1 辅助 API 与 2 个 P2 远期 API 的统一登记与后续演进规划
08 08_risk_register.md 技术风险登记册、并发防死锁策略、外部 Mock 隔离与现场确认事项应对策略
Reference in new issue View Git Blame Copy Permalink