docs

tangwang
1 parent fbc7f114
Showing 11 changed files with 476 additions and 9 deletions Show diff stats
docs/UA-站内全站埋点数据结构定义.md
docs/blog/个性化.md
docs/全渠道数据整合-广告平台S2S对接手册.md -> docs/blog/全渠道数据整合、外部数据打通/全渠道数据整合-广告平台S2S对接手册.md
docs/用户匹配与外部数据打通-平台官方机制提权.md -> docs/blog/全渠道数据整合、外部数据打通/用户匹配与外部数据打通-平台官方机制提权.md
docs/竞品参考文档/Bloomreach-用户数据获取技术方案.md -> docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Bloomreach-用户数据获取技术方案.md
docs/竞品参考文档/DynamicYield-用户数据获取技术方案.md -> docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/DynamicYield-用户数据获取技术方案.md
docs/竞品参考文档/Nosto-用户数据获取技术方案.md -> docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/Nosto-用户数据获取技术方案.md
docs/竞品参考文档/prefixbox_api.md -> docs/blog/全渠道数据整合、外部数据打通/竞品参考文档/prefixbox_api.md
docs/proto/user_action.proto
@@ -0,0 +1,105 @@
+# UA 站内全站埋点数据结构定义（推荐/搜索/画像统一口径）
+
+本文档用于定义站内全量行为采集（基于“全站埋点采集”，可落地到神策 JS SDK 二次开发），覆盖推荐、搜索、画像、转化分析等核心场景。
+
+## 1. 目标与约束
+
+- **目标**：用一套统一事件模型覆盖全站行为（Pageview / Exposure / Click / View Product / Add to Cart / Purchase / Search&Filtering / Cart&Checkout）。
+- **约束**：事件需要能在“推荐/搜索请求”与“曝光-点击-加购”等链路上串联；同时需要能表达购物车/结账阶段的状态快照，用于搭配、互补、凑单、替代品推荐。
+
+## 2. 关键设计原则
+
+- **统一事件骨架**：所有事件共享同一套顶层字段（用户标识、时间、页面、trace、设备、扩展字段），业务差异放到 `event`（oneof）里。
+- **可串联**：用 `trace_id` 串联一次搜索/推荐请求与后续点击、加购、详情浏览等行为；用 `session_id` 串联同一次访问会话。
+- **可回放/可训练**：曝光事件尽量携带曝光商品列表、位置、模块；购物车/结账事件携带快照（items + 国家/币种/价格等）。
+- **停留时长口径一致**：对 `page_view`/`view_item` 统一给出 `dwell_time_ms` 的采集口径与上报方式。
+
+## 3. 顶层事件模型（概念）
+
+每条 UA 事件为一个 `UserActionEvent`，包含：
+
+- **identity**：tenant / user / anonymous / device / cookie
+- **time**：事件发生时间（毫秒时间戳）
+- **page**：页面类型、URL、来源、模块位置信息
+- **trace**：`trace_id`、`session_id`、实验信息
+- **device**：OS / UA / viewport 等
+- **event**：具体业务事件（page_view、exposure、click、view_item、search、filter、cart、checkout、purchase…）
+- **extra**：业务扩展 KV
+
+> proto 草案见 `docs/proto/user_action.proto`（本次补充文件）。
+
+## 4. 核心字段说明
+
+### 4.1 标识体系（强烈建议）
+
+- **tenant_id**：租户/店铺/商家维度的隔离主键。
+- **user_id**：登录用户 ID（未登录可为空）。
+- **anonymous_id**：匿名用户 ID（建议 Cookie 级别稳定，登录后可与 user_id 做归因合并）。
+- **device_id**：设备指纹（可选；Web 端更推荐 anonymous_id + cookie_id）。
+- **cookie_id**：首次访问生成的持久化 Cookie ID（与 anonymous_id 可以一致，也可分开）。
+
+### 4.2 trace_id（最重要）
+
+**定义**：串联一次“搜索/推荐请求（曝光）”与后续点击、详情、加购等行为的请求级会话 ID，同时用于串联内部技术模块（召回/排序/重排等子模块日志）。
+
+**规则建议**：
+
+- **新搜索/新推荐刷新**：生成新的 `trace_id`。
+- **搜索翻页**：沿用原 `trace_id`，用 `page_number` 区分页（见 `SearchEvent`）。
+- **曝光 → 点击/详情/加购**：沿用产生曝光的 `trace_id`，用于表达“该转化源自哪一次曝光/哪一次请求”。
+- **购买/支付**：如果链路被购物车长时间阻隔，串联成本高，可不强制要求延续 `trace_id`；但建议在 `PurchaseEvent.attribution_trace_id` 上尽力保留“主要来源”的 trace（若可得）。
+
+### 4.3 停留时长（dwell_time_ms）
+
+**适用事件**：
+
+- `PageViewEvent`：用户在该页面的停留时长
+- `ViewItemEvent`：用户在详情页/商品内容上的停留时长（可与 pageview 相同，也可更精细）
+
+**采集口径建议（Web）**：
+
+- 在 `pagehide` / `beforeunload` / SPA 路由切换时计算当前页面停留：`now - enter_time`。
+- 若页面进入后立即产生 `page_view`，则可在离开页面时补发一条 `page_view_end`（或在同一条事件里填充 `dwell_time_ms`，需要延迟上报）。
+- 对详情页：可按“进入详情页到离开详情页”计算；若停留时长无法计算，允许不上报或置 0，但需要在文档/ETL 中区分“缺失 vs 真实 0”。
+
+## 5. 必须覆盖的事件清单（推荐）
+
+- **Pageview**
+  - 分类页、活动页、列表页、首页、店铺页、购物车页、结账页等
+  - *最好携带该页面曝光的商品列表*（见 `ExposureEvent`，或在 `PageViewEvent.exposed_items` 携带“本页首屏/本次渲染”曝光）
+- **Exposure / Click**
+  - 列表/推荐位曝光与点击（必须包含 position / module_id / item）
+- **View product（详情页浏览）**
+  - 包含 `dwell_time_ms`
+- **Add to cart**
+  - 商品信息 + 数量 + 价格（若可得）+ 当前 cart 快照（若可得）
+- **Purchase**
+  - 订单信息（order_id / currency / total）+ 购买 items
+- **On-site Search & Filtering**
+  - 搜索词、建议词、排序、筛选条件（结构化，避免仅 JSON 字符串）
+  - 搜索结果曝光/点击建议归入 Exposure/Click，但必须携带 `search_context`
+- **Cart Logic / Checkout 状态**
+  - `cart_snapshot`：购物车当前 items 及属性（qty、price、category、brand…）
+  - `checkout`：shipping_country、step、payment_method（如可得）
+
+## 6. 落地建议（神策 JS SDK 二次开发）
+
+- **事件名**：建议统一用一个事件名（如 `ua_event`），将 `action_type`（主类型）+ `event_id`（子类型，可选）作为属性；或按神策习惯拆分事件名，但必须保证字段一致。
+- **批量上报**：曝光事件可批量（一屏/一次渲染一次上报）以降低量级；点击/加购/购买等强转化事件单条实时上报。
+- **字段扩展**：放入 `extra.debug_info`，严禁在顶层无限加字段造成版本失控。
+
+## 7. proto 草案
+
+见 `docs/proto/user_action.proto`。
+
+### 7.1 枚举命名说明（避免 proto 枚举值冲突）
+
+为兼容较旧版本 `protoc`（枚举值采用 package 级作用域），本 proto 中枚举值都带前缀：
+
+- **ActionType**：`ACTION_TYPE_*`（如 `ACTION_TYPE_PAGEVIEW`）
+- **EventId**：`EVENT_ID_*`（如 `EVENT_ID_ADD_TO_CART`）
+- **PageType**：`PAGE_TYPE_*`
+- **SortType**：`SORT_TYPE_*`
+- **CheckoutStep**：`CHECKOUT_STEP_*`
+
+
@@ -1,9 +0,0 @@
-
-| 数据类型       | 采集方式              | 应用场景       | 示例                                     |
-| ---------- | ----------------- | ---------- | -------------------------------------- |
-| **流量来源**   | UTM参数、referrer解析  | 欢迎页差异化展示   | Instagram用户看到"网红同款"，Facebook用户看到"好友购买" |
-| **页面行为**   | 前端埋点、SDK          | 实时意图判断     | 商品页停留>30秒→触发"库存紧张"提示                   |
-| **交易数据**   | 订单API、Webhook     | RFM分群、复购预测 | 近30天购买3次+客单价>\$100→标记"高价值用户"           |
-| **用户属性**   | 注册表单、CRM导入        | 精准分群       | 年龄>35岁+女性→推荐抗衰老护肤品                     |
-| **设备/环境**  | User-Agent、IP地理定位 | 体验适配       | iOS用户→App下载引导，安卓用户→Google Pay支付        |
-| **邮箱/手机号** | 登录、订阅（需授权）        | 跨渠道唤醒      | 弃购后2小时发邮件，展示"最近浏览"抽屉                   |
@@ -291,4 +291,14 @@
 - Shopify Help Center（Audiences/隐私/营销报告等）：`https://help.shopify.com/`
 - Shopify Audiences（受众类型说明等，help center 页面为准）：`https://help.shopify.com/`
+### 7.1 关联平台（广告/社交）官方入口
+
+- **Meta / Facebook**
+  - [Meta Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/)
+  - [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/)
+- **Google**
+  - [Google Ads API（Start）](https://developers.google.com/google-ads/api/docs/start)
+- **TikTok**
+  - [TikTok for Business / Marketing API Docs](https://ads.tiktok.com/marketing_api/docs)
+
@@ -406,4 +406,19 @@ SA360 çš„å…³é”®ä¸æ˜¯â€œå¤šæ‹¿åˆ°ä»€ä¹ˆç”¨æˆ·è¡Œä¸ºâ€ï¼Œè€Œæ˜¯â€œå¤šä¸€å¥—ä¼ä¸
 - **å“ˆå¸Œè§„åˆ™**ï¼šé‚®ç®±/æ‰‹æœºå·å¿…é¡»æ ‡å‡†åŒ–åŽå†å“ˆå¸Œï¼ˆSHA-256 ç‰ï¼‰ï¼Œåªåœ¨â€œç”¨äºŽåŒ¹é…â€çš„å¿…è¦èŒƒå›´å†…ä¼ è¾“
 - **æ•°æ®æœ€å°åŒ–**ï¼šä¸æ”¶é›†ä¸å¿…è¦çš„ PIIï¼›å¯¹ `referrer/landing_url` åšè„±æ•ä¸Žå‚æ•°ç™½åå•
+---
+
+## 9. å‚è€ƒé“¾æŽ¥ï¼ˆå®˜æ–¹å…¥å£ï¼‰
+
+- **Meta / Facebook**
+  - [Meta Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/)
+  - [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/)
+  - [Facebook Loginï¼ˆOAuth æ‰‹åŠ¨æµç¨‹ï¼‰](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/)
+- **Google**
+  - [Google Ads APIï¼ˆStartï¼‰](https://developers.google.com/google-ads/api/docs/start)
+  - [Google Ads API OAuthï¼ˆOverviewï¼‰](https://developers.google.com/google-ads/api/docs/oauth/overview)
+- **TikTok**
+  - [TikTok for Business / Marketing API Docs](https://ads.tiktok.com/marketing_api/docs)
+  - [TikTok Events APIï¼ˆæ–‡æ¡£å…¥å£ï¼‰](https://ads.tiktok.com/marketing_api/docs?id=1701890979375106)
+
@@ -278,4 +278,19 @@ TikTok 场景下最常见的串联信号：
 - 全量 S2S 闭环、归因标签字段、端到端案例（更偏“怎么接入平台”）：`docs/全渠道数据整合-广告平台S2S对接手册.md`
 - 本文（更偏“为什么这样能匹配、哪些字段/机制能提权匹配率、跨设备怎么做”）：`docs/用户匹配与外部数据打通-平台官方机制提权.md`
+---
+
+## 9. 参考链接（官方入口）
+
+- **Meta / Facebook**
+  - [Meta Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/)
+  - [Meta Marketing API](https://developers.facebook.com/docs/marketing-api/)
+  - [Facebook Login（OAuth 手动流程）](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/)
+- **Google**
+  - [Google Ads API（Start）](https://developers.google.com/google-ads/api/docs/start)
+  - [Google Ads API OAuth（Overview）](https://developers.google.com/google-ads/api/docs/oauth/overview)
+- **TikTok**
+  - [TikTok for Business / Marketing API Docs](https://ads.tiktok.com/marketing_api/docs)
+  - [TikTok Events API（文档入口）](https://ads.tiktok.com/marketing_api/docs?id=1701890979375106)
+
@@ -132,4 +132,16 @@ Engagement 类平台通常会：
 - 身份合并：匿名 → email/phone/customer_id（确定性优先）
 - 触达互动回流（open/click/退订）是“营销型个性化”的关键外部信号
+---
+
+## 7. 参考链接（官方/公开入口）
+
+- **Bloomreach**
+  - [Bloomreach 文档中心（入口）](https://documentation.bloomreach.com/)
+  - [Bloomreach Discovery Web SDK（公开文档）](https://bloomreach.github.io/discovery-web-sdk/index.html)
+  - [Bloomreach 官网 Docs（入口）](https://www.bloomreach.com/en/docs)
+- **关联阅读（本仓库）**
+  - `docs/全渠道数据整合-广告平台S2S对接手册.md`
+  - `docs/用户匹配与外部数据打通-平台官方机制提权.md`
+
@@ -133,4 +133,14 @@ DY 的 A/B 测试与个性化要成立，必须同时拥有：
 - purchase 必须 S2S 幂等回传（order_id）
 - 广告平台闭环：click id + S2S 回传 + 报表富化（见 `docs/用户匹配与外部数据打通-平台官方机制提权.md`）
+---
+
+## 7. 参考链接（官方/公开入口）
+
+- **Dynamic Yield**
+  - [Dynamic Yield Support Center（支持文档入口）](https://support.dynamicyield.com/hc/en-us)
+- **关联阅读（本仓库）**
+  - `docs/全渠道数据整合-广告平台S2S对接手册.md`
+  - `docs/用户匹配与外部数据打通-平台官方机制提权.md`
+
@@ -195,4 +195,17 @@ Nosto 邀ｻ莠ｧ蜩∝ｼｺ隹噪窶懆★蜷域頗邏｢荳守､ｾ莠､蟷ｳ蜿ｰ謨ｰ謐ｮ窶晢ｼ悟ｷ･遞倶ｸ企壼ｸ
 - **霄ｫ莉ｽ蜷亥ｹｶ荳ｻ體ｾ霍ｯ**啾nonymous_id 竊 customer_id/email/phone育｡ｮ螳壽ｧ莨伜
 - **蟷ｿ蜻雁ｹｳ蜿ｰ髣ｭ邇ｯ**喞lick id + S2S 蝗樔ｼ + 謚･陦ｨ蟇悟喧井ｸ崎ｦ∽ｾ晁ｵ問懷ｹｳ蜿ｰ蝗樔ｼ逕ｨ謌ｷ陦御ｸｺ窶晢ｼ
+---
+
+## 8. 蜿り得謗･亥ｮ俶婿/蜈ｬ蠑蜈･蜿｣
+
+- **Nosto**
+  - [Nosto 螳倡ｽ曽(https://www.nosto.com/)
+  - [Nosto Tech Docs域枚譯｣蜈･蜿｣云(https://docs.nosto.com/)
+  - [Nosto Support Center域髪謖∵枚譯｣蜈･蜿｣云(https://support.nosto.com/)
+  - [Nosto Magento2 髮亥ｼ貅蝉ｻ灘ｺ難ｼ云(https://github.com/Nosto/nosto-magento2)
+- **蜈ｳ閨秘隸ｻ域悽莉灘ｺ難ｼ**
+  - `docs/蜈ｨ貂驕捺焚謐ｮ謨ｴ蜷-蟷ｿ蜻雁ｹｳ蜿ｰS2S蟇ｹ謗･謇句.md`
+  - `docs/逕ｨ謌ｷ蛹ｹ驟堺ｸ主､夜Κ謨ｰ謐ｮ謇馴-蟷ｳ蜿ｰ螳俶婿譛ｺ蛻ｶ謠先揀.md`
+
@@ -0,0 +1,296 @@
+syntax = "proto3";
+
+package ua.v1;
+
+// UA: 站内全站埋点统一事件模型（推荐/搜索/画像/转化）
+//
+// 设计要点：
+// - 单条事件统一骨架（identity/time/page/trace/device + oneof event）
+// - trace_id 串联一次搜索/推荐请求产生的曝光与后续点击/详情/加购等
+// - 支持 pageview 携带曝光列表、搜索筛选上下文、购物车/结账快照、购买明细
+
+// 详细事件子类型（可选），用于更细粒度区分同一主类型下的来源/动作。
+// 例如：CLICK + SEARCH_RESULT_ITEM_CLICK / RECOMMEND_ITEM_CLICK
+enum EventId {
+  EVENT_ID_UNSPECIFIED = 0;
+
+  // 搜索相关 (1-99)
+  EVENT_ID_SEARCH_SUBMIT = 1;
+  EVENT_ID_SEARCH_SUGGESTION_CLICK = 2;
+  EVENT_ID_SEARCH_RESULT_EXPOSURE = 3;
+  EVENT_ID_SEARCH_RESULT_ITEM_CLICK = 4;
+
+  // 推荐相关 (100-199)
+  EVENT_ID_RECOMMEND_REQUEST = 100;
+  EVENT_ID_RECOMMEND_EXPOSURE = 101;
+  EVENT_ID_RECOMMEND_ITEM_CLICK = 102;
+
+  // 页面/浏览 (200-299)
+  EVENT_ID_PAGE_VIEW = 200;
+  EVENT_ID_VIEW_ITEM = 201;
+
+  // 购物车/结账 (300-399)
+  EVENT_ID_ADD_TO_CART = 300;
+  EVENT_ID_REMOVE_FROM_CART = 301;
+  EVENT_ID_CART_VIEW = 302;
+  EVENT_ID_CHECKOUT_STEP_VIEW = 330;
+  EVENT_ID_CHECKOUT_STEP_COMPLETE = 331;
+
+  // 购买 (400-499)
+  EVENT_ID_PURCHASE = 400;
+  EVENT_ID_PAYMENT_SUCCESS = 401;
+}
+
+// 行为主类型（用于统计/分流；细分用 EventId 或各事件内字段表达）
+enum ActionType {
+  ACTION_TYPE_UNSPECIFIED = 0;
+  ACTION_TYPE_PAGEVIEW = 1;
+  ACTION_TYPE_EXPOSURE = 2;
+  ACTION_TYPE_CLICK = 3;
+  ACTION_TYPE_VIEW_ITEM = 4;
+  ACTION_TYPE_ADD_TO_CART = 5;
+  ACTION_TYPE_REMOVE_FROM_CART = 6;
+  ACTION_TYPE_CART = 7;
+  ACTION_TYPE_CHECKOUT = 8;
+  ACTION_TYPE_PURCHASE = 9;
+  ACTION_TYPE_SEARCH = 10;
+  ACTION_TYPE_FILTER = 11;
+}
+
+// 页面类型（可按业务扩展；无法归类时用 OTHER 并填 page_id/page_name/url）
+enum PageType {
+  PAGE_TYPE_UNSPECIFIED = 0;
+  PAGE_TYPE_HOME = 1;
+  PAGE_TYPE_SEARCH_RESULT = 2;
+  PAGE_TYPE_CATEGORY_PAGE = 3;
+  PAGE_TYPE_COLLECTION_PAGE = 4; // 活动页/专题页/聚合页
+  PAGE_TYPE_PRODUCT_DETAIL = 5;
+  PAGE_TYPE_CART_PAGE = 6;
+  PAGE_TYPE_CHECKOUT_PAGE = 7;
+  PAGE_TYPE_ORDER_CONFIRM = 8;
+  PAGE_TYPE_MERCHANT_SHOP = 9;
+  PAGE_TYPE_OTHER = 99;
+}
+
+// 排序方式（无法覆盖时，用 CUSTOM 并填 sort_key）
+enum SortType {
+  SORT_TYPE_UNSPECIFIED = 0;
+  SORT_TYPE_RELEVANCE = 1;
+  SORT_TYPE_PRICE_ASC = 2;
+  SORT_TYPE_PRICE_DESC = 3;
+  SORT_TYPE_SALES_DESC = 4;
+  SORT_TYPE_NEWEST_DESC = 5;
+  SORT_TYPE_CUSTOM = 99;
+}
+
+// 结账阶段（可按业务扩展）
+enum CheckoutStep {
+  CHECKOUT_STEP_UNSPECIFIED = 0;
+  CHECKOUT_STEP_CART = 1;
+  CHECKOUT_STEP_SHIPPING = 2;
+  CHECKOUT_STEP_PAYMENT = 3;
+  CHECKOUT_STEP_REVIEW = 4;
+  CHECKOUT_STEP_COMPLETE = 5;
+}
+
+message UserActionEvent {
+  // 基础标识
+  string tenant_id = 1;          // 租户/店铺/商家ID
+  string user_id = 2;            // 登录用户ID（未登录可为空）
+  string anonymous_id = 3;       // 匿名用户ID（建议 cookie 级别稳定）
+  string device_id = 4;          // 设备指纹（可选）
+  string ip = 5;                 // 客户端IP（可选）
+
+  // 时间
+  int64 event_timestamp_ms = 6;  // 行为发生时刻（毫秒）
+
+  // 事件类型
+  ActionType action_type = 7;    // 行为主类型
+  EventId event_id = 8;          // 详细事件子类型（可选）
+
+  // 公共上下文
+  PageInfo page = 9;
+  TraceInfo trace = 10;
+  DeviceProfile device = 11;
+  ContextProfile context = 12;
+
+  // 具体事件载荷
+  oneof event {
+    PageViewEvent page_view = 20;
+    ExposureEvent exposure = 21;
+    ClickEvent click = 22;
+    ViewItemEvent view_item = 23;
+    SearchEvent search = 24;
+    FilterEvent filter = 25;
+    CartEvent cart = 26;
+    CheckoutEvent checkout = 27;
+    PurchaseEvent purchase = 28;
+  }
+
+  Extra extra = 90;              // 扩展字段（灵活KV）
+}
+
+message PageInfo {
+  PageType page_type = 1;
+  string page_id = 2;            // 页面唯一标识（如活动页ID/类目ID/自定义key）
+  string page_name = 3;          // 可读名称（可选）
+  string url = 4;                // 完整URL（可选）
+  string path = 5;               // path（可选）
+  string refer_url = 6;          // 来源URL（可选）
+  string lang = 7;               // 页面语言（可选）
+
+  // 模块信息：用于表达曝光/点击发生在哪个模块
+  string module_id = 20;         // e.g. "search_result", "recommend_home"
+  int32 position = 21;           // 在本屏/本列表的位置（从0开始；无则填 -1）
+}
+
+message TraceInfo {
+  // 串联一次搜索/推荐请求产生的曝光与后续点击/详情/加购
+  string trace_id = 1;
+
+  // 会话ID（同一次访问，跨多个 trace_id）
+  string session_id = 2;
+
+  // 实验/流量
+  string abtest_id = 10;         // 实验ID、流量组标识
+}
+
+message ContextProfile {
+  // 业务自定义来源（如 "shopify-web", "app", "mini-program"）
+  string source = 1;
+}
+
+message DeviceProfile {
+  string os = 1;                 // e.g. "Windows", "macOS", "iOS", "Android"
+  string user_agent = 2;         // 浏览器UA
+  string cookie_id = 3;          // 首次访问生成的持久化Cookie ID
+  int32 viewport_width = 4;
+  int32 viewport_height = 5;
+}
+
+// 商品/内容基础信息（埋点侧尽量带齐，便于离线特征构建）
+message Item {
+  string spu_id = 1;
+  string sku_id = 2;
+  string snapshot_id = 3;        // 特征快照ID（可选）
+  string category_id = 4;
+  string brand_id = 5;
+  string title = 6;
+
+  // 可选：价格与属性（若能拿到）
+  string currency = 20;          // e.g. "USD"
+  double price = 21;             // 单价
+  map<string, string> properties = 30; // 颜色/尺码等扩展属性
+}
+
+// 搜索上下文：既可作为 SearchEvent 的主体，也可挂载在 exposure/click 上
+message SearchContext {
+  string search_query = 1;
+  string suggestion_used = 2;
+  int32 result_count = 3;
+  int32 page_number = 4;         // 从1开始
+  SortType sort_type = 5;
+  string sort_key = 6;           // sort_type=CUSTOM 时使用
+  repeated FilterParam filters = 7;
+}
+
+message FilterParam {
+  string key = 1;                // e.g. "color", "price"
+  repeated string values = 2;    // e.g. ["red","blue"]
+  string op = 3;                 // e.g. "in", "range"
+}
+
+// Pageview：建议可携带“本次渲染曝光的商品列表”（用于特征与归因）
+message PageViewEvent {
+  int64 dwell_time_ms = 1;       // 停留时长（如无法计算可缺省）
+  repeated ExposedItem exposed_items = 2; // 可选：首屏/本次渲染曝光
+  SearchContext search_context = 3;       // 若该 pageview 属于搜索结果页，可填
+}
+
+// 曝光：可用于列表页/推荐位/活动页等
+message ExposureEvent {
+  repeated ExposedItem items = 1;         // 一次曝光可批量上报多商品
+  SearchContext search_context = 2;       // 搜索流量曝光需填（推荐流量可不填）
+}
+
+message ExposedItem {
+  Item item = 1;
+  int32 position = 2;             // 从0开始
+  string module_id = 3;           // e.g. "search_result"
+}
+
+// 点击：用于列表/推荐位点击商品等
+message ClickEvent {
+  Item item = 1;
+  int32 position = 2;
+  string module_id = 3;
+  SearchContext search_context = 4; // 若点击发生在搜索结果中，需填
+}
+
+// 详情页浏览：建议与 Pageview 区分，便于训练“商品级浏览”序列
+message ViewItemEvent {
+  Item item = 1;
+  int64 dwell_time_ms = 2;        // 在详情页停留（建议）
+}
+
+// 搜索：提交/改词/使用建议词等
+message SearchEvent {
+  SearchContext search_context = 1;
+}
+
+// 筛选：筛选条件变更（也可与搜索事件合并；这里单独提供便于实时系统消费）
+message FilterEvent {
+  SearchContext search_context = 1;
+}
+
+// 购物车：加购/移除/查看等，建议尽量携带快照
+message CartEvent {
+  // 动作相关商品（对 add/remove 有意义）
+  Item item = 1;
+  int32 quantity = 2;            // 加/减数量（可选）
+
+  CartSnapshot cart_snapshot = 10; // 当前购物车快照（强烈建议）
+}
+
+message CartSnapshot {
+  repeated CartItem items = 1;
+  string currency = 2;
+  double cart_total_value = 3;   // 购物车总价（可选）
+}
+
+message CartItem {
+  Item item = 1;
+  int32 quantity = 2;
+  double line_total_value = 3;   // 行总价（可选）
+}
+
+// 结账：shipping/payment 等阶段状态
+message CheckoutEvent {
+  CheckoutStep step = 1;
+  string shipping_country = 2;   // 用于跨境/税费/配送推荐
+  string payment_method = 3;     // 可选
+  CartSnapshot cart_snapshot = 10;
+}
+
+// 购买：订单完成/支付成功等
+message PurchaseEvent {
+  string order_id = 1;
+  string currency = 2;
+  double order_total_value = 3;
+  repeated PurchasedItem items = 4;
+
+  // 若能保留主要来源 trace，用于归因（可选）
+  string attribution_trace_id = 10;
+}
+
+message PurchasedItem {
+  Item item = 1;
+  int32 quantity = 2;
+  double paid_price = 3;         // 实付单价（可选）
+}
+
+message Extra {
+  map<string, string> debug_info = 1;
+}
+
+