海康摄像头取流示例初始签入

SHH.CameraSdk/Core/Telemetry/CameraHealthReport.cs

@@ -0,0 +1,50 @@
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 相机健康度报告
+/// 功能：封装相机的详细运行健康数据，包含状态、性能、故障统计等信息
+/// 用途：用于运维分析、故障排查、设备健康度评估，提供比遥测快照更细致的健康指标
+/// </summary>
+public class CameraHealthReport
+{
+    #region --- 设备核心标识 (Device Core Identification) ---
+
+    /// <summary> 设备唯一业务标识（对应数据库ID或配置中的设备ID） </summary>
+    public long DeviceId { get; set; }
+
+    /// <summary> 设备IP地址（用于定位具体设备） </summary>
+    public string Ip { get; set; } = string.Empty;
+
+    #endregion
+
+    #region --- 设备运行状态 (Device Operation Status) ---
+
+    /// <summary> 设备当前运行状态（字符串形式，对应 VideoSourceStatus 枚举值，如 "Streaming"/"Faulted"/"Reconnecting"） </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary> 最后一次错误信息（无错误时建议设为空字符串，记录设备最近一次故障原因） </summary>
+    public string LastError { get; set; } = string.Empty;
+
+    #endregion
+
+    #region --- 性能与延迟指标 (Performance & Latency Metrics) ---
+
+    /// <summary> 实时帧率（单位：fps，反映相机实际输出的有效帧率） </summary>
+    /// <remarks> 统计逻辑：需在 RaiseFrameReceived 事件中增加计数器，按时间窗口计算实时值 </remarks>
+    public double RealFps { get; set; }
+
+    /// <summary> 推流延迟（单位：毫秒，记录从相机推流到接收端成功接收的总延迟） </summary>
+    public double LatencyMs { get; set; }
+
+    #endregion
+
+    #region --- 故障与恢复统计 (Fault & Recovery Statistics) ---
+
+    /// <summary> 丢帧计数（因渲染过慢、缓冲区溢出等原因导致的丢弃帧数累计值） </summary>
+    public long DropFrames { get; set; }
+
+    /// <summary> 重连次数（哨兵机制触发的自动重连累计次数，反映设备网络稳定性） </summary>
+    public int ReconnectCount { get; set; }
+
+    #endregion
+}

SHH.CameraSdk/Core/Telemetry/CameraTelemetryInfo.cs

@@ -0,0 +1,56 @@
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 相机实时遥测数据快照
+/// 功能：封装单台相机的实时运行状态、性能指标与健康度信息，用于监控面板展示、运维告警与数据分析
+/// 特性：数据为瞬时快照，通常定期（如1秒/次）更新，反映相机当前运行状况
+/// </summary>
+public class CameraTelemetryInfo
+{
+    #region --- 设备核心标识 (Device Core Identification) ---
+
+    /// <summary> 设备唯一业务标识（对应数据库ID或配置中的设备ID） </summary>
+    public long DeviceId { get; set; }
+
+    /// <summary> 设备显示名称（如“北大门-枪机01”，用于UI展示） </summary>
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary> 设备IP地址（用于网络连通性校验与远程访问） </summary>
+    public string IpAddress { get; set; } = string.Empty;
+
+    #endregion
+
+    #region --- 设备运行状态 (Device Operation Status) ---
+
+    /// <summary> 相机当前运行状态（字符串形式，对应 VideoSourceStatus 枚举值，如 "Playing"/"Faulted"/"Connecting"） </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary> 设备物理连接状态（通过 Ping/TCP 探测判定，true=在线，false=离线） </summary>
+    public bool IsOnline { get; set; }
+
+    /// <summary> 最后一次报错信息（无错误时为 null，用于快速定位故障原因） </summary>
+    public string? LastErrorMessage { get; set; }
+
+    #endregion
+
+    #region --- 性能指标 (Performance Metrics) ---
+
+    /// <summary> 实时帧率（单位：fps，反映相机取流与处理的实时速度） </summary>
+    public double Fps { get; set; }
+
+    /// <summary> 累计接收帧数（相机启动后接收的总帧数，用于统计数据完整性） </summary>
+    public long TotalFrames { get; set; }
+
+    #endregion
+
+    #region --- 健康度与统计 (Health & Statistics) ---
+
+    /// <summary> 设备健康度评分（0-100分，分数越高健康状态越好） </summary>
+    /// <remarks> 计算逻辑：结合是否断线、实时FPS是否在正常范围、是否有报错等因素综合判定 </remarks>
+    public int HealthScore { get; set; }
+
+    /// <summary> 遥测数据统计时间戳（记录当前快照的生成时间，默认当前时间） </summary>
+    public DateTime Timestamp { get; set; } = DateTime.Now;
+
+    #endregion
+}

SHH.CameraSdk/Core/Telemetry/FrameConsumerType.cs

@@ -0,0 +1,21 @@
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 帧消费者类型枚举
+/// 功能：定义帧数据的消费场景/模块标识，用于帧分发路由、权限控制与遥测统计
+/// 用途：配合全局流分发器（GlobalStreamDispatcher），实现帧数据的精准定向分发
+/// </summary>
+public enum FrameConsumerType
+{
+    /// <summary> UI 预览消费：用于前端界面实时显示（如 WPF/WinForm 控件、Web 页面渲染） </summary>
+    UI_Preview,
+
+    /// <summary> AI 分析消费：用于 AI 算法处理（如行为识别、人脸检测、车牌识别等耗时分析场景） </summary>
+    AI_Analysis,
+
+    /// <summary> 网络流消费：用于网络推流（如 RTSP/RTMP 推流、WebSocket 实时推送等） </summary>
+    Network_Stream,
+
+    /// <summary> 一次性截图消费：用于单次截图操作（如用户手动抓拍、定时快照等临时消费场景） </summary>
+    Snapshot_OneOff
+}

SHH.CameraSdk/Core/Telemetry/FrameContext.cs

@@ -0,0 +1,61 @@
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 帧全链路追踪上下文
+/// 功能：记录单帧数据从产生到结束的完整生命周期信息，包含标识、决策结果、性能指标与日志流水
+/// 用途：用于问题排查、性能分析、帧流转追溯，支撑全链路可观测性
+/// </summary>
+public class FrameContext
+{
+    #region --- 帧核心标识 (Frame Core Identification) ---
+
+    /// <summary> 物理帧序号（全局唯一，关联帧的原始数据标识） </summary>
+    public long FrameSequence { get; set; }
+
+    /// <summary> 帧上下文创建时间戳（默认当前时间，记录帧进入追踪链路的时刻） </summary>
+    public DateTime Timestamp { get; set; } = DateTime.Now;
+
+    #endregion
+
+    #region --- 帧决策结果 (Frame Decision Results) ---
+
+    /// <summary> 帧是否被保留（true=保留并分发，false=被丢弃） </summary>
+    public bool IsCaptured { get; set; }
+
+    /// <summary> 帧丢弃原因（仅 IsCaptured 为 false 时有效，默认空字符串） </summary>
+    /// <remarks>示例值："NoSubscribers"（无订阅者）、"PipelineFull"（处理管道满）、"FpsLimit"（帧率限制）</remarks>
+    public string DropReason { get; set; } = string.Empty;
+
+    /// <summary> 帧分发目标应用ID列表（记录该帧最终分发给的所有订阅者标识，合并结果） </summary>
+    /// <remarks>示例值：["WPF_Display_Main", "AI_Behavior_Engine"]</remarks>
+    public List<string> TargetAppIds { get; set; } = new();
+
+    #endregion
+
+    #region --- 帧性能指标 (Frame Performance Metrics) ---
+
+    /// <summary> 颜色转码耗时（单位：毫秒） </summary>
+    /// <remarks>记录帧数据格式转换（如 YUV→BGR）的耗时，用于性能瓶颈定位</remarks>
+    public double CvtColorCostMs { get; set; }
+
+    /// <summary> 二次处理耗时（单位：毫秒） </summary>
+    /// <remarks>记录帧在处理管道中的额外加工耗时（如打水印、裁剪、AI预处理等）</remarks>
+    public double ProcessCostMs { get; set; }
+
+    /// <summary> 帧总处理耗时（单位：毫秒） </summary>
+    /// <remarks>记录帧从进入追踪链路到处理完成/丢弃的总耗时，为性能优化提供数据支撑</remarks>
+    public double TotalCostMs { get; set; }
+
+    #endregion
+
+    #region --- 帧日志流水 (Frame Logs) ---
+
+    /// <summary> 帧生命周期日志流水（按时间顺序记录关键节点操作） </summary>
+    public List<string> Logs { get; } = new();
+
+    /// <summary> 新增帧日志（自动添加时间戳，格式：[HH:mm:ss.fff] 日志内容） </summary>
+    /// <param name="msg">日志内容（记录帧流转的关键节点，如“驱动提交帧数据”“管道处理完成”）</param>
+    public void AddLog(string msg) => Logs.Add($"[{DateTime.Now:HH:mm:ss.fff}] {msg}");
+
+    #endregion
+}

SHH.CameraSdk/Core/Telemetry/FrameTrace.cs

@@ -0,0 +1,43 @@
+using System.Collections.Generic;
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 帧追踪数据模型
+/// 功能：记录单帧数据的生命周期关键信息，用于帧流转监控、丢帧分析与性能排查
+/// 适用场景：配合全局遥测或调试工具，追溯帧的处理路径、耗时及最终状态
+/// </summary>
+public class FrameTrace
+{
+    #region --- 帧核心标识 (Frame Core Identification) ---
+
+    /// <summary> 帧唯一序列号（全局唯一，用于关联帧的全生命周期） </summary>
+    public long FrameId { get; set; }
+
+    /// <summary> 帧产生时间戳（单位：毫秒，通常为 Environment.TickCount64 或 UTC 时间戳） </summary>
+    public long Timestamp { get; set; }
+
+    #endregion
+
+    #region --- 帧状态信息 (Frame Status Information) ---
+
+    /// <summary> 帧是否被丢弃（true=已丢弃，false=正常处理/分发） </summary>
+    public bool IsDropped { get; set; }
+
+    /// <summary> 帧丢弃原因（仅 IsDropped 为 true 时有效） </summary>
+    /// <remarks>示例值："NoSubscribers"（无订阅者）、"FpsLimit"（帧率限制）、"PipelineFull"（处理管道满）</remarks>
+    public string DropReason { get; set; } = string.Empty;
+
+    /// <summary> 帧最终分发目标列表（记录该帧被发送到的订阅者/模块标识） </summary>
+    /// <remarks>示例值：["WPF_Display_Main", "AI_Behavior_Engine"]</remarks>
+    public List<string> Targets { get; set; } = new();
+
+    #endregion
+
+    #region --- 帧性能指标 (Frame Performance Metrics) ---
+
+    /// <summary> 帧处置总耗时（单位：毫秒） </summary>
+    /// <remarks>计算范围：从帧产生到最终处理完成/丢弃的总时间，用于性能瓶颈分析</remarks>
+    public double ProcessDurationMs { get; set; }
+
+    #endregion
+}

SHH.CameraSdk/Core/Telemetry/GlobalTelemetry.cs

@@ -0,0 +1,66 @@
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 全局遥测仓储（静态类）
+/// 功能：存储并提供帧生命周期的追踪日志查询，采用环形缓冲区机制限制日志数量
+/// 用途：用于问题排查、性能分析，记录每帧的处理流程、耗时、丢弃原因等信息
+/// </summary>
+public static class GlobalTelemetry
+{
+    #region --- 静态存储资源 (Static Storage Resources) ---
+
+    /// <summary>
+    /// 环形日志缓冲区：存储帧追踪上下文（线程安全）
+    /// Key：帧序列号（FrameSequence），Value：帧全链路追踪上下文
+    /// </summary>
+    private static readonly ConcurrentDictionary<long, FrameContext> _logs = new();
+
+    /// <summary>
+    /// 日志序列号队列：用于维护环形缓冲区的淘汰顺序（线程安全）
+    /// 作用：记录帧日志的插入顺序，超过最大数量时淘汰最早的记录
+    /// </summary>
+    private static readonly ConcurrentQueue<long> _keys = new();
+
+    /// <summary>
+    /// 最大日志保留数量：限制环形缓冲区仅保留最近 200 条帧追踪记录
+    /// 目的：防止日志过多导致内存占用飙升
+    /// </summary>
+    private const int MaxLogCount = 200;
+
+    #endregion
+
+    #region --- 核心操作方法 (Core Operation Methods) ---
+
+    /// <summary>
+    /// 记录帧追踪日志
+    /// 功能：将帧上下文存入缓冲区，超过最大数量时自动淘汰最早的记录
+    /// </summary>
+    /// <param name="frameSeq">帧序列号（唯一标识某一帧）</param>
+    /// <param name="context">帧全链路追踪上下文（含处理日志、耗时、丢弃原因等）</param>
+    public static void RecordLog(long frameSeq, FrameContext context)
+    {
+        // 存入日志缓冲区（存在相同序列号时会覆盖，确保最新记录）
+        _logs[frameSeq] = context;
+        // 记录序列号到队列，用于后续淘汰逻辑
+        _keys.Enqueue(frameSeq);
+
+        // 环形缓冲区淘汰逻辑：超过最大数量时，移除最早插入的记录
+        if (_keys.Count > MaxLogCount && _keys.TryDequeue(out var oldKey))
+        {
+            _logs.TryRemove(oldKey, out _);
+        }
+    }
+
+    /// <summary>
+    /// 获取最近的帧追踪日志
+    /// 功能：按时间戳降序返回缓冲区中的所有记录（最新记录在前）
+    /// </summary>
+    /// <returns>帧追踪上下文集合（最多 MaxLogCount 条）</returns>
+    public static IEnumerable<FrameContext> GetRecentLogs()
+    {
+        // 按帧上下文的时间戳降序排序，确保最新记录优先返回
+        return _logs.Values.OrderByDescending(x => x.Timestamp);
+    }
+
+    #endregion
+}