83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# 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` 属于架构契约的一致性与自洽性修订：
|
||
1. **不改变 PRD 业务范围**，未引入任何新业务需求；
|
||
2. **不新增、不删除任何真实定义的 HTTP API 端点**（物理端点精确为 89 个）；
|
||
3. **不修改 Database V2 任何数据表结构、字段类型或约束**；
|
||
4. 保证了后续 Phase 3 Issue 拆解、代码生成器对接与前后端开发的严密对齐。
|