g82tt/SecMPS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
29e12a235a2b8934ee606089a885501d04953351
SecMPS/doc/整合方案/KMS钥匙柜整合方案_v1.0.md

8.6 KiB
Raw Blame History

钥匙柜（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

/// 认证流程: 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 能力接口

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 配置新增

// appsettings.json
{
  "KMS": {
    "InstanceName": "main",
    "BaseUrl": "http://192.168.1.50:8080",
    "ClientId": "your_client_id",
    "ClientSecret": "your_client_secret"
  }
}

3.5 Program.cs 注册

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/ 前缀可能变化）。

Reference in New Issue View Git Blame Copy Permalink