# RailwaySystem 现场验证问题映射与 API 应对策略 (Open Questions)

> **基准依据：** 严格对齐 PRD V1.0 第 28 章冻结的 **V-01 ~ V-14 现场验证清单**。
> **核心原则：** 不私自发明不相关的额外问题；对每个问题明确当前默认策略、影响 API、影响 DTO/VO 以及现场确认后的数据库评估。
> **当前评估：** 大多数 V-01~V-14 的不同答案可由 API / Service / DTO / Adapter 策略吸收，预计无需修改 Database V2。但若现场确认引入新的持久化业务对象、一期范围变化、新的硬件持久化要求或审计要求，必须重新进入 Database Change Review。

---

## 1. V-01 ~ V-14 映射与全方位应对矩阵

| 编号 | 现场待确认事项 | 当前默认策略 | 影响 API | 影响 DTO/VO | 现场确认后DB影响 | 应对与隔离策略 |
|:---|:---|:---|:---|:---|:---:|:---|
| **V-01** | 学员最终真实来源系统及数据字段 | 默认支持工号、姓名、性别、身份证、单位、电话、邮箱 7 项核心字段 | `POST /train/student`, `POST /train/plans/{id}/enrollments` | `StudentCreateDTO`, `EnrollmentAddDTO` | **预计无** | 现有 `train_student` 预留 `source_type` 与 `remark` 字段，常规业务扩展字段可通过 `remark` 承载。若需引入复杂组织机构多层级模型，则需重新评估。 |
| **V-02** | 一期实际如何导入内部人员 | 默认提供通用 Excel 批量导入模板，并支持自动建档开关 | `POST /train/plans/{id}/enrollments/batch` | `EnrollmentBatchDTO` | **预计无** | 现场若提供直连只读视图或内部平台接口，仅需在 `EnrollmentAppService` 中切换数据提取实现类。 |
| **V-03** | 宿舍是否分到具体床位还是只到房间 | 默认“**房间必填，床号可选填**”，按 1~N 顺序编排可选床号 | `POST /train/plans/{id}/accommodations/preallocate` | `AccommodationPreallocateDTO`, `AccommodationAdjustDTO` | **预计无** | `train_accommodation.bed_no` 字段已允许为 NULL；若只要房间，传空即可；若要床位，直接传值。 |
| **V-04** | 请假如何影响考勤统计 | 默认请假为独立考勤状态 (`status=5`)，计算出勤率时分母扣减请假课次 | `GET /train/plans/{id}/statistics/overview` | `PlanStatisticsVO`, `AttendanceSummaryVO` | **预计无** | 纯内存/SQL统计算法调整，`StatisticsAppService` 封装公式，对外数据结构完全一致。 |
| **V-05** | 迟到/早退的具体判定规则与宽限期 | 默认上课前30分至开课后10分为正常，超过10分判定迟到，教师可人工修正 | `POST /train/attendance/sign-in`, `PUT /attendance/{id}` | `AttendanceSignInDTO`, `AttendanceAdjustDTO` | **预计无** | 判定阈值通过若依系统参数 (`sys_config`) 动态配置，API 与数据库表结构不受影响。 |
| **V-06** | 正式成绩考核项目有哪些 | 采用开班级动态配置模型，由培训班自由定义项目名称、类型及权重，总权重等于100% | `POST /train/plans/{id}/score-items` | `ScoreItemBatchConfigDTO`, `PlanScoreMatrixVO` | **预计无** | `train_score_item` 支持任意门数与类型的考核项，彻底杜绝固定科目列硬编码。 |
| **V-07** | 是否存在及格线 | 默认只输出加权折算综合成绩 `weightedTotalScore`，及格判定 `passStatus` 作为可选入参动态比较 | `GET /train/plans/{id}/scores/matrix` | `PlanScoreMatrixVO` | **预计无** | 数据库不存及格状态；若现场需要固定及格线，仅在 VO 计算时与阈值（如60分）对比输出。 |
| **V-08** | 培训结束与“合格/结业”是否区分 | 默认简化为：培训时间结束即结训，有效参训学员全部更新为“已完成”，保留成绩 | `POST /train/plans/{id}/complete` | `PlanWorkbenchVO` | **可能有** | 当前状态在 `train_enrollment.enrollment_status = 4` 表达。若现场提出多级结业审批或不合格复议归档，可能需要新增审批流相关状态字段。 |
| **V-09** | 是否需要证书管理 | 明确一期不开发证书模块，API 契约不设证书接口 | 无 | 无 | **需重新评估** | 一期删除此功能；二期若现场确认需要证书持久化（如电子证书编号、发证日期），必须重新评估并引入 `train_certificate` 表。 |
| **V-10** | 学员画像最终指标与标签集 | 默认采用通用指标集 (`metrics`) + 标签集 (`tags`) 弹性结构，预置出勤、理论、实操、时长4项指标 | `GET /train/enrollments/{id}/portrait` | `StudentPortraitVO` | **预计无** | `train_student_portrait` 的文本字段与数值字段具备承载通用指标与标签能力。 |
| **V-11** | 电子班牌真实硬件协议 | 采用标准 RESTful/JSON 契约，一期使用 Mock 适配器驱动 | 适配器内部通讯 | `FaceAttendanceAdapter` | **预计无** | 硬件差异隔离在 Adapter 防腐层内，现场确定品牌型号后仅需编写厂商驱动类。 |
| **V-12** | 智能门锁真实硬件协议 | 采用基于门锁 SN 与人脸凭证的标准指令，一期使用 Mock 适配器驱动 | 适配器内部通讯 | `DoorAccessAdapter` | **预计无** | 门锁 SDK 集成仅影响 `DoorAccessAdapter` 实现类，业务主表只记录下发状态与错误日志。 |
| **V-13** | VR/3D/阅览系统真实推送协议 | 采用标准化极简 HTTP POST 接口接入：`source_system`, `source_event_id`, `study_seconds` | `POST /train/study-records/receive` | `StudyRecordReceiveDTO` | **预计无** | 契约已覆盖外部学习打卡核心要素，第三方系统无论如何定制均可映射到该通用 DTO。 |
| **V-14** | 对其他系统需要开放哪些数据查询接口 | 提供只读查询接口（学员课表、成绩单、训练详情），通过若依 Token 鉴权与白名单过滤 | 现有 Resource Query API | `PlanTimetableVO`, `StudentScoreReportVO` | **需重新评估** | 常规只读查询直接复用现有接口；若现场提出第三方系统专用的推送回调队列或独立数据交换审计日志，需重新评估。 |

---

## 2. 结论与架构策略

1. **当前评估与变更控制：** 当前评估表明大多数 V-01~V-14 的不同答案可由 API / Service / DTO / Adapter 策略吸收，预计无需修改 Database V2。但若现场确认引入新的持久化业务对象、一期范围变化、新的硬件持久化要求或审计要求，必须重新进入 Database Change Review；
2. **契约弹性保障：** 成绩台账矩阵解耦了及格判定，学员画像解耦了雷达图与具体标签，报到逾期解耦了阻断与放行策略，架构具备良好的适配与应对能力。