11 KiB
11 KiB
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) 与实验台锁具 供应商能否在联调前提供专属测试租户（独立 appid、appsecret、projectId）以及挂载在实验台的物理测试门锁与网关？ |
研发与测试交付 严禁在学员现住公寓门锁实操 |
必须提供物理实验台沙箱，包含至少 1 台测试网关与 2 把独立测试锁。 | A. 测试沙箱 |
| Q-BLK-02 | 一期试点采用的主要开门钥匙类型 沈阳房建公寓段一期学员开门主凭据确定采用密码还是卡片？ |
硬件投入与实施成本 1. 在线限时密码 (4~8位，建议6位) 2. 在线芯片学员卡 (需配读卡器) |
推荐选项 1（在线限时密码）：零额外硬件成本，全软件闭环管理；实体卡作为二期备选。 | B. 主钥匙类型 |
| Q-BLK-03 | 门禁授权触发时点 (Grant Trigger) 何时正式向智能门锁下发通行权限？ |
现场效率与出入安全 1. 住宿预分配完成后立即下发 2. 学员现场完成《报到核验》后下发 3. 临近开班前定时批量下发 |
推荐选项 2（报到成功后触发）：人已到校核验确认才给开门钥匙，防止未报到人员提早进房。 | C. 授权时点 |
| Q-BLK-04 | 退训与请假离校撤权规则 学员中途退训或请假离校时，门锁权限如何处理？ |
公寓安防与考勤纪律 1. 退训：强制立即主动撤销权限 2. 请假：保留权限 / 临时冻结 |
推荐退训立即强制撤权；学员短期请假物品留在宿舍，建议默认保留权限（需公寓方签字确认）。 | D. 撤权规则 |
| Q-BLK-05 | 正式环境网络链路、Base URL 与 IP 白名单 沈阳机房生产服务器能否直接连通 dms.dmsiot.com？DMS 是否对调用方公网 IP 强制配置防火墙白名单？ |
生产网络连通性 | 优先确认生产机房出网策略，向供应商提供固定公网出口 IP 加入白名单。 | E. 网络连通 |
| Q-BLK-06 | 设备离线时 validUntil 本地过期语义 (DMS_LOCK_OFFLINE_EXPIRY_SEMANTICS)若门锁处于离线/断网状态，在线密码与卡片到达 validUntil 后，是否由锁端本地 RTC 硬件时钟强制拒绝开门？门锁电池耗尽断电、更换重启或时钟漂移时本地过期保证级别如何？ |
物理安全与离线兜底 公开文档未确认锁端离线过期行为 |
必须向供应商确认：确认锁具离线 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 适配层开发中，上述问题被严格保留为待确认事项，绝不在代码与文档中伪称已解决：
- 门锁离线与 RTC 漂移语义：依然待供应商提供技术规格，系统在 Adapter 与 Poller 中保持以主动撤权为主、有效期为辅的双重安全设计。
- 真实环境 Sandbox 账号：本 Wave 严格使用
MockDmsServer动态模拟，不依赖真实 DMS 沙箱。 - 真实错误码全集：通过
DmsOperationPoller.ERROR_CATEGORY_*抽象通用错误分类（AUTH_ERROR, NETWORK_ERROR, VENDOR_BUSINESS_ERROR, DEVICE_FAILED, DEVICE_TIMEOUT），兼容未知供应商错误。 - 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及测试门锁硬件。