# 14 邀请裂变与增长（for AI Agents）

> 关联代码：internal/service/fission/、internal/model/{mp_user,referral,share,guaranteed_coupon,promoter}.go、internal/service/risk/（裂变风控事件）
> 管理端页面：web/src/views/fission/；小程序页面：pages/invite/*、pages/team/index、海报 pages/share/poster/

====================================================================
1. 功能概述
====================================================================

增长体系四个子系统：
- 邀请裂变：邀请码/邀请链/下线统计（裂变运营菜单的数据看板）。
- 分享归因：全站分享带 st token，统计分享→回访→绑定→消费漏斗。
- 必中券（GuaranteedCoupon）：邀请奖励，幸运抽奖保底（见 07）。
- 好运合伙人 + CPA 推广员：分销/地推激励。

====================================================================
2. 底层逻辑
====================================================================

2.1 邀请体系（MpUser 字段）
- InviterID 直邀人 / InviteCode 我的邀请码（唯一）/ InviteDepth 深度 / InvitePath 祖先链+自己（如 "1,5,12"）。
- 绑定：新用户经分享链接（path 带 invite_code）首登时绑 ReferralLog（InviteeID 唯一，一次性绑定不可改）；老用户补绑会触发风控事件 bind_after_active。
- 分级统计：1/2/3 级邀请按 InvitePath 前缀匹配 JOIN 关系（非快照），下线消费口径同。
- 已知缺口：Order.InviterIDSnapshot 从未写入 → 订单邀请人筛选、漏斗归因 GMV、推广员佣金恒为空（运营不要依赖这些数据做决策；修复属开发任务）。

2.2 分享归因（ShareEvent/ShareVisit）
- 分享前 prepareShareToken(type,id) → POST /mp/share/event 取 st token；分享 path 拼 ?st=。
- 落地页 onLoad 调 reportShareVisit → POST /mp/share/visit 记录回访（场景 chat 会话/poster 海报/timeline 朋友圈/group 群）。
- 后台漏斗页消费：分享/访问/新增绑定/归因 GMV 四级 + 各场景转化率。

2.3 必中券（GuaranteedCoupon）
- 邀请达标发放（另有 admin_grant/activity 来源）；7 天有效，每小时 sweep 标记 expired；使用入口在幸运抽奖（过滤 A/S 级，见 07）。

2.4 好运合伙人（pages/team/index）
- 基于 drawbox.TeamLevel 等级（白银/黄金/钻石，KV drawbox.team.lv1/2/3，见 08）；展示邀请进度与等级权益。

2.5 CPA 推广员（Promoter/PromoterOrder）
- 申请：POST /mp/promoter/apply → 后台审核（PUT /admin/promoters/:id/status）+ 设置佣金率 rate（CommissionRateBps，默认 500=5%）。
- 佣金：确认收货后 pending → settled → withdrawn；提现接口为记账桩（无前端入口，未接通钱包，勿对外承诺）。

2.6 裂变风控事件（RiskLog，见 17 风控中心）
- self_invite 自邀 / circular_invite 循环邀请 / bind_after_active 老用户补绑 / invite_burst 突发邀请 / same_ip_cluster 同 IP 簇 / share_token_abuse 分享 token 滥用；severity 1 info/2 warn/3 block。

====================================================================
3. 后台操作（裂变运营菜单）
====================================================================

3.1 邀请排行 /fission/leaderboard（Leaderboard.vue）
- 日期范围 + Top N（10-500）→ 表格列：排名/用户/邀请人数/抽奖次数/有效邀请/转化率/操作；行内「详情」跳用户裂变详情页。

3.2 转化漏斗 /fission/funnel（Funnel.vue）
- 日期范围 → 4 项统计（分享/访问/新增绑定/归因 GMV）+ 场景拆分表（chat/poster/timeline/group）+ 4 条转化率。
- 注意：归因 GMV 因 InviterIDSnapshot 缺口恒为空/不准（见 2.1）。

3.3 用户裂变详情 /fission/users/:id（UserDetail.vue）
- 用户信息（邀请码/深度/直邀人可点击跳转/InvitePath）+ 1/2/3 级邀请统计卡 + 按级 Tab 成员表 + 下线最近消费/最近中奖两张表。
- 入口：邀请排行行内、小程序用户列表「更多→邀请详情」。

3.4 风控日志 /fission/risk（RiskLog.vue）
- 筛选：事件 6 种、severity、仅未处理开关；「标记已处理」。
- 与风控中心（/sprint6/risk）的日志 Tab 同源（见 17）。

3.5 推广员（智能推广/裂变数据域，API 层）
- GET /api/admin/promoters 列表；PUT /:id/status 审核；PUT /:id/rate 调佣金率（权限 promoter:*）。无独立菜单页时经 API 操作。

3.6 后台操作逻辑备注（隐藏约束，UI 不直接体现）
- 邀请排行计算：按日期范围筛选 InvitePath 匹配的下线用户数统计；Top N 范围 10-500，超出边界会被服务端裁剪。转化率 = 有效邀请数 / 邀请人数。
- 归因 GMV 恒为空/不准：因 Order.InviterIDSnapshot 从未写入（已知缺口），漏斗页的归因 GMV 字段无真实数据；运营不要基于此数据做决策。
- 推广员佣金生命周期：确认收货后佣金 pending → settled（可提现状态）→ withdrawn（已提现）；但提现接口目前为记账桩（无前端入口，未接通钱包），佣金资金未实际流转。
- 邀请绑定不可逆：ReferralLog.InviteeID 唯一索引，新用户首次经分享链接绑定后不可更改邀请人；任何「改邀请人」需求都是数据修正任务（需直接操作数据库）。
- 风控事件处理：裂变域风控日志与风控中心（/sprint6/risk）同源；severity=3（block）通常伴随自动限制动作，处理投诉先查用户当前 RiskScore。

====================================================================
4. 小程序端操作
====================================================================

- pages/invite/index/index：邀请好友页——我的邀请码、有效必中券展示、邀请历史；分享 path 带 invite_code 落首页完成绑定。
- pages/team/index：好运合伙人等级进度（白银/黄金/钻石）。
- pages/share/poster/index：canvas 合成分享海报（奖品图+小程序码，?record_id=），可保存相册；分享全站统一带 st（见 2.2）。

====================================================================
5. API 速查
====================================================================

小程序端（/api/mp）：
POST /api/mp/share/event                分享前取 st token
POST /api/mp/share/visit                落地回访上报（st 归因）
POST /api/mp/promoter/apply             申请推广员
GET  /api/mp/promoter/me|orders         我的推广员信息/佣金订单
POST /api/mp/promoter/withdraw          佣金提现（记账桩，未接通钱包）
GET  /api/mp/guaranteed-coupons/valid|history   我的必中券（见 07）

管理端（/api/admin，权限 fission:read / promoter:*）：
GET  /api/admin/fission/leaderboard|funnel|users/:id
GET  /api/admin/promoters；PUT /api/admin/promoters/:id/status|rate

====================================================================
6. 注意事项
====================================================================

- 邀请绑定一次性（InviteeID 唯一），任何「改邀请人」需求都是数据修正任务，无产品入口。
- 邀请链 InvitePath 含祖先链+自己，统计 2/3 级用它前缀匹配；曾有 GROUP BY 别名撞 mp_users.level 列的方言坑，自定义 SQL 时注意。
- 风控事件 severity=3（block）通常伴随限制动作，处理投诉先查风控日志页与用户风控分。
- 推广员提现是记账桩：佣金 withdrawn 状态仅记账，资金未走钱包/商家转账链路，勿当作可提现余额答复用户。
- 合规：分享引导文案不得承诺中奖；裂变活动设计前参考微信平台诱导分享规则（现有 encourage_share 仅一次性引导层）。
