新增住宿：对齐住宿与门禁授权领域模型

2026-09-15 17:27:38 +08:00
1 parent cc911186aa
commit 5de1d2a142
@@ -137,3 +137,35 @@
  2. **`train_dorm_auth`**：Kingbase 物理表已在 V2 中升级为以 `accommodation_id` 为外键的门禁授权结构，但 Java 实体类 `TrainDormAuth.java` 与 XML Mapper 依然停留在 V1 旧结构（持有 `student_id`, `plan_id`, `dorm_id`, `bed_no`）。
 - **执行原则**：
  在进入 R.3B 真正编写 DMS Adapter 之前，**必须先在 Wave 0 完成本地住宿与门禁授权领域模型对齐**！严禁让外部 DMS 集成适配器直接架设在当前存在严重漂移的本地模型之上。
+
+### 5.2 Wave 0 Implementation Result (本地模型对齐实施完成)
+- **完成状态**：已全面对齐并消除结构漂移。
+- **实体层**：
+  - 新增 `TrainAccommodation.java`，严格对应 Kingbase V2 生产物理表（`accommodation_id`, `enrollment_id`, `dorm_id`, `bed_no`, `assigned_time`, `accommodation_status`, 审计列）。
+  - 重构 `TrainDormAuth.java`，外键核心对齐 `accommodation_id`，持久化字段剔除 V1 遗留字段（`student_id`, `plan_id`, `dorm_id`, `bed_no`, `createUser`），保留为非持久化兼容视图字段以保障只读兼容。
+- **Mapper/SQL**：
+  - 新增 `TrainAccommodationMapper.java` / `TrainAccommodationMapper.xml`，所有字段显式指定，严禁 `SELECT *`。
+  - 重构 `TrainDormAuthMapper.xml`，INSERT/UPDATE 语句彻底清理 V1 废弃字段写入，通过 LEFT JOIN 视图提供兼容字段。
+- **业务服务**：
+  - 新增 `ITrainAccommodationService` / `TrainAccommodationServiceImpl`，落地“同一时刻最多1个有效住宿安排”（Duplicate Active Accommodation Guard）、宿舍核定容量边界检查（Capacity Boundary Guard）与换房原子流转（Transfer）。
+  - 升级 `TrainDormAuthServiceImpl`，严格执行“Enrollment -> Accommodation -> Door Authorization”业务单向依赖，禁止绕过住宿事实直接授权。
+
+### 5.3 Wave 0.1 Accommodation History & 006 Migration (基数模型升级与迁移方案)
+- **基数语义冻结**：
+  - `Enrollment 1:N Accommodation History`（一个报名记录可有多条历史住宿记录，调房换房产生历史轨迹）
+  - `Enrollment 1:0..1 Active Accommodation`（同一时间一个报名记录最多只能有 1 条有效住宿记录，`accommodation_status IN (0, 1)`）
+  - `Accommodation 1:0..1 DoorAuthorization`（门禁授权强依赖具体的某一次住宿记录）
+  - `TIME_RANGE_SUPPORT = LIMITED`（当前 Kingbase 物理表仅包含 `assigned_time`，无 `start_time`/`end_time`，时间窗口支持为有限支持）
+- **006 迁移脚本方案 (`006_accommodation_history_constraint.sql`)**：
+  - 脚本路径：`RuoYi-Vue/sql/system/kingbase/006_accommodation_history_constraint.sql`
+  - 安全编号：`006`（001-003 为基线，004-005 已被 R.2 分支占用）
+  - 前置检查：Fail-fast，若发现同一 `enrollment_id` 存在多条 active（`accommodation_status IN (0, 1)`）则 `RAISE EXCEPTION` 阻止迁移
+  - 安全 DROP：仅在原约束 `uq_accommodation_enroll` 确认为 `UNIQUE (enrollment_id)` 时安全移除
+  - 局部唯一索引：创建 `uq_accommodation_enroll_active` 并在 `WHERE accommodation_status IN (0, 1)` 生效
+  - 幂等性防护：重复执行不会报错或破坏表结构
+  - 生产执行纪律：本迁移脚本仅完成工程资产化与隔离测试，**严禁在生产数据库执行**
+- **自动化测试**：
+  - `AccommodationHistoryMigrationContractTest`（契约测试：SQL 语法、前置检查、条件 DROP、局部索引及幂等性）
+  - `AccommodationServiceTest`（10 项测试，包含调房历史与并发唯一性）
+  - `DormAuthAlignmentTest`（7 项测试，包含依赖住宿与换房级联）
+  - 全量测试套件 174 项全部 PASS（0 failures, 0 errors）。
@@ -101,3 +101,26 @@
 1. **第一步**：重构修复 Java 实体类 `TrainDormAuth.java`，彻底移除已弃用的 `student_id`, `plan_id`, `dorm_id` 字段，使其与已存在的 Kingbase 物理表字段完全对齐。
 2. **第二步**：创建 `train_external_resource_mapping` 与 `train_external_operation` 迁移脚本（遵循系统标准 Liquibase/Flyway 规范）。
 3. **第三步**：通过 Spring Data / MyBatis-Plus 完成三表关联映射。
+
+### 4.1 Wave 0 Implementation Result (第一步已正式交付)
+- **已完成事项**：
+  1. 重构并修复 `TrainDormAuth.java`，彻底废弃了向 `train_dorm_auth` 写入 `student_id`, `plan_id`, `dorm_id`, `bed_no`, `create_user` 的历史假设。
+  2. 补齐 `TrainAccommodation.java`、`TrainAccommodationMapper.java`、`TrainAccommodationMapper.xml`、`ITrainAccommodationService` 以及 `TrainAccommodationServiceImpl`，完全对齐 V2 生产物理结构。
+  3. 严格禁止在 Wave 0 中引入任何 DMS 物理字段（如 `lock_id`, `place_id`, `operation_id`），保持 Vendor-Neutral 纯净业务边界。
+  4. 生产 Migration 检查：`MIGRATION_REQUIRED = NO`，生产数据库零写入、零变更。
+
+### 4.2 Wave 0.1 Accommodation History Migration (006 迁移方案与基数冻结)
+- **领域基数与物理约束演进**：
+  - **历史模型**：`Enrollment 1:N Accommodation History`，允许学员由于调房等产生多条住宿历史。
+  - **唯一性收敛**：`Enrollment 1:0..1 Active Accommodation`，原全局唯一约束 `UNIQUE(enrollment_id)` 阻碍了历史留痕，演进为针对有效状态（`accommodation_status IN (0, 1)`）的局部唯一索引。
+  - **授权关联**：`Accommodation 1:0..1 DoorAuthorization`，门禁授权强引用住宿实体。
+  - **时间范围特性**：`TIME_RANGE_SUPPORT = LIMITED`，当前物理表仅有 `assigned_time`，未扩展起止时间列。
+- **006 Migration 脚本设计与验证**：
+  - 文件路径：`RuoYi-Vue/sql/system/kingbase/006_accommodation_history_constraint.sql`
+  - 安全编号：`006`（避免与 R.2 占用的 004/005 冲突）。
+  - 执行安全机制：
+    1. 前置重复数据检查：存在并发违规 active 记录时直接 `RAISE EXCEPTION` 阻断。
+    2. 严格条件 DROP：仅当原约束 `uq_accommodation_enroll` 确认为 `UNIQUE (enrollment_id)` 时执行 drop。
+    3. 创建局部唯一索引：`CREATE UNIQUE INDEX IF NOT EXISTS uq_accommodation_enroll_active ON train_accommodation (enrollment_id) WHERE accommodation_status IN (0, 1);`
+    4. 幂等防护：重复执行幂等安全。
+  - 生产执行纪律：本脚本已在单元/契约测试中完成全量静态与逻辑校验，**禁止在生产库执行**。
@@ -139,3 +139,29 @@ flowchart TD
 | **Wave 2: DMS Adapter & Mock Tests** | 协议适配器、TokenManager、轮询调度器、22项单测 | 外部集成层 | 5 人天 |
 | **Wave 3: Orchestration, UI & Sandbox** | 业务编排服务、前端界面、现场沙箱实物 E2E 联调 | 业务层/前端/现场 | 5~6 人天 |
 | **总计** | **R.3 门禁集成端到端正式交付上线** | **全栈闭环** | **约 15~16 人天** |
+
+### 3.1 Wave 0 Implementation Result (交付与验收验证)
+- **阶段目标**：Local Accommodation & Door Authorization Domain Alignment
+- **执行状态**：已完成 (Completed)
+- **交付清单**：
+  1. `TrainAccommodation.java`、`TrainAccommodationMapper.java`、`TrainAccommodationMapper.xml`
+  2. `ITrainAccommodationService.java`、`TrainAccommodationServiceImpl.java`
+  3. `TrainAccommodationController.java` (最小必要 Admin REST API)
+  4. `TrainDormAuth.java`、`TrainDormAuthMapper.java`、`TrainDormAuthMapper.xml`、`TrainDormAuthServiceImpl.java`、`TrainDormAuthController.java` (V2 Schema 对齐与清理)
+  5. 自动化测试套件：`AccommodationServiceTest`、`DormAuthAlignmentTest`、`AccommodationAndAuthApiControllerContractTest`。
+
+### 3.2 Wave 0.1 Implementation Result (基数模型升级与 006 迁移交付)
+- **阶段目标**：Accommodation History Migration & Final Checkpoint
+- **模型基数关系**：
+  - `Enrollment 1:N Accommodation History`
+  - `Enrollment 1:0..1 Active Accommodation` (`accommodation_status IN (0, 1)`)
+  - `Accommodation 1:0..1 DoorAuthorization`
+  - `TIME_RANGE_SUPPORT = LIMITED`
+- **新增交付物**：
+  1. `RuoYi-Vue/sql/system/kingbase/006_accommodation_history_constraint.sql`（安全编号 006、前置检查、条件 DROP、局部唯一索引、幂等执行；生产库未执行）
+  2. `RuoYi-Vue/ruoyi-admin/src/test/java/com/ruoyi/web/controller/train/AccommodationHistoryMigrationContractTest.java`（迁移脚本规范与语法契约测试）
+  3. 历史查询与调房并发唯一性测试（`selectAccommodationHistoryByEnrollmentId`、`transferAccommodation` 级联授权废弃）
+- **全量回归验证**：
+  - `ruoyi-train`: 153 tests
+  - `ruoyi-admin`: 21 tests
+  - 总计：174 tests, Failures: 0, Errors: 0, Skipped: 0，全量通过。
@@ -106,3 +106,25 @@
   - 配置与环境变量绑定；`DmsTokenManager` 单飞排他锁并发控制；细分 HTTP 客户端；在线密码/卡片适配器；10 秒轮询调度器；WireMock 22 项单测全覆盖。
 4. **Wave 3: Business Orchestration & UI & Sandbox (业务编排、界面与现场验收，5~6天)**：
   - 报到联动授权下发；“先发新房后撤旧房”换房补偿；退训/结训撤权；管理端门禁综合视图；学员端 30 秒倒计时密码受控查看；现场实验台沙箱 E2E 闭环验收。
+
+### 6.1 Wave 0 Implementation Result (本地领域模型闭环)
+- **基线与状态**：
+  - 成功消除数据库 V2 模型与 Java 代码之间的全部结构漂移。
+  - 严格保持 0 DMS 耦合：无 DmsClient、无 TokenManager、无外部调用、无假设备成功。
+  - 保持 Kingbase 生产库只读，零 Migration（`MIGRATION_REQUIRED = NO`）。
+  - 交付本地领域模型：`TrainAccommodation` 与升级后的 `TrainDormAuth`。
+
+### 6.2 Wave 0.1 Accommodation History & Final Checkpoint Decision (基数模型升级与终态)
+- **核心基数关系冻结**：
+  - `Enrollment 1:N Accommodation History`：允许学员产生多次历史住宿记录（调房/换房留痕）。
+  - `Enrollment 1:0..1 Active Accommodation`：同一时刻最多一条有效住宿（`accommodation_status IN (0, 1)`）。
+  - `Accommodation 1:0..1 DoorAuthorization`：门禁授权强引用住宿实体。
+  - `TIME_RANGE_SUPPORT = LIMITED`：当前 Kingbase 物理表仅有 `assigned_time`，无 `start_time` / `end_time` 列，时间窗口支持为有限支持。
+- **006 Migration 方案设计**：
+  - 脚本路径：`RuoYi-Vue/sql/system/kingbase/006_accommodation_history_constraint.sql`。
+  - 安全序号：`006`（001-003 为基线，004-005 已被 R.2 分支占用）。
+  - 迁移安全护栏：前置重复 active 检查抛异常、仅在定义匹配时安全 DROP `uq_accommodation_enroll`、创建 `uq_accommodation_enroll_active` 局部唯一索引（`WHERE accommodation_status IN (0, 1)`）、全流程幂等。
+  - 生产执行纪律：**禁止在生产库执行 006 迁移脚本**，本 Wave 仅作资产与契约验证储备。
+- **质量与构建验收**：
+  - 单元与契约测试总数：174 项，全部 PASS（0 failures, 0 errors）。
+  - Maven `clean test` 与 `clean package` 均顺利构建成功。