/v2/summary 接口查询语句和数据统计方法详解

本文档详细解释了 /v2/summary 接口使用的查询语句和数据统计方法。

1. 查询语句

对于请求 /v2/summary?postId=6ff59f85-6b2b-486c-a7e6-33d1a1979da9&startDate=2025-11-25&endDate=2025-12-02&zoneId=America/Los_Angeles，系统会执行以下 MongoDB 查询：

1.1 查询条件

{
  "postId": "6ff59f85-6b2b-486c-a7e6-33d1a1979da9",
  "date": {
    "$gte": "2025-11-25",
    "$lte": "2025-12-02"
  }
}

这个查询会在名为 prodUserActivitySummary_America/Los_Angeles_v2 的集合中查找匹配的文档。

1.2 完整的聚合管道

系统使用 MongoDB 的聚合管道（Aggregation Pipeline）来处理数据，聚合管道包含以下阶段：

匹配阶段 ($match)：

{
  $match: {
    "postId": "6ff59f85-6b2b-486c-a7e6-33d1a1979da9",
    "date": {
      "$gte": "2025-11-25",
      "$lte": "2025-12-02"
    }
  }
}

分组汇总阶段 ($group)：

{
  $group: {
    _id: null,
    summary: {
      $accumulator: {
        init: function() {
          return {
            uniqueVisitors: 0,
            engaged: 0,
            viewedProduct: 0,
            clickedAddToCart: 0,
            clickedBuyNow: 0,
            initiatedCheckout: 0,
            placedOrder: 0,
            addedToCart: 0,
            orderQuantity: 0,
            device: {},
            platform: {},
            ui: {}
          };
        },
        accumulate: function(summary, record) {
          // 累加各项指标
          if (record["uniqueVisitors"] > 0) summary["uniqueVisitors"] += record["uniqueVisitors"];
          if (record["engaged"] > 0) summary["engaged"] += record["engaged"];
          if (record["viewedProduct"] > 0) summary["viewedProduct"] += record["viewedProduct"];
          if (record["clickedAddToCart"] > 0) summary["clickedAddToCart"] += record["clickedAddToCart"];
          if (record["clickedBuyNow"] > 0) summary["clickedBuyNow"] += record["clickedBuyNow"];
          if (record["initiatedCheckout"] > 0) summary["initiatedCheckout"] += record["initiatedCheckout"];
          if (record["addedToCart"] > 0) summary["addedToCart"] += record["addedToCart"];
          if (record["placedOrder"] > 0) summary["placedOrder"] += record["placedOrder"];
          if (record["orderQuantity"] > 0) summary["orderQuantity"] += record["orderQuantity"];

          // 合并设备分布统计
          for (const key in record.device) {
            if (summary.device[key]) {
              summary.device[key] += record.device[key];
            } else {
              summary.device[key] = record.device[key];
            }
          }

          // 合并平台分布统计
          for (const key in record.platform) {
            if (summary.platform[key]) {
              summary.platform[key] += record.platform[key];
            } else {
              summary.platform[key] = record.platform[key];
            }
          }

          // 合并UI分布统计
          for (const key in record.ui) {
            if (summary.ui[key]) {
              summary.ui[key] += record.ui[key];
            } else {
              summary.ui[key] = record.ui[key];
            }
          }
          return summary;
        },
        accumulateArgs: ["$$CURRENT"],
        merge: function(summary, record) {
          // 与accumulate函数相同，用于合并多个聚合节点的结果
          // 实现逻辑略...
        }
      }
    }
  }
}

结果展开阶段 ($project)：

{
  $project: {
    _id: false,
    uniqueVisitors: "$summary.uniqueVisitors",
    engaged: "$summary.engaged",
    viewedProduct: "$summary.viewedProduct",
    clickedAddToCart: "$summary.clickedAddToCart",
    clickedBuyNow: "$summary.clickedBuyNow",
    initiatedCheckout: "$summary.initiatedCheckout",
    addedToCart: "$summary.addedToCart",
    placedOrder: "$summary.placedOrder",
    orderQuantity: "$summary.orderQuantity",
    device: "$summary.device",
    platform: "$summary.platform",
    ui: "$summary.ui"
  }
}

2. 数据统计来源

2.1 原始数据收集

系统中的数据来自于用户的实际行为，包括：

浏览文章 (USER_ACTIVITY_POST_ACCESS)
查看商品 (USER_ACTIVITY_POST_VIEWED_PRODUCT)
点击购物车 (USER_ACTIVITY_POST_CLICK_ADD_TO_CART)
点击立即购买 (USER_ACTIVITY_POST_CLICK_BUY_NOW)
发起结账 (USER_ACTIVITY_CHECKOUT_INITIATED)
下订单 (USER_ACTIVITY_ORDER_PLACED)
等等...

2.2 数据处理流程

原始用户活动数据 (UserActivity)
- 存储最原始的用户行为数据
处理后的用户活动数据 (ProcessedUserActivity)
- 对原始数据进行清洗、去重、会话识别等处理
- 为每个用户行为打上标签，如是否为唯一访客、是否互动等
详细统计数据 (UserActivityStatistic)
- 基于处理后的数据，按用户、会话等维度生成详细的行为统计数据
- 每条记录代表一个用户在一个会话中的行为统计
汇总数据 (UserActivitySummary)
- 对详细统计数据按日期、文章等维度进行汇总
- 这就是 /v2/summary 接口查询的数据源

2.3 汇总统计方法

对于请求的时间范围内，系统会对每个匹配的记录进行如下统计：

访客统计：
- uniqueVisitors: 唯一访客数
- engaged: 互动用户数（进行了除访问外的其他行为）
- viewedProduct: 查看商品用户数
- clickedAddToCart: 点击加购按钮用户数
- clickedBuyNow: 点击立即购买按钮用户数
- initiatedCheckout: 发起结账流程用户数
- addedToCart: 添加到购物车用户数
- placedOrder: 下单用户数
- orderQuantity: 订单数量
分布统计：
- device: 不同设备类型的访问次数分布
- platform: 不同平台的访问次数分布
- ui: 不同UI组件的交互次数分布

3. 示例数据结构

查询返回的数据结构类似于：

{
  "uniqueVisitors": 1250,
  "engaged": 860,
  "viewedProduct": 420,
  "clickedAddToCart": 180,
  "clickedBuyNow": 95,
  "initiatedCheckout": 150,
  "addedToCart": 210,
  "placedOrder": 75,
  "orderQuantity": 92,
  "device": {
    "Windows": 620,
    "Android": 380,
    "iOS": 250
  },
  "platform": {
    "Facebook": 780,
    "Instagram": 320,
    "TikTok": 150
  },
  "ui": {
    "button_add_to_cart": 180,
    "button_buy_now": 95,
    "product_image": 420
  }
}

4. 总结

/v2/summary 接口通过 MongoDB 的聚合管道功能，对预处理好的汇总数据进行二次聚合计算，得出指定时间范围和条件下的统计数据。这种方式避免了每次请求都进行大量的实时计算，大大提高了查询性能。

query_and_statistics