|
|
@@ -0,0 +1,522 @@
|
|
|
+# 埋点与统计表结构说明
|
|
|
+
|
|
|
+> 本文档说明平台埋点统计系统的 **表结构、分层关系、数据流向、关联键与查询口径**。
|
|
|
+> 与 [`前端埋点接入指南.md`](./前端埋点接入指南.md)（接入 API）配合使用。
|
|
|
+
|
|
|
+**文档版本**：v1.0
|
|
|
+**最后更新**：2026-06-17
|
|
|
+**DDL 来源**：`alien-entity/src/main/resources/db/migration/analytics_schema.sql`（新环境）
|
|
|
+**旧环境升级**：`analytics_tables_dashboard_upgrade.sql`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 一、设计目标
|
|
|
+
|
|
|
+| 目标 | 实现方式 |
|
|
|
+|------|----------|
|
|
|
+| 原始行为可追溯 | 所有 scene 落 `analytics_event` 流水 |
|
|
|
+| 看板查询快 | 按自然日预聚合到 `analytics_daily_summary` |
|
|
|
+| 明细分页/下钻 | 用户/商家/内容等 `*_stat` 明细表 |
|
|
|
+| 当日准实时 | 埋点同步写 `*_today`，每小时跑批覆盖 |
|
|
|
+| 历史可查 | 零点归档到 `*_history`，保留 30 天 |
|
|
|
+
|
|
|
+**核心原则**：数据库层 **不设外键**；表之间通过 `user_id`、`merchant_id`、`content_type + content_id`、`stat_date`、`event_code` 等字段 **逻辑关联**。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 二、表清单总览
|
|
|
+
|
|
|
+共 **4 张基础表 + 12 张明细表（6 组 today/history）**。
|
|
|
+
|
|
|
+### 2.1 基础表（不参与 today/history 拆分）
|
|
|
+
|
|
|
+| 表名 | Java 实体 | 粒度 | 说明 |
|
|
|
+|------|-----------|------|------|
|
|
|
+| `analytics_event` | `AnalyticsEvent` | 每条埋点事件 | **原始日志**，所有统计的源头 |
|
|
|
+| `analytics_ai_request` | `AnalyticsAiRequest` | 每次 AI API 调用 | 响应耗时，不写 event 表 |
|
|
|
+| `analytics_daily_summary` | `AnalyticsDailySummary` | 每天 1 行 | 四页看板 KPI 宽表 |
|
|
|
+| `analytics_stat_job_log` | `AnalyticsStatJobLog` | 每次跑批任务 | 运维排查用 |
|
|
|
+
|
|
|
+### 2.2 明细表（today + history 成对）
|
|
|
+
|
|
|
+| 今日表 | 历史表 | Java 实体（today / history） | 唯一键 |
|
|
|
+|--------|--------|------------------------------|--------|
|
|
|
+| `analytics_user_stat_today` | `analytics_user_stat_history` | `AnalyticsUserStatToday` / `AnalyticsUserStat` | `user_id` / `(stat_date, user_id)` |
|
|
|
+| `analytics_merchant_stat_today` | `analytics_merchant_stat_history` | `AnalyticsMerchantStatToday` / `AnalyticsMerchantStat` | `merchant_id` / `(stat_date, merchant_id)` |
|
|
|
+| `analytics_content_stat_today` | `analytics_content_stat_history` | `AnalyticsContentStat` / `AnalyticsContentStatHistory` | `(content_type, content_id)` / `(stat_date, content_type, content_id)` |
|
|
|
+| `analytics_category_daily_today` | `analytics_category_daily_history` | `AnalyticsCategoryDailyToday` / `AnalyticsCategoryDaily` | `business_category` / `(stat_date, business_category)` |
|
|
|
+| `analytics_ai_chat_stat_today` | `analytics_ai_chat_stat_history` | `AnalyticsAiChatStat` / `AnalyticsAiChatStatHistory` | `chat_id` / `(stat_date, chat_id)` |
|
|
|
+| `analytics_report_record_today` | `analytics_report_record_history` | `AnalyticsReportRecord` / `AnalyticsReportRecordHistory` | `report_id` / `(stat_date, report_id)` |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 三、分层架构
|
|
|
+
|
|
|
+```
|
|
|
+┌─────────────────────────────────────────────────────────────────┐
|
|
|
+│ L0 接入层 POST /analytics/front/* + POST /analytics/detail/* │
|
|
|
+└───────────────────────────────┬─────────────────────────────────┘
|
|
|
+ │
|
|
|
+ ┌───────────────────────┼───────────────────────┐
|
|
|
+ ▼ ▼ ▼
|
|
|
+┌───────────────┐ ┌─────────────────┐ ┌──────────────────┐
|
|
|
+│ analytics_event│ │ analytics_ai_ │ │ *_today 明细表 │
|
|
|
+│ （事件流水） │ │ request │ │ （当日增量/快照） │
|
|
|
+└───────┬───────┘ └────────┬────────┘ └────────┬─────────┘
|
|
|
+ │ │ │
|
|
|
+ │ POST /analytics/stat/calculate（定时/手动） │
|
|
|
+ ▼ ▼ ▼
|
|
|
+┌─────────────────────────────────────────────────────────────────┐
|
|
|
+│ L2 汇总层 analytics_daily_summary（按 stat_date 一行 KPI） │
|
|
|
+│ L1 明细层 *_today 覆盖/补全 + 历史日写入 *_history（补跑时） │
|
|
|
+└───────────────────────────────┬─────────────────────────────────┘
|
|
|
+ │ 零点 analyticsArchiveDaily
|
|
|
+ ▼
|
|
|
+ *_history（stat_date=昨日，保留 30 天）
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+ GET /analytics/*/charts、/summary（报表读层）
|
|
|
+```
|
|
|
+
|
|
|
+### 3.1 三层职责
|
|
|
+
|
|
|
+| 层级 | 表 | 职责 |
|
|
|
+|------|-----|------|
|
|
|
+| **L0 原始** | `analytics_event`、`analytics_ai_request` | 保留完整行为流水；支持漏斗下钻、复杂去重、cohort 留存 |
|
|
|
+| **L1 明细** | `*_stat_*`、`*_daily_*`、`report_record_*` | 按用户/商家/内容/品类/会话/举报预聚合，支撑明细分页与 TOP 榜 |
|
|
|
+| **L2 汇总** | `analytics_daily_summary` | 按自然日一行，支撑看板 KPI 卡片与趋势图 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 四、数据生命周期
|
|
|
+
|
|
|
+### 4.1 实时写入（埋点服务）
|
|
|
+
|
|
|
+**入口**：`AnalyticsTrackServiceImpl`
|
|
|
+**路径**：`POST /analytics/front/report`（及 register/login/logout/heartbeat 等专用接口）
|
|
|
+
|
|
|
+每次成功上报的典型步骤：
|
|
|
+
|
|
|
+1. 将 `scene` 映射为 `event_code`，插入 `analytics_event`（`event_id` 幂等）
|
|
|
+2. 按场景 **同步更新** 对应 `*_today` 表（非全部 scene 都会写明细，见下表）
|
|
|
+
|
|
|
+| scene / 接口 | event_code | 同步写明细 |
|
|
|
+|--------------|------------|------------|
|
|
|
+| `APP_LAUNCH` 等通用 report | `user.launch` 等 | 部分场景仅写 event |
|
|
|
+| `USER_HEARTBEAT` / heartbeat | `user.heartbeat` | `user_stat_today`（last_active_time、在线时长） |
|
|
|
+| `APP_REGISTER` / user/register | `user.register` | `user_stat_today` |
|
|
|
+| `USER_LOGIN` / `USER_LOGOUT` | `user.login` / `user.logout` | `user_stat_today` |
|
|
|
+| `MERCHANT_VIEW` / merchant/view | `merchant.view` | `merchant_stat_today`（visit_uv/pv） |
|
|
|
+| `CONTENT_INTERACT` | `content.interact` | `content_stat_today`（互动计数） |
|
|
|
+| `AUDIT_*` | `audit.*` | `content_stat_today`（审核状态） |
|
|
|
+| `REPORT_SUBMIT` / `REPORT_HANDLE` | `report.*` | `report_record_today` |
|
|
|
+| `AI_CHAT_END` | `ai.chat.end` | event + 建议 `/detail/ai-chat` 写 `ai_chat_stat_today` |
|
|
|
+| `POST /analytics/front/ai-request` | — | 仅 `analytics_ai_request` |
|
|
|
+| `POST /analytics/detail/*` | 可选 | 直接 upsert 对应 `*_today` |
|
|
|
+
|
|
|
+**明细路由**：`AnalyticsDetailStoreServiceImpl` 根据 `statDate` 是否为当天，自动选择写 `*_today` 或 `*_history`。
|
|
|
+
|
|
|
+### 4.2 定时统计（跑批服务）
|
|
|
+
|
|
|
+**入口**：`AnalyticsStatisticsServiceImpl.calculate(statDate, scope, triggerType)`
|
|
|
+**触发**：
|
|
|
+
|
|
|
+| 方式 | 接口 / 任务 |
|
|
|
+|------|-------------|
|
|
|
+| 手动 | `POST /analytics/stat/calculate` |
|
|
|
+| 每小时 | XXL-JOB `analyticsCalculateTodayHourly`（建议 cron: `5 5 * * * ?`） |
|
|
|
+| 前日完整 | XXL-JOB `analyticsCalculateYesterdayDaily`（`0 0 2 * * ?`） |
|
|
|
+| 次日留存 | XXL-JOB `analyticsCalculateRetention`（`0 0 3 * * ?`） |
|
|
|
+
|
|
|
+**scope 与任务对应**：
|
|
|
+
|
|
|
+| scope | 方法 | 输出表 |
|
|
|
+|-------|------|--------|
|
|
|
+| `USER` | `calculateUserStat` | `user_stat_*` |
|
|
|
+| `MERCHANT` | `calculateMerchantStat` | `merchant_stat_*` |
|
|
|
+| `MERCHANT` | `calculateCategoryDaily` | `category_daily_*` |
|
|
|
+| `CONTENT` | `calculateContentStat` | `content_stat_*` |
|
|
|
+| `AI_CHAT` | `calculateAiChatStat` | （明细主要由 detail 接口维护） |
|
|
|
+| `DAILY` | `calculateDailySummary` | `analytics_daily_summary` |
|
|
|
+| `ALL` | 以上全部 | — |
|
|
|
+
|
|
|
+跑批 **以 `analytics_event` 为主数据源**，对明细表做 **覆盖/补全**（非简单 +1 累加），再汇总到 `daily_summary`。
|
|
|
+
|
|
|
+### 4.3 零点归档
|
|
|
+
|
|
|
+**入口**：`AnalyticsArchiveServiceImpl.archiveYesterday()`
|
|
|
+**任务**：XXL-JOB `analyticsArchiveDaily`（`0 0 0 * * ?`）
|
|
|
+
|
|
|
+```
|
|
|
+1. INSERT *_history ← SELECT * FROM *_today（stat_date = 昨日）
|
|
|
+2. DELETE *_history WHERE stat_date < 今天 - 30 天
|
|
|
+3. TRUNCATE *_today
|
|
|
+```
|
|
|
+
|
|
|
+**不归档的表**：
|
|
|
+
|
|
|
+- `analytics_event`（需单独制定清理/分区策略）
|
|
|
+- `analytics_ai_request`
|
|
|
+- `analytics_daily_summary`（按 `stat_date` 长期保留）
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 五、关联键与实体关系
|
|
|
+
|
|
|
+### 5.1 核心维度
|
|
|
+
|
|
|
+| 维度 | 字段 | 出现位置 |
|
|
|
+|------|------|----------|
|
|
|
+| 用户 | `user_id` | event、user_stat、ai_chat_stat、report_record |
|
|
|
+| 商家 | `merchant_id` | event、merchant_stat |
|
|
|
+| 内容 | `content_type` + `content_id`（event 中为 `target_id`） | event、content_stat、report_record |
|
|
|
+| 自然日 | `stat_date` | history 表 daily_summary |
|
|
|
+| 经营品类 | `business_category` (1–7) | event、category_daily |
|
|
|
+| 店铺类型 | `shop_type` (1–3) | event、merchant_stat |
|
|
|
+| 举报单 | `report_id`（通常 = 提交时 `event_id`） | report_record |
|
|
|
+
|
|
|
+### 5.2 ER 关系（逻辑）
|
|
|
+
|
|
|
+```
|
|
|
+analytics_event
|
|
|
+ ├─ user_id ──────────► analytics_user_stat_*.user_id
|
|
|
+ ├─ merchant_id ──────► analytics_merchant_stat_*.merchant_id
|
|
|
+ ├─ content_type + target_id ► analytics_content_stat_*.content_type + content_id
|
|
|
+ ├─ business_category ► analytics_category_daily_*.business_category
|
|
|
+ └─ event_time 按日聚合 ► analytics_daily_summary.stat_date
|
|
|
+
|
|
|
+analytics_ai_request.created_time 按日聚合 ► daily_summary.ai_request_count / 响应时长
|
|
|
+
|
|
|
+analytics_report_record ◄── REPORT_SUBMIT/HANDLE（report_id 关联）
|
|
|
+```
|
|
|
+
|
|
|
+### 5.3 today / history 查询约定
|
|
|
+
|
|
|
+报表 Mapper 普遍使用 **UNION ALL**：
|
|
|
+
|
|
|
+```sql
|
|
|
+-- 历史段
|
|
|
+SELECT ... FROM analytics_xxx_stat_history
|
|
|
+ WHERE stat_date >= #{startDate} AND stat_date <= #{endDate}
|
|
|
+UNION ALL
|
|
|
+-- 查询区间包含「今天」时追加
|
|
|
+SELECT ... FROM analytics_xxx_stat_today
|
|
|
+ WHERE #{endDate} >= CURDATE() AND #{startDate} <= CURDATE()
|
|
|
+```
|
|
|
+
|
|
|
+**含义**：
|
|
|
+
|
|
|
+- `*_today`：当前自然日内的 **累计快照**（每个实体最多 1 行）
|
|
|
+- `*_history`：每个 `stat_date` 一行历史快照（保留 30 天）
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 六、scene → event_code → 表 映射
|
|
|
+
|
|
|
+前端传 `scene`，后端枚举见 `AnalyticsScene`，落库 `event_code` 见 `AnalyticsEventCode`。
|
|
|
+
|
|
|
+### 6.1 用户域
|
|
|
+
|
|
|
+| scene | event_code | 主要影响 |
|
|
|
+|-------|------------|----------|
|
|
|
+| `APP_LAUNCH` | `user.launch` | event → DAU、`user_stat` |
|
|
|
+| `APP_REGISTER` | `user.register` | event → 新增用户、`user_stat.is_new_user` |
|
|
|
+| `REGISTER_PAGE` | `user.register.page` | 注册漏斗 |
|
|
|
+| `REGISTER_PHONE` | `user.register.phone` | 注册漏斗 |
|
|
|
+| `REGISTER_OTP` | `user.register.otp` | 注册漏斗 |
|
|
|
+| `REGISTER_PASSWORD` | `user.register.password` | 注册漏斗 |
|
|
|
+| `USER_LOGIN` | `user.login` | event、`user_stat` |
|
|
|
+| `USER_LOGOUT` | `user.logout` | event、在线时长 |
|
|
|
+| `USER_HEARTBEAT` | `user.heartbeat` | event、`user_stat.last_active_time`、在线时长 |
|
|
|
+
|
|
|
+### 6.2 商家域
|
|
|
+
|
|
|
+| scene | event_code | 主要影响 |
|
|
|
+|-------|------------|----------|
|
|
|
+| `MERCHANT_EXPOSE` | `merchant.expose` | 漏斗曝光、`merchant_stat.expose_count` |
|
|
|
+| `MERCHANT_CLICK` | `merchant.click` | 漏斗点击 |
|
|
|
+| `MERCHANT_DETAIL` | `merchant.detail` | 漏斗详情 |
|
|
|
+| `MERCHANT_CONTACT` | `merchant.contact` | 漏斗电话/导航 |
|
|
|
+| `MERCHANT_VIEW` | `merchant.view` | 商家 UV、`merchant_stat.visit_uv/pv` |
|
|
|
+| `MERCHANT_VERIFY` | `merchant.verify` | 核销、转化率分母/分子 |
|
|
|
+| `MERCHANT_REVIEW` | `merchant.review` | 评价率 |
|
|
|
+| `PAY_SUCCESS` | `pay.success` | GMV、`merchant_stat.gmv`、转化率 |
|
|
|
+
|
|
|
+### 6.3 内容 / 审核 / 举报
|
|
|
+
|
|
|
+| scene | event_code | 主要影响 |
|
|
|
+|-------|------------|----------|
|
|
|
+| `CONTENT_PUBLISH` | `content.publish` | 发布数、`content_stat` |
|
|
|
+| `CONTENT_INTERACT` | `content.interact` | 互动数（`eventSubtype`: like/comment/share） |
|
|
|
+| `AUDIT_SUBMIT` | `audit.submit` | 审核提交 |
|
|
|
+| `AUDIT_PASS` | `audit.pass` | 审核通过 |
|
|
|
+| `AUDIT_REJECT` | `audit.reject` | 审核驳回 |
|
|
|
+| `REPORT_SUBMIT` | `report.submit` | `report_record`、举报率分母 |
|
|
|
+| `REPORT_HANDLE` | `report.handle` | `report_record.status`、举报率分子 |
|
|
|
+
|
|
|
+### 6.4 AI
|
|
|
+
|
|
|
+| scene | event_code | 主要影响 |
|
|
|
+|-------|------------|----------|
|
|
|
+| `AI_CHAT_START` | `ai.chat.start` | event |
|
|
|
+| `AI_CHAT_MESSAGE` | `ai.chat.message` | event |
|
|
|
+| `AI_CHAT_END` | `ai.chat.end` | 对话次数 KPI、`ai_chat_stat` |
|
|
|
+| （独立接口）ai-request | — | `analytics_ai_request` → 平均响应时间 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 七、`analytics_event` 字段说明
|
|
|
+
|
|
|
+| 字段 | 说明 | 典型用途 |
|
|
|
+|------|------|----------|
|
|
|
+| `event_id` | 幂等 UUID | 防重复上报 |
|
|
|
+| `event_code` | 事件编码 | 聚合分组 |
|
|
|
+| `event_subtype` | 子类型 | 互动 like/comment/share；审核 pass/reject；举报处理时传原 report_id |
|
|
|
+| `user_id` | 用户 | DAU、漏斗下钻 |
|
|
|
+| `merchant_id` | 商家 | 商家漏斗、GMV |
|
|
|
+| `target_id` | 目标 ID | 内容 ID、订单 ID |
|
|
|
+| `content_type` | 1动态 2打卡 3二手 | 内容维度 |
|
|
|
+| `business_category` | 1–7 经营品类 | 品类 GMV 分布 |
|
|
|
+| `shop_type` | 1–3 店铺类型 | 商家分类 |
|
|
|
+| `amount` | 金额（元） | GMV、客单价 |
|
|
|
+| `duration_ms` | 毫秒 | 心跳/会话时长 |
|
|
|
+| `device_type` / `channel` / `city` | 设备/渠道/城市 | 画像、地域 TOP10 |
|
|
|
+| `event_time` | 事件发生时间 | 划分 stat_date |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 八、`analytics_daily_summary` 字段血缘
|
|
|
+
|
|
|
+每行对应一个 `stat_date`（自然日），由 `calculateDailySummary` 写入。
|
|
|
+
|
|
|
+| 字段 | 计算口径（主要来源） |
|
|
|
+|------|---------------------|
|
|
|
+| `dau` | `COUNT(DISTINCT user_id)` @ event（当日活跃） |
|
|
|
+| `mau` | 近 30 日 event 去重活跃 |
|
|
|
+| `new_user_count` | `user.register` 事件数 |
|
|
|
+| `register_page_view_count` … `register_success_count` | 注册漏斗各 step 的 event 计数 |
|
|
|
+| `ai_chat_count` / `ai_chat_user_count` | `ai.chat.end` 次数 / 去重用户 |
|
|
|
+| `content_publish_count` | `content.publish` |
|
|
|
+| `content_interaction_count` | `content.interact` |
|
|
|
+| `merchant_visit_uv` | 商家访问去重 UV |
|
|
|
+| `merchant_expose_count` … `merchant_contact_count` | merchant_stat 汇总或 event |
|
|
|
+| `ai_response_duration_total_ms` / `ai_request_count` | `analytics_ai_request` |
|
|
|
+| `online_user_count` | 跑批快照（实时在线查 `user_stat_today`） |
|
|
|
+| `pay_user_count` / `today_gmv` / `avg_order_amount` | `pay.success` |
|
|
|
+| `conversion_rate` / `today_conversion_rate` | 支付用户数 / DAU |
|
|
|
+| `verify_rate` | 核销数 / 商家访问 UV |
|
|
|
+| `merchant_review_rate` | `merchant.review` / `merchant.verify` |
|
|
|
+| `audit_*` / `audit_pass_rate` | 审核 event |
|
|
|
+| `report_submit_count` / `report_handle_count` / `report_handle_rate` | 举报 event |
|
|
|
+| `next_day_retention_rate` | T-1 注册用户中 T 日活跃比例（写在前日行） |
|
|
|
+| `last_7d_new_user_count` / `last_7d_active_user_count` | 滑动窗口 event 去重 |
|
|
|
+| `total_settled_merchant_count` | merchant_stat 入驻商家数 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 九、明细表字段与 event 聚合关系
|
|
|
+
|
|
|
+### 9.1 `analytics_user_stat_*`
|
|
|
+
|
|
|
+| 字段 | 来源 |
|
|
|
+|------|------|
|
|
|
+| `first_launch_time` / `last_active_time` | event 聚合 / 心跳实时更新 |
|
|
|
+| `online_duration_min` | heartbeat + logout 的 `duration_ms` 累计 |
|
|
|
+| `is_new_user` | 当日是否有 `user.register` |
|
|
|
+| `gender` / `age_group` / `channel` / `city` | 注册或 detail 接口 |
|
|
|
+
|
|
|
+**关联**：`user_id`；看板「当前在线」查 `user_stat_today.last_active_time` 近 5 分钟。
|
|
|
+
|
|
|
+### 9.2 `analytics_merchant_stat_*`
|
|
|
+
|
|
|
+| 字段 | 来源 |
|
|
|
+|------|------|
|
|
|
+| `visit_uv` / `visit_pv` | `merchant.view` |
|
|
|
+| `expose_count` … `contact_count` | 漏斗 event |
|
|
|
+| `verify_count` | `merchant.verify` |
|
|
|
+| `review_count` / `review_rate` | `merchant.review` / verify |
|
|
|
+| `gmv` / `pay_count` / `pay_user_count` | `pay.success` |
|
|
|
+| `verify_conversion_rate` | verify / visit_uv |
|
|
|
+| `settle_time` / `settle_status` | 入驻 detail |
|
|
|
+
|
|
|
+**关联**：`merchant_id`。
|
|
|
+
|
|
|
+### 9.3 `analytics_content_stat_*`
|
|
|
+
|
|
|
+| 字段 | 来源 |
|
|
|
+|------|------|
|
|
|
+| `interaction_count` / `like_count` 等 | `content.interact` |
|
|
|
+| `publish_time` / `status` | `content.publish`、业务状态 |
|
|
|
+| `audit_status` / `audit_time` | `audit.*` event 或 detail |
|
|
|
+
|
|
|
+**关联**：`(content_type, content_id)`。
|
|
|
+
|
|
|
+### 9.4 `analytics_category_daily_*`
|
|
|
+
|
|
|
+按 `business_category`（1–7）汇总当日 GMV、支付笔数、商家 UV、内容发布/互动。
|
|
|
+
|
|
|
+### 9.5 `analytics_report_record_*`
|
|
|
+
|
|
|
+| 字段 | 说明 |
|
|
|
+|------|------|
|
|
|
+| `report_id` | 举报单号（提交时 `event_id`） |
|
|
|
+| `content_id` / `content_title` / `report_type` | 举报对象 |
|
|
|
+| `status` | 0 处理中 / 1 已处理 |
|
|
|
+| `report_time` / `handle_time` | 提交/处理时间 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十、报表 API 读表策略
|
|
|
+
|
|
|
+| 能力 | 优先读取 | 回退 / 补充 |
|
|
|
+|------|----------|-------------|
|
|
|
+| 看板 8 KPI 卡片 | `daily_summary` + 周期对比 | event 现场聚合 |
|
|
|
+| 趋势图（多日） | `daily_summary` | 今日按小时查 event |
|
|
|
+| 商家/注册漏斗 | `merchant_stat_*` / `daily_summary` 漏斗字段 | event |
|
|
|
+| 漏斗下钻明细分页 | **`analytics_event`** | — |
|
|
|
+| 用户/商家/内容明细分页 | `*_today` ∪ `*_history` | — |
|
|
|
+| 留存 cohort | event 跨日 join | `daily_summary.next_day_retention_rate` |
|
|
|
+| 当前在线（TODAY） | `user_stat_today.last_active_time` | — |
|
|
|
+| 举报列表 | `report_record_today` ∪ `report_record_history` | — |
|
|
|
+| AI 平均响应 | `daily_summary` 或 `analytics_ai_request` | — |
|
|
|
+| 多日 UV 整段去重 | **`analytics_event`** | 勿简单 SUM 每日 UV |
|
|
|
+
|
|
|
+**设计原则**：
|
|
|
+
|
|
|
+- **快**：KPI、趋势 → `daily_summary`
|
|
|
+- **细**：分页、TOP → `*_stat`
|
|
|
+- **准**：去重、下钻、cohort → `analytics_event`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十一、KPI 卡片数据链路示例
|
|
|
+
|
|
|
+### 11.1 今日 DAU
|
|
|
+
|
|
|
+```
|
|
|
+APP_LAUNCH / 活跃行为
|
|
|
+ → analytics_event (user_id, event_time)
|
|
|
+ → calculateDailySummary → daily_summary.dau
|
|
|
+ → GET /analytics/dashboard/summary → activeUser.value
|
|
|
+```
|
|
|
+
|
|
|
+多日周期：`countActiveUsersInRange` 直接扫 event 整段去重。
|
|
|
+
|
|
|
+### 11.2 当前在线
|
|
|
+
|
|
|
+```
|
|
|
+USER_HEARTBEAT (durationMs)
|
|
|
+ → analytics_event
|
|
|
+ → user_stat_today.last_active_time（实时更新）
|
|
|
+ → countOnlineSince(5min) / summary.onlineUser
|
|
|
+```
|
|
|
+
|
|
|
+仅 `period=TODAY` 为实时；其他周期不展示 5 分钟窗口值。
|
|
|
+
|
|
|
+### 11.3 举报处理率
|
|
|
+
|
|
|
+```
|
|
|
+REPORT_SUBMIT → event + report_record_today
|
|
|
+REPORT_HANDLE → event + report_record 更新 status=1
|
|
|
+ → daily_summary.report_handle_rate = handle / submit
|
|
|
+ → content-report.summary.reportHandleRate
|
|
|
+```
|
|
|
+
|
|
|
+### 11.4 商家评价率趋势
|
|
|
+
|
|
|
+```
|
|
|
+MERCHANT_REVIEW / MERCHANT_VERIFY
|
|
|
+ → merchant_stat.review_rate（商家维度）
|
|
|
+ → daily_summary.merchant_review_rate（平台日）
|
|
|
+ → merchant-report.reviewRateTrend
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十二、代码与 SQL 文件索引
|
|
|
+
|
|
|
+### 12.1 核心 Java 类
|
|
|
+
|
|
|
+| 职责 | 类 |
|
|
|
+|------|-----|
|
|
|
+| 埋点写入 | `AnalyticsTrackServiceImpl` |
|
|
|
+| 明细存取路由 | `AnalyticsDetailStoreServiceImpl` |
|
|
|
+| 跑批统计 | `AnalyticsStatisticsServiceImpl` |
|
|
|
+| 零点归档 | `AnalyticsArchiveServiceImpl` |
|
|
|
+| 看板查询 | `AnalyticsDashboardServiceImpl` |
|
|
|
+| 用户/内容/商家报表 | `Analytics*ReportServiceImpl` |
|
|
|
+| scene / event 枚举 | `AnalyticsScene`、`AnalyticsEventCode` |
|
|
|
+
|
|
|
+### 12.2 Mapper / SQL
|
|
|
+
|
|
|
+| 文件 | 用途 |
|
|
|
+|------|------|
|
|
|
+| `AnalyticsEventMapper.java` | event 聚合 SQL（@Select） |
|
|
|
+| `AnalyticsDashboardMapper.xml` | 看板趋势、漏斗、留存 |
|
|
|
+| `AnalyticsUserReportMapper.xml` | 用户报表 |
|
|
|
+| `AnalyticsContentReportMapper.xml` | 内容报表 |
|
|
|
+| `AnalyticsMerchantReportMapper.xml` | 商家报表 |
|
|
|
+| `AnalyticsFunnelMapper.xml` | 漏斗下钻 |
|
|
|
+| `AnalyticsArchiveMapper.xml` | 归档 / TRUNCATE |
|
|
|
+
|
|
|
+### 12.3 定时任务（XXL-JOB）
|
|
|
+
|
|
|
+| Job 名称 | 建议 Cron | 说明 |
|
|
|
+|----------|-----------|------|
|
|
|
+| `analyticsArchiveDaily` | `0 0 0 * * ?` | 明细 today → history |
|
|
|
+| `analyticsCalculateTodayHourly` | `5 5 * * * ?` | 当日准实时汇总（避开零点归档） |
|
|
|
+| `analyticsCalculateYesterdayDaily` | `0 0 2 * * ?` | 前日完整汇总 |
|
|
|
+| `analyticsCalculateRetention` | `0 0 3 * * ?` | 次日留存写前日行 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十三、运维与数据一致性
|
|
|
+
|
|
|
+### 13.1 新环境初始化
|
|
|
+
|
|
|
+1. 执行 `analytics_schema.sql`
|
|
|
+2. 配置 XXL-JOB 上述 4 个任务
|
|
|
+3. 前端接入埋点后，可手动 `POST /analytics/stat/calculate` 补历史日
|
|
|
+
|
|
|
+### 13.2 旧环境升级
|
|
|
+
|
|
|
+执行 `analytics_tables_dashboard_upgrade.sql`，必要时按脚本末尾说明将旧单表 RENAME 为 `*_today`。
|
|
|
+
|
|
|
+### 13.3 一致性说明
|
|
|
+
|
|
|
+| 现象 | 原因 | 建议 |
|
|
|
+|------|------|------|
|
|
|
+| 明细与 event 短暂不一致 | 实时写 today，跑批后按 event 覆盖 | 以跑批后为准 |
|
|
|
+| 看板无数据 | 未跑 `calculate` 或 `daily_summary` 无该行 | 补跑跑批 |
|
|
|
+| 今日与历史拼接断层 | 未跑归档或 today 已 TRUNCATE | 检查 archive 任务 |
|
|
|
+| 多日 UV 偏大 | 误用 SUM(日 UV) | 改用 event 周期去重 |
|
|
|
+
|
|
|
+### 13.4 手动运维接口
|
|
|
+
|
|
|
+| 接口 | 用途 |
|
|
|
+|------|------|
|
|
|
+| `POST /analytics/stat/calculate` | 指定 `statDate`、`scope` 跑批 |
|
|
|
+| `POST /analytics/stat/archive` | 手动触发昨日归档 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十四、与旧埋点体系的关系
|
|
|
+
|
|
|
+- **新体系**：`/analytics/front/*` + 本文档所述表，代码在 `shop.alien.store.controller.analytics` 包下。
|
|
|
+- **旧体系**：`@TrackEvent` 注解 + `POST /track/event`，见 [`埋点接口清单.md`](./埋点接口清单.md)，与 analytics 表 **相互独立**。
|
|
|
+- 运营看板 **仅消费新体系** 数据；旧埋点如需纳入看板，需增加 scene 上报或同步任务。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 十五、相关文档
|
|
|
+
|
|
|
+| 文档 | 内容 |
|
|
|
+|------|------|
|
|
|
+| [`前端埋点接入指南.md`](./前端埋点接入指南.md) | 前端 scene、请求示例、看板 API |
|
|
|
+| [`埋点接口清单.md`](./埋点接口清单.md) | 旧 @TrackEvent 接口列表 |
|
|
|
+| `analytics_schema.sql` | 完整 DDL |
|
|
|
+| `analytics_tables_dashboard_upgrade.sql` | 旧库增量升级 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+**维护说明**：表结构或跑批逻辑变更时，请同步更新本文档与 `analytics_schema.sql` 头部注释。
|
