KMS整合方案v2.0: 完整覆盖50+REST接口 修正技术栈为.NET8

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 <token>` |
+
+### 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<string> GetTokenAsync() { ... }
+    public async Task<HttpClient> 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<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword);
+
+    // IHasAlarms → 2.18.7 POST /prod-api/getWarningList
+    public async Task<PagedResult<StandardAlarm>> 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<bool> 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<List<KmsConfig>>() ?? 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