From ee2c9ca648d5cd93418d73ae58cf3ba4f31fae0f Mon Sep 17 00:00:00 2001 From: g82tt Date: Tue, 19 May 2026 14:40:09 +0800 Subject: [PATCH] =?UTF-8?q?KMS=E6=95=B4=E5=90=88=E6=96=B9=E6=A1=88v2.0:=20?= =?UTF-8?q?=E5=AE=8C=E6=95=B4=E8=A6=86=E7=9B=9650+REST=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=20=E4=BF=AE=E6=AD=A3=E6=8A=80=E6=9C=AF=E6=A0=88=E4=B8=BA.NET8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/整合方案/KMS钥匙柜整合方案_v2.0.md | 256 +++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 doc/整合方案/KMS钥匙柜整合方案_v2.0.md diff --git a/doc/整合方案/KMS钥匙柜整合方案_v2.0.md b/doc/整合方案/KMS钥匙柜整合方案_v2.0.md new file mode 100644 index 0000000..8e9557a --- /dev/null +++ b/doc/整合方案/KMS钥匙柜整合方案_v2.0.md @@ -0,0 +1,256 @@ +# 钥匙柜（KMS）整合方案 v2.0 + +> **版本**: 2.0 +> **日期**: 2025-05-19 +> **数据源**: `doc/对接文档/钥匙管理系统软件接口.docx`（KMS API v1.0.4） +> **技术栈**: 全链路 .NET 8 / C#（网关 ASP.NET Core + Vol.Pro ASP.NET Core） +> **架构**: IntegrationGateway 适配器模式，KMS 作为第三个子系统适配器加入 + +--- + +## 1. KMS 系统全接口分析 + +### 1.1 认证体系 + +| 项目 | 说明 | +|------|------| +| 认证接口 | `POST /prod-api/getToken` | +| 参数 | `clientId` + `clientSecret`（由 KMS 管理员分配） | +| 返回 | `{ code: 200, token: "xxx" }` | +| 有效期 | 30 分钟，过期重新获取 | +| 使用方式 | 后续请求 Header: `Authorization: Bearer ` | + +### 1.2 第三方专用接口（第 2.18 节 —— 整合核心） + +KMS 预留了 8 个专供第三方对接的接口，这些是网关适配器必须实现的： + +| # | 方法 | 路径 | 用途 | 对应能力接口 | +|---|:---:|------|------|------| +| 2.18.1 | `POST` | `/prod-api/heartBeat` | 心跳检测 | `IGatewayAdapter.HealthCheck` | +| 2.18.2 | `POST` | `/prod-api/batchDeleteStaff` | 批量删除员工 | Phase 2 | +| 2.18.3 | `POST` | `/prod-api/batchSyncStaff` | 批量同步员工信息 | Phase 2 | +| 2.18.4 | `POST` | `/prod-api/getOpenerList` | 查询所有柜体及钥匙列表 | `IHasFlatDevices` | +| 2.18.5 | `POST` | `/prod-api/getPermissionList` | 查询远程授权记录 | Phase 2 | +| 2.18.6 | `POST` | `/prod-api/getRecordList` | 查询借还记录 | Phase 2 | +| 2.18.7 | `POST` | `/prod-api/getWarningList` | 查询告警记录 | `IHasAlarms` | +| 2.18.8 | `POST` | `/thirdPlatlogin` | 第三方登录/事件记录 | Phase 2 | + +> 注意：第 2.18.X 节接口的路径不同于标准 KMS 业务接口（不以 `/prod-api/kms/` 开头）。这是 KMS 为第三方特意设计的**扁平化集成 API**。 + +### 1.3 标准 KMS 业务接口（第 2.3-2.17 节 —— 辅助参考） + +以下是 KMS 完整的标准 REST API，供深入对接时使用： + +| 模块 | 接口 | 方法 | 说明 | +|------|------|:---:|------| +| **认证** | `/prod-api/getToken` | POST | 获取 Bearer Token | +| **部门** | `/prod-api/system/dept/root/{userId}` | GET | 获取部门树 | +| **交接记录** | `/prod-api/kms/handover/handoverInfolist` | GET | 查询交接记录明细 | +| | `/prod-api/kms/handover/list` | GET | 查询交接记录列表（分页） | +| **授权** | `/prod-api/kms/permission/list` | GET | 查询授权列表 | +| | `/prod-api/kms/permission/listPer` | GET | 查询授权人列表 | +| | `/prod-api/kms/permission/remote` | POST | 远程授权 | +| **告警** | `/prod-api/kms/warning/list` | GET | 查询告警列表（标准版） | +| **员工可借** | `/prod-api/kms/staffopener/available` | POST | 设置员工可借/永久授权钥匙 | +| | `/prod-api/kms/staffopener/listall` | GET | 查询员工可借/永久授权钥匙列表 | +| **员工管理** | `/prod-api/kms/staff` | POST | 创建员工 | +| | `/prod-api/kms/staff` | PUT | 修改员工信息 | +| | `/prod-api/kms/staff/list` | GET | 分页查询员工列表 | +| | `/prod-api/kms/staff/{id}` | DELETE | 删除员工 | +| | `/prod-api/kms/staff/{id}` | GET | 获取员工详细信息 | +| **员工组** | `/prod-api/kms/staffGroup/...` | CRUD | 员工组管理（6个接口） | +| **物品类别** | `/prod-api/kms/openerType/...` | CRUD | 物品类别管理（6个接口） | +| **柜体管理** | `/prod-api/kms/locker` | POST/PUT | 创建/修改柜体 | +| | `/prod-api/kms/locker/list` | GET | 分页查询柜体列表 | +| | `/prod-api/kms/locker/{id}` | DELETE/GET | 删除/获取柜体详细信息 | +| | `/prod-api/kms/locker/statistics` | GET | 首页统计图表数据 | +| **锁孔管理** | `/prod-api/kms/lockhole` | PUT | 修改锁孔 | +| | `/prod-api/kms/lockhole/list` | GET | 分页查询锁孔列表 | +| | `/prod-api/kms/lockhole/{id}` | DELETE/GET | 删除/获取锁孔详细信息 | +| **钥匙管理** | `/prod-api/kms/opener` | POST/PUT | 创建/修改钥匙 | +| | `/prod-api/kms/opener/list` | GET | 分页查询钥匙列表 | +| | `/prod-api/kms/opener/selectCanBorrow` | GET | 查询可借钥匙列表 | +| | `/prod-api/kms/opener/staff` | GET | 查询可借钥匙员工列表 | +| | `/prod-api/kms/opener/{id}` | DELETE/GET | 删除/获取钥匙详细信息 | +| **钥匙组** | `/prod-api/kms/openerGroup/...` | CRUD | 钥匙组管理（7个接口） | + +> 共约 **50+ 个 REST 端点**，覆盖 KMS 完整业务。 + +--- + +## 2. 整合策略 + +### 核心原则 + +1. **KMS 作为独立子系统**，通过 IntegrationGateway 的 `KmsAdapter` 接入 +2. **Phase 1** 实现第三方接口（8 个端点），这是 KMS 专门为集成设计的 +3. **Phase 2** 按需扩展标准业务接口（远程授权/开门/借还记录查询） +4. Vol.Pro 管理端通过网关 B 组接口间接调用 KMS，不直接对 KMS 编程 + +### 适配器能力矩阵 + +| 能力接口 | 实现 | 映射的 KMS 第三方接口 | +|----------|:---:|------| +| `IGatewayAdapter` | ✅ | 2.18.1 心跳 | +| `IHasFlatDevices` | ✅ | 2.18.4 柜体钥匙列表 → StandardDevice | +| `IHasAlarms` | ✅ | 2.18.7 告警列表 → StandardAlarm | +| 远程控制 (新接口) | ⏭️ | 2.18.5 远程授权 + KMS 标准接口 remote | + +--- + +## 3. 设备树映射 + +KMS 物理拓扑：**柜体(Locker) → 锁孔(Lockhole) → 钥匙(Opener)** + +映射到 `base_device` 表： + +``` +KMS 管理平台 (一个 IP:PORT = 一个 gateway_node) +├── 智能钥匙柜A (lockerId=25) +│ ├── 锁孔1 "仓库大门" (lockholeSort=1 → StandardDevice, Category="钥匙位") +│ ├── 锁孔2 "机房钥匙" (lockholeSort=2) +│ └── 锁孔N ... +├── 智能钥匙柜B (lockerId=26) +│ ├── 锁孔1 "配电室" +│ └── 锁孔M ... +``` + +| KMS 实体 | base_device 字段 | 值 | +|----------|------|------| +| 柜体 | `SourceId` | `locker_{lockerId}` | +| | `Name` | lockerName (如 "10位智能公共钥匙柜") | +| | `DeviceCategory` | "智能钥匙柜" | +| | `DeviceGroup` | "门禁设备" | +| | `IsParent` | "是" | +| | `Extra` | `{ lockerCode, lockholeCount }` | +| 锁孔子设备 | `SourceId` | `lockhole_{lockerId}_{lockholeSort}` | +| | `Name` | openerName (如 "仓库大门钥匙") | +| | `DeviceCategory` | "钥匙位" | +| | `DeviceGroup` | "门禁设备" | +| | `IsParent` | "否" | +| | `ParentSourceId` | `locker_{lockerId}` (解析为 ParentDeviceId) | +| | `Extra` | `{ openerState, openerType, openerId }` | +| | `IsOnline` | openerState="在位" → 在线; "离位" → 离线 | + +--- + +## 4. 告警映射 + +| KMS 告警字段(2.18.7) | StandardAlarm 字段 | 说明 | +|------|------|------| +| uuid | SourceAlarmId | KMS 告警唯一ID | +| warningTime | OccurTime | 告警时间 | +| type (1=当前告警,2=历史告警) | Status | type=1→"未确认", type=2→"已结束" | +| lockerName + lockholeSort | Title | 如 "10位公共钥匙柜 锁孔3" | +| openerName | 关联设备 | 通过 openerId 查找对应设备 | +| remark | Content | 告警备注详情 | + +--- + +## 5. 网关改造清单 + +### 5.1 新增项目 + +``` +gateway/src/IntegrationGateway.Adapters.Kms/ +├── IntegrationGateway.Adapters.Kms.csproj +├── KmsAdapter.cs # IHasFlatDevices + IHasAlarms +├── KmsAuthHelper.cs # clientId/clientSecret → Bearer Token +└── KmsModels.cs # KMS 响应 DTO +``` + +### 5.2 KmsAuthHelper + +```csharp +/// .NET 8 ASP.NET Core 适配: KMS Bearer Token 认证 +public class KmsAuthHelper +{ + private readonly HttpClient _http; + private readonly string _baseUrl, _clientId, _clientSecret; + private string? _token; + private DateTime _expiry = DateTime.MinValue; // 30min TTL + + public async Task GetTokenAsync() { ... } + public async Task GetAuthenticatedClientAsync() { ... } +} +``` + +### 5.3 KmsAdapter + +```csharp +public class KmsAdapter : IHasFlatDevices, IHasAlarms +{ + public string AdapterCode { get; } // "KMS:main" + public AdapterCapabilities Capabilities => new() { + HasFlatDevices = true, HasAlarms = true + }; + + // IHasFlatDevices → 2.18.4 POST /prod-api/getOpenerList + public async Task> GetDevicesAsync(int page, int size, string? keyword); + + // IHasAlarms → 2.18.7 POST /prod-api/getWarningList + public async Task> GetAlarmsAsync(int page, int size, DateTime from, DateTime to, string? level, string? state); + public async Task ConfirmAlarmAsync(string alarmId); + public async Task EndAlarmAsync(string alarmId); + + // IGatewayAdapter + public async Task HealthCheckAsync(); // → 2.18.1 POST /prod-api/heartBeat +} +``` + +### 5.4 配置文件 + +```json +// appsettings.json 新增 KMS 段 +{ + "KMS": { + "InstanceName": "main", + "BaseUrl": "http://192.168.1.50:8080", + "ClientId": "your_client_id", + "ClientSecret": "your_client_secret" + } +} +``` + +### 5.5 Program.cs 注册 + +```csharp +var kmsList = app.Configuration.GetSection("KMS").Get>() ?? new(); +foreach (var k in kmsList) + registry.Register(new KmsAdapter($"KMS:{k.InstanceName ?? "default"}", + httpClient, k.BaseUrl, k.ClientId, k.ClientSecret)); +``` + +--- + +## 6. Vol.Pro 端改动 + +| 项 | 改动 | 说明 | +|------|:---:|------| +| 数据库 | 无 | base_device/iot_alarm 已兼容 | +| 后端代码 | 无 | A1-A4 同步逻辑通用 | +| 字典 | 新增 2 项 | "智能钥匙柜" / "钥匙位" 加入设备种类字典 | +| 前端页面 | 无 | 设备列表自动显示 KMS 同步的设备 | +| 前端操作按钮 | Phase 2 | `KeyDeviceActions.vue` — 显示钥匙状态 + 远程授权入口 | + +--- + +## 7. 实施计划 + +| 阶段 | 内容 | 涉及文件 | 预计 | +|------|------|------|:---:| +| K0 | 创建 `Adapters.Kms` 项目 + 引用 Core | csproj + sln | 10min | +| K1 | `KmsModels.cs` — 所有 KMS 响应 DTO | 1 文件 | 30min | +| K2 | `KmsAuthHelper.cs` — Token 获取 + 刷新 | 1 文件 | 30min | +| K3 | `KmsAdapter.HealthCheck` + `GetDevicesAsync` | 1 文件 | 1h | +| K4 | `KmsAdapter.GetAlarmsAsync` + Confirm/End | 1 文件 | 1h | +| K5 | appsettings.json + Program.cs 注册 | 2 文件 | 15min | +| K6 | 字典补充 + 编译验证 | 管理端 | 15min | +| K7 | 联调验证 (需 KMS 环境) | — | 2h | +| K8 | Phase 2: 远程授权 + 前端按钮 | 3 文件 | 3h | + +--- + +> **版本历史**: +> - v1.0 (2025-05-17) — 初版，未完整覆盖所有接口 +> - v2.0 (2025-05-19) — 完整覆盖 50+ REST 接口，明确 Phase 1/2 分界，修正技术栈为 .NET 8