257 lines
10 KiB
Markdown
257 lines
10 KiB
Markdown
# 钥匙柜（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
|