|
|
// ============================================================================
|
|
|
// 【文件说明】HwAnalyticsService.cs - 网站访问统计分析服务
|
|
|
// ============================================================================
|
|
|
// 这个服务负责收集和分析网站访问数据，类似于 Google Analytics 的功能。
|
|
|
//
|
|
|
// 【核心功能】
|
|
|
// 1. 收集访问事件：页面浏览、搜索、下载等
|
|
|
// 2. 解析 User-Agent：获取浏览器、操作系统、设备类型
|
|
|
// 3. 生成日报统计：PV、UV、跳出率等
|
|
|
// 4. 提供仪表盘数据：热门页面、搜索关键词排行
|
|
|
//
|
|
|
// 【数据流程】
|
|
|
// 1. 前端上报事件 → Collect 方法接收
|
|
|
// 2. 解析并归一化数据 → 写入明细表
|
|
|
// 3. 聚合计算日报 → 写入日报表
|
|
|
// 4. 查询仪表盘 → 返回统计数据
|
|
|
//
|
|
|
// 【隐私保护】
|
|
|
// - IP 地址不直接存储，而是存储哈希值
|
|
|
// - 访客 ID 由前端生成，不包含个人信息
|
|
|
//
|
|
|
// 【与 Java Spring Boot 的对比】
|
|
|
// Java 通常用定时任务聚合统计：
|
|
|
// @Scheduled(cron = "0 5 0 * * ?") // 每天凌晨 0:05 执行
|
|
|
// public void aggregateDailyStats() { ... }
|
|
|
//
|
|
|
// C# 这里在写入事件时实时聚合，保证数据即时可用。
|
|
|
// ============================================================================
|
|
|
|
|
|
using UAParser;
|
|
|
|
|
|
namespace Admin.NET.Plugin.HwPortal;
|
|
|
|
|
|
/// <summary>
|
|
|
/// 网站访问统计分析服务。
|
|
|
/// <para>
|
|
|
/// 【服务职责】
|
|
|
/// 1. 收集访问事件（页面浏览、搜索、下载等）
|
|
|
/// 2. 解析 User-Agent 获取设备信息
|
|
|
/// 3. 聚合生成日报统计
|
|
|
/// 4. 提供仪表盘查询接口
|
|
|
/// </para>
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - ITransient 瞬态服务】
|
|
|
/// ITransient 表示每次请求都创建新实例。
|
|
|
/// 分析服务通常是无状态的，适合瞬态模式。
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public class HwAnalyticsService : ITransient
|
|
|
{
|
|
|
/// <summary>
|
|
|
/// MyBatis 映射器名称。
|
|
|
/// </summary>
|
|
|
private const string Mapper = "HwAnalyticsMapper";
|
|
|
private const string InsertVisitEventSql =
|
|
|
"""
|
|
|
INSERT INTO hw_web_visit_event (
|
|
|
event_type, visitor_id, session_id, path, referrer, utm_source, utm_medium, utm_campaign,
|
|
|
keyword, ip_hash, ua, device, browser, os, stay_ms, event_time, created_at
|
|
|
) VALUES (
|
|
|
@EventType, @VisitorId, @SessionId, @Path, @Referrer, @UtmSource, @UtmMedium, @UtmCampaign,
|
|
|
@Keyword, @IpHash, @Ua, @Device, @Browser, @Os, @StayMs, @EventTime, NOW()
|
|
|
)
|
|
|
""";
|
|
|
private const string CountEventByTypeSql =
|
|
|
"""
|
|
|
SELECT COUNT(1)
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = @eventType
|
|
|
""";
|
|
|
private const string CountDistinctVisitorSql =
|
|
|
"""
|
|
|
SELECT COUNT(DISTINCT visitor_id)
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'page_view'
|
|
|
AND visitor_id IS NOT NULL
|
|
|
AND visitor_id != ''
|
|
|
""";
|
|
|
private const string CountDistinctIpSql =
|
|
|
"""
|
|
|
SELECT COUNT(DISTINCT ip_hash)
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'page_view'
|
|
|
AND ip_hash IS NOT NULL
|
|
|
AND ip_hash != ''
|
|
|
""";
|
|
|
private const string AvgStayMsSql =
|
|
|
"""
|
|
|
SELECT COALESCE(ROUND(AVG(stay_ms)), 0)
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'page_leave'
|
|
|
AND stay_ms IS NOT NULL
|
|
|
AND stay_ms >= 0
|
|
|
""";
|
|
|
private const string CountDistinctSessionsSql =
|
|
|
"""
|
|
|
SELECT COUNT(DISTINCT session_id)
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'page_view'
|
|
|
AND session_id IS NOT NULL
|
|
|
AND session_id != ''
|
|
|
""";
|
|
|
private const string CountSinglePageSessionsSql =
|
|
|
"""
|
|
|
SELECT COUNT(1)
|
|
|
FROM (
|
|
|
SELECT session_id
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'page_view'
|
|
|
AND session_id IS NOT NULL
|
|
|
AND session_id != ''
|
|
|
GROUP BY session_id
|
|
|
HAVING COUNT(1) = 1
|
|
|
) t
|
|
|
""";
|
|
|
private const string SelectTopEntryPagesSql =
|
|
|
"""
|
|
|
SELECT IFNULL(e.path, '/') AS name, COUNT(1) AS value
|
|
|
FROM hw_web_visit_event e
|
|
|
INNER JOIN (
|
|
|
SELECT session_id, MIN(event_time) AS min_event_time
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'page_view'
|
|
|
AND session_id IS NOT NULL
|
|
|
AND session_id != ''
|
|
|
GROUP BY session_id
|
|
|
) s ON s.session_id = e.session_id AND s.min_event_time = e.event_time
|
|
|
WHERE DATE(e.event_time) = @statDate
|
|
|
AND e.event_type = 'page_view'
|
|
|
GROUP BY e.path
|
|
|
ORDER BY value DESC
|
|
|
LIMIT @limit
|
|
|
""";
|
|
|
private const string SelectTopHotPagesSql =
|
|
|
"""
|
|
|
SELECT IFNULL(path, '/') AS name, COUNT(1) AS value
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'page_view'
|
|
|
GROUP BY path
|
|
|
ORDER BY value DESC
|
|
|
LIMIT @limit
|
|
|
""";
|
|
|
private const string SelectTopKeywordsSql =
|
|
|
"""
|
|
|
SELECT keyword AS name, COUNT(1) AS value
|
|
|
FROM hw_web_visit_event
|
|
|
WHERE DATE(event_time) = @statDate
|
|
|
AND event_type = 'search_submit'
|
|
|
AND keyword IS NOT NULL
|
|
|
AND keyword != ''
|
|
|
GROUP BY keyword
|
|
|
ORDER BY value DESC
|
|
|
LIMIT @limit
|
|
|
""";
|
|
|
private const string UpsertDailySql =
|
|
|
"""
|
|
|
INSERT INTO hw_web_visit_daily (
|
|
|
stat_date, pv, uv, ip_uv, avg_stay_ms, bounce_rate, search_count, download_count, created_at, updated_at
|
|
|
) VALUES (
|
|
|
@StatDate, @Pv, @Uv, @IpUv, @AvgStayMs, @BounceRate, @SearchCount, @DownloadCount, NOW(), NOW()
|
|
|
)
|
|
|
ON DUPLICATE KEY UPDATE
|
|
|
pv = VALUES(pv),
|
|
|
uv = VALUES(uv),
|
|
|
ip_uv = VALUES(ip_uv),
|
|
|
avg_stay_ms = VALUES(avg_stay_ms),
|
|
|
bounce_rate = VALUES(bounce_rate),
|
|
|
search_count = VALUES(search_count),
|
|
|
download_count = VALUES(download_count),
|
|
|
updated_at = NOW()
|
|
|
""";
|
|
|
private const string SelectDailyByDateSql =
|
|
|
"""
|
|
|
SELECT stat_date AS StatDate, pv AS Pv, uv AS Uv, ip_uv AS IpUv, avg_stay_ms AS AvgStayMs,
|
|
|
bounce_rate AS BounceRate, search_count AS SearchCount, download_count AS DownloadCount,
|
|
|
created_at AS CreatedAt, updated_at AS UpdatedAt
|
|
|
FROM hw_web_visit_daily
|
|
|
WHERE stat_date = @statDate
|
|
|
""";
|
|
|
|
|
|
/// <summary>
|
|
|
/// 允许的事件类型集合。
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - HashSet<T> 哈希集合】
|
|
|
/// HashSet 适合做"是否存在"判断，查找效率通常比 List 更高。
|
|
|
///
|
|
|
/// 为什么用 HashSet？
|
|
|
/// - Contains 方法是 O(1) 时间复杂度
|
|
|
/// - List 的 Contains 是 O(n) 时间复杂度
|
|
|
///
|
|
|
/// StringComparer.OrdinalIgnoreCase 参数：
|
|
|
/// - 忽略大小写比较
|
|
|
/// - "page_view" 和 "PAGE_VIEW" 被视为相同
|
|
|
/// </para>
|
|
|
/// <para>
|
|
|
/// 【业务说明】
|
|
|
/// 只允许预定义的事件类型，避免脏数据进入统计表：
|
|
|
/// - page_view：页面浏览
|
|
|
/// - page_leave：离开页面
|
|
|
/// - search_submit：提交搜索
|
|
|
/// - download_click：点击下载
|
|
|
/// - contact_submit：提交联系表单
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
private static readonly HashSet<string> AllowedEvents = new(StringComparer.OrdinalIgnoreCase)
|
|
|
{
|
|
|
"page_view", "page_leave", "search_submit", "download_click", "contact_submit"
|
|
|
};
|
|
|
|
|
|
/// <summary>
|
|
|
/// MyBatis 执行器（依赖注入）。
|
|
|
/// </summary>
|
|
|
private readonly HwPortalMyBatisExecutor _executor;
|
|
|
private readonly ISqlSugarClient _db;
|
|
|
|
|
|
/// <summary>
|
|
|
/// 日志记录器（依赖注入）。
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - ILogger<T> 泛型日志接口】
|
|
|
/// ILogger<HwAnalyticsService> 是带类别的日志器：
|
|
|
/// - 日志会自动包含类名前缀
|
|
|
/// - 便于筛选特定类的日志
|
|
|
///
|
|
|
/// 对比 Java：
|
|
|
/// Java: private static final Logger logger = LoggerFactory.getLogger(HwAnalyticsService.class);
|
|
|
/// C#: private readonly ILogger<HwAnalyticsService> _logger;
|
|
|
///
|
|
|
/// C# 通过 DI 注入，更易于测试和配置。
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
private readonly ILogger<HwAnalyticsService> _logger;
|
|
|
|
|
|
/// <summary>
|
|
|
/// 构造函数（依赖注入）。
|
|
|
/// </summary>
|
|
|
/// <param name="executor">MyBatis 执行器</param>
|
|
|
/// <param name="logger">日志记录器</param>
|
|
|
public HwAnalyticsService(HwPortalMyBatisExecutor executor, ISqlSugarClient db, ILogger<HwAnalyticsService> logger)
|
|
|
{
|
|
|
_executor = executor;
|
|
|
_db = db;
|
|
|
_logger = logger;
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 收集访问事件。
|
|
|
/// <para>
|
|
|
/// 【处理流程】
|
|
|
/// 1. 校验事件类型是否合法
|
|
|
/// 2. 归一化字段值（去除空白、截断长度）
|
|
|
/// 3. 解析 User-Agent 获取设备信息
|
|
|
/// 4. 对 IP 地址进行哈希处理
|
|
|
/// 5. 写入明细事件表
|
|
|
/// 6. 刷新日报统计
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="request">事件请求</param>
|
|
|
/// <param name="requestIp">请求 IP</param>
|
|
|
/// <param name="requestUserAgent">请求 User-Agent</param>
|
|
|
public async Task Collect(AnalyticsCollectRequest request, string requestIp, string requestUserAgent)
|
|
|
{
|
|
|
if (request == null)
|
|
|
{
|
|
|
// 【Furion 异常处理】
|
|
|
// Oh.Oh("消息") 是 Furion 框架的异常抛出方式：
|
|
|
// - 自动包装成友好的错误响应
|
|
|
// - 支持多语言
|
|
|
// - 自动记录日志
|
|
|
//
|
|
|
// 对比 Java：
|
|
|
// Java: throw new BusinessException("请求体不能为空");
|
|
|
throw Oops.Oh("请求体不能为空");
|
|
|
}
|
|
|
|
|
|
// 先校验事件类型是否合法，避免脏数据进入统计表。
|
|
|
string eventType = NormalizeText(request.EventType, 32);
|
|
|
if (!AllowedEvents.Contains(eventType))
|
|
|
{
|
|
|
throw Oops.Oh("不支持的事件类型");
|
|
|
}
|
|
|
|
|
|
// 【对象初始化器】
|
|
|
// 对象初始化时统一做字段归一化和长度裁剪。
|
|
|
// new HwWebVisitEvent { ... } 是对象初始化器语法。
|
|
|
HwWebVisitEvent entity = new()
|
|
|
{
|
|
|
EventType = eventType,
|
|
|
VisitorId = RequireText(request.VisitorId, 64, "visitorId不能为空"),
|
|
|
SessionId = RequireText(request.SessionId, 64, "sessionId不能为空"),
|
|
|
Path = RequireText(request.Path, 500, "path不能为空"),
|
|
|
Referrer = NormalizeText(request.Referrer, 500),
|
|
|
UtmSource = NormalizeText(request.UtmSource, 128),
|
|
|
UtmMedium = NormalizeText(request.UtmMedium, 128),
|
|
|
UtmCampaign = NormalizeText(request.UtmCampaign, 128),
|
|
|
Keyword = NormalizeText(request.Keyword, 128),
|
|
|
StayMs = NormalizeStayMs(request.StayMs),
|
|
|
EventTime = ResolveEventTime(request.EventTime)
|
|
|
};
|
|
|
|
|
|
// Why：优先用前端上报的 ua；如果前端没传，就退回请求头里的 User-Agent。
|
|
|
string ua = NormalizeText(string.IsNullOrWhiteSpace(request.Ua) ? requestUserAgent : request.Ua, 500);
|
|
|
|
|
|
// 【User-Agent 解析】
|
|
|
// UAParser 是一个现成库，用来从 User-Agent 字符串里拆出浏览器、系统等信息。
|
|
|
// Parser.GetDefault() 获取默认解析器。
|
|
|
// Parse(ua) 返回 ClientInfo 对象，包含：
|
|
|
// - UA：浏览器信息
|
|
|
// - OS：操作系统信息
|
|
|
// - Device：设备信息
|
|
|
ClientInfo client = Parser.GetDefault().Parse(ua ?? string.Empty);
|
|
|
entity.Ua = ua;
|
|
|
|
|
|
// 【null 合并运算符 ??】
|
|
|
// 如果前端传了 Browser，用前端的值；否则用解析器的值。
|
|
|
entity.Browser = NormalizeText(string.IsNullOrWhiteSpace(request.Browser) ? client.UA.Family : request.Browser, 64);
|
|
|
entity.Os = NormalizeText(string.IsNullOrWhiteSpace(request.Os) ? client.OS.Family : request.Os, 64);
|
|
|
entity.Device = NormalizeText(string.IsNullOrWhiteSpace(request.Device) ? DetectDevice(ua) : request.Device, 64);
|
|
|
entity.IpHash = BuildIpHash(requestIp);
|
|
|
|
|
|
// 先写明细事件，再刷新日报统计。
|
|
|
// 回滚到 XML 方案时可直接恢复：
|
|
|
// await _executor.InsertReturnIdentityAsync(Mapper, "insertVisitEvent", entity);
|
|
|
await _db.Ado.ExecuteCommandAsync(InsertVisitEventSql, BuildParameters(entity));
|
|
|
await RefreshDailyStat(entity.EventTime?.Date ?? DateTime.Now.Date);
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 获取仪表盘统计数据。
|
|
|
/// <para>
|
|
|
/// 【返回数据】
|
|
|
/// - PV：页面浏览量
|
|
|
/// - UV：独立访客数
|
|
|
/// - IP UV：独立 IP 数
|
|
|
/// - 跳出率：只浏览一页的会话占比
|
|
|
/// - 热门页面排行
|
|
|
/// - 搜索关键词排行
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="statDate">统计日期</param>
|
|
|
/// <param name="rankLimit">排行条数限制</param>
|
|
|
/// <returns>仪表盘数据</returns>
|
|
|
public async Task<AnalyticsDashboardDTO> GetDashboard(DateTime? statDate, int? rankLimit)
|
|
|
{
|
|
|
// 【DateTime.Date 属性】
|
|
|
// .Date 会把时间截断到"当天 00:00:00"。
|
|
|
// 例如：2024-01-15 14:30:00 → 2024-01-15 00:00:00
|
|
|
DateTime targetDate = (statDate ?? DateTime.Now).Date;
|
|
|
int topN = NormalizeRankLimit(rankLimit);
|
|
|
|
|
|
// 先刷新统计，确保数据最新。
|
|
|
await RefreshDailyStat(targetDate);
|
|
|
|
|
|
// 【查询日报数据】
|
|
|
// QuerySingleAsync<T> 查询单条记录。
|
|
|
// 如果查询结果为空，返回 null。
|
|
|
// 回滚到 XML 方案时可直接恢复：
|
|
|
// HwWebVisitDaily daily = await _executor.QuerySingleAsync<HwWebVisitDaily>(Mapper, "selectDailyByDate", new { statDate = targetDate });
|
|
|
HwWebVisitDaily daily = await QuerySingleOrDefaultAsync<HwWebVisitDaily>(SelectDailyByDateSql, new { statDate = targetDate });
|
|
|
|
|
|
// 【null 合并运算符 ??】
|
|
|
// daily?.Pv ?? 0 表示：
|
|
|
// - 如果 daily 为 null，返回 0
|
|
|
// - 如果 daily.Pv 为 null，返回 0
|
|
|
// - 否则返回 daily.Pv
|
|
|
AnalyticsDashboardDTO dashboard = new()
|
|
|
{
|
|
|
StatDate = targetDate.ToString("yyyy-MM-dd"),
|
|
|
Pv = daily?.Pv ?? 0,
|
|
|
Uv = daily?.Uv ?? 0,
|
|
|
IpUv = daily?.IpUv ?? 0,
|
|
|
AvgStayMs = daily?.AvgStayMs ?? 0,
|
|
|
BounceRate = daily?.BounceRate ?? 0,
|
|
|
SearchCount = daily?.SearchCount ?? 0,
|
|
|
DownloadCount = daily?.DownloadCount ?? 0,
|
|
|
// 回滚到 XML 方案时可直接恢复：
|
|
|
// EntryPages = await _executor.QueryListAsync<AnalyticsRankItemDTO>(Mapper, "selectTopEntryPages", new { statDate = targetDate, limit = topN }),
|
|
|
EntryPages = await QueryListAsync<AnalyticsRankItemDTO>(SelectTopEntryPagesSql, new { statDate = targetDate, limit = topN }),
|
|
|
// 回滚到 XML 方案时可直接恢复：
|
|
|
// HotPages = await _executor.QueryListAsync<AnalyticsRankItemDTO>(Mapper, "selectTopHotPages", new { statDate = targetDate, limit = topN }),
|
|
|
HotPages = await QueryListAsync<AnalyticsRankItemDTO>(SelectTopHotPagesSql, new { statDate = targetDate, limit = topN }),
|
|
|
// 回滚到 XML 方案时可直接恢复：
|
|
|
// HotKeywords = await _executor.QueryListAsync<AnalyticsRankItemDTO>(Mapper, "selectTopKeywords", new { statDate = targetDate, limit = topN })
|
|
|
HotKeywords = await QueryListAsync<AnalyticsRankItemDTO>(SelectTopKeywordsSql, new { statDate = targetDate, limit = topN })
|
|
|
};
|
|
|
return dashboard;
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 刷新日报统计。
|
|
|
/// <para>
|
|
|
/// 【聚合逻辑】
|
|
|
/// 从明细表聚合以下指标：
|
|
|
/// - PV：页面浏览次数
|
|
|
/// - UV：独立访客数（按 visitorId 去重）
|
|
|
/// - IP UV：独立 IP 数（按 ipHash 去重）
|
|
|
/// - 平均停留时长
|
|
|
/// - 搜索次数
|
|
|
/// - 下载次数
|
|
|
/// - 跳出率
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="statDate">统计日期</param>
|
|
|
public async Task RefreshDailyStat(DateTime? statDate)
|
|
|
{
|
|
|
// 日报统计的核心做法：
|
|
|
// 先从明细表聚合出 pv / uv / ip_uv / 搜索次数等指标，再 upsert 到日报表。
|
|
|
DateTime targetDate = (statDate ?? DateTime.Now).Date;
|
|
|
|
|
|
// 【查询聚合值】
|
|
|
long pv = await QueryLong("countEventByType", new { statDate = targetDate, eventType = "page_view" });
|
|
|
long uv = await QueryLong("countDistinctVisitor", new { statDate = targetDate });
|
|
|
long ipUv = await QueryLong("countDistinctIp", new { statDate = targetDate });
|
|
|
long avgStayMs = await QueryLong("avgStayMs", new { statDate = targetDate });
|
|
|
long searchCount = await QueryLong("countEventByType", new { statDate = targetDate, eventType = "search_submit" });
|
|
|
long downloadCount = await QueryLong("countEventByType", new { statDate = targetDate, eventType = "download_click" });
|
|
|
long sessionCount = await QueryLong("countDistinctSessions", new { statDate = targetDate });
|
|
|
long singlePageSessions = await QueryLong("countSinglePageSessions", new { statDate = targetDate });
|
|
|
|
|
|
// 【跳出率计算】
|
|
|
double bounceRate = 0D;
|
|
|
if (sessionCount > 0)
|
|
|
{
|
|
|
// Why：跳出率 = 单页 session 数 / 总 session 数。
|
|
|
// Math.Round 四舍五入：
|
|
|
// - 第一个参数：要舍入的值
|
|
|
// - 第二个参数：保留小数位数
|
|
|
// - 第三个参数：舍入方式（AwayFromZero 表示四舍五入）
|
|
|
bounceRate = Math.Round(singlePageSessions * 100.0D / sessionCount, 2, MidpointRounding.AwayFromZero);
|
|
|
}
|
|
|
|
|
|
HwWebVisitDaily daily = new()
|
|
|
{
|
|
|
StatDate = targetDate,
|
|
|
Pv = pv,
|
|
|
Uv = uv,
|
|
|
IpUv = ipUv,
|
|
|
AvgStayMs = avgStayMs,
|
|
|
BounceRate = bounceRate,
|
|
|
SearchCount = searchCount,
|
|
|
DownloadCount = downloadCount
|
|
|
};
|
|
|
|
|
|
// 【Upsert 操作】
|
|
|
// upsert = update + insert
|
|
|
// 如果记录存在，更新；不存在，插入。
|
|
|
// 回滚到 XML 方案时可直接恢复：
|
|
|
// await _executor.ExecuteAsync(Mapper, "upsertDaily", daily);
|
|
|
await _db.Ado.ExecuteCommandAsync(UpsertDailySql, BuildParameters(daily));
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 查询单个长整数值。
|
|
|
/// </summary>
|
|
|
/// <param name="statementId">SQL 语句 ID</param>
|
|
|
/// <param name="parameter">参数</param>
|
|
|
/// <returns>查询结果（默认 0）</returns>
|
|
|
private async Task<long> QueryLong(string statementId, object parameter)
|
|
|
{
|
|
|
// 回滚到 XML 方案时可直接恢复：
|
|
|
// long? value = await _executor.QuerySingleAsync<long?>(Mapper, statementId, parameter);
|
|
|
string sql = statementId switch
|
|
|
{
|
|
|
"countEventByType" => CountEventByTypeSql,
|
|
|
"countDistinctVisitor" => CountDistinctVisitorSql,
|
|
|
"countDistinctIp" => CountDistinctIpSql,
|
|
|
"avgStayMs" => AvgStayMsSql,
|
|
|
"countDistinctSessions" => CountDistinctSessionsSql,
|
|
|
"countSinglePageSessions" => CountSinglePageSessionsSql,
|
|
|
_ => throw Oops.Oh($"不支持的统计语句：{statementId}")
|
|
|
};
|
|
|
List<long?> rows = await _db.Ado.SqlQueryAsync<long?>(sql, BuildParameters(parameter));
|
|
|
return rows.FirstOrDefault() ?? 0L;
|
|
|
}
|
|
|
|
|
|
private async Task<T> QuerySingleOrDefaultAsync<T>(string sql, object parameter)
|
|
|
{
|
|
|
List<T> rows = await _db.Ado.SqlQueryAsync<T>(sql, BuildParameters(parameter));
|
|
|
return rows.FirstOrDefault();
|
|
|
}
|
|
|
|
|
|
private Task<List<T>> QueryListAsync<T>(string sql, object parameter)
|
|
|
{
|
|
|
return _db.Ado.SqlQueryAsync<T>(sql, BuildParameters(parameter));
|
|
|
}
|
|
|
|
|
|
private static SugarParameter[] BuildParameters(object parameter)
|
|
|
{
|
|
|
if (parameter == null)
|
|
|
{
|
|
|
return Array.Empty<SugarParameter>();
|
|
|
}
|
|
|
|
|
|
if (parameter is SugarParameter[] sugarParameters)
|
|
|
{
|
|
|
return sugarParameters;
|
|
|
}
|
|
|
|
|
|
if (parameter is IEnumerable<SugarParameter> sugarParameterEnumerable)
|
|
|
{
|
|
|
return sugarParameterEnumerable.ToArray();
|
|
|
}
|
|
|
|
|
|
List<SugarParameter> parameters = new();
|
|
|
foreach (PropertyInfo property in parameter.GetType().GetProperties(BindingFlags.Instance | BindingFlags.Public))
|
|
|
{
|
|
|
object value = property.GetValue(parameter);
|
|
|
parameters.Add(new SugarParameter($"@{property.Name}", value ?? DBNull.Value));
|
|
|
}
|
|
|
|
|
|
return parameters.ToArray();
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 校验并获取必填文本。
|
|
|
/// <para>
|
|
|
/// 【处理逻辑】
|
|
|
/// 1. 调用 NormalizeText 归一化
|
|
|
/// 2. 如果结果为空，抛出异常
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="text">输入文本</param>
|
|
|
/// <param name="maxLen">最大长度</param>
|
|
|
/// <param name="emptyMessage">空值错误消息</param>
|
|
|
/// <returns>归一化后的文本</returns>
|
|
|
private static string RequireText(string text, int maxLen, string emptyMessage)
|
|
|
{
|
|
|
string normalized = NormalizeText(text, maxLen);
|
|
|
if (string.IsNullOrWhiteSpace(normalized))
|
|
|
{
|
|
|
throw Oops.Oh(emptyMessage);
|
|
|
}
|
|
|
|
|
|
return normalized;
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 归一化文本（去除空白、截断长度）。
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - 字符串截取】
|
|
|
/// normalized[..maxLen] 是范围操作符：
|
|
|
// - 从索引 0 开始
|
|
|
// - 到索引 maxLen 结束（不含）
|
|
|
// - 等价于 normalized.Substring(0, maxLen)
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="text">输入文本</param>
|
|
|
/// <param name="maxLen">最大长度</param>
|
|
|
/// <returns>归一化后的文本</returns>
|
|
|
private static string NormalizeText(string text, int maxLen)
|
|
|
{
|
|
|
// Trim() 用于去掉首尾空白。
|
|
|
string normalized = text?.Trim();
|
|
|
if (string.IsNullOrWhiteSpace(normalized))
|
|
|
{
|
|
|
return null;
|
|
|
}
|
|
|
|
|
|
// 【范围操作符】
|
|
|
// normalized[..maxLen] 表示从开始到 maxLen 位置。
|
|
|
// 如果长度超过 maxLen，截断；否则返回原字符串。
|
|
|
return normalized.Length > maxLen ? normalized[..maxLen] : normalized;
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 归一化停留时长。
|
|
|
/// <para>
|
|
|
/// 【处理逻辑】
|
|
|
/// - 负值转为 0
|
|
|
/// - 超过 7 天的值限制为 7 天（防止异常数据）
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="stayMs">停留时长（毫秒）</param>
|
|
|
/// <returns>归一化后的时长</returns>
|
|
|
private static long? NormalizeStayMs(long? stayMs)
|
|
|
{
|
|
|
// 【可空值类型】
|
|
|
// long? 是可空的长整型，可以是 null 或 long 值。
|
|
|
// .HasValue 判断是否有值。
|
|
|
// .Value 获取值（如果有值）。
|
|
|
if (!stayMs.HasValue)
|
|
|
{
|
|
|
return null;
|
|
|
}
|
|
|
|
|
|
if (stayMs.Value < 0)
|
|
|
{
|
|
|
return 0L;
|
|
|
}
|
|
|
|
|
|
// 【限制最大值】
|
|
|
// 7L * 24 * 3600 * 1000 = 7 天的毫秒数
|
|
|
// Math.Min 取较小值，防止异常数据。
|
|
|
return Math.Min(stayMs.Value, 7L * 24 * 3600 * 1000);
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 解析事件时间。
|
|
|
/// <para>
|
|
|
/// 【Unix 时间戳转换】
|
|
|
/// 前端传的是 Unix 毫秒时间戳，这里转换成本地 DateTime。
|
|
|
///
|
|
|
/// DateTimeOffset.FromUnixTimeMilliseconds：
|
|
|
/// - 把 Unix 毫秒时间戳转换为 DateTimeOffset
|
|
|
/// - .LocalDateTime 获取本地时间
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="timestamp">Unix 毫秒时间戳</param>
|
|
|
/// <returns>本地时间</returns>
|
|
|
private DateTime ResolveEventTime(long? timestamp)
|
|
|
{
|
|
|
if (!timestamp.HasValue || timestamp.Value <= 0)
|
|
|
{
|
|
|
return DateTime.Now;
|
|
|
}
|
|
|
|
|
|
try
|
|
|
{
|
|
|
// 前端传的是 Unix 毫秒时间戳，这里转换成本地 DateTime。
|
|
|
return DateTimeOffset.FromUnixTimeMilliseconds(timestamp.Value).LocalDateTime;
|
|
|
}
|
|
|
catch (Exception ex)
|
|
|
{
|
|
|
// 【结构化日志】
|
|
|
// _logger.LogWarning(ex, "消息 {属性名}", 属性值)
|
|
|
// 属性名会被自动替换为属性值，便于日志查询。
|
|
|
//
|
|
|
// 对比 Java：
|
|
|
// Java: logger.warn("invalid eventTime: {}", timestamp, ex);
|
|
|
_logger.LogWarning(ex, "invalid eventTime: {Timestamp}", timestamp);
|
|
|
return DateTime.Now;
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 检测设备类型。
|
|
|
/// <para>
|
|
|
/// 【检测逻辑】
|
|
|
/// - 包含 ipad/tablet：平板
|
|
|
/// - 包含 mobile/android/iphone：手机
|
|
|
/// - 其他：桌面
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="ua">User-Agent 字符串</param>
|
|
|
/// <returns>设备类型</returns>
|
|
|
private static string DetectDevice(string ua)
|
|
|
{
|
|
|
// ToLowerInvariant() 转换为小写（不依赖区域设置）。
|
|
|
string text = (ua ?? string.Empty).ToLowerInvariant();
|
|
|
if (text.Contains("ipad", StringComparison.Ordinal) || text.Contains("tablet", StringComparison.Ordinal))
|
|
|
{
|
|
|
return "Tablet";
|
|
|
}
|
|
|
|
|
|
if (text.Contains("mobile", StringComparison.Ordinal) || text.Contains("android", StringComparison.Ordinal) || text.Contains("iphone", StringComparison.Ordinal))
|
|
|
{
|
|
|
return "Mobile";
|
|
|
}
|
|
|
|
|
|
return "Desktop";
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 构建 IP 哈希值。
|
|
|
/// <para>
|
|
|
/// 【隐私保护】
|
|
|
/// Why：出于隐私和合规考虑，不直接存明文 IP，而是落哈希值。
|
|
|
///
|
|
|
/// 哈希算法：SHA256
|
|
|
/// 加盐值：hw-portal-analytics（防止彩虹表攻击）
|
|
|
/// </para>
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - using 语句】
|
|
|
/// using 语句确保资源正确释放：
|
|
|
/// - SHA256 实现了 IDisposable 接口
|
|
|
/// - 离开 using 块时自动调用 Dispose()
|
|
|
///
|
|
|
/// 对比 Java：
|
|
|
/// Java 用 try-with-resources：
|
|
|
/// try (MessageDigest md = MessageDigest.getInstance("SHA-256")) {
|
|
|
/// ...
|
|
|
/// }
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="ip">IP 地址</param>
|
|
|
/// <returns>哈希值（十六进制字符串）</returns>
|
|
|
private static string BuildIpHash(string ip)
|
|
|
{
|
|
|
string safeIp = string.IsNullOrWhiteSpace(ip) ? "unknown" : ip;
|
|
|
try
|
|
|
{
|
|
|
// 【SHA256 哈希】
|
|
|
using System.Security.Cryptography.SHA256 sha256 = System.Security.Cryptography.SHA256.Create();
|
|
|
|
|
|
// ComputeHash 计算字节数组的哈希值。
|
|
|
// Encoding.UTF8.GetBytes 把字符串转换为字节数组。
|
|
|
byte[] hash = sha256.ComputeHash(Encoding.UTF8.GetBytes($"{safeIp}|hw-portal-analytics"));
|
|
|
|
|
|
// Convert.ToHexString 把字节数组转换为十六进制字符串。
|
|
|
// ToLowerInvariant() 转换为小写。
|
|
|
return Convert.ToHexString(hash).ToLowerInvariant();
|
|
|
}
|
|
|
catch
|
|
|
{
|
|
|
// 【降级处理】
|
|
|
// 如果 SHA256 失败，使用 GetHashCode 作为降级方案。
|
|
|
// GetHashCode 返回 int，ToString("x") 转换为十六进制。
|
|
|
return safeIp.GetHashCode().ToString("x", CultureInfo.InvariantCulture);
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/// <summary>
|
|
|
/// 归一化排行条数限制。
|
|
|
/// <para>
|
|
|
/// 【处理逻辑】
|
|
|
/// - 默认 10 条
|
|
|
/// - 最大 50 条
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="rankLimit">排行条数</param>
|
|
|
/// <returns>归一化后的条数</returns>
|
|
|
private static int NormalizeRankLimit(int? rankLimit)
|
|
|
{
|
|
|
if (!rankLimit.HasValue || rankLimit.Value <= 0)
|
|
|
{
|
|
|
return 10;
|
|
|
}
|
|
|
|
|
|
return Math.Min(rankLimit.Value, 50);
|
|
|
}
|
|
|
}
|