BeeX 商品详情推荐搜索实现说明

1. 目标和结论

商品详情页现在不是只展示当前商品，而是要让用户在任意入口都能继续找到可购买、可返现的商品。尤其是用户粘贴的商品没有返佣、没有库存、不能转链时，不能让链路断掉，要推荐“相似可返现商品”。

当前业务为 User-only 单层邀请返佣：所有用户业务角色都是 USER，用户之间只有一层直接邀请返佣。商品详情接口中可能带有 viewer、starLevel、shareCommissionBps 等字段，前端一律把 viewer.role 按 USER 处理，starLevel 不参与收益计算；邀请人可得比例以服务端当前有效规则返回的结果为准。

2. 三类推荐场景

3. 整体调用流程

sequenceDiagram
    participant User as 用户
    participant H5 as 商品详情页
    participant API as BeeX API
    participant Cache as 本地/服务端缓存
    participant TK as TikTok APIs
    participant Shopee as Shopee API
    participant Lazada as Lazada API

    User->>H5: 打开商品详情
    H5->>API: POST /api/v1/products/resolve
    API-->>H5: 商品详情 + 用户可见返现 + 兼容用户上下文
    H5->>Cache: 读取推荐缓存
    Cache-->>H5: 先显示旧推荐(如有)
    H5->>API: POST /api/v1/products/recommendations scene=SHOP
    H5->>API: POST /api/v1/products/recommendations scene=CATEGORY
    alt 当前商品无返佣或不可转链
      H5->>API: POST /api/v1/products/recommendations scene=CATEGORY
      Note over H5,API: 后端支持 SIMILAR，但当前 H5 尚未切换
    end
    API->>TK: TikTok Campaign / Creator 搜索
    API->>Shopee: Shopee productOfferV2 搜索
    API->>Lazada: Lazada product feed/search
    API-->>H5: 推荐商品列表
    H5->>Cache: 写入 72 小时缓存

4. 接口协议

4.1 推荐接口

POST /api/v1/products/recommendations
Content-Type: application/json

4.2 SHOP 请求示例

{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "scene": "SHOP",
  "shopName": "LUNAVEE INDONESIA",
  "shopId": "749322114",
  "excludeProductId": "tiktok-1733045523587827027",
  "excludePlatformProductId": "1733045523587827027",
  "pageSize": 20
}

4.3 CATEGORY 请求示例

{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "scene": "CATEGORY",
  "categoryId": "601493",
  "categoryName": "Sabun & Sabun Mandi",
  "excludeProductId": "tiktok-1733045523587827027",
  "excludePlatformProductId": "1733045523587827027",
  "pageSize": 20
}

4.4 SIMILAR 请求示例

{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "scene": "SIMILAR",
  "productName": "Lunavée - Rose Flowers Fragrance Body Wash 400ML",
  "categoryId": "601493",
  "categoryName": "Sabun & Sabun Mandi",
  "shopName": "LUNAVEE INDONESIA",
  "excludeProductId": "tiktok-1733045523587827027",
  "excludePlatformProductId": "1733045523587827027",
  "pageSize": 20
}

5. H5 实现

商品详情页在 app/pages/product-detail.vue 内部处理三类推荐：

H5 会给推荐接口做本地缓存。缓存键包含 scene、platform、当前商品 ID、店铺、类目、商品标题和 pageSize。这样同一商品反复进入详情时，会先显示本地缓存，再后台刷新。

6. 后端实现

6.1 新增枚举

ProductRecommendationScene 现在包含：

public enum ProductRecommendationScene {
    SHOP,
    CATEGORY,
    SIMILAR
}

6.2 请求模型新增 productName

AffiliateProductRecommendationRequest 增加 productName，用于无返佣替代商品搜索。它不替代 keyword，而是在前端没有显式搜索词时作为关键词来源。

6.3 关键词生成规则

6.4 SIMILAR 的标题压缩

商品标题通常很长，比如包含促销词、规格、单位、国家名、套装词。后端不会直接拿完整标题搜索，而是用 compactSimilarKeyword() 做压缩：

1. 按字母和数字切词。
2. 转小写。
3. 过滤通用词和促销词，例如 official、shop、produk、promo、bundle、ml、gram、indonesia。
4. 过滤纯数字和过短词。
5. 最多取前 4 个核心词。

这样 Lunavée - Rose Flowers Fragrance Body Wash 400ML 会被压缩为更适合搜索的核心词，而不是把无意义规格也带到平台搜索。

6.5 关键词过滤增强

后端 filterByKeyword() 现在支持两种命中方式：

1. 完整归一化字符串包含：适合简单关键词。
2. 所有关键词 token 都命中：适合标题里有空格、横杠、标点的场景。

匹配字段包括商品名、品牌名、类目、店铺名、平台商品 ID 和 BeeX 商品 ID。这样可以避免因为 Cool-Vita、Coolvita、Cool Vita 这种标点差异导致错误 miss。

7. 平台搜索策略

7.1 TikTok

7.2 Shopee

7.3 Lazada

Lazada 当前通过 Affiliate Product Feed/Search 类能力做推荐。SIMILAR 会把压缩后的商品关键词传给 Lazada 搜索；如果 Lazada 返回的商品缺少价格、佣金或稳定跳转链接，后端会过滤或降级展示。

8. 过滤、缓存和兜底规则

8.1 过滤规则

推荐列表只应该展示能形成购买链路的商品。后端会过滤掉当前商品本身，并尽量过滤掉以下商品：

• 没有稳定购买链接的商品。
• 价格小于等于 0 的商品。
• 用户可见返现小于等于 0 的商品。
• TikTok Campaign 中 review_status != APPROVED 的商品。
• 平台返回无库存、下架、不可购买、店铺休假等明确状态的商品。

8.2 兜底规则

8.3 缓存规则

H5 对推荐结果使用本地缓存，先渲染缓存，再后台刷新。这样详情页不会因为多个推荐接口同时请求而卡住主内容。

9. 用户上下文与字段

用户上下文接口返回体示例：

GET /api/v1/growth/users/{userId}/role

商品详情返回体结构示例：

{
  "shareCommissionBps": 1200,
  "viewer": {
    "role": "USER",
    "starLevel": 1
  }
}

viewer.role 按 USER 处理，starLevel（若字段仍在）不参与收益计算。shareCommissionBps 表达当前有效的一级邀请返佣比例。

10. 代码位置和验证

10.1 后端代码

10.2 H5 代码

10.3 已做验证

• 后端：mvn -pl seahub-core -DskipTests compile 通过。
• H5：npm run build 通过。
• 代码格式：git diff --check 通过。

10.4 还需要业务测试的点

1. 用一个有返佣 TikTok 商品进入详情，确认店铺推荐、品类推荐正常出现。
2. 用一个无返佣或不可转链商品进入详情，确认 SIMILAR 能返回替代商品。
3. 用 Shopee 商品进入详情，确认有 shopId 时店铺推荐正常，没有 shopId 时不会错误兜底。
4. 用 Lazada 商品进入详情，确认能拿到的字段展示正常，拿不到返现时不展示虚假返现金额。
5. 确认详情页对 /api/v1/growth/users/{userId}/role 返回值一律按 USER 身份处理，收益以服务端当前有效规则为准。
6. 若后续把无返佣替代区切换为 SIMILAR，需单独完成 H5 接线和回归测试后再把本文状态改为“已闭环”。