Owl模块检查报告: 40个API覆盖8个(20%) 关键缺失:设备通道展开+AI事件+OwlDevice字段

doc/设计文档/网关owl模块检查报告20260603.md

@@ -0,0 +1,197 @@
+# 网关 Owl 模块检查报告 2026-06-03
+
+> **基准文档**: `doc/对接文档/GoWVP接口文档.md` (3419行, ~40个API)
+> **检查范围**: `gateway/src/IntegrationGateway.Adapters.Owl/` (OwlAdapter.cs, OwlAuthHelper.cs)
+> **日期**: 2026-06-03
+
+---
+
+## 1. 覆盖率概览
+
+GoWVP 接口文档共 **40 个 REST 端点**，当前 OwlAdapter 覆盖了 **8 个**（20%）。
+
+| 模块 | 文档端点数 | 已实现 | 缺失 |
+|------|:---:|:---:|:---:|
+| 控制台 | 1 | 0 | 1 |
+| 推流列表 | 4 | 0 | 4 |
+| 拉流代理 | 4 | 0 | 4 |
+| 国标设备 | 6 | 3 | 3 |
+| 国标通道 | 3 | 3 | 0 |
+| 通道管理 | 4 | 2 | 2 |
+| AI 检测 | 4 | 0 | 4 |
+| 事件 | 5 | 0 | 5 |
+| 区域管理 | 2 | 0 | 2 |
+| 配置管理 | 2 | 0 | 2 |
+| 流媒体 | 2 | 0 | 2 |
+| ONVIF | 3 | 0 | 3 |
+| **合计** | **40** | **8** | **32** |
+
+---
+
+## 2. 已实现接口对照
+
+| GoWVP 端点 | OwlAdapter 方法 | 能力接口 | 状态 |
+|------|------|------|:--:|
+| GET /devices | GetDevicesAsync | IHasFlatDevices | ✅ |
+| PUT /devices/{id} | PushMetadataAsync | IAcceptsMetadataPush | ✅ |
+| POST /channels/{id}/play | GetLiveUrlAsync | IHasStreams | ✅ |
+| POST /channels/{id}/ptz | PtzControlAsync / PtzStopAsync | IHasStreams | ✅ |
+| POST /channels/{id}/snapshot | GetSnapshotAsync | IHasStreams | ✅ |
+| GET /recordings | GetRecordingsAsync | IHasRecordings | ✅ |
+| (未映射) | GetPlaybackUrlAsync | IHasStreams | ⚠️ 自拼URL |
+| GET /health | HealthCheckAsync | IGatewayAdapter | ✅ |
+
+---
+
+## 3. 缺失项详细清单
+
+### 3.1 控制台监控（1个）
+
+| 端点 | 用途 | 影响 |
+|------|------|------|
+| **GET /stats** | CPU/内存/磁盘/网络实时监控 | 管理端无法查看 Owl 服务器健康度 |
+
+**建议**: OwlAdapter 增加 `GetStatsAsync()`，返回 CPU/内存/磁盘 JSON，`Capabilities.HasStats = true`。
+
+### 3.2 推流管理（4个）
+
+| 端点 | 说明 |
+|------|------|
+| POST /stream_pushs | 添加推流通道 |
+| GET /stream_pushs | 分页查询推流列表 |
+| PUT /stream_pushs/{id} | 编辑推流 |
+| DELETE /stream_pushs/{id} | 删除推流 |
+
+**影响**: 管理端无法从 Vol.Pro 直接添加/管理 Owl 推流通道，需登录 Owl 控制台操作。
+
+### 3.3 拉流代理（4个）
+
+| 端点 | 说明 |
+|------|------|
+| POST /stream_proxys | 添加拉流代理 |
+| GET /stream_proxys | 分页查询拉流列表 |
+| PUT /stream_proxys | 编辑拉流代理 |
+| DELETE /stream_proxys/{id} | 删除拉流代理 |
+
+**影响**: 同推流，非 GB28181 的 RTSP/RTMP 通道无法通过管理端管理。
+
+### 3.4 国标设备扩展（3个）
+
+| 端点 | 说明 | 当前替代 |
+|------|------|------|
+| **GET /devices/channels** | 一键获取所有设备+通道列表 | 无 — 当前 GetDevicesAsync 只返回 NVR，不展开通道 |
+| POST /devices | 添加 GB28181 设备 | 无 |
+| POST /devices/{id}/catalog | 查询设备目录 | 无 |
+
+**关键缺失**: `GET /devices/channels` 直接返回设备+通道的联合结果，比单独调 `/devices` + `/channels` 高效。当前适配器在 `GetDevicesAsync` 中只映射了 NVR 设备（IsParent=true），**没有展开下级通道**。
+
+### 3.5 通道管理（2个）
+
+| 端点 | 说明 |
+|------|------|
+| **POST /channels** | 添加 RTMP/RTSP 通道 |
+| **DELETE /channels/{id}** | 删除通道 |
+| GET /channels | 通道列表(独立) |
+
+**半缺失**: `GET /channels` 和 `PUT /channels/{id}` 虽未直接调用，但流和 PTZ 接口已间接使用通道 ID。
+
+### 3.6 AI 检测能力（4个）
+
+| 端点 | 说明 |
+|------|------|
+| POST /channels/{id}/ai/enable | 启用 AI 检测 |
+| POST /channels/{id}/ai/disable | 禁用 AI 检测 |
+| POST /channels/{id}/zones | 添加 AI 检测区域 |
+| GET /channels/{id}/zones | 获取检测区域 |
+
+**影响**: Owl 的 AI 人数统计/区域入侵能力无法通过网关管理端开启/配置。
+
+### 3.7 AI 事件管理（5个）
+
+| 端点 | 说明 |
+|------|------|
+| GET /events | 分页查询 AI 事件（按通道/标签/时间筛选） |
+| GET /events/{id} | 事件详情 |
+| PUT /events/{id} | 更新事件 |
+| DELETE /events/{id} | 删除事件 |
+| GET /events/image/{path} | 获取事件快照图片 |
+
+**战略缺失**: Owl AI 事件（人员检测、车辆检测、入侵告警等）是**视频智能监控的核心数据**。当前网关零接入，意味着：
+- 规则引擎无法以"人数越限"为条件触发动作
+- AI 事件不能同步到 Vol.Pro 告警表
+- 事件快照无法在大屏展示
+
+**建议**: 通过 `IHasAlarms` 接口暴露 AI 事件，映射 `StandardAlarm { AlarmId=event.id, Level=重要/普通, Title=label, Content=快照路径 }`。
+
+### 3.8 系统管理（4个）
+
+| 端点 | 说明 |
+|------|------|
+| GET /configs/info | 查询配置 |
+| PUT /configs/info/sip | 修改 SIP 配置 |
+| GET /media_servers | 流媒体列表 |
+| PUT /media_servers/{id} | 修改流媒体 |
+
+**影响**: 运维类接口，暂不阻塞业务。
+
+### 3.9 ONVIF（3个）
+
+| 端点 | 说明 |
+|------|------|
+| GET /onvif/devices-discover | ONVIF 设备发现 |
+| POST /onvif | 添加 ONVIF 设备 |
+| GET /onvif/discover | ONVIF 设备发现(SSE) |
+
+---
+
+## 4. 现有代码问题项
+
+### 4.1 设备列表只返回 NVR 不展开通道
+
+`GetDevicesAsync` → `MapDevice` 将所有设备映射为 `IsParent=true, Category="硬盘录像机"`，不查询也不返回通道子设备。这导致：
+- Vol.Pro 设备树中 Owl 设备全是父设备，无摄像头子节点
+- 前端预览按钮要求 `DeviceGroup='视频设备'` 的叶子设备，找不到子设备
+
+`GET /devices/channels` 可一次性返回设备+通道，相比两次调用更高效。
+
+### 4.2 OwlDevice 模型字段不完整
+
+当前 `OwlDevice` 只有 8 个字段（Id, Name, IsOnline, Protocol, Address, Port, Transport），GoWVP 返回的 Device 至少有 20+ 个字段，缺失包括：
+
+| 缺失字段 | 说明 | 用途 |
+|------|------|------|
+| Manufacturer | 厂商 | 设备详情显示 |
+| Model | 型号 | 设备详情显示 |
+| Firmware | 固件版本 | 运维 |
+| Longitude/Latitude | 经纬度 | 地图标记 |
+| ChannelCount | 通道数 | 统计 |
+| Status/RegisterWay | 注册方式 | GB28181 状态 |
+| CreatedAt/UpdatedAt | 时间戳 | 同步管理 |
+
+### 4.3 HealthCheck 端点路径可能错误
+
+代码调 `GET /health`，但 GoWVP 文档显示控制台唯一端点 `GET /stats`。需确认 Owl 实际实现。
+
+### 4.4 GetPlaybackUrlAsync 手工拼 URL
+
+直接拼接 `/recordings/channels/{id}/index.m3u8?start_ms=&end_ms=&token=`，未调用 Owl API。虽然功能通常可用，但依赖内部路径约定，Owl 版本升级可能失效。
+
+### 4.5 无 PTZ 预设位/巡航支持
+
+GoWVP PTZ 接口 `POST /channels/{id}/ptz/control` 支持 `action: preset/patrol/scan/stop`，当前仅实现 `continuous` 方向移动和 `stop`。
+
+---
+
+## 5. 优先级建议
+
+| 优先级 | 项目 | 说明 |
+|:---:|------|------|
+| 🔴 P0 | 设备列表展开通道 | 前端无法展示摄像头设备 |
+| 🔴 P0 | AI 事件接入 IHasAlarms | 规则引擎无法获知人数/入侵 |
+| 🟠 P1 | 使用 GET /devices/channels | 替代当前单独调 /devices |
+| 🟠 P1 | OwlDevice 字段补全 | 设备详情展示 |
+| 🟡 P2 | AI 检测启停 | 远程控制 Owl AI |
+| 🟡 P2 | 推流/拉流 CRUD | 管理端统一通道管理 |
+| ⚪ P3 | 预设位/巡航 PTZ | 高级云台功能 |
+| ⚪ P3 | 系统管理接口 | 运维便捷性 |
+| ⚪ P3 | ONVIF 设备发现 | 部署时的设备发现 |