hw-web/Admin.NET-v2/Admin.NET/Plugins/Admin.NET.Plugin.HwPortal/Dto/AnalyticsRankItemDTO.cs

// ============================================================================
// 【文件说明】AnalyticsRankItemDTO.cs - 分析排行项 DTO
// ============================================================================
// 这是排行榜中的单项数据结构，用于表示排行中的一个条目。
// 
// 【使用场景】
// - 入口页面排行：Name = 页面路径，Value = 访问次数
// - 热门页面排行：Name = 页面路径，Value = 浏览量
// - 搜索关键词排行：Name = 关键词，Value = 搜索次数
// 
// 【设计模式 - 通用 DTO】
// 这个 DTO 设计得很通用，可以用于多种排行场景：
// - 不限定具体的业务含义
// - Name 和 Value 可以代表不同的事物
// - 减少 DTO 类的数量
// 
// 【与 Java Spring Boot 的对比】
// Java 通常也用类似的通用类：
//   public class RankItem {
//       private String name;
//       private Long value;
//       // getter/setter...
//   }
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 分析排行项。
/// <para>
/// 【业务场景】
/// 用于表示排行榜中的单个条目：
/// - Name：条目名称（如页面路径、关键词）
/// - Value：条目值（如访问次数、浏览量）
/// </para>
/// <para>
/// 【设计说明】
/// 这是一个通用的排行项结构，可用于：
/// - 入口页面排行：Name = 页面路径，Value = 进入次数
/// - 热门页面排行：Name = 页面路径，Value = PV
/// - 搜索关键词排行：Name = 关键词，Value = 搜索次数
/// </para>
/// </summary>
public class AnalyticsRankItemDTO
{
    /// <summary>
    /// 条目名称。
    /// <para>
    /// 【业务含义】
    /// 根据排行类型不同，含义不同：
    /// - 入口页面排行：页面路径（如 /product/detail）
    /// - 热门页面排行：页面路径（如 /search）
    /// - 搜索关键词排行：搜索关键词（如 "产品介绍"）
    /// </para>
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 条目值。
    /// <para>
    /// 【业务含义】
    /// 根据排行类型不同，含义不同：
    /// - 入口页面排行：进入次数
    /// - 热门页面排行：页面浏览量（PV）
    /// - 搜索关键词排行：搜索次数
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 可空值类型】
    /// long? 是可空的长整型：
    /// - 可以是 null（表示无数据）
    /// - 可以是 long 值
    /// 
    /// 为什么用可空类型？
    /// - 数据库查询可能返回 null
    /// - 前端需要区分"0 次"和"无数据"
    /// </para>
    /// </summary>
    public long? Value { get; set; }
}