// ============================================================================
// 【文件说明】SearchResultDTO.cs - 搜索结果项 DTO
// ============================================================================
// 这是搜索结果列表中的单项数据结构。
// 
// 【设计说明】
// 这是面向前端的搜索结果格式：
// - 不直接返回数据库实体
// - 只包含前端需要的字段
// - 字段经过处理（如 Snippet 是截断后的摘要）
// 
// 【与 SearchRawRecord 的区别】
// - SearchRawRecord：旧版搜索的原始数据，字段多且可能为空
// - SearchResultDTO：新版搜索的结果数据，字段精简且友好
// 
// 【与 Java Spring Boot 的对比】
// Java 若依的搜索结果 VO：
//   public class SearchResultVO {
//       private String sourceType;
//       private String title;
//       private String snippet;
//       // getter/setter...
//   }
// 
// C# 用自动属性，代码更简洁。
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 搜索结果项。
/// <para>
/// 【业务场景】
/// 前端搜索结果列表中的单个条目：
/// - 展示标题、摘要
/// - 点击跳转到详情页
/// - 显示来源类型图标
/// </para>
/// <para>
/// 【设计模式 - DTO vs Entity】
/// 为什么不直接返回数据库实体？
/// 1. 安全性：实体可能包含敏感字段
/// 2. 灵活性：DTO 可以组合多个实体的字段
/// 3. 性能：DTO 只返回需要的字段，减少数据传输
/// 4. 解耦：数据库结构变化不影响 API 契约
/// </para>
/// </summary>
public class SearchResultDTO
{
    /// <summary>
    /// 来源类型。
    /// <para>
    /// 【允许值】
    /// - menu：菜单
    /// - web：页面
    /// - web1：页面1
    /// - document：文档
    /// - configType：配置类型
    /// 
    /// 【前端用途】
    /// 用于显示不同类型的结果图标。
    /// </para>
    /// </summary>
    public string SourceType { get; set; }

    /// <summary>
    /// 标题。
    /// <para>
    /// 【业务说明】
    /// 搜索结果展示的主要文本。
    /// 用于搜索结果列表的标题显示。
    /// </para>
    /// </summary>
    public string Title { get; set; }

    /// <summary>
    /// 内容摘要。
    /// <para>
    /// 【业务说明】
    /// 从 Content 中截取的摘要：
    /// - 包含搜索关键词的上下文
    /// - 长度有限，适合列表展示
    /// - 可能包含高亮标记
    /// </para>
    /// </summary>
    public string Snippet { get; set; }

    /// <summary>
    /// 相关性得分。
    /// <para>
    /// 【业务说明】
    /// 用于搜索结果排序：
    /// - 分数越高，排名越靠前
    /// - 前端可以显示"相关度"提示
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 可空值类型】
    /// int? 是可空的整型：
    /// - 可以是 null（表示未计算得分）
    /// - 可以是 int 值
    /// </para>
    /// </summary>
    public int? Score { get; set; }

    /// <summary>
    /// 路由路径。
    /// <para>
    /// 【业务说明】
    /// 前端跳转的路由路径。
    /// 例如：/product/detail
    /// </para>
    /// </summary>
    public string Route { get; set; }

    /// <summary>
    /// 路由查询参数（字典格式）。
    /// <para>
    /// 【业务说明】
    /// 路由的查询参数，已解析为字典：
    /// - Key：参数名
    /// - Value：参数值（可能是字符串、数字等）
    /// 
    /// 例如：{"id": "123", "type": "product"}
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - Dictionary&lt;K,V&gt; 字典】
    /// Dictionary&lt;string, object&gt; 是键值对集合：
    /// - Key：string 类型
    /// - Value：object 类型（可以存储任意类型）
    /// 
    /// 对比 Java：
    /// Java: Map&lt;String, Object&gt; routeQuery = new HashMap&lt;&gt;();
    /// 
    /// 为什么用 object 类型？
    /// - 参数值可能是字符串、数字、布尔值等
    /// - object 是所有类型的基类，可以存储任意值
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 集合初始化器】
    /// = new() 是属性初始化器：
    /// - 创建对象时自动初始化字典
    /// - 避免 null 引用异常
    /// </para>
    /// </summary>
    public Dictionary<string, object> RouteQuery { get; set; } = new();

    /// <summary>
    /// 编辑路由。
    /// <para>
    /// 【业务说明】
    /// 管理后台的编辑页面路由。
    /// 用于从搜索结果直接跳转到编辑页面。
    /// </para>
    /// </summary>
    public string EditRoute { get; set; }
}