blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
122a242dd0ea408fe1f02183ea5b84a13937cdd1
railwaysystem/docs/current/05-CLIENT-API-STATUS.md
T
wangzhibiao 122a242dd0 文档维护：纠偏现行真理中心构建源与已闭环事实 
1. 明确 build_ui/ 为前端唯一构建与部署真源，RuoYi-Vue/ruoyi-ui 标记为历史归档备份；
2. 标记 ACCOM-PERM-01 为 RESOLVED_2026-09-23 已彻底闭环，内部 P0 阻断项清零；
3. 对全量 104 项内部 API 端点完成源码级表追踪 (VERIFIED_FROM_SOURCE) 与 build_ui 视图引用验证；
4. 外部 Client API 矩阵全面引入最后验证时间、验证方式、证据源与实时响应四项证据字段；
5. 更新下一阶段标准化行动路线图为严格 16 步标准流。
2026-09-24 00:03:47 +08:00

6.7 KiB
Raw Blame History

05 - 甲方与外部接口状态清单 (Client API Status)

最高原则：严禁将模拟桩 (Mock) 误报为真实在线 (REAL_LIVE)！ 任何标记为 CLIENT_REAL_LIVE 的接口，必须严格具备真实联调证据来源（EVIDENCE_SOURCE）与可查验的实时返回结果（LIVE_RESULT）。 安全红线：当前阶段严禁发起任何未经授权的破坏性写操作 (Mutation)。

1. 外部接口状态枚举与证据分级

  • 状态枚举 (STATUS)：
    • CLIENT_REAL_LIVE：外部真实网络畅通、凭据认证通过、在真实网络环境下成功发起调用并返回符合契约的数据报文；
    • CLIENT_REAL_AUTH_BLOCKED：外部网络可达，但因密钥错误、凭据失效或缺少角色权限被 401/403 阻断；
    • CLIENT_REAL_UNREACHABLE：外部网络不通、连接超时、域名未解析或接口已下线；
    • NOT_YET_TESTED：代码已编写适配器，但受安全红线约束或缺少设备资源，尚未在真实网络发起调用；
    • MOCK_SIMULATION：无外部真实服务支撑，完全由本地假数据桩或单元测试套件仿真驱动。
  • 证据属性要求：
    • LAST_VERIFIED_AT：最近一次真实验证日期；
    • VERIFICATION_METHOD：验证方式（如真实局域网 HTTP 探测、MockServer 契约测试等）；
    • EVIDENCE_SOURCE：可核验的原始凭证路径；
    • LIVE_RESULT：真实调用返回特征（HTTP 码、响应字段摘要、数据量）。

2. 外部接口状态与证据矩阵表

序号 外部接口名称 协议与端点 (API ENDPOINT) 提供方 (PROVIDER) 真实状态判定 (STATUS) 最近验证时间 (LAST_VERIFIED_AT) 验证方式 (VERIFICATION_METHOD) 证据来源 (EVIDENCE_SOURCE) 真实返回特征 (LIVE_RESULT) 破坏性风险说明
01 DMS 第三方应用凭据获取 POST /public/rest/third-party-app/token/get DMS 门锁厂商平台 CLIENT_REAL_LIVE 2026-09-17 真实网络 HTTP POST 携带有效 AppId/Secret 探测 docs/reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/dms-final-status.md HTTP 200，取得有效 Token，expires_in: 7200，Cookie Token 认证机制验证通过 只读认证，无破坏性风险
02 DMS 建筑空间列表查询 POST /rest/place/building/list DMS 门锁厂商平台 CLIENT_REAL_LIVE 2026-09-17 真实网络携带 Cookie Token 发起 POST 查询 docs/reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/dms-final-status.md HTTP 200，外层 JSON 符合契约，列表数据量为 0 (BUILDING=0) 只读查询，安全
03 DMS 楼层空间列表查询 POST /rest/place/floor/list DMS 门锁厂商平台 CLIENT_REAL_LIVE 2026-09-17 真实网络携带 Cookie Token 发起 POST 查询 docs/reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/dms-final-status.md HTTP 200，外层 JSON 符合契约，列表数据量为 0 (FLOOR=0) 只读查询，安全
04 DMS 房间空间列表查询 POST /rest/place/room/list DMS 门锁厂商平台 CLIENT_REAL_LIVE 2026-09-17 真实网络携带 Cookie Token 发起 POST 查询 docs/reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/dms-final-status.md HTTP 200，外层 JSON 符合契约，列表数据量为 0 (ROOM=0) 只读查询，安全
05 DMS 智能门锁设备列表查询 POST /rest/doorlock/list DMS 门锁厂商平台 CLIENT_REAL_LIVE 2026-09-17 真实网络携带 Cookie Token 发起 POST 查询 docs/reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/dms-final-status.md HTTP 200，外层 JSON 符合契约，挂载门锁数为 0 (LOCK=0) 只读查询，安全
06 DMS 在线密码下发 (Mutation) POST /rest/doorlock/online-password-key/create DMS 门锁厂商平台 NOT_YET_TESTED
(本地测试为 MOCK_SIMULATION)		 2026-09-17 (Mock) 本地 MockServer 单元契约测试 (MockDmsServer.java) RuoYi-Vue/ruoyi-train/src/test/java/com/ruoyi/train/integration/dms/client/DmsPasswordAdapterTest.java 真实环境因无指定房间与锁具，禁止发起调用 (REAL_DMS_MUTATION_COUNT = 0)；Mock 环境返回模拟 operationId 写操作：严禁向未知门锁发起下发，待划拨测试硬件后联调
07 DMS 在线密码撤销 (Mutation) POST /rest/doorlock/online-password-key/delete DMS 门锁厂商平台 NOT_YET_TESTED
(本地测试为 MOCK_SIMULATION)		 2026-09-17 (Mock) 本地 MockServer 单元契约测试 RuoYi-Vue/ruoyi-train/src/test/java/com/ruoyi/train/integration/dms/client/DmsPasswordAdapterTest.java 真实环境未调用；Mock 环境成功模拟撤销响应 写操作：严禁向未知设备发起撤销
08 DMS 异步操作状态轮询 POST /rest/doorlock/operation/status DMS 门锁厂商平台 NOT_YET_TESTED
(本地测试为 MOCK_SIMULATION)		 2026-09-17 (Mock) 本地 MockServer 轮询测试 (DmsOperationStatusAdapterTest.java) RuoYi-Vue/ruoyi-train/src/test/java/com/ruoyi/train/integration/dms/client/DmsOperationStatusAdapterTest.java 真实环境无有效 operationId 供轮询；Mock 仿真状态机轮询成功 只读轮询，安全
09 DMS 远程开门 (Remote Unlock) 门锁远程触发开门接口 DMS 门锁厂商平台 CLIENT_REAL_UNREACHABLE
(OUT_OF_CURRENT_SCOPE)		 2026-09-17 架构与安全红线基线审查 docs/decisions/security/ 与项目安全红线规则 系统严禁集成任何远程开锁 API，未进行网络配置与客户端实现 极高危险：绝对禁止集成与调用
10 电子班牌实时数据推送 班牌通信端口与协议 电子班牌硬件厂商 MOCK_SIMULATION 2026-09-20 本地数据库档案与模拟心跳更新 TrainElectronicBoardController.java 现场缺少实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩 无物理设备破坏风险

3. 外部接口联调与解锁条件 (Unblocking Criteria)

针对当前处于 NOT_YET_TESTED 与 BLOCKED_EXTERNAL 的接口，解除受限状态必须满足以下前置条件：

  1. 真实硬件设备划拨：由沈阳房建公寓段主管领导或厂商指派具体的、通电的、物理隔离的 真实测试房间与门锁编号；
  2. 测试授权协议签署：明确现场测试期间密码下发与冲正补偿的法律责任边界；
  3. 禁止自动化无限制重试：写操作调用必须保持 Single-Flight，超时严禁无限制自动重发，必须走人工或受控冲正通道。
Reference in new issue View Git Blame Copy Permalink