← 返回文档导航

💰 收益体系 + 两个新活动 · 设计稿

返佣基金 · 前 x 单倍率券 · 单笔返佣拆解 · 收益卡 / 收入明细 展示逻辑
📝 设计稿 · 已把业务方 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——代码 CourseRewardServicecanReceiveCommission(…, 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 接入页面);③ 倍率券领取流 + 拆解「增量」展示端到端验。全盘以功能状态总表为准。