90 lines
11 KiB
Markdown
90 lines
11 KiB
Markdown
# 13 供应商技术歧义、业务决策与阻塞性问题清单 (Open Questions)
|
||
|
||
> **审计说明**：本清单系统性整理了在 DMS 官方文档审计、网络架构评估及业务流程梳理中发现的**技术不一致项（歧义）**与**业务决策项**。
|
||
> **状态分类**：明确标明 `BLOCKING`（必须在编码前达成一致，否则直接阻塞实施）与 `NON_BLOCKING`（可在一期实施过程中平滑协商）。
|
||
|
||
---
|
||
|
||
## 1. DMS 官方文档自身不一致性审计 (`DMS_DOC_AMBIGUITIES`)
|
||
|
||
审计发现了 **7 项严重的文档内部矛盾与笔误**，严禁在代码中私自掩盖，必须建立兼容防御：
|
||
|
||
| # | 歧义分类 | 文档表面陈述 | 文档内部矛盾 / 真实示例数据 | 潜在隐患与对策 | 置信度状态 |
|
||
| :-: | :--- | :--- | :--- | :--- | :--- |
|
||
| 1 | **端点前缀版本** | 页面大标题与文档路径标注为 `/V1/doc/restapi.html` | 文档内所有接口地址实际路径均为 `https://dms.dmsiot.com/rest/...` 或 `/public/rest/...`，**完全没有 `/V1/` 前缀**！ | 调用若加 `/V1` 可能会报 404。需向供应商核实实际服务根路径。 | `NEEDS_VENDOR_CONFIRMATION` |
|
||
| 2 | **协议混用 (HTTP vs HTTPS)** | 绝大多数端点为 `https://...` | 楼层列表接口明确写成了 `http://dms.dmsiot.com/rest/place/floor/list` | 生产环境若强制启用 HSTS 或反向代理重定向，HTTP 可能被拒绝或发生 301 重定向。统一配置 HTTPS。 | `DOCUMENTED (Defect)` |
|
||
| 3 | **删除密码 requestType 错乱** | 文字说明定义：`3 = 删除在线密码` | 在《删除在线密码结果》的返回示例中，`data.requestType` 赫然给出了数字 `1`（1实为下发密码）！ | 若客户端强行校验返回的 `requestType == 3` 会导致对账失败。状态机只以 `operationId` 为主键比对。 | `DOCUMENTED (Defect)` |
|
||
| 4 | **二维码钥匙返回数据污染** | 标题为《生成二维码/手机钥匙》，端点存在于 `/rest/doorlock/qrcode/create` | 返回成功示例中，`typeStr` 却显示为 `"Online Card"`，且响应体**没有包含任何二维码图片Base64、URL链接或开门Token**！ | 接口存在 (`DOCUMENTED`) 但载荷残缺污染，无法直接用于移动端扫码开门。适用性归为 `NEEDS_BUSINESS_CONFIRMATION`。 | `DOCUMENTED (Defect)` |
|
||
| 5 | **注销二维码路径不一致** | 其他门锁端点均位于 `/rest/doorlock/...` 下 | 注销二维码端点地址为 `https://dms.dmsiot.com/rest/qrcode/delete`（缺少 `doorlock` 层级） | URL 路由不统一。客户端需针对该端点单独定义 Path。 | `DOCUMENTED (Defect)` |
|
||
| 6 | **开门记录路径不一致** | 其他门锁端点均位于 `/rest/doorlock/...` 下 | 开门记录端点地址为 `https://dms.dmsiot.com/rest/lock/unlock-record/list`（使用的是 `/lock/` 而非 `/doorlock/`） | URL 路由不统一。 | `DOCUMENTED (Defect)` |
|
||
| 7 | **未实现死字段 (Dead Fields)** | 网关列表返回 `lastOnlineTime: null` 与 `onlineStatus: "Offline"` | 文档直接在注释中注明：`// 在线状态，暂未实现` | 绝对不能依赖静态网关列表中的 `onlineStatus` 判定设备是否在线。 | `DOCUMENTED` |
|
||
|
||
---
|
||
|
||
## 2. 核心阻塞性问题清单 (`BLOCKING QUESTIONS - 共 6 项`)
|
||
|
||
以下 6 个关键决策直接决定数据库设计、集成网络拓扑与业务流程闭环，**必须在编码前正式定稿**：
|
||
|
||
| # | 决策核心内容 | 影响范围与备选方案 | 推荐决策结论 | 对应分类 |
|
||
| :-: | :--- | :--- | :--- | :---: |
|
||
| **Q-BLK-01** | **供应商联调测试沙箱 (Sandbox) 与实验台锁具**<br>供应商能否在联调前提供专属测试租户（独立 `appid`、`appsecret`、`projectId`）以及挂载在实验台的物理测试门锁与网关？ | 研发与测试交付<br>严禁在学员现住公寓门锁实操 | **必须提供物理实验台沙箱**，包含至少 1 台测试网关与 2 把独立测试锁。 | **A. 测试沙箱** |
|
||
| **Q-BLK-02** | **一期试点采用的主要开门钥匙类型**<br>沈阳房建公寓段一期学员开门主凭据确定采用密码还是卡片？ | 硬件投入与实施成本<br>1. 在线限时密码 (4~8位，建议6位)<br>2. 在线芯片学员卡 (需配读卡器) | **推荐选项 1（在线限时密码）**：零额外硬件成本，全软件闭环管理；实体卡作为二期备选。 | **B. 主钥匙类型** |
|
||
| **Q-BLK-03** | **门禁授权触发时点 (Grant Trigger)**<br>何时正式向智能门锁下发通行权限？ | 现场效率与出入安全<br>1. 住宿预分配完成后立即下发<br>2. **学员现场完成《报到核验》后下发**<br>3. 临近开班前定时批量下发 | **推荐选项 2（报到成功后触发）**：人已到校核验确认才给开门钥匙，防止未报到人员提早进房。 | **C. 授权时点** |
|
||
| **Q-BLK-04** | **退训与请假离校撤权规则**<br>学员中途退训或请假离校时，门锁权限如何处理？ | 公寓安防与考勤纪律<br>1. 退训：强制立即主动撤销权限<br>2. 请假：保留权限 / 临时冻结 | **推荐退训立即强制撤权**；学员短期请假物品留在宿舍，建议**默认保留权限**（需公寓方签字确认）。 | **D. 撤权规则** |
|
||
| **Q-BLK-05** | **正式环境网络链路、Base URL 与 IP 白名单**<br>沈阳机房生产服务器能否直接连通 `dms.dmsiot.com`？DMS 是否对调用方公网 IP 强制配置防火墙白名单？ | 生产网络连通性 | 优先确认生产机房出网策略，向供应商提供固定公网出口 IP 加入白名单。 | **E. 网络连通** |
|
||
| **Q-BLK-06** | **设备离线时 `validUntil` 本地过期语义 (`DMS_LOCK_OFFLINE_EXPIRY_SEMANTICS`)**<br>若门锁处于离线/断网状态，在线密码与卡片到达 `validUntil` 后，是否由锁端本地 RTC 硬件时钟强制拒绝开门？门锁电池耗尽断电、更换重启或时钟漂移时本地过期保证级别如何？ | 物理安全与离线兜底<br>公开文档未确认锁端离线过期行为 | **必须向供应商确认**：确认锁具离线 RTC 行为；系统在结训时坚决执行主动撤权 + 有效期边界双保障。 | **F. 离线过期语义** |
|
||
|
||
---
|
||
|
||
## 3. 非阻塞性技术与业务协商清单 (`NON_BLOCKING QUESTIONS`)
|
||
|
||
| # | 问题内容 | 推荐结论与技术建议 |
|
||
| :-: | :--- | :--- |
|
||
| **Q-NON-01** | **主数据权威归属**：是否使用 DMS 房间台账作为主数据覆盖本地系统？ | **坚决否决**。RailwaySystem 住宿业务台账保持本地唯一真源，DMS 仅作为设备执行端。 |
|
||
| **Q-NON-02** | **并发 QPS 阈值**：学员报到高峰期 DMS 是否有调用频次与速率限制？ | 请求供应商提供 QPS 指标；RailwaySystem 内部集成线程池平滑排队削峰。 |
|
||
| **Q-NON-03** | **异步回调 (Webhook)**：DMS 是否支持门锁执行完成后主动回调？ | 若支持则优先接入回调；一期严格以内部 10 秒对账调度器为主。 |
|
||
| **Q-NON-04** | **开门密码学员触达渠道**：密码如何安全告知学员？ | 推荐学员在移动端个人中心经二次身份验证后查看 30 秒倒计时明文，节省短信资费。 |
|
||
| **Q-NON-05** | **远程紧急开锁 (Remote Unlock)**：一期是否需要上线远程开锁？ | 属于高危控制操作，一期严格排除；仅设计两票制受控应急方案备查。 |
|
||
| **Q-NON-06** | **门锁电量与信号监控**：是否需要专门的设备运行状态大盘？ | 一期在宿舍列表表格中轻量展示电量与信号徽标，辅助宿管员排查低电量门锁。 |
|
||
|
||
---
|
||
|
||
## 4. Wave 2 架构中对未决问题的设计守则 (`Wave 2 Open Question Guards`)
|
||
在 Wave 2 适配层开发中，上述问题被严格保留为待确认事项，绝不在代码与文档中伪称已解决：
|
||
1. **门锁离线与 RTC 漂移语义**：依然待供应商提供技术规格，系统在 Adapter 与 Poller 中保持以主动撤权为主、有效期为辅的双重安全设计。
|
||
2. **真实环境 Sandbox 账号**：本 Wave 严格使用 `MockDmsServer` 动态模拟，不依赖真实 DMS 沙箱。
|
||
3. **真实错误码全集**：通过 `DmsOperationPoller.ERROR_CATEGORY_*` 抽象通用错误分类（AUTH_ERROR, NETWORK_ERROR, VENDOR_BUSINESS_ERROR, DEVICE_FAILED, DEVICE_TIMEOUT），兼容未知供应商错误。
|
||
4. **Token Cookie 头名称**：在 `DmsProperties.tokenCookieName` 中参数化配置（默认 "token"），杜绝写死猜测。
|
||
|
||
---
|
||
|
||
## 5. Wave 3A 编排层冻结之核心待决问题清单 (Wave 3A Open Questions Frozen)
|
||
在 Wave 3A 业务授权编排层落地过程中，以下 6 项核心业务与供应商技术问题被明确固化为待决事项，严禁以实现猜测替代业务确认：
|
||
|
||
### A. 学员请假是否自动撤销门禁 (`LEAVE_AUTO_REVOKE_POLICY = OPEN_QUESTION`)
|
||
- **现状**：学员请假（`status = 2`）时，当前编排器严格判定为 `NO_ACTION`，保持门禁现状不撤权。
|
||
- **业务争议**：请假期间学员个人物品仍存放于宿舍内，若自动撤销门禁，请假归来或中途取物无法进门；若不撤权，存在请假外出期间他人冒用或公寓安防真空。
|
||
- **待确认**：需公寓管理部门与培训业务处明确出台请假门禁管理细则。
|
||
|
||
### B. 在线密码交付与重置恢复策略 (`ONLINE_PASSWORD_DELIVERY_AND_RECOVERY_POLICY = OPEN_QUESTION` / `CREDENTIAL_DELIVERY_POLICY = OPEN_QUESTION`)
|
||
- **现状**：出于安全红线，系统对生成的 6 位纯数字密码明文执行零落库、零日志、零异常信息泄漏。
|
||
- **业务争议**：若系统数据库不持久化明文或可逆密文，当学员忘记密码、网络短信发送失败或管理员需要现场协助开门时，“管理员在哪里看到密码？”、“学员如何再次获取密码？”。
|
||
- **待确认**：在正式 Sandbox 联调前，需业务部门评审确认是采用“非对称加密临时暂存/查看二次鉴权”，还是“支持随时一键作废重置并重新下发新密码”。
|
||
|
||
### C. 最终门锁选择策略是否仅限单主锁 (`LOCK_SELECTION_POLICY = PRIMARY_LOCK_ONLY`)
|
||
- **现状**：Wave 3A 依据 Least Privilege 原则，严格落地 `PRIMARY_LOCK_ONLY`（0主锁阻断/1主锁放行/多主锁配置错误阻断/次锁不自动发码）。
|
||
- **业务争议**：部分宿舍可能存在套间结构（外防盗门 + 内卧室门），是否最终所有套间锁均需要自动同步下发密码（即未来 `ALL_REQUIRED_LOCKS`）。
|
||
- **待确认**：待实际宿舍楼栋智能门锁安装布设拓扑确定后终审。
|
||
|
||
### D. 真实 DMS Cookie 名称 (`TOKEN_COOKIE_NAME = VENDOR_CONFIRMATION_REQUIRED`)
|
||
- **现状**：供应商文档未正式声明传输 Cookie 的 Key 名称，代码中参数化配置为 `token`。
|
||
- **待确认**：需供应商技术人员书面核实 HTTP 请求头中的 Cookie 名称（如 `token`、`JSESSIONID`、`DMS_TOKEN` 等）。
|
||
|
||
### E. 设备离线 validUntil 与硬件 RTC 时钟漂移语义 (`DMS_LOCK_OFFLINE_EXPIRY_SEMANTICS = NEEDS_VENDOR_CONFIRMATION`)
|
||
- **现状**：系统在培训结训时统一执行主动撤权为主、有效期边界为辅策略。
|
||
- **待确认**：门锁处于断网、断电或电池耗尽更换电池导致 RTC 时钟重置时，离线本地密码过期判断的物理保证级别。
|
||
|
||
### F. 供应商沙箱联调账号与项目信息 (`DMS_SANDBOX_ENVIRONMENT = VENDOR_CONFIRMATION_REQUIRED`)
|
||
- **现状**：Wave 3A 严格在全内存 MockDmsServer 下执行 Dry-Run。
|
||
- **待确认**：供应商提供正式可连通公网测试沙箱环境的 `app_id`、`app_secret`、`project_id` 及测试门锁硬件。
|