前端埋点接入指南

请前端统一使用 /analytics/front 接口，不要再调用旧接口 POST /track/event。

一、推荐接口

接口	说明
`POST /analytics/front/report`	主入口，传 `scene` 即可
`POST /analytics/front/batch`	批量上报（最多50条）
`POST /analytics/front/heartbeat`	在线心跳（统计在线时长）
`POST /analytics/front/user/register`	用户注册埋点
`POST /analytics/front/user/login`	用户登录埋点
`POST /analytics/front/user/logout`	用户登出埋点
`POST /analytics/front/ai-chat/end`	AI对话结束埋点
`POST /analytics/front/content/publish`	内容发布埋点
`POST /analytics/front/content/interact`	内容互动埋点（评论/点赞/收藏）
`POST /analytics/front/merchant/view`	商家浏览埋点
`POST /analytics/front/ai-request`	AI 请求耗时上报
`GET /analytics/front/scenes`	获取全部 scene 列表

明细同步（业务侧主动推送完整字段）：

接口	说明
`POST /analytics/detail/user`	用户明细
`POST /analytics/detail/merchant`	商户明细
`POST /analytics/detail/content`	内容明细
`POST /analytics/detail/ai-chat`	AI 对话明细

二、快速开始

1. 复制 SDK

将 alien-store/doc/analytics-front-sdk.js 复制到前端项目 utils/analytics.js。

2. 初始化（App.vue onLaunch）

import Analytics from '@/utils/analytics.js';

Analytics.init({
  baseUrl: 'https://your-api.com',
  getToken: () => uni.getStorageSync('token'),
  channel: 'app_store',
});

Analytics.onLaunch();
Analytics.startHeartbeat(60000);

3. 用户注册 / 登录 / 登出

// 注册成功
Analytics.userRegister({
  userId: 10001,
  userPhone: '13800138000',
  registerTime: '2026-06-15 10:00:00',
  channel: 'app_store',
  city: '北京',
});

// 登录成功
Analytics.userLogin({
  userId: 10001,
  city: '北京',
  deviceName: 'iPhone 15',
});

// 登出
Analytics.userLogout({
  userId: 10001,
  city: '北京',
  deviceName: 'iPhone 15',
  onlineDurationMin: 30,
});

4. AI 对话结束

Analytics.aiChatEnd({
  chatId: 'chat-uuid-001',
  userId: 10001,
  startTime: '2026-06-15 14:00:00',
  messageCount: 12,
  aiResponseDurationMs: 8500,
});

5. 内容发布

Analytics.contentPublish({
  contentId: 90001,
  contentType: 1,   // 1动态 2打卡 3二手商品
  authorType: 1,    // 1用户 2商家
  authorId: 10001,
  publishTime: '2026-06-15 16:00:00',
});

6. 内容互动（评论 / 点赞 / 收藏）

// 点赞 +1
Analytics.contentInteract({
  contentId: 90001,
  contentType: 1,
  increment: 1,
  userId: 10001,
});

// 取消点赞 -1
Analytics.contentInteract({
  contentId: 90001,
  contentType: 1,
  increment: -1,
  userId: 10001,
});

// 兼容旧写法（默认 increment=1）
Analytics.onContentInteract(90001, 1, { userId: 10001 });

7. 商家浏览

// 进入商家页：PV+1，当日首次访问 UV+1
Analytics.merchantView({
  merchantId: 20001,
  shopType: 1,   // 1美食 2休闲娱乐 3生活服务
  visitPv: 1,
  visitUv: 1,
  userId: 10001,
});

// 兼容旧写法（需传 shopType、visitPv、visitUv）
Analytics.onMerchantView(20001, {
  shopType: 1,
  visitPv: 1,
  visitUv: 1,
  userId: 10001,
});

8. 业务页面埋点示例

// 访问商户页
Analytics.onMerchantView(merchantId, {
  shopType: 1,
  visitPv: 1,
  visitUv: 1,
});

// 内容互动（contentType: 1动态 2打卡 3二手商品）
Analytics.onContentInteract(contentId, 1);

// 支付成功
Analytics.report('PAY_SUCCESS', { amount: 99.00, targetId: orderId });

// AI 请求耗时
Analytics.aiRequest({
  apiName: 'chat.completion',
  apiUrl: '/api/ai/chat',
  responseDurationMs: 1200,
  isTimeout: 0,
});

三、事件表独立字段说明

analytics_event 表每个业务值对应独立列，不使用 JSON 扩展字段：

字段	说明
userId / merchantId / targetId	用户、商户、目标对象
contentType	1动态 2打卡 3二手商品
amount / durationMs	金额、时长
deviceType / channel / city	设备、渠道、城市

四、scene 场景对照表

scene	含义	主要参数
`APP_LAUNCH`	App 启动	channel, city
`APP_REGISTER`	用户注册	-
`USER_HEARTBEAT`	在线心跳	durationMs
`MERCHANT_VIEW`	访问商户	merchantId
`MERCHANT_VERIFY`	商户核销	merchantId, amount
`CONTENT_PUBLISH`	发布内容	targetId, contentType
`CONTENT_INTERACT`	内容互动	targetId, contentType
`PAY_SUCCESS`	支付成功	targetId, amount
`AI_CHAT_START`	AI 对话开始	-
`REPORT_SUBMIT`	提交举报	targetId
`AUDIT_SUBMIT`	提交审核	targetId, contentType

完整列表调用：GET /analytics/front/scenes

五、请求示例

统一上报

POST /analytics/front/report
Authorization: Bearer {token}
Content-Type: application/json

{
  "scene": "MERCHANT_VIEW",
  "eventId": "a1b2c3d4e5f6",
  "merchantId": 1001,
  "city": "北京",
  "channel": "ios"
}

userId 可不传，服务端从 JWT 自动解析。

在线心跳

POST /analytics/front/heartbeat

{
  "durationMs": 60000
}

用户注册

POST /analytics/front/user/register

{
  "userId": 10001,
  "userPhone": "13800138000",
  "registerTime": "2026-06-15 10:00:00",
  "channel": "app_store",
  "city": "北京"
}

用户登录

POST /analytics/front/user/login

{
  "userId": 10001,
  "lastActiveTime": "2026-06-15 14:30:00",
  "city": "北京",
  "deviceName": "iPhone 15"
}

用户登出

POST /analytics/front/user/logout

{
  "userId": 10001,
  "lastActiveTime": "2026-06-15 15:00:00",
  "city": "北京",
  "deviceName": "iPhone 15",
  "onlineDurationMin": 30
}

AI 对话结束

POST /analytics/front/ai-chat/end

{
  "chatId": "chat-uuid-001",
  "userId": 10001,
  "startTime": "2026-06-15 14:00:00",
  "messageCount": 12,
  "aiResponseDurationMs": 8500
}

内容发布

POST /analytics/front/content/publish

{
  "contentId": 90001,
  "contentType": 1,
  "authorType": 1,
  "authorId": 10001,
  "publishTime": "2026-06-15 16:00:00"
}

内容互动

POST /analytics/front/content/interact

{
  "contentId": 90001,
  "contentType": 1,
  "increment": 1,
  "userId": 10001
}

increment 由前端决定增减幅度：评论/点赞/收藏传正数，取消操作传负数。会实时累加到 analytics_content_stat.interaction_count。

商家浏览

POST /analytics/front/merchant/view

{
  "merchantId": 20001,
  "shopType": 1,
  "visitUv": 1,
  "visitPv": 1,
  "userId": 10001
}

visitUv、visitPv 为当日增量：通常 PV 传 1；UV 在当日首次访问该商家时传 1，否则传 0。

商户明细同步（可选）

POST /analytics/detail/merchant

{
  "merchantId": 20001,
  "shopType": 1,
  "visitUv": 100,
  "visitPv": 500,
  "settleStatus": 1
}

明细同步接口中 visitUv/visitPv 为覆盖写入；浏览埋点 /merchant/view 为累加写入，请勿混用语义。

用户名称、商家名称、作者名称等展示字段不入库、不上报，查询明细时由服务端按 ID 回填。

AI 请求明细

POST /analytics/front/ai-request

{
  "apiName": "chat.completion",
  "apiUrl": "/api/ai/chat",
  "responseDurationMs": 1200,
  "isTimeout": 0
}

六、幂等与防重复

每条上报建议传 eventId（前端 UUID）
相同 eventId 重复提交会被服务端忽略，不会重复计数

七、管理端统计

建表脚本：alien-entity/src/main/resources/db/migration/analytics_tables.sql

埋点只写明细，看板数据由 alien-job 模块 XXL-JOB 定时任务或手动接口触发汇总：

XXL-JOB Handler	Cron 建议	说明
`analyticsCalculateTodayHourly`	`0 0 * * * ?`	每小时汇总当日
`analyticsCalculateYesterdayDaily`	`0 0 2 * * ?`	每天凌晨2点汇总前日
`analyticsCalculateRetention`	`0 0 3 * * ?`	每天凌晨3点计算留存

手动触发：

POST /analytics/stat/calculate
{ "statDate": "2026-06-15", "scope": "ALL" }

查询看板：

GET /analytics/stat/daily?statDate=2026-06-15

八、代码目录（与旧埋点完全隔离）

alien-store/src/main/java/shop/alien/store/
├── controller/analytics/
│   ├── AnalyticsFrontController   # 前端上报 /analytics/front/*
│   ├── AnalyticsDetailController  # 明细上报 /analytics/detail/*
│   ├── AnalyticsStatController    # 统计查询 /analytics/stat/*
│   └── AnalyticsJobController     # 定时任务回调 /analytics/job/*
├── service/analytics/
└── util/analytics/

alien-job/src/main/java/shop/alien/job/store/
└── AnalyticsStatisticsJob         # XXL-JOB 调度入口

前端埋点接入指南.md 9.0 KB Permanentný odkaz História Raw