using System.Collections.Generic;
using System.Threading.Tasks;
using MDL.Models;
using SqlSugar;

namespace DAL.Interfaces
{
    /// <summary>
    /// 面单PDF缓存的数据访问接口
    /// </summary>
    public interface ILabelPdfCacheRepository
    {
        /// <summary>
        /// 根据中性面单单号获取缓存记录
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <returns>缓存记录实体</returns>
        Task<LabelPdfCache?> GetByWaybillNumberAsync(string waybillNumber);

        /// <summary>
        /// 根据中性面单单号获取缓存元数据（不含 pdf_bytes），用于校验缓存有效性，避免加载大字段
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <returns>不含 PdfBytes 的缓存实体，不存在时返回 null</returns>
        Task<LabelPdfCache?> GetMetaByWaybillNumberAsync(string waybillNumber);

        /// <summary>
        /// 单独查询指定面单的 PDF 字节流，仅在缓存校验通过后调用，避免无效 BLOB 传输
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <returns>PDF 字节数组，不存在时返回 null</returns>
        Task<byte[]?> GetPdfBytesAsync(string waybillNumber);
        
        /// <summary>
        /// 创建缓存记录
        /// </summary>
        /// <param name="entity">缓存实体</param>
        /// <returns>创建的记录ID</returns>
        Task<long> CreateAsync(LabelPdfCache entity);
        
        /// <summary>
        /// 更新缓存记录
        /// </summary>
        /// <param name="entity">缓存实体</param>
        /// <returns>更新是否成功</returns>
        Task<bool> UpdateAsync(LabelPdfCache entity);
        
        /// <summary>
        /// 标记缓存为失效状态
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <returns>操作是否成功</returns>
        Task<bool> InvalidateCacheAsync(string waybillNumber);
        
        /// <summary>
        /// 获取待处理的缓存任务列表
        /// </summary>
        /// <param name="maxRetryCount">最大重试次数</param>
        /// <param name="limit">最大返回数量</param>
        /// <returns>待处理的缓存任务列表</returns>
        Task<List<LabelPdfCache>> GetPendingTasksAsync(int maxRetryCount, int limit);
        
        /// <summary>
        /// 获取订单表中新的有标签订单（缓存表中不存在的）
        /// </summary>
        /// <param name="limit">最大返回数量</param>
        /// <returns>新订单的面单号列表</returns>
        Task<List<string>> GetNewOrdersWithLabelsAsync(int limit);
        
        /// <summary>
        /// 获取需要重新处理的失效缓存列表
        /// </summary>
        /// <param name="limit">最大返回数量</param>
        /// <returns>失效的缓存记录列表</returns>
        Task<List<LabelPdfCache>> GetInvalidCachesAsync(int limit);
        
        /// <summary>
        /// 异步更新条码信息
        /// </summary>
        /// <param name="waybillNumber">中性面单单号</param>
        /// <param name="barcodeNumber">条码号</param>
        /// <param name="barcodeType">条码类型</param>
        /// <param name="confidence">识别置信度</param>
        /// <returns>更新是否成功</returns>
        Task<bool> UpdateBarcodeInfoAsync(string waybillNumber, string barcodeNumber, byte barcodeType, int confidence);

        /// <summary>
        /// 获取数据库客户端实例
        /// </summary>
        /// <returns>SqlSugar数据库客户端</returns>
        ISqlSugarClient GetClient();

        /// <summary>
        /// 获取定时任务新订单（仅2026-05-10之后的订单）
        /// </summary>
        /// <param name="limit">最大返回数量</param>
        /// <returns>新订单的中性面单号列表（仅>=2026-05-10）</returns>
        Task<List<string>> GetNewOrdersWithLabelsForBackgroundTaskAsync(int limit);
    }
}
