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 人天** |