namespace SHH.CameraSdk;

/// <summary>
/// 帧处理任务模型
/// 功能：封装单帧数据的处理任务信息，包含帧数据、分发决策、全链路追踪上下文，是帧处理管道的核心数据载体
/// 用途：在全局处理中心与分发器之间传递，串联帧的二次处理、分发与追踪流程
/// </summary>
public class ProcessingTask
{
    #region --- 任务核心标识 (Task Core Identification) ---

    /// <summary> 设备唯一标识（关联产生该帧的相机设备ID） </summary>
    public long DeviceId { get; set; }

    #endregion

    #region --- 帧核心数据 (Frame Core Data) ---

    /// <summary> 待处理的智能帧数据（包含原始图像数据与引用计数管理） </summary>
    /// <remarks> 非空约束：任务必须关联有效帧数据，不可为 null </remarks>
    public SmartFrame Frame { get; set; } = null!;

    #endregion

    #region --- 帧分发决策 (Frame Distribution Decision) ---

    /// <summary> 帧处理决策信息（包含是否保留帧、分发目标AppId列表等） </summary>
    /// <remarks> 非空约束：任务必须携带决策信息，指导后续分发逻辑 </remarks>
    public FrameDecision Decision { get; set; } = null!;

    #endregion

    #region --- 全链路追踪上下文 (Full-Link Tracing Context) ---

    /// <summary> 帧全链路追踪上下文（用于记录帧处理过程中的日志、耗时、状态等信息） </summary>
    /// <remarks> 非空约束：支持通过 AddLog 方法补充追踪日志，支撑问题排查 </remarks>
    public FrameContext Context { get; set; } = null!;

    #endregion
}