# 网关 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 设备发现 | 部署时的设备发现 |