# 网关 KMS 模块检查报告 2026-06-04

> **基准文档**: `doc/对接文档/钥匙管理系统软件接口.docx` (KMS API v1.0.4)
> **检查范围**: `gateway/src/IntegrationGateway.Adapters.Kms/` (KmsAdapter.cs / KmsAuthHelper.cs / KmsModels.cs) + `Program.cs` B10-B13 路由
> **方法**: 逐接口比对文档 → 代码 → 路由

---

## 1. 覆盖率总览

| 模块 | KMS 文档端点数 | Gateway 覆盖 | 覆盖率 |
|------|:---:|:---:|:---:|
| 2.9 Token 获取 | 1 | 1 | 100% |
| 2.18 开放接口 | 8 | 8 | 100% |
| **总计 (Phase 1)** | **9** | **9** | **100%** |
| 2.3-2.17 标准接口 | 38 | 1 (确认告警) | 3% |

---

## 2. 逐接口检查

### 2.18.1 心跳 — `GET /prod-api/heartBeat`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | `client.GetAsync(...)` | GET | ✅ |
| 请求路径 | `/prod-api/heartBeat` | `/prod-api/heartBeat` | ✅ |
| 请求体 | 无 | 无 | ✅ |
| 错误处理 | `catch (Exception ex) { Console.Error.WriteLine; return false; }` | — | ✅ |

### 2.18.2 批量删除员工 — `POST /prod-api/batchDeleteStaff`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | `PostAsJsonAsync(...)` | POST | ✅ |
| 请求路径 | `/prod-api/batchDeleteStaff` | `/prod-api/batchDeleteStaff` | ✅ |
| 请求体 | `List<string>` (staffUuid 数组) | `["uuid1","uuid2",...]` | ✅ |
| 参数类型 | 数组 | 数组 (v1.0.2 修正) | ✅ |

### 2.18.3 批量同步员工 — `POST /prod-api/batchSyncStaff`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | `PostAsJsonAsync(...)` | POST | ✅ |
| 请求路径 | `/prod-api/batchSyncStaff` | `/prod-api/batchSyncStaff` | ✅ |
| 请求体 | `new { staff = staffList }` | staff 数组 | ⚠️ |
| account 字段 | 模型中有 Account? | v1.0.4 新增 account | ⚠️ 待验证 |

**风险**: 文档 v1.0.4 新增了 `account` (登录账号) 字段。`KmsStaff` 模型需确认包含此字段。网关包装为 `{ staff: [...] }` 可能与 KMS 期望的裸数组不一致。

### 2.18.4 查询柜体钥匙 — `POST /prod-api/getOpenerList`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | POST | POST | ✅ |
| 请求路径 | `/prod-api/getOpenerList` | `/prod-api/getOpenerList` | ✅ |
| 请求体 | `"{}"` | 无明确要求 / 空对象 | ✅ |
| 响应 → StandardDevice | 柜体→父设备, 锁孔→子设备 | 树状结构 | ✅ |

### 2.18.5 查询授权记录 — `POST /prod-api/getPermissionList`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | POST | POST | ✅ |
| 请求路径 | `/prod-api/getPermissionList` | `/prod-api/getPermissionList` | ✅ |
| 请求体 | `"{}"` | 授权记录业务对象 (含 lockerName, lendStaffName 等 20+ 字段) | 🔴 |
| 时间范围 | `DateTime? from, DateTime? to` 参数**未传入请求体** | `beginApplyTime`/`endApplyTime` | 🔴 |
| 分页 | `page`/`size` 参数**未传入请求体** | `pageNum`/`pageSize` | 🔴 |

**致命问题**: 网关注入 `from`/`to`/`page`/`size` 参数但**从未传入 KMS 请求体**。代码注释 `// 联调时加入时间范围` 确认这是已知缺口。当前实现等价于无过滤全量查询，无法按时间范围分页。

### 2.18.6 查询借还记录 — `POST /prod-api/getRecordList`

**与 2.18.5 完全相同的致命问题**: `from`/`to`/`page`/`size` 参数未传入 KMS 请求体。此外文档标记 `lockerName`、`lockholeSort`、`openerCnName` 为必填字段，但网关传 `"{}"` 无这些字段。

### 2.18.7 查询告警记录 — `POST /prod-api/getWarningList`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | POST | POST | ✅ |
| 请求路径 | `/prod-api/getWarningList` | `/prod-api/getWarningList` | ✅ |
| 请求体 | `"{}"` | 告警业务对象 (含 type, beginWarningTime 等) | 🔴 |
| 时间范围 | 未传 | `beginWarningTime`/`endWarningTime` | 🔴 |
| 告警类型 | 未传 (type=1当前/2历史) | 文档支持过滤 | 🔴 |
| 响应映射 | `Type==1 ? "未确认" : "已结束"` | `type` 1=当前告警, 2=历史告警 | 🔴 |

**状态映射错误**: `type` 字段在告警接口中表示 1=当前告警 / 2=历史告警，**不是** 1=未确认 / 2=已结束。代码将 type=1 映射为 Status="未确认"、type=2 映射为 Status="已结束"，语义错误。正确的映射应该是 type=1 → "活跃", type=2 → "历史"。

### 2.18.8 单点登录 — `POST /thirdPlatlogin`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | POST | POST | ✅ |
| 请求路径 | `/thirdPlatlogin?username={x}` | `/thirdPlatlogin?username={x}` | ✅ |
| 重定向处理 | 捕获 302, 返回 Location header | 文档说明"调用成功后直接重定向" | ✅ |
| 超时 | 无显式设置 | — | 🟡 |

### 2.9 Token 获取 — `POST /prod-api/getToken`

| 检查项 | Gateway 实现 | 文档规范 | 状态 |
|------|------|------|:--:|
| 请求方法 | `http.PostAsync(url, null)` | POST | ✅ |
| 参数位置 | query string: `?clientId=&clientSecret=` | query string | ✅ |
| 响应校验 | `Code != 200` → 抛异常 | `code: 200` = 成功 | ✅ |
| 缓存策略 | 25分钟 (30分钟效期-5分钟余量) | 30分钟效期 | ✅ |

> **注意**: 文档 2.9.1 显示 `POST /prod-api/getToken` 参数在 body 中 (`{ clientId, clientSecret }`)，但 2.9 节概述描述为 query 参数。两种方式 KMS 可能都支持。当前实现用 query string，联调时需确认兼容。

---

## 3. 模型映射核对

### 3.1 KMS 柜体 → StandardDevice

| 文档字段 | 代码映射 | 准确性 |
|------|------|:--:|
| lockerId | `SourceId = $"locker_{lockerId}"` | ✅ |
| lockerName | `Name = lockerName` | ✅ |
| lockerCode | `Extra["lockerCode"]` | ✅ |
| lockholeList | 遍历展开为子设备 | ✅ |
| IsParent | `true` | ✅ |

### 3.2 KMS 锁孔 → StandardDevice

| 文档字段 | 代码映射 | 准确性 |
|------|------|:--:|
| lockholeSort | `SourceId = $"lockhole_{lockerId}_{lockholeSort}"` | ✅ |
| openerName | `Name = openerName` | ✅ |
| openerType | `Extra["openerType"]` (1/2/3 数值) | ✅ |
| openerState | `Extra["openerState"]` + `IsOnline = (openerState=="在位")` | 🔴 |
| ParentSourceId | `$"locker_{lockerId}"` | ✅ |

**openerState 映射错误**: 根据文档数据字典（§4），`openerState` 是数值编码：
- 1 = 在柜
- 2 = 借出
- 3 = 录入
- 10 = 丢失

代码用 `openerState == "在位"` 做字符串比较，**永远不成立**。需改为 `openerState == "1"` 或解析为 int 后判断。

### 3.3 KMS 借还记录 → BusinessLogEntry

| 文档字段 | 代码映射 | 准确性 |
|------|------|:--:|
| uuid | `LogId` | ✅ |
| lockerName | 拼入 `DeviceSourceId` | ✅ |
| staffName | `StaffName` | ✅ |
| borrowTime | `CreatedAt` | ✅ |
| openerName | `Description` (不充分) | 🟡 |

### 3.4 KMS 告警 → StandardAlarm

| 文档字段 | 代码映射 | 准确性 |
|------|------|:--:|
| uuid | `AlarmId` | ✅ |
| warningTime | `OccurTime` | ✅ |
| remark | `Content` | ✅ |
| type (1/2) | `Status = Type==1 ? "未确认"："已结束"` | 🔴 |
| level | 固定 `"普通"` | 🟡 |

**type 语义错误**: 见 2.18.7 说明。文档明确 `type` 表示告警分类(1=当前,2=历史)，而非确认状态。

---

## 4. B 路由链路检查

| B 路由 | 对应 KMS 能力 | 适配器方法 | 参数传递 | 状态 |
|------|------|------|:--:|:--:|
| B1 `/health` | 心跳 2.18.1 | `HealthCheckAsync` | ✅ | ✅ |
| B2 `/devices` | 柜体钥匙 2.18.4 | `GetDevicesAsync` | ✅ | ✅ |
| B8 `/alarms` | 告警 2.18.7 | `GetAlarmsAsync` | ✅ | ✅ (映射有误) |
| B9 `/alarms/{id}/confirm` | 确认告警 | `ConfirmAlarmAsync` | ✅ | ⚠️ 端点未确认 |
| B10 `/control` | 远程控制 | `SendControlAsync` | ✅ | ⚠️ |
| B11 `/logs` | 业务记录 | `GetBusinessLogsAsync` | ✅ | ⚠️ |
| B12 `/sync` (POST) | 员工同步 2.18.3 | `SyncDataAsync` | ✅ | ⚠️ |
| B13 `/sync` (DELETE) | 删除员工 2.18.2 | `DeleteDataAsync` | ✅ | ✅ |

---

## 5. 问题汇总

### 🔴 致命问题 (需联调前修复)

| # | 问题 | 影响 |
|:--:|------|------|
| **R1** | 2.18.5/2.18.6/2.18.7 请求体只传 `"{}"`，忽略 `from`/`to`/`page`/`size` 参数 | 无法按时间分页查询，联调时大概率返回全量数据或报错 |
| **R2** | 2.18.7 type 字段语义错误 (1=当前告警被映射为"未确认") | 告警状态全部错误 |
| **R3** | openerState 字符串比较 vs 文档数值编码 | 所有锁孔 IsOnline 永远为 false |

### 🟠 严重问题

| # | 问题 | 影响 |
|:--:|------|------|
| **S1** | 2.18.6 必填字段 (`lockerName`, `lockholeSort`, `openerCnName`) 未传 | 借还记录查询可能被 KMS 拒绝 |
| **S2** | `ConfirmAlarmAsync` 端点 (`/prod-api/kms/warning/confirm/{id}`) 未在文档中确认存在 | 告警确认功能不可用 |
| **S3** | 2.18.5 请求体结构未知 (文档未给完整示例) | 授权记录查询格式需联调验证 |

### 🟡 改善项

| # | 问题 | 建议 |
|:--:|------|------|
| **M1** | KmsModels.cs 包含大量 Phase 2 DTO 但未使用 | 保留，Phase 2 可用 |
| **M2** | B10 控制指令 `command == "open"` 和 `command == "authorize"` 都调同一方法 | 区分"开门"和"授权"两种指令 |
| **M3** | ThirdPlatLoginAsync 无超时设置 | 加 15s 超时 |
| **M4** | SyncDevicesJob 中 `gwRepo.Update(node)` vs `gwSvc.UpdateAsync(node)` 不一致 | 统一风格 |

---

## 6. 需联调验证项

| # | 验证项 | 说明 |
|:--:|------|------|
| V1 | Token 获取用 query string vs body | 文档 2.9.1 标记为 body 参数，2.9 节概述为 query |
| V2 | `batchSyncStaff` body 格式 | `{ staff: [...] }` vs `[...]` |
| V3 | `KmsStaff` 是否需 account 字段 | v1.0.4 新增 |
| V4 | `getOpenerList` 返回的 openerState 是数值还是中文 | 决定映射逻辑 |
| V5 | `getRecordList` 必填字段是否真的必填 | 决定请求体最小字段集 |
| V6 | `getPermissionList` 请求体完整格式 | 文档示例不完整 |
| V7 | `warning/confirm` 端点存在性 | 调标准管理接口 |

---

> **结论**: 9 个 Phase 1 接口全部实现覆盖（100%），但 3 个致命问题（R1-R3）需在联调前修复——核心是请求体格式、type 语义映射、openerState 编码映射。其余 4 个严重问题需联调验证后确认。