# 03 RailwaySystem 与 DMS 领域模型映射体系 (Domain Mapping)

> **核心原则**：**RailwaySystem 是住宿业务事实的唯一真源 (Source of Truth)**。
> **DMS 平台**仅作为外部门禁与物联网设备的执行端与监控端。
> **严禁**：以 DMS 房间状态 (`status`) 直接替代 RailwaySystem 住宿占用与床位台账。

---

## 1. 核心实体对应关系总览 (Mermaid 架构图)

```mermaid
classDiagram
    direction TB

    class RailwayTrainingPlan {
        +String planId "内部培训班计划ID"
        +String planName
        +Date trainStart
        +Date trainEnd
    }

    class RailwayEnrollment {
        +Long enrollmentId "参训学员档案ID"
        +String planId
        +String studentId
        +Integer reportStatus
    }

    class RailwayAccommodation {
        +Long accommodationId "住宿安排事实ID (Source of Truth)"
        +Long enrollmentId
        +String dormId
        +String bedNo
        +Integer accommodationStatus "0预分配, 1已入住, 2已退宿"
    }

    class RailwayDormitoryInfo {
        +String dormId "本地宿舍UUID"
        +String dormBuilding "楼栋"
        +String dormFloor "楼层"
        +String dormRoom "房号"
        +Integer capacity "床位容量"
    }

    class ExternalResourceMapping {
        +Long mappingId
        +String localDormId "关联本地宿舍"
        +Long dmsProjectId "DMS租户/物业站点ID"
        +Long dmsPlaceId "DMS房间ID"
        +String dmsBuilding
        +String dmsFloor
        +String dmsRoom
        +Integer mappingStatus "1已绑定, 0待校验"
    }

    class DmsPlaceRoom {
        <<DMS Remote>>
        +Long id "DMS placeId"
        +Long projectId "DMS租户ID (≠ planId)"
        +String building
        +String floor
        +String room
    }

    class DmsDoorLock {
        <<DMS Remote>>
        +Long lockId "DMS锁ID"
        +String hardwareId "锁硬件SN (如 5C9F539A)"
        +Long placeId
        +Integer battery
        +Integer signal
    }

    class DoorAuthorization {
        +Long authId "本地授权凭证主记录"
        +Long accommodationId
        +Long dmsLockId
        +String dmsHardwareId
        +Long dmsKeyId "DMS返回的钥匙ID"
        +String credentialType "PASSWORD / CARD"
        +Timestamp validStart
        +Timestamp validUntil
        +Integer authStatus "PENDING / ACTIVE / REVOKED"
    }

    class ExternalOperationRecord {
        +Long operationLocalId
        +Long authId
        +String dmsOperationId "DMS异步操作流水ID"
        +Integer requestType "1下发密码, 3删除密码等"
        +String operationStatus "undone / success / failed / timeout"
        +Integer pollCount
        +Timestamp nextPollTime
    }

    RailwayTrainingPlan "1" --> "0..*" RailwayEnrollment : 包含
    RailwayEnrollment "1" --> "1" RailwayAccommodation : 产生住宿安排
    RailwayAccommodation "0..*" --> "1" RailwayDormitoryInfo : 分配房间
    RailwayDormitoryInfo "1" --> "0..1" ExternalResourceMapping : 稳定映射
    ExternalResourceMapping "1" ..> "1" DmsPlaceRoom : 对应DMS物理房间
    DmsPlaceRoom "1" ..> "0..*" DmsDoorLock : 挂载智能门锁 (支持一房多锁)
    RailwayAccommodation "1" --> "0..*" DoorAuthorization : 派生门锁授权
    DoorAuthorization "1" --> "0..*" ExternalOperationRecord : 追踪异步执行
```

---

## 2. 关键实体边界与重大概念澄清

### 2.1 铁律：`DMS projectId ≠ RailwaySystem Training Plan ID`
- **DMS `projectId`**（示例中为 `319402846`、`3837087560`）：代表 DMS 物联网平台的**物业项目/租户/公寓站点 ID**。属于系统级或物理站点级的静态上下文配置，由设备供应商分配。
- **RailwaySystem `plan_id`**（如 `PLAN20260901`）：代表铁路局/段内的**具体教学培训开班批次**。生命周期通常为几天到几周。
- **红线**：严禁将 DMS `projectId` 错写成或动态传为学员开班 `planId`！在配置文件中应统一作为 `dms.project-id` 进行站点级静态受控配置。

### 2.2 铁律：本地住宿事实是唯一真源 (`Local Source of Truth`)
- DMS 的 `room.status`（0:空置, 1:已入住, 2:脏房等）仅为其平台或第三方酒店系统的简单标记，**绝对不能用于覆盖或推断 RailwaySystem 的床位与入住状态**。
- 只有 RailwaySystem 自身的 `train_accommodation` 与 `train_enrollment` 能决定学员是否在住、床位是否已满、是否已报到。
- DMS 门锁授权状态仅是硬件执行层面的技术属性（开门凭据是否已在锁具上成功生效）。

---

## 3. 房间与门锁映射策略深度比选 (Mapping Proposals)

### 3.1 房间映射 (Local Dormitory ↔ DMS Place)
DMS 提供了两种查询房间的途径：
- 模糊查询列表：`POST /rest/place/room/list`
- 精确查询：`POST /rest/place/room/get`（入参：`building`, `floor`, `room`）

| 方案 | 实现方式 | 优缺点分析 | 结论 |
| :--- | :--- | :--- | :--- |
| **方案 1：直接在 `train_dormitory_info` 加列** | 增加 `dms_place_id`, `dms_project_id`, `dms_sync_time` | **优点**：查询直观，单表读取。<br>**缺点**：污染本地物理宿舍模型；若未来接入其他门禁厂商（如海康、大华），列定义难以复用。 | 可作为一期过渡备选 |
| **方案 2：独立 `train_external_resource_mapping` 映射表** | 建立独立映射表：`local_resource_type ('DORMITORY')`, `local_id`, `vendor ('DMS')`, `external_id (placeId)`, `metadata_json` | **优点**：模型高度解耦；本地宿舍资源生命周期不受外部影响；天然支持多厂商与资源解绑/重绑。<br>**缺点**：需要多做一次关联查询。 | **推荐采纳** |

**映射规则明确**：
- **严禁**每次下发授权时现场调用 `/rest/place/room/get` 进行文本字符串模糊匹配。网络抖动或楼栋名称微小差异（例如 "1号楼" vs "楼栋1"）会导致授权链路阻断。
- **必须**在管理端提供“房源映射绑定/同步”功能，预先在数据库中持久化 `localDormId ↔ dmsPlaceId` 的权威主键映射。

### 3.2 门锁映射：支持“一房多锁”模型 (`One Room to Multi-Locks`)
DMS 接口 `POST /rest/doorlock/list`（入参 `placeId`）返回的是一个门锁列表：`rows: [...]`。
这证实了物理现实：**一个公寓房间可能没有门锁（0把）、有一把门锁（1把）、或者有多个门锁（例如外防盗门锁 + 内卧室锁，多把锁）**。

- **错误做法**：在 `train_dormitory_info` 中仅保留单一的 `lock_device_sn` 字符串，假设一房仅有一锁。
- **推荐设计**：
  - 系统必须能够处理一个 `placeId` 对应 `0..N` 把门锁的情况。
  - 当为学员下发该房间的开门权限时，集成适配器应查询该房间绑定的**所有有效门锁**，并为每把锁分别申请/下发开门凭据，生成对应的 `DoorAuthorization` 记录。

---

## 4. 详细字段级映射字典 (Field-Level Mapping Dictionary)

### 4.1 宿舍/房间信息映射
| RailwaySystem 本地字段 | DMS 对应字段 | 类型转换 / 映射规则 | 说明 |
| :--- | :--- | :--- | :--- |
| `train_dormitory_info.dorm_id` | `mapping.local_dorm_id` | `VARCHAR(32)` (UUID) | 本地主键 |
| - | `dms.place.id` / `placeId` | `BIGINT` | DMS 房间全局唯一主键 |
| `train_dormitory_info.dorm_building` | `dms.place.building` | 字符串精确比对/绑定 | 宿舍楼栋名 |
| `train_dormitory_info.dorm_floor` | `dms.place.floor` | 字符串精确比对/绑定 | 所在楼层 |
| `train_dormitory_info.dorm_room` | `dms.place.room` | 字符串精确比对/绑定 | 房间号 |
| - | `dms.place.projectId` | `BIGINT` | 系统级受控站点配置 |

### 4.2 门锁设备信息映射
| RailwaySystem 本地概念 | DMS 对应字段 | 类型 / 格式 | 说明 |
| :--- | :--- | :--- | :--- |
| `mapping.external_lock_id` | `doorlock.id` | `BIGINT` | DMS 门锁管理 ID |
| `train_dormitory_info.lock_device_sn` | `doorlock.hardwareId` | `VARCHAR(64)` (如 `5C9F539A`) | 门锁硬件 SN / 通信 ID |
| `device_battery` | `doorlock.battery` | `INT` (0~100, 255为未知) | 门锁电量 |
| `device_signal` | `doorlock.signal` | `INT` (-100~0, -128为未知) | 信号强度 (RSSI) |

### 4.3 门禁授权与钥匙下发映射 (Online Password 场景)
| RailwaySystem 本地字段 | DMS 对应入参 / 字段 | 映射规则与约束 |
| :--- | :--- | :--- |
| `train_accommodation.accommodation_id` | - | 本地业务事实归属 |
| `target_lock_id` | `create.lockId` | 目标门锁的 DMS ID |
| `auth_start` (配合提早 Buffer) | `create.validStart` | 毫秒级时间戳 (`Long`) |
| `auth_end` (配合延后 Buffer) | `create.validUntil` | 毫秒级时间戳 (`Long`) |
| `student_name` | `create.holder` | 学员姓名 (可选，建议填写真实姓名) |
| - | `create.canOpenAntilock` | 固定设为 `false` (不可开反锁，保障私密安全) |
| `phone_country` | `create.phoneCountry` | 默认 `+86` |
| `student_phonenumber` | `create.phoneNumber` | 学员手机号 |
| `door_password` (一次性生成或安全受控) | `create.password` | 系统可生成4~8位纯数字密码，Pilot建议采用6位限时密码 |
| `credential_sub_type` | `create.subType` | 固定为 `4` (限时密码) |
| `external_key_id` | 返回的 `data.id` | DMS 钥匙全局 ID (退宿撤权时作为删除入参) |
| `dms_operation_id` | 返回的 `data.operationId` | DMS 异步下发任务 ID (用于10秒后状态轮询) |

---

## 5. Wave 1 Implementation Result (Wave 1 implemented)
- **阶段状态**：Wave 1 implemented（外部资源映射模型与外部操作流水持久化模型已交付并验证）。
- **资源映射基数与引用模型 (`RESOURCE_MAPPING_REFERENCE_MODEL = DORM_ID_FK`)**：
  - 本地采用 `dorm_id` 外键强关联 `train_dormitory_info`，确保一期完整性与零类型歧义。
  - **房间映射基数**：`ROOM_MAPPING_CARDINALITY = Dormitory 1:0..1 Active Room (Dormitory 1:N History)`，同一宿舍在同一 Vendor 下最多只能有 1 个处于 ACTIVE 状态的房间映射（通过局部唯一索引 `uq_ext_res_map_active_room` 严格保障）。
  - **门锁映射基数**：`LOCK_MAPPING_CARDINALITY = Dormitory 1:0..N DoorLocks`，支持一房多锁（防盗门、内门、套间门），`is_primary` 区分主从门锁。
  - **外部资源唯一性**：`EXTERNAL_RESOURCE_ACTIVE_UNIQUENESS = Vendor + External Resource ID + Active Unique`，同一外部资源在同一厂商下严禁跨房间重复 ACTIVE 绑定（通过局部唯一索引 `uq_ext_res_map_active_ext_res` 保障）。
- **操作流水基数与引用模型 (`OPERATION_REFERENCE_MODEL = DOOR_AUTH_ID_FK`)**：
  - 本地采用 `door_auth_id` 外键强关联 `train_dorm_auth`，业务类型默认为 `DOOR_AUTH`。
  - **操作流水基数**：`DOOR_AUTH_OPERATION_CARDINALITY = DoorAuthorization 1:N ExternalOperation`，每次具体下发、重试、撤销均保留独立流水行，禁止直接覆写。
  - **状态机与幂等**：`OPERATION_STATUS_MODEL` 包含从 `CREATED` 到 `SUCCESS/FAILED/TIMEOUT/RETRY_WAIT` 的合法单向流转（`REVOKED` 属于 `DoorAuthorization` 业务状态，单次注销流水为 `operation_type=REVOKE` 达成 `SUCCESS`），终态不可逆；`idempotency_key` 唯一索引全局防重。
- **敏感数据治理**：不存 raw JSON、密码明文、卡号明文、Token、Secret，敏感字段数为 0。
- **数据库迁移安全**：`008_external_resource_operation.sql` 已通过静态契约测试与幂等验证，生产库保持零变更。