wangzhibiao
8ad0f5172e
docs: bootstrap canonical current truth portal (00-START-HERE through 08-NEXT-ACTIONS)
4.9 KiB
4.9 KiB
05 - 甲方与外部接口状态清单 (Client API Status)
最高原则：严禁将模拟桩 (Mock) 误报为真实在线 (REAL_LIVE)！ 本文件仅收录甲方、外部硬件厂商或第三方提供的外部接口，客观记录网络连通、鉴权及数据可用性真实状态。 安全红线：当前阶段严禁发起任何破坏性写操作 (Mutation)。
1. 外部接口状态枚举定义
CLIENT_REAL_LIVE：外部真实网络畅通、账号鉴权通过、只读调用成功并返回符合契约的数据结构；CLIENT_REAL_AUTH_BLOCKED：外部网络可达，但因密钥错误、账号锁定或缺少权限被 401/403 阻断；CLIENT_REAL_UNREACHABLE：外部网络不通、连接超时、域名未解析或接口已被外部下线；NOT_YET_TESTED：代码已编写适配器，但尚未在当前真实网络中发起调用，或受安全红线禁止调用；MOCK_SIMULATION：无外部真实服务支撑，当前完全由本地假数据桩或仿真测试套件驱动。
2. 外部接口状态全量盘点表
| 序号 | 外部接口名称 | 协议与端点 (API ENDPOINT) | 提供方 (PROVIDER) | 真实状态判定 (STATUS) | 真实返回特征与依据 | 破坏性风险与限制 |
|---|---|---|---|---|---|---|
| 01 | DMS 第三方应用凭据获取 | POST /public/rest/third-party-app/token/get |
DMS 门锁厂商平台 | CLIENT_REAL_LIVE |
局域网真实环境探测通过；凭据有效返回 Cookie Token 与 7200 秒 TTL，支持并发 DCL 单例刷新。 | 只读鉴权，无破坏性风险。 |
| 02 | DMS 建筑空间列表查询 | POST /rest/place/building/list |
DMS 门锁厂商平台 | CLIENT_REAL_LIVE |
鉴权后网络可达；返回 HTTP 200，响应结构包含 code/data，当前实际返回数据量为 0 ([])。 |
只读查询，安全。 |
| 03 | DMS 楼层空间列表查询 | POST /rest/place/floor/list |
DMS 门锁厂商平台 | CLIENT_REAL_LIVE |
鉴权后网络可达；返回 HTTP 200，当前实际返回数据量为 0 ([])。 |
只读查询，安全。 |
| 04 | DMS 房间空间列表查询 | POST /rest/place/room/list |
DMS 门锁厂商平台 | CLIENT_REAL_LIVE |
鉴权后网络可达；返回 HTTP 200，当前实际返回数据量为 0 ([])。 |
只读查询，安全。 |
| 05 | DMS 智能门锁设备列表查询 | POST /rest/doorlock/list |
DMS 门锁厂商平台 | CLIENT_REAL_LIVE |
鉴权后网络可达；按空间 ID 检索返回空列表，当前挂载门锁数为 0。 | 只读查询，安全。 |
| 06 | DMS 在线密码下发 (Mutation) | POST /rest/doorlock/online-password-key/create |
DMS 门锁厂商平台 | NOT_YET_TESTED(本地单元测试为 MOCK_SIMULATION) |
在本地 MockServer 验证通过并取得 operationId；真实环境因无指定测试门锁，当前执行禁止策略 (REAL_DMS_MUTATION_COUNT = 0)。 |
写操作：严禁向未知门锁发起下发，待甲方正式划拨指定硬件后测试。 |
| 07 | DMS 在线密码撤销 (Mutation) | POST /rest/doorlock/online-password-key/delete |
DMS 门锁厂商平台 | NOT_YET_TESTED(本地单元测试为 MOCK_SIMULATION) |
在本地 MockServer 验证通过；真实环境禁止调用。 | 写操作：同上。 |
| 08 | DMS 异步操作状态轮询 | POST /rest/doorlock/operation/status |
DMS 门锁厂商平台 | NOT_YET_TESTED(本地单元测试为 MOCK_SIMULATION) |
代码具备轮询器 (DmsOperationPoller)；由于未下发真实密码，无真实 operationId 供轮询。 |
只读轮询，安全。 |
| 09 | DMS 远程开门 (Remote Unlock) | 门锁远程触发开门接口 | DMS 门锁厂商平台 | CLIENT_REAL_UNREACHABLE( OUT_OF_CURRENT_SCOPE) |
生产与试用安全红线：系统严禁集成任何远程开锁 API，未进行任何路由配置与适配器实现。 | 极高危险：绝对禁止调用。 |
| 10 | 电子班牌实时数据推送 | 班牌通信端口与协议 | 电子班牌硬件厂商 | MOCK_SIMULATION |
甲方现场尚未提供实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩。 | 无物理设备破坏风险。 |
3. 外部接口联调与解锁条件 (Unblocking Criteria)
针对当前处于 NOT_YET_TESTED 与 BLOCKED_EXTERNAL 的接口，解除受限状态必须满足以下前置条件：
- 真实硬件设备划拨：由沈阳房建公寓段主管领导或厂商指派具体的、通电的、物理隔离的 真实测试房间与门锁编号；
- 测试授权协议签署：明确现场测试期间密码下发与冲正补偿的法律责任边界；
- 禁止自动化无限制重试：写操作调用必须保持 Single-Flight，超时严禁无限制自动重发，必须走人工或受控冲正通道。