4.4 KiB
4.4 KiB
RailwaySystem API Contract V1.0.1 Patch 说明
版本定位： API Contract V1.0.1 一致性修订补丁 修订日期： 2026-09-14 修订原则： 仅针对技术负责人正式裁决 (CG-01 与 CG-02) 开展一致性修正，不改变 PRD 业务范围，不修改 Database V2 物理结构。
PATCH-01：Module A P0 统计遗漏与全局口径修正 (CG-01)
1. 修订原因
- 在 API Contract V1.0 的
02_module_a_base_resource_api.md头部摘要及总纲中，将 Module A 的 P0 统计误写为 16 个； - 经核验正文详细定义，宿舍基础维护的 4 个 API（列表、详情、新增、选项）正文中均已明确打上【P0】标记；
- 业务主链路中，Accommodation 模块的批量预分配与调房强依赖可维护的宿舍基础房间资源、核定容量与性别隔离属性，故宿舍基础维护 4 个 API 属于一期不可或缺的 P0 核心能力。
2. 修订内容
docs/api-v2/02_module_a_base_resource_api.md头部统计由P0: 16个, P1: 22个修正为P0: 20个, P1: 18个；- 全局 P0 正式集合以逐 API 标记为准，从原宣称的 49 个正式收敛并确认为 53 个；
- 模块头部声明口径下 P1 由 40 个修正为 36 个（经 PATCH-03 进一步收敛物理条目为 34 个）；P2 保持 2 个不变。
3. API 增删统计
- 新增 HTTP API： 0
- 删除 HTTP API： 0
PATCH-02：TimetableLessonItemVO 字段补齐以支持课次编辑回显 (CG-02)
1. 修订原因
- 原
docs/api-v2/06_dto_vo_catalog.md中定义的PlanTimetableVO（TimetableLessonItemVO）仅包含了课程名称、教师名称、场地名称等展示文本，缺少前端进入课次编辑弹窗表单回显所需的实体主键/外键 ID； - 若无外键 ID，前端从课表点击进入编辑时无法预填下拉选项，容易误导后续开发新增单查接口；
- 技术负责人裁决禁止新增
GET /train/lessons/{lessonId}，由前端从完整课表直接获取详情并编辑，故需在 VO 层补强数据字段。
2. 修订内容
在 docs/api-v2/06_dto_vo_catalog.md 的 TimetableLessonItemVO 中，严格沿用 Database V2 / API Contract 统一命名规范，补齐以下必要关联字段：
planCourseId: Long (本期计划课程关联标识)tId: String (授课教师工号/标识)venueType: Integer (场地类型：1教室 2实训场地)classRoomId: Long (普通教室物理标识，venueType=1 时有效)classRoomName: String (普通教室名称)siteId: Long (实训场地物理标识，venueType=2 时有效)siteName: String (实训场地名称)remark: String (课次备注)
3. API 增删统计
- 新增 HTTP API： 0
- 删除 HTTP API： 0
PATCH-03：API 物理端点计数一致性修复 (CG-03)
1. 修订原因
- 原问题：
- V1.0 摘要统计声明：Module B = 25, Module D = 15, 全局 Total = 91；
- 但正文真实定义的 Method + Path 物理端点实际为：Module B = 24, Module D = 14, 全局 Total = 89。
- 根因分析：
- 摘要统计保留了两个未形成正式 HTTP 契约的预想接口；
- 其中 Module B 的 Lesson 详情单查接口已经通过 CG-02 裁决为“不新增”（由课表 VO 直接回显）；
- Module D 契约中所有一期业务能力均已由 14 个真实 API 完整覆盖，物理上不存在第 15 个正式 Method + Path 定义。
2. 修订内容
- Module B 头部统计由 25 修正为 24（P0: 17, P1: 6, P2: 1）；
- Module D 头部统计由 15 修正为 14（P0: 7, P1: 6, P2: 1）；
- 全局 P1 统计由 36 修正为 34；
- 全局总 API 统计由 91 修正为 89；
- P0 仍为 53 个，P2 仍为 2 个。
3. API 增删统计
- 新增 HTTP API： 0
- 删除已定义 HTTP API： 0
- 说明： 本项修订属于摘要计数纠正，不是删除两个已经存在的 API，因为这两个预想接口在正文中从未拥有过正式 Endpoint 定义。
总结说明
Contract V1.0.1 属于架构契约的一致性与自洽性修订：
- 不改变 PRD 业务范围，未引入任何新业务需求；
- 不新增、不删除任何真实定义的 HTTP API 端点（物理端点精确为 89 个）；
- 不修改 Database V2 任何数据表结构、字段类型或约束；
- 保证了后续 Phase 3 Issue 拆解、代码生成器对接与前后端开发的严密对齐。