railwaysystem/docs/development/dms-r3/12_implementation_task_breakdown.md

# 12 R.3B 实施阶段 WBS 任务拆分与四阶段推进路线图 (Implementation Task Breakdown)

> **实施基准**：严格遵循本 R.3A 审计与设计冻结规范。
> **核心演进策略**：**严禁在模型漂移之上直接开发适配器**。
> 实施路线严格划分为 **四个推进阶段 (Wave 0 ~ Wave 3)**，确保本地领域事实先就绪，再推进外部协议适配与端到端编排。

---

## 1. 四阶段演进路线图 (Four-Wave Roadmap)

```mermaid
flowchart TD
    subgraph Wave0["Wave 0: 本地领域模型对齐 (Local Domain Alignment)"]
        W0_1["TrainAccommodation Java 实体/DTO/VO 构建"]
        W0_2["TrainAccommodationMapper & 业务 Service 实现"]
        W0_3["TrainDormAuth Java 实体与 Mapper V2 升级清洗"]
        W0_4["确立 Accommodation 与 DoorAuthorization 明确职责边界"]
    end

    subgraph Wave1["Wave 1: 外部映射与操作持久化 (External Mapping & Operation Persistence)"]
        W1_1["train_external_resource_mapping 物理表与领域映射"]
        W1_2["train_external_operation 异步流水持久化表构建"]
        W1_3["Liquibase / Flyway 增量数据库 Migration 脚本"]
        W1_4["门禁与操作双层状态机模型持久化枚举与转换器"]
    end

    subgraph Wave2["Wave 2: DMS 专用适配器与仿真 (DMS Adapter & Mock Test)"]
        W2_1["DmsProperties 安全配置契约与受控环境变量集成"]
        W2_2["DmsTokenManager 进程级单飞排他锁与 401 自愈"]
        W2_3["细分 DmsClient (Place, DoorLock, Key, Operation)"]
        W2_4["在线密码 / 在线卡片下发与撤销协议适配 (含 CardNumberCodec)"]
        W2_5["DmsOperationPoller 10 秒延迟对账调度器"]
        W2_6["WireMock 仿真服务与 22 项单测套件 (并发/异常注入)"]
    end

    subgraph Wave3["Wave 3: 业务编排、交互与现场验收 (Business Orchestration & UI & Sandbox)"]
        W3_1["门禁授权触发编排 (报到核验联动 / 提早进房时间 Buffer)"]
        W3_2["退宿、退训强制撤权与计划结训批量注销"]
        W3_3["换房补偿编排服务 (先发新房后撤旧房，异常熔断保留原房)"]
        W3_4["管理端 UI: 住宿列表门禁彩色徽标、操作历史抽屉、手动重试"]
        W3_5["学员端 UI: 个人中心门锁状态、有效期展示、30秒倒计时密码受控查看"]
        W3_6["现场实验台测试沙箱 E2E 闭环验收与真实门锁调测"]
    end

    Wave0 --> Wave1
    Wave1 --> Wave2
    Wave2 --> Wave3
```

---

## 2. 各 Wave 任务详细定义与交付清单

### Wave 0: 本地领域模型对齐 (`Local Domain Alignment`)
> **前置条件**：基线处于 `adcf930e`；`LOCAL_DOMAIN_ALIGNMENT_REQUIRED = YES`。
> **核心目标**：消除本地 Java 实体与 Kingbase 物理表 V2 的历史漂移，补齐缺失的 Accommodation 业务代码。

1. **TrainAccommodation Java Domain 构建**：
   - 创建 `TrainAccommodation.java` 实体，映射物理表 `train_accommodation` 的全部 11 个列（`accommodation_id`, `enrollment_id`, `dorm_id`, `bed_no`, `assigned_time`, `accommodation_status` 等）。
   - 创建 `AccommodationCreateDTO`, `AccommodationVO` 等。
2. **Mapper & Service 实现**：
   - 编写 `TrainAccommodationMapper.java` 与 XML，实现排宿、入住、退宿状态流转。
   - 编写 `ITrainAccommodationService` 及其实现类，承接业务事实变更。
3. **TrainDormAuth V2 结构升级与清洗**：
   - 彻底清洗 Java 类 `TrainDormAuth.java`，移除已废弃的 V1 字段（`studentId`, `planId`, `dormId`, `bedNo`）。
   - 使其完全对齐 V2 数据库物理表（`accommodation_id`, `retry_count`, `last_error`, `external_auth_id`, `last_sync_time`）。
   - 同步修正 `TrainDormAuthMapper.xml` 中的 ResultMap 与 SQL 映射。
4. **业务边界明确与解耦测试**：
   - 编写本地单测，验证：`Dormitory Resource` (物理房源) ↔ `Accommodation` (住宿事实) ↔ `TrainDormAuth` (门禁事实) 三者职责分离。

---

### Wave 1: 外部映射与操作持久化 (`External Mapping & Operation Persistence`)
> **前置条件**：Wave 0 完成。
> **核心目标**：建立房源/设备映射体系与异步操作流水持久化模型，为外部调用提供存储支撑。

1. **外部资源映射模型 (`train_external_resource_mapping`)**：
   - 编写 DDL Migration 脚本，创建资源映射表，支持一房多锁及未来多厂商拓展。
   - 编写 `TrainExternalResourceMapping` 实体与 Mapper，支持按 `dorm_id` 查询关联的所有锁具。
2. **外部异步操作流水模型 (`train_external_operation`)**：
   - 创建操作流水表，记录每一次向外部设备派发的具体指令（`operation_local_id`, `dms_operation_id`, `dms_request_type`, `operation_status`, `poll_count`, `next_poll_time`）。
3. **状态机枚举与状态映射规范**：
   - 在系统内部定义门禁业务状态枚举 `DoorAuthorizationStatus` 与硬件操作状态枚举 `ExternalOperationStatus`。

---

### Wave 2: DMS 专用适配器与仿真验证 (`DMS Adapter & Mock Tests`)
> **前置条件**：Wave 1 完成。
> **核心目标**：完成对 DMS REST API 的全套适配，并通过 WireMock 离线仿真实现 100% 自动化测试。

1. **安全配置与基础设施**：
   - 建立 `DmsProperties`，绑定环境变量（`DMS_BASE_URL`, `DMS_APP_ID`, `DMS_APP_SECRET`, `DMS_PROJECT_ID`）。
   - 配置 HTTP 日志脱敏拦截器（掩码 Token、Secret 与 Password）。
2. **Token 管理器与并发防击穿 (`DmsTokenManager`)**：
   - 实现进程级内存 Token 缓存，实现单飞排他锁（Single-Flight），拦截 20 线程并发竞争，确保远程登录只调用一次；实现 401 自动失效重登录与最大 1 次重试。
3. **细分领域 HTTP 客户端**：
   - 封装 `DmsPlaceClient`, `DmsDoorLockClient`, `DmsKeyClient`, `DmsOperationClient`。
4. **门锁授权网关适配器实现 (`DmsDoorAccessGateway`)**：
   - 实现中立接口 `DoorAccessGateway`；
   - 适配在线限时密码下发 (`/online-password-key/create`，系统支持4~8位，Pilot建议生成6位限时密码) 与注销 (`/online-password/delete`)；
   - 实现 `CardNumberCodec` 小端序十六进制转换；
5. **异步对账轮询调度器 (`DmsOperationPoller`)**：
   - 基于 Spring Scheduled 专用线程池，实现门锁操作 10 秒后对账拉取与超时判定。
6. **WireMock 仿真测试套件**：
   - 编写包含 22 个场景的自动化集成测试用例，覆盖正常流、超时、401、并发击穿、网络读取异常对账等。

---

### Wave 3: 业务编排、交互与现场沙箱验收 (`Business Orchestration & UI & Sandbox`)
> **前置条件**：Wave 2 完成。
> **核心目标**：实现上层业务联动、管理端与学员端界面交互，并在现场测试沙箱完成闭环验收。

1. **门禁授权触发时机与编排 (`DoorAccessOrchestrationService`)**：
   - 联动现场《报到核验》事件：学员报到核验成功后异步触发门禁下发；
   - 配置授权时间窗口 Buffer（提前进房、延后离校）。
2. **注销与补偿服务**：
   - 换房补偿：“先发新房权限、确认生效后再撤销旧房权限”，新房下发失败时保留旧房并报警；
   - 学员退训强制立即撤销权限；
   - 培训结训主动批量撤销钥匙，辅以 `validUntil` 有效期边界兜底。
3. **管理端 UI 交互实现**：
   - 住宿安排列表集成门禁彩色徽标（下发中/已生效/失败/已注销）；
   - 提供操作流水抽屉弹窗、手动重试按钮与设备电量监控视图。
4. **学员端个人中心视图**：
   - 移动端个人中心展示宿舍分配、门锁就绪状态与有效期；
   - 支持经二次身份验证后查看 30 秒倒计时完整开门密码。
5. **现场测试沙箱实物闭环验收**：
   - 在甲方提供的专属测试账号与实验台测试门锁上进行全流程实物验证；
   - 确认门锁离线时的 `validUntil` 本地过期与 RTC 时钟行为；
   - 输出正式现场实物验收报告。

---

## 3. 工期与人力资源估算

| 阶段 | 核心交付成果 | 涉及模块 | 预估工时 |
| :--- | :--- | :--- | :---: |
| **Wave 0: Local Domain Alignment** | 消除本地代码与 DB 漂移，补齐 Accommodation 业务层 | 后端领域层 | 3 人天 |
| **Wave 1: External Mapping & Persistence** | 资源映射表、操作流水表及数据库 Migration | 数据库/持久层 | 2 人天 |
| **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，全量通过。

### 3.3 Wave 1 Implementation Result (外部资源映射与操作流水持久化 - Wave 1 implemented)
- **阶段目标**：External Resource Mapping & External Operation Persistence
- **执行状态**：Wave 1 implemented
- **核心交付清单**：
  1. 迁移脚本：`RuoYi-Vue/sql/system/kingbase/008_external_resource_operation.sql`（安全编号 008，支持一房多锁与幂等流水）
  2. 领域实体：`TrainExternalResourceMapping.java`、`TrainExternalOperation.java`（纯净中立模型，零敏感数据）
  3. 持久映射：`TrainExternalResourceMappingMapper.java/.xml`、`TrainExternalOperationMapper.java/.xml`（显式列投影，严禁 `SELECT *`）
  4. 业务服务：`IExternalResourceMappingService/Impl`、`IExternalOperationService/Impl`（Active唯一性校验、跨房间绑定防护、终态保护、重试创建）
  5. 自动化测试套件：`ExternalResourceMappingServiceTest` (10项)、`ExternalOperationServiceTest` (12项)、`ExternalResourceOperationMigrationContractTest` (7项)
- **全量构建与回归验收**：
  - `ruoyi-train`: 175 tests
  - `ruoyi-admin`: 28 tests
  - 总计：203 tests, Failures = 0, Errors = 0, Skipped = 0，全部通过。
  - Maven `clean test` 与 `clean package` 构建成功。
  - 生产数据库变更：`PRODUCTION_DB_MODIFIED? NO`。
  - 外部 HTTP 客户端与通信：`DMS_HTTP_CLIENT_COUNT = 0`，`DMS_LIVE_API_CALLED? NO`。
- **Migration 验证与准入门禁标记**：
  - `008_RUNTIME_FIRST_RUN = NOT_EXECUTED`
  - `008_RUNTIME_SECOND_RUN = NOT_EXECUTED`
  - `008_CONTRACT_TEST = PASS`
  - `RUNTIME_MIGRATION_GATE_BEFORE_PRODUCTION = REQUIRED`
  - 严禁将 Contract Test PASS 描述为实际 Kingbase 双执行 PASS。

### 3.4 Wave 2 Implementation Result (DMS 适配层 / Token / HTTP / Poller / Mock 集成 - Wave 2 implemented)
- **阶段目标**：DMS Adapter / Token / HTTP / Poller / Mock Integration against Mock DMS only
- **执行状态**：Wave 2 implemented
- **核心交付清单**：
  1. 基础配置：`DmsProperties.java`（受控配置，`enabled=false` 安全默认，参数化超时与刷新窗口）。
  2. 令牌管理：`DmsTokenManager.java`（进程级单例缓存，ReentrantLock + DCL 单飞互斥防击穿，滑动顺延，401 集中失效）。
  3. 通信客户端：`DmsHttpClient.java`（Cookie 头鉴权，脱敏日志，写操作读取超时严禁自动重发 `AMBIGUOUS_MUTATION_AUTO_RETRY = NO`）。
  4. 位置适配器：`DmsLocationClient.java`、`ExternalLocationGateway.java`、`DmsLocationGatewayImpl.java`（层级空间查询与 placeId 解析）。
  5. 门锁适配器：`DmsDoorLockClient.java`、`ExternalDoorLockGateway.java`、`DmsDoorLockGatewayImpl.java`（支持 0、1、多把智能门锁）。
  6. 密码凭据适配器：`DmsPasswordClient.java`、`ExternalCredentialGateway.java`、`DmsCredentialGatewayImpl.java`（下发 4~8 位限时密码、删除密码，密码明文内存短暂留存）。
  7. 状态查询与映射：`DmsOperationStatusClient.java`、`DmsOperationStatusMapper.java`（集中统一映射，未知状态判定为 UNKNOWN 严禁判定为 SUCCESS）。
  8. 异步轮询器：`DmsOperationPoller.java`（条件化启动，单进程并发防重，终态不可篡改保护，退避重试）。
  9. 测试基础设施：`MockDmsServer.java`（内嵌纯 JDK HttpServer，完全模拟真实 DMS 平台登录互斥、短 TTL、多锁/零锁与状态流转）。
  10. 自动化测试套件：`DmsTokenManagerTest` (4项)、`DmsHttpClientTest` (3项)、`DmsLocationAdapterTest` (1项)、`DmsDoorLockAdapterTest` (2项)、`DmsPasswordAdapterTest` (4项)、`DmsOperationStatusAdapterTest` (4项)、`DmsOperationPollerTest` (6项)、`DmsAsyncLifecycleAndSecurityTest` (2项)。
- **全量构建与回归验收**：
  - `ruoyi-train`: 201 tests
  - `ruoyi-admin`: 28 tests
  - 总计：229 tests, Failures = 0, Errors = 0, Skipped = 0，全部通过。
  - Maven `clean test` 与 `clean package` 构建成功。
  - 生产数据库变更：`PRODUCTION_DB_MODIFIED? NO`。
  - 外部通信真实调用：`LIVE_DMS_REQUEST_COUNT = 0`。
  - 控制器与前端改动：`CONTROLLER_COUNT = 0`，`FRONTEND_MODIFIED = 0`。
- **Migration 标记**：
  - `008_RUNTIME_FIRST_RUN = NOT_EXECUTED`
  - `008_RUNTIME_SECOND_RUN = NOT_EXECUTED`
  - `RUNTIME_MIGRATION_GATE_BEFORE_PRODUCTION = REQUIRED`

### 3.5 Wave 3A Implementation Result (业务状态/门禁期望状态/外部操作统一编排 Dry-Run - Wave 3A implemented against Mock DMS only)
- **阶段目标**：Access Authorization Orchestration Dry-Run
- **执行状态**：Wave 3A implemented against Mock DMS only
- **核心交付清单**：
  1. 架构扩展迁移脚本：`RuoYi-Vue/sql/system/kingbase/009_dorm_authorization_orchestration.sql`（安全编号 009，幂等增量添加凭据类型、业务授权状态、关联操作ID与版本号列，零明文列）。
  2. 实体模型扩展：`TrainDormAuth.java`（新增业务状态与凭据常量、双向状态映射、版本控制属性）。
  3. 服务层编排扩展：`ITrainDormAuthService/Impl`（实现 `ensureAuthorizationForAccommodation`、`updateAuthStatusByPoller` 并植入迟到保护）。
  4. 安全凭据生成器：`SecurePasswordGenerator.java`（`SecureRandom` 强随机、6 位纯数字、内存局部留存、杜绝弱密码）。
  5. 统一编排器：`AccessAuthorizationOrchestrator.java`（状态驱动对账 `reconcile`，解耦业务事件时序，短事务解耦外部 HTTP，最少特权单主锁策略，调房先新后旧）。
  6. 异步轮询器联动推进：`DmsOperationPoller.java`（集成授权状态联动，根据最新操作归属安全更新业务授权状态）。
  7. 业务事件安全挂接：`TrainAccommodationServiceImpl.java`（分房/退宿/调房）、`EnrollmentAppServiceImpl.java`（报到确认）、`EnrollmentPlanCompletionAdapter.java`（计划结训），异常不回滚本地业务主事务。
  8. 迁移契约测试：`DormAuthorizationOrchestrationMigrationContractTest.java` (4 项)。
  9. 端到端编排测试：`AccessAuthorizationOrchestrationTest.java` (9 项)。
  10. 业务事务独立性与安全扫描：`BusinessTransactionIndependenceTest.java` (5 项)。
- **全量构建与回归验收**：
  - `ruoyi-train`: 219 tests
  - `ruoyi-admin`: 32 tests
  - 总计：251 tests, Failures = 0, Errors = 0, Skipped = 0，全部通过。
  - Maven `clean test` 与 `clean package` 构建成功。
  - 静态检查：`git diff --check` PASS。
- **环境纪律与准入门禁**：
  - `LIVE_DMS_REQUEST_COUNT = 0`。
  - `FRONTEND_MODIFIED = 0`，`CONTROLLER_COUNT = 0`。
  - `008_RUNTIME_FIRST_RUN = NOT_EXECUTED`，`008_RUNTIME_SECOND_RUN = NOT_EXECUTED`。
  - `009_RUNTIME_FIRST_RUN = NOT_EXECUTED`，`009_RUNTIME_SECOND_RUN = NOT_EXECUTED`。
  - `RUNTIME_MIGRATION_GATE_BEFORE_PRODUCTION = REQUIRED`。