# 前端埋点接入指南

> **请前端统一使用 `/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）

```javascript
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. 用户注册 / 登录 / 登出

```javascript
// 注册成功
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 对话结束

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

### 5. 内容发布

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

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

```javascript
// 点赞 +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. 商家浏览

```javascript
// 进入商家页：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. 业务页面埋点示例

```javascript
// 访问商户页
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`

## 五、请求示例

### 统一上报

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

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

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

### 在线心跳

```http
POST /analytics/front/heartbeat

{
  "durationMs": 60000
}
```

### 用户注册

```http
POST /analytics/front/user/register

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

### 用户登录

```http
POST /analytics/front/user/login

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

### 用户登出

```http
POST /analytics/front/user/logout

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

### AI 对话结束

```http
POST /analytics/front/ai-chat/end

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

### 内容发布

```http
POST /analytics/front/content/publish

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

### 内容互动

```http
POST /analytics/front/content/interact

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

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

### 商家浏览

```http
POST /analytics/front/merchant/view

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

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

### 商户明细同步（可选）

```http
POST /analytics/detail/merchant

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

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

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

### AI 请求明细

```http
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点计算留存 |

手动触发：

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

查询看板：

```http
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 调度入口
```