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
}