railwaysystem/docs/current/05-CLIENT-API-STATUS.md

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

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

---

## 1. 契约来源与提供方概念分离 (Task A & Task E)

根据项目负责人裁定，系统严格区分**契约来源**与**服务运营提供方**：
- **`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. 契约路径冲突排查与审计结论 (Task C)

对历史文档中曾出现的契约路径漂移展开全工程源码与测试桩穿透检查：

| 业务项 | 甲方契约路径 (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. 四层 DMS 集成覆盖矩阵 (Task D — 4-Tier Integration Matrix)

涵盖甲方原始契约中全部 27 个唯一接口，穿透追踪：
```text
CLIENT CONTRACT API → RAILWAYSYSTEM ADAPTER / CLIENT → RAILWAYSYSTEM INTERNAL API → RUNTIME VERIFICATION
```

| 序号 | 甲方契约接口 (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_AUTH_SUCCESS` | 真实外网 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_RESOURCE_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_RESOURCE_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_RESOURCE_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_RESOURCE_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_AUTH_SUCCESS`**：**1 项**（Token 鉴权接口，真实外网 HTTP 200，取得有效 Token `expires_in: 7200`，Cookie Token 认证通过）
- **`REAL_LIVE_WITH_RESOURCE_DATA`**：**0 项**（厂商测试环境无真实业务资源数据）
- **`REAL_LIVE_EMPTY_RESOURCE_DATA`**：**4 项**（Building, Floor, Room, Lock 读接口，外网 HTTP 200 返回符合契约的空列表）
- **`MOCK_ONLY_COUNT`**：**3 项**（在线密码下发、撤销、异步操作状态轮询）
- **`SECURITY_PROHIBITED_COUNT`**：**1 项**（远程开锁）
- **`NOT_YET_TESTED_COUNT`**：**18 项**