From 4873e5f555ecfe7d1d21d313007c2c8f6f65d6b6 Mon Sep 17 00:00:00 2001 From: wangzhibiao Date: Mon, 14 Sep 2026 10:07:00 +0800 Subject: [PATCH] =?UTF-8?q?docs(api):=20=E4=BF=AE=E8=AE=A2=E5=B9=B6?= =?UTF-8?q?=E5=86=BB=E7=BB=93API=20Contract=20V1.0.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-v2/00_readme.md | 18 ++-- docs/api-v2/02_module_a_base_resource_api.md | 2 +- ...3_module_b_plan_enrollment_schedule_api.md | 2 +- ..._module_d_score_learning_statistics_api.md | 2 +- docs/api-v2/06_dto_vo_catalog.md | 12 ++- docs/api-v2/12_contract_review_round1.md | 10 +-- docs/api-v2/13_contract_patch_v1.0.1.md | 82 +++++++++++++++++++ 7 files changed, 108 insertions(+), 20 deletions(-) create mode 100644 docs/api-v2/13_contract_patch_v1.0.1.md diff --git a/docs/api-v2/00_readme.md b/docs/api-v2/00_readme.md index 8d3f85e1c..ab6605703 100644 --- a/docs/api-v2/00_readme.md +++ b/docs/api-v2/00_readme.md @@ -107,15 +107,15 @@ flowchart LR ## 5. 一期规模与核心指标统计 (Review Round 1) -- **一期 API 总数：** 91 个 - - **P0 优先级 (核心闭环必须实现)：** 49 个 - - **P1 优先级 (辅助支撑能力)：** 40 个 +- **一期 API 总数：** 89 个 (以正文真实定义的 HTTP Method + Path 物理 Endpoint 为准) + - **P0 优先级 (核心闭环必须实现)：** 53 个 + - **P1 优先级 (辅助支撑能力)：** 34 个 - **P2 优先级 (依赖现场确认/延后)：** 2 个 - **模块分布统计：** - - **Module A (人员与基础资源)：** 38 个 (P0: 16, P1: 22, P2: 0) - - **Module B (开班计划与排课)：** 25 个 (P0: 17, P1: 7, P2: 1) + - **Module A (人员与基础资源)：** 38 个 (P0: 20, P1: 18, P2: 0) + - **Module B (开班计划与排课)：** 24 个 (P0: 17, P1: 6, P2: 1) - **Module C (住宿/门禁/考勤)：** 13 个 (P0: 9, P1: 4, P2: 0) - - **Module D (成绩/学习/统计/画像)：** 15 个 (P0: 7, P1: 7, P2: 1) + - **Module D (成绩/学习/统计/画像)：** 14 个 (P0: 7, P1: 6, P2: 1) - **外部 Adapter 接口数量：** 3 个 (`FaceAttendanceAdapter`, `DoorAccessAdapter`, `ExternalLearningAdapter`) - **核心业务 Command API 数量：** 24 个 (包含 P0 核心 Command API 20 个 [19 个核心业务流程 Command + 1 个 P0 计划管理更新: `PUT /train/plans/{planId}`], P1 辅助 Command 4 个) - **核心聚合 VO 数量：** 8 个 @@ -131,9 +131,9 @@ flowchart LR 为确保后续 Issue 拆分与开发聚焦于最小可用的完整培训业务闭环，特设立 **Phase 1 Minimal Contract** 视图。后续开发阶段将首先按此基线开展编码与单元测试： -### 6.1 P0 API 规模概览 (共 49 个) -- **Module A (16个)：** 教师列表/详情/增/改；学员列表/详情/录入；课程列表/详情/新增；教室列表/详情/新增；场地列表/详情/新增；宿舍列表/详情/新增/选项。 -- **Module B (17个)：** 计划列表/增/查/改/完成/工作台；本期课程列表/增；参训名单列表/单增/批量导入/详情；新增课次/修改课次/课次详情/冲突预检/完整课表；报到确认。 +### 6.1 P0 API 规模概览 (共 53 个) +- **Module A (20个)：** 教师列表/详情/增/改；学员列表/详情/录入；课程列表/详情/新增；教室列表/详情/新增；场地列表/详情/新增；宿舍列表/详情/新增/选项。 +- **Module B (17个)：** 计划列表/增/查/改/完成/工作台；本期课程列表/增；参训名单列表/单增/批量导入/详情；新增课次/修改课次/冲突预检/完整课表；报到确认。 - **Module C (9个)：** 批量预分配宿舍/单人调房/走读设置/住宿列表；门禁同步重试；签到/签退/人工修正/课次考勤名单。 - **Module D (7个)：** 成绩项目列表/权重配置；录入成绩；成绩台账大表/学员成绩单；学习记录接收；计划统计概览。 diff --git a/docs/api-v2/02_module_a_base_resource_api.md b/docs/api-v2/02_module_a_base_resource_api.md index d4b5b0468..51ebb2840 100644 --- a/docs/api-v2/02_module_a_base_resource_api.md +++ b/docs/api-v2/02_module_a_base_resource_api.md @@ -2,7 +2,7 @@ > **模块定位：** 支撑培训业务运转的基础主数据管理（Teacher, Student, Course, Resource, Classroom, Site, Board, Dormitory）。 > **设计特点：** 标准基础资料型对象，保留规范化的资源 CRUD 与关联管理接口，严格遵循敏感信息脱敏与业务校验。不引入审批流、多版本、复杂搜索等过度设计。 -> **优先级统计：** 共 38 个 API (P0: 16个, P1: 22个, P2: 0个)。 +> **优先级统计：** 共 38 个 API (P0: 20个, P1: 18个, P2: 0个)。 --- diff --git a/docs/api-v2/03_module_b_plan_enrollment_schedule_api.md b/docs/api-v2/03_module_b_plan_enrollment_schedule_api.md index 2f23e7ef4..679b1399c 100644 --- a/docs/api-v2/03_module_b_plan_enrollment_schedule_api.md +++ b/docs/api-v2/03_module_b_plan_enrollment_schedule_api.md @@ -2,7 +2,7 @@ > **模块定位：** 智慧培训业务核心流转引擎，贯穿“立项建班 → 课程配置 → 名单确定 → 课次编排与冲突检测 → 课程表生成 → 学员报到”。 > **设计原则：** 禁止退化为 5 张表的独立 CRUD，全面以“开班计划聚合工作台”与“业务 Command”为主线。 -> **优先级统计：** 共 25 个 API (P0: 17个, P1: 7个, P2: 1个)。 +> **优先级统计：** 共 24 个 API (P0: 17个, P1: 6个, P2: 1个)。 --- diff --git a/docs/api-v2/05_module_d_score_learning_statistics_api.md b/docs/api-v2/05_module_d_score_learning_statistics_api.md index fc7407f2e..a17eda266 100644 --- a/docs/api-v2/05_module_d_score_learning_statistics_api.md +++ b/docs/api-v2/05_module_d_score_learning_statistics_api.md @@ -2,7 +2,7 @@ > **模块定位：** 培训业务成效与多维量化评估模块，贯穿“成绩项目与权重配置 → 成绩录入导入台账 → 外部学习数据幂等接入 → 统计概览 → 学员简单画像”。 > **核心原则：** 统计一期不建持久化表、成绩权重总和强校验 100%、学习记录事件幂等防重、加权综合分作为核心结果、及格判定与画像标签保持现场弹性。 -> **优先级统计：** 共 15 个 API (P0: 7个, P1: 7个, P2: 1个)。 +> **优先级统计：** 共 14 个 API (P0: 7个, P1: 6个, P2: 1个)。 --- diff --git a/docs/api-v2/06_dto_vo_catalog.md b/docs/api-v2/06_dto_vo_catalog.md index 670837e9a..9ea6459b9 100644 --- a/docs/api-v2/06_dto_vo_catalog.md +++ b/docs/api-v2/06_dto_vo_catalog.md @@ -43,15 +43,21 @@ | `days` | List | 按日期分组的课次排期集合 | | `days[].date` | String | 日期 (yyyy-MM-dd) | | `days[].dayOfWeek` | Integer | 星期几 (1~7) | -| `days[].lessons` | List | 当日课次列表 | -| `lessons[].lessonId` | Long | 课次 ID | +| `lessons[].lessonId` | Long | 课次主键标识 | +| `lessons[].planCourseId` | Long | 本期计划课程关联标识 (回显表单必需) | | `lessons[].courseName` | String | 本期课程名称 | +| `lessons[].tId` | String | 授课教师工号/标识 (回显表单必需) | | `lessons[].teacherName` | String | 授课教师姓名 | | `lessons[].startTime` | Date | 课次开始时间 | | `lessons[].endTime` | Date | 课次结束时间 | | `lessons[].venueType` | Integer | 场地类型 (1教室 2实训场地) | -| `lessons[].venueName` | String | 教室名称或实训场地名称 | +| `lessons[].classRoomId` | Long | 普通教室物理标识 (venueType=1 时有效，回显表单必需) | +| `lessons[].classRoomName` | String | 普通教室名称 | +| `lessons[].siteId` | Long | 实训场地物理标识 (venueType=2 时有效，回显表单必需) | +| `lessons[].siteName` | String | 实训场地名称 | +| `lessons[].venueName` | String | 场地聚合展示名称 | | `lessons[].boardSn` | String | 关联电子班牌 SN 号（若有） | +| `lessons[].remark` | String | 课次备注 (回显表单必需) | --- diff --git a/docs/api-v2/12_contract_review_round1.md b/docs/api-v2/12_contract_review_round1.md index e6bb5fc20..7e8a26d88 100644 --- a/docs/api-v2/12_contract_review_round1.md +++ b/docs/api-v2/12_contract_review_round1.md @@ -29,7 +29,7 @@ | **画像模型弹性化** | `05`, `06`, `11` | 固定四维雷达图 + 固定标签枚举 | 【确认】简单画像数据；采用弹性指标集 `metrics` + 标签集 `tags`；具体计算维度与标签标记为待现场确认 | | **时效规则归位** | `03`, `08`, `10`, `11` | 6 项硬业务不变量 (含 Report Deadline) | **5 项跨表硬业务不变量** + **1 项报到生命周期策略 (Report Lifecycle Policy)**；支持 BLOCK / WARNING / OVERRIDE 三种模式 | | **外部调用解耦规范** | `04`, `07`, `08`, `09` | 误表达 afterCommit 本身为异步，提及 Outbox/MQ | **严禁引入 MQ / Kafka / Outbox【扩展】**；明确为事务提交后通过 afterCommit 触发后续调用，一期建议经轻量异步执行器或事务外调用，外部失败绝不回滚已提交事务 | -| **全面优先级划分** | `00`, `01`, `02`, `03`, `04`, `05`, `06` | 91 个 API 未分级 | 全面划分：**P0 (49个)**、**P1 (40个)**、**P2 (2个)**；新增 **Phase 1 Minimal Contract** 视图 | +| **全面优先级划分** | `00`, `01`, `02`, `03`, `04`, `05`, `06` | 91 个 API 未分级 (V1.0原统计) | 全面划分：**P0 (53个)**、**P1 (34个)**、**P2 (2个)**，物理总数 **89 个**；新增 **Phase 1 Minimal Contract** 视图 | | **业务Command口径统一** | `00`, `01`, `06` | 19个与20个数字模糊混淆 | 明确 **P0 核心 Command API 共 20 个**（包含 19 个核心业务流程 Command + 1 个 P0 计划管理更新 `PUT /train/plans/{planId}`），P1 辅助 Command 4 个 | | **消除数据库绝对承诺** | `11`, `12` | 100%无需修改数据库 | 修正为客观评估：当前评估预计无需改 DB，采用“预计无/可能有/需重新评估”，若引入新持久化业务对象重新进入 DB Change Review | @@ -48,12 +48,12 @@ ## 4. API 优先级分级 (P0 / P1 / P2) 统计裁定 -- **P0 API (共 49 个)：** 一期核心闭环必须实现，包含： - - Module A 基础主数据核心 CRUD (16个)； +- **P0 API (共 53 个)：** 一期核心闭环必须实现，包含： + - Module A 基础主数据核心 CRUD (20个)； - Module B 开班、本期课程、参训名单导入、排课、冲突预检、完整课表、学员报到 (17个)； - Module C 批量宿舍预分配、调房、走读、住宿查看、门禁重试、签到、签退、考勤修正、课次考勤 (9个)； - Module D 成绩配置、打分录入、成绩台账大表、学员成绩单、外部学习记录接入、综合统计概览 (7个)。 -- **P1 API (共 40 个)：** 一期辅助管理能力（如主档启停用、教学资源独立管理、班牌注册管理、房态看板、门禁流水、人工补录考勤、成绩Excel导入、学习记录流水、学员训练详情、学员画像等）。 +- **P1 API (共 34 个)：** 一期辅助管理能力（如主档启停用、教学资源独立管理、班牌注册管理、房态看板、门禁流水、人工补录考勤、成绩Excel导入、学习记录流水、学员训练详情、学员画像等）。 - **P2 API (共 2 个)：** 依赖现场确认或面向学员端的次要门户接口（`GET /train/student/my-training` 学员端门户、`GET /train/plans/{id}/statistics/score-distribution` 成绩区间下钻分析）。 --- @@ -143,7 +143,7 @@ UC-29 结束培训计划 (P0) 1. `afterCommit` 技术语义已全面纠正，杜绝“afterCommit本身是异步”的误读，明确外部失败不回滚已提交本地事务； 2. 彻底删除了“100%不改DB”绝对化承诺，建立了客观科学的三态评估与变更控制原则； 3. 统计口径完全统一并消除歧义： - - API 总数：**91 个** (P0: 49, P1: 40, P2: 2)； + - API 总数：**89 个** (P0: 53, P1: 34, P2: 2)； - 核心业务 Command API：共 **24 个** (P0 核心 Command API 20 个 [包含 19 个核心业务流程 Command + 1 个 P0 计划管理更新 `PUT /train/plans/{planId}`]，P1 辅助 Command 4 个)； - P0 业务编排 Service：**10 个 P0 Application Service**； 4. 领域核心标识 `enrollment_id`, `plan_course_id`, `lesson_id` 稳固落实，5 大跨表硬 Invariant 与 1 项 Lifecycle Policy 界限分明； diff --git a/docs/api-v2/13_contract_patch_v1.0.1.md b/docs/api-v2/13_contract_patch_v1.0.1.md new file mode 100644 index 000000000..088f7c7db --- /dev/null +++ b/docs/api-v2/13_contract_patch_v1.0.1.md @@ -0,0 +1,82 @@ +# 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 拆解、代码生成器对接与前后端开发的严密对齐。