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