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

一、需求概述

为 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 核心组件

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

三、数据库表设计

3.1 埋点事件主表 (store_track_event)

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)

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

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

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

请求参数:

{
  "eventType": "VIEW",
  "eventCategory": "TRAFFIC",
  "storeId": 1001,
  "targetId": 2001,
  "targetType": "PRICE",
  "eventData": "{}",
  "amount": 100.00,
  "duration": 3000
}

响应示例:

{
  "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)

响应示例:

{
  "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结束日期

响应示例:

{
  "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 (必填)

响应示例:

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

5.2 前端调用示例

// 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 埋点事件类型枚举

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推荐流程

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

7.2 AI接口调用

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

八、部署和运维

8.1 配置项

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

8.2 监控指标

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

九、注意事项

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

埋点需求完整方案.md 12 KB Историја Датотека

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

一、需求概述

1.1 埋点数据类型

1.1.1 流量数据

1.1.2 互动数据

1.1.3 优惠券数据

1.1.4 代金券数据

1.1.5 服务质量数据

1.1.6 价目表排名数据

二、技术架构

2.1 架构设计

2.2 核心组件

三、数据库表设计

3.1 埋点事件主表 (store_track_event)

3.2 埋点统计数据表 (store_track_statistics)

四、后端实现

4.1 埋点注解 (@TrackEvent)

4.2 AOP切面实现

4.3 Redis List 异步存储

4.4 定时任务消费

4.5 前端上报接口

4.6 统计查询接口

4.7 AI推荐接口

五、前端联调

5.1 前端需要的后端接口

5.1.1 埋点上报接口

5.1.2 经营数据查询接口

5.1.3 数据对比接口

5.1.4 AI推荐接口

5.2 前端调用示例

六、实现细节

6.1 埋点事件类型枚举

6.2 Redis Key 设计

6.3 消费策略

七、AI推荐实现

7.1 AI推荐流程

7.2 AI接口调用

八、部署和运维

8.1 配置项

8.2 监控指标

九、注意事项

埋点需求完整方案.md 12 KB

Историја Датотека