From 1aac011227193592ea24cb4e9e65ff1aa8d99f3c Mon Sep 17 00:00:00 2001 From: g82tt Date: Tue, 19 May 2026 15:53:43 +0800 Subject: [PATCH] =?UTF-8?q?KMS=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3v2.1:=20?= =?UTF-8?q?=E9=99=84=E5=BD=95A=E6=8E=A5=E5=8F=A3=E5=85=A8=E8=A6=86?= =?UTF-8?q?=E7=9B=96=E6=AF=94=E5=AF=B9+=E9=99=84=E5=BD=95B=E9=80=82?= =?UTF-8?q?=E9=85=8D=E5=8E=9F=E5=88=99=E5=AE=A1=E6=9F=A5+3=E4=B8=AA?= =?UTF-8?q?=E6=96=B0=E6=8E=A5=E5=8F=A3=E5=BB=BA=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/设计文档/KMS钥匙柜适配器详细设计文档.md | 204 +++++++++++++++++++- 1 file changed, 202 insertions(+), 2 deletions(-) diff --git a/doc/设计文档/KMS钥匙柜适配器详细设计文档.md b/doc/设计文档/KMS钥匙柜适配器详细设计文档.md index 7773efd..aff60bf 100644 --- a/doc/设计文档/KMS钥匙柜适配器详细设计文档.md +++ b/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 | ✅ | +| 统一分页 | GetDevices/GetAlarms 返回 PagedResult | ✅ | +| 弹性 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; + +/// +/// 设备反向控制接口。适用于支持远程下发指令的子系统（如 KMS 远程开门、门禁远程开闸、道闸抬杆）。 +/// 控制指令为通用键值对字典，适配器内部转换。 +/// +public interface IAcceptsControl : IGatewayAdapter +{ + /// 向设备下发控制指令 + /// 子系统设备原始 ID + /// 指令名，如 "open"/"close"/"authorize" + /// 指令参数键值对 + Task SendControlAsync(string sourceDeviceId, string command, Dictionary parameters); +} + +/// 控制结果 +public class ControlResult { public bool Success { get; set; } public string? Message { get; set; } } +``` + +```csharp +/// +/// 业务记录查询接口。适用于具有借还、交接、授权等业务日志的子系统。 +/// 不走 StandardAlarm 通道，独立分页查询。 +/// +public interface IHasBusinessLogs : IGatewayAdapter +{ + /// 分页查询业务记录 + /// 记录类型: "borrow"/"handover"/"permission"/"event" + /// 开始时间 + /// 结束时间 + /// 页码 + /// 每页条数 + /// 额外过滤条件 + Task> GetBusinessLogsAsync( + string logType, DateTime? from, DateTime? to, + int page, int size, Dictionary? filters = null); +} + +/// 业务记录条目 +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? Extra { get; set; } +} +``` + +```csharp +/// +/// 外部数据同步写入接口。适用于需要从 Vol.Pro 向子系统推送数据的场景（如员工同步）。 +/// +public interface IAcceptsDataSync : IGatewayAdapter +{ + /// 批量写入数据到子系统 + /// 数据类型: "staff"/"department" + /// 待同步的数据对象列表（JSON 兼容） + Task SyncDataAsync(string dataType, List items); + + /// 批量删除 + Task DeleteDataAsync(string dataType, List 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）。