257 lines
8.6 KiB
Markdown
257 lines
8.6 KiB
Markdown
# 钥匙柜（KMS）整合方案 v1.0
|
||
|
||
> **版本**: 1.0
|
||
> **日期**: 2025-05-19
|
||
> **数据源**: doc/对接文档/钥匙管理系统软件接口.docx
|
||
> **架构**: IntegrationGateway 适配器模式 + Vol.Pro 管理端
|
||
|
||
---
|
||
|
||
## 1. 现状分析
|
||
|
||
### 1.1 KMS 系统概览
|
||
|
||
钥匙管理系统是一个独立的 REST API 服务，管理智能钥匙柜的硬件设备。
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 技术栈 | Java/Spring Boot (推测) |
|
||
| 认证方式 | clientId/clientSecret → Bearer Token (30分钟) |
|
||
| 数据模型 | 柜体(locker) → 锁孔(lockhole) → 钥匙(opener) |
|
||
| 用户体系 | 员工(staff) + 员工组(staff group) |
|
||
| 核心业务 | 借还记录、交接记录、远程授权、告警记录 |
|
||
|
||
### 1.2 KMS 第三方集成接口（第2.18节）
|
||
|
||
KMS 预留了 8 个专用于第三方对接的接口：
|
||
|
||
| 接口 | 路径 | 用途 |
|
||
|------|------|------|
|
||
| 心跳 | `/prod-api/kms/thirdparty/heartbeat` | 检测 KMS 存活 |
|
||
| 批量删除员工 | `/prod-api/kms/staff/batchDelete` | 同步删除 |
|
||
| 批量同步员工 | `/prod-api/kms/staff/batchSync` | 同步员工信息 |
|
||
| 查询柜体钥匙 | `/prod-api/kms/thirdparty/locker/keys` | 获取所有柜体及其钥匙列表 |
|
||
| 授权记录 | `/prod-api/kms/thirdparty/auth/records` | 查询远程授权历史 |
|
||
| 借还记录 | `/prod-api/kms/thirdparty/borrow/records` | 查询借还日志 |
|
||
| 告警记录 | `/prod-api/kms/thirdparty/alarm/records` | 查询告警列表 |
|
||
| 事件记录 | `/prod-api/kms/thirdparty/event/records` | 查询系统事件 |
|
||
|
||
认证方式：所有接口需要在 `Authorization: Bearer <token>` 头中携带 Token。
|
||
|
||
### 1.3 Vol.Pro 端现存钥匙相关模块
|
||
|
||
| 表/模块 | 说明 | 来源 |
|
||
|----------|------|------|
|
||
| `warehouse_keys` | 钥匙管理（自主） | Vol.Pro 代码生成 |
|
||
| `warehouse_keyapply` | 钥匙领用申请 | Vol.Pro 代码生成 |
|
||
| `warehouse_keylog` | 钥匙使用日志 | Vol.Pro 代码生成 |
|
||
|
||
这些是 Vol.Pro 自建的钥匙管理流程（申请→审批→记录），与硬件 KMS 系统平行运行。
|
||
|
||
---
|
||
|
||
## 2. 整合策略
|
||
|
||
### 2.1 核心决策
|
||
|
||
**KMS 作为一个独立的物联网子系统接入 IntegrationGateway**，与 Owl、MC4.0 平级。
|
||
|
||
通过适配器模式，KMS 的能力被抽象为统一的网关接口，Vol.Pro 管理端通过网关调用 KMS，无需直接对 KMS 编程。
|
||
|
||
### 2.2 KMS 能力评估
|
||
|
||
| 能力 | KMS 支持 | 统一接口 | 实现优先级 |
|
||
|------|:---:|------|:---:|
|
||
| 设备列表 | ✅ (钥匙柜+钥匙) | `IHasFlatDevices` | Phase 1 |
|
||
| 告警 | ✅ (告警记录) | `IHasAlarms` | Phase 1 |
|
||
| 实时状态 | ❌ | 无 | — |
|
||
| 远程控制 | ✅ (远程授权/开门) | `IAcceptsControl` (新增) | Phase 2 |
|
||
| 借还记录 | ✅ | 新增接口 | Phase 2 |
|
||
| 员工同步 | ✅ | 无 (单向推送) | Phase 2 |
|
||
|
||
### 2.3 设备模型映射
|
||
|
||
KMS 的物理拓扑是 **柜体 → 锁孔 → 钥匙**。映射到 `StandardDevice`：
|
||
|
||
```
|
||
KMS 柜体 (locker) → StandardDevice { DeviceGroup="门禁设备", DeviceCategory="智能钥匙柜", IsParent=true }
|
||
KMS 锁孔 (lockhole) → StandardDevice { DeviceGroup="门禁设备", DeviceCategory="钥匙位", IsParent=false, ParentSourceId=柜体SourceId }
|
||
(钥匙本身是一个逻辑实体,不映射为设备)
|
||
```
|
||
|
||
**示例**：
|
||
|
||
```
|
||
KMS "10位智能公共钥匙柜" (lockerId=25)
|
||
├── 钥孔1 "仓库大门钥匙" (lockholeSort=1)
|
||
├── 钥孔2 "机房钥匙" (lockholeSort=2)
|
||
├── ...
|
||
└── 钥孔10 "配电室钥匙" (lockholeSort=10)
|
||
```
|
||
|
||
每个锁孔又是一个 `StandardDevice`，其 `Extra` 字段承载钥匙状态（在位/离位/借出）。
|
||
|
||
---
|
||
|
||
## 3. 网关改造
|
||
|
||
### 3.1 新增 `IntegrationGateway.Adapters.Kms`
|
||
|
||
```
|
||
gateway/src/IntegrationGateway.Adapters.Kms/
|
||
├── KmsAdapter.cs # IHasFlatDevices + IHasAlarms
|
||
└── KmsAuthHelper.cs # clientId/clientSecret → Bearer Token
|
||
```
|
||
|
||
### 3.2 KmsAuthHelper
|
||
|
||
```csharp
|
||
/// 认证流程: POST /prod-api/kms/token?clientId=xxx&clientSecret=yyy → { code, token }
|
||
/// Token 有效期 30 分钟, 过期前 5 分钟自动刷新
|
||
public class KmsAuthHelper
|
||
{
|
||
public async Task<string> GetTokenAsync() { ... }
|
||
public async Task<HttpClient> GetAuthenticatedClientAsync() { ... }
|
||
}
|
||
```
|
||
|
||
### 3.3 KmsAdapter 能力接口
|
||
|
||
```csharp
|
||
public class KmsAdapter : IHasFlatDevices, IHasAlarms
|
||
{
|
||
public string AdapterCode { get; } // "KMS:main"
|
||
public AdapterCapabilities Capabilities => new()
|
||
{
|
||
HasFlatDevices = true, HasAlarms = true
|
||
};
|
||
|
||
// IHasFlatDevices: 查询柜体钥匙信息 → List<StandardDevice>
|
||
public async Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword)
|
||
{
|
||
// 调 2.18.4 GET /prod-api/kms/thirdparty/locker/keys
|
||
// 展开为: 每个柜体 → 1个父设备, 每个锁孔 → 1个子设备
|
||
}
|
||
|
||
// IHasAlarms: 查询告警记录
|
||
public async Task<PagedResult<StandardAlarm>> GetAlarmsAsync(...)
|
||
{
|
||
// 调 2.18.7 GET /prod-api/kms/thirdparty/alarm/records
|
||
// KMS 告警类型: 1=当前告警, 2=历史告警
|
||
}
|
||
|
||
public async Task ConfirmAlarmAsync(string alarmId) { ... }
|
||
public async Task EndAlarmAsync(string alarmId) { ... }
|
||
}
|
||
```
|
||
|
||
### 3.4 配置新增
|
||
|
||
```json
|
||
// appsettings.json
|
||
{
|
||
"KMS": {
|
||
"InstanceName": "main",
|
||
"BaseUrl": "http://192.168.1.50:8080",
|
||
"ClientId": "your_client_id",
|
||
"ClientSecret": "your_client_secret"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.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"}", http, k.BaseUrl, k.ClientId, k.ClientSecret));
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Vol.Pro 管理端改动
|
||
|
||
### 4.1 数据流向
|
||
|
||
```
|
||
KMS 硬件柜 IntegrationGateway Vol.Pro
|
||
─────── ────────────── ──────
|
||
钥匙在位/离位 ────→ KmsAdapter.GetDevices ────→ base_device 表
|
||
(AdapterCode="KMS:main")
|
||
(DeviceCategory="钥匙位")
|
||
告警事件 ────→ KmsAdapter.GetAlarms ────→ iot_alarm 表
|
||
远程授权开门 ←──── B-interface (Phase2) ←──── 管理端操作
|
||
```
|
||
|
||
### 4.2 不需要改的内容
|
||
|
||
- `warehouse_keys` / `warehouse_keyapply` / `warehouse_keylog` — 保留现有体系，不与 KMS 冲突
|
||
- `base_device` 表 — 已支持 `DeviceCategory="钥匙位"`、`DeviceGroup="门禁设备"`
|
||
- 前端操作列 — 已预留 `AccessDeviceActions` / `AlarmDeviceActions` 骨架
|
||
- 管理端设备列表 — 自动显示 KMS 同步的设备
|
||
|
||
### 4.3 需要新增的内容
|
||
|
||
| 项 | 说明 |
|
||
|------|------|
|
||
| KMS 数据字典项 | `设备种类` 字典增加 "智能钥匙柜"、"钥匙位" |
|
||
| 前端 KMS 操作按钮 | `KeyDeviceActions.vue` — 显示钥匙状态 + 远程授权入口 (Phase 2) |
|
||
|
||
---
|
||
|
||
## 5. 数据映射表
|
||
|
||
### 5.1 KMS 柜体 → StandardDevice
|
||
|
||
| KMS 字段 | StandardDevice 字段 |
|
||
|------|------|
|
||
| lockerId | SourceId |
|
||
| lockerName | Name |
|
||
| "智能钥匙柜" | Category |
|
||
| "门禁设备" | Group |
|
||
| true | IsParent |
|
||
| lockerCode | Extra.lockerCode |
|
||
| online (健康检查) | IsOnline |
|
||
|
||
### 5.2 KMS 锁孔 → StandardDevice
|
||
|
||
| KMS 字段 | StandardDevice 字段 |
|
||
|------|------|
|
||
| lockerId.lockholeSort | SourceId (组合) |
|
||
| openerName (钥匙名) | Name |
|
||
| "钥匙位" | Category |
|
||
| "门禁设备" | Group |
|
||
| false | IsParent |
|
||
| lockerId | ParentSourceId |
|
||
| openerState (在位/离位) | Extra.openerState |
|
||
| openerType (永久授权/一次性授权/应急授权) | Extra.openerType |
|
||
|
||
### 5.3 KMS 告警 → StandardAlarm
|
||
|
||
| KMS 字段 | StandardAlarm 字段 |
|
||
|------|------|
|
||
| uuid | AlarmId (SourceAlarmId) |
|
||
| warningTime | OccurTime |
|
||
| alarmType 映射 | Level (提示/普通/重要) |
|
||
| lockerName + openerName | Title |
|
||
| remark | Content |
|
||
|
||
---
|
||
|
||
## 6. 实施计划
|
||
|
||
| 阶段 | 内容 | 预计工时 |
|
||
|------|------|:---:|
|
||
| K1 | 创建 `IntegrationGateway.Adapters.Kms` 项目骨架 | 0.5h |
|
||
| K2 | 实现 `KmsAuthHelper` (clientId/secret → Token) | 1h |
|
||
| K3 | 实现 `KmsAdapter` — `IHasFlatDevices` (设备同步) | 2h |
|
||
| K4 | 实现 `KmsAdapter` — `IHasAlarms` (告警同步) | 1h |
|
||
| K5 | 网关配置 + Program.cs 注册 | 0.5h |
|
||
| K6 | 字典补充（智能钥匙柜/钥匙位） | 0.5h |
|
||
| K7 | 联调验证 (需 KMS 环境) | 2h |
|
||
| K8 | Phase 2: 远程授权/开门 + 前端按钮 | 3h |
|
||
|
||
---
|
||
|
||
> **风险**: KMS 的实际 API 路径和响应格式需在真实环境验证，文档中的路径格式可能与实际部署有差异（如 `/prod-api/kms/` 前缀可能变化）。
|