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

文档维护：固化纯净库引导链与三维接口总账

Browse Source 
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)。
This commit is contained in:
wangzhibiao committed 2026-09-24 00:18:15 +08:00
1 parent 122a242dd0
commit 86e07c35e3
6 files changed
+440 -243
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/current/05-CLIENT-API-STATUS.md
+49 -32
View File
@@ -1,47 +1,64 @@
# 05 - 甲方与外部接口状态清单 (Client API Status)
> **最高原则**：**严禁将模拟桩 (Mock) 误报为真实在线 (REAL_LIVE)！**
> 任何标记为 `CLIENT_REAL_LIVE` 的接口，必须严格具备真实联调证据来源（`EVIDENCE_SOURCE`）与可查验的实时返回结果（`LIVE_RESULT`）。
> **安全红线**：当前阶段**严禁发起任何未经授权的破坏性写操作 (Mutation)**。
> 任何标记为 `REAL_LIVE` 的接口，必须严格具备真实联调证据来源（`EVIDENCE_SOURCE`）与可查验的实时返回结果（`LIVE_RESULT`）。
> **安全红线**：当前阶段**严禁发起任何未经授权的破坏性写操作 (Mutation)**；安全政策禁止集成的接口明确标记为 `SECURITY_PROHIBITED`。
---
## 1. 外部接口状态枚举与证据分级
## 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 码、响应字段摘要、数据量）。
为了杜绝“接口 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. 外部接口状态与证据矩阵表
## 2. 外部接口状态与证据矩阵表 (External API Matrix)
| 序号 | 外部接口名称 | 协议与端点 (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`**<br>(本地测试为 `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`**<br>(本地测试为 `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`**<br>(本地测试为 `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`**<br>(`OUT_OF_CURRENT_SCOPE`) | 2026-09-17 | 架构与安全红线基线审查 | `docs/decisions/security/` 与项目安全红线规则 | 系统严禁集成任何远程开锁 API，未进行网络配置与客户端实现 | **极高危险**：绝对禁止集成与调用 |
| **10** | **电子班牌实时数据推送** | 班牌通信端口与协议 | 电子班牌硬件厂商 | **`MOCK_SIMULATION`** | 2026-09-20 | 本地数据库档案与模拟心跳更新 | `TrainElectronicBoardController.java` | 现场缺少实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩 | 无物理设备破坏风险 |
| 序号 | 外部接口名称 | 协议与端点 (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. 外部接口联调与解锁条件 (Unblocking Criteria)
## 3. 统计汇总与客观边界说明
针对当前处于 `NOT_YET_TESTED` 与 `BLOCKED_EXTERNAL` 的接口，解除受限状态必须满足以下前置条件：
1. **真实硬件设备划拨**：由沈阳房建公寓段主管领导或厂商指派具体的、通电的、物理隔离的 **真实测试房间与门锁编号**；
2. **测试授权协议签署**：明确现场测试期间密码下发与冲正补偿的法律责任边界；
3. **禁止自动化无限制重试**：写操作调用必须保持 Single-Flight，超时严禁无限制自动重发，必须走人工或受控冲正通道。
### 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 个 (电子班牌)