blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
86e07c35e3547423ce703e10cd13293395e336b4
railwaysystem/docs/current/05-CLIENT-API-STATUS.md
T
wangzhibiao 86e07c35e3 文档维护：固化纯净库引导链与三维接口总账 
1. 查明空库真正 Bootstrap Chain：明确以 ry_20250522.sql + quartz.sql + 000_phase05_exact_schema.sql 为前置基线；
2. 纠偏 API Inventory 统计指标：确立 107 个端点、0 重复，升级为读写分离物理表调用链 (100% 源码追踪)；
3. 明确四类 API 边界：自研业务端点 107、平台端点 95、甲方端点 0、第三方端点 9、纯模拟端点 1；
4. 升级 Client API 状态模型：引入连通性、真实数据与可用性三维矩阵，实证 DMS 0 资源现状，将远程开门更正为 SECURITY_PROHIBITED；
5. 输出纯净演示数据库设计规约草案 (CLEAN_DEMO_DATABASE_SPEC.md)。
2026-09-24 00:18:15 +08:00

8.5 KiB
Raw Blame History

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

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

1. 外部接口状态模型与三维判定准则

为了杜绝“接口 HTTP 200”与“演示业务可用”之间的混淆，外部接口引入三维判定模型：

  1. 真实网络连通性 (CONNECTIVITY_STATUS)：

    • REAL_LIVE：外部真实网络畅通、凭据认证通过、成功发起 HTTP 请求并收到 200 响应；
    • CLIENT_REAL_AUTH_BLOCKED：外部网络可达，但因密钥错误或缺少角色权限被 401/403 阻断；
    • CLIENT_REAL_UNREACHABLE：外部网络不通、连接超时、域名未解析或接口已下线；
    • NOT_YET_TESTED：代码已编写适配器，但受安全红线或硬件限制尚未发起真实外网调用；
    • MOCK_SIMULATION：无外部真实服务支撑，完全由本地假数据桩或单元测试套件驱动；
    • SECURITY_PROHIBITED / OUT_OF_SCOPE：系统安全政策明确禁止实现与调用的高危接口（如远程开门）。

  2. 真实数据状态 (REAL_DATA_STATUS)：

    • REAL_DATA_AVAILABLE：真实接口返回了非空的物理硬件或业务资源数据；
    • EMPTY_DATA：真实接口返回成功，但目标列表数据量为 0（如 0 栋楼、0 间房、0 把锁）；
    • NOT_APPLICABLE：接口属于写操作、认证或禁止调用，不适用数据查询。

  3. 演示可用性 (DEMO_USABILITY)：

    • LIVE_API_BUT_NO_REAL_RESOURCE_DATA：接口虽在线但因厂商测试环境缺少物理资源，不可用于全真实数据演示；
    • MOCK_SIMULATION_REQUIRED：端到端演示必须使用受控 Mock 桩模拟硬件反馈；
    • PROHIBITED_FROM_DEMO：绝不允许在演示中调用。

2. 外部接口状态与证据矩阵表 (External API Matrix)

序号 外部接口名称 协议与端点 (API ENDPOINT) 提供方 (PROVIDER) 网络连通性 (CONNECTIVITY) 真实数据状态 (DATA_STATUS) 演示可用性 (DEMO_USABILITY) 最近验证时间 (LAST_VERIFIED_AT) 验证方式 (METHOD) 证据来源 (EVIDENCE_SOURCE) 实时返回特征 (LIVE_RESULT) 破坏性风险说明
01 DMS 第三方应用凭据获取 POST /public/rest/third-party-app/token/get DMS 厂商平台 REAL_LIVE NOT_APPLICABLE LIVE_AUTH_READY 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 厂商平台 REAL_LIVE EMPTY_DATA
(BUILDING=0)		 LIVE_API_BUT_NO_REAL_RESOURCE_DATA 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 厂商平台 REAL_LIVE EMPTY_DATA
(FLOOR=0)		 LIVE_API_BUT_NO_REAL_RESOURCE_DATA 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 厂商平台 REAL_LIVE EMPTY_DATA
(ROOM=0)		 LIVE_API_BUT_NO_REAL_RESOURCE_DATA 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 厂商平台 REAL_LIVE EMPTY_DATA
(LOCK=0)		 LIVE_API_BUT_NO_REAL_RESOURCE_DATA 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)		 NOT_APPLICABLE MOCK_SIMULATION_REQUIRED 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)		 NOT_APPLICABLE MOCK_SIMULATION_REQUIRED 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)		 NOT_APPLICABLE MOCK_SIMULATION_REQUIRED 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 厂商平台 SECURITY_PROHIBITED
(OUT_OF_SCOPE)		 NOT_APPLICABLE PROHIBITED_FROM_DEMO 2026-09-17 架构与安全红线基线审查 docs/decisions/security/ 与项目安全红线规则 历史证据表明系统安全政策严格禁止实现与调用远程开锁，未配置客户端亦未调用（非网络故障不可达，系范围外安全阻断） 极高危险：绝对禁止集成与调用
10 电子班牌实时数据推送 班牌通信端口与协议 电子班牌硬件厂商 MOCK_SIMULATION SIMULATED_DATA LOCAL_SIMULATION_READY 2026-09-20 本地数据库档案与模拟心跳更新 TrainElectronicBoardController.java 现场缺少实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩 无物理设备破坏风险

3. 统计汇总与客观边界说明

3.1 外部接口统计指标 (Task 6 对齐)

  • RAILWAYSYSTEM_CUSTOM_BUSINESS_API_COUNT：107 个（详见 04-API-INVENTORY.md）
  • RUOYI_PLATFORM_API_COUNT：95 个（底座通用管理与监控接口）
  • CLIENT_PROVIDED_API_COUNT：0 个（甲方沈阳房建公寓段自身未提供信息化接口）
  • THIRD_PARTY_API_COUNT：9 个（DMS 门锁平台接口：01~09）
  • MOCK_ONLY_INTERFACE_COUNT：1 个（电子班牌推送接口：10）

3.2 外部接口真实状态分布

  • 真实网络连通端点数 (CLIENT_API_REAL_CONNECTIVITY_COUNT)：5 个 (Token, Building, Floor, Room, Lock)
  • 真实数据非空端点数 (CLIENT_API_REAL_DATA_NONEMPTY_COUNT)：0 个 (当前真实资源数量：BUILDING=0, FLOOR=0, ROOM=0, LOCK=0)
  • 受控待测写操作端点数 (CLIENT_API_NOT_YET_TESTED_COUNT)：3 个 (密码下发、撤销、操作轮询)
  • 安全红线禁止端点数 (CLIENT_API_SECURITY_PROHIBITED_COUNT)：1 个 (远程开门)
  • 纯本地模拟桩端点数 (CLIENT_API_MOCK_COUNT)：1 个 (电子班牌)
Reference in new issue View Git Blame Copy Permalink