// ============================================================================
// 【文件说明】SearchPageDTO.cs - 搜索分页结果 DTO
// ============================================================================
// 这是搜索接口返回的分页数据结构。
// 
// 【分页设计说明】
// 分页是 Web 开发的常见需求：
// - 数据量大时，不可能一次返回所有数据
// - 分页返回：每页 N 条，返回总数和当前页数据
// 
// 【与 Java Spring Boot 的对比】
// Java 若依的分页结构：
//   public class TableDataInfo {
//       private long total;           // 总记录数
//       private List<?> rows;         // 数据列表
//       private int code;             // 状态码
//       private String msg;           // 消息
//   }
// 
// C# 这里更简洁，只包含核心字段：
// - Total：总记录数
// - Rows：当前页数据
// 
// Admin.NET 框架会自动包装统一的返回格式，所以 DTO 不需要 code/msg 字段。
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 搜索分页结果。
/// <para>
/// 【业务场景】
/// 前端搜索接口返回的数据结构：
/// - Total：总记录数（用于前端分页组件）
/// - Rows：当前页数据列表
/// </para>
/// <para>
/// 【设计模式 - 分页 DTO】
/// 这是标准的分页数据结构：
/// - 不包含页码、每页条数（这些由前端维护）
/// - 只返回总数和数据列表
/// - 适用于任何分页场景
/// </para>
/// </summary>
public class SearchPageDTO
{
    /// <summary>
    /// 总记录数。
    /// <para>
    /// 【业务说明】
    /// 用于前端计算总页数：
    /// - 总页数 = Math.Ceiling(Total / PageSize)
    /// - 前端分页组件需要此值显示页码
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - long 类型】
    /// long 是 64 位整数：
    /// - 范围：-9,223,372,036,854,775,808 到 9,223,372,036,854,775,807
    /// - 对比 Java：Java 的 long 也是 64 位
    /// - 为什么用 long？数据量可能超过 int 的 21 亿上限
    /// </para>
    /// </summary>
    public long Total { get; set; }

    /// <summary>
    /// 当前页数据列表。
    /// <para>
    /// 【业务说明】
    /// 当前页的搜索结果列表。
    /// 每个元素是一个 SearchResultDTO 对象。
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 泛型集合】
    /// List&lt;SearchResultDTO&gt; 是泛型集合：
    /// - List：动态数组，可以添加、删除元素
    /// - &lt;SearchResultDTO&gt;：泛型参数，指定元素类型
    /// 
    /// 对比 Java：
    /// Java: List&lt;SearchResultDTO&gt; rows = new ArrayList&lt;&gt;();
    /// C#:  List&lt;SearchResultDTO&gt; Rows { get; set; } = new();
    /// 
    /// C# 的 = new() 是目标类型 new 表达式，编译器自动推断类型。
    /// </para>
    /// </summary>
    public List<SearchResultDTO> Rows { get; set; } = new();
}