// ============================================================================
// 【文件说明】AnalyticsDashboardDTO.cs - 分析仪表盘数据 DTO
// ============================================================================
// 这是仪表盘接口返回的数据结构，包含网站访问统计的核心指标。
// 
// 【核心指标说明】
// - PV（Page View）：页面浏览量，用户每打开一个页面计为 1 次
// - UV（Unique Visitor）：独立访客数，同一访客多次访问只计 1 次
// - IP UV：独立 IP 数，同一 IP 多次访问只计 1 次
// - 跳出率：只浏览一页就离开的会话占比
// - 平均停留时长：用户在网站的平均停留时间
// 
// 【与 Java Spring Boot 的对比】
// Java 通常用 POJO：
//   public class AnalyticsDashboardDTO {
//       private String statDate;
//       private Long pv;
//       private Long uv;
//       // getter/setter...
//   }
// 
// C# 用自动属性，代码更简洁。
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 分析仪表盘数据。
/// <para>
/// 【业务场景】
/// 管理后台的"数据分析"页面展示：
/// - 今日/指定日期的访问统计
//  - 热门页面排行
//  - 搜索关键词排行
/// </para>
/// </summary>
public class AnalyticsDashboardDTO
{
    /// <summary>
    /// 统计日期（格式：yyyy-MM-dd）。
    /// </summary>
    public string StatDate { get; set; }

    /// <summary>
    /// 页面浏览量（PV）。
    /// <para>
    /// 【业务说明】
    /// 用户每打开一个页面计为 1 次 PV。
    /// 同一用户刷新页面会增加 PV。
    /// </para>
    /// </summary>
    public long? Pv { get; set; }

    /// <summary>
    /// 独立访客数（UV）。
    /// <para>
    /// 【业务说明】
    /// 按 visitorId 去重统计。
    /// 同一访客多次访问只计 1 次 UV。
    /// </para>
    /// </summary>
    public long? Uv { get; set; }

    /// <summary>
    /// 独立 IP 数。
    /// <para>
    /// 【业务说明】
    /// 按 IP 哈希去重统计。
    /// 同一 IP 多次访问只计 1 次。
    /// 注意：由于存储的是哈希值，无法反查原始 IP。
    /// </para>
    /// </summary>
    public long? IpUv { get; set; }

    /// <summary>
    /// 平均停留时长（毫秒）。
    /// <para>
    /// 【计算方式】
    /// 所有 page_leave 事件的停留时长平均值。
    /// </para>
    /// </summary>
    public long? AvgStayMs { get; set; }

    /// <summary>
    /// 跳出率（百分比）。
    /// <para>
    /// 【计算方式】
    /// 跳出率 = 单页会话数 / 总会话数 × 100
    /// 
    /// 【业务含义】
    /// - 跳出率高：用户只看了一页就离开，可能内容不相关或体验差
    /// - 跳出率低：用户浏览了多个页面，内容吸引人
    /// </para>
    /// </summary>
    public double? BounceRate { get; set; }

    /// <summary>
    /// 搜索次数。
    /// <para>
    /// 【业务说明】
    /// search_submit 事件的总次数。
    /// </para>
    /// </summary>
    public long? SearchCount { get; set; }

    /// <summary>
    /// 下载次数。
    /// <para>
    /// 【业务说明】
    /// download_click 事件的总次数。
    /// </para>
    /// </summary>
    public long? DownloadCount { get; set; }

    /// <summary>
    /// 入口页面排行。
    /// <para>
    /// 【业务说明】
    /// 用户进入网站的第一页统计：
    /// - 哪些页面是用户进入网站的入口
    /// - 用于评估推广页面的效果
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 集合属性初始化】
    /// List&lt;T&gt; Property { get; set; } = new();
    /// 
    /// = new() 是属性初始化器：
    /// - 创建对象时自动初始化集合
    /// - 避免 null 引用异常
    /// - new() 是 C# 9.0 的目标类型 new 表达式
    /// 
    /// 对比 Java：
    /// Java 通常不初始化，或需要显式初始化：
    ///   private List&lt;Item&gt; items = new ArrayList&lt;&gt;();
    /// </para>
    /// </summary>
    public List<AnalyticsRankItemDTO> EntryPages { get; set; } = new();

    /// <summary>
    /// 热门页面排行。
    /// <para>
    /// 【业务说明】
    /// 浏览量最高的页面列表。
    /// </para>
    /// </summary>
    public List<AnalyticsRankItemDTO> HotPages { get; set; } = new();

    /// <summary>
    /// 热门搜索关键词排行。
    /// <para>
    /// 【业务说明】
    /// 搜索次数最多的关键词列表。
    /// </para>
    /// </summary>
    public List<AnalyticsRankItemDTO> HotKeywords { get; set; } = new();
}