数据流向及验证方法说明

本文档解释了 /v2/summary 接口请求 POST /v2/summary?postId=6ff59f85-6b2b-486c-a7e6-33d1a1979da9&startDate=2025-11-25&endDate=2025-12-02&zoneId=America/Los_Angeles 的数据来源以及如何验证返回结果的正确性。

1. 数据源说明

1.1 查询的表(collection)

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

{environment}UserActivitySummary_{zoneId}_v2

其中：

{environment} 是环境变量，例如 prod、staging 等
{zoneId} 是时区 ID，即 America/Los_Angeles

所以实际查询的表名为：

prodUserActivitySummary_America/Los_Angeles_v2

1.2 数据生成流程

数据不是直接由用户产生，而是通过一系列处理步骤生成的：

原始用户活动数据 (UserActivity)

存储用户的各种活动，如浏览、点击等行为。
处理后的用户活动数据 (ProcessedUserActivity)

对原始数据进行清洗、会话识别等处理。
详细统计数据 (UserActivityStatistic)

基于处理后的数据，按用户、会话等维度生成详细的行为统计数据。
汇总数据 (UserActivitySummary)

对详细统计数据按日期、文章等维度进行汇总。

2. /v2/summary 接口的数据查询逻辑

该接口执行以下步骤：

根据请求参数构造查询条件：

BsonDocument query = new BsonDocument("postId", new BsonString(postId))
        .append("date", new BsonDocument("$gte", new BsonString(startDate))
        .append("$lte", new BsonString(endDate)));

在 UserActivitySummary_{zone}_v2 集合中查找匹配的文档。
使用 MongoDB 聚合管道对找到的数据进行汇总处理：
- $group: 将所有匹配的数据合并成一组
- $accumulator: 自定义累加器，对各种指标进行求和
- $project: 格式化输出结果
最终返回一个包含以下字段的对象：
- uniqueVisitors: 唯一访客数
- engaged: 互动用户数
- viewedProduct: 查看商品用户数
- clickedAddToCart: 点击加购按钮用户数
- clickedBuyNow: 点击立即购买按钮用户数
- initiatedCheckout: 发起结账流程用户数
- addedToCart: 添加到购物车用户数
- placedOrder: 下单用户数
- orderQuantity: 订单数量
- device: 设备类型分布
- platform: 平台分布
- ui: UI 版本分布

3. 如何验证数据正确性

要验证 /v2/summary 接口返回的数据是否正确，可以采用以下几种方法：

3.1 直接查询数据库

连接到 MongoDB 数据库，执行以下查询命令：

db.prodUserActivitySummary_America/Los_Angeles_v2.find({
  "postId": "6ff59f85-6b2b-486c-a7e6-33d1a1979da9",
  "date": {
    $gte: "2025-11-25",
    $lte: "2025-12-02"
  }
})

然后手动对查询结果进行汇总计算，与接口返回的结果对比。

3.2 查询上游数据并重新计算

为了更彻底地验证，还可以查询上一级的数据：

查询 UserActivityStatistic 集合中的原始数据：

db.prodUserActivityStatistic_America/Los_Angeles_v2.find({
  "postId": "6ff59f85-6b2b-486c-a7e6-33d1a1979da9",
  "date": {
    $gte: "2025-11-25",
    $lte: "2025-12-02"
  }
})

对这些数据进行手工汇总计算，验证是否与 UserActivitySummary 集合中的数据一致。

3.3 检查数据处理流程

确认数据处理流程是否正常运行：

确认定时任务是否正常执行
查看日志是否有错误信息
检查各阶段数据是否完整

4. 总结

/v2/summary 接口从 UserActivitySummary 集合中读取预处理好的汇总数据，而不是实时计算。这种设计提升了查询性能，但也意味着数据可能存在一定的延迟。如果需要验证数据准确性，可以直接查询数据库或检查上游数据源。

data_flow_explanation