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

65 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`**<br>(`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`**<br>(`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`**<br>(`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`**<br>(`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`**<br>(本地单测为 `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`**<br>(本地单测为 `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`**<br>(本地单测为 `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`**<br>(`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