10 KiB
10 KiB
05A - 甲方提供外部接口总账 (Client-Provided API Catalog)
契约来源定义 (Task A & Task E)：
- 本文档为甲方（沈阳房建公寓段）向本项目提供的完整原始接口契约总账；
- 严格区分契约来源与实际服务提供方：
CONTRACT_SOURCE = CLIENT_PROVIDED（甲方正式提供交付的原始技术契约）；SERVICE_PROVIDER = DMS_VENDOR（由第三方门锁/物联网平台厂商运营托管）；- 任何敏感口令、密钥、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% 符合脱敏规范，无任何敏感信息泄漏。