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_*