# BeeX 邀请与返佣实现说明

更新时间：2026-07-20
适用范围：BeeX App/H5、服务端、管理后台
状态：**现行领域实现说明**。产品规则的唯一权威来源是 `BeeX-PRD-v2.0_by_hexi.html`；本文件负责说明这些规则如何在代码中落地。

## 1. 一句话模型

所有真实用户都是同一种身份 **USER**。用户之间只有**一层**邀请关系（直接邀请人 → 被邀请人）。订单产生的返佣发两处：**买家本人返现** + **直接邀请人返佣**；另有活动返现独立发放。

## 2. 返佣类型

- 本人返现 `USER_CASHBACK`：买家自己下单获得的返现。
- 直接邀请人返佣 `DIRECT_COMMISSION`：被邀请人下单时，其**直接邀请人**（depth=1）按比例分佣；乘数固定 1.0。
- 活动返现 `ACTIVITY_CASHBACK`：由活动规则引擎（GRANT_COMMISSION_BONUS 等）触发，独立配置。
- 返佣基金 `REBATE_FUND`：由活动规则发放的额外返现额度，从用户个人额度池预占、核销和退回。

## 3. 计算口径（订单返佣）

来源：`AffiliateRewardService.preview/calculateAndSave`。
1. 取佣金基数 `commissionBaseMinor`（受 `maxCommissionBaseBps` 上限约束）。
2. 买家本人返现 = 基数 × `buyer.factorBps`（默认 6000 bps）。
3. 取 `findAncestors(userId, 1)` 的**直接邀请人**；其有效则：直推返佣 = 基数 × `directUpline.factorBps`（默认 1200 bps）× 1.0。

**直接邀请人有效性**：所有真实用户默认即为有效 USER 邀请人。判定 `isEligibleDirectInviter`：
- `user_roles` 查不到该用户的行 → 按默认 USER 处理、**视为有效**（新注册用户尚未回填角色行，这一点必须成立，否则新邀请人拿不到返佣）；
- 有行 → 要求 `role=USER` 且 `status=ACTIVE` 且已生效。

口径与 `AffiliateOrderRepositoryImpl` 的 `coalesce(max(role),'USER')` 一致。

## 4. 配置来源

返佣规则从 `rule_config_versions`（rule_type=`reward`）读取，由 `RewardRuleConfigService` 维护，默认 `USER_CASHBACK 6000bps`、`DIRECT_COMMISSION 1200bps`、`REBATE_FUND`。

> ⚠️ 注意：注册流程（手机/WhatsApp/Apple/Google/TikTok 登录）当前**不会**给新用户建 `user_roles` 行。因此返佣资格判定必须容忍「无角色行=默认 USER」（见 §3）。若日后想让每个新用户都落 USER 行，需在各登录 service 注册成功后补 `upsertUserRole`。

## 5. 管理后台

返佣配置统一在「邀请分佣」入口。基础返现、直接邀请返佣和返现券按国家与订单平台分别配置冻结天数；活动返现和返佣基金使用各自活动规则的释放天数。

## 6. 校验清单（部署后）

- `select role,count(*) from user_roles group by role` → 只应有 `USER`。
- 新注册用户 A 邀请 B，B 下单 → A 有 `DIRECT_COMMISSION`、B 有 `USER_CASHBACK`。

## 7. 邀请关系建立

### 7.1 产品目标

被邀请人通过有效邀请码、邀请链接或分享承接页完成账号识别时，系统直接尝试建立一条一级邀请关系：

- 邀请人和被邀请人都必须是有效 BeeX USER；
- 禁止自己邀请自己；
- 被邀请人已有邀请人时不覆盖；
- 建立成功后永久锁定，后续分享链接不能换绑；
- 不要求被邀请人先完成首单。

所有入口复用同一个绑定服务和同一组校验，让 WhatsApp、App 邀请码和活动入口遵循同一套规则。

### 7.2 绑定时机

所有入口写正式一级邀请关系，首次绑定即永久锁定。绑定在账号识别时立即完成，订单结算不参与邀请关系的建立。

## 8. 相关配置

- `USER_CASHBACK`：买家返现比例按订单下单时间命中有效版本，释放时间按该版本中的订单平台冻结天数计算。
- `DIRECT_COMMISSION`：直接邀请人推广奖励比例，等级乘数固定为 1，释放时间与同一订单的基础返现一致。
- `maxCommissionBaseBps`：平台佣金基数相对订单 GMV 的上限。
- `REBATE_FUND` / 活动奖励：由活动编排决定领取条件、额度、比例、有效期和适用订单。

配置发布后只影响其生效时间之后的订单；订单必须保存收益快照，避免后续改配置改变历史结果。

## 9. 代码入口（收口现状）

- `AffiliateRewardService`：生成买家返现和直接邀请人返佣。
- `RewardRuleConfigService`：返佣规则从 `rule_config_versions`（rule_type=`reward`）读取。
- `InviteRelationPolicy`：允许任意 active User 作为邀请人（无 `user_roles` 行按默认 USER 处理，存在行则要求 ACTIVE）。
- `GrowthRepositoryImpl`：关系接口对外返回 `USER / 1`。

**管理后台 / App**：配置中心展示佣金系数模块；App「我的 / 邀请」展示 User 身份与当前用户的直接一级邀请关系。