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
}