## 1）BI 怎么设计（对标 Shopify/独立站“搜索/推荐”常见报表）
  Shopify 的 Search & Discovery/行为报表里，搜索常看的就是 **query、no results、no clicks、click rate、purchase rate**（会话口径漏斗）。推荐系统的看板更强调 **曝光→点击→加购→购买→收入**，并按**推荐位/算法/实验**拆解。
  
  ### 1.1 搜索 BI（核心看板）
  - **搜索总览（KPI + 漏斗）**
    - **搜索 PV/UV**：search request 次数 / 搜索用户数
    - **Click rate（会话口径，Shopify 常用）**：有点击的搜索会话 / 搜索会话
    - **ATC rate**：有加购的搜索会话 / 搜索会话
    - **Purchase rate（会话口径，Shopify 常用）**：有购买的搜索会话 / 搜索会话
    - **结果曝光 CTR（结果口径）**：点击次数 / 结果曝光次数（更适合诊断排序/样式）
    - **延迟&稳定性**：P50/P95 搜索耗时、错误率、空响应率
  
  - **Query 分析（运营/选品/词库最常用）**
    - **高热搜索词**：按搜索 UV、曝光 UV、点击 UV、购买 UV 排序
    - **飙升词/新词**：与过去 \(7/14/28\) 天对比的增速
    - **无结果 query**（no results）
    - **有结果但无点击 query**（no clicks）——强信号：相关性差/图片价位不吸引/首屏无货等
    - **建议词（suggestion）**：suggest 点击发起的搜索占比、suggest→点击/购买转化
  
  - **结果质量诊断（给算法/工程用）**
    - **点击位置分布**：position=1/2/3… 的点击占比（反推排序质量）
    - **类目/品牌/价格带分布**：哪些 query 对哪些类目贡献转化
    - **筛选/排序使用率**：filter 使用率、排序切换率、filter 后的 CTR/CVR 变化
  
  - **用户与渠道拆解（增长/产品用）**
    - **新/老客**、地域、语言、设备、来源（自然/广告/社媒）
    - **页面维度**：首页搜索框 / 搜索页 / 分类页搜索 / 详情页内搜索等
  
  - **Session/链路回放（你提到的 track_id/trace_id）**
    - 单用户或单 trace：**搜索→换词→曝光→点击→详情→加购→支付**
    - 支持按 **trace_id** 串联一次“搜索请求”与后续行为（你们文档也强调这一点）
  
  > 参考：Shopify 官方对搜索分析的核心指标包括 click rate、purchase rate、queries、no results、no clicks（见 [Shopify Search & Discovery analytics](https://help.shopify.com/en/manual/online-store/storefront-search/search-and-discovery-analytics)）。
  
  ### 1.2 推荐 BI（核心看板）
  - **推荐位总览（按 placement/module）**
    - **Impressions/Clicks/CTR**
    - **ATC、Purchase、Revenue**
    - **Revenue per impression / per click**
    - **AOV（推荐归因订单）**
    - **覆盖与多样性**：覆盖商品数、长尾曝光占比、重复率（避免“只推爆款”）
  
  - **按算法/实验拆解**
    - 算法版本（model_version/strategy_id）
    - 实验（experiment_id/variant_id）
    - **Lift（增量）**：相对对照组的 CTR/CVR/Revenue uplift（最好有 holdout）
  
  - **健康度与风控**
    - 缺货/下架命中率、被过滤原因分布（无库存/不可售/地域不发货）
    - 冷启动占比（新用户/新商品）与表现
  
  ---
  
  ## 2）数据层面的设计（埋点→数仓→指标→推荐特征）
  你们已有统一事件骨架的方向（`tenant_id / session_id / trace_id / event(oneof)`）。建议在数据层分成 **ODS（原始）→DWD（清洗明细）→DWS（汇总）→ADS（看板语义层）**，同时给推荐做 **离线+在线特征库**。
  
  ### 2.1 关键 ID 设计（决定 BI/推荐能否串起来）
  - **tenant_id**：多租户隔离必备（所有表分区/主键都带）
  - **user_key**：归一后的用户主键（优先 login/user_id；否则 anonymous_id/cookie_id）
  - **session_id**：会话（SDK 产生或用 30min inactivity 规则补齐）
  - **trace_id（最重要）**：一次搜索/一次推荐刷新生成一个，后续点击/详情/加购尽量继承
  - **request_id**：后端请求日志关联（用于延迟、错误、召回/排序 debug）
  - **order_id/cart_id/item_id(sku/spu)**：交易与商品归因
  
  ### 2.2 ODS：原始事件（“可回放、可重放”）
  - `ods_ua_event_raw`
    - tenant_id, event_time, received_time
    - identities（原始字段：distinct_id/login_id/anonymous_id/cookie_id…）
    - page/device/geo/referrer
    - trace_id, session_id, experiment 信息
    - event_name + properties（原始 JSON，保留全量）
  
  > 你现在的 `$pageview/$WebClick` 自动采集能覆盖点击和页面，但 **推荐/搜索“曝光”必须补埋点**（否则 CTR、归因、训练样本都会缺）。
  
  ### 2.3 DWD：清洗后的事实表（BI/训练统一口径）
  建议把“强分析对象”拆成事实表（便于 join、去重、做漏斗）：
  
  - **搜索域**
    - `dwd_search_request`：一次“搜索结果刷新/请求”的主表（强烈建议：**每次请求一个 request_id，同时每次请求一个 trace_id**）
      - **用途**：search PV/UV、零结果、延迟、query 聚合、会话口径漏斗分母（search_session）
      - **主键建议**：`(tenant_id, request_id)`
      - **核心索引建议**：
        - `(tenant_id, created_at)`
        - `(tenant_id, user_key, created_at)`
        - `(tenant_id, query_normalized, created_at)`
        - `(tenant_id, trace_id)`（用于 join 曝光/点击）
        - `(tenant_id, search_session_id, created_at)`
      - **字段建议（MySQL 参考类型，可按你们存储调整）**
        - `tenant_id` VARCHAR(64) NOT NULL：店铺/租户
        - `request_id` VARCHAR(64) NOT NULL：该次搜索请求唯一 ID（前端生成或后端返回）
        - `trace_id` VARCHAR(64) NOT NULL：该次搜索链路 ID（一次结果集 = 一个 trace）
        - `session_id` VARCHAR(64) NULL：访问会话（30min inactivity）
        - `search_session_id` VARCHAR(64) NULL：搜索会话（一次“找东西”的连续过程）
        - `user_id` VARCHAR(64) NULL：登录用户 ID
        - `anonymous_id` VARCHAR(64) NULL：匿名用户（cookie 级稳定）
        - `user_key` VARCHAR(64) NOT NULL：归一用户主键（ETL 生成）
        - `query` TEXT NOT NULL：原始 query
        - `query_normalized` VARCHAR(512) NOT NULL：归一化 query（聚合用）
        - `is_suggestion` TINYINT NOT NULL DEFAULT 0：是否由 suggestion 触发
        - `suggestion_text` VARCHAR(512) NULL：命中的 suggestion（如有）
        - `page_number` INT NOT NULL DEFAULT 1：翻页页码（1-based）
        - `sort` VARCHAR(64) NULL：排序方式（如 relevance/price_asc/…）
        - `filters_json` JSON NULL：结构化筛选条件（原子字段更好；JSON 为起步方案）
        - `filters_hash` CHAR(32) NULL：filters 归一化后的 hash（便于聚合/去重）
        - `results_count` INT NOT NULL DEFAULT 0：总命中数
        - `returned_count` INT NULL：本页返回数量（page size）
        - `latency_ms` INT NULL：搜索耗时
        - `is_zero_result` TINYINT NOT NULL DEFAULT 0：是否零结果（可由 results_count=0 派生）
        - `is_error` TINYINT NOT NULL DEFAULT 0：是否错误
        - `error_code` VARCHAR(64) NULL：错误码（如超时/限流等）
        - `page_type` VARCHAR(64) NULL：发生搜索的页面（home/search/pdp/collection…）
        - `referrer` TEXT NULL：来源页
        - `device_type` VARCHAR(32) NULL：pc/mobile（可从 UA 解析）
        - `country` VARCHAR(8) NULL：国家（建议由 IP->Geo 派生；避免落全量 IP）
        - `created_at` DATETIME(3) NOT NULL：事件时间（毫秒级可选）
  
    - `dwd_search_impression_item`：搜索结果“曝光明细”（**必须补**，否则无法算 position CTR、训练负样本）
      - **用途**：曝光 PV/UV、位置 CTR、召回/排序诊断、训练样本（曝光未点为负样本）
      - **主键建议**：`(tenant_id, trace_id, item_id, position)`（或 `(tenant_id, request_id, item_id, position)`，二选一但全局统一）
      - **核心索引建议**：
        - `(tenant_id, trace_id)`
        - `(tenant_id, request_id)`
        - `(tenant_id, item_id, exposed_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `request_id` VARCHAR(64) NOT NULL
        - `trace_id` VARCHAR(64) NOT NULL
        - `search_session_id` VARCHAR(64) NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `query_normalized` VARCHAR(512) NOT NULL
        - `item_id` VARCHAR(64) NOT NULL：spu 或 sku，需统一
        - `position` INT NOT NULL：在搜索结果中的排名（1-based）
        - `score` DOUBLE NULL：排序分（如 ES score/learning-to-rank score）
        - `price` DECIMAL(18,2) NULL：曝光时价格快照（可选但强烈建议）
        - `currency` VARCHAR(8) NULL
        - `in_stock` TINYINT NULL：曝光时库存可售快照（可选但强烈建议）
        - `exposed_at` DATETIME(3) NOT NULL：曝光时间
  
    - `dwd_search_click_item`：搜索结果点击明细（点击必须能回链到曝光/请求）
      - **用途**：click UV、CTR（曝光口径/会话口径）、位置点击分布、归因触点
      - **主键建议**：`(tenant_id, click_id)`（若无 click_id，可用 `(tenant_id, trace_id, item_id, clicked_at)` 近似）
      - **核心索引建议**：
        - `(tenant_id, trace_id)`
        - `(tenant_id, request_id)`
        - `(tenant_id, item_id, clicked_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `click_id` VARCHAR(64) NULL：点击事件唯一 ID（推荐补）
        - `request_id` VARCHAR(64) NOT NULL
        - `trace_id` VARCHAR(64) NOT NULL
        - `search_session_id` VARCHAR(64) NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `query_normalized` VARCHAR(512) NOT NULL
        - `item_id` VARCHAR(64) NOT NULL
        - `position` INT NULL：点击时该商品所在排名（无法取到则置空）
        - `clicked_at` DATETIME(3) NOT NULL
        - `target_url` TEXT NULL：点击跳转 URL（可选）
  
  - **推荐域**
    - `dwd_rec_request`：一次推荐请求/刷新主表（一次刷新 = 一个 trace_id）
      - **用途**：推荐 PV/UV、分推荐位指标、实验/版本拆解、延迟与稳定性
      - **主键建议**：`(tenant_id, request_id)`
      - **核心索引建议**：
        - `(tenant_id, created_at)`
        - `(tenant_id, placement, created_at)`
        - `(tenant_id, trace_id)`
        - `(tenant_id, algo_id, model_version, created_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `request_id` VARCHAR(64) NOT NULL
        - `trace_id` VARCHAR(64) NOT NULL
        - `session_id` VARCHAR(64) NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `placement` VARCHAR(64) NOT NULL：推荐位（home/pdp/cart/checkout/search…）
        - `module_id` VARCHAR(128) NULL：页面内模块标识（一个页面多个推荐模块）
        - `trigger_item_id` VARCHAR(64) NULL：触发商品（PDP/Cart 场景常用）
        - `candidates_count` INT NULL：候选数量
        - `returned_count` INT NULL：返回条数
        - `algo_id` VARCHAR(64) NULL：策略/算法标识（rule/i2i/embedding/…）
        - `model_version` VARCHAR(64) NULL：模型版本
        - `experiment_id` VARCHAR(64) NULL：实验 ID（如有）
        - `variant_id` VARCHAR(64) NULL：分桶/分组（如有）
        - `latency_ms` INT NULL
        - `is_error` TINYINT NOT NULL DEFAULT 0
        - `error_code` VARCHAR(64) NULL
        - `created_at` DATETIME(3) NOT NULL
  
    - `dwd_rec_impression_item`：推荐曝光明细
      - **主键建议**：`(tenant_id, trace_id, item_id, position)`
      - **核心索引建议**：`(tenant_id, trace_id)`、`(tenant_id, item_id, exposed_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `request_id` VARCHAR(64) NOT NULL
        - `trace_id` VARCHAR(64) NOT NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `placement` VARCHAR(64) NOT NULL
        - `module_id` VARCHAR(128) NULL
        - `trigger_item_id` VARCHAR(64) NULL
        - `item_id` VARCHAR(64) NOT NULL
        - `position` INT NOT NULL
        - `score` DOUBLE NULL
        - `price` DECIMAL(18,2) NULL
        - `currency` VARCHAR(8) NULL
        - `in_stock` TINYINT NULL
        - `exposed_at` DATETIME(3) NOT NULL
  
    - `dwd_rec_click_item`：推荐点击明细
      - **主键建议**：`(tenant_id, click_id)`（或 `(tenant_id, trace_id, item_id, clicked_at)`）
      - **核心索引建议**：`(tenant_id, trace_id)`、`(tenant_id, item_id, clicked_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `click_id` VARCHAR(64) NULL
        - `request_id` VARCHAR(64) NOT NULL
        - `trace_id` VARCHAR(64) NOT NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `placement` VARCHAR(64) NOT NULL
        - `module_id` VARCHAR(128) NULL
        - `trigger_item_id` VARCHAR(64) NULL
        - `item_id` VARCHAR(64) NOT NULL
        - `position` INT NULL
        - `clicked_at` DATETIME(3) NOT NULL
  
  - **转化域（全站通用）**
    - `dwd_view_item`：商品详情页浏览（可承接 search/rec 的 trace，用于链路与兴趣序列）
      - **主键建议**：`(tenant_id, view_id)`（或 `(tenant_id, user_key, item_id, viewed_at)`）
      - **核心索引建议**：`(tenant_id, user_key, viewed_at)`、`(tenant_id, item_id, viewed_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `view_id` VARCHAR(64) NULL
        - `session_id` VARCHAR(64) NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `item_id` VARCHAR(64) NOT NULL
        - `source_type` VARCHAR(32) NULL：来源（search/rec/direct/ads/…）
        - `source_trace_id` VARCHAR(64) NULL：来源 trace（若来自 search/rec）
        - `dwell_time_ms` INT NULL
        - `viewed_at` DATETIME(3) NOT NULL
  
    - `dwd_add_to_cart`：加购事实表（全站统一）
      - **主键建议**：`(tenant_id, atc_id)`（或 `(tenant_id, user_key, item_id, added_at)`）
      - **核心索引建议**：`(tenant_id, user_key, added_at)`、`(tenant_id, item_id, added_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `atc_id` VARCHAR(64) NULL
        - `session_id` VARCHAR(64) NULL
        - `cart_id` VARCHAR(64) NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `item_id` VARCHAR(64) NOT NULL
        - `quantity` INT NOT NULL DEFAULT 1
        - `price` DECIMAL(18,2) NULL
        - `currency` VARCHAR(8) NULL
        - `source_type` VARCHAR(32) NULL：来源（search/rec/direct/…）
        - `source_trace_id` VARCHAR(64) NULL：来源 trace（若来自 search/rec）
        - `added_at` DATETIME(3) NOT NULL
        - `cart_snapshot_json` JSON NULL：购物车快照（可选，体积大时可下沉到独立表）
  
    - `dwd_purchase`：订单事实表（全站统一）
      - **主键建议**：`(tenant_id, order_id)`
      - **核心索引建议**：`(tenant_id, user_key, paid_at)`、`(tenant_id, paid_at)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `order_id` VARCHAR(64) NOT NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `currency` VARCHAR(8) NULL
        - `total_amount` DECIMAL(18,2) NULL
        - `paid_at` DATETIME(3) NOT NULL
  
    - `dwd_purchase_item`：订单明细事实表（全站统一）
      - **主键建议**：`(tenant_id, order_id, item_id)`（若一单同商品可多行，则增加 `line_id`）
      - **核心索引建议**：`(tenant_id, item_id, paid_at)`、`(tenant_id, order_id)`
      - **字段建议**
        - `tenant_id` VARCHAR(64) NOT NULL
        - `order_id` VARCHAR(64) NOT NULL
        - `line_id` VARCHAR(64) NULL
        - `user_key` VARCHAR(64) NOT NULL
        - `item_id` VARCHAR(64) NOT NULL
        - `quantity` INT NOT NULL DEFAULT 1
        - `price` DECIMAL(18,2) NULL
        - `paid_at` DATETIME(3) NOT NULL
  
    - **落库/分区建议（MySQL）**
      - 量小：按 `tenant_id` + `created_at` 索引即可
      - 量大：建议按月分表/分区（`*_202601`），或落到 ClickHouse/ES/湖仓；DWD 保持明细可追溯，DWS/ADS 做聚合提速
  
  - **归因桥（可选但强烈建议）**
    - `dwd_attribution_touch`
      - order_id, item_id, last_touch_trace_id, touch_type(search/rec), touch_time, window（如 7d click/1d view）
    - 这样 BI 里的“搜索带来收入/推荐带来收入”不会口径混乱。
  
  ### 2.4 DWS/ADS：面向看板的汇总层（高性能）
  - `dws_search_kpi_daily`（tenant_id, date, page_type/device/geo/new_vs_returning…）
    - search_pv, search_uv, sessions_with_click, sessions_with_atc, sessions_with_purchase
    - click_rate_session, purchase_rate_session, zero_result_rate, no_click_rate, p95_latency

  - `dws_query_daily`（tenant_id, date, query_normalized）

    - searches, exposure_uv, click_uv, purchase_uv, zero_cnt, no_click_cnt
  - `dws_rec_kpi_daily`（tenant_id, date, placement, algo_id/model_version）
    - impressions, clicks, ctr, atc, purchases, revenue, rpi（revenue per impression）
  - `dws_item_daily`（tenant_id, date, item_id）
    - search_impr/click/atc/purchase、rec_impr/click/…（用于“商品天级统计特征”与运营）
  
  ---
  
  ## 3）推荐系统依赖的数据（“能训练、能实时、能解释”）
  把特征分成 **用户/商品/上下文**，再分 **静态/快照/统计/序列（实时）**。
  
  ### 3.1 用户基础信息（dim）
  - `dim_user`：user_key、注册时间、是否会员、国家/语言、获客渠道（如可得）、新老客标签
  - 合规：只存业务需要的最小信息，敏感字段做脱敏/哈希
  
  ### 3.2 用户实时特征（在线序列 + 聚合）
  在线（Redis/Key-Value）建议保留：
  - **最近 N 次行为序列**（按时间衰减）
    - view_item_seq（最近浏览商品）
    - search_query_seq（最近搜索词/类目）
    - click_seq（点击的商品，区分来自 search/rec）
    - cart_seq、purchase_seq
  - **实时聚合**
    - 最近 1h/24h 搜索次数、点击次数、加购次数
    - 最近一次偏好类目/品牌/价格带（从序列实时计算）
  
  离线（天/小时级）输出：
  - RFM、长期偏好向量（类目/品牌 embedding）、价格敏感度、复购周期等
  
  ### 3.3 商品基础特征（静态）
  - `dim_item`（sku/spu）
    - 类目、品牌、属性（颜色/尺码/材质…）、标题/描述、价格、币种、图片
    - 文本/图片 embedding（你们已有 embeddings 模块可复用）
  
  ### 3.4 商品快照（强业务约束，必须可回溯）
  - `item_snapshot`（tenant_id, item_id, snapshot_time）
    - 库存/可售、折扣、上新、发货国家限制、活动标签
  - 推荐/搜索曝光明细里最好**写入当时的关键快照字段**（至少 in_stock、price），避免事后回算失真。
  
  ### 3.5 商品天级统计特征（训练/排序最常用）
  - 由 `dws_item_daily` 派生：
    - 1d/7d/28d：search_ctr、search_cvr、rec_ctr、rec_cvr、atc_rate、purchase_rate
    - 热度、趋势（环比/同比）、退货/取消（如可得）
    - 分 placement 的表现（同一商品在“购物车推荐”与“首页推荐”差异巨大）
  
  ### 3.6 标签（Label）与训练样本（建议一开始就定口径）
  - **曝光→点击**（CTR）标签：以 `impression_item` 为样本
  - **点击→加购/购买**（CVR/GMV）标签：以 click 或 impression 为样本，设定归因窗口
  - 负样本：同一 trace_id 下未被点击的曝光 item（更稳定）
  
  ---
  
  ## 4）你提到的两项“未完成工作”，数据层如何补齐
  - **商品曝光（搜索/推荐）**：必须新增 `ExposureEvent`（建议一屏/一次渲染批量上报 item 列表 + position + module/placement + trace_id）
  - **链路跟踪**：以 `trace_id` 为主串联；若购买跨会话严重，可在 purchase 上补 `attribution_trace_id` 或单独落 `attribution_touch` 表做归因
  
  ---
  
  如果你愿意，我可以基于你们现有 `proto`/事件骨架，把“搜索请求/曝光/点击/加购/购买/推荐请求”这几类事件的**最小必填字段清单**列成一张表（直接给前端埋点和后端 ETL 用），并给出每个指标（CTR/CVR/zero/no-click）的**精确定义与 SQL 计算口径**。