# 网关 Owl 模块整改方案 v1.0

> **版本**: 1.0
> **日期**: 2026-06-03
> **基准**: `doc/设计文档/网关owl模块检查报告20260603.md`
> **架构原则**: 遵循网关设计原则 §3.2-3.4（显式、异步、统一分页、弹性 Extra、不修改已有接口签名）

---

## 1. 整改总览

| 阶段 | 优先级 | 内容 | 涉及文件 | 预计 |
|:---:|:---:|------|------|:---:|
| O1 | P0 | 设备通道展开 + OwlDevice 模型补全 | OwlAdapter.cs + OwlModels.cs | 2h |
| O2 | P0 | AI 事件接入 IHasAlarms | OwlAdapter.cs + OwlModels.cs | 2h |
| O3 | P1 | 回放取流修正 + PTZ 预设位 | OwlAdapter.cs | 1h |
| O4 | P2 | AI 检测启停(IAcceptsControl) | OwlAdapter.cs | 1h |
| O5 | P2 | 推流/拉流管理（可选独立路由） | Program.cs + OwlAdapter | 1.5h |
| O6 | 验证 | 全量编译 + 联调 | — | 1h |
| **合计** | — | — | **5 文件** | **~8.5h** |

---

## 2. 阶段 O1: 设备通道展开 + 模型补全（预计 2h）

### 2.1 现状与问题

```csharp
// 当前: GET /devices → 只返回NVR父设备
public async Task<PagedResult<StandardDevice>> GetDevicesAsync(...)
{
    var json = await client.GetStringAsync($"/devices?page={page}&size={size}");
    // MapDevice: IsParent=true, Category="硬盘录像机" — 无通道子设备
}
```

**后果**: Vol.Pro 设备列表只有 NVR，前端"预览"按钮找不到摄像头通道。

### 2.2 整改设计

**改用** `GET /devices/channels` — Owl 的联合接口直接返回设备+通道的扁平列表：

```json
{
  "items": [
    { "id": "mp123", "type": "DEVICE", "name": "NVR-01", "is_online": "1", "channel_count": 4, ... },
    { "id": "mp123/34020000001320000001", "type": "CHANNEL", "did": "mp123", "name": "仓库入口", "is_online": true, "ptztype": 1, ... },
    { "id": "mp123/34020000001320000002", "type": "CHANNEL", "did": "mp123", "name": "仓库后门", "is_online": true, "ptztype": 0, ... }
  ],
  "total": 3
}
```

**映射逻辑**（单次请求完成父子映射）：

```csharp
// OwlDeviceChannel 联合模型
public class OwlDeviceChannel
{
    public string? Id { get; set; }
    public string? Type { get; set; }         // "DEVICE" | "CHANNEL"
    public string? Did { get; set; }          // 通道所属设备ID
    public string? Name { get; set; }
    public string? IsOnline { get; set; }     // DEVICE: "1"/"0", CHANNEL: true/false
    public string? Manufacturer { get; set; }
    public string? Model { get; set; }
    public string? Firmware { get; set; }
    public string? Longitude { get; set; }
    public string? Latitude { get; set; }
    public int? ChannelCount { get; set; }
    public int? Ptztype { get; set; }         // CHANNEL: 0=无云台, 1=方向, 2=预置位
    public string? App { get; set; }          // CHANNEL: 流应用名
    public string? StreamId { get; set; }     // CHANNEL: 流ID
    // ... 其他字段
}
```

**GetDevicesAsync 重写**：

```csharp
public async Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword = null)
{
    await _limiter.WaitAsync();
    var client = await _auth.GetAuthenticatedClientAsync();
    var url = $"/devices/channels?page={page}&size=1000";  // 大pageSize一次性获取
    if (!string.IsNullOrEmpty(keyword)) url += $"&key={Uri.EscapeDataString(keyword)}";
    var json = await client.GetStringAsync(url);
    var result = JsonSerializer.Deserialize<OwlPagedResult<OwlDeviceChannel>>(json)!;

    var devices = new List<StandardDevice>();

    // 第一遍: 映射 DEVICE 为父设备
    var deviceItems = result.Items.Where(x => x.Type == "DEVICE").ToList();
    var channelItems = result.Items.Where(x => x.Type == "CHANNEL").ToList();

    foreach (var d in deviceItems)
    {
        // 收集该设备的通道
        var childChannels = channelItems.Where(c => c.Did == d.Id).ToList();

        devices.Add(new StandardDevice
        {
            SourceId = d.Id ?? "",
            Name = d.Name ?? d.Id ?? "",
            Category = "硬盘录像机",
            Group = "视频设备",
            IsOnline = d.IsOnline == "1",
            IsParent = true,
            IpAddress = d.Address,
            Extra = new Dictionary<string, object?>
            {
                ["manufacturer"] = d.Manufacturer,
                ["model"] = d.Model,
                ["firmware"] = d.Firmware,
                ["longitude"] = d.Longitude,
                ["latitude"] = d.Latitude,
                ["channelCount"] = d.ChannelCount ?? childChannels.Count
            }
        });

        // 映射通道为子设备
        foreach (var ch in childChannels)
        {
            devices.Add(new StandardDevice
            {
                SourceId = ch.Id ?? "",
                Name = ch.Name ?? $"通道{ch.Id}",
                Category = "摄像机",
                Group = "视频设备",
                IsOnline = ch.IsOnline?.ToLower() == "true" || ch.IsOnline == "1",
                IsParent = false,
                ParentSourceId = d.Id,
                Extra = new Dictionary<string, object?>
                {
                    ["hasPtz"] = (ch.Ptztype ?? 0) > 0 ? "1" : "0",
                    ["app"] = ch.App,
                    ["streamId"] = ch.StreamId
                }
            });
        }
    }

    return new PagedResult<StandardDevice> { Items = devices, Total = devices.Count };
}
```

### 2.3 影响分析

| 影响点 | 说明 |
|------|------|
| 前端预览按钮 | 现在能找到 `DeviceGroup=视频设备, IsParent=否` 的通道子设备，预览按钮可用 |
| 设备树同步 | A3 同步时有父子关系，`ParentSourceId` 解析为父设备 DeviceId |
| 视频墙 | 摄像机通道列表包含 `hasPtz` 标识，云台面板按需显示 |
| MC4/IoT | 零影响 — 不同适配器独立运行 |

---

## 3. 阶段 O2: AI 事件接入 IHasAlarms（预计 2h）

### 3.1 现状态

`OwlAdapter` **没有**实现 `IHasAlarms`，AI 事件走不到 Vol.Pro。

### 3.2 整改设计

**OwlAdapter 增加 IHasAlarms 实现**：

```csharp
public class OwlAdapter : IHasFlatDevices, IHasStreams, IHasRecordings, IAcceptsMetadataPush, IHasAlarms
{
    // Capabilities 增加 HasAlarms = true

    /// <summary>GET /events → StandardAlarm[]</summary>
    public async Task<PagedResult<StandardAlarm>> GetAlarmsAsync(
        int page, int size, DateTime from, DateTime to, string? level = null, string? state = null)
    {
        await _limiter.WaitAsync();
        var client = await _auth.GetAuthenticatedClientAsync();
        var fromMs = new DateTimeOffset(from).ToUnixTimeMilliseconds();
        var toMs = new DateTimeOffset(to).ToUnixTimeMilliseconds();
        var url = $"/events?page={page}&size={size}&start_ms={fromMs}&end_ms={toMs}";
        var json = await client.GetStringAsync(url);
        var result = JsonSerializer.Deserialize<OwlPagedResult<OwlAiEvent>>(json)!;

        return new PagedResult<StandardAlarm>
        {
            Items = result.Items.Select(MapEventToAlarm).ToList(),
            Total = result.Total
        };
    }

    private StandardAlarm MapEventToAlarm(OwlAiEvent e) => new()
    {
        AlarmId = $"owl-ai-{e.Id}",
        AdapterCode = AdapterCode,
        Level = e.Label switch {
            "person" => "重要",
            "car" => "重要", 
            _ => "普通"
        },
        Title = $"AI检测: {e.Label} (置信度 {e.Score:P0})",
        Content = $"通道{e.Cid}: {e.Zones ?? ""}",
        OccurTime = DateTimeOffset.FromUnixTimeMilliseconds(e.StartedAt ?? 0).DateTime,
        Status = e.EndedAt > 0 ? "已结束" : "未确认",
        Extra = new Dictionary<string, object?>
        {
            ["imagePath"] = e.ImagePath,
            ["score"] = e.Score,
            ["label"] = e.Label,
            ["model"] = e.Model
        }
    };

    public async Task ConfirmAlarmAsync(string alarmId) { /* AI事件不支持确认 */ }
    public async Task EndAlarmAsync(string alarmId) { /* AI事件不支持结束 */ }
}
```

### 3.3 事件快照图片

网关注册一条 B-路由直接代理图片访问：

```csharp
// 在 OwlAdapter 中增加
public async Task<byte[]> GetEventImageAsync(string imagePath)
{
    var client = await _auth.GetAuthenticatedClientAsync();
    return await client.GetByteArrayAsync($"/events/image/{imagePath}");
}

// Program.cs 加路由
app.MapGet("/api/gateway/owl/image/{*path}", async (string path, AdapterRegistry registry) =>
{
    var owl = registry.FindByCode<OwlAdapter>("Owl:main");
    if (owl == null) return Results.NotFound();
    var bytes = await owl.GetEventImageAsync(path);
    return Results.File(bytes, "image/jpeg");
});
```

### 3.4 后端 DTO 补充

```csharp
/// <summary>Owl AI 事件</summary>
public class OwlAiEvent
{
    public long? Id { get; set; }
    public string? Did { get; set; }          // 设备ID
    public string? Cid { get; set; }          // 通道ID
    public long? StartedAt { get; set; }      // 毫秒时间戳
    public long? EndedAt { get; set; }
    public string? Label { get; set; }        // person / car / ...
    public float? Score { get; set; }         // 0.0-1.0
    public string? Zones { get; set; }        // 检测区域JSON
    public string? ImagePath { get; set; }
    public string? Model { get; set; }
}
```

---

## 4. 阶段 O3: 回放修正 + PTZ 扩展（预计 1h）

### 4.1 GetPlaybackUrlAsync 修正

当前手工拼 URL，改为调用 Owl API：

GoWVP 文档中播放接口 POST /channels/{id}/play 返回的 `PlayOutput.Items[]` 包含 `Hls` 字段。录像回放无需额外接口——同一个 HLS 地址加上 `start_ms`/`end_ms` 参数即可。

**方案**: 保持当前实现（手工拼 URL 是 Owl 的约定用法），增加 URL 不存在时的 fallback：

```csharp
public async Task<StreamUrls> GetPlaybackUrlAsync(string channelId, DateTime start, DateTime end)
{
    await _limiter.WaitAsync();
    var client = await _auth.GetAuthenticatedClientAsync();
    var token = await _auth.GetTokenAsync();
    var startMs = new DateTimeOffset(start).ToUnixTimeMilliseconds();
    var endMs = new DateTimeOffset(end).ToUnixTimeMilliseconds();
    var baseAddr = client.BaseAddress?.ToString().TrimEnd('/') ?? "";
    return new StreamUrls
    {
        Hls = $"{baseAddr}/recordings/channels/{channelId}/index.m3u8?start_ms={startMs}&end_ms={endMs}&token={token}"
    };
}
```

变化：`client.BaseAddress` → 实际 Owl 地址（之前隐式依赖 `HttpClient.BaseAddress` 已包含）。

### 4.2 PTZ 预设位/巡航

`PtzControlAsync` 增加 action 参数透传：

```csharp
public async Task PtzPresetAsync(string channelId, int presetIndex)
{
    await _limiter.WaitAsync();
    var client = await _auth.GetAuthenticatedClientAsync();
    await client.PostAsJsonAsync($"/channels/{channelId}/ptz/control",
        new { action = "preset", preset = presetIndex });
}
```

无需修改 `IHasStreams` 接口——PTZ 扩展通过 `PtzControlAsync(direction: "preset_1")` 或新增公开方法由 B-路由直接调用。

---

## 5. 阶段 O4: AI 检测启停（预计 1h）

### 5.1 通过 IAcceptsControl 暴露

`OwlAdapter` 实现 `IAcceptsControl`（已在 KMS 适配器中新增的接口）：

```csharp
public class OwlAdapter : ..., IAcceptsControl
{
    public async Task<ControlResult> SendControlAsync(string sourceDeviceId, string command, Dictionary<string, object?> parameters)
    {
        await _limiter.WaitAsync();
        var client = await _auth.GetAuthenticatedClientAsync();
        try
        {
            switch (command)
            {
                case "ai-enable":
                    await client.PostAsync($"/channels/{sourceDeviceId}/ai/enable", null);
                    break;
                case "ai-disable":
                    await client.PostAsync($"/channels/{sourceDeviceId}/ai/disable", null);
                    break;
                case "zone-add":
                    await client.PostAsJsonAsync($"/channels/{sourceDeviceId}/zones", parameters!);
                    break;
                default:
                    return new ControlResult { Success = false, Message = $"不支持的指令: {command}" };
            }
            return new ControlResult { Success = true };
        }
        catch (Exception ex) { return new ControlResult { Success = false, Message = ex.Message }; }
    }
}
```

前端调用：`POST /api/gateway/control/Owl:main { deviceId: "ch123", command: "ai-enable" }`

---

## 6. 阶段 O5: 推流/拉流管理（可选项，预计 1.5h）

### 6.1 设计决策

推流/拉流管理属于**管理员操作**而非实时数据查询。建议通过 B-组新路由暴露，不新增 Core 接口：

```csharp
// Program.cs — 推流/拉流 CRUD 路由组
app.MapGet("/api/gateway/owl/stream-pushs", async (int page, int size, AdapterRegistry registry) => { ... });
app.MapPost("/api/gateway/owl/stream-pushs", async (StreamPushRequest req, ...) => { ... });
// ... 类推
```

### 6.2 推流请求模型

```csharp
public class StreamPushRequest
{
    public string Name { get; set; } = "";
    public string App { get; set; } = "live";
    public string Stream { get; set; } = "";
    public bool? IsAuthEnabled { get; set; }
}

public class StreamProxyRequest
{
    public string Name { get; set; } = "";
    public string Type { get; set; } = "RTSP";
    public string App { get; set; } = "live";
    public string Stream { get; set; } = "";
    public string? SourceUrl { get; set; }
    public int? Transport { get; set; }
}
```

### 6.3 作用

管理端通过网关统一管理 Owl 视频源添加/删除/状态查询，无需单独登录 Owl 控制台。前端可加"添加摄像头"按钮调用这些路由。

---

## 7. 文件变更清单

| 文件 | 新增 | 修改 | 说明 |
|------|:---:|:---:|------|
| `OwlAdapter.cs` | — | ✅ | GetDevicesAsync 重写 + IHasAlarms 实现 + IAcceptsControl 实现 + PTZ 预设位 |
| `OwlModels.cs` (新建) | ✅ | — | OwlDeviceChannel + OwlAiEvent + DTO 完整化（从 OwlAdapter.cs 分离） |
| `OwlAuthHelper.cs` | — | ✅ | HealthCheck 端点改 /stats（需确认） |
| `Program.cs` | ✅ | ✅ | AI 事件图片代理路由 + 推流/拉流路由（O5） |
| `IAcceptsControl.cs` | — | — | 已存在（KMS 阶段新增） |

---

## 8. 与现有架构的兼容性

| 架构元素 | 影响 |
|------|------|
| IHasFlatDevices 签名 | 不变 — GetDevicesAsync 签名不变，仅内部实现改为调 /devices/channels |
| IHasAlarms | OwlAdapter 新增实现，零冲突 — KMS 也实现了 IHasAlarms |
| IAcceptsControl | OwlAdapter 新增实现 — KMS 已有实现，B10 路由自动发现 |
| AdapterCapabilities | 扩展 HasAlarms=true, FeatureFlags["aiEnable"]=true |
| Vol.Pro A3 同步 | ParentSourceId 已有解析逻辑，新通道子设备自然被正确处理 |
| 前端 base_device.vue | 无改动 — 操作列按钮按 DeviceGroup="视频设备" 自动匹配新展开的通道 |

---

## 9. 验证点

| 场景 | 预期 |
|------|------|
| GET /api/gateway/devices?adapter=Owl:main | 返回 NVR 父设备 + 通道子设备，子设备有 hasPtz Extra |
| Vol.Pro 设备列表 | 显示 Owl 摄像机通道，AdapterCode=Owl:main |
| 前端预览按钮 | 通道子设备显示"预览"按钮，点击播放实时流 |
| GET /api/gateway/alarms/Owl:main | 返回 AI 检测事件（人员/车辆等） |
| 规则引擎 | 可将 Owl AI 事件作为告警源触发规则 |
| POST /api/gateway/control/Owl:main ai-enable | 远程开启 Owl AI 检测 |