railwaysystem/docs/reports/dms-r3/real-api-probe/RUN-20260916-01/contract-matrix.md

04 真实契约与 Adapter 对照矩阵 (Contract Matrix)

执行批次：RUN-20260916-01
基线规范：DMS REST API 2026 V1
匹配度总评：ADAPTER_CONTRACT_MATCH = PARTIAL
修复状态：ADAPTER_FIX_REQUIRED = YES (ALL_NECESSARY_FIXES_APPLIED)

---

1. 契约比对全景矩阵 (13 项核心能力)

#	Capability	Vendor Docs	Real Response	Current Adapter	Match	Action
1	Token Endpoint	POST /public/rest/third-party-app/token/get	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	DmsTokenManager 正确组装官方完整路径	MATCH	保持现有实现，无需修改
2	Token Response	{"success": true, "token": "...", "expiresIn": 7200}	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	支持直接根节点和 data 包装双模式提取 token 与 expiresIn	MATCH	保持现有防御性解析
3	Cookie Name	请求头 Cookie 携带 Token，官方文档描述为标准请求 Cookie	VENDOR_CONFIRMATION_REQUIRED	默认使用 tokenCookieName = "token"，支持外部配置覆盖	PARTIAL	保持配置化，允许生产环境变量根据实际网络嗅探调整
4	Token TTL	7200 秒 (2 小时)，成功请求任一平台接口会重新延长 2 小时	DOCUMENTED_7200S_NOT_RUNTIME_CONFIRMED	默认 7200s，含 120s 预防性提前刷新和成功调用滑动延展	MATCH	保持现有 Single-Flight 机制
5	Room Query	POST /rest/place/room/list & /room/get，支持 building, floor, room	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	原仅有 floorId，已扩充标准三元组重载	MATCH	已完成兼容增强：扩充全量入参重载
6	placeId 映射	房间主键即为 id，在门锁及权限下发中作为 placeId	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	原 DmsRoomDto 分立字段可能导致空值，已增加双向 fallback	MATCH	已完成兼容修复：双向互通兜底
7	Lock Query	POST /rest/doorlock/list，入参 placeId，返回 rows 列表	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	DmsDoorLockClient.listDoorLocksByPlaceId 准确调用入参	MATCH	保持现有查询实现
8	lockId 映射	门锁列表返回中主键字段名为 id，在下发密码入参为 lockId	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	原 DmsDoorLockDto 仅有 lockId，已扩充 id 与双向互通	MATCH	已完成兼容修复：双向互通兜底
9	hardwareId	硬件 SN，格式如字符串，下发与上报关键比对标识	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	DmsDoorLockDto.hardwareId 字符串类型完整映射	MATCH	保持现有映射
10	Operation Status	POST /rest/doorlock/query-operation-status，异步 10 秒后轮询	NOT_EXECUTED_SAFETY_GATE	DmsOperationStatusClient + DmsOperationStatusMapper (4 种状态归一化)	MATCH	保持现有 Mapper，状态未决决不冒进判成功
11	Password Create	POST /rest/doorlock/online-password-key/create (4~8位, subType=4)	NOT_EXECUTED_SAFETY_GATE	DmsPasswordClient 强随机生成，写操作读超时严禁自动重发	MATCH	保持现有安全调用与幂等控制
12	Password Delete	POST /rest/doorlock/online-password/delete，入参 id (keyId)	NOT_EXECUTED_SAFETY_GATE	DmsPasswordClient.deleteOnlinePassword 准确封装入参，读超时不重发	MATCH	保持现有实现
13	Error Response	HTTP 401 触发重新鉴权；{"success": false, "code": "...", "message": "..."}	BLOCKED_BY_SECURE_CREDENTIAL_HANDOFF	DmsHttpClient 集中解析，抛出分类分级异常，拦截脱敏	MATCH	保持现有异常分级与脱敏拦截

---

2. 字段兼容修改前后对比

A. 门锁 DTO (DmsDoorLockDto)

  public class DmsDoorLockDto implements Serializable {
+     private Long id;
      private Long lockId;
      ...
+     public Long getId() { return id != null ? id : lockId; }
+     public void setId(Long id) { this.id = id; if (this.lockId == null) this.lockId = id; }
+     public Long getLockId() { return lockId != null ? lockId : id; }
+     public void setLockId(Long lockId) { this.lockId = lockId; if (this.id == null) this.id = lockId; }
  }

B. 房间 DTO (DmsRoomDto)

  public class DmsRoomDto implements Serializable {
      private Long id;
      private Long placeId;
      ...
+     public Long getId() { return id != null ? id : placeId; }
+     public void setId(Long id) { this.id = id; if (this.placeId == null) this.placeId = id; }
+     public Long getPlaceId() { return placeId != null ? placeId : id; }
+     public void setPlaceId(Long placeId) { this.placeId = placeId; if (this.id == null) this.id = placeId; }
  }