blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档维护：校准甲方DMS接口契约与后端物理调用链

Browse Source
This commit is contained in:
wangzhibiao committed 2026-09-24 00:40:58 +08:00
1 parent 86e07c35e3
commit b97622c1d1
7 files changed
+324 -200
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/current/05-CLIENT-API-STATUS.md
+68 -46
View File
@@ -6,59 +6,81 @@
---
## 1. 外部接口状态模型与三维判定准则
## 1. 契约来源与提供方概念分离 (Task A & Task E)
为了杜绝“接口 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`**：绝不允许在演示中调用。
根据项目负责人裁定，系统严格区分**契约来源**与**服务运营提供方**：
- **`CLIENT_PROVIDED_API_COUNT = 27`**：甲方正式交付给项目的完整 DMS 外部接口契约中 unique METHOD + PATH 数量（详见 [05A-CLIENT-PROVIDED-API-CATALOG.md](05A-CLIENT-PROVIDED-API-CATALOG.md)）；
- **`DMS_VENDOR_API_COUNT = 27`**：上述 27 个接口均由 DMS 门锁物联网厂商平台托管运营；
- 严禁再以“服务商为第三方厂商”为由将甲方交付契约排除在 `CLIENT_PROVIDED_API` 统计之外。
---
## 2. 外部接口状态与证据矩阵表 (External API Matrix)
## 2. 契约路径冲突排查与审计结论 (Task C)
| 序号 | 外部接口名称 | 协议与端点 (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` | 现场缺少实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩 | 无物理设备破坏风险 |
对历史文档中曾出现的契约路径漂移展开全工程源码与测试桩穿透检查：
| 业务项 | 甲方契约路径 (CONTRACT_PATH) | 源码客户端路径 (CURRENT_CODE_PATH) | 本地Mock桩路径 (CURRENT_MOCK_PATH) | 历史文档路径 (CURRENT_DOC_PATH) | 源码契约一致性 (MATCH) | 缺陷裁决说明 |
| :--- | :--- | :--- | :--- | :--- | :---: | :--- |
| **在线密码删除** | `POST /rest/doorlock/online-password/delete` | `POST /rest/doorlock/online-password/delete`<br>(`DmsPasswordClient.java:89`) | `POST /rest/doorlock/online-password/delete`<br>(`MockDmsServer.java:286`) | `POST /rest/doorlock/online-password-key/delete`<br>(旧版 05 文档) | **YES** | **文档漂移笔误**。生产代码与 Mock 代码完全符合甲方真实契约，无需修改代码，已纠正文档。 |
| **操作状态查询** | `POST /rest/doorlock/query-operation-status` | `POST /rest/doorlock/query-operation-status`<br>(`DmsOperationStatusClient.java:33`) | `POST /rest/doorlock/query-operation-status`<br>(`MockDmsServer.java:316`) | `POST /rest/doorlock/operation/status`<br>(旧版 05 文档) | **YES** | **文档漂移笔误**。生产代码与 Mock 代码完全符合甲方真实契约，无需修改代码，已纠正文档。 |
- **`CLIENT_CONTRACT_MISMATCH_COUNT`**：**0 项**（后端产品代码与甲方原始接口契约保持 100% 严格一致）。
---
## 3. 统计汇总与客观边界说明
## 3. 四层 DMS 集成覆盖矩阵 (Task D — 4-Tier Integration Matrix)
### 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）
涵盖甲方原始契约中全部 27 个唯一接口，穿透追踪：
```text
CLIENT CONTRACT API → RAILWAYSYSTEM ADAPTER / CLIENT → RAILWAYSYSTEM INTERNAL API → RUNTIME VERIFICATION
```
### 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 个 (电子班牌)
| 序号 | 甲方契约接口 (CLIENT_API) | 适配器类 (ADAPTER_CLASS) | 适配器方法 (ADAPTER_METHOD) | 对应内部接口 (INTERNAL_API) | 实现状态 (IMPLEMENTATION_STATUS) | 真实测试状态 (REAL_TEST_STATUS) | 实时返回特征与证据 (REAL_RESULT) | 演示可用性 (DEMO_USABILITY) |
| :---: | :--- | :--- | :--- | :--- | :---: | :---: | :--- | :---: |
| **01** | `POST /public/rest/third-party-app/token/get` | `DmsTokenClient` | `obtainToken` | `DmsClient / DmsProperties` (底层服务) | `IMPLEMENTED` | `REAL_LIVE_EMPTY_DATA` | 真实外网 HTTP 200，取得有效 Token (`expires_in: 7200`)，Cookie Token 认证通过 | `LIVE_AUTH_READY` |
| **02** | `POST /public/rest/security/logout` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 未封装客户端；Token 自然过期或会话替换 | `NOT_APPLICABLE` |
| **03** | `POST /rest/place/building/list` | `DmsPlaceClient` | `listBuildings` | `N/A` (集成探测) | `IMPLEMENTED` | `REAL_LIVE_EMPTY_DATA` | 真实外网 HTTP 200，返回 JSON 结构符合契约，数据量为 0 (`BUILDING=0`) | `LIVE_API_BUT_NO_REAL_RESOURCE_DATA` |
| **04** | `POST /rest/place/floor/list` | `DmsPlaceClient` | `listFloors` | `N/A` (集成探测) | `IMPLEMENTED` | `REAL_LIVE_EMPTY_DATA` | 真实外网 HTTP 200，返回 JSON 结构符合契约，数据量为 0 (`FLOOR=0`) | `LIVE_API_BUT_NO_REAL_RESOURCE_DATA` |
| **05** | `POST /rest/place/room/list` | `DmsPlaceClient` | `listRooms` | `N/A` (集成探测) | `IMPLEMENTED` | `REAL_LIVE_EMPTY_DATA` | 真实外网 HTTP 200，返回 JSON 结构符合契约，数据量为 0 (`ROOM=0`) | `LIVE_API_BUT_NO_REAL_RESOURCE_DATA` |
| **06** | `POST /rest/place/room/get` | `DmsPlaceClient` | `getRoom` | `N/A` | `PARTIAL` | `NOT_YET_TESTED` | 部分实现，待真实环境具备房间资源后完整测试 | `NOT_APPLICABLE` |
| **07** | `POST /rest/gateway/list` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 网关级运维接口，由厂商后台维护，非学员住宿业务范围 | `PROHIBITED_FROM_DEMO` |
| **08** | `POST /rest/gateway/refresh-online-status` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 网关级运维接口，非学员培训管理范围 | `PROHIBITED_FROM_DEMO` |
| **09** | `POST /rest/gateway/query-online-status` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 网关级运维接口，非学员培训管理范围 | `PROHIBITED_FROM_DEMO` |
| **10** | `POST /rest/doorlock/list` | `DmsDoorLockClient` | `listDoorLocks` | `N/A` (集成探测) | `IMPLEMENTED` | `REAL_LIVE_EMPTY_DATA` | 真实外网 HTTP 200，返回 JSON 结构符合契约，挂载门锁数为 0 (`LOCK=0`) | `LIVE_API_BUT_NO_REAL_RESOURCE_DATA` |
| **11** | `POST /rest/doorlock/query-lock-battery` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 批量电池与信号查询，本期暂未接入 | `NOT_APPLICABLE` |
| **12** | `POST /rest/doorlock/remote-unlock` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `SECURITY_PROHIBITED` | 系统安全红线绝对禁止远程开锁，未配置客户端亦严禁调用 | `PROHIBITED_FROM_DEMO` |
| **13** | `POST /rest/doorlock/query-operation-status` | `DmsOperationStatusClient` | `queryStatus` | `GET /train/access/operations/{doorAuthId}` | `IMPLEMENTED` | `MOCK_ONLY` | 本地 MockServer 状态机测试通过；真实外网因无真实 operationId 待硬件划拨 | `MOCK_SIMULATION_REQUIRED` |
| **14** | `POST /rest/doorlock/online-password-key/create` | `DmsPasswordClient` | `createOnlinePassword` | `POST /train/access/auth/{authId}/issue` | `IMPLEMENTED` | `MOCK_ONLY` | Mock 测试通过，返回模拟 operationId；真实环境因无测试硬件阻断写操作调用 | `MOCK_SIMULATION_REQUIRED` |
| **15** | `POST /rest/doorlock/online-password/delete` | `DmsPasswordClient` | `deleteOnlinePassword` | `POST /train/access/auth/{authId}/revoke` | `IMPLEMENTED` | `MOCK_ONLY` | Mock 测试通过；真实环境未对未知设备发起真实撤销调用 | `MOCK_SIMULATION_REQUIRED` |
| **16** | `POST /rest/doorlock/offline-password/create` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 离线密码算法申请，本期网络门锁采用在线密码策略 | `NOT_APPLICABLE` |
| **17** | `POST /rest/doorlock/offline-password-key/create`| `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 离线密码钥匙生成，本期暂未接入 | `NOT_APPLICABLE` |
| **18** | `POST /rest/doorlock/online-card/create` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 在线卡片下发，本期优先下发在线时效密码 | `NOT_APPLICABLE` |
| **19** | `POST /rest/doorlock/online-card/delete` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 在线卡片删除，本期暂未接入 | `NOT_APPLICABLE` |
| **20** | `POST /rest/doorlock/qrcode/create` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 二维码/手机钥匙生成，本期暂未接入 | `NOT_APPLICABLE` |
| **21** | `POST /rest/qrcode/delete` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 二维码/手机钥匙注销，本期暂未接入 | `NOT_APPLICABLE` |
| **22** | `POST /rest/doorlock/offline-card/create` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 需现场物理读卡器DLL发卡，非本期网络远程开锁范围 | `PROHIBITED_FROM_DEMO` |
| **23** | `POST /rest/lock/unlock-record/list` | `N/A` | `N/A` | `N/A` | `NOT_IMPLEMENTED` | `NOT_YET_TESTED` | 开门流水记录拉取，本期暂未集成 | `NOT_APPLICABLE` |
| **24** | `POST /rest/powerswitch/list` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 取电开关硬件列表，非学员培训业务范围 | `PROHIBITED_FROM_DEMO` |
| **25** | `POST /rest/powerswitch/remote-poweron` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 远程送电强电控制，非学员培训管理范围 | `PROHIBITED_FROM_DEMO` |
| **26** | `POST /rest/powerswitch/remote-poweroff` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 远程断电强电控制，非学员培训管理范围 | `PROHIBITED_FROM_DEMO` |
| **27** | `POST /rest/powerswitch/query-operation-status` | `N/A` | `N/A` | `N/A` | `INTENTIONALLY_OUT_OF_SCOPE` | `NOT_YET_TESTED` | 取电开关操作状态轮询，非学员培训管理范围 | `PROHIBITED_FROM_DEMO` |
---
## 4. 统计汇总与客观边界说明
### 4.1 甲方接口实现与范围分布
- **`CLIENT_PROVIDED_API_COUNT`**：**27 个**
- **`DMS_VENDOR_API_COUNT`**：**27 个**
- **`RAILWAYSYSTEM_IMPLEMENTED_CLIENT_API_COUNT`**：**8 个**（Token, Building, Floor, Room, Lock, Password create, Password delete, Query op status）
- **`RAILWAYSYSTEM_PARTIAL_CLIENT_API_COUNT`**：**1 个**（Room get）
- **`RAILWAYSYSTEM_NOT_IMPLEMENTED_CLIENT_API_COUNT`**：**9 个**（Logout, Lock battery, Offline pwd x2, Online card x2, QR x2, Unlock record）
- **`RAILWAYSYSTEM_OUT_OF_SCOPE_CLIENT_API_COUNT`**：**9 个**（Gateway x3, Remote unlock x1, Offline card x1, Powerswitch x4）
- **`CLIENT_CONTRACT_MISMATCH_COUNT`**：**0 个**
### 4.2 真实运行验证状态分布 (`REAL_TEST_STATUS`)
- **`REAL_LIVE_WITH_DATA_COUNT`**：**0 个**（厂商测试环境无真实业务数据）
- **`REAL_LIVE_EMPTY_DATA_COUNT`**：**5 个**（Token, Building, Floor, Room, Lock）
- **`MOCK_ONLY_COUNT`**：**3 个**（在线密码下发、撤销、异步操作状态轮询）
- **`SECURITY_PROHIBITED_COUNT`**：**1 个**（远程开锁）
- **`NOT_YET_TESTED_COUNT`**：**18 个**