埋点统计表结构说明.md 22 KB
埋点与统计表结构说明
本文档说明平台埋点统计系统的 表结构、分层关系、数据流向、关联键与查询口径。
与前端埋点接入指南.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 等专用接口）
每次成功上报的典型步骤：
- 将
scene映射为event_code，插入analytics_event（event_id幂等） - 按场景 同步更新 对应
*_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_requestanalytics_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：
-- 历史段
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 新环境初始化
- 执行
analytics_schema.sql - 配置 XXL-JOB 上述 4 个任务
- 前端接入埋点后，可手动
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，与 analytics 表 相互独立。 - 运营看板 仅消费新体系 数据；旧埋点如需纳入看板，需增加 scene 上报或同步任务。
十五、相关文档
| 文档 | 内容 |
|---|---|
前端埋点接入指南.md |
前端 scene、请求示例、看板 API |
埋点接口清单.md |
旧 @TrackEvent 接口列表 |
analytics_schema.sql |
完整 DDL |
analytics_tables_dashboard_upgrade.sql |
旧库增量升级 |
维护说明：表结构或跑批逻辑变更时，请同步更新本文档与 analytics_schema.sql 头部注释。