blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
39f633528ce82e042efc729013eabeb256d65558
railwaysystem/docs/current/05A-CLIENT-PROVIDED-API-CATALOG.md
T

74 lines
10 KiB
Markdown
Raw Normal View History

文档维护：校准甲方DMS接口契约与后端物理调用链
2026-09-24 00:40:58 +08:00
# 05A - 甲方提供外部接口总账 (Client-Provided API Catalog)
> **契约来源定义 (Task A & Task E)**：
> 1. 本文档为**甲方（沈阳房建公寓段）向本项目提供的完整原始接口契约总账**；
> 2. 严格区分契约来源与实际服务提供方：
> - **`CONTRACT_SOURCE = CLIENT_PROVIDED`**（甲方正式提供交付的原始技术契约）；
> - **`SERVICE_PROVIDER = DMS_VENDOR`**（由第三方门锁/物联网平台厂商运营托管）；
> 3. 任何敏感口令、密钥、Token 及手机号示例均已脱敏处理为 `<REDACTED>`。
---
## 1. 契约统计概览 (Catalog Summary)
- **原始接口声明总数 (`RAW_ENDPOINT_DECLARATION_COUNT`)**：**30 处**
- **去重后唯一接口总数 (`UNIQUE_CLIENT_PROVIDED_API_COUNT`)**：**27 个**（以 `METHOD + PATH` 为联合主键）
- **文档重复引用次数 (`DUPLICATE_REFERENCE_COUNT`)**：**3 次**
- 说明：`POST /rest/doorlock/query-operation-status`（查询操作结果）在甲方原始文档中分别于“门锁管理”、“下发在线密码”、“删除在线密码”、“下发/删除在线卡片” 4 个业务章节重复声明引用；
- **托管服务提供商 (`DMS_VENDOR_API_COUNT`)**：**27 个**（100% 由 DMS 物联网平台厂商承载运营）。
---
## 2. 甲方提供接口全量清单 (`CLIENT_PROVIDED_API`)
| 序号 (API_ID) | 业务分类 (CATEGORY) | 接口名称 (NAME) | 请求方式 (METHOD) | 契约路径 (PATH) | 契约来源 (CONTRACT_SOURCE) | 服务提供商 (SERVICE_PROVIDER) | 读写属性 (READ_OR_MUTATION) | 请求参数要素 (DOCUMENTED_REQUEST) | 响应关键字段 (DOCUMENTED_RESPONSE) |
| :---: | :--- | :--- | :---: | :--- | :---: | :---: | :---: | :--- | :--- |
| **API-01** | 登录鉴权 | 平台登录 | `POST` | `/public/rest/third-party-app/token/get` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"appid": "<REDACTED>", "appsecret": "<REDACTED>"}` | `success, token, expiresIn, message` |
| **API-02** | 登录鉴权 | 退出登录 | `POST` | `/public/rest/security/logout` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{}` (Token置于Cookie/URL) | `success` |
| **API-03** | 区域管理 | 获取楼栋列表 | `POST` | `/rest/place/building/list` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"building": "<string>", "offset": 0, "limit": 100}` | `success, rows: [{id, name, parentId, building, type, ...}], total` |
| **API-04** | 区域管理 | 获取楼层列表 | `POST` | `/rest/place/floor/list` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"building": "<string>", "floor": "<string>", "offset": 0, "limit": 100}` | `success, rows: [{id, name, parentId, building, floor, ...}], total` |
| **API-05** | 区域管理 | 获取房间列表 | `POST` | `/rest/place/room/list` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"building": "<string>", "floor": "<string>", "room": "<string>", "offset": 0, "limit": 100}` | `success, rows: [{id, name, parentId, building, floor, room, ...}], total` |
| **API-06** | 区域管理 | 获取房间id | `POST` | `/rest/place/room/get` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"building": "<string>", "floor": "<string>", "room": "<string>"}` | `success, data: {id, projectId, building, floor, room}` |
| **API-07** | 网关管理 | 获取网关列表 | `POST` | `/rest/gateway/list` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"offset": 0, "limit": 100}` | `success, rows: [{id, projectId, hardwareId, ...}], total` |
| **API-08** | 网关管理 | 刷新网关状态 | `POST` | `/rest/gateway/refresh-online-status` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"id": <long>, "hardwareId": "<string>"}` | `success, data: {operationId, requestType, timeoutSeconds, ...}` |
| **API-09** | 网关管理 | 查询网关状态 | `POST` | `/rest/gateway/query-online-status` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"operationId": "<string>", "hardwareId": "<string>"}` | `success, data: {operationStatus, operationId, hardwareId, ...}` |
| **API-10** | 门锁管理 | 获取门锁列表 | `POST` | `/rest/doorlock/list` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"placeId": <long>, "offset": 0, "limit": 100}` | `success, rows: [{id, hardwareId, building, floor, battery, signal, ...}], total` |
| **API-11** | 门锁管理 | 查询门锁电池和信号状态 | `POST` | `/rest/doorlock/query-lock-battery` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"roomIds": [<long>]}` | `success, data: {"<roomId>": [{id, roomId, battery, signal, ...}]}` |
| **API-12** | 门锁管理 | 远程开锁 | `POST` | `/rest/doorlock/remote-unlock` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"lockId": <long>, "hardwareId": "<string>", "canOpenAntilock": true}` | `success, data: {operation: {operationId, requestType: 5, ...}}` |
| **API-13** | 门锁管理 | 查询操作结果 | `POST` | `/rest/doorlock/query-operation-status` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"requestType": <int>, "operationId": "<string>", "hardwareId": "<string>"}` | `success, data: {operationStatus, requestType, operationId, ...}` |
| **API-14** | 钥匙管理 | 下发在线密码 | `POST` | `/rest/doorlock/online-password-key/create` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"lockId": <long>, "validStart": <ts>, "validUntil": <ts>, "password": "<REDACTED>", "subType": 4, ...}` | `success, data: {id, lockId, operationId, typeStr: "Online Password", ...}` |
| **API-15** | 钥匙管理 | 删除在线密码 | `POST` | `/rest/doorlock/online-password/delete` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"id": <long>}` | `success, data: {id, lockId, operationId, ...}` |
| **API-16** | 钥匙管理 | 申请离线密码 | `POST` | `/rest/doorlock/offline-password/create` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"lockId": <long>, "validStart": <ts>, "validUntil": <ts>, "subType": 4}` | `success, data: {"password": "<REDACTED>"}` |
| **API-17** | 钥匙管理 | 生成离线密码钥匙 | `POST` | `/rest/doorlock/offline-password-key/create` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"lockId": <long>, "holder": "<name>", "validStart": <ts>, "validUntil": <ts>, "password": "<REDACTED>"}` | `success, data: {id, lockId, typeStr: "Offline Password", ...}` |
| **API-18** | 钥匙管理 | 下发在线卡片 | `POST` | `/rest/doorlock/online-card/create` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"lockId": <long>, "validStart": <ts>, "validUntil": <ts>, "cardNumber": "<hex>", "subType": 4, ...}` | `success, data: {id, lockId, operationId, typeStr: "Online Card", ...}` |
| **API-19** | 钥匙管理 | 删除在线卡片 | `POST` | `/rest/doorlock/online-card/delete` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"id": <long>}` | `success, data: {id, lockId, operationId, typeStr: "Online Card", ...}` |
| **API-20** | 钥匙管理 | 生成二维码/手机钥匙 | `POST` | `/rest/doorlock/qrcode/create` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"lockId": <long>, "validStart": <ts>, "validUntil": <ts>, "phoneCountry": "+86", "phoneNumber": "<REDACTED>"}` | `success, data: {id, lockId, cardNumber, ...}` |
| **API-21** | 钥匙管理 | 注销二维码/手机钥匙 | `POST` | `/rest/qrcode/delete` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"id": <long>}` | `success` |
| **API-22** | 钥匙管理 | 生成离线卡片钥匙 | `POST` | `/rest/doorlock/offline-card/create` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"lockId": <long>, "validStart": <ts>, "validUntil": <ts>, "cardNumber": "<hex>", "offlineCardType": 2}` | `success, data: {id, lockId, typeStr: "Offline Card", ...}` |
| **API-23** | 开门记录 | 获取开门记录列表 | `POST` | `/rest/lock/unlock-record/list` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"room": "<string>", "offset": 0, "limit": 10, "typeList": [6]}` | `success, rows: [{id, lockId, password, userName, typeStr, ...}], total` |
| **API-24** | 取电开关 | 获取取电开关列表 | `POST` | `/rest/powerswitch/list` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"offset": 0, "limit": 20}` | `success, rows: [{id, projectId, hardwareId, ...}], total` |
| **API-25** | 取电开关 | 取电开关远程送电 | `POST` | `/rest/powerswitch/remote-poweron` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"id": <long>, "hardwareId": "<string>"}` | `success, data: {operation: {operationId, requestType: 1, ...}}` |
| **API-26** | 取电开关 | 取电开关远程断电 | `POST` | `/rest/powerswitch/remote-poweroff` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `MUTATION` | `{"id": <long>, "hardwareId": "<string>"}` | `success, data: {operation: {operationId, requestType: 2, ...}}` |
| **API-27** | 取电开关 | 查询断送电结果 | `POST` | `/rest/powerswitch/query-operation-status` | `CLIENT_PROVIDED` | `DMS_VENDOR` | `READ` | `{"requestType": <int>, "operationId": "<string>", "hardwareId": "<string>"}` | `success, data: {operationStatus, resultDetails: {powerStatus, powerType}}` |
---
## 3. 文档重复声明关系映射 (Duplicate Reference Mapping)
在甲方原始文档中，`POST /rest/doorlock/query-operation-status` 在不同章节中重复出现 3 次，其语义与调用契约如下：
| 重复声明序号 | 所在原始文档章节 | 声明接口名称 | 契约路径 | 对应统一主条目 | 去重后处理策略 |
| :---: | :--- | :--- | :--- | :--- | :--- |
| **Dup-01** | 钥匙管理接口 - 在线密码 | 查询下发在线密码结果 | `POST /rest/doorlock/query-operation-status` | `API-13` (查询操作结果) | 契约路径完全一致，参数 `requestType=1`，已作为子用例归入 API-13 |
| **Dup-02** | 钥匙管理接口 - 在线密码 | 查询删除在线密码结果 | `POST /rest/doorlock/query-operation-status` | `API-13` (查询操作结果) | 契约路径完全一致，参数 `requestType=1`，已作为子用例归入 API-13 |
| **Dup-03** | 钥匙管理接口 - 在线卡片 | 查询下发或删除在线卡片结果 | `POST /rest/doorlock/query-operation-status` | `API-13` (查询操作结果) | 契约路径完全一致，参数 `requestType=1`，已作为子用例归入 API-13 |
---
## 4. 敏感凭据保护审计 (Security & Redaction Compliance)
- **APPID / SECRET**：甲方原始文档包含的凭据已全部替换为 `<REDACTED>`；
- **TOKEN**：示例 Token 已全部替换为 `<REDACTED>`；
- **手机号与联系方式**：示例手机号已全部替换为 `<REDACTED>`；
- **明文测试密码**：文档示例中的密码已全部替换为 `<REDACTED>`；
- **结论**：本文件 100% 符合脱敏规范，无任何敏感信息泄漏。
Reference in new issue Copy Permalink