using System.Threading.Tasks;
using MDL.Models;

namespace BLL.Interfaces
{
    /// <summary>
    /// 面单PDF缓存服务接口
    /// </summary>
    public interface ILabelPdfCacheService
    {
        /// <summary>
        /// 获取有效的缓存记录（状态为处理成功的）
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <returns>缓存记录，不存在或无效返回null</returns>
        Task<LabelPdfCache?> GetValidCacheAsync(string waybillNumber);

        /// <summary>
        /// 获取有效的缓存记录，传入已有订单对象跳过内部重复查询
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <param name="order">已查询好的订单实体，传入后跳过内部DB查询</param>
        /// <returns>缓存记录，不存在或无效返回null</returns>
        Task<LabelPdfCache?> GetValidCacheAsync(string waybillNumber, LabelReplaceEntity? order);
        
        /// <summary>
        /// 保存PDF缓存
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <param name="pdfBytes">PDF字节流</param>
        /// <param name="pageCount">PDF页数</param>
        /// <param name="fileSize">文件大小</param>
        /// <param name="originalUrl">原始标签URL</param>
        /// <param name="finalMileTrackingNumber">尾程跟踪单号</param>
        /// <param name="customerId">客户ID</param>
        /// <param name="barcodeNumber">提取到的条码单号</param>
        /// <param name="barcodeType">条码类型</param>
        /// <param name="barcodeConfidence">识别置信度</param>
        /// <param name="parseDurationMs">PDF解析花费的时间（毫秒）</param>
        /// <returns>操作是否成功</returns>
        Task<bool> SaveCacheAsync(string waybillNumber, byte[] pdfBytes, int pageCount, int fileSize, 
            string? originalUrl = null,
            string? finalMileTrackingNumber = null, int? customerId = null,
            string? barcodeNumber = null, byte barcodeType = 0, int? barcodeConfidence = null, int? parseDurationMs = null);
        
        /// <summary>
        /// 标记缓存为失效状态
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <returns>操作是否成功</returns>
        Task<bool> InvalidateCacheAsync(string waybillNumber);
        
        /// <summary>
        /// 处理待处理的缓存任务
        /// </summary>
        /// <param name="maxRetryCount">最大重试次数，默认3次</param>
        /// <param name="batchSize">每次处理的批量大小，默认300</param>
        /// <returns>处理成功的数量</returns>
        Task<int> ProcessPendingTasksAsync(int maxRetryCount = 3, int batchSize = 300);
        
        /// <summary>
        /// 从PDF字节流中提取条码信息
        /// </summary>
        /// <param name="pdfBytes">PDF字节流</param>
        /// <returns>元组：(条码内容, 条码类型:0=未识别,1=一维码,2=二维码, 置信度0-100)</returns>
        Task<(string barcodeNumber, byte barcodeType, int confidence)> ExtractBarcodeFromPdfAsync(byte[] pdfBytes);

        /// <summary>
        /// 处理单条缓存任务（公开接口，用于手动触发）
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <returns>元组：(处理是否成功, 错误消息)</returns>
        Task<(bool Success, string ErrorMessage)> ProcessSingleCacheTaskAsync(string waybillNumber);

        /// <summary>
        /// 获取缓存统计信息
        /// </summary>
        /// <returns>统计数据</returns>
        Task<CacheStatistics> GetCacheStatisticsAsync();
    }
}
