it/backend/HardwarePerformance.Application/Interfaces/IProductRepository.cs

using HardwarePerformance.Core.Entities;

namespace HardwarePerformance.Application.Interfaces
{
    /// <summary>
    /// 产品Repository接口
    /// </summary>
    public interface IProductRepository : IRepository<Product>
    {
        /// <summary>
        /// 根据类别ID获取产品列表（支持分页和排序）
        /// </summary>
        /// <param name="categoryId">类别ID</param>
        /// <param name="pageNumber">页码</param>
        /// <param name="pageSize">每页大小</param>
        /// <param name="sortBy">排序字段</param>
        /// <param name="ascending">是否升序</param>
        /// <returns>产品列表</returns>
        Task<(IEnumerable<Product> products, int totalCount)> GetByCategoryAsync(
            int categoryId, 
            int pageNumber = 1, 
            int pageSize = 20, 
            string sortBy = "CurrentRank", 
            bool ascending = true);

        /// <summary>
        /// 搜索产品（按名称、型号、品牌）
        /// </summary>
        /// <param name="searchTerm">搜索关键词</param>
        /// <param name="categoryId">类别ID（可选）</param>
        /// <param name="pageNumber">页码</param>
        /// <param name="pageSize">每页大小</param>
        /// <returns>产品列表</returns>
        Task<(IEnumerable<Product> products, int totalCount)> SearchAsync(
            string searchTerm, 
            int? categoryId = null, 
            int pageNumber = 1, 
            int pageSize = 20);

        /// <summary>
        /// 筛选产品（按性能分数区间、发布年份、品牌）
        /// </summary>
        /// <param name="categoryId">类别ID</param>
        /// <param name="minScore">最低分数</param>
        /// <param name="maxScore">最高分数</param>
        /// <param name="minYear">最早年份</param>
        /// <param name="maxYear">最晚年份</param>
        /// <param name="manufacturer">品牌</param>
        /// <param name="pageNumber">页码</param>
        /// <param name="pageSize">每页大小</param>
        /// <returns>产品列表</returns>
        Task<(IEnumerable<Product> products, int totalCount)> FilterAsync(
            int categoryId, 
            int? minScore = null, 
            int? maxScore = null, 
            int? minYear = null, 
            int? maxYear = null, 
            string? manufacturer = null, 
            int pageNumber = 1, 
            int pageSize = 20);

        /// <summary>
        /// 获取产品详情（包含规格参数和性能分数）
        /// </summary>
        /// <param name="id">产品ID</param>
        /// <returns>产品详情</returns>
        Task<Product?> GetWithDetailsAsync(int id);

        /// <summary>
        /// 获取多个产品（用于对比）
        /// </summary>
        /// <param name="productIds">产品ID列表</param>
        /// <returns>产品列表</returns>
        Task<IEnumerable<Product>> GetByIdsAsync(IEnumerable<int> productIds);

        /// <summary>
        /// 获取品牌列表
        /// </summary>
        /// <param name="categoryId">类别ID（可选）</param>
        /// <returns>品牌列表</returns>
        Task<IEnumerable<string>> GetManufacturersAsync(int? categoryId = null);

        /// <summary>
        /// 获取排名变化历史
        /// </summary>
        /// <param name="productId">产品ID</param>
        /// <param name="months">月份数</param>
        /// <returns>排名历史</returns>
        Task<IEnumerable<RankingHistory>> GetRankingHistoryAsync(int productId, int months = 12);

        /// <summary>
        /// 根据制造商获取产品列表
        /// </summary>
        /// <param name="manufacturer">制造商名称</param>
        /// <param name="categoryId">类别ID（可选）</param>
        /// <param name="pageNumber">页码</param>
        /// <param name="pageSize">每页大小</param>
        /// <returns>产品列表</returns>
        Task<(IEnumerable<Product> products, int totalCount)> GetByManufacturerAsync(
            string manufacturer, 
            int? categoryId = null, 
            int pageNumber = 1, 
            int pageSize = 20);

        /// <summary>
        /// 根据型号获取产品
        /// </summary>
        /// <param name="model">型号</param>
        /// <returns>产品</returns>
        Task<Product?> GetByModelAsync(string model);

        /// <summary>
        /// 获取类别中排名前N的产品
        /// </summary>
        /// <param name="categoryId">类别ID</param>
        /// <param name="n">数量</param>
        /// <returns>产品列表</returns>
        Task<IEnumerable<Product>> GetTopNByCategoryAsync(int categoryId, int n);
    }
}