🍯 BeeX 蜜源圈 · 需求与技术方案

1背景与业务目标

BeeX 已支持粘贴 TikTok Shop / Shopee 商品链接生成返佣链接。蜜源圈在此之上增加一个内容流入口,让用户更容易把高潜商品分享给朋友。业务目标:

• 运营在后台快速发布爆品推荐;
• 任意 BeeX 用户都可在 App 内一键分享爆品到 WhatsApp;
• 分享出去的是 BeeX 承接页(非平台最终返佣链接);
• 接收者点击后被引导进 BeeX 体系完成购买;
• 接收者尚未绑定邀请人时,可按一次性归因凭证绑定本次分享人;
• 商品价格/返佣/图来自平台、允许变化,不由 BeeX 手工维护。

2两条核心原则

① 蜜源圈链接 ≠ 最终购买链接

分享链接形如 https://www.beexofficial.com/h/{shareCode}（短链域名由服务端分享基础域名配置决定）,只负责:展示承接页 · 记录谁分享 · 记录谁点击 · 引导开/装 App · 在 App 内再生成最终平台返佣链接。

② 商品信息是平台快照,不是 BeeX 定价

后台保存时按原始链接解析一次商品(平台 / 商品ID / 名称 / 图 / 店铺 / 价格 / 预估返现 / 原始快照),存为快照供列表与承接页展示。平台价格/佣金/库存/上下架都可能变,故前端用「预估返现」「预计价格」表达。建议后续加定时刷新快照能力。

③ 发布前必须校验商品可用性

蜜源圈是 BeeX 官方主动推荐内容,发布前必须复用商品过滤规则。运营输入 TikTok / Shopee 原始商品链接并解析时,后端需要校验购买入口、有效价格、用户预估返现、Offer/Campaign 有效期、TikTok Campaign review_status=APPROVED、库存/售罄/店铺休假/不可购买/下架等状态。

3角色

4产品流程(4 条)

① 运营发布爆品

后台「蜜源圈」→ 新增 → 录入平台商品链接 + 一句推广文案 + ≤3 张自定义图 + 状态(草稿/已发布/已停用)→ 保存时服务端解析商品并存快照。

② 用户分享

App 底部 Tab「蜜源圈」→ 某条内容右上「分享」→ 调分享接口生成 shareCode → 拼 WhatsApp 消息(文案 + /h/{shareCode} 短链)→ 选群/联系人发送。

③ 已有 App 用户点击

WhatsApp 点链接 → 承接页(商品/图/价/预估返现/文案)→「去购买」→ 唤起 App → App 识别 shareCode → 当前用户尚无邀请人且分享人非自己 → 绑定直接邀请人 → App 调转链接口生成最终返佣链接 → 跳平台下单。

④ 新用户未装 App

承接页判断无法唤起 App → 展示下载引导 → 装 App → 首启进新用户注册(携一次性 attributionToken 或兜底邀请码)→ 尚无邀请人则绑定本次分享人 → 之后在 App 内购买时再生成自己的返佣链接。

4.1延迟归因流程图

蜜源圈分享要分清两个编号:shareCode 表示「哪一条分享内容」,attributionToken 表示「某一次点击/安装归因」。真正绑定关系发生在用户进入 App 并登录之后,由 App 调 claim 接口完成。

flowchart LR
  Admin["BeeX 运营后台"] -->|发布爆品| AdminApi["Admin API"]
  AdminApi --> ProductResolver["商品解析服务"]
  ProductResolver --> Tiktok["TikTok Shop API"]
  ProductResolver --> Shopee["Shopee Affiliate API"]
  AdminApi --> Posts[(honey_feed_posts)]

  Publisher["BeeX 用户 / 分享者"] --> AppH5["BeeX App H5 蜜源圈"]
  AppH5 --> CoreApi["Core API /api/v1/honey-feed"]
  CoreApi --> Posts
  CoreApi --> ShareLogs[(share_logs)]
  CoreApi --> ShareClicks[(share_clicks)]
  CoreApi --> Attribution[(attribution_tokens)]

  ShareLogs --> ShortPage["短链页 /h/{shareCode}"]
  ShortPage --> Landing["H5 承接页 /honey/{shareCode}"]
  Landing --> Attribution
  Landing --> NativeApp["BeeX Native App"]
  NativeApp --> ClaimApi["归因 Claim API"]
  ClaimApi --> Growth[(referral_relations)]
  NativeApp --> Affiliate["转链服务"]
  Affiliate --> Tiktok
  Affiliate --> Shopee
  Affiliate --> Orders[(affiliate_orders)]
  Orders --> Rewards["分佣结算"]
  Rewards --> Wallet[(wallet_ledger)]
  

flowchart TD
  A["用户在蜜源圈点击分享"] --> B["服务端生成 shareCode"]
  B --> C["生成 BeeX 分享链接"]
  C --> D["用户把链接发到 WhatsApp"]
  D --> E["用户点击 BeeX 分享链接"]
  E --> F["服务端记录点击并生成 attributionToken"]

  F --> G{"用户是否已安装 App"}
  G -->|已安装| H["Universal Link 打开 App 并携带 token"]
  H --> I["App 保存 attributionToken 到本地"]
  G -->|未安装| U["进入未安装 App 补充流程"]
  U --> I

  I --> J{"用户是否已登录"}
  J -->|已登录| K["App 调 claim 接口"]
  J -->|未登录| L["引导登录或注册"]
  L --> M["登录成功"]
  M --> K

  K --> N["服务端校验 attributionToken"]
  N --> O{"用户是否已有直接邀请人"}
  O -->|尚未绑定| P["绑定分享人为直接邀请人"]
  O -->|已经绑定| Q["不改变关系 只记录来源"]
  P --> R["用户点击购买"]
  Q --> R
  R --> S["App 调转链接接口"]
  S --> T["生成 TikTok 或 Shopee 返佣购买链接"]
  T --> V["跳转平台下单"]
  V --> W["订单同步回来"]
  W --> X["按用户关系和规则分佣"]
  

flowchart TD
  A["用户点击 BeeX 分享链接"] --> B["落地页生成 attributionToken"]
  B --> C{"系统平台"}

  C -->|Android| D["跳转 Google Play 并通过 Install Referrer 带 token"]
  D --> E["用户安装并打开 App"]
  E --> F["App 读取 Install Referrer"]
  F --> G["拿到 attributionToken"]

  C -->|iOS| H["跳转 App Store"]
  H --> I["用户安装并打开 App"]
  I --> J{"是否接入 MMP"}
  J -->|已接 Branch 或 AppsFlyer| K["SDK 回传 attributionToken"]
  J -->|未接 MMP| L["剪切板或弱匹配兜底"]
  K --> G
  L --> G

  G --> M["App 保存 attributionToken"]
  M --> N["用户登录或注册成功"]
  N --> O["App 调 claim 接口完成归因"]
  

5页面:App Tab / 承接页 / 短链

App 蜜源圈 Tab(底部,排首页之后)

标题「蜜源圈」+ 副标题「分享最新好货信息」+ 官方标识(BeeX 小助理)+ 发布时间 + 推广文案 + ≤3 自定义图 + 商品卡(平台图标/商品图/名称/价格/预估返现/店铺)+ 分享按钮。交互:分享(未登录引导登录)、点卡进商品详情、下拉刷新 / 上拉加载。

承接页 /honey/{shareCode}

BeeX 品牌 + 文案 + 商品图/名/价/预估返现 + 操作按钮(已装→打开 BeeX 去购买 / 未装→下载 App)。需带 Open Graph(og:title/description/image/url)供 WhatsApp 自动预览(图必须公网 HTTPS)。

服务端短链 /h/{shareCode}

输出 OG HTML 并跳转到 H5 承接页。

6管理后台

菜单「蜜源圈」。列表:商品 / 平台 / 价格 / 预估返现 / 状态 / 排序 / 文案 / 更新时间 / 操作。新增编辑字段:

保存时服务端:校验 → 识别平台 → 解析短链/跳转 → 调平台商品解析 → 存快照 → 写入/更新记录。

7数据模型

表 honey_feed_posts

分享记录复用 share_logs

蜜源圈分享时:share_type=HONEY_FEED · campaign_id=honey_feed_posts.id · share_user_id=分享人 · referral_code=分享人邀请码 · target_url=分享元数据 JSON。

8接口清单

生成分享返回示例:{shareCode, shareUrl:".../h/HXABC12345", shareMessage:"文案\n\n短链", post:{id,productName}}。

9实现状态 · 已完成 / 待完善

已完成(测试环境已部署):服务端表自动初始化 · 公开列表/详情/分享/承接接口 · /h/{shareCode} OG 短链 · H5 底部 Tab 蜜源圈 · H5 /honey/{shareCode} 承接页 · 后台「蜜源圈」菜单 + 增改发布。

待完善:

1. 后台图片上传(当前填 URL → 接 OSS 上传);
2. 商品快照定时刷新(当前仅保存时解析一次);
3. 新用户安装后延迟归因(Android Install Referrer / iOS MMP 或剪切板·弱匹配·邀请码兜底);
4. 分享效果埋点(曝光→点击→开App→生成购买链接→下单转化);
5. 内容审核(预览 / 上下架时间 / 发布人审计)。

10风险与边界

• WhatsApp 能否显图/标题取决于其抓取 BeeX 短链页 OG 标签,图必须公网 HTTPS。
• 平台商品可能下架 / 佣金价格变化 → 展示金额只能作预估。
• 未装 App 的新用户安装后无法天然保留浏览器 shareCode → 必须设计归因兜底。
• 关系保护 已有直接邀请人的用户不因点蜜源圈链接改绑,避免被恶意抢占;分享人点自己的链接不产生绑定。
• 平台未返回不可购买状态时,BeeX 只能通过黑名单、运营下架和跳转失败反馈补充拦截,不能把平台 App 内实时提示视为 BeeX 一定能提前识别的信息。

11给设计 / 给开发的重点

给设计

蜜源圈是官方推荐内容流,非普通商品列表。强化:官方感(小助理/官方标签/时间)· 内容感(文案在前、卡片在后)· 分享感(分享按钮突出)· 收益感(预估返现突出,不泄漏平台佣金比例)· 流程感(承接页明确「打开 BeeX 后购买才有返现」)。

给开发

• 分享链接只做承接 + 归因,不直接生成最终平台返佣链接;
• 最终 TikTok/Shopee 返佣链接必须在 App 内、由当前购买用户生成;
• 关系绑定只在尚无直接邀请人时发生,已有关系不覆盖;
• 平台佣金/原始数据仅后台可见,App/WhatsApp 对用户只展示 BeeX 预估返现;
• 商品快照可被后续刷新覆盖,但已发生订单的分佣仍按订单时间命中的规则计算。

本页是蜜源圈需求与技术方案的唯一维护入口。产品身份与邀请规则以 BeeX PRD v2.0 为准。相关：活动规则引擎(ECA) · 架构与部署。