blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f0fcb3ab63e05eeee9107085104f47b546c5a5ab
railwaysystem/docs/api-v2/12_contract_review_round1.md
T

11 KiB
Raw Blame History

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 用例构成闭环：

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-01V-07, V-10V-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 最终冻结)。

Reference in new issue View Git Blame Copy Permalink