# 埋点统计数据JSON格式说明

## 一、概述

`store_track_statistics` 表中的各个数据字段存储的是JSON格式的统计数据。本文档详细说明各个字段的JSON格式。

````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='埋点事件表';

-- 埋点统计表
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='埋点统计表';
```

## 二、各字段JSON格式

### 2.1 traffic_data（流量数据）

**字段说明**：存储流量相关的统计数据

**JSON格式**：
```json
{
  "searchCount": 100,           // 搜索量（Long类型）
  "viewCount": 500,             // 浏览量（Long类型）
  "visitorCount": 300,          // 访客数（去重后的用户数，Long类型）
  "newVisitorCount": 50,        // 新增访客数（Long类型）
  "totalDuration": 1500000,     // 总访问时长（毫秒，Long类型）
  "avgDuration": 5000           // 平均访问时长（毫秒，Long类型）
}
```

**字段说明**：
- `searchCount`: 店铺搜索次数（埋点时间SEARCH该店铺的次数）
- `viewCount`: 店铺浏览次数（埋点时间VIEW该店铺的次数）
- `visitorCount`: 访客数（去重后的用户ID数量）
- `newVisitorCount`: 新增访客数（在统计日期之前没有访问记录的用户）
- `totalDuration`: 总访问时长（所有浏览事件duration字段的总和，单位：毫秒）
- `avgDuration`: 平均访问时长（totalDuration / 有duration的浏览事件数，单位：毫秒）

---

### 2.2 interaction_data（互动数据）

**字段说明**：存储用户互动相关的统计数据

**JSON格式**：
```json
{
  "collectCount": 50,           // 收藏次数（Long类型）
  "shareCount": 30,             // 分享次数（Long类型）
  "checkinCount": 20,           // 打卡次数（Long类型）
  "consultCount": 10,           // 咨询次数（Long类型）
  "friendCount": 100,           // 好友数量（互相关注的用户数，Long类型）
  "followCount": 200,           // 关注数量（店铺用户关注的人数，Long类型）
  "fansCount": 150,             // 粉丝数量（关注店铺用户的人数，Long类型）
  "postCount": 25,              // 发布动态数量（Long类型）
  "postLikeCount": 200,         // 动态点赞数量（Long类型）
  "postCommentCount": 80,      // 动态评论数量（Long类型）
  "postRepostCount": 15,        // 动态转发数量（Long类型）
  "reportCount": 5,             // 被举报次数（Long类型）
  "blockCount": 2               // 被拉黑次数（Long类型）
}
```

**字段说明**：
- `collectCount`: 店铺收藏次数（从埋点事件中统计COLLECT类型）
- `shareCount`: 店铺分享次数（从埋点事件中统计SHARE类型）
- `checkinCount`: 店铺打卡次数（从埋点事件中统计CHECKIN类型）
- `consultCount`: 咨询商家次数（从埋点事件中统计CONSULT类型）
- `friendCount`: 好友数量（通过life_fans表查询互相关注的用户数）
- `followCount`: 关注数量（店铺用户关注的人数）
- `fansCount`: 粉丝数量（关注店铺用户的人数）
- `postCount`: 发布动态数量（从life_user_dynamics表查询，type=2商家社区）
- `postLikeCount`: 动态点赞数量（从埋点事件中统计POST_LIKE类型）
- `postCommentCount`: 动态评论数量（从埋点事件中统计POST_COMMENT类型）
- `postRepostCount`: 动态转发数量（从埋点事件中统计POST_REPOST类型）
- `reportCount`: 被举报次数（从埋点事件中统计REPORT类型）
- `blockCount`: 被拉黑次数（从埋点事件中统计BLOCK类型）

---

### 2.3 coupon_data（优惠券数据）

**字段说明**：存储优惠券相关的统计数据

**JSON格式**：
```json
{
  "giveToFriendCount": 50,                    // 赠送好友数量（Long类型）
  "giveToFriendAmount": 5000.00,             // 赠送好友金额合计（BigDecimal类型，单位：元）
  "giveToFriendUseCount": 30,                // 赠送好友使用数量（Long类型）
  "giveToFriendUseAmount": 3000.00,          // 赠送好友使用金额合计（BigDecimal类型，单位：元）
  "giveToFriendUseAmountPercent": 60.00,     // 赠送好友使用金额占比（Double类型，单位：%）
  "friendGiveCount": 20,                     // 好友赠送数量（Long类型）
  "friendGiveAmount": 2000.00,               // 好友赠送金额合计（BigDecimal类型，单位：元）
  "friendGiveUseCount": 15,                  // 好友赠送使用数量（Long类型）
  "friendGiveUseAmount": 1500.00,            // 好友赠送使用金额合计（BigDecimal类型，单位：元）
  "friendGiveUseAmountPercent": 75.00        // 好友赠送使用金额占比（Double类型，单位：%）
}
```

**字段说明**：
- `giveToFriendCount`: 赠送好友数量（从life_discount_coupon_user表统计，关联店铺的优惠券）
- `giveToFriendAmount`: 赠送好友金额合计（优惠券面值的总和）
- `giveToFriendUseCount`: 赠送好友使用数量（status=1已使用的数量）
- `giveToFriendUseAmount`: 赠送好友使用金额合计（已使用优惠券的面值总和）
- `giveToFriendUseAmountPercent`: 赠送好友使用金额占比（giveToFriendUseAmount / giveToFriendAmount * 100）
- `friendGiveCount`: 好友赠送数量（好友赠送给店铺用户的优惠券数量，从life_discount_coupon_store_friend表统计）
- `friendGiveAmount`: 好友赠送金额合计（好友赠送的优惠券面值总和）
- `friendGiveUseCount`: 好友赠送使用数量（已使用的数量）
- `friendGiveUseAmount`: 好友赠送使用金额合计（已使用的优惠券面值总和）
- `friendGiveUseAmountPercent`: 好友赠送使用金额占比（friendGiveUseAmount / friendGiveAmount * 100）

---

### 2.4 voucher_data（代金券数据）

**字段说明**：存储代金券相关的统计数据

**JSON格式**：
```json
{
  "giveToFriendCount": 30,                    // 赠送好友数量（Long类型）
  "giveToFriendAmount": 3000.00,             // 赠送好友金额合计（BigDecimal类型，单位：元）
  "giveToFriendUseCount": 20,               // 赠送好友使用数量（Long类型）
  "giveToFriendUseAmount": 2000.00,         // 赠送好友使用金额合计（BigDecimal类型，单位：元）
  "giveToFriendUseAmountPercent": 66.67,    // 赠送好友使用金额占比（Double类型，单位：%）
  "friendGiveCount": 10,                     // 好友赠送数量（Long类型）
  "friendGiveAmount": 1000.00,               // 好友赠送金额合计（BigDecimal类型，单位：元）
  "friendGiveUseCount": 8,                   // 好友赠送使用数量（Long类型）
  "friendGiveUseAmount": 800.00,             // 好友赠送使用金额合计（BigDecimal类型，单位：元）
  "friendGiveUseAmountPercent": 80.00        // 好友赠送使用金额占比（Double类型，单位：%）
}
```

**字段说明**：
- `giveToFriendCount`: 赠送好友数量（从埋点事件中统计VOUCHER_GIVE类型）
- `giveToFriendAmount`: 赠送好友金额合计（从埋点事件的amount字段汇总）
- `giveToFriendUseCount`: 赠送好友使用数量（从埋点事件中统计VOUCHER_USE类型）
- `giveToFriendUseAmount`: 赠送好友使用金额合计（从埋点事件的amount字段汇总）
- `giveToFriendUseAmountPercent`: 赠送好友使用金额占比（giveToFriendUseAmount / giveToFriendAmount * 100）
- `friendGiveCount`: 好友赠送数量（好友赠送给店铺用户的代金券数量，从life_discount_coupon_store_friend表统计，type=1代金券）
- `friendGiveAmount`: 好友赠送金额合计（好友赠送的代金券面值总和）
- `friendGiveUseCount`: 好友赠送使用数量（已使用的数量）
- `friendGiveUseAmount`: 好友赠送使用金额合计（已使用的代金券面值总和）
- `friendGiveUseAmountPercent`: 好友赠送使用金额占比（friendGiveUseAmount / friendGiveAmount * 100）

---

### 2.5 service_data（服务质量数据）

**字段说明**：存储服务质量相关的统计数据

**JSON格式**：
```json
{
  "storeScore": 4.5,              // 店铺评分（Double类型，0-5分）
  "scoreOne": 4.3,                // 评分1（Double类型，0-5分）
  "scoreTwo": 4.2,                // 评分2（Double类型，0-5分）
  "scoreThree": 4.4,              // 评分3（Double类型，0-5分）
  "ratingCount": 100,             // 评价数量（Long类型）
  "goodRatingCount": 60,          // 好评数量（score >= 4.5，Long类型）
  "midRatingCount": 30,           // 中评数量（3.0 <= score <= 4.0，Long类型）
  "badRatingCount": 10,           // 差评数量（0.5 <= score <= 2.5，Long类型）
  "badRatingPercent": 10.00,      // 差评占比（Double类型，单位：%）
  "appealCount": 5,               // 差评申诉次数（Long类型）
  "appealSuccessCount": 3,        // 差评申诉成功次数（Long类型）
  "appealSuccessPercent": 60.00   // 差评申诉成功占比（Double类型，单位：%）
}
```

**字段说明**：
- `storeScore`: 店铺评分（从common_rating表查询score字段，businessType=1，计算平均分）
- `scoreOne`: 评分1（从common_rating表的score_one字段，计算平均分）
- `scoreTwo`: 评分2（从common_rating表的score_two字段，计算平均分）
- `scoreThree`: 评分3（从common_rating表的score_three字段，计算平均分）
- `ratingCount`: 评价数量（common_rating表中该店铺的累计评价总数）
- `goodRatingCount`: 好评数量（score >= 4.5的评价数）
- `midRatingCount`: 中评数量（3.0 <= score <= 4.0的评价数）
- `badRatingCount`: 差评数量（0.5 <= score <= 2.5的评价数）
- `badRatingPercent`: 差评占比（badRatingCount / ratingCount * 100）
- `appealCount`: 差评申诉次数（从埋点事件中统计APPEAL类型）
- `appealSuccessCount`: 差评申诉成功次数（从store_comment_appeal表统计，appealStatus=2已同意）
- `appealSuccessPercent`: 差评申诉成功占比（appealSuccessCount / appealCount * 100）

**注意**：评价数据为累计数据，统计截止到统计日期的所有评价。

---

### 2.6 price_ranking_data（价目表排名数据）

**字段说明**：存储价目表排名相关的统计数据（数组格式）

**JSON格式**：
```json
[
  {
    "priceId": 1001,        // 价目表ID（Integer类型）
    "viewCount": 500,       // 浏览量（Integer类型）
    "visitorCount": 300,    // 访客数（Integer类型）
    "shareCount": 50        // 分享数（Integer类型）
  },
  {
    "priceId": 1002,
    "viewCount": 400,
    "visitorCount": 250,
    "shareCount": 40
  },
  {
    "priceId": 1003,
    "viewCount": 300,
    "visitorCount": 200,
    "shareCount": 30
  }
]
```

**字段说明**：
- 数组按`viewCount`（浏览量）降序排列
- 每个元素包含一个价目表的统计数据
- `priceId`: 价目表ID（targetId字段）
- `viewCount`: 浏览量（PRICE_VIEW事件数量）
- `visitorCount`: 访客数（去重后的用户ID数量）
- `shareCount`: 分享数（PRICE_SHARE事件数量）

---

## 三、数据保存说明

### 3.1 统计数据如何保存

统计数据通过定时任务自动计算并保存：

1. **日统计任务**：每天凌晨1点执行，计算前一天的统计数据（statType=DAILY）
2. **周统计任务**：每周一凌晨2点执行，计算上一周的统计数据（statType=WEEKLY）
3. **月统计任务**：每月1号凌晨3点执行，计算上一个月的统计数据（statType=MONTHLY）

**定时任务类**：`TrackStatisticsScheduler.java`

### 3.2 手动触发统计

如果需要手动触发统计数据计算，可以调用：

```java
trackEventService.calculateAndSaveStatistics(storeId, statDate, statType);
```

**参数说明**：
- `storeId`: 店铺ID
- `statDate`: 统计日期
- `statType`: 统计类型（DAILY/WEEKLY/MONTHLY）

### 3.3 数据更新策略

- 如果该店铺、该日期、该统计类型的记录已存在，则更新数据
- 如果不存在，则创建新记录
- 使用唯一索引 `uk_store_date_type` 保证唯一性

---

## 四、注意事项

1. **数据类型**：
   - Long类型字段在JSON中显示为数字（如：100）
   - BigDecimal类型字段在JSON中显示为数字（如：5000.00）
   - Double类型字段在JSON中显示为数字（如：4.5）
   - 数组类型字段在JSON中显示为数组（如：[]）

2. **空值处理**：
   - 如果某个分类没有数据，对应的字段可能为null或空对象
   - 建议在查询时进行null判断

3. **数据精度**：
   - 金额字段使用BigDecimal保证精度
   - 百分比字段保留2位小数
   - 评分字段保留1位小数

4. **性能优化**：
   - 统计数据已预计算并存储，查询时直接读取，无需实时计算
   - 建议定期清理历史统计数据，避免数据表过大