58 lines
8.2 KiB
Markdown
58 lines
8.2 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"），杜绝写死猜测。
|