501 lines
17 KiB
Markdown
501 lines
17 KiB
Markdown
# KMS 钥匙柜适配器详细设计文档
|
||
|
||
> **版本**: 1.0
|
||
> **日期**: 2025-05-19
|
||
> **基准**: `doc/整合方案/KMS钥匙柜整合方案_v2.0.md`
|
||
> **技术栈**: .NET 8 / ASP.NET Core / C#
|
||
> **架构**: IntegrationGateway 适配器模式
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 设计目标
|
||
|
||
在 IntegrationGateway 中新增 `KmsAdapter`，将智能钥匙管理系统（KMS）作为第三个子系统接入 SecMPS 整合平台。KMS 通过网关的 `IHasFlatDevices` 上报柜体/锁孔设备树，通过 `IHasAlarms` 上报告警记录，由 Vol.Pro 管理端统一展示和管理。
|
||
|
||
### 1.2 技术约束
|
||
|
||
| 约束 | 说明 |
|
||
|------|------|
|
||
| 不修改 Core 接口 | 复用现有 `IHasFlatDevices` + `IHasAlarms`，不需新增接口 |
|
||
| 不依赖 KMS 运行时 | `dotnet build` 可在无 KMS 环境下通过 |
|
||
| 故障隔离 | KMS 离线不影响 Owl/MC4 适配器运行 |
|
||
| 限流 | KMS 无明确 QPS 限制，设 5 QPS 保守值 |
|
||
|
||
---
|
||
|
||
## 2. 系统架构
|
||
|
||
```
|
||
┌──────────────┐ HTTP (Bearer Token) ┌────────────────────┐
|
||
│ KMS 服务端 │◄──────────────────────────►│ IntegrationGateway │
|
||
│ :8080 │ /prod-api/* │ :5100 │
|
||
│ (Java) │ │ (NET 8) │
|
||
└──────────────┘ └────────┬───────────┘
|
||
│ B 组接口
|
||
▼
|
||
┌────────────────────┐
|
||
│ Vol.Pro 管理端 │
|
||
│ :9100 │
|
||
│ (NET 8) │
|
||
└────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
gateway/src/IntegrationGateway.Adapters.Kms/
|
||
├── IntegrationGateway.Adapters.Kms.csproj # 类库, net8.0
|
||
├── KmsAuthHelper.cs # Bearer Token 认证
|
||
├── KmsAdapter.cs # 适配器主体
|
||
└── KmsModels.cs # 请求/响应 DTO
|
||
```
|
||
|
||
### 3.1 依赖关系
|
||
|
||
```
|
||
Host → Adapters.Kms → Core
|
||
Host → Core
|
||
```
|
||
|
||
适配器只引用 Core，零外部 NuGet 依赖（除 Microsoft.Extensions.Http 已由 Core 引入）。
|
||
|
||
---
|
||
|
||
## 4. KMS 接口详细参考
|
||
|
||
### 4.1 认证
|
||
|
||
**POST** `/prod-api/getToken`
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| clientId | query | 由 KMS 分配的客户端ID |
|
||
| clientSecret | query | 由 KMS 分配的客户端密钥 |
|
||
|
||
响应：
|
||
```json
|
||
{ "code": 200, "token": "eyJ...", "msg": "操作成功" }
|
||
```
|
||
|
||
### 4.2 第三方接口（Phase 1 实现 4 个）
|
||
|
||
#### 4.2.1 心跳 — `POST /prod-api/heartBeat`
|
||
|
||
请求体：`{}` (空 JSON)
|
||
|
||
响应：
|
||
```json
|
||
{ "code": 200, "msg": "success" }
|
||
```
|
||
|
||
#### 4.2.2 柜体钥匙列表 — `POST /prod-api/getOpenerList`
|
||
|
||
请求体：`{}`
|
||
|
||
响应（核心字段）：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"rows": [{
|
||
"lockerId": 25,
|
||
"lockerName": "10位智能公共钥匙柜",
|
||
"lockerCode": "888",
|
||
"lockholeList": [{
|
||
"lockholeSort": 1,
|
||
"openerId": 2020,
|
||
"openerName": "仓库大门钥匙",
|
||
"openerType": "永久授权",
|
||
"openerState": "在位"
|
||
}]
|
||
}]
|
||
}
|
||
```
|
||
|
||
#### 4.2.3 告警列表 — `POST /prod-api/getWarningList`
|
||
|
||
请求体：`{}`（所有告警）或带时间范围
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"total": 5,
|
||
"rows": [{
|
||
"uuid": "xxx",
|
||
"lockerName": "10位公共钥匙柜",
|
||
"lockholeSort": 3,
|
||
"openerName": "机房钥匙",
|
||
"type": 1,
|
||
"warningTime": "2025-05-19 10:30:00",
|
||
"remark": "超时未归还",
|
||
"staffName": "张三"
|
||
}]
|
||
}
|
||
```
|
||
|
||
#### 4.2.4 借还记录 — `POST /prod-api/getRecordList`（Phase 2 参考）
|
||
|
||
请求体：`{}`
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"total": 10,
|
||
"rows": [{
|
||
"uuid": "xxx",
|
||
"lockerName": "10位公共钥匙柜",
|
||
"lockholeSort": 2,
|
||
"openerName": "仓库大门钥匙",
|
||
"staffName": "张三",
|
||
"borrowTime": "2025-05-19 09:00:00",
|
||
"returnTime": "2025-05-19 11:00:00",
|
||
"type": "1"
|
||
}]
|
||
}
|
||
```
|
||
|
||
### 4.3 标准业务接口（Phase 2 参考，共 50+）
|
||
|
||
见 `doc/整合方案/KMS钥匙柜整合方案_v2.0.md` §1.3。
|
||
|
||
---
|
||
|
||
## 5. KmsModels 详细设计
|
||
|
||
```csharp
|
||
namespace IntegrationGateway.Adapters.Kms;
|
||
|
||
// ── 认证 ──
|
||
public class KmsTokenResponse { public int Code { get; set; } public string Token { get; set; } = ""; public string? Msg { get; set; } }
|
||
|
||
// ── 第三方接口响应 ──
|
||
public class KmsOpenerListResponse { public int Code { get; set; } public string? Msg { get; set; } public List<KmsLocker> Rows { get; set; } = new(); }
|
||
public class KmsLocker { public int LockerId { get; set; } public string? LockerName { get; set; } public string? LockerCode { get; set; } public List<KmsLockhole> LockholeList { get; set; } = new(); }
|
||
public class KmsLockhole { public int LockholeSort { get; set; } public int OpenerId { get; set; } public string? OpenerName { get; set; } public string? OpenerType { get; set; } public string? OpenerState { get; set; } }
|
||
|
||
public class KmsWarningListResponse { public int Code { get; set; } public string? Msg { get; set; } public int Total { get; set; } public List<KmsWarning> Rows { get; set; } = new(); }
|
||
public class KmsWarning { public string? Uuid { get; set; } public string? LockerName { get; set; } public int LockholeSort { get; set; } public string? OpenerName { get; set; } public int Type { get; set; } public string? WarningTime { get; set; } public string? Remark { get; set; } public string? StaffName { get; set; } }
|
||
|
||
public class KmsRecordListResponse { public int Code { get; set; } public int Total { get; set; } public List<KmsRecord> Rows { get; set; } = new(); }
|
||
public class KmsRecord { public string? Uuid { get; set; } public string? LockerName { get; set; } public int LockholeSort { get; set; } public string? OpenerName { get; set; } public string? StaffName { get; set; } public string? BorrowTime { get; set; } public string? ReturnTime { get; set; } public string? Type { get; set; } }
|
||
```
|
||
|
||
---
|
||
|
||
## 6. KmsAuthHelper 详细设计
|
||
|
||
```csharp
|
||
/// <summary>
|
||
/// KMS Bearer Token 认证辅助。
|
||
///
|
||
/// 流程:
|
||
/// 1. POST /prod-api/getToken?clientId={}&clientSecret={}
|
||
/// 2. 返回 { code: 200, token: "xxx" }
|
||
/// 3. Token 缓存 25 分钟 (KMS 有效期 30 分钟，留 5 分钟余量)
|
||
/// </summary>
|
||
public class KmsAuthHelper
|
||
{
|
||
private readonly HttpClient _http;
|
||
private readonly string _baseUrl;
|
||
private readonly string _clientId;
|
||
private readonly string _clientSecret;
|
||
private string? _token;
|
||
private DateTime _tokenExpiry = DateTime.MinValue;
|
||
|
||
public KmsAuthHelper(HttpClient http, string baseUrl, string clientId, string clientSecret)
|
||
{
|
||
_http = http; _baseUrl = baseUrl.TrimEnd('/');
|
||
_clientId = clientId; _clientSecret = clientSecret;
|
||
}
|
||
|
||
public async Task<string> GetTokenAsync()
|
||
{
|
||
if (!string.IsNullOrEmpty(_token) && DateTime.UtcNow < _tokenExpiry)
|
||
return _token;
|
||
|
||
var resp = await _http.PostAsync(
|
||
$"{_baseUrl}/prod-api/getToken?clientId={Uri.EscapeDataString(_clientId)}&clientSecret={Uri.EscapeDataString(_clientSecret)}",
|
||
null);
|
||
resp.EnsureSuccessStatusCode();
|
||
var result = await resp.Content.ReadFromJsonAsync<JsonElement>();
|
||
var code = result.GetProperty("code").GetInt32();
|
||
if (code != 200) throw new Exception($"KMS 认证失败: {code}");
|
||
_token = result.GetProperty("token").GetString();
|
||
_tokenExpiry = DateTime.UtcNow.AddMinutes(25); // 30min TTL, 25min 刷新
|
||
return _token!;
|
||
}
|
||
|
||
public async Task<HttpClient> GetAuthenticatedClientAsync()
|
||
{
|
||
var token = await GetTokenAsync();
|
||
var client = new HttpClient { BaseAddress = new Uri(_baseUrl) };
|
||
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
|
||
return client;
|
||
}
|
||
|
||
public void Invalidate() => _token = null;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. KmsAdapter 详细设计
|
||
|
||
```csharp
|
||
/// <summary>
|
||
/// KMS 智能钥匙柜适配器。实现 IHasFlatDevices + IHasAlarms。
|
||
///
|
||
/// 设备模型：柜体为父设备(IsParent=是)，锁孔为子设备(ParentSourceId=柜体ID)。
|
||
/// 限流：5 QPS。
|
||
/// AdapterCode: "KMS:{InstanceName}"
|
||
/// </summary>
|
||
public class KmsAdapter : IHasFlatDevices, IHasAlarms
|
||
{
|
||
private readonly HttpClient _http;
|
||
private readonly KmsAuthHelper _auth;
|
||
private readonly RateLimiter _limiter = new(5);
|
||
|
||
public string AdapterCode { get; }
|
||
public string DisplayName => $"KMS ({AdapterCode})";
|
||
public AdapterCapabilities Capabilities => new() { HasFlatDevices = true, HasAlarms = true };
|
||
|
||
public KmsAdapter(string adapterCode, HttpClient http, string baseUrl, string clientId, string clientSecret)
|
||
{
|
||
AdapterCode = adapterCode;
|
||
_http = http;
|
||
_auth = new KmsAuthHelper(http, baseUrl, clientId, clientSecret);
|
||
}
|
||
|
||
public async Task InitializeAsync() => await _auth.GetTokenAsync();
|
||
|
||
// ── HealthCheck → 2.18.1 心跳 ──
|
||
public async Task<bool> HealthCheckAsync()
|
||
{
|
||
try
|
||
{
|
||
var client = await _auth.GetAuthenticatedClientAsync();
|
||
var resp = await client.PostAsync("/prod-api/heartBeat",
|
||
new StringContent("{}", Encoding.UTF8, "application/json"));
|
||
return resp.IsSuccessStatusCode;
|
||
}
|
||
catch { return false; }
|
||
}
|
||
|
||
// ── IHasFlatDevices → 2.18.4 柜体钥匙列表 ──
|
||
public async Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword = null)
|
||
{
|
||
await _limiter.WaitAsync();
|
||
var client = await _auth.GetAuthenticatedClientAsync();
|
||
var resp = await client.PostAsync("/prod-api/getOpenerList",
|
||
new StringContent("{}", Encoding.UTF8, "application/json"));
|
||
resp.EnsureSuccessStatusCode();
|
||
var data = await resp.Content.ReadFromJsonAsync<KmsOpenerListResponse>()!;
|
||
|
||
var devices = new List<StandardDevice>();
|
||
foreach (var locker in data.Rows)
|
||
{
|
||
// 父设备: 柜体
|
||
devices.Add(new StandardDevice
|
||
{
|
||
SourceId = $"locker_{locker.LockerId}",
|
||
Name = locker.LockerName ?? $"柜体{locker.LockerId}",
|
||
Category = "智能钥匙柜", Group = "门禁设备",
|
||
IsParent = true, IsOnline = true,
|
||
Extra = new Dictionary<string, object?>
|
||
{
|
||
["lockerCode"] = locker.LockerCode,
|
||
["lockholeCount"] = locker.LockholeList.Count
|
||
}
|
||
});
|
||
// 子设备: 锁孔
|
||
foreach (var hole in locker.LockholeList)
|
||
{
|
||
bool isOnline = hole.OpenerState == "在位";
|
||
devices.Add(new StandardDevice
|
||
{
|
||
SourceId = $"lockhole_{locker.LockerId}_{hole.LockholeSort}",
|
||
Name = hole.OpenerName ?? $"锁孔{hole.LockholeSort}",
|
||
Category = "钥匙位", Group = "门禁设备",
|
||
IsParent = false, IsOnline = isOnline,
|
||
ParentSourceId = $"locker_{locker.LockerId}",
|
||
Extra = new Dictionary<string, object?>
|
||
{
|
||
["openerId"] = hole.OpenerId,
|
||
["openerType"] = hole.OpenerType,
|
||
["openerState"] = hole.OpenerState
|
||
}
|
||
});
|
||
}
|
||
}
|
||
return new PagedResult<StandardDevice> { Items = devices, Total = devices.Count };
|
||
}
|
||
|
||
// ── IHasAlarms → 2.18.7 告警列表 ──
|
||
public async Task<PagedResult<StandardAlarm>> GetAlarmsAsync(
|
||
int page, int size, DateTime from, DateTime to, string? level = null, string? state = null)
|
||
{
|
||
await _limiter.WaitAsync();
|
||
var client = await _auth.GetAuthenticatedClientAsync();
|
||
var resp = await client.PostAsync("/prod-api/getWarningList",
|
||
new StringContent("{}", Encoding.UTF8, "application/json"));
|
||
resp.EnsureSuccessStatusCode();
|
||
var data = await resp.Content.ReadFromJsonAsync<KmsWarningListResponse>()!;
|
||
|
||
var alarms = data.Rows.Select(w => new StandardAlarm
|
||
{
|
||
AlarmId = w.Uuid ?? "", AdapterCode = AdapterCode,
|
||
Level = "普通", // KMS 不区分告警等级，统一"普通"
|
||
Title = $"{w.LockerName} 锁孔{w.LockholeSort}: {w.OpenerName}",
|
||
Content = w.Remark,
|
||
OccurTime = DateTime.TryParse(w.WarningTime, out var t) ? t : DateTime.MinValue,
|
||
Status = w.Type == 1 ? "未确认" : "已结束"
|
||
}).ToList();
|
||
|
||
return new PagedResult<StandardAlarm> { Items = alarms, Total = data.Total };
|
||
}
|
||
|
||
public async Task ConfirmAlarmAsync(string alarmId)
|
||
{
|
||
// KMS 2.18 接口不提供告警确认，调用标准接口
|
||
await _limiter.WaitAsync();
|
||
var client = await _auth.GetAuthenticatedClientAsync();
|
||
await client.PostAsync($"/prod-api/kms/warning/confirm/{alarmId}", null);
|
||
}
|
||
|
||
public async Task EndAlarmAsync(string alarmId)
|
||
{
|
||
// KMS 2.18 接口不提供告警结束
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 设备映射逻辑
|
||
|
||
```
|
||
POST /prod-api/getOpenerList 响应
|
||
│
|
||
▼
|
||
遍历每个 KmsLocker
|
||
├── 生成 1 个父 StandardDevice (SourceId="locker_{lockerId}", IsParent=true)
|
||
└── 遍历 lockholeList
|
||
└── 每个 lockhole 生成 1 个子 StandardDevice
|
||
(SourceId="lockhole_{lockerId}_{lockholeSort}", ParentSourceId="locker_{lockerId}")
|
||
(IsOnline = OpenerState=="在位" ? true : false)
|
||
```
|
||
|
||
**parentSourceId 解析**（A3 同步时在 gateway_nodesService.SyncDevicesAsync 中处理）：
|
||
```
|
||
"locker_{lockerId}" → 查询 base_device WHERE SourceId='locker_{lockerId}' → 获取 DeviceId → 填入子设备的 ParentDeviceId
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 告警映射逻辑
|
||
|
||
```
|
||
POST /prod-api/getWarningList 响应
|
||
│
|
||
▼
|
||
遍历每个 KmsWarning
|
||
├── AlarmId ← uuid
|
||
├── Title ← "{lockerName} 锁孔{lockholeSort}: {openerName}"
|
||
├── Content ← remark
|
||
├── OccurTime ← warningTime
|
||
├── Status ← Type==1 ? "未确认" : "已结束"
|
||
└── Level ← "普通" (KMS 不区分告警等级)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 配置
|
||
|
||
### 10.1 appsettings.json
|
||
|
||
```json
|
||
{
|
||
"KMS": {
|
||
"InstanceName": "main",
|
||
"BaseUrl": "http://192.168.1.50:8080",
|
||
"ClientId": "your_client_id",
|
||
"ClientSecret": "your_client_secret"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10.2 KmsConfig POCO
|
||
|
||
```csharp
|
||
public class KmsConfig
|
||
{
|
||
public string? InstanceName { get; set; }
|
||
public string BaseUrl { get; set; } = "";
|
||
public string ClientId { get; set; } = "";
|
||
public string ClientSecret { get; set; } = "";
|
||
}
|
||
```
|
||
|
||
### 10.3 Program.cs 注册
|
||
|
||
```csharp
|
||
var kmsList = app.Configuration.GetSection("KMS").Get<List<KmsConfig>>() ?? new();
|
||
foreach (var k in kmsList)
|
||
{
|
||
var code = $"KMS:{k.InstanceName ?? "default"}";
|
||
var a = new KmsAdapter(code,
|
||
app.Services.GetRequiredService<IHttpClientFactory>().CreateClient("VolPro"),
|
||
k.BaseUrl, k.ClientId, k.ClientSecret);
|
||
registry.Register(a);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 测试策略
|
||
|
||
### 11.1 单元测试（无 KMS 依赖）
|
||
|
||
| 测试 | 验证点 |
|
||
|------|------|
|
||
| KmsModels 序列化 | JSON 往返正确 |
|
||
| 设备映射 | locker + lockhole → StandardDevice 正确 |
|
||
| 告警映射 | KmsWarning → StandardAlarm 正确 |
|
||
|
||
### 11.2 集成测试（需 KMS 环境）
|
||
|
||
| 场景 | 预期 |
|
||
|------|------|
|
||
| 认证成功 | GetToken → 返回有效 token |
|
||
| 设备同步 | GetOpenerList → 返回柜体+锁孔列表 |
|
||
| 告警同步 | GetWarningList → 返回告警列表 |
|
||
| 健康检查 | HeartBeat → 200 OK |
|
||
| 认证失败 | 错误 clientId → 适配器初始化失败 |
|
||
| KMS 离线 | HealthCheck → false, 不影响 Owl/MC4 |
|
||
|
||
---
|
||
|
||
## 12. 实施计划
|
||
|
||
| 步骤 | 内容 | 文件 | 预计 |
|
||
|:---:|------|------|:---:|
|
||
| 1 | 创建 `Adapters.Kms` 项目 + 引用 | csproj, sln | 10min |
|
||
| 2 | `KmsModels.cs` | 1 文件 | 20min |
|
||
| 3 | `KmsAuthHelper.cs` | 1 文件 | 30min |
|
||
| 4 | `KmsAdapter.cs` (HealthCheck + GetDevices) | 1 文件 | 1h |
|
||
| 5 | `KmsAdapter.cs` (GetAlarms + Confirm/End) | 1 文件 | 30min |
|
||
| 6 | appsettings.json + Program.cs 注册 | 2 文件 | 15min |
|
||
| 7 | 编译验证 `dotnet build` | 网关 | 5min |
|
||
| 8 | 联调 (需 KMS 环境) | — | 2h |
|
||
|
||
---
|
||
|
||
> **版本历史**:
|
||
> - v1.0 (2025-05-19) — 初版详细设计
|