|
|
// ============================================================================
|
|
|
// 【文件说明】AnalyticsCollectRequest.cs - 分析事件收集请求 DTO
|
|
|
// ============================================================================
|
|
|
// 这是前端上报访问事件的请求数据结构。
|
|
|
//
|
|
|
// 【什么是 DTO？】
|
|
|
// DTO = Data Transfer Object（数据传输对象）
|
|
|
// - 用于在 API 和前端之间传递数据
|
|
|
// - 不包含业务逻辑
|
|
|
// - 通常是简单的属性容器
|
|
|
//
|
|
|
// 【与 Java Spring Boot 的对比】
|
|
|
// Java 通常用 POJO 或 Record：
|
|
|
// public class AnalyticsCollectRequest {
|
|
|
// private String visitorId;
|
|
|
// private String sessionId;
|
|
|
// // getter/setter...
|
|
|
// }
|
|
|
//
|
|
|
// 或 Java 14+ Record：
|
|
|
// public record AnalyticsCollectRequest(
|
|
|
// String visitorId,
|
|
|
// String sessionId,
|
|
|
// ...
|
|
|
// ) {}
|
|
|
//
|
|
|
// C# 用普通类 + 自动属性，更简洁。
|
|
|
// ============================================================================
|
|
|
|
|
|
namespace Admin.NET.Plugin.HwPortal;
|
|
|
|
|
|
/// <summary>
|
|
|
/// 分析事件收集请求。
|
|
|
/// <para>
|
|
|
/// 【业务场景】
|
|
|
/// 前端在以下时机上报事件：
|
|
|
/// - 页面加载完成：page_view
|
|
|
/// - 离开页面：page_leave（带停留时长）
|
|
|
/// - 提交搜索：search_submit（带关键词）
|
|
|
/// - 点击下载：download_click
|
|
|
/// - 提交联系表单：contact_submit
|
|
|
/// </para>
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - 自动属性】
|
|
|
/// public string VisitorId { get; set; }
|
|
|
///
|
|
|
/// 这是 C# 3.0 引入的"自动属性"语法：
|
|
|
/// - 编译器自动生成私有字段
|
|
|
/// - 不需要显式声明 getter/setter
|
|
|
/// - 等价于 Java 的 private field + public getter/setter
|
|
|
///
|
|
|
/// 对比 Java：
|
|
|
/// Java:
|
|
|
/// private String visitorId;
|
|
|
/// public String getVisitorId() { return visitorId; }
|
|
|
/// public void setVisitorId(String visitorId) { this.visitorId = visitorId; }
|
|
|
///
|
|
|
/// C# 一行代码完成同样功能。
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public class AnalyticsCollectRequest
|
|
|
{
|
|
|
/// <summary>
|
|
|
/// 访客 ID。
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 由前端生成并存储在 Cookie 或 localStorage：
|
|
|
/// - 首次访问时生成 UUID
|
|
|
/// - 后续访问复用同一 ID
|
|
|
/// - 用于识别同一访客的多次访问
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string VisitorId { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 会话 ID。
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 每次访问生成新的会话 ID：
|
|
|
/// - 用于区分不同的访问会话
|
|
|
/// - 计算跳出率（单页会话占比）
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string SessionId { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 事件类型。
|
|
|
/// <para>
|
|
|
/// 【允许值】
|
|
|
/// - page_view：页面浏览
|
|
|
/// - page_leave：离开页面
|
|
|
/// - search_submit：提交搜索
|
|
|
/// - download_click：点击下载
|
|
|
/// - contact_submit：提交联系表单
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string EventType { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 页面路径。
|
|
|
/// <para>
|
|
|
/// 【示例】
|
|
|
/// /product/detail
|
|
|
/// /search?keyword=xxx
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string Path { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 来源页面（Referrer）。
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 用户从哪个页面跳转过来：
|
|
|
/// - 搜索引擎：https://www.google.com/search?q=xxx
|
|
|
/// - 外部网站：https://partner.com/link
|
|
|
/// - 直接访问：为空
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string Referrer { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// UTM 来源参数。
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 用于营销追踪：
|
|
|
/// - utm_source：流量来源（如 google, baidu）
|
|
|
/// - utm_medium：营销媒介（如 cpc, email）
|
|
|
/// - utm_campaign：营销活动名称
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string UtmSource { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// UTM 媒介参数。
|
|
|
/// </summary>
|
|
|
public string UtmMedium { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// UTM 活动参数。
|
|
|
/// </summary>
|
|
|
public string UtmCampaign { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 搜索关键词。
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 仅 search_submit 事件需要此字段。
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string Keyword { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// User-Agent 字符串。
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 前端可以上报自己的 UA，如果不传则使用请求头中的 UA。
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string Ua { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 设备类型（前端上报）。
|
|
|
/// <para>
|
|
|
/// 【允许值】
|
|
|
/// - Mobile：手机
|
|
|
/// - Tablet：平板
|
|
|
/// - Desktop：桌面
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public string Device { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 浏览器名称（前端上报）。
|
|
|
/// </summary>
|
|
|
public string Browser { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 操作系统（前端上报）。
|
|
|
/// </summary>
|
|
|
public string Os { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 停留时长（毫秒）。
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - 可空值类型】
|
|
|
/// long? 是可空的长整型：
|
|
|
/// - 可以是 null（表示未提供）
|
|
|
/// - 可以是 long 值
|
|
|
///
|
|
|
/// 对比 Java：
|
|
|
/// Java 用 Long 包装类：
|
|
|
/// private Long stayMs; // 可以为 null
|
|
|
///
|
|
|
/// C# 的可空值类型是值类型，更高效。
|
|
|
/// </para>
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 仅 page_leave 事件需要此字段。
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public long? StayMs { get; set; }
|
|
|
|
|
|
/// <summary>
|
|
|
/// 事件时间（Unix 毫秒时间戳）。
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 前端上报事件发生的时间：
|
|
|
/// - 如果不传，使用服务器当前时间
|
|
|
/// - 用于处理网络延迟导致的时间偏差
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public long? EventTime { get; set; }
|
|
|
}
|