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;
  }