14 KiB
14 KiB
01 DMS API 全量资产清单与分级评估 (DMS API Inventory)
文档来源：
https://dms.dmsiot.com/V1/doc/restapi.html文档完整性评估：DOCUMENTATION_COMPLETENESS = PARTIAL接口审计原则：严格基于官方文档文字与 Schema 表达，不臆测不存在的接口，明确标记置信度与敏感字段。
1. 范围与分级定义说明
| 分级标识 | 定义与采纳建议 | 典型接口范畴 |
|---|---|---|
P0_REQUIRED |
一期核心闭环必备：完成学员入住开门、退宿撤权、异步状态对账所必需的接口 | 登录获取 Token、房间查询、门锁列表、下发在线密码/卡片、删除密码/卡片、查询门锁操作状态 |
P1_USEFUL |
高价值辅助运维接口：用于设备健康度巡检、房源维护、现场排障，不阻断核心入住业务流 | 查询门锁电池与信号状态、楼栋/楼层列表、开门记录流水查询 |
P2_FUTURE |
未来二期/扩展功能：非当前学员住宿刚需，或需要额外硬件联动、现场施工配合的功能 | 取电开关全套接口（送电/断电/列表/状态）、网关状态主动巡检刷新 |
OUT_OF_SCOPE |
高风险或不适用当前场景：需要严苛线下流程或与当前全自动/半自动学员管理模型冲突 | 离线制卡接口（依赖现场物理制卡机与 DLL）、生成离线密码（需现场输入超长动态数字码） |
UNCONFIRMED |
文档缺失关键接口端点：仅在响应体或枚举中出现字段，未提供独立接口调用支持 | 手机蓝牙钥匙、指纹下发接口 |
2. DMS API 全量清单 (DMS_API_INVENTORY)
| # | Category | Operation | HTTP Method | Path | Request Fields | Response Fields | Auth | Sync/Async | operationId? | requestType? | External ID | Sensitive Fields | Relevance | Phase Recommendation | Confidence |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | 鉴权认证 | 平台登录获取 Token | POST |
/public/rest/third-party-app/token/get |
appid, appsecret |
success, token, expiresIn, message |
无需 Token (凭 appid/secret) | Sync | 否 | 无 | 无 | appid, appsecret, token |
核心入口 | P0_REQUIRED |
DOCUMENTED |
| 2 | 鉴权认证 | 退出登录 | POST |
/public/rest/security/logout |
{} (空 JSON) |
success |
Cookie / URL token |
Sync | 否 | 无 | 无 | token |
会话销毁 | P1_USEFUL |
DOCUMENTED |
| 3 | 区域管理 | 获取楼栋列表 | POST |
/rest/place/building/list |
building, offset, limit |
success, rows (含 id, name, parentId, building, projectId), total |
Cookie / URL token |
Sync | 否 | 无 | 楼栋 id |
无 | 房源台账对照 | P1_USEFUL |
DOCUMENTED |
| 4 | 区域管理 | 获取楼层列表 | POST |
/rest/place/floor/list (注: 文档示例为 http) |
building, floor, offset, limit |
success, rows (含 id, name, parentId, floor, building), total |
Cookie / URL token |
Sync | 否 | 无 | 楼层 id |
无 | 房源台账对照 | P1_USEFUL |
DOCUMENTED |
| 5 | 区域管理 | 获取房间列表 | POST |
/rest/place/room/list |
building, floor, room, offset, limit |
success, rows (含 id, name, parentId, building, floor, room, status), total |
Cookie / URL token |
Sync | 否 | 无 | 房间 id (placeId) |
无 | 房间映射与校验 | P0_REQUIRED |
DOCUMENTED |
| 6 | 区域管理 | 精确获取房间 ID | POST |
/rest/place/room/get |
building, floor, room |
success, data (含 id, projectId, building, floor, room), message |
Cookie / URL token |
Sync | 否 | 无 | 房间 id (placeId) |
无 | 房间快速映射绑定 | P0_REQUIRED |
DOCUMENTED |
| 7 | 网关管理 | 获取网关列表 | POST |
/rest/gateway/list |
offset, limit |
success, rows (含 id, projectId, hardwareId, onlineStatus 等), total |
Cookie / URL token |
Sync | 否 | 无 | 网关 id, hardwareId |
无 | 设备拓扑巡检 | P1_USEFUL |
DOCUMENTED (onlineStatus未实现) |
| 8 | 网关管理 | 刷新网关状态 | POST |
/rest/gateway/refresh-online-status |
id, hardwareId |
success, data (含 operation 对象: operationId, timeoutSeconds: 10, requestType: 1) |
Cookie / URL token |
Async | 是 (operationId) |
1 | 网关 id |
操作人手机号 (username) |
故障排查 | P2_FUTURE |
DOCUMENTED |
| 9 | 网关管理 | 查询网关状态 | POST |
/rest/gateway/query-online-status |
operationId, hardwareId |
success, data (含 operationStatus: success/undone/timeout) |
Cookie / URL token |
Polling | 是 (operationId) |
1 | 无 | 无 | 故障排查轮询 | P2_FUTURE |
DOCUMENTED |
| 10 | 门锁管理 | 获取门锁列表 | POST |
/rest/doorlock/list |
placeId, offset, limit |
success, rows (含 id, hardwareId, placeId, battery, signal, passagewayMode), total |
Cookie / URL token |
Sync | 否 | 无 | 门锁 id, hardwareId |
无 | 核心设备映射 | P0_REQUIRED |
DOCUMENTED |
| 11 | 门锁管理 | 查询门锁电池与信号状态 | POST |
/rest/doorlock/query-lock-battery |
roomIds (数组) |
success, data (Map: roomId -> [{id, battery, signal, batteryStr, signalStr}]) |
Cookie / URL token |
Sync | 否 | 无 | 门锁 id |
无 | 门锁健康度监控 | P1_USEFUL |
DOCUMENTED |
| 12 | 门锁管理 | 远程开锁 | POST |
/rest/doorlock/remote-unlock |
lockId, hardwareId, canOpenAntilock |
success, data.operation (含 operationId, requestType: 5) |
Cookie / URL token |
Async | 是 (operationId) |
5 | 门锁 id |
远程触发开门操作 | 高风险应急开门 | P2_FUTURE / 受控应急 |
DOCUMENTED |
| 13 | 门锁管理 | 查询门锁操作结果 | POST |
/rest/doorlock/query-operation-status |
requestType, operationId, hardwareId |
success, data (含 operationStatus: success/failed/undone/timeout, resultDetails, message) |
Cookie / URL token |
Polling (10s后) | 是 (operationId) |
1~9 | operationId |
resultDetails |
异步状态对账必备 | P0_REQUIRED |
DOCUMENTED |
| 14 | 钥匙管理 | 下发在线密码 | POST |
/rest/doorlock/online-password-key/create |
lockId, validStart, validUntil, holder, canOpenAntilock, phoneCountry, phoneNumber, password (系统支持4~8位，建议6位), subType: 4 (限时) |
success, data (含钥匙 id, operationId, lockHardwareId, smsStatus) |
Cookie / URL token |
Async (需10s后对账) | 是 (operationId) |
1 | 钥匙 id, operationId |
password, phoneNumber |
核心凭据发放 | P0_REQUIRED |
DOCUMENTED |
| 15 | 钥匙管理 | 查询下发在线密码结果 | POST |
/rest/doorlock/query-operation-status |
requestType: 1, operationId, hardwareId |
success, data.operationStatus |
Cookie / URL token |
Polling | 是 (operationId) |
1 | operationId |
无 | 密码生效对账 | P0_REQUIRED |
DOCUMENTED |
| 16 | 钥匙管理 | 删除在线密码 | POST |
/rest/doorlock/online-password/delete |
id (钥匙 ID) |
success, data (含 operationId, 钥匙状态 snapshot) |
Cookie / URL token |
Async (需10s后对账) | 是 (operationId) |
3 (注: 文档示例误标为1) | 钥匙 id, operationId |
fuzzyPassword, phoneNumber |
核心退宿撤权 | P0_REQUIRED |
DOCUMENTED |
| 17 | 钥匙管理 | 申请离线密码 | POST |
/rest/doorlock/offline-password/create |
lockId, validStart, validUntil, subType (1永久, 2单次, 4限时, 5清空) |
success, data.password (动态纯数字码，如 "2420101197") |
Cookie / URL token |
Sync (纯算法计算) | 否 | 无 | 无 | password |
离线网络应急备用 | OUT_OF_SCOPE |
DOCUMENTED |
| 18 | 钥匙管理 | 生成离线密码钥匙记录 | POST |
/rest/doorlock/offline-password-key/create |
lockId, holder, validStart, validUntil, password |
success, data (含钥匙 id, placeId, lockHardwareId) |
Cookie / URL token |
Sync | 否 | 无 | 钥匙 id |
fuzzyPassword |
离线台账补录 | OUT_OF_SCOPE |
DOCUMENTED |
| 19 | 钥匙管理 | 下发在线卡片 | POST |
/rest/doorlock/online-card/create |
lockId, validStart, validUntil, holder, canOpenAntilock, cardNumber (16进制低位在前), subType: 4 |
success, data (含钥匙 id, operationId, lockHardwareId) |
Cookie / URL token |
Async (需10s后对账) | 是 (operationId) |
2 | 钥匙 id, operationId |
cardNumber |
实体学员卡下发 | P1_USEFUL / 备选 |
DOCUMENTED |
| 20 | 钥匙管理 | 删除在线卡片 | POST |
/rest/doorlock/online-card/delete |
id (钥匙 ID) |
success, data (含 operationId, 钥匙状态 snapshot) |
Cookie / URL token |
Async (需10s后对账) | 是 (operationId) |
4 (注: 文档示例误标为1) | 钥匙 id, operationId |
cardNumber |
实体卡退宿注销 | P1_USEFUL / 备选 |
DOCUMENTED |
| 21 | 钥匙管理 | 生成二维码/手机钥匙 | POST |
/rest/doorlock/qrcode/create |
lockId, validStart, validUntil, holder, canOpenAntilock, phoneCountry, phoneNumber |
success, data (含钥匙 id, 示例含数据污染) |
Cookie / URL token |
Sync | 否 | 无 | 钥匙 id |
phoneNumber |
移动端二维码开锁 | NEEDS_BUSINESS_CONFIRMATION |
DOCUMENTED |
| 22 | 钥匙管理 | 注销二维码/手机钥匙 | POST |
/rest/qrcode/delete (注: 路径无 doorlock) |
id (钥匙 ID) |
success |
Cookie / URL token |
Sync | 否 | 无 | 钥匙 id |
无 | 二维码注销 | NEEDS_BUSINESS_CONFIRMATION |
DOCUMENTED |
| 23 | 钥匙管理 | 生成离线卡片钥匙 | POST |
/rest/doorlock/offline-card/create |
lockId, validStart, validUntil, holder, canOpenAntilock, cardNumber, subType: 4, offlineCardType: 2 |
success, data (钥匙元数据) |
Cookie / URL token |
Sync (无需下发锁，需配合物理写卡机) | 否 | 无 | 钥匙 id |
cardNumber |
传统酒店磁卡/IC卡制卡 | OUT_OF_SCOPE |
DOCUMENTED |
| 24 | 开门记录 | 获取开门记录列表 | POST |
/rest/lock/unlock-record/list (注: 路径为 /lock/) |
lockId, building, room, userName, startTime, endTime, offset, limit, typeList (数组) |
success, rows (含 id, lockId, placeId, hardwareId, password, type, creationTime, userName), total |
Cookie / URL token |
Sync | 否 | 无 | 记录 id |
password, userName |
考勤辅助/安全排障 | P1_USEFUL |
DOCUMENTED |
| 25 | 取电开关 | 获取取电开关列表 | POST |
/rest/powerswitch/list |
offset, limit |
success, rows (含开关 id, projectId, hardwareId, placeId, building, room), total |
Cookie / URL token |
Sync | 否 | 无 | 开关 id, hardwareId |
无 | 宿舍节能控制 | P2_FUTURE |
DOCUMENTED |
| 26 | 取电开关 | 取电开关远程送电 | POST |
/rest/powerswitch/remote-poweron |
id, hardwareId |
success, data.operation (含 operationId, requestType: 1) |
Cookie / URL token |
Async | 是 (operationId) |
1 | 开关 id, operationId |
操作人手机号 | 宿舍远程供电 | P2_FUTURE |
DOCUMENTED |
| 27 | 取电开关 | 取电开关远程断电 | POST |
/rest/powerswitch/remote-poweroff |
id, hardwareId |
success, data.operation (含 operationId, requestType: 2) |
Cookie / URL token |
Async | 是 (operationId) |
2 | 开关 id, operationId |
操作人手机号 | 宿舍远程断电 | P2_FUTURE |
DOCUMENTED |
| 28 | 取电开关 | 查询取电开关远程断/送电结果 | POST |
/rest/powerswitch/query-operation-status |
requestType (1送电, 2断电), operationId, hardwareId |
success, data (含 operationStatus: success/undone/timeout, powerStatus) |
Cookie / URL token |
Polling | 是 (operationId) |
1 / 2 | operationId |
无 | 取电开关对账 | P2_FUTURE |
DOCUMENTED |
3. 一期重点接口范围确认 (Scope Freeze)
3.1 一期必须接入接口 (P0_REQUIRED)
- 平台登录：
POST /public/rest/third-party-app/token/get（用于获取和维持通信令牌）。 - 房间映射：
POST /rest/place/room/get及POST /rest/place/room/list（建立本地宿舍与 DMS 房间placeId的权威绑定）。 - 门锁映射：
POST /rest/doorlock/list（根据placeId获取房间内所有智能门锁的lockId与hardwareId）。 - 权限下发：
POST /rest/doorlock/online-password-key/create（推荐作为一期首选试点凭据下发方式）。 - 权限撤销：
POST /rest/doorlock/online-password/delete（退宿/调房/结训时主动撤销钥匙）。 - 异步结果查询：
POST /rest/doorlock/query-operation-status（所有写操作的异步 10 秒后对账保障）。
3.2 高风险与非核心功能排除说明
- 远程开锁 (
remote-unlock)：属于主动设备控制，具有物理安全风险。一期严禁作为学员常规功能，仅设计受控管理员权限与两票制审计，标记为P2_FUTURE / 受控应急。 - 取电开关全套接口 (
powerswitch/*)：沈阳房建公寓段学员管理系统核心是学员学籍、住宿、报到业务，强行纳入取电开关将带来硬件施工与网络调试成本，确定归入P2_FUTURE。 - 二维码钥匙 (
qrcode/create)：官方文档中明确包含端点定义 (POST /rest/doorlock/qrcode/create与POST /rest/qrcode/delete)，分类为DOCUMENTED；但其响应示例存在数据污染（typeStr: "Online Card"）且未见二维码载荷内容，其实际方案可行性属于NEEDS_BUSINESS_CONFIRMATION，一期推荐保持使用在线密码作为 Pilot 方案。