docs(api): 修订并冻结API Contract V1.0.1
This commit is contained in:
wangzhibiao committed
1 parent
67543e0422
commit
4873e5f555
7 files changed
+108
-20
No files matched your search
@@ -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个)：** 成绩项目列表/权重配置；录入成绩；成绩台账大表/学员成绩单；学习记录接收；计划统计概览。
|
||||
|
||||
|
||||
@@ -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个)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> **模块定位：** 智慧培训业务核心流转引擎，贯穿“立项建班 → 课程配置 → 名单确定 → 课次编排与冲突检测 → 课程表生成 → 学员报到”。
|
||||
> **设计原则：** 禁止退化为 5 张表的独立 CRUD，全面以“开班计划聚合工作台”与“业务 Command”为主线。
|
||||
> **优先级统计：** 共 25 个 API (P0: 17个, P1: 7个, P2: 1个)。
|
||||
> **优先级统计：** 共 24 个 API (P0: 17个, P1: 6个, P2: 1个)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> **模块定位：** 培训业务成效与多维量化评估模块，贯穿“成绩项目与权重配置 → 成绩录入导入台账 → 外部学习数据幂等接入 → 统计概览 → 学员简单画像”。
|
||||
> **核心原则：** 统计一期不建持久化表、成绩权重总和强校验 100%、学习记录事件幂等防重、加权综合分作为核心结果、及格判定与画像标签保持现场弹性。
|
||||
> **优先级统计：** 共 15 个 API (P0: 7个, P1: 7个, P2: 1个)。
|
||||
> **优先级统计：** 共 14 个 API (P0: 7个, P1: 6个, P2: 1个)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -43,15 +43,21 @@
|
||||
| `days` | List<TimetableDayVO> | 按日期分组的课次排期集合 |
|
||||
| `days[].date` | String | 日期 (yyyy-MM-dd) |
|
||||
| `days[].dayOfWeek` | Integer | 星期几 (1~7) |
|
||||
| `days[].lessons` | List<TimetableLessonItemVO> | 当日课次列表 |
|
||||
| `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 | 课次备注 (回显表单必需) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 界限分明；
|
||||
|
||||
@@ -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 拆解、代码生成器对接与前后端开发的严密对齐。
|
||||
Reference in new issue
Block a user