# IntegrationGateway 对接网关详细设计文档

> **版本**: 1.0  
> **日期**: 2025-05-17  
> **基准**: SecMPS 整合方案 v3.0  
> **作者**: 架构组  

---

## 1. 概述

IntegrationGateway 是 SecMPS 整合方案 v3.0 的核心组件，定位为 Vol.Pro 管理端与各物联子系统之间的**协议适配中间层**。网关对外提供统一 REST API，对内通过适配器模式对接异构子系统，实现"适配一次，多处复用"。

### 1.1 设计目标

| 目标 | 度量 |
|------|------|
| 适配器热插拔 | 新增子系统不改网关核心，仅加 Adapter 项目 |
| 故障隔离 | 任一适配器故障不影响其他适配器和网关注册 |
| 无状态部署 | 网关不存数据库，配置仅 NodeCode/Token/VolProUrl |
| 编译独立性 | `dotnet build` 0 错误，不依赖 Vol.Pro 运行时 |

### 1.2 技术栈

| 层面 | 选型 |
|------|------|
| 运行时 | .NET 8 |
| Web 框架 | ASP.NET Core Minimal API |
| HTTP 客户端 | IHttpClientFactory + SocketsHttpHandler |
| 序列化 | System.Text.Json |
| 容器化 | Docker (可选) |

---

## 2. 项目结构

```
gateway/
├── IntegrationGateway.sln
└── src/
    ├── IntegrationGateway.Core/           # 核心抽象（被所有项目引用）
    │   ├── Abstractions/                  # 7 个能力接口
    │   │   ├── IHasOwnDeviceTree.cs
    │   │   ├── IHasFlatDevices.cs
    │   │   ├── IHasPoints.cs
    │   │   ├── IHasStreams.cs
    │   │   ├── IHasAlarms.cs
    │   │   ├── IHasRecordings.cs
    │   │   └── IAcceptsMetadataPush.cs
    │   ├── Models/                        # 统一模型
    │   │   ├── StandardDevice.cs
    │   │   ├── StandardAlarm.cs
    │   │   ├── StandardRecording.cs
    │   │   ├── DeviceTreeNode.cs
    │   │   ├── PointValue.cs
    │   │   ├── StreamUrls.cs
    │   │   ├── PagedResult.cs
    │   │   ├── AdapterCapabilities.cs
    │   │   └── MetadataChangeSet.cs
    │   └── Infrastructure/               # 基础设施
    │       ├── AdapterRegistry.cs         # 适配器注册中心
    │       ├── RateLimiter.cs             # 令牌桶限流器
    │       └── GatewayClientFactory.cs    # HTTP 客户端工厂
    │
    ├── IntegrationGateway.Adapters.Owl/   # Owl 适配器
    │   ├── OwlAdapter.cs                  # 实现 IHasFlatDevices + IHasStreams
    │   └── OwlAuthHelper.cs              # RSA 加密登录
    │
    ├── IntegrationGateway.Adapters.MC4/   # MC4.0 适配器
    │   ├── Mc4Adapter.cs                  # 实现 IHasOwnDeviceTree + IHasPoints + IHasAlarms
    │   └── Mc4AuthHelper.cs              # Token 认证
    │
    └── IntegrationGateway.Host/          # 宿主（启动项目）
        ├── Program.cs                     # 路由注册 + 适配器初始化
        └── appsettings.json               # 适配器连接配置
```

### 2.1 依赖关系

```
Host → Adapters.Owl → Core
Host → Adapters.MC4 → Core
Host → Core
```

适配器项目不互相引用，Core 项目零外部依赖（仅 Microsoft.Extensions.*）。

---

## 3. 核心接口体系

### 3.1 接口总览

```csharp
namespace IntegrationGateway.Core.Abstractions
{
    /// <summary>所有适配器必须实现的基础接口</summary>
    public interface IGatewayAdapter
    {
        string AdapterCode { get; }                    // "Owl:main" / "MC4:31ku"
        string DisplayName { get; }                    // 人类可读名称
        AdapterCapabilities Capabilities { get; }      // 能力声明
        Task InitializeAsync();                        // 懒加载初始化
        Task<bool> HealthCheckAsync();                 // 健康检查
    }

    /// <summary>扁平设备列表（Owl/门禁/道闸）</summary>
    public interface IHasFlatDevices : IGatewayAdapter
    {
        Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword);
    }

    /// <summary>自有对象树（MC4.0）</summary>
    public interface IHasOwnDeviceTree : IGatewayAdapter
    {
        Task<List<DeviceTreeNode>> GetObjectTreeAsync();
    }

    /// <summary>实时点位值（MC4.0 动环）</summary>
    public interface IHasPoints : IGatewayAdapter
    {
        Task<List<PointValue>> GetRealtimeValuesAsync(string sourceDeviceId);
        Task SetPointValueAsync(string sourceDeviceId, int pointIndex, double value);
    }

    /// <summary>视频流（Owl）</summary>
    public interface IHasStreams : IGatewayAdapter
    {
        Task<StreamUrls> GetLiveUrlAsync(string channelId);
        Task<StreamUrls> GetPlaybackUrlAsync(string channelId, DateTime start, DateTime end);
        Task PtzControlAsync(string channelId, string direction, float speed);
        Task PtzStopAsync(string channelId);
        Task<StreamUrls> GetSnapshotAsync(string channelId);
    }

    /// <summary>告警（MC4.0 + Owl AI可选）</summary>
    public interface IHasAlarms : IGatewayAdapter
    {
        Task<PagedResult<StandardAlarm>> GetAlarmsAsync(
            int page, int size, DateTime from, DateTime to,
            string? level = null, string? state = null);
        Task ConfirmAlarmAsync(string alarmId);
        Task EndAlarmAsync(string alarmId);
    }

    /// <summary>录像回放（Owl）</summary>
    public interface IHasRecordings : IGatewayAdapter
    {
        Task<PagedResult<StandardRecording>> GetRecordingsAsync(
            string channelId, DateTime start, DateTime end, int page, int size);
    }

    /// <summary>元数据回写（Owl 设备改名等）</summary>
    public interface IAcceptsMetadataPush : IGatewayAdapter
    {
        Task<MetadataPushResult> PushMetadataAsync(string sourceDeviceId, MetadataChangeSet changes);
    }
}
```

### 3.2 接口设计原则

- **显式优于隐式**：每个接口明确声明一种能力，适配器按需实现，网关通过 `is` 检查自动发现路由
- **异步优先**：所有方法返回 `Task`/`Task<T>`，避免阻塞线程
- **统一分页**：`PagedResult<T>` 统一 page/size 语义，适配器内部完成 skip/limit 转换
- **弹性 Extra**：`Dictionary<string, object?>` 承载适配器特有属性，不污染核心模型

### 3.3 适配器能力矩阵

```
                  Owl     MC4.0   门禁(未来)
IGatewayAdapter    ✅       ✅       ✅
IHasOwnDeviceTree  -        ✅       -
IHasFlatDevices    ✅       -        ✅
IHasPoints         -        ✅       -
IHasStreams        ✅       -        -
IHasAlarms         ⚠️       ✅       ✅
IHasRecordings     ✅       -        -
IAcceptsMetadata   ✅       -        ⚠️
```

### 3.4 接口扩展规则

新增子系统时：
1. 如果现有接口能覆盖 → 直接实现对应接口，零网关改动
2. 如果现有接口不覆盖 → Core 中新增接口（如 `IHasFaceRecognition`），不能改已有接口签名
3. 新增能力接口后 → Controller 加一个 `if (adapter is INewFeature)` 分支即可

---

## 4. 统一模型设计

### 4.1 StandardDevice

```csharp
public class StandardDevice
{
    public int DeviceId { get; set; }                  // Vol.Pro 侧主键（同步后回填）
    public string AdapterCode { get; set; } = "";      // "Owl:main"
    public string SourceId { get; set; } = "";         // 子系统原始ID (GB28181编码 / MC4 sid)
    public string Name { get; set; } = "";             // 设备名称
    public string Category { get; set; } = "";         // 摄像机/温湿度变送器/...
    public string Group { get; set; } = "";            // 视频设备/IoT设备/...
    public bool IsParent { get; set; }                 // 是否有子设备
    public string? ParentSourceId { get; set; }        // 父设备SourceId（层级关系）
    public bool IsOnline { get; set; }                 // 在线状态
    public string? IpAddress { get; set; }             // IP地址
    public int? Port { get; set; }                     // 端口
    public Dictionary<string, object?>? Extra { get; set; } // 适配器扩展JSON
}
```

### 4.2 字段映射规则（字段分治）

| StandardDevice | base_device | 写入策略 |
|:---|---|:---:|
| Name | DeviceName | 仅首次 |
| Category | DeviceCategory | 仅首次 |
| Group | DeviceGroup | 仅首次 |
| IsOnline | IsOnline | 每次覆盖 |
| IsParent | IsParent | 每次覆盖 |
| ParentSourceId | ParentDeviceId | 每次覆盖（解析映射） |
| IpAddress | IpAddress | 每次覆盖 |
| Port | Port | 每次覆盖 |
| Extra | ExtraData | 每次覆盖 |
| AdapterCode + SourceId | (AdapterCode, SourceId) | 联合唯一键 |

### 4.3 DeviceTreeNode（对象树）

```csharp
public class DeviceTreeNode
{
    public int Id { get; set; }                        // MC4.0 原始ID
    public string SourceId { get; set; } = "";         // 转换为 string 的源ID
    public string Name { get; set; } = "";             // 节点名称
    public int Type { get; set; }                      // 1=区域, 2=设备
    public int ObjectType { get; set; }                // MC4.0 对象类型
    public string? Tag { get; set; }                   // 标签（温湿度/烟雾/门磁...）
    public Dictionary<string, object?>? Option { get; set; } // 扩展属性
    public List<DeviceTreeNode> Children { get; set; } = new();
}
```

### 4.4 PagedResult<T>

```csharp
public class PagedResult<T>
{
    public List<T> Items { get; set; } = new();
    public int Total { get; set; }
    public int Page => 0;  // 由调用方设置
    public int Size => 0;
}
```

### 4.5 其他模型

```
StreamUrls        → { WsFlv, HttpFlv, Hls, WebRtc, Rtmp, Rtsp }
StandardAlarm     → { AlarmId, DeviceId, AdapterCode, Level, Title, Content, OccurTime, Status, ... }
StandardRecording → { Id, ChannelId, StartedAt, EndedAt, Duration, FilePath, Size }
PointValue        → { SourceDeviceId, PointIndex, Value, UpdateTime, Interval }
MetadataChangeSet → { Name?, Category?, Group?, Extra? }
AdapterCapabilities → { HasObjectTree, HasPoints, HasStreams, HasAlarms, HasRecordings, AcceptsControl, AcceptsMetadataPush }
```

---

## 5. 基础设施设计

### 5.1 AdapterRegistry

```csharp
public class AdapterRegistry
{
    private readonly List<IGatewayAdapter> _adapters = new();

    public void Register(IGatewayAdapter adapter) => _adapters.Add(adapter);

    public async Task InitializeAllAsync()
    {
        // 并行初始化，单个失败不影响其他
        await Task.WhenAll(_adapters.Select(a => Task.Run(async () =>
        {
            try { await a.InitializeAsync(); }
            catch (Exception ex) { Log.Error($"Adapter {a.AdapterCode} init failed: {ex.Message}"); }
        })));
    }

    public IReadOnlyList<IGatewayAdapter> All => _adapters.AsReadOnly();

    public T? FindByCode<T>(string adapterCode) where T : class, IGatewayAdapter
        => _adapters.FirstOrDefault(a => a.AdapterCode == adapterCode && a is T) as T;

    public IGatewayAdapter? FindByCode(string adapterCode)
        => _adapters.FirstOrDefault(a => a.AdapterCode == adapterCode);
}
```

**设计要点**：
- 列表存储，O(1) 注册，O(n) 查找（n≤5，可接受）
- 初始化失败不回滚，适配器标记为离线
- 网关启动时通过 `POST /register` 上报 `AdapterTypes` 给 Vol.Pro

### 5.2 RateLimiter（令牌桶）

```csharp
public class RateLimiter
{
    private readonly SemaphoreSlim _semaphore;
    private readonly int _tokensPerSecond;

    public RateLimiter(int tokensPerSecond)
    {
        _tokensPerSecond = tokensPerSecond;
        _semaphore = new SemaphoreSlim(tokensPerSecond, tokensPerSecond);
    }

    public async Task WaitAsync(CancellationToken ct = default)
    {
        await _semaphore.WaitAsync(ct);
        _ = Task.Run(async () =>
        {
            await Task.Delay(1000 / _tokensPerSecond);
            _semaphore.Release();
        });
    }
}
```

**配置策略**：
| 适配器 | QPS 限制 | 原因 |
|--------|:---:|------|
| Owl | 5 | 按文档推荐 |
| MC4.0 | 2 | MC4.0 API 限频 |

### 5.3 HttpClient 工厂

```csharp
// Program.cs 注册
builder.Services.AddHttpClient("VolPro", c =>
{
    c.BaseAddress = new Uri("http://localhost:9100");
    c.DefaultRequestHeaders.Add("Accept", "application/json");
    c.Timeout = TimeSpan.FromSeconds(30);
}).ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(5),
    MaxConnectionsPerServer = 10
});
```

**策略**：
- 命名 HttpClient（`"VolPro"` 用于调 Vol.Pro，适配器内部自行创建 AuthenticatedClient）
- 连接池复用，5 分钟生命周期
- 超时 30 秒，防止第三方 API 慢响应阻塞

---

## 6. 认证与安全

### 6.1 网关注册认证（A1-A4）

```
网关持有: NodeCode + NodeToken（管理端分配）
注册流程:
  1. 网关 → POST /api/gateway/register { nodeCode, token, ... }
  2. Vol.Pro 查询 gateway_nodes WHERE NodeCode = req.NodeCode
     - 存在 → 比对 NodeToken
     - 不存在 → NodeToken 验证通过后 Insert
  3. 认证失败 → 401
  4. 成功后返回 NodeId + 设备列表
```

### 6.2 Owl 认证（RSA 加密）

```
1. GET /login/key → 获取 RSA 公钥 (Base64)
2. 用公钥加密 { username, password } → Base64
3. POST /login { data: <Base64密文> } → 获取 JWT Token
4. Token 有效期: 3 天
5. 后续请求: Authorization: Bearer <token>
```

**安全要点**：
- Token 内存缓存，不落盘
- Token 过期前 1 小时自动刷新（懒刷新策略）
- 认证失败不清除缓存 → 重试 3 次后 `Invalidate()`

### 6.3 MC4.0 认证

```
1. POST /api/central/auth/conf/get → 获取临时 Token
2. Token 有效期: 8 小时（保守估计）
3. 后续请求: header["token"] = <token>
```

### 6.4 网关内部接口（B 组）

B 组接口供管理端或 Vol.Pro 内部调用，认证方式：
- 内网部署：IP 白名单（Simple）
- 外网部署：共享 Secret Key（HMAC 签名），Phase 4 实现

---

## 7. 路由设计

### 7.1 网关主动接口（调 Vol.Pro，不暴露给外部）

网关内部通过 `VolProClient` 调用，不在 Minimal API 中注册路由。

```
POST {VolProBaseUrl}/api/gateway/register      A1
POST {VolProBaseUrl}/api/gateway/heartbeat     A2
POST {VolProBaseUrl}/api/gateway/sync/devices  A3
POST {VolProBaseUrl}/api/gateway/sync/alarms   A4
```

### 7.2 网关暴露接口（B 组，供管理端调用）

```csharp
// Program.cs 路由注册伪代码
app.MapGet("/api/gateway/health", async (AdapterRegistry reg) => {
    var results = await Task.WhenAll(reg.All.Select(async a => new {
        a.AdapterCode, a.DisplayName,
        Healthy = await a.HealthCheckAsync(),
        a.Capabilities
    }));
    return Results.Ok(results);
});

app.MapGet("/api/gateway/devices", async (string adapter, int page, int size, string? keyword, AdapterRegistry reg) => {
    var a = reg.FindByCode<IHasFlatDevices>(adapter);
    if (a == null) return Results.NotFound();
    return Results.Ok(await a.GetDevicesAsync(page, size, keyword));
});

app.MapGet("/api/gateway/tree", async (string adapter, AdapterRegistry reg) => {
    var a = reg.FindByCode<IHasOwnDeviceTree>(adapter);
    if (a == null) return Results.NotFound();
    return Results.Ok(await a.GetObjectTreeAsync());
});

app.MapGet("/api/gateway/streams/{adapter}/{deviceId}/live", async (string adapter, string deviceId, AdapterRegistry reg) => {
    var a = reg.FindByCode<IHasStreams>(adapter);
    if (a == null) return Results.NotFound();
    return Results.Ok(await a.GetLiveUrlAsync(deviceId));
});

app.MapPost("/api/gateway/streams/{adapter}/{deviceId}/ptz", async (string adapter, string deviceId, PtzRequest req, AdapterRegistry reg) => {
    var a = reg.FindByCode<IHasStreams>(adapter);
    if (a == null) return Results.NotFound();
    if (req.Action == "stop") await a.PtzStopAsync(deviceId);
    else await a.PtzControlAsync(deviceId, req.Direction, req.Speed);
    return Results.Ok();
});

app.MapGet("/api/gateway/alarms/{adapter}", async (string adapter, int page, int size, DateTime from, DateTime to, AdapterRegistry reg) => {
    var a = reg.FindByCode<IHasAlarms>(adapter);
    if (a == null) return Results.NotFound();
    return Results.Ok(await a.GetAlarmsAsync(page, size, from, to));
});

app.MapPost("/api/gateway/alarms/{adapter}/{alarmId}/confirm", async (string adapter, string alarmId, AdapterRegistry reg) => {
    var a = reg.FindByCode<IHasAlarms>(adapter);
    if (a == null) return Results.NotFound();
    await a.ConfirmAlarmAsync(alarmId);
    return Results.Ok();
});

// ... 更多 B 组接口
```

### 7.3 路由设计原则

- **适配器参数前置**：所有 B 组接口第一个路径参数都是 `{adapter}`，通过注册中心查找
- **能力检查懒加载**：请求到达时才检查适配器是否实现对应接口
- **404 语义**：适配器不存在或未实现对应能力 → 404（而非 500）
- **统一错误格式**：`{ "error": "ADAPTER_NOT_FOUND", "message": "Adapter 'xxx' not found" }`

---

## 8. 同步流程设计

### 8.1 网关启动同步

```
1. 网关启动 → 加载配置 (NodeCode, Token, VolProBaseUrl)
2. 初始化适配器 (并行: Owl + MC4)
3. POST /api/gateway/register → 获取 NodeId + 已有设备列表
4. 按 AdapterCode 分流已有设备 → 适配器对比差异
5. 各适配器发现子设备 → 构建 StandardDevice[] 列表
6. POST /api/gateway/sync/devices → Vol.Pro Upsert 设备
7. 开启 15s 心跳定时器
```

### 8.2 手动全量同步（B3）

```
管理端 → POST /api/gateway/devices/sync?adapter=MC4:31ku
网关:
  1. 找到 Mc4Adapter
  2. (MC4) GetObjectTree() → 解析区域+设备 → StandardDevice[]
  3. (Owl)  GetDevices() + GetChannels() → StandardDevice[]
  4. POST /api/gateway/sync/devices → Vol.Pro
  5. 返回 { added, updated, removed }
```

### 8.3 MC4.0 同步（FullReplace 模式）

```
MC4.0 对象树遍历:
  type=1 (区域) → 名称匹配 warehouse_regions → 新建或绑区
  type=2 (设备) → Upsert base_device
    - 首次写入: DeviceName/Category/Group/ExtraData 全量
    - 后续同步: 仅更新 IsOnline/ExtraData/ParentDeviceId
  type=2 子节点 → parentSourceId 解析 → ParentDeviceId
```

### 8.4 Owl 同步（Merge 模式）

```
Owl 设备列表遍历:
  GET /devices → NVR 设备 (IsParent=是, DeviceGroup=视频设备)
  GET /channels → 通道 (ParentDeviceId=NVR, IsParent=否)
  通道额外写 video_channel 扩展记录 (OwlStreamApp/OwlStreamName)
```

---

## 9. 错误处理

### 9.1 错误码规范

| HTTP 状态码 | error_code | 场景 |
|:---:|------|------|
| 200 | - | 正常 |
| 400 | `INVALID_PARAMETER` | 参数缺失或格式错误 |
| 401 | `UNAUTHORIZED` | Token 验证失败 |
| 404 | `ADAPTER_NOT_FOUND` | 适配器不存在 |
| 404 | `CAPABILITY_NOT_SUPPORTED` | 适配器未实现该能力 |
| 502 | `UPSTREAM_ERROR` | 第三方 API 返回错误 |
| 503 | `ADAPTER_OFFLINE` | 适配器健康检查失败 |
| 504 | `UPSTREAM_TIMEOUT` | 第三方 API 超时 |
| 500 | `INTERNAL_ERROR` | 网关内部错误 |

### 9.2 适配器日志

```csharp
public void Log(string adapterCode, string operation, string detail, Exception? ex = null)
{
    var level = ex != null ? "ERROR" : "INFO";
    var msg = $"[{DateTime.UtcNow:O}] [{level}] [{adapterCode}] {operation}: {detail}";
    if (ex != null) msg += $"\n{ex}";
    Console.WriteLine(msg);
}
```

---

## 10. 配置管理

### 10.1 appsettings.json 结构

```json
{
  "Logging": {
    "LogLevel": { "Default": "Information" }
  },
  "Owl": {
    "BaseUrl": "http://localhost:15123",
    "Username": "admin",
    "Password": "your_password"
  },
  "MC4": {
    "BaseUrl": "http://localhost:3000"
  },
  "Gateway": {
    "VolProBaseUrl": "http://localhost:9100",
    "NodeCode": "gw-31ku",
    "NodeToken": "xxxxxxxxxx",
    "HeartbeatIntervalSec": 15,
    "AdapterInitTimeoutSec": 30
  }
}
```

### 10.2 环境变量覆盖（Docker 部署）

```bash
GATEWAY__OWL__BASEURL=http://192.168.1.100:15123
GATEWAY__OWL__PASSWORD=prod_password
GATEWAY__GATEWAY__NODETOKEN=prod_token
```

### 10.3 配置验证

启动时验证必填项：
```
Gateway.VolProBaseUrl  ✓
Gateway.NodeCode       ✓ (长度 1-50)
Gateway.NodeToken      ✓ (长度 8-100)
Owl.BaseUrl            ✓ (格式 http(s)://...)
Owl.Username           ✓
Owl.Password           ✓
MC4.BaseUrl            ✓
```

---

## 11. 部署方案

### 11.1 单机部署

```bash
cd gateway
dotnet publish src/IntegrationGateway.Host -c Release -o publish
cd publish
./IntegrationGateway.Host --urls http://0.0.0.0:5100
```

### 11.2 Docker 部署

```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY publish/ .
ENV ASPNETCORE_URLS=http://+:5100
ENTRYPOINT ["dotnet", "IntegrationGateway.Host.dll"]
```

### 11.3 双实例部署

```
实例A: gw-31ku :5100 → MC4.0(31号库) + Owl(仓库视频)
实例B: gw-11ku :5101 → MC4.0(11号库) + 海康ISC(门禁)
```

### 11.4 运维命令

```bash
# 健康检查
curl http://localhost:5100/api/gateway/health

# 手动同步
curl -X POST "http://localhost:5100/api/gateway/devices/sync?adapter=MC4:31ku"

# 查看日志
docker logs -f integration-gateway
```

---

## 12. 性能指标

| 指标 | 目标值 | 说明 |
|------|:---:|------|
| 网关启动时间 | < 5s | 含适配器并行初始化 |
| 设备同步吞吐 | 100 设备/s | 含 HTTP 往返 |
| 实时取流响应 | < 500ms | 从请求到返回流地址 |
| 内存占用 | < 100MB | 空载状态 |
| 并发连接数 | 50 | 同时处理的管理端请求 |

---

## 13. 测试策略

### 13.1 单元测试（Phase 4）

```
IntegrationGateway.Core.Tests/
├── AdapterRegistryTests    # 注册/查找/初始化
├── RateLimiterTests        # 令牌桶行为
└── ModelSerializationTests # JSON 序列化往返
```

### 13.2 集成测试（需子系统 Mock）

```
适配器层 Mock → 验证 Controller 路由分发
Vol.Pro API Mock → 验证网关注册/心跳/同步流程
```

### 13.3 边界测试

| 场景 | 预期行为 |
|------|----------|
| Owl 离线 | HealthCheck → false, 设备 IsOnline 不变 |
| MC4.0 超时 | 返回 504, 不影响 Owl 适配器 |
| 并发取流 | RateLimiter 排队, 不丢请求 |
| 配置错误 | 启动时校验失败, 拒绝启动 |

---

## 14. 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0 | 2025-05-17 | 初版详细设计 |

---

> **下一步**: Phase 0 Day 1 按本设计实施网关项目骨架。