# 用户端埋点需求完整方案文档

## 一、需求概述

为 alien-store 模块的用户端实现完整的埋点系统，用于统计和分析用户行为数据，并通过AI提供智能推荐服务。

### 1.1 埋点数据类型

根据原型图，需要收集以下类型的数据：

#### 1.1.1 流量数据
- 店铺搜索量
- 浏览量
- 访客数
- 新增访客数
- 访问时长
- 平均访问时长

#### 1.1.2 互动数据
- 店铺收藏次数
- 店铺分享次数
- 店铺打卡次数
- 咨询商家次数
- 好友数量
- 关注数量
- 粉丝数量
- 发布动态数量
- 动态点赞数量
- 动态评论数量
- 动态转发数量
- 被举报次数
- 被拉黑次数

#### 1.1.3 优惠券数据
- 赠送好友数量
- 赠送好友金额合计
- 赠送好友使用数量
- 赠送好友使用金额合计
- 赠送好友使用金额占比
- 好友赠送数量
- 好友赠送金额合计
- 好友赠送使用数量
- 好友赠送使用金额合计
- 好友赠送使用金额占比

#### 1.1.4 代金券数据
- 赠送好友数量
- 赠送好友金额合计
- 赠送好友使用数量
- 赠送好友使用金额合计
- 赠送好友使用金额占比
- 好友赠送数量
- 好友赠送金额合计
- 好友赠送使用数量
- 好友赠送使用金额合计
- 好友赠送使用金额占比

#### 1.1.5 服务质量数据
- 店铺评分
- 评分1
- 评分2
- 评分3
- 评价数量
- 好评数量
- 中评数量
- 差评数量
- 差评占比
- 差评申诉次数
- 差评申诉成功次数
- 差评申诉成功占比

#### 1.1.6 价目表排名数据
- 价目表浏览量
- 价目表访客数
- 价目表分享数

## 二、技术架构

### 2.1 架构设计

```
前端 (客户端)
  ↓ HTTP请求
Controller (埋点上报接口)
  ↓ 异步写入
Redis List (消息队列)
  ↓ 定时任务批量消费
数据库 (MySQL)
  ↓ 统计分析
统计查询接口
  ↓ AI分析
AI推荐服务
```

### 2.2 核心组件

1. **埋点注解** (`@TrackEvent`): 标注需要埋点的方法
2. **AOP切面** (`TrackEventAspect`): 拦截标注的方法，自动收集数据
3. **Redis List**: 作为消息队列，异步存储埋点数据
4. **消费服务** (`TrackEventConsumer`): 定时从Redis List批量消费数据并写入数据库
5. **前端接口** (`TrackEventController`): 提供前端主动上报埋点的接口
6. **统计接口** (`BusinessDataController`): 提供经营数据统计查询
7. **AI推荐接口** (`AIRecoveryController`): 基于埋点数据提供AI推荐

## 三、数据库表设计

### 3.1 埋点事件主表 (store_track_event)

```sql
CREATE TABLE `store_track_event` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `event_type` varchar(50) NOT NULL COMMENT '事件类型(VIEW-浏览,SEARCH-搜索,COLLECT-收藏,SHARE-分享,CHECKIN-打卡,CONSULT-咨询,FOLLOW-关注,UNFOLLOW-取消关注,FRIEND_ADD-添加好友,POST_PUBLISH-发布动态,POST_LIKE-动态点赞,POST_COMMENT-动态评论,POST_REPOST-动态转发,REPORT-举报,BLOCK-拉黑,COUPON_GIVE-赠送优惠券,COUPON_USE-使用优惠券,VOUCHER_GIVE-赠送代金券,VOUCHER_USE-使用代金券,PRICE_VIEW-价目表浏览,PRICE_SHARE-价目表分享,RATING-评价,APPEAL-申诉)',
  `event_category` varchar(50) NOT NULL COMMENT '事件分类(TRAFFIC-流量数据,INTERACTION-互动数据,COUPON-优惠券,VOUCHER-代金券,SERVICE-服务质量,PRICE-价目表)',
  `user_id` int(11) DEFAULT NULL COMMENT '用户ID',
  `store_id` int(11) DEFAULT NULL COMMENT '店铺ID',
  `target_id` int(11) DEFAULT NULL COMMENT '目标对象ID(如价目表ID、动态ID等)',
  `target_type` varchar(50) DEFAULT NULL COMMENT '目标对象类型(PRICE-价目表,POST-动态,STORE-店铺等)',
  `event_data` text COMMENT '事件附加数据(JSON格式)',
  `amount` decimal(10,2) DEFAULT NULL COMMENT '金额(用于优惠券、代金券等)',
  `duration` bigint(20) DEFAULT NULL COMMENT '时长(毫秒,用于访问时长等)',
  `ip_address` varchar(50) DEFAULT NULL COMMENT 'IP地址',
  `user_agent` varchar(500) DEFAULT NULL COMMENT '用户代理',
  `device_type` varchar(20) DEFAULT NULL COMMENT '设备类型(IOS,ANDROID,WEB)',
  `app_version` varchar(20) DEFAULT NULL COMMENT 'APP版本号',
  `event_time` datetime NOT NULL COMMENT '事件发生时间',
  `created_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `delete_flag` int(1) NOT NULL DEFAULT '0' COMMENT '删除标记(0:未删除,1:已删除)',
  PRIMARY KEY (`id`),
  KEY `idx_store_id` (`store_id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_event_type` (`event_type`),
  KEY `idx_event_category` (`event_category`),
  KEY `idx_event_time` (`event_time`),
  KEY `idx_store_event_time` (`store_id`,`event_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='埋点事件表';
```

### 3.2 埋点统计数据表 (store_track_statistics)

用于存储按店铺、日期聚合的统计数据，提升查询性能：

```sql
CREATE TABLE `store_track_statistics` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `store_id` int(11) NOT NULL COMMENT '店铺ID',
  `stat_date` date NOT NULL COMMENT '统计日期',
  `stat_type` varchar(50) NOT NULL COMMENT '统计类型(DAILY-日统计,WEEKLY-周统计,MONTHLY-月统计)',
  `traffic_data` text COMMENT '流量数据(JSON格式)',
  `interaction_data` text COMMENT '互动数据(JSON格式)',
  `coupon_data` text COMMENT '优惠券数据(JSON格式)',
  `voucher_data` text COMMENT '代金券数据(JSON格式)',
  `service_data` text COMMENT '服务质量数据(JSON格式)',
  `price_ranking_data` text COMMENT '价目表排名数据(JSON格式)',
  `created_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_store_date_type` (`store_id`,`stat_date`,`stat_type`),
  KEY `idx_store_id` (`store_id`),
  KEY `idx_stat_date` (`stat_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='埋点统计表';
```

## 四、后端实现

### 4.1 埋点注解 (@TrackEvent)

定义在 `alien-store/src/main/java/shop/alien/store/annotation/TrackEvent.java`

### 4.2 AOP切面实现

定义在 `alien-store/src/main/java/shop/alien/store/aspect/TrackEventAspect.java`

### 4.3 Redis List 异步存储

使用现有的 `BaseRedisService` 的 `setListRight` 方法将埋点数据写入Redis List

### 4.4 定时任务消费

定义在 `alien-store/src/main/java/shop/alien/store/service/TrackEventConsumer.java`

使用 `@Scheduled` 注解定时从Redis List批量取出数据并写入数据库

### 4.5 前端上报接口

定义在 `alien-store/src/main/java/shop/alien/store/controller/TrackEventController.java`

### 4.6 统计查询接口

定义在 `alien-store/src/main/java/shop/alien/store/controller/BusinessDataController.java`

### 4.7 AI推荐接口

定义在 `alien-store/src/main/java/shop/alien/store/controller/AIRecoveryController.java`

## 五、前端联调

### 5.1 前端需要的后端接口

#### 5.1.1 埋点上报接口

**接口路径**: `POST /track/event`

**接口说明**: 前端主动上报埋点数据

**请求参数**:
```json
{
  "eventType": "VIEW",
  "eventCategory": "TRAFFIC",
  "storeId": 1001,
  "targetId": 2001,
  "targetType": "PRICE",
  "eventData": "{}",
  "amount": 100.00,
  "duration": 3000
}
```

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "msg": "上报成功",
  "data": null
}
```

#### 5.1.2 经营数据查询接口

**接口路径**: `GET /business/data`

**接口说明**: 查询店铺的经营数据统计

**请求参数**:
- `storeId`: 店铺ID (必填)
- `startDate`: 开始日期 (格式: yyyy-MM-dd)
- `endDate`: 结束日期 (格式: yyyy-MM-dd)
- `category`: 数据分类 (可选: TRAFFIC, INTERACTION, COUPON, VOUCHER, SERVICE, PRICE)

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "msg": "查询成功",
  "data": {
    "trafficData": {
      "searchCount": 100,
      "viewCount": 100,
      "visitorCount": 70,
      "newVisitorCount": 10,
      "totalDuration": 373533,
      "avgDuration": 213
    },
    "interactionData": {
      "collectCount": 100,
      "shareCount": 100,
      "checkinCount": 100,
      "consultCount": 100
    }
  }
}
```

#### 5.1.3 数据对比接口

**接口路径**: `GET /business/data/compare`

**接口说明**: 对比两个时间段的数据

**请求参数**:
- `storeId`: 店铺ID (必填)
- `startDate1`: 时间段1开始日期
- `endDate1`: 时间段1结束日期
- `startDate2`: 时间段2开始日期
- `endDate2`: 时间段2结束日期

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "msg": "查询成功",
  "data": {
    "period1": {
      "viewCount": 100,
      "visitorCount": 70
    },
    "period2": {
      "viewCount": 80,
      "visitorCount": 70
    },
    "compare": {
      "viewCountChange": 25.00,
      "visitorCountChange": 0.00
    }
  }
}
```

#### 5.1.4 AI推荐接口

**接口路径**: `GET /business/ai/recommendation`

**接口说明**: 获取基于埋点数据的AI推荐

**请求参数**:
- `storeId`: 店铺ID (必填)

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "msg": "查询成功",
  "data": {
    "summary": "相较于其他同星级的店铺,您价目表中的锅包肉和烤羊腿价格远高于其他商家",
    "recommendations": [
      {
        "type": "PRICING",
        "title": "价格优化建议",
        "content": "寻找原材料更便宜的菜场、菜量降低、菜名突出特色,如锡林郭勒盟羔羊烤羊腿"
      }
    ]
  }
}
```

### 5.2 前端调用示例

```javascript
// 1. 上报浏览事件
axios.post('/track/event', {
  eventType: 'VIEW',
  eventCategory: 'TRAFFIC',
  storeId: 1001,
  targetType: 'STORE',
  duration: 3000
});

// 2. 查询经营数据
axios.get('/business/data', {
  params: {
    storeId: 1001,
    startDate: '2026-01-08',
    endDate: '2026-01-14',
    category: 'TRAFFIC'
  }
});

// 3. 数据对比
axios.get('/business/data/compare', {
  params: {
    storeId: 1001,
    startDate1: '2026-01-08',
    endDate1: '2026-01-14',
    startDate2: '2026-01-01',
    endDate2: '2026-01-07'
  }
});

// 4. 获取AI推荐
axios.get('/business/ai/recommendation', {
  params: {
    storeId: 1001
  }
});
```

## 六、实现细节

### 6.1 埋点事件类型枚举

```java
public enum EventType {
    VIEW("VIEW", "浏览"),
    SEARCH("SEARCH", "搜索"),
    COLLECT("COLLECT", "收藏"),
    SHARE("SHARE", "分享"),
    CHECKIN("CHECKIN", "打卡"),
    CONSULT("CONSULT", "咨询"),
    FOLLOW("FOLLOW", "关注"),
    UNFOLLOW("UNFOLLOW", "取消关注"),
    FRIEND_ADD("FRIEND_ADD", "添加好友"),
    POST_PUBLISH("POST_PUBLISH", "发布动态"),
    POST_LIKE("POST_LIKE", "动态点赞"),
    POST_COMMENT("POST_COMMENT", "动态评论"),
    POST_REPOST("POST_REPOST", "动态转发"),
    REPORT("REPORT", "举报"),
    BLOCK("BLOCK", "拉黑"),
    COUPON_GIVE("COUPON_GIVE", "赠送优惠券"),
    COUPON_USE("COUPON_USE", "使用优惠券"),
    VOUCHER_GIVE("VOUCHER_GIVE", "赠送代金券"),
    VOUCHER_USE("VOUCHER_USE", "使用代金券"),
    PRICE_VIEW("PRICE_VIEW", "价目表浏览"),
    PRICE_SHARE("PRICE_SHARE", "价目表分享"),
    RATING("RATING", "评价"),
    APPEAL("APPEAL", "申诉");
}
```

### 6.2 Redis Key 设计

- 埋点队列: `track:event:queue`
- 消费锁: `track:event:consumer:lock`

### 6.3 消费策略

- 每次消费数量: 100条
- 消费频率: 每10秒执行一次
- 使用分布式锁防止多实例重复消费

## 七、AI推荐实现

### 7.1 AI推荐流程

1. 收集店铺的埋点数据
2. 调用AI服务分析数据
3. 对比同行业、同星级店铺数据
4. 生成推荐建议

### 7.2 AI接口调用

使用现有的 `AlienAIFeign` 调用AI服务，需要新增推荐接口。

## 八、部署和运维

### 8.1 配置项

- Redis List最大长度: 100000
- 批量消费大小: 100
- 消费间隔: 10秒
- 统计数据保留期: 2年

### 8.2 监控指标

- Redis List长度
- 消费延迟
- 消费失败率
- 统计查询响应时间

## 九、注意事项

1. 埋点数据量可能很大，需要定期清理历史数据
2. Redis List需要设置最大长度，防止内存溢出
3. 消费服务需要异常处理和重试机制
4. 统计数据建议使用定时任务预计算，提升查询性能
5. AI推荐接口需要缓存，避免频繁调用AI服务