Files

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

2026-05-19 14:40:09 +08:00

10 KiB

Raw Blame History

钥匙柜（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. 整合策略

核心原则

KMS 作为独立子系统，通过 IntegrationGateway 的 KmsAdapter 接入
Phase 1 实现第三方接口（8 个端点），这是 KMS 专门为集成设计的
Phase 2 按需扩展标准业务接口（远程授权/开门/借还记录查询）
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

/// .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

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 配置文件

// 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 注册

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

10 KiB Raw Blame History Unescape Escape

钥匙柜（KMS）整合方案 v2.0

1. KMS 系统全接口分析

1.1 认证体系

1.2 第三方专用接口（第 2.18 节 —— 整合核心）

1.3 标准 KMS 业务接口（第 2.3-2.17 节 —— 辅助参考）

2. 整合策略

核心原则

适配器能力矩阵

3. 设备树映射

4. 告警映射

5. 网关改造清单

5.1 新增项目

5.2 KmsAuthHelper

5.3 KmsAdapter

5.4 配置文件

5.5 Program.cs 注册

6. Vol.Pro 端改动

7. 实施计划

10 KiB

Raw Blame History