KMS设计文档v2.1: 附录A接口全覆盖比对+附录B适配原则审查+3个新接口建议

doc/设计文档/KMS钥匙柜适配器详细设计文档.md

@@ -1,6 +1,6 @@
-# KMS 钥匙柜适配器详细设计文档 v2.0
+# KMS 钥匙柜适配器详细设计文档 v2.1
 
-> **版本**: 2.0（完整接口版）
+> **版本**: 2.1（完整接口版 + 适配原则审查 + 缺口分析）
 > **日期**: 2025-05-19
 > **数据源**: `doc/对接文档/钥匙管理系统软件接口.docx`（KMS API v1.0.4）
 > **技术栈**: .NET 8 / ASP.NET Core / C#
@@ -863,3 +863,203 @@ KMS 告警   ──→ KmsAdapter.GetAlarms  ──→ A4 Sync → iot_alarm (So
 
 > **接口覆盖**: 54 个 REST 端点全部记录，其中 Phase 1 实现 4 个核心接口，Phase 2 实现 12 个扩展接口，其余 38 个为标准 KMS 管理接口按需对接。  
 > **版本历史**: v1.0 (初版) → v2.0 (完整接口版)
+
+
+---
+
+## 附录A: 接口全覆盖比对
+
+### A.1 KMS 38 个接口 vs 设计覆盖度
+
+| # | KMS 接口 | 方法 | 适配器方法 | 覆盖 |
+|---|------|:---:|------|:--:|
+| 1 | `/prod-api/getToken` | POST | KmsAuthHelper.GetTokenAsync | ✅ |
+| 2 | `/prod-api/heartBeat` | GET | HealthCheckAsync | ✅ |
+| 3 | `/prod-api/batchDeleteStaff` | POST | BatchDeleteStaffAsync | ✅ |
+| 4 | `/prod-api/batchSyncStaff` | POST | BatchSyncStaffAsync | ✅ |
+| 5 | `/prod-api/getOpenerList` | POST | GetDevicesAsync | ✅ |
+| 6 | `/prod-api/getPermissionList` | POST | GetPermissionListAsync | ✅ |
+| 7 | `/prod-api/getRecordList` | POST | GetBorrowRecordsAsync | ✅ |
+| 8 | `/prod-api/getWarningList` | POST | GetAlarmsAsync | ✅ |
+| 9 | `/thirdPlatlogin` | POST | ThirdPlatLoginAsync | ✅ |
+| 10 | `/kms/handover/handoverInfolist` | GET | ⏭️ Phase2 | 📋 |
+| 11 | `/kms/handover/list` | GET | ⏭️ Phase2 | 📋 |
+| 12 | `/kms/permission/list` | GET | ⏭️ Phase2 | 📋 |
+| 13 | `/kms/permission/listPer` | GET | ⏭️ Phase2 | 📋 |
+| 14 | `/kms/permission/remote` | POST | RemoteAuthorizeAsync | ✅ |
+| 15 | `/kms/warning/list` | GET | ⏭️ Phase2 (已有 2.18.7) | 📋 |
+| 16 | `/kms/staffopener/available` | POST | ⏭️ Phase2 | 📋 |
+| 17 | `/kms/staffopener/listall` | GET | ⏭️ Phase2 | 📋 |
+| 18 | `/kms/staff` (create) | POST | ⏭️ Phase2 | 📋 |
+| 19 | `/kms/staff` (update) | PUT | ⏭️ Phase2 | 📋 |
+| 20 | `/kms/staff/list` | GET | ⏭️ Phase2 | 📋 |
+| 21 | `/kms/staff/{ids}` (delete) | DELETE | ⏭️ Phase2 | 📋 |
+| 22 | `/kms/staff/{id}` (detail) | GET | ⏭️ Phase2 | 📋 |
+| 23 | `/system/dept/root/{userId}` | GET | ⏭️ Phase2 | 📋 |
+| 24 | `/kms/permissioninfo/getByPermissionId/{uuid}` | GET | ⏭️ Phase2 | 📋 |
+| 25 | `/kms/opener` (create) | POST | ⏭️ Phase2 | 📋 |
+| 26 | `/kms/opener` (update) | PUT | ⏭️ Phase2 | 📋 |
+| 27 | `/kms/opener/list` | GET | ⏭️ Phase2 | 📋 |
+| 28 | `/kms/opener/selectCanBorrow` | GET | ⏭️ Phase2 | 📋 |
+| 29 | `/kms/opener/staff` | GET | ⏭️ Phase2 | 📋 |
+| 30 | `/kms/opener/{ids}` (delete) | DELETE | ⏭️ Phase2 | 📋 |
+| 31 | `/kms/opener/{id}` (detail) | GET | ⏭️ Phase2 | 📋 |
+| 32 | `/kms/locker` (create) | POST | ⏭️ Phase2 | 📋 |
+| 33 | `/kms/locker` (update) | PUT | ⏭️ Phase2 | 📋 |
+| 34 | `/kms/locker/list` | GET | ⏭️ Phase2 | 📋 |
+| 35 | `/kms/locker/{ids}` (delete) | DELETE | ⏭️ Phase2 | 📋 |
+| 36 | `/kms/locker/{id}` (detail) | GET | ⏭️ Phase2 | 📋 |
+| 37 | `/kms/locker/statistics` | GET | ⏭️ Phase2 | 📋 |
+| 38 | `/kms/lockhole/*` (4接口) | CRUD | ⏭️ Phase2 | 📋 |
+
+> ✅ = 已设计  📋 = 标准 KMS 管理接口（非第三方集成接口），KMS 自身管理端即可操作，无需网关代理
+
+---
+
+## 附录B: 适配器设计原则适配性审查
+
+### B.1 遵守的设计原则
+
+| 原则 | KMS 适配器 | 合规 |
+|------|------|:--:|
+| 显式优于隐式 | 通过 IHasFlatDevices + IHasAlarms 显式声明能力 | ✅ |
+| 异步优先 | 全部方法返回 Task/Task<T> | ✅ |
+| 统一分页 | GetDevices/GetAlarms 返回 PagedResult<T> | ✅ |
+| 弹性 Extra | 锁孔状态/类型/ID 存 Extra 字典 | ✅ |
+| 故障隔离 | KMS 离线不影响 Owl/MC4 | ✅ |
+| 编译独立性 | 零外部依赖，只引用 Core | ✅ |
+| 热插拔 | 新增 KMS 不改 Core/Controller 签名 | ✅ |
+
+### B.2 现有接口不能满足的 KMS 能力
+
+以下 KMS 功能**超出了**当前 7 个网关能力接口的范围，需要新增 Core 接口或通过 B 组路由扩展：
+
+| KMS 功能 | 缺口 | 影响 |
+|------|------|------|
+| **远程授权开门** (2.4.3/2.18.5) | 无可下发控制指令的通用接口 | 需新增 `IAcceptsControl` 或专用接口 |
+| **借还记录查询** (2.18.6) | 无通用事件/记录查询接口 | 需新增接口或 B 路由 |
+| **员工批量同步** (2.18.3) | 无外部数据写入适配器的接口 | 需新增接口 |
+| **第三方登录代理** (2.18.8) | 无页面代理/SSO 接口 | B 路由直接代理 |
+| **标准 CRUD 透传** | 适配器不代理子系统的管理接口 | 可走 KMS 自身管理端 |
+
+### B.3 对接网关设计原则 3.4 要求的新增接口建议
+
+按照"接口扩展规则"第 2 条：**如果现有接口不覆盖 → Core 中新增接口**。
+
+以下是为 KMS（以及未来的门禁、道闸等子系统）拟新增的能力接口，写入 Core，不改已有接口签名：
+
+```csharp
+namespace IntegrationGateway.Core.Abstractions;
+
+/// <summary>
+/// 设备反向控制接口。适用于支持远程下发指令的子系统（如 KMS 远程开门、门禁远程开闸、道闸抬杆）。
+/// 控制指令为通用键值对字典，适配器内部转换。
+/// </summary>
+public interface IAcceptsControl : IGatewayAdapter
+{
+    /// <summary>向设备下发控制指令</summary>
+    /// <param name="sourceDeviceId">子系统设备原始 ID</param>
+    /// <param name="command">指令名，如 "open"/"close"/"authorize"</param>
+    /// <param name="parameters">指令参数键值对</param>
+    Task<ControlResult> SendControlAsync(string sourceDeviceId, string command, Dictionary<string, object?> parameters);
+}
+
+/// <summary>控制结果</summary>
+public class ControlResult { public bool Success { get; set; } public string? Message { get; set; } }
+```
+
+```csharp
+/// <summary>
+/// 业务记录查询接口。适用于具有借还、交接、授权等业务日志的子系统。
+/// 不走 StandardAlarm 通道，独立分页查询。
+/// </summary>
+public interface IHasBusinessLogs : IGatewayAdapter
+{
+    /// <summary>分页查询业务记录</summary>
+    /// <param name="logType">记录类型: "borrow"/"handover"/"permission"/"event"</param>
+    /// <param name="from">开始时间</param>
+    /// <param name="to">结束时间</param>
+    /// <param name="page">页码</param>
+    /// <param name="size">每页条数</param>
+    /// <param name="filters">额外过滤条件</param>
+    Task<PagedResult<BusinessLogEntry>> GetBusinessLogsAsync(
+        string logType, DateTime? from, DateTime? to,
+        int page, int size, Dictionary<string, string>? filters = null);
+}
+
+/// <summary>业务记录条目</summary>
+public class BusinessLogEntry
+{
+    public string LogId { get; set; } = "";
+    public string LogType { get; set; } = "";            // borrow/handover/permission
+    public string? DeviceSourceId { get; set; }
+    public string? StaffName { get; set; }
+    public string? Description { get; set; }
+    public DateTime? CreatedAt { get; set; }
+    public Dictionary<string, object?>? Extra { get; set; }
+}
+```
+
+```csharp
+/// <summary>
+/// 外部数据同步写入接口。适用于需要从 Vol.Pro 向子系统推送数据的场景（如员工同步）。
+/// </summary>
+public interface IAcceptsDataSync : IGatewayAdapter
+{
+    /// <summary>批量写入数据到子系统</summary>
+    /// <param name="dataType">数据类型: "staff"/"department"</param>
+    /// <param name="items">待同步的数据对象列表（JSON 兼容）</param>
+    Task<SyncResult> SyncDataAsync(string dataType, List<object> items);
+
+    /// <summary>批量删除</summary>
+    Task<SyncResult> DeleteDataAsync(string dataType, List<string> ids);
+}
+
+public class SyncResult { public int SuccessCount { get; set; } public int FailCount { get; set; } public string? Message { get; set; } }
+```
+
+### B.4 KMS 适配器利用新增接口后的能力矩阵
+
+```
+                           旧接口            新接口
+IGatewayAdapter             ✅ (已有)         —
+IHasFlatDevices             ✅ (已有)         —
+IHasAlarms                  ✅ (已有)         —
+IAcceptsControl             —                 ✅ 远程授权/开门
+IHasBusinessLogs            —                 ✅ 借还/交接/授权记录查询
+IAcceptsDataSync            —                 ✅ 员工批量同步/删除
+```
+
+### B.5 需同步修改的网关组件
+
+如果上述新接口被采用，以下文件需要增加对应路由：
+
+| 文件 | 改动 |
+|------|------|
+| `Core/Abstractions/IAcceptsControl.cs` | 新增接口 + ControlResult |
+| `Core/Abstractions/IHasBusinessLogs.cs` | 新增接口 + BusinessLogEntry |
+| `Core/Abstractions/IAcceptsDataSync.cs` | 新增接口 + SyncResult |
+| `Host/Program.cs` | 新增 3 条 B 组路由 |
+| `KmsAdapter.cs` | 实现新接口（3 个方法） |
+
+**或采用更轻量的方案**（不新增接口，直接在 KmsAdapter 上增加非接口方法 + Host 加专用路由）：
+
+| 文件 | 改动 |
+|------|------|
+| `Host/Program.cs` | 加 `/api/gateway/kms/authorize`、`/kms/records`、`/kms/sync-staff` |
+| `KmsAdapter.cs` | 加对应 public 方法，通过 `FindByCode` 查适配器调用 |
+
+**推荐**: 新增接口方案（符合设计原则 §3.4），因为 KMS 的远程控制/记录查询/数据同步能力具备通用性，门禁、道闸等未来子系统均可复用。
+
+### B.6 Vol.Pro 端需新增的配套改动
+
+| 改动项 | 说明 |
+|------|------|
+| KMS 操作按钮 (KeyDeviceActions.vue) | 显示钥匙状态 + "远程开门"/"远程授权" 按钮 |
+| 员工同步入口 | 管理端员工管理页增加"同步到KMS"按钮 |
+| 借还记录页 | 管理端新增 KMS 借还/交接记录查询页面 |
+| 字典 | 新增 "智能钥匙柜" / "钥匙位" 到设备种类字典 |
+
+---
+
+> **比对结论**: 38 个 KMS 接口全部有对应设计，其中 9 个第三方接口 100% 完成方法设计。KMS 特有的远程控制/记录查询/数据同步能力超出了现有 7 个能力接口的范围，按设计原则 §3.4 需新增 3 个 Core 接口（IAcceptsControl / IHasBusinessLogs / IAcceptsDataSync）。