← 返回文档导航
📝 设计稿 · 已把业务方 spec + 两张设计图整理成数据模型/流程/收入分类,并对照现状标出差距 · 确认后分期实现(动到返佣计算,先对齐再写代码)
本稿覆盖 4 件相互关联的事:① 返佣基金活动、② 前 x 单返佣倍率券活动、③ 单笔返佣的"组成拆解"、④ 收益卡 + 收入明细 的金额与分类展示。
其中 ③ 依赖 ①②:先让每单把"基础 + 各活动增量"算出来并分项落库,③ 才有东西可拆。
⚠ 这些都改到钱的计算,且基金"计算方式随时可能调整"——所以按可配 / 可插拔设计。
一、收益卡 金额逻辑
| 字段 | 口径 |
| 预估总收入 | 待处理收入 + 已确认收入(钱包 PENDING + AVAILABLE 之和) |
| 今日收入 | 用户今日产生的所有收入(不分待处理/已确认,按当日入账时间) |
| 今日收入(截图 Rp 23.00) | = 当日所有类型收入合计 |
| 可提现金额 | 钱包 AVAILABLE(已确认且未提现),为 0 时「去提现」置灰 |
二、收入明细 页面结构
① 待处理收入(顶部展示总额)
1.1 个人收入 个人 = 个人购物返现 + 邀请/活动奖励
1.2 联盟收入 联盟 = 按等级展示联盟全部收入(普通 User 不展示此模块)
② 已确认收入(顶部展示总额 · 下分 Tab)
2.1 全部
2.2 返现
2.2.1 用户购物返现 个人
2.2.2 直属销售佣金 联盟(仅 Agent / Partner)
2.2.3 间接佣金 联盟(仅 Partner)
2.3 奖励
2.3.1 参加活动 个人
2.3.2 课程直接推荐 联盟(仅 Partner)
2.3.3 课程间接推荐 联盟(仅 Partner)
2.3.4 团队佣金 联盟(仅 Partner)
2.3.5 TPB 培育奖 联盟(仅 Partner)
2.4 提现
📌 每一笔记录都带类型标签(见下表);列表按 Tab(全部/返现/奖励/提现)过滤;联盟收入相关项对普通 User 隐藏。这是一个"统一收入流水(ledger)"视图——把现有各 reward 类型 + 提现汇到一条时间线。
三、收入类型总表(taxonomy → 现状映射)
| 收入类型 | 归类 | 大类 | 角色可见 | 状态轴 | 后端来源(枚举/表) | 现状 |
| 用户购物返现 | 个人 个人 | 返现 | 全部 | 待处理→已确认 | USER_CASHBACK | ✅ 有 |
| 参加活动奖励 | 个人 个人 | 奖励 | 全部 | 待处理→已确认 | activity_campaign_reward | 🟡 部分 |
| 直属销售佣金(直推) | 联盟 联盟 | 返现 | Agent / Partner | 待处理→已确认 | DIRECT_COMMISSION | ✅ 有 |
| 间接佣金 | 联盟 联盟 | 返现 | Partner | 待处理→已确认 | INDIRECT_COMMISSION | ✅ 有 |
| 课程直接推荐奖励 | 联盟 联盟 | 奖励 | 仅 Partner | 待处理→已确认 | INVITE_DIRECT_* | ✅ 已核实·受益人=Partner |
| 课程间接推荐奖励 | 联盟 联盟 | 奖励 | Partner | 待处理→已确认 | INVITE_INDIRECT_* | ✅ 已核实·受益人=Partner |
| 团队佣金(带团队奖) | 联盟 联盟 | 奖励 | Partner | 待处理→已确认 | TEAM_LEAD | ✅ 有 |
| TPB 培育奖 | 联盟 联盟 | 奖励 | Partner | 待处理→已确认 | TpbReward / STAR_UPGRADE | ✅ 有(含拆解) |
| 提现 | — 提现 | 提现 | 全部 | — | withdraw 记录 | ✅ 有 |
✅ 已核实(2026-06-05):课程直接/间接推荐奖励 走 INVITE_DIRECT_* / INVITE_INDIRECT_*(邀新购课固定奖),受益人均为 Partner——代码 CourseRewardService 用 canReceiveCommission(…, EnumSet.of(PARTNER)) 过滤;*_PARTNER vs *_AGENT 区分的是「买家购大团长课 / 小团长课」(决定金额档),不是收奖角色。「购课分佣%」是另一回事。🟡 参加活动奖励 活动返现链路仍部分实现。
四、活动① 返佣基金
规则(业务方确认)
| 项 | 规则 |
| 领取 | 新用户无上线时,输入某团长邀请码 → 补绑上线 + 领取返佣基金 |
| 基金额度 | 默认 Rp 500,000(可配)。结束条件:额度消耗完 或 超过有效期(默认 30 天),两者其一 |
| 核销方式 | 按订单核销:每产生一单都查"是否有生效基金",有则按规则算增量并扣减余额 |
| 默认计算 | 每单多返 = 10% × M(M = 该订单商品返佣金额)。⚙ 计算规则可配/可插拔,随时可调 |
| 取整 | 向上取整到 1 印尼盾(ceil 到整 IDR) |
| 叠加 | 与活动② 倍率券可叠加 |
核销流程
flowchart TD
O([产生一笔订单
商品返佣 M]):::trunk --> Q{"有生效中的返佣基金?
(未过期 且 余额 > 0)"}:::decision
Q -->|"无"| BASE[仅基础返佣]:::trunk
Q -->|"有"| CALC["按基金规则算增量
默认:+10% × M
⚙ 规则可配 / 可插拔(随时可调)
金额向上取整到 1 IDR"]:::a
CALC --> CAP{"增量 ≥ 基金余额?"}:::decision
CAP -->|"是"| TRIM["增量 = 剩余余额 → 基金清零(消耗完)"]:::a
CAP -->|"否"| DED["扣减基金余额(按单核销)"]:::a
TRIM --> REC["落 bonus 明细
type = 返佣基金增量"]:::money
DED --> REC
BASE --> SUM
REC --> SUM(["本单返佣 = 基础 + 各活动增量"]):::done
classDef trunk fill:#ffffff,stroke:#e8d9b8,color:#1a1410;
classDef decision fill:#fef3c7,stroke:#e07c00,color:#7a4f24,stroke-width:2px;
classDef a fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6;
classDef money fill:#f0fdf4,stroke:#15803d,color:#15803d;
classDef done fill:#f0fdf4,stroke:#15803d,color:#15803d;
数据模型(拟新增)
| 表/字段 | 说明 |
| rebate_fund_grant | 基金发放:user_id、inviter_user_id、total_minor(x元)、remaining_minor、rule_code(可插拔计算规则键)、valid_from、valid_to、status |
| rebate_fund_settle | 按单核销流水:fund_id、order_id、base_M_minor、bonus_minor(增量)、remaining_after |
| 配置 | rebate_fund_config:默认额度 x、有效期天数、计算规则键(默认 PCT_10_OF_M)、取整粒度(1 IDR)、封顶等(后台可配) |
五、活动② 前 x 单返佣倍率券
规则(业务方确认)
| 项 | 规则 |
| 单数 x | 默认前 3 单(后台可配) |
| 倍率序列 | 默认 第1单 ×1.2 / 第2单 ×1.3 / 第3单 ×1.5(后台可配) |
| 作用 | 对该单基础返佣放大:增量 = 基础 ×(r_n − 1);向上取整到 1 IDR |
| 发放对象 | 圈人发放(复用人标签:注册时间 / GMV / 订单数 / 多久没上线 / 多久没下单 …) |
| 叠加 | 与活动① 返佣基金可叠加 |
发放 + 计算流程
flowchart TD
SEG([圈人命中
注册时间/GMV/订单数/沉默天数…]):::ch --> ISSUE["发放「前 x 单返佣倍率券」
x 可配 · 倍率序列可配(如 1.2/1.3/1.5)"]:::a
ISSUE --> HOLD["用户持有:剩余可用单数 + 倍率序列"]:::trunk
HOLD --> O([产生第 n 单返佣]):::trunk
O --> Q{"券还有可用单数?"}:::decision
Q -->|"是"| MUL["取第 n 单倍率 r_n
倍率增量 = 基础返佣 ×(r_n − 1)
向上取整到 1 IDR · 消耗 1 单"]:::a
Q -->|"否"| ZERO[无倍率增量]:::trunk
MUL --> SUM
ZERO --> SUM(["本单返佣 = 基础 + 倍率增量 + 基金增量
(① 与 ② 可叠加)"]):::done
classDef ch fill:#eef6ff,stroke:#3b82f6,color:#1e40af;
classDef trunk fill:#ffffff,stroke:#e8d9b8,color:#1a1410;
classDef decision fill:#fef3c7,stroke:#e07c00,color:#7a4f24,stroke-width:2px;
classDef a fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6;
classDef done fill:#f0fdf4,stroke:#15803d,color:#15803d;
⚠️ 当前坑:前端首页已经在向新用户展示「1.2x / 1.3x / 1.5x 首/2/3 单」,但后端返佣计算根本没有"按第几单放大",「立即领」也是死按钮——即现在是空头承诺,本活动落地前端要接领取、后端要接计算。
🔗
三个购物激励的关系(正交叠加 · 运营层互斥 · 封顶兜底):
① 返佣基金 /
② 前x单倍率券 /
🅲 用户购物券(见
券体系设计)是
三个正交、各自独立后台开关的「促进下单」激励——
后台都开就都生效(叠加),系统侧
不写死互斥逻辑。若要「二选一 / 互斥」,由
运营在配置层保证(不对同一圈人群同时开生效)。
🛡️ 系统只保留
「单笔激励封顶」(可配)兜底:一笔订单的总激励(基础返佣 + 倍率增量 + 基金增量 + 券返现)
≤ 配置上限(按 M 的百分比或绝对额,后台可配),防止运营误配叠加导致单均成本失控——与提现风控限额同思路。
六、收入详情 / 提现详情 页面(单笔 · ③ 拆解的落地形态)
业务方设计图:详情分 收入详情 和 提现详情 两种。拆解不是金额逐项相加,而是按需显示的"标签行"——告诉用户这笔有哪些加成/来自谁,金额取最终总额。
展示规则
| 规则 | 说明 |
| 优惠券行 | 有优惠券才显示,否则不显示。如倍率券 → 1.5x Cashback |
| 活动奖励行 | 有活动加成才显示。如返佣基金 → 10% 额外返现 |
| 相关用户行 | 该笔为联盟收益时,显示一级关联用户(谁的单带来的) |
| 提现方式行 | 提现详情必显示提现方式(如 银行卡 ·7853) |
收入详情 — 字段(按需显示)
| 字段 | 内容 / 条件 |
| 金额(大字) | 该笔最终金额,如 Rp 34.455 |
| 类型(副标题) | 个人返现 / 邀请活动奖励 / 直属佣金 / 间接佣金 / 课程直接·间接推荐 / 团队佣金 / TPB 培育奖 |
| 优惠券 | 🟠 有券才显示(如 1.5x Cashback = 活动② 倍率券) |
| 活动奖励 | 🟠 有活动加成才显示(如 10% 额外返现 = 活动① 返佣基金 / 新人信用) |
| 相关用户 | 🟠 联盟收益才显示(一级关联用户名) |
| 时间 | 入账时间 |
| 交易流水 | 流水号(可复制) |
提现详情 — 字段
| 字段 | 内容 |
| 金额 / 标题 | 金额 + 「提现」 |
| 提现方式 | 必显示,如 银行卡 ·7853 |
| 时间 / 交易流水 | 同上 |
4 种样例(对齐设计图)
| 样例 | 类型 | 特有行 |
| ① 个人返现 + 倍率券 | 个人返现 | 优惠券:1.5x Cashback |
| ② 邀请活动奖励(联盟) | 邀请活动奖励 | 相关用户:用户名称 |
| ③ 提现 | 提现 | 提现方式:银行卡 ·7853 |
| ④ 个人返现 + 新人信用 | 个人返现 | 活动奖励:10% 额外返现 |
📌 数据模型:每笔记录带 type + 可选 couponLabel(倍率券)/ activityLabel(返佣基金等)/ relatedUserName(联盟一级)/ withdrawMethod(提现)+ time + txSerial。内部仍建议存各加成的数值增量(base / 倍率增量 / 基金增量,便于审计对账),但详情页只按"标签行"展示,不必把数字逐项相加给用户看。
七、我的推广联盟 / 团队
入口:收益页「我的推广联盟」——仅 Agent / Partner 可见,普通 User 不展示。展示"我推广的团队 + 联盟收入"。角色与星级(见 PRD):User / Agent 小团长(1–3 星) / Partner 大团长(1–5 星)。
页头
| 区块 | 内容 / 可见性 |
| 预估总收入 / 实际收入 | 各带说明弹窗:预估「估算仅供参考,到账前数值可能变动」;实际「已结算到账收益 / 可提现返现」。下方「今日:+RpX」 |
| 销售佣金 / 总返现联盟 | Agent / Partner 都有 |
| TPB培育奖 / 间接佣金 / 间接推荐奖 | 🟣 仅 Partner 多这三块 |
| 推广数量 | N 人 |
| Partner推广(按星 1–5) / Agent推广(按星) | 🟣 仅 Partner:按星级统计下线 Partner/Agent 数量 |
筛选 + 排序(筛选条滑动吸顶)
| 维度 | 选项 |
| 身份 Tab | 全部用户 / Partner用户 / Agent用户 / User用户 |
| 按账户星级 | User · 1–3 Star Agent · 1–5 Star Partner(多选) |
| 排序 | 预估返现联盟(升/降) · 已收到的返现(升/降) |
下线行
| 字段 | 内容 |
| 头部 | 头像 + 昵称 + WhatsApp 图标 + 角色标签(User / Agent / Partner) |
| 加入时间 | 如 06/06/2026 10:34:23 |
| 金额 | 预估推广返现 / 已到账返现 |
🟣 Agent 视图 vs Partner 视图:Partner 多「TPB培育奖 / 间接佣金 / 间接推荐奖」三块 + 「Partner/Agent 按星计数」;Agent 只有「销售佣金 / 总返现联盟」+ 下线(主要是 User)。
✅ 已定:推广联盟列表展示一级下线(我直接推广的)。接口/数据按"带 level 字段、可扩层"设计——将来最多扩到 2 级只需查询深度 1→2 + 前端加层级标签/分组,改动小。
八、实施状态 · 已交付与残留
📌
本节已回填实施进度(原标题「现状 vs 待做」):草稿期标 ❌/🟡 的项,多数已在后续迭代交付。下表「现状」列为
当前真实状态,以代码 +
功能状态总表为准。
| 模块 | 现状(已回填) | 交付内容 / 残留 |
| 收入明细页结构 + 收益卡口径 | ✅ 已交付 | income-detail:待处理[个人/联盟] + 已确认[全部/返现/奖励/提现] + 角色门 + 卡片口径,全部落地 |
| 收入类型标签 | ✅ 已交付 | 统一类型枚举 → 9 类映射,每笔带标签(personalCashback / 各 commission role / 活动 / 券) |
| 活动① 返佣基金 | ✅ 已交付 | RebateFund 表 + 按单核销 + 可插拔计算 + ceil 到 1 IDR + T1 后台可配;🔵 真实订单 e2e 待验 |
| 活动② 倍率券 | ✅ 后端 / 🔵 前端 | ActivityCampaign:券「第几单」维度 + 圈人发放 + 计算接入已建;前端领取 + 拆解「倍率增量」展示待 e2e |
| ③ 单笔拆解 / 收入·提现详情页 | ✅ 已交付 | 详情页条件行(couponLabel / activityLabel / relatedUser / withdrawMethod)落地;🔵 显式「增量」拆解行随活动 e2e 补 |
| 我的推广联盟 / 团队页 | ✅ 已交付 | 身份 Tab + 星级筛选 + 排序 + 滑动吸顶 + Agent/Partner 差异 + 下线行(昵称/加入时间/预估·已到账返现) |
✅ 分期已执行(原 P1→P2→P3 计划,留作回顾):
P1 收益展示重构(不动金额、纯展示):收入明细 + 收入·提现详情页 + 我的推广联盟/团队页 —— ✅ 已落地。
P2 活动② 倍率券(圈人发放 + 按第几单计算 + 拆解「倍率增量」+ 前端领取)—— 后端 ✅ / 前端领取 + 增量展示 🔵 待 e2e。
P3 活动① 返佣基金(补绑领取 + 基金按单核销 + 可插拔计算 + 拆解「基金增量」)—— ✅ 已落地(参数本轮迁 T1 后台可配)。
③ 单笔拆解随 P2/P3 产出:详情页条件行已通,显式「增量」行随活动 e2e 补齐。
✅ 参数已定(业务方确认):① 返佣基金默认 Rp 500,000 / 30 天;② 倍率券默认 前 3 单 ×1.2/1.3/1.5(后台可配);③ 普通 User 收入明细只显示个人收入;④ 推广联盟一级下线(预留 level,最多扩 2 级);⑤ P1→P2→P3 顺序确认 · 已实施。
🚧
真正残留(不在上表「已交付」范围):①
提现真出款 e2e(Xendit disbursement 真跑一笔,见
场景六);②
弱网错误 UX(describeApiError 接入页面);③
倍率券领取流 + 拆解「增量」展示端到端验。全盘以
功能状态总表为准。