184 lines
5.5 KiB
Markdown
184 lines
5.5 KiB
Markdown
# 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** |
|