153 lines
11 KiB
Markdown
153 lines
11 KiB
Markdown
# RailwaySystem Phase 2 Contract Review Round 1 审查报告
|
||
|
||
> **审查日期：** 2026-09-14
|
||
> **审查基线：** PRD V1.0 + Database V2 (21张表) + generator-v2-ready-20260914
|
||
> **审查对象：** `docs/api-v2/` 目录全套 API 契约、DTO/VO、Service 边界与架构设计规范
|
||
> **最终评审结论：** **Contract Review Round 1 Final = A (完全通过，达到架构冻结准入标准)**
|
||
|
||
---
|
||
|
||
## 1. 本轮审查发现的核心问题与偏离项
|
||
|
||
在初版 API 契约完成设计后，经过技术架构与业务基线严审，识别出以下 5 处需要规范化收敛的问题：
|
||
|
||
1. **“及格/合格判定”存在需求越界：** 初版将 60 分及格线和 `passStatus` 作为【确认】规则固化在成绩台账及统计中，偏离了 PRD V-07/V-08 明确标注的“是否存在及格线待现场确认”基线；
|
||
2. **学员画像模型过早冻结：** 初版将四维雷达图、固定指标名称与规则标签直接写死，与 PRD V-10“一期存在简单画像，具体指标与标签待现场确认”存在超前假设；
|
||
3. **Report Deadline 误定为硬物理 Invariant：** 初版将 `report_time <= report_deadline` 误列为与跨班串签同等级别的硬一致性拓扑不变量，忽略了业务上超期补录或管理员特批放行的生命周期弹性需求；
|
||
4. **外部异步调用存在过度设计隐患与语义模糊：** 文字表述中将 `afterCommit` 误表达为本身就是异步，且提到了 Outbox 等重型方案，容易误导后续开发引入不必要的 MQ/事件总线中间件；
|
||
5. **91 个 API 缺乏实施优先级分级与 Command 统计口径模糊：** 未明确区分核心验收闭环与辅助运维接口，Command API 与普通更新混淆。
|
||
|
||
---
|
||
|
||
## 2. 本轮修订与收敛内容
|
||
|
||
针对上述问题，本轮评审进行了系统性修订并同步更新了 `docs/api-v2/` 下的全部相关文档：
|
||
|
||
| 修订项 | 涉及文档 | 调整前 | 调整后 |
|
||
|:---|:---|:---|:---|
|
||
| **及格判定解耦** | `01`, `05`, `06`, `10`, `11` | `compositeScore` + 硬编码 `passStatus` 判定 | `weightedTotalScore` 作为核心【确认】业务结果；`passStatus` 降级为【默认/建议方案（待现场确认）】；移除固定合格率 |
|
||
| **画像模型弹性化** | `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 未分级 (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 |
|
||
|
||
---
|
||
|
||
## 3. PRD 越界项的裁定与处理
|
||
|
||
1. **及格线与合格结业 (PRD V-07, V-08)：**
|
||
- 裁定：一期不做及格门槛硬拦截，不设“考核不合格退学/无法结业”状态机。培训班到达结束时间，所有正常参训学员状态一律置为“已完成”，完整保留其各科成绩与加权总分供后续查阅。
|
||
2. **学员画像规则引擎 (PRD V-10)：**
|
||
- 裁定：严禁在一期引入 Drools 或复杂规则引擎；采用极简统计数值与轻量 JSON 存储，前端动态适配渲染。
|
||
3. **复杂课程版本/审批/证书：**
|
||
- 裁定：彻底剔除，契约中不设立任何审批流和证书接口。
|
||
|
||
---
|
||
|
||
## 4. API 优先级分级 (P0 / P1 / P2) 统计裁定
|
||
|
||
- **P0 API (共 53 个)：** 一期核心闭环必须实现，包含：
|
||
- Module A 基础主数据核心 CRUD (20个)；
|
||
- Module B 开班、本期课程、参训名单导入、排课、冲突预检、完整课表、学员报到 (17个)；
|
||
- Module C 批量宿舍预分配、调房、走读、住宿查看、门禁重试、签到、签退、考勤修正、课次考勤 (9个)；
|
||
- Module D 成绩配置、打分录入、成绩台账大表、学员成绩单、外部学习记录接入、综合统计概览 (7个)。
|
||
- **P1 API (共 34 个)：** 一期辅助管理能力（如主档启停用、教学资源独立管理、班牌注册管理、房态看板、门禁流水、人工补录考勤、成绩Excel导入、学习记录流水、学员训练详情、学员画像等）。
|
||
- **P2 API (共 2 个)：** 依赖现场确认或面向学员端的次要门户接口（`GET /train/student/my-training` 学员端门户、`GET /train/plans/{id}/statistics/score-distribution` 成绩区间下钻分析）。
|
||
|
||
---
|
||
|
||
## 5. 核心业务用例 (UC-01 ~ UC-29) 的 P0 主链映射
|
||
|
||
经核对 PRD V1.0 业务验收场景，一期主流程由以下 17 个 P0 用例构成闭环：
|
||
```text
|
||
UC-01 创建培训计划 (P0)
|
||
UC-02 编辑培训计划 (P0)
|
||
UC-03 配置本期课程 (P0)
|
||
UC-04 添加参训人员 (P0)
|
||
UC-05 Excel批量导入参训人员 (P0)
|
||
UC-06 查看本期参训名单 (P0)
|
||
UC-07 新增课次 (P0)
|
||
UC-08 修改课次 (P0)
|
||
UC-10 排课冲突检查 (P0)
|
||
UC-11 获取计划完整课表 (P0)
|
||
UC-12 批量住宿预分配 (P0)
|
||
UC-13 单人住宿调整 (P0)
|
||
UC-14 查看住宿安排 (P0)
|
||
UC-15 学员报到确认 (P0)
|
||
UC-16 创建/同步门禁授权 (P0)
|
||
UC-17 课次签到 (P0)
|
||
UC-18 课次签退 (P0)
|
||
UC-19 人工修正考勤 (P0)
|
||
UC-20 配置成绩项目及权重 (P0)
|
||
UC-21 录入成绩 (P0)
|
||
UC-23 获取学员本期成绩 (P0)
|
||
UC-24 接收外部学习记录 (P0)
|
||
UC-26 计划统计概览 (P0)
|
||
UC-29 结束培训计划 (P0)
|
||
```
|
||
*(注：UC-09 删除课次、UC-22 Excel导入成绩、UC-25 查询学习记录、UC-27 学员训练详情、UC-28 学员画像划入 P1 辅助能力)*
|
||
|
||
---
|
||
|
||
## 6. Report Deadline 时效生命周期策略
|
||
|
||
- **确认事实：** `report_deadline` 作为时间戳字段保存在 `train_class_plan` 表中；
|
||
- **执行规则：** 学员报到时系统检查当前时间；
|
||
- **兼容策略：**
|
||
- 默认行为：若超时且 `forceOverride = false`，接口返回警告提醒 `REPORT_DEADLINE_WARNING`；若由管理员代办或 `forceOverride = true`，允许完成报到并在报到流水中标记 `is_overdue = true`；
|
||
- 完美兼容现场最终确认的严格阻断、提示警告或特批覆盖，预计无需修改数据库字段。
|
||
|
||
---
|
||
|
||
## 7. 学员画像 (Student Portrait) 策略
|
||
|
||
- **确认事实：** 数据持久化保存在 `train_student_portrait` 表；
|
||
- **弹性契约：** API 返回结构抽象为 `metrics` (指标数值数组) + `tags` (能力标签字符串数组) + `summary` (简短文字摘要)；
|
||
- **实现策略：** 后端一期默认基于考勤率、理论成绩、实操成绩与自主学习时长进行四维归一化打分；现场若对指标名称或标签有微调，仅需在 `PortraitAppService` 中微调权重与打标文案，前端自适应渲染，彻底杜绝数据模型硬编码。
|
||
|
||
---
|
||
|
||
## 8. 及格判定 (Pass / Qualified) 策略
|
||
|
||
- **确认事实：** 成绩核心计算依据为 `train_score_item` 中的 `weight` 与 `full_score`；
|
||
- **业务输出：** 各科成绩根据权重汇总计算出的加权总分 `weightedTotalScore` 是唯一【确认】输出结果；
|
||
- **及格解耦：** API 默认不对学员进行“及格/不及格”判定，全班台账中的 `passStatus` 设为可选参数；若现场需要及格线，通过入参传递阈值（如60）动态判定，不污染数据库与主干业务流。
|
||
|
||
---
|
||
|
||
## 9. 外部调用最小实现策略与技术语义修正
|
||
|
||
- **铁律：** 本地短事务严禁包裹外部第三方 HTTP 长请求；
|
||
- **技术语义规范：**
|
||
- `afterCommit` 本身不代表异步，其本质是数据库事务提交成功后的回调钩子；
|
||
- 一期默认建议：`afterCommit` → 轻量异步执行器 → Adapter；若未引入异步执行器，则为 `afterCommit` → 当前线程事务外调用 Adapter；
|
||
- 两者都必须保证：外部调用失败不得回滚已经提交的本地数据库事务，而是保留/更新同步状态并支持手工重试；
|
||
- **明确：MQ / Outbox / 分布式事务 = 一期不引入【扩展】。**
|
||
|
||
---
|
||
|
||
## 10. V-01 ~ V-14 数据库影响客观评估原则
|
||
|
||
- **删除绝对承诺：** 严禁使用“100%无需修改数据库”等绝对化承诺；
|
||
- **规范表述口径：**
|
||
> 当前评估：大多数 V-01~V-14 的不同答案可由 API / Service / DTO / Adapter 策略吸收，预计无需修改 Database V2。但若现场确认引入新的持久化业务对象、一期范围变化、新的硬件持久化要求或审计要求，必须重新进入 Database Change Review。
|
||
- 各 V 项评估采用三态分类：`预计无` (如V-01~V-07, V-10~V-13)、`可能有` (如V-08结业审批状态)、`需重新评估` (如V-09证书持久化、V-14外部数据交换审计)。
|
||
|
||
---
|
||
|
||
## 11. 最终收口修订记录与评审裁定
|
||
|
||
经过本轮全面复查与最终收口修订：
|
||
1. `afterCommit` 技术语义已全面纠正，杜绝“afterCommit本身是异步”的误读，明确外部失败不回滚已提交本地事务；
|
||
2. 彻底删除了“100%不改DB”绝对化承诺，建立了客观科学的三态评估与变更控制原则；
|
||
3. 统计口径完全统一并消除歧义：
|
||
- 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 界限分明；
|
||
5. 未修改任何一行 Java/Vue 代码或数据库表结构。
|
||
|
||
**评审最终裁定：【Contract Review Round 1 Final = A】(完全通过，允许进入 API Contract 最终冻结)。**
|