文档更新

alien-store/doc/前端埋点接入指南.md

@@ -1,6 +1,8 @@
 # 前端埋点接入指南
 
 > **请前端统一使用 `/analytics/front` 接口，不要再调用旧接口 `POST /track/event`。**
+>
+> 表结构、数据流向与统计关联说明见 **[埋点统计表结构说明.md](./埋点统计表结构说明.md)**。
 
 ## 一、推荐接口
 
@@ -512,6 +514,8 @@ POST /analytics/stat/archive
 
 ## 九、代码目录（与旧埋点完全隔离）
 
+相关文档：[埋点统计表结构说明.md](./埋点统计表结构说明.md)（表分层、归档、字段血缘）
+
 ```
 alien-store/src/main/java/shop/alien/store/
 ├── controller/analytics/

alien-store/doc/埋点统计表结构说明.md

@@ -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` 头部注释。