SecMPS/doc/设计文档/KMS钥匙柜适配器详细设计文档_任务清单.md

KMS 钥匙柜适配器 — 任务清单

基准文档: doc/设计文档/KMS钥匙柜适配器详细设计文档.md 分支: gateway-dev 原则: 严格按照设计文档执行，不凭空添加。网关/Vol.Pro 改动放倒数第二步，联调放最后。

---

Phase K0: 项目骨架（预计 15min）

K0.1 创建适配器项目

• 在 gateway/src/ 下执行 dotnet new classlib -n IntegrationGateway.Adapters.Kms -f net8.0
• 删除自动生成的 Class1.cs
• 添加项目引用：dotnet add reference ../IntegrationGateway.Core/IntegrationGateway.Core.csproj
• 将项目加入解决方案：dotnet sln add

K0.2 Host 引用适配器

• dotnet add Host reference Adapters.Kms

K0.3 编译验证

• dotnet build → 0 错误

K0 提交点: PhaseK0_scaffold — Kms适配器项目骨架就绪

---

Phase K1: KmsModels — 数据模型（预计 1h）

K1.1 认证模型

• 创建 KmsModels.cs
• KmsTokenResponse { Code, Token, Msg }

K1.2 第三方接口响应模型（2.18.X）

• KmsOpenerListResponse { Code, Msg, Rows }
• KmsLocker { LockerId, LockerName, LockerCode, LockholeList }
• KmsLockhole { LockholeSort, OpenerId, OpenerName, OpenerType, OpenerState }
• KmsWarningListResponse { Code, Msg, Total, Rows }
• KmsWarning { Uuid, LockerName, LockholeSort, OpenerName, Type, WarningTime, Remark, StaffName }
• KmsRecordListResponse { Code, Msg, Total, Rows }
• KmsRecord { Uuid, LockerName, LockholeSort, OpenerName, StaffName, BorrowTime, ReturnTime, Type }

K1.3 编译验证

• dotnet build → 0 错误

K1 提交点: PhaseK1_models — KmsModels.cs 完整定义全部响应 DTO

---

Phase K2: KmsAuthHelper — 认证（预计 30min）

K2.1 创建 KmsAuthHelper.cs

• 构造函数：接收 HttpClient, baseUrl, clientId, clientSecret
• 属性：_token (string?), _tokenExpiry (DateTime)

K2.2 GetTokenAsync

• POST /prod-api/getToken?clientId=xx&clientSecret=yy
• 校验 Code == 200
• 缓存 Token，过期时间 = UtcNow.AddMinutes(25)（30 分钟效期，5 分钟余量）

K2.3 GetAuthenticatedClientAsync

• 创建 HttpClient，设置 Authorization: Bearer {token}
• Invalidate() → _token = null

K2.4 编译验证

• dotnet build → 0 错误

K2 提交点: PhaseK2_auth — Bearer Token 认证就绪

---

Phase K3: KmsAdapter 核心方法（预计 1.5h）

K3.1 类定义

• public class KmsAdapter : IHasFlatDevices, IHasAlarms
• 属性：AdapterCode, DisplayName, Capabilities

K3.2 HealthCheckAsync（2.18.1）

• GET /prod-api/heartBeat
• 异常捕获返回 false + Console.Error 打日志

K3.3 GetDevicesAsync（2.18.4）

• POST /prod-api/getOpenerList (body {})
• 遍历柜体/锁孔 → 映射为 StandardDevice
• 父设备 IsParent=是, 子设备 ParentSourceId=locker_{id}

K3.4 GetAlarmsAsync（2.18.7）

• POST /prod-api/getWarningList
• 映射 KmsWarning → StandardAlarm
• AlarmId=uuid, Status=Type==1?"未确认":"已结束"

K3.5 ConfirmAlarmAsync / EndAlarmAsync

• Confirm 调标准接口；End 留空实现

K3.6 编译验证

• dotnet build → 0 错误

K3 提交点: PhaseK3_adapter_core — 核心4方法就绪

---

Phase K4: 扩展方法（预计 1h）

K4.1 借还/授权/员工/登录

• GetBorrowRecordsAsync（2.18.6）
• GetPermissionListAsync（2.18.5）
• BatchSyncStaffAsync（2.18.3）
• BatchDeleteStaffAsync（2.18.2）
• RemoteAuthorizeAsync（2.4.3）
• ThirdPlatLoginAsync（2.18.8）

K4.2 编译验证

• dotnet build → 0 错误

K4 提交点: PhaseK4_adapter_ext — 6个扩展方法就绪

---

Phase K5: 配置与注册（预计 15min）

K5.1 KmsConfig POCO

• 在 Program.cs 同级加 class，属性：InstanceName, BaseUrl, ClientId, ClientSecret

K5.2 appsettings.json

• 新增 KMS 数组配置段

K5.3 Program.cs 注册

• var kmsList = app.Configuration.GetSection("KMS").Get<List<KmsConfig>>() ?? new();
• foreach 注册 KmsAdapter("KMS:{InstanceName}", ...)

K5 提交点: PhaseK5_config — 配置+注册就绪

---

Phase K6: 编译与自测（预计 15min）

K6.1 编译验证

• dotnet build → 0 错误

K6 提交点: PhaseK6_build — 全量编译通过

---

Phase K7: Vol.Pro 端配套（预计 1h）

K7.1 字典

• 管理端设备种类字典 ← "智能钥匙柜" + "钥匙位"

K7.2 前端按钮

• base_device.vue 操作列：门禁设备 → [开门] [授权] 按钮

K7 提交点: PhaseK7_volpro — 字典+前端就绪

---

Phase K8: 联调验证（预计 3h，需 KMS 环境）

K8.1 认证

• 网关启动 → KmsAdapter.InitializeAsync 成功

K8.2 设备/告警/记录

• /api/gateway/devices?adapter=KMS:main → 返回柜体+锁孔
• /api/gateway/alarms/KMS:main → 返回告警列表
• /api/gateway/control/KMS:main → 远程开门

K9: 联调文档记录

• 记录异常接口到 KMS_联调笔记.txt

K8 提交点: PhaseK8_integration — 全链路联调通过

---

Phase	内容	文件	预计
K0	项目骨架	2	15min
K1	全部 DTO	1	1h
K2	AuthHelper	1	30min
K3	核心方法	1	1.5h
K4	扩展方法	1	1h
K5	配置注册	3	15min
K6	编译	—	15min
K7	VolPro配套	2	1h
K8	联调	—	3h
合计	—	11	~9h