9.3 KiB
9.3 KiB
03 RailwaySystem 与 DMS 领域模型映射体系 (Domain Mapping)
核心原则：RailwaySystem 是住宿业务事实的唯一真源 (Source of Truth)。 DMS 平台仅作为外部门禁与物联网设备的执行端与监控端。 严禁：以 DMS 房间状态 (
status) 直接替代 RailwaySystem 住宿占用与床位台账。
1. 核心实体对应关系总览 (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 |
优点：查询直观，单表读取。 缺点：污染本地物理宿舍模型；若未来接入其他门禁厂商（如海康、大华），列定义难以复用。 |
可作为一期过渡备选 |
方案 2：独立 train_external_resource_mapping 映射表 |
建立独立映射表：local_resource_type ('DORMITORY'), local_id, vendor ('DMS'), external_id (placeId), metadata_json |
优点：模型高度解耦；本地宿舍资源生命周期不受外部影响；天然支持多厂商与资源解绑/重绑。 缺点：需要多做一次关联查询。 |
推荐采纳 |
映射规则明确：
- 严禁每次下发授权时现场调用
/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秒后状态轮询) |