埋点与统计表结构说明

本文档说明平台埋点统计系统的 表结构、分层关系、数据流向、关联键与查询口径。
与 前端埋点接入指南.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_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：

-- 历史段
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 头部注释。

埋点统计表结构说明.md 22 KB История Исходник