文档维护：纠偏现行真理中心构建源与已闭环事实
1. 明确 build_ui/ 为前端唯一构建与部署真源，RuoYi-Vue/ruoyi-ui 标记为历史归档备份； 2. 标记 ACCOM-PERM-01 为 RESOLVED_2026-09-23 已彻底闭环，内部 P0 阻断项清零； 3. 对全量 104 项内部 API 端点完成源码级表追踪 (VERIFIED_FROM_SOURCE) 与 build_ui 视图引用验证； 4. 外部 Client API 矩阵全面引入最后验证时间、验证方式、证据源与实时响应四项证据字段； 5. 更新下一阶段标准化行动路线图为严格 16 步标准流。
This commit is contained in:
wangzhibiao committed
1 parent
8ad0f5172e
commit
122a242dd0
9 files changed
+292
-233
No files matched your search
@@ -1,35 +1,41 @@
|
||||
# 05 - 甲方与外部接口状态清单 (Client API Status)
|
||||
|
||||
> **最高原则**：**严禁将模拟桩 (Mock) 误报为真实在线 (REAL_LIVE)！**
|
||||
> 本文件仅收录甲方、外部硬件厂商或第三方提供的外部接口，客观记录网络连通、鉴权及数据可用性真实状态。
|
||||
> **安全红线**：当前阶段**严禁发起任何破坏性写操作 (Mutation)**。
|
||||
> 任何标记为 `CLIENT_REAL_LIVE` 的接口，必须严格具备真实联调证据来源（`EVIDENCE_SOURCE`）与可查验的实时返回结果（`LIVE_RESULT`）。
|
||||
> **安全红线**：当前阶段**严禁发起任何未经授权的破坏性写操作 (Mutation)**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 外部接口状态枚举定义
|
||||
## 1. 外部接口状态枚举与证据分级
|
||||
|
||||
- **`CLIENT_REAL_LIVE`**：外部真实网络畅通、账号鉴权通过、只读调用成功并返回符合契约的数据结构；
|
||||
- **`CLIENT_REAL_AUTH_BLOCKED`**：外部网络可达，但因密钥错误、账号锁定或缺少权限被 401/403 阻断；
|
||||
- **`CLIENT_REAL_UNREACHABLE`**：外部网络不通、连接超时、域名未解析或接口已被外部下线；
|
||||
- **`NOT_YET_TESTED`**：代码已编写适配器，但尚未在当前真实网络中发起调用，或受安全红线禁止调用；
|
||||
- **`MOCK_SIMULATION`**：无外部真实服务支撑，当前完全由本地假数据桩或仿真测试套件驱动。
|
||||
- **状态枚举 (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 码、响应字段摘要、数据量）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 外部接口状态全量盘点表
|
||||
## 2. 外部接口状态与证据矩阵表
|
||||
|
||||
| 序号 | 外部接口名称 | 协议与端点 (API ENDPOINT) | 提供方 (PROVIDER) | 真实状态判定 (STATUS) | 真实返回特征与依据 | 破坏性风险与限制 |
|
||||
| :---: | :--- | :--- | :--- | :---: | :--- | :--- |
|
||||
| **01** | **DMS 第三方应用凭据获取** | `POST /public/rest/third-party-app/token/get` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 局域网真实环境探测通过；凭据有效返回 Cookie Token 与 7200 秒 TTL，支持并发 DCL 单例刷新。 | 只读鉴权，无破坏性风险。 |
|
||||
| **02** | **DMS 建筑空间列表查询** | `POST /rest/place/building/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；返回 HTTP 200，响应结构包含 code/data，**当前实际返回数据量为 0 (`[]`)**。 | 只读查询，安全。 |
|
||||
| **03** | **DMS 楼层空间列表查询** | `POST /rest/place/floor/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；返回 HTTP 200，**当前实际返回数据量为 0 (`[]`)**。 | 只读查询，安全。 |
|
||||
| **04** | **DMS 房间空间列表查询** | `POST /rest/place/room/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；返回 HTTP 200，**当前实际返回数据量为 0 (`[]`)**。 | 只读查询，安全。 |
|
||||
| **05** | **DMS 智能门锁设备列表查询** | `POST /rest/doorlock/list` | DMS 门锁厂商平台 | **`CLIENT_REAL_LIVE`** | 鉴权后网络可达；按空间 ID 检索返回空列表，**当前挂载门锁数为 0**。 | 只读查询，安全。 |
|
||||
| **06** | **DMS 在线密码下发 (Mutation)** | `POST /rest/doorlock/online-password-key/create`| DMS 门锁厂商平台 | **`NOT_YET_TESTED`**<br>(本地单元测试为 `MOCK_SIMULATION`) | 在本地 MockServer 验证通过并取得 operationId；**真实环境因无指定测试门锁，当前执行禁止策略 (`REAL_DMS_MUTATION_COUNT = 0`)**。 | **写操作**：严禁向未知门锁发起下发，待甲方正式划拨指定硬件后测试。 |
|
||||
| **07** | **DMS 在线密码撤销 (Mutation)** | `POST /rest/doorlock/online-password-key/delete`| DMS 门锁厂商平台 | **`NOT_YET_TESTED`**<br>(本地单元测试为 `MOCK_SIMULATION`) | 在本地 MockServer 验证通过；真实环境禁止调用。 | **写操作**：同上。 |
|
||||
| **08** | **DMS 异步操作状态轮询** | `POST /rest/doorlock/operation/status` | DMS 门锁厂商平台 | **`NOT_YET_TESTED`**<br>(本地单元测试为 `MOCK_SIMULATION`) | 代码具备轮询器 (`DmsOperationPoller`)；由于未下发真实密码，无真实 operationId 供轮询。 | 只读轮询，安全。 |
|
||||
| **09** | **DMS 远程开门 (Remote Unlock)** | 门锁远程触发开门接口 | DMS 门锁厂商平台 | **`CLIENT_REAL_UNREACHABLE`**<br>(`OUT_OF_CURRENT_SCOPE`) | 生产与试用安全红线：**系统严禁集成任何远程开锁 API**，未进行任何路由配置与适配器实现。 | **极高危险**：绝对禁止调用。 |
|
||||
| **10** | **电子班牌实时数据推送** | 班牌通信端口与协议 | 电子班牌硬件厂商 | **`MOCK_SIMULATION`** | 甲方现场尚未提供实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩。 | 无物理设备破坏风险。 |
|
||||
| 序号 | 外部接口名称 | 协议与端点 (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` | 现场缺少实际联网电子班牌设备；系统当前在数据库记录心跳时间与班牌档案，通信属于模拟桩 | 无物理设备破坏风险 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user