Ayay/SHH.CameraSdk/Drivers/BaseVideoSource.cs

namespace SHH.CameraSdk;

/// <summary>
/// [架构基类] 工业级视频源抽象核心 (V3.3.4 严格匹配版)
/// 核心职责：
/// <para>1. 提供线程安全的生命周期管理（启动/停止/销毁）</para>
/// <para>2. 实现状态变更的可靠分发与异常隔离</para>
/// <para>3. 支持配置热更新与动态参数应用</para>
/// <para>4. 内置 FPS/码率统计、心跳保活、审计日志能力</para>
/// 关键修复记录：
/// <para>✅ [Bug A] 死锁免疫：所有 await 均添加 ConfigureAwait(false)，解除 UI 线程依赖</para>
/// <para>✅ [Bug π] 管道安全：Dispose 采用优雅关闭策略，确保剩余状态消息被消费</para>
/// <para>✅ [编译修复] 补全 CloneConfig 中 Transport/VendorArguments 的深拷贝逻辑</para>
/// </summary>
public abstract class BaseVideoSource : IVideoSource, IAsyncDisposable
{
    #region --- 1. 核心配置与锁机制 (Core Config & Locks) ---

    /// <summary>
    /// 核心配置对象（支持热更新，去除 readonly 修饰符）
    /// 注意：外部修改需通过 UpdateConfig 方法，确保线程安全
    /// </summary>
    protected VideoSourceConfig _config;

    /// <summary>
    /// 状态同步锁
    /// 作用：保护 _status 字段的读写原子性，防止多线程竞争导致状态不一致
    /// </summary>
    private readonly object _stateSyncRoot = new();

    /// <summary>
    /// 生命周期互斥锁（信号量）
    /// 作用：确保 StartAsync/StopAsync/UpdateConfig 串行执行，防止重入导致状态机混乱
    /// 配置：初始计数 1，最大计数 1 → 互斥锁
    /// </summary>
    private readonly SemaphoreSlim _lifecycleLock = new(1, 1);

    #endregion

    #region --- 2. 内部状态与基础设施 (Internal States & Infrastructure) ---

    /// <summary> 设备在线状态标志（volatile 确保多线程可见性） </summary>
    private volatile bool _isOnline;

    /// <summary> 视频源核心状态（受 _stateSyncRoot 保护） </summary>
    private VideoSourceStatus _status = VideoSourceStatus.Disconnected;

    /// <summary>
    /// 状态通知有界通道
    /// 特性：DropOldest 策略，消费者过载时丢弃旧状态，防止内存溢出
    /// 配置：容量 100 | 单读者多写者
    /// </summary>
    private readonly Channel<StatusChangedEventArgs> _statusQueue;

    /// <summary> 状态分发器的取消令牌源 </summary>
    private CancellationTokenSource? _distributorCts;

    /// <summary> 状态分发任务引用（用于 Dispose 时优雅等待） </summary>
    private Task? _distributorTask;

    /// <summary> 最后一帧接收的系统 Tick（单调时钟，不受系统时间修改影响） </summary>
    private long _lastFrameTick = 0;

    /// <summary> 视频帧回调事件（热路径，低延迟分发） </summary>
    public event Action<object>? FrameReceived;

    #endregion

    #region --- 3. 公开属性 (Public Properties) ---

    /// <summary> 视频源唯一标识 </summary>
    public long Id => _config.Id;

    /// <summary> 只读配置副本（外部仅能通过 UpdateConfig 修改） </summary>
    public VideoSourceConfig Config => _config;

    /// <summary> 视频源当前状态（线程安全读取） </summary>
    public VideoSourceStatus Status
    {
        get
        {
            lock (_stateSyncRoot)
            {
                return _status;
            }
        }
    }

    /// <summary> 运行状态标记 </summary>
    public bool IsRunning { get; set; }

    /// <summary> 设备在线状态 </summary>
    public bool IsOnline => _isOnline;

    /// <summary> 设备元数据（能力集、通道信息等） </summary>
    public DeviceMetadata Metadata { get; protected set; } = new();

    /// <summary> 状态变更事件（对外暴露状态通知） </summary>
    public event EventHandler<StatusChangedEventArgs>? StatusChanged;

    /// <summary> 最后一帧接收的 Tick 时间戳（线程安全读取） </summary>
    public long LastFrameTick => Interlocked.Read(ref _lastFrameTick);

    #endregion

    #region --- 4. 遥测统计属性 (Telemetry Properties) ---

    /// <summary> 生命周期内接收的总帧数 </summary>
    private long _totalFramesReceived = 0;

    /// <summary> FPS 计算临时计数器 </summary>
    private int _tempFrameCounter = 0;

    /// <summary> 上次 FPS 计算的 Tick 时间 </summary>
    private long _lastFpsCalcTick = 0;

    /// <summary> 实时 FPS（每秒更新一次） </summary>
    public double RealFps { get; private set; } = 0.0;

    /// <summary> 实时码率 (Mbps) </summary>
    protected double _currentBitrate = 0;
    public double RealBitrate => _currentBitrate;

    /// <summary> 码率计算临时字节计数器 </summary>
    private long _tempByteCounter = 0;

    /// <summary> 生命周期总帧数（线程安全读取） </summary>
    public long TotalFrames => Interlocked.Read(ref _totalFramesReceived);

    #endregion

    #region --- 5. 审计日志系统 (Audit Log System) ---

    /// <summary> 审计日志列表（线程安全访问） </summary>
    private readonly List<string> _auditLogs = new();

    /// <summary> 最大日志条数（滚动清除，防止内存溢出） </summary>
    private const int MaxAuditLogCount = 100;

    #endregion

    #region --- 6. 构造函数 (Constructor) ---

    /// <summary>
    /// 初始化视频源基础设施
    /// </summary>
    /// <param name="config">视频源基础配置</param>
    /// <exception cref="ArgumentNullException">配置为空时抛出</exception>
    protected BaseVideoSource(VideoSourceConfig config)
    {
        // 入参校验
        _config = config ?? throw new ArgumentNullException(nameof(config), "视频源配置不能为空");

        // 初始化帧控制器
        Controller = new FrameController();

        // 配置深拷贝（防漂移：内部配置与外部引用隔离）
        _config = CloneConfig(config);

        // 初始化有界状态通道
        _statusQueue = Channel.CreateBounded<StatusChangedEventArgs>(new BoundedChannelOptions(100)
        {
            FullMode = BoundedChannelFullMode.DropOldest,
            SingleReader = true,
            SingleWriter = false
        });

        // 初始化状态分发器
        _distributorCts = new CancellationTokenSource();
        _distributorTask = Task.Run(() => StatusDistributorLoopAsync(_distributorCts.Token));
    }

    #endregion

    #region --- 7. 配置管理 (Config Management) ---

    /// <summary>
    /// 热更新视频源配置（线程安全）
    /// 新配置将在下次启动/重连时生效
    /// </summary>
    /// <param name="newConfig">新的视频源配置</param>
    public void UpdateConfig(VideoSourceConfig newConfig)
    {
        if (newConfig == null) return;

        // 加生命周期锁：防止与启动/停止操作并发
        _lifecycleLock.Wait();
        try
        {
            // 深拷贝新配置，隔离外部引用
            _config = newConfig.DeepCopy();

            // 写入审计日志
            AddAuditLog($"配置已更新 [IP:{_config.IpAddress}]，生效时机：{(_isOnline ? "下次重连" : "下次启动")}");
            Debug.WriteLine($"[ConfigUpdated] 设备 {Id} 配置落地完成");
        }
        finally
        {
            _lifecycleLock.Release();
        }
    }

    /// <summary>
    /// 配置深拷贝辅助方法（确保引用类型独立）
    /// </summary>
    /// <param name="source">源配置</param>
    /// <returns>深拷贝后的新配置</returns>
    private VideoSourceConfig CloneConfig(VideoSourceConfig source)
    {
        return new VideoSourceConfig
        {
            Id = source.Id,
            Brand = source.Brand,
            IpAddress = source.IpAddress,
            Port = source.Port,
            Username = source.Username,
            Password = source.Password,
            ChannelIndex = source.ChannelIndex,
            StreamType = source.StreamType,
            Transport = source.Transport,
            ConnectionTimeoutMs = source.ConnectionTimeoutMs,
            // Dictionary 深拷贝：防止外部修改影响内部
            VendorArguments = source.VendorArguments != null
                ? new Dictionary<string, string>(source.VendorArguments)
                : new Dictionary<string, string>()
        };
    }

    #endregion

    #region --- 8. 生命周期控制 (Lifecycle Control) ---

    /// <summary>
    /// 异步启动设备连接
    /// 包含：状态校验、非托管初始化、元数据刷新
    /// </summary>
    public async Task StartAsync()
    {
        // 死锁免疫：不捕获当前同步上下文
        await _lifecycleLock.WaitAsync().ConfigureAwait(false);
        try
        {
            // 等待上一个生命周期任务完成
            await _pendingLifecycleTask.ConfigureAwait(false);

            // 幂等性检查：已在线则直接返回
            if (_isOnline) return;

            // 更新状态为连接中
            UpdateStatus(VideoSourceStatus.Connecting, $"正在启动 {_config.Brand} 设备...");

            // 驱动层启动逻辑（带 15 秒超时）
            using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(15));
            await OnStartAsync(cts.Token).ConfigureAwait(false);

            // 标记运行状态
            _isOnline = true;
            IsRunning = true;

            // 初始化心跳：给予 2 秒宽限期，防止刚启动被判定为僵死
            Interlocked.Exchange(ref _lastFrameTick, Environment.TickCount64 + 2000);

            // 更新状态为播放中，并刷新元数据
            UpdateStatus(VideoSourceStatus.Playing, "流传输正常运行");
            await RefreshMetadataAsync().ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            // 异常回滚：标记离线并更新状态
            _isOnline = false;
            UpdateStatus(VideoSourceStatus.Disconnected, $"启动失败: {ex.Message}");
            throw; // 向上抛出异常，由上层处理
        }
        finally
        {
            _lifecycleLock.Release();
        }
    }

    /// <summary>
    /// 异步停止设备连接
    /// </summary>
    public async Task StopAsync()
    {
        await _lifecycleLock.WaitAsync().ConfigureAwait(false);
        try
        {
            // 标记离线，阻断后续数据处理
            _isOnline = false;

            // 执行驱动层停止逻辑
            await OnStopAsync().ConfigureAwait(false);
        }
        finally
        {
            // 更新状态并释放锁
            UpdateStatus(VideoSourceStatus.Disconnected, "连接已手动断开");
            _lifecycleLock.Release();
        }
    }

    /// <summary>
    /// 刷新设备元数据，对比差异并更新
    /// </summary>
    /// <returns>元数据差异描述符</returns>
    public async Task<MetadataDiff> RefreshMetadataAsync()
    {
        // 离线状态不刷新元数据
        if (!_isOnline) return MetadataDiff.None;

        try
        {
            // 获取驱动层最新元数据
            var latestMetadata = await OnFetchMetadataAsync().ConfigureAwait(false);
            if (latestMetadata != null && latestMetadata.ChannelCount > 0)
            {
                // 对比新旧元数据差异
                var diff = Metadata.CompareWith(latestMetadata);
                // 更新元数据并标记同步时间
                Metadata = latestMetadata;
                Metadata.MarkSynced();
                return diff;
            }
        }
        catch (Exception ex)
        {
            AddAuditLog($"元数据刷新失败: {ex.Message}");
            Debug.WriteLine($"[MetadataWarning] 设备 {Id}: {ex.Message}");
        }

        return MetadataDiff.None;
    }

    /// <summary>
    /// 应用动态流参数（运行时热更新）
    /// 支持：分辨率切换、码流类型切换、渲染句柄变更等
    /// </summary>
    /// <param name="options">动态配置项</param>
    public void ApplyOptions(DynamicStreamOptions options)
    {
        // 离线或参数为空时，忽略请求
        if (options == null || !_isOnline)
        {
            AddAuditLog("动态参数应用失败：设备离线或参数为空");
            return;
        }

        try
        {
            // 1. 基于设备能力校验参数合法性
            if (Metadata.ValidateOptions(options, out string errorMsg))
            {
                // 2. 执行驱动层参数应用逻辑
                OnApplyOptions(options);
                UpdateStatus(_status, "动态参数已成功应用");

                // 3. 记录参数变更日志
                var changeLog = new List<string>();
                if (options.StreamType.HasValue) changeLog.Add($"码流类型={options.StreamType}");
                if (options.RenderHandle.HasValue) changeLog.Add($"渲染句柄已更新");
                if (options.TargetAnalyzeFps.HasValue) changeLog.Add($"分析帧率={options.TargetAnalyzeFps}fps");

                AddAuditLog($"动态参数应用: {string.Join(" | ", changeLog)}");
            }
            else
            {
                Debug.WriteLine($"[OptionRejected] 设备 {Id}: {errorMsg}");
            }
        }
        catch (Exception ex)
        {
            AddAuditLog($"动态参数应用失败: {ex.Message}");
            Debug.WriteLine($"[ApplyOptionsError] {ex.Message}");
        }
    }

    /// <summary>
    /// 驱动层参数应用逻辑（子类重写）
    /// </summary>
    /// <param name="options">动态配置项</param>
    protected virtual void OnApplyOptions(DynamicStreamOptions options) { }

    #endregion

    #region --- 9. 帧处理与状态管理 (Frame Processing & Status Management) ---

    /// <summary>
    /// 检查是否存在帧订阅者（性能优化）
    /// 无订阅时可跳过解码/预处理等耗时操作
    /// </summary>
    /// <returns>有订阅者返回 true</returns>
    protected bool HasFrameSubscribers() => FrameReceived != null;

    /// <summary>
    /// 上报驱动层异常，触发重连自愈逻辑
    /// </summary>
    /// <param name="ex">相机统一异常</param>
    protected void ReportError(CameraException ex)
    {
        if (!_isOnline) return;

        // 标记离线并更新状态为重连中
        _isOnline = false;
        UpdateStatus(VideoSourceStatus.Reconnecting, $"SDK异常: {ex.Message}", ex);
    }

    /// <summary>
    /// 标记数据接收（心跳保活 + 双路统计）
    /// <para>调用规则：</para>
    /// <para>1. 网络层收到流数据时：调用 MarkFrameReceived(dwBufSize)，只统计流量。</para>
    /// <para>2. 解码层流控通过后：调用 MarkFrameReceived(0)，只统计有效帧率。</para>
    /// </summary>
    /// <param name="dataSize">数据包大小（字节），0 表示这是一帧解码后的图像</param>
    protected void MarkFrameReceived(uint dataSize = 0)
    {
        long now = Environment.TickCount64;

        // 1. [心跳保活] 无论网络包还是解码帧，都视为设备“活着”
        // 使用 Interlocked 保证多线程读写安全
        Interlocked.Exchange(ref _lastFrameTick, now);

        // 2. [分流累加] 根据来源不同，累加不同的计数器
        if (dataSize > 0)
        {
            // --- 来源：网络层回调 (SafeOnRealDataReceived) ---
            // 只累加字节数，用于计算带宽 (Mbps)
            // 绝对不能在这里累加帧数，否则会被网络包的数量误导（导致 FPS 虚高）
            Interlocked.Add(ref _tempByteCounter, dataSize);
        }
        else
        {
            // --- 来源：解码层回调 (SafeOnDecodingCallBack) ---
            // 只累加帧数，用于计算有效 FPS
            // 只有经过 MakeDecision() 筛选保留下来的帧才走到这里，所以是真实的 "Output FPS"
            Interlocked.Increment(ref _tempFrameCounter);

            // 累加生命周期总帧数
            Interlocked.Increment(ref _totalFramesReceived);
        }

        // 3. [定期结算] 每 1000ms (1秒) 结算一次统计指标
        long timeDiff = now - _lastFpsCalcTick;
        if (timeDiff >= 1000)
        {
            // 忽略第一次冷启动的数据（避免除以 0 或时间跨度过大）
            if (_lastFpsCalcTick > 0)
            {
                double duration = timeDiff / 1000.0;

                // --- A. 结算有效帧率 (FPS) ---
                // 原子读取并重置计数器，防止漏算
                int frames = Interlocked.Exchange(ref _tempFrameCounter, 0);
                RealFps = Math.Round(frames / duration, 1);

                // --- B. 结算网络带宽 (Mbps) ---
                // 公式: (字节数 * 8位) / 1024 / 1024 / 秒数
                long bytes = Interlocked.Exchange(ref _tempByteCounter, 0);
                _currentBitrate = Math.Round((bytes * 8.0) / 1024 / 1024 / duration, 2);
            }
            else
            {
                // 初始化重置
                _tempFrameCounter = 0;
                _tempByteCounter = 0;
            }

            // 更新结算时间锚点
            _lastFpsCalcTick = now;
        }
    }

    /// <summary>
    /// 触发帧回调事件（热路径优化）
    /// </summary>
    /// <param name="frameData">帧数据（如 Mat/SmartFrame）</param>
    protected void RaiseFrameReceived(object frameData) => FrameReceived?.Invoke(frameData);

    /// <summary>
    /// 后台状态分发循环（单线程消费状态队列）
    /// </summary>
    /// <param name="token">取消令牌</param>
    private async Task StatusDistributorLoopAsync(CancellationToken token)
    {
        try
        {
            // 关键修复：使用 CancellationToken.None 等待读取
            // 确保取消时仍能消费完队列剩余消息
            while (await _statusQueue.Reader.WaitToReadAsync(CancellationToken.None).ConfigureAwait(false))
            {
                // 批量读取队列中的所有消息
                while (_statusQueue.Reader.TryRead(out var args))
                {
                    // 异常隔离：捕获订阅者回调异常，防止分发器崩溃
                    try
                    {
                        StatusChanged?.Invoke(this, args);
                    }
                    catch (Exception ex)
                    {
                        Debug.WriteLine($"[UIEventError] 设备 {Id} 状态回调异常: {ex.Message}");
                    }

                    // 退出条件：取消令牌已触发 且 队列为空
                    if (token.IsCancellationRequested && _statusQueue.Reader.Count == 0)
                    {
                        return;
                    }
                }

                // 双重检查退出条件
                if (token.IsCancellationRequested && _statusQueue.Reader.Count == 0)
                {
                    return;
                }
            }
        }
        catch (Exception ex)
        {
            Debug.WriteLine($"[DistributorFatal] 设备 {Id} 状态分发器崩溃: {ex.Message}");
        }
    }

    /// <summary>
    /// 更新设备状态并写入分发队列
    /// </summary>
    /// <param name="status">新状态</param>
    /// <param name="msg">状态描述</param>
    /// <param name="ex">关联异常（可选）</param>
    protected void UpdateStatus(VideoSourceStatus status, string msg, CameraException? ex = null)
    {
        lock (_stateSyncRoot)
        {
            // 更新内部状态
            _status = status;

            // 写入状态队列（满时自动丢弃旧数据）
            _ = _statusQueue.Writer.TryWrite(new StatusChangedEventArgs(
                status,
                msg,
                ex,
                ex?.RawErrorCode)
            {
                NewHandle = ex?.Context.TryGetValue("NativeHandle", out var handle) == true ? (IntPtr)handle : null
            });
        }
    }

    #endregion

    #region --- 10. 审计日志辅助 (Audit Log Helpers) ---

    /// <summary>
    /// 添加审计日志（线程安全）
    /// </summary>
    /// <param name="message">日志内容</param>
    public void AddAuditLog(string message)
    {
        lock (_auditLogs)
        {
            var logEntry = $"[{DateTime.Now:HH:mm:ss.fff}] {message}";
            _auditLogs.Add(logEntry);

            // 滚动清除旧日志
            if (_auditLogs.Count > MaxAuditLogCount)
            {
                _auditLogs.RemoveAt(0);
            }
        }
    }

    /// <summary>
    /// 获取审计日志副本
    /// </summary>
    /// <returns>日志列表副本</returns>
    public List<string> GetAuditLogs()
    {
        lock (_auditLogs)
        {
            return new List<string>(_auditLogs);
        }
    }

    #endregion

    #region --- 11. 抽象方法 (Abstract Methods) ---

    /// <summary>
    /// 驱动层启动逻辑（子类必须实现）
    /// 包含：设备登录、码流订阅、取流线程启动等
    /// </summary>
    /// <param name="token">取消令牌</param>
    protected abstract Task OnStartAsync(CancellationToken token);

    /// <summary>
    /// 驱动层停止逻辑（子类必须实现）
    /// 包含：码流停止、设备登出、资源释放等
    /// </summary>
    protected abstract Task OnStopAsync();

    /// <summary>
    /// 驱动层元数据获取逻辑（子类必须实现）
    /// </summary>
    /// <returns>设备元数据</returns>
    protected abstract Task<DeviceMetadata> OnFetchMetadataAsync();

    #endregion

    #region --- 12. 资源清理 (Resource Disposal) ---

    /// <summary>
    /// 同步销毁入口（死锁免疫）
    /// </summary>
    public void Dispose()
    {
        // 异步销毁在后台执行，避免阻塞 UI 线程
        Task.Run(async () => await DisposeAsync().ConfigureAwait(false)).GetAwaiter().GetResult();
    }

    /// <summary>
    /// 异步销毁资源（优雅关闭）
    /// </summary>
    /// <returns>ValueTask</returns>
    public virtual async ValueTask DisposeAsync()
    {
        // 1. 停止业务逻辑
        await StopAsync().ConfigureAwait(false);

        // 2. 优雅关闭状态分发器
        _statusQueue.Writer.TryComplete(); // 标记队列不再接受新消息
        _distributorCts?.Cancel();         // 触发分发器取消

        // 3. 等待分发器处理完剩余消息（最多等待 500ms）
        if (_distributorTask != null)
        {
            await Task.WhenAny(_distributorTask, Task.Delay(500)).ConfigureAwait(false);
        }

        // 4. 切断事件引用，防止内存泄漏
        FrameReceived = null;
        StatusChanged = null;

        // 5. 释放基础资源
        _lifecycleLock.Dispose();
        _distributorCts?.Dispose();

        // 6. 抑制垃圾回收器的终结器
        GC.SuppressFinalize(this);
    }

    #endregion

    #region --- 13. 内部字段与补全属性 ---

    /// <summary> 跟踪上一个未完成的生命周期任务 </summary>
    private Task _pendingLifecycleTask = Task.CompletedTask;

    /// <summary> 帧控制器（用于帧分发策略管理） </summary>
    public FrameController Controller { get; protected set; }

    #endregion
}