204 lines
8.8 KiB
Markdown
204 lines
8.8 KiB
Markdown
# IntegrationGateway 对接网关详细设计 — 任务清单
|
||
|
||
> **基准文档**: 对接网关设计文档 v1.0
|
||
> **分支**: phase/0-infrastructure
|
||
> **原则**: 每阶段产出可编译、可提交的独立成果
|
||
|
||
---
|
||
|
||
## Phase G0: 项目骨架与核心抽象（预计 1 天）
|
||
|
||
### G0.1 解决方案与项目结构
|
||
- [ ] 创建 `gateway/IntegrationGateway.sln`（dotnet new sln）
|
||
- [ ] 创建 `src/IntegrationGateway.Core/` 类库项目（net8.0）
|
||
- [ ] 创建 `src/IntegrationGateway.Host/` Web 项目（net8.0, ASP.NET Core Minimal API）
|
||
- [ ] Host 引用 Core 项目
|
||
- [ ] 确认 `dotnet build` 0 错误
|
||
|
||
### G0.2 能力接口体系（7 个接口）
|
||
- [ ] 创建 `Core/Abstractions/IGatewayAdapter.cs` — 基础接口（AdapterCode/DisplayName/Capabilities/InitializeAsync/HealthCheckAsync）
|
||
- [ ] 创建 `Core/Abstractions/IHasOwnDeviceTree.cs` — 对象树接口
|
||
- [ ] 创建 `Core/Abstractions/IHasFlatDevices.cs` — 扁平设备列表接口
|
||
- [ ] 创建 `Core/Abstractions/IHasPoints.cs` — 实时点位值 + 控制接口
|
||
- [ ] 创建 `Core/Abstractions/IHasStreams.cs` — 视频流 + PTZ + 截图接口
|
||
- [ ] 创建 `Core/Abstractions/IHasAlarms.cs` — 告警查询 + 确认 + 结束接口
|
||
- [ ] 创建 `Core/Abstractions/IHasRecordings.cs` — 录像回放接口
|
||
- [ ] 创建 `Core/Abstractions/IAcceptsMetadataPush.cs` — 元数据回写接口
|
||
- [ ] 确认 `dotnet build` 0 错误
|
||
|
||
### G0.3 统一模型（10 个类）
|
||
- [ ] 创建 `Core/Models/StandardDevice.cs`
|
||
- [ ] 创建 `Core/Models/StandardAlarm.cs`
|
||
- [ ] 创建 `Core/Models/StandardRecording.cs`
|
||
- [ ] 创建 `Core/Models/DeviceTreeNode.cs`
|
||
- [ ] 创建 `Core/Models/PointValue.cs`
|
||
- [ ] 创建 `Core/Models/StreamUrls.cs`
|
||
- [ ] 创建 `Core/Models/PagedResult.cs`（泛型分页容器）
|
||
- [ ] 创建 `Core/Models/AdapterCapabilities.cs`
|
||
- [ ] 创建 `Core/Models/MetadataChangeSet.cs`
|
||
- [ ] 创建 `Core/Models/MetadataPushResult.cs`
|
||
- [ ] 确认 `dotnet build` 0 错误
|
||
|
||
### G0.4 基础设施（3 个类）
|
||
- [ ] 创建 `Core/Infrastructure/AdapterRegistry.cs` — 注册/查找/并行初始化
|
||
- [ ] 创建 `Core/Infrastructure/RateLimiter.cs` — 令牌桶限流器
|
||
- [ ] 创建 `Core/Infrastructure/GatewayClientFactory.cs` — Vol.Pro HTTP 客户端工厂
|
||
- [ ] 确认 `dotnet build` 0 错误
|
||
|
||
> **G0 提交点**: `PhaseG0_gateway_core — Core 项目编译通过，7 接口 + 10 模型 + 3 基础设施`
|
||
|
||
---
|
||
|
||
## Phase G1: Host 宿主与路由注册（预计 0.5 天）
|
||
|
||
### G1.1 配置文件
|
||
- [ ] 创建 `appsettings.json` — Owl/MC4/Gateway 三段配置
|
||
- [ ] 配置验证：启动时检查必填项（VolProBaseUrl/NodeCode/NodeToken/Owl/MC4）
|
||
|
||
### G1.2 启动与注册
|
||
- [ ] 实现 `Program.cs` — IHttpClientFactory 注册（"VolPro" 命名客户端）
|
||
- [ ] 实现适配器初始化（从配置读取生成 OwlAdapter/MC4Adapter 实例 → 注册到 AdapterRegistry）
|
||
- [ ] 实现并行初始化（`Task.WhenAll`，单个失败不影响其他）
|
||
|
||
### G1.3 B 组路由（14 个端点）
|
||
- [ ] `GET /api/gateway/health` — 返回所有适配器健康状态
|
||
- [ ] `GET /api/gateway/devices?adapter=&page=&size=&keyword=` — 扁平设备列表
|
||
- [ ] `GET /api/gateway/tree?adapter=` — 对象树
|
||
- [ ] `GET /api/gateway/streams/{adapter}/{deviceId}/live` — 实时流地址
|
||
- [ ] `GET /api/gateway/streams/{adapter}/{deviceId}/playback?start=&end=` — 回放地址
|
||
- [ ] `POST /api/gateway/streams/{adapter}/{deviceId}/snapshot` — 截图
|
||
- [ ] `POST /api/gateway/streams/{adapter}/{deviceId}/ptz` — 云台控制
|
||
- [ ] `GET /api/gateway/realtime/{adapter}/{deviceId}` — 实时点位值
|
||
- [ ] `POST /api/gateway/realtime/{adapter}/control` — 设备控制写值
|
||
- [ ] `GET /api/gateway/alarms/{adapter}?from=&to=&page=&size=` — 告警查询
|
||
- [ ] `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm` — 告警确认
|
||
- [ ] `POST /api/gateway/alarms/{adapter}/{alarmId}/end` — 告警结束
|
||
- [ ] `GET /api/gateway/recordings/{adapter}/{deviceId}` — 录像列表
|
||
- [ ] `POST /api/gateway/devices/sync?adapter=` — 手动触发同步
|
||
- [ ] 确认 `dotnet build` 0 错误
|
||
|
||
### G1.4 错误处理中间件
|
||
- [ ] 统一错误响应格式：`{ error, message }`
|
||
- [ ] 适配器未找到 → 404 `ADAPTER_NOT_FOUND`
|
||
- [ ] 能力不支持 → 404 `CAPABILITY_NOT_SUPPORTED`
|
||
- [ ] 第三方超时 → 504 `UPSTREAM_TIMEOUT`
|
||
|
||
> **G1 提交点**: `PhaseG1_gateway_host — Host 编译通过，14 个路由骨架就绪，健康检查可响应`
|
||
|
||
---
|
||
|
||
## Phase G2: OwlAdapter（预计 1 天）
|
||
|
||
### G2.1 项目创建
|
||
- [ ] 创建 `src/IntegrationGateway.Adapters.Owl/` 类库项目（net8.0）
|
||
- [ ] 引用 Core 项目
|
||
- [ ] Host 引用 Adapters.Owl
|
||
- [ ] 加入解决方案
|
||
|
||
### G2.2 OwlAuthHelper
|
||
- [ ] 实现 RSA 公钥获取 → 加密登录 → JWT Token 缓存
|
||
- [ ] Token 过期前自动刷新（懒刷新）
|
||
- [ ] 提供 `GetAuthenticatedClientAsync()` 方法
|
||
|
||
### G2.3 OwlAdapter 核心实现
|
||
- [ ] 实现 `IGatewayAdapter` — AdapterCode="Owl:main"
|
||
- [ ] 实现 `IHasFlatDevices` — `GetDevicesAsync` 分页 + `GetAllDevicesAsync` 全量
|
||
- [ ] 实现通道管理 — `GetChannelsAsync` + `GetAllChannelsAsync`
|
||
- [ ] 设备映射 — `OwlDevice → StandardDevice`, `OwlChannel → StandardDevice`
|
||
|
||
### G2.4 OwlAdapter 视频流实现
|
||
- [ ] 实现 `IHasStreams.GetLiveUrlAsync` — POST /channels/:id/play → StreamUrls
|
||
- [ ] 实现 `IHasStreams.GetPlaybackUrlAsync` — 构建 HLS VOD URL
|
||
- [ ] 实现 `IHasStreams.PtzControlAsync` — continuous + stop（仅方向键）
|
||
- [ ] 实现 `IHasStreams.GetSnapshotAsync` — POST /channels/:id/snapshot
|
||
|
||
### G2.5 OwlAdapter 录像与 Metadata
|
||
- [ ] 实现 `IHasRecordings.GetRecordingsAsync` — GET /recordings
|
||
- [ ] 实现 `IAcceptsMetadataPush.PushMetadataAsync` — PUT /devices/:id
|
||
|
||
### G2.6 HealthCheck
|
||
- [ ] 实现 `HealthCheckAsync` — 调 /health 端点
|
||
- [ ] Owl 认证失败 → HealthCheck = false
|
||
|
||
### G2.7 构建验证
|
||
- [ ] 确认 `dotnet build` 0 错误
|
||
- [ ] 确认 `POST /register` 返回 OwlAdapter 在适配器列表中
|
||
|
||
> **G2 提交点**: `PhaseG2_owl_adapter — OwlAdapter 编译通过，3 个接口实现完整（FlatDevices+Streams+Recordings+MetadataPush）`
|
||
|
||
---
|
||
|
||
## Phase G3: MC4Adapter（预计 1 天）
|
||
|
||
### G3.1 项目创建
|
||
- [ ] 创建 `src/IntegrationGateway.Adapters.MC4/` 类库项目（net8.0）
|
||
- [ ] 引用 Core 项目
|
||
- [ ] Host 引用 Adapters.MC4
|
||
- [ ] 加入解决方案
|
||
|
||
### G3.2 Mc4AuthHelper
|
||
- [ ] 实现 POST /api/central/auth/conf/get → Token 缓存（8 小时）
|
||
- [ ] 提供 `GetAuthenticatedClientAsync()` 方法（header["token"]）
|
||
|
||
### G3.3 MC4Adapter 对象树
|
||
- [ ] 实现 `IGatewayAdapter` — AdapterCode="MC4:31ku"
|
||
- [ ] 实现 `IHasOwnDeviceTree.GetObjectTreeAsync` — POST /api/central/object/tree → DeviceTreeNode[]
|
||
- [ ] MC4 节点映射：`Mc4TreeNode → DeviceTreeNode`（Type=1区域/2设备）
|
||
|
||
### G3.4 MC4Adapter 实时数据
|
||
- [ ] 实现 `IHasPoints.GetRealtimeValuesAsync` — POST /api/central/device/point/value/get → PointValue[]
|
||
- [ ] 实现 `IHasPoints.GetMultiPointValuesAsync` — POST /api/central/point/multi/value/get
|
||
- [ ] 实现 `IHasPoints.SetPointValueAsync` — POST /api/central/point/value/set
|
||
|
||
### G3.5 MC4Adapter 告警
|
||
- [ ] 实现 `IHasAlarms.GetAlarmsAsync` — POST /api/central/alarm/query（skip/limit 转 page/size）
|
||
- [ ] 实现 `IHasAlarms.ConfirmAlarmAsync` — POST /api/central/alarm/confirm
|
||
- [ ] 实现 `IHasAlarms.EndAlarmAsync` — POST /api/central/alarm/end
|
||
- [ ] 告警去重：`SourceAlarmId` 唯一
|
||
|
||
### G3.6 限流与验证
|
||
- [ ] RateLimiter = new RateLimiter(2)（MC4.0 QPS 限制）
|
||
- [ ] 确认 `dotnet build` 0 错误
|
||
|
||
> **G3 提交点**: `PhaseG3_mc4_adapter — MC4Adapter 编译通过，3 个接口实现完整（OwnDeviceTree+Points+Alarms）`
|
||
|
||
---
|
||
|
||
## Phase G4: 联调验证（需子系统就绪，预计 1 天）
|
||
|
||
### G4.1 Owl 联调
|
||
- [ ] 启动 Owl+ZLM → 网关 RSA 登录成功
|
||
- [ ] `GET /api/gateway/devices?adapter=Owl:main` → 返回设备列表
|
||
- [ ] `GET /api/gateway/streams/Owl:main/{channelId}/live` → 返回 WS-FLV 地址
|
||
- [ ] `POST /api/gateway/streams/Owl:main/{channelId}/ptz` → 云台响应
|
||
|
||
### G4.2 MC4.0 联调
|
||
- [ ] `GET /api/gateway/tree?adapter=MC4:31ku` → 返回对象树 JSON
|
||
- [ ] `GET /api/gateway/realtime/MC4:31ku/{deviceId}` → 返回点位值
|
||
- [ ] `GET /api/gateway/alarms/MC4:31ku` → 返回告警列表
|
||
|
||
### G4.3 故障隔离验证
|
||
- [ ] 停止 MC4.0 → `GET /health` 中 Owl=OK, MC4=FAIL
|
||
- [ ] Owl 设备查询仍正常返回
|
||
|
||
> **G4 提交点**: `PhaseG4_integration — 联调通过，健康检查报告真实状态`
|
||
|
||
---
|
||
|
||
## Phase G5: 部署与文档（预计 0.5 天）
|
||
|
||
### G5.1 发布
|
||
- [ ] `dotnet publish` Release 模式
|
||
- [ ] Dockerfile 编写与构建
|
||
|
||
### G5.2 运维文档
|
||
- [ ] 启动脚本（单机/Docker）
|
||
- [ ] 配置说明（环境变量覆盖）
|
||
- [ ] 健康检查命令
|
||
|
||
> **G5 提交点**: `PhaseG5_deploy — 可发布的网关二进制 + 运维文档`
|
||
|
||
---
|
||
|
||
> **总周期**: G0-G5 预计 4 个工作日（不含联调等待时间）
|