blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4bd2f54856a05d770013f2037ed798869eac8fb2
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.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 中登记备查，不计入开发排期。
  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 总数 26 个 每个 Issue 为 0.5~2 个开发日的独立可验收业务能力
P0 API 覆盖率 53 / 53 (100%) 契约逐条提取 53 个 P0 API 全量映射闭环，无遗漏无多余
Contract Gap 状态 CG-01: RESOLVED
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 阶段总纲、最高原则、主链路、统计总览、Contract Gap 分析与文档索引
01 01_epic_overview.md 12 个业务 Epic 概览、目标、业务边界与包含的 Issue 对应清单
02 02_p0_issue_backlog.md 26 个 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 34 个 P1 辅助 API 与 2 个 P2 远期 API 的统一登记与后续演进规划
08 08_risk_register.md 技术风险登记册、稳定资源锁策略、外部 Mock 隔离与 CG-01 裁决辅助表
09 09_issue_review_round1.md Phase 3 Issue Review Round 1 审查整改记录与结论报告
Reference in new issue View Git Blame Copy Permalink