SecMPS/doc/设计文档/对接网关设计文档_任务清单.md

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 个工作日（不含联调等待时间）