109 lines
7.6 KiB
Markdown
109 lines
7.6 KiB
Markdown
# 14 DMS 门禁集成审计与设计决策一页纸总结 (Decision Summary)
|
||
|
||
> **面向对象**：项目负责人、架构指导老师、业务决策评审委员会
|
||
> **核心宗旨**：以最短篇幅、最清晰视角，讲透“现状、能力、接入边界、推荐架构与实施规划”。
|
||
|
||
---
|
||
|
||
## 1. 当前系统有什么？(Current RailwaySystem Assets)
|
||
|
||
1. **业务与数据基线**：
|
||
- 当前生产分支基于 `adcf930e`，已完成 V2 数据库结构迁移。
|
||
- 物理表层：`train_dormitory_info`（宿舍楼栋/房间台账）、`train_accommodation`（学员参训住宿分配事实表）、`train_dorm_auth`（门禁授权表，外键绑定 `accommodation_id`）已在 Kingbase 物理库建表。
|
||
- 业务逻辑层：已具备完整的培训计划编排、学员报到核验、宿舍入住分配与床位容量实时统计能力。
|
||
2. **本地模型漂移与前置对齐要求 (`LOCAL_DOMAIN_ALIGNMENT_REQUIRED = YES`)**：
|
||
- **`train_accommodation`**：DB 物理表已建，但 Java 层尚无对应的实体类、Mapper 与业务 Service，未形成完整业务层。
|
||
- **`train_dorm_auth`**：DB 已升级为以 `accommodation_id` 为外键的 V2 结构，但 Java 实体类与 XML Mapper 仍残留 V1 字段（`student_id`, `plan_id`, `dorm_id`）。
|
||
- **决策红线**：在真正编写外部 DMS Adapter 之前，**必须在 Wave 0 优先完成本地住宿与门禁授权领域模型对齐**，严禁将外部适配器直接架设在漂移模型上。
|
||
|
||
---
|
||
|
||
## 2. DMS 平台能提供什么？(DMS IoT Platform Capabilities)
|
||
|
||
外部 DMS 智能门锁平台（`https://dms.dmsiot.com`）具备完整的 RESTful 接口体系：
|
||
1. **楼栋-楼层-房间-门锁全层级资产查询**（可精确匹配房间获取 `placeId`，支持一房多锁）。
|
||
2. **多模态电子钥匙下发能力**：
|
||
- **在线限时密码 (Online Password)**：系统可生成 4~8 位纯数字密码（Pilot 建议采用 6 位限时密码），指定起止有效时间，支持远程主动注销。
|
||
- **在线实体芯片卡 (Online Card)**：支持将学员 IC/M1 卡按小端十六进制编码下发至锁具，支持远程主动注销。
|
||
- **二维码/手机钥匙 (QR Key)**：端点已定义 (`POST /rest/doorlock/qrcode/create` 与 `POST /rest/qrcode/delete`)，分类为 `DOCUMENTED`，但返回体存在数据污染且无具体二维码载荷，适用性归为 `NEEDS_BUSINESS_CONFIRMATION`。
|
||
3. **低功耗异步执行与对账体系**：门锁基于电池无线通信，下发指令后返回 `operationId`，要求 10 秒后通过接口查询终态。
|
||
4. **设备运行指标**：提供门锁电池电量、信号强度及门锁开门记录流水拉取。
|
||
|
||
---
|
||
|
||
## 3. 一期建议先接什么？暂时不接什么？(Scope Boundary)
|
||
|
||
```
|
||
+-------------------------------------------------------------------------------+
|
||
| 一期重点纳入 (P0 / P1) |
|
||
| 1. 认证鉴权: Token 内存单飞排他锁缓存 + 滑动刷新 + 401 单次重试自愈 |
|
||
| 2. 房源映射: 本地宿舍与 DMS placeId / lockId 的预绑定持久化 (支持一房多锁) |
|
||
| 3. 首选凭据: 【在线限时密码】(零硬件与发卡器依赖, 支持4~8位/推荐6位, 随时主动撤销) |
|
||
| 4. 异步对账: 后台调度器 10 秒后异步轮询 operationId，消除 HTTP 线程阻塞 |
|
||
| 5. 换房补偿: 严格遵循"先发新房权限、确认生效后再撤旧房"原则，避免学员无处可住 |
|
||
| 6. 结训撤权: 培训结束主动派发 Revoke 指令，同时以 validUntil 作为有效期边界兜底 |
|
||
| 7. 设备巡检: 门锁电量与信号查询 (P1)，辅助宿管员发现低电量设备 |
|
||
+-------------------------------------------------------------------------------+
|
||
▲
|
||
【严格划清边界】
|
||
▼
|
||
+-------------------------------------------------------------------------------+
|
||
| 一期明确排除 (P2 / Out of Scope / Needs Confirmation) |
|
||
| 1. 取电开关全套接口 (P2): 涉及强电改造，与学员核心学籍住宿无关，暂缓接入 |
|
||
| 2. 远程网络开锁 (P2): 属于高危主动开门操作，一期严格封存，仅设计受控两票制应急方案 |
|
||
| 3. 二维码钥匙 (Needs Biz Confirm): 接口已文档化但载荷污染，一期不作首选方案 |
|
||
| 4. 离线密码与离线发卡 (Out of Scope): 缺乏可靠远程主动撤销机制，增加现场运维负担 |
|
||
+-------------------------------------------------------------------------------+
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 需要向甲方与业务负责人确认的核心问题 (Blocking Decisions)
|
||
|
||
1. **下发触发时机 (Q-BLK-03)**：
|
||
- *推荐意见*：**学员在现场完成《报到核验》后自动触发门禁下发**。确保人已到校才给钥匙，杜绝未报到人员提前进房。
|
||
2. **首期钥匙类型 (Q-BLK-02)**：
|
||
- *推荐意见*：首选采用**系统派发 6 位在线限时密码**（学员移动端个人中心受控查看）；若后续统一下发实体卡，可平滑启用在线卡片模式。
|
||
3. **主数据权威归属 (Q-NON-01)**：
|
||
- *推荐意见*：**坚决以 RailwaySystem 作为住宿与房间主数据**，DMS 仅作为外部执行端，严禁让 DMS 状态覆盖本地系统。
|
||
4. **现场网络连通性与沙箱 (Q-BLK-01 & Q-BLK-05)**：
|
||
- 生产环境机房是否允许访问公网 `dms.dmsiot.com`？供应商必须提供包含测试网关与实验台门锁的**独立联调测试沙箱**。
|
||
5. **设备离线时 `validUntil` 过期语义 (Q-BLK-06)**：
|
||
- 门锁离线断网时，到达 `validUntil` 是否由锁端本地时钟强制失效？需供应商提供硬件保证级别说明。
|
||
|
||
---
|
||
|
||
## 5. 推荐技术架构设计
|
||
|
||
```
|
||
[前端 Accommodation / 个人中心]
|
||
│
|
||
▼
|
||
[业务领域层: 住宿分配 / 换房补偿 / 报到联动] <--- 绝对 Source of Truth
|
||
│
|
||
▼ (通过强类型 DTO，完全屏蔽外部厂商细节)
|
||
[中立网关接口: DoorAccessGateway (grant / revoke / query)]
|
||
│
|
||
▼ (SPI 模式)
|
||
[DMS 集成适配器: DmsDoorAccessGateway]
|
||
├── DmsTokenManager: 进程级单飞排他锁 (防并发覆盖踩踏)
|
||
├── 细分 HTTP 客户端: PlaceClient / DoorLockClient / KeyClient / OpClient
|
||
└── DmsOperationPoller: 后台 10 秒对账调度器 (解除 HTTP 线程阻塞)
|
||
│
|
||
▼ (HTTPS / Cookie 传递 token)
|
||
[外部 DMS 物联网平台: https://dms.dmsiot.com]
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 后续 R.3B 四阶段推进路线图 (Four Waves, 约 15~16 人天)
|
||
|
||
1. **Wave 0: Local Domain Alignment (本地领域模型对齐，3天)**：
|
||
- 实现 `TrainAccommodation` Java 实体/Mapper/Service；升级并清洗 `TrainDormAuth` 对齐 V2 数据库；确立住宿事实与门禁授权的清晰边界。
|
||
2. **Wave 1: External Mapping & Operation Persistence (外部映射与持久化，2天)**：
|
||
- 创建 `train_external_resource_mapping` 与 `train_external_operation` 物理表及 Migration 脚本；落地双层状态机模型。
|
||
3. **Wave 2: DMS Adapter & Mock Tests (DMS 适配器与离线仿真，5天)**：
|
||
- 配置与环境变量绑定；`DmsTokenManager` 单飞排他锁并发控制；细分 HTTP 客户端；在线密码/卡片适配器；10 秒轮询调度器；WireMock 22 项单测全覆盖。
|
||
4. **Wave 3: Business Orchestration & UI & Sandbox (业务编排、界面与现场验收，5~6天)**：
|
||
- 报到联动授权下发；“先发新房后撤旧房”换房补偿；退训/结训撤权；管理端门禁综合视图；学员端 30 秒倒计时密码受控查看；现场实验台沙箱 E2E 闭环验收。
|