🤝 推荐人招商分成系统
搭建「能绑定、能追踪、能算佣、能对账、能打款」的推荐人招商底座。推荐人推荐中国供方、日方采购方或 BTOB 大 B 渠道企业入驻平台，平台从实收佣金中让利给推荐人，复用 Stripe Connect（Stripe 连接）+ finance 模块（财务结算）+ commission 引擎（佣金计算）。
⚠️2. 模块定位：推荐人 ≠ 网红
推荐人与网红联盟是两个独立模块，业务语义完全不同。混淆会导致数据模型错位。
🛍️ 网红联盟模块
推什么：推广 BTOC 可售商品，目标是消费者进入网红店铺下单
归因维度：product scope（商品维度），按订单商品行归因
有效期：30 天归因窗口（短期）
佣金率：占销售额 3% – 30%
对标：抖音联盟 / Amazon Associates / Rakuten Affiliate
🤝 推荐人模块（本方案）
推什么：推荐企业入驻，目标是中国供方、H2B 采购商、BTOB 大 B 完成审核入驻
归因维度：seller scope（企业维度），被荐企业在有效期内产生的平台佣金订单计入；商品二维码、店铺二维码、大 B 海报扫码只作为销售入口，不自动生成新的推荐关系
有效期：12 / 6 个月（长期，按主体）
佣金率：占平台佣金的 10% – 30%（让利）
对标：SaaS referral（推荐返佣）/ 房产中介 / 猎头 / 渠道 BD
🔁 双向招商（新版已确认）：H2B 平台要求中国供方、日本采购方的开发都实行推荐人制度，即既招供方又招采购方；H2B 采购商审核通过后才可查看商城。若该企业后续关联 BTOB 大 B 能力，沿用原推荐关系，不重新归因。若下游小 B 只是通过大 B 商品/店铺二维码下单或提交采购意向，不视为推荐人拉新；只有其单独注册并被运营确认绑定时，才进入推荐人招商归因。
🔗 两模块的复用关系（底座同构）
👥3. 角色与术语（中英对照）
技术用语后括号附中文解释，确保业务、运营、开发三方语义对齐。
| 术语（EN） | 中文 | 说明 |
|---|---|---|
| Referrer | 推荐人 | 推荐企业入驻的人脉型个人/机构。不卖货、不碰商品 |
| Referred Enterprise | 被荐企业 | 由推荐人引荐入驻的中国供方、H2B 采购商或 BTOB 大 B，是招商归因主体 |
| Referral Relationship | 推荐关系 | 推荐人 ↔ 被荐企业的绑定记录，含让利比例快照 + 有效期 |
| Platform Commission | 平台佣金 | 平台从每笔订单收取的手续费（当前 5%，后续会调整） |
| Payment Processing Fee | 支付手续费 | Stripe 等支付渠道收取的费用（约 2.9%–5%，从平台佣金中扣除） |
| Net Commission | 平台实收佣金 | = 平台佣金 − 支付手续费。本方案的统一计佣基数 |
| Let-go Rate | 让利比例 | 平台从自己佣金中让给推荐人的百分比（如让 10%、30%） |
| Valid Period | 有效期 | 推荐人可享受分成的时长（促销期 12 月 / 常规期 6 月） |
| Promotion Window | 促销期 | 管理员配置的高有效期政策时段 |
| Clawback | 佣金冲回 | 订单退款时，已计佣金按比例回滚（防虚增） |
| Seller Scope | 企业维度 | 推荐人佣金覆盖被荐企业有效期内的合规订单；渠道能力开通不重新归因 |
| Share QR | 商品/店铺分享二维码 | 销售入口，不是推荐人招商二维码，不自动生成推荐关系 |
| H2B Approval Gate | H2B 审核门禁 | H2B 采购商注册后需管理员审核，通过后才可查看 H2B 商品 |
| KYC | 实名认证 | Know Your Customer，全交 Stripe 处理，平台不存敏感信息 |
| Drop / Dropshipping | 直发模式 | 订单生成时即内部分配好各方金额（网红/产品/平台/推荐人） |
| Transfer | 资金划拨 | 平台通过 Stripe Connect 把佣金划给推荐人账户 |
📊4. 市场调研（让利比例取值依据）
参照各行业分成行情，为让利比例取值提供数据支撑。注意：本方案让利比例是相对平台佣金（非销售额），下表已做口径换算。
📈 各维度分成行情对比
📋 行情数据明细与来源
| 对标维度 | 比例区间 | 有效期 | 数据来源 |
|---|---|---|---|
| B2B 引荐（只推不卖） | 5–10% 首年 | 1–2 年 | Expando / Fullcast 指南 |
| B2B 引荐（高出单介入） | 20–40%+ | 首年 | SaaStr 企业基准 |
| SaaS 推荐返佣（recurring） | 20–30% | 12 月~终身 | Rewardful(2600+项目) / Reditus |
| 电商联盟（实体商品） | 5–15%（中位 8.4%） | 按单 | Digital Applied 统计 |
| 渠道返利（让利型） | 2–5% 占销售额 | 周期 | Magentrix / 360insights |
📐 让利比例最终建议取值（点击展开理由）
促销期让利 30%（占平台佣金）：平台佣金 5% 中让出 30% = 推荐人得销售额 1.5%。鼓励开发，对推荐人有吸引力。
常规期让利 15%（占平台佣金）：推荐人得销售额 0.75%。平台可持续。
护栏：让利比例 + 支付手续费 ≤ 平台佣金率（平台不亏本，详见 §5 金额约束）。
案例：被荐企业月销 ¥100 万 → 平台佣金 ¥5 万 → 扣支付手续费 ¥3 万 → 平台实收 ¥2 万 → 促销期让利 30%×5万 = ¥1.5 万给推荐人，平台净留 ¥0.5 万。
💸5. 分账链路（金额敏感 · 4 条路线）
这是本方案核心：买家付款如何分流到 商家 / 平台 / 推荐人（以及网红、联合开店）。统一基数 = 平台实收佣金。
⚠️ 特别注意：平台佣金要扣支付手续费，让利空间有限
平台佣金（当前 5%，后续会调整）本身要扣除支付平台手续费 2.9%–5%（Stripe 国际卡约 3.15%+，不同卡段不同）。也就是说平台实收净利很薄（约 5% − 3% = 2%）。
因此：① 推荐人让利 + 平台净利 ≤ 平台佣金，让利比例必须克制；② 若让利压力增大，平台佣金率需要上调（如从 5% 调到 6%–7%），需提前与财务确认；③ 本方案让利从平台佣金出，不从销售额出，与按订单卖出价还是产品价无关——因为基数是平台自己收的那份佣金。
🏗️ 基础分账架构图
以 ¥10,000 订单（正常商品售价）、平台佣金 5%、支付手续费 3%、让利 30% 为例：商家 ¥9,500 ／ 支付手续费 ¥300 ／ 推荐人 ¥150 ／ 平台净 ¥50
🥧 平台佣金 ¥500 拆分（谁拿了）
🧮 统一计算公式
🛣️ 四条分账路线（含网红 / 联合开店组合）
① 基础路线：普通订单 + 推荐人
最简单场景：普通订单，被荐企业有推荐人。
② 网红参与：订单有网红归因 + 推荐人
同一订单同时被网红推广（CPS 带货）且企业有推荐人。网红分成从销售额出（按其佣金率），推荐人分成从平台佣金出，互不冲突。
网红佣金由卖家承担（卖家为推广商品分给网红），推荐人由平台佣金让利，两层独立。
③ 联合开店参与：联合开店订单 + 推荐人
订单走联合开店链路（供应商 ↔ 经销商分账），且其中一方企业有推荐人。联合开店内部先分供应商/经销商，平台佣金照常计，推荐人从平台佣金让利。
说明：联合开店分账逻辑不变，推荐人挂在平台佣金层（已扣支付手续费）
④ 最复杂：联合开店 + 网红 + 推荐人
联合开店订单 + 网红带货归因 + 企业有推荐人，三方叠加。网红佣金由经销商让利（经销商为推广自己商品分给网红），推荐人由平台佣金让利，两层独立互不承担。
联合开店内：供应商 ¥5,700 ＋ 经销商 ¥3,800（经销商让利网红 ¥800 → 实得 ¥3,000）。网红由经销商承担，推荐人由平台承担。
- 让利比例 + 支付手续费占比 ≤ 平台佣金率（平台不亏本）
- 计佣必须扣退款，已发分成 clawback 冲回
- 有效期外订单不计分成
- 让利比例在绑定时快照锁定，全局调价不影响已绑定关系
⏳6. 有效期与促销期策略
推荐人不能无限期分享；促销期内推荐享一年，促销期后享半年；按批次锁定；到期可续约。
📅 有效期时间轴
推荐人与企业绑定成功即开始倒计时。从绑定日算最简单，无需额外的首单检测逻辑；企业不开单也占用额度可接受（不影响平台成本，分成只在有销售时才产生）
政策按"推荐发生时"锁定，不溯及已绑定关系
管理员可手动续约（重新起算，可调让利比例，生成新记录）
📊 促销期 vs 常规期对比
🔥 促销期（Promotion Window）
- 有效期：12 个月
- 让利比例：平台佣金的 30%（鼓励开发）
- 配置：管理员后台设时间段（如 2026-07-01 ~ 2026-12-31）
- 目的：冷启动期重赏推荐人，快速扩张商家规模
📉 常规期（Regular）
- 有效期：6 个月
- 让利比例：平台佣金的 15%（平稳期）
- 触发：促销期结束后新推荐的企业
- 目的：平台可持续，鼓励持续开发
🎯 案例：推荐人推荐 21 家企业
某推荐人在促销期推荐 21 家企业。其中 2 家已到期（可续约），其余按剩余有效期递减。到期企业可由管理员手动续约（重新起算，可调比例）。
平台佣金 5% = ¥60000 推荐人王经理分成 3% = ¥36000（从平台佣金让利） 平台实得 = ¥24000（¥60000 − ¥36000） 核验：平台永不倒贴 ✓关键：分成 100% 从平台佣金让出，被荐商家智核不承担任何费用；中日资金通路各异（日方 Stripe 自动 / 中方月结手动），但分账公式一致。
🗄️7. 数据模型（ER 图）
参照网红联盟底座 + H2B / BTOB 适配。核心 5 张表，复用现有 finance / commission 引擎。
★ referral_relationship（推荐关系）是核心表，承载"让利比例快照 + 有效期 + 促销期 + 国籍结算方式 + 续约溯源"。续约时生成新记录，parent_relationship_id 指向原关系。建议增加 origin_channel / origin_context 记录来源渠道用于审计，但推荐关系仍绑定同一企业主体，不因 H2B → BTOB 关联开通而切断。
🖼️8. 各平台页面功能
推荐人绑定关系由运营人员手动建立（推荐人推荐企业后告知运营，运营在后台绑定），企业注册时邀请码为可选填写。详细原型见 referrer-prototype.html。
🤝 推荐人工作台
独立 Panel（见 §9 方案）
- 总览（推荐企业总数/累计分成）
- 我推荐的企业（详情/比例/到期日/累计销售额）
- 我的分成（明细）
- 提现（打款/提现记录）
- 账户（资料/Stripe 绑定/国籍）
⚙️ 运营管理端
admin 后台
- 推荐人管理（新建/详情/审核/启停/搜索）
- 推荐关系管理（核心）：运营绑定/续约
- 关系列表（企业↔推荐人全量）
- 促销期配置（时间段/政策）
- 结算复核（查看明细/打款）
🏬 商户注册端
vendor-panel / H2B 注册入口
- 注册时邀请码字段（可选），适用于中国供方、H2B 采购商和 BTOB 大 B 企业；H2B 采购商仍需管理员审核后才可查看商品
⚠️ 被荐企业不参与分账，无分账明细页。分成由平台在佣金层处理，与商户无关。
⚙️ 后端核心逻辑
| 模块 | 职责 | 复用 |
|---|---|---|
| 推荐关系绑定 | 运营手动绑定 + 邀请码辅助 + 一企业一推荐人 + 来源渠道审计 | 新建 |
| 有效期计算 | 促销期判定 + 绑定日起算 + 到期停止 + 续约生成新记录 | 新建 |
| 平台佣金归集 | seller scope 归集被荐企业有效期内的平台佣金；商品/店铺二维码、大 B 海报扫码不自动生成推荐关系 | 新建 |
| 分成计算 | 平台佣金 × 让利比例 + 护栏校验 | 复用 commission |
| 结算打款（日本） | Stripe 自动 Transfer（drop 直发，订单生成即分配） | 复用 Stripe + finance |
| 结算打款（中国） | 手动结算（Stripe 不支持，运营线下打款记录） | 半手动 |
🖥️9. 推荐人独立 Panel 方案（待定）
推荐人工作台不应嵌入 admin-panel（会造成权限和界面混乱）。基于现有代码架构，给出三种方案对比。
✅ 方案 A：独立 Panel
参考 vendor-panel 模式
新建独立 React 应用（如 referrer-panel），新域名指向（如 referrer.nexaai.com）。
优点：权限隔离清晰、不扰乱现有端、可独立迭代
缺点：新建工程，初期成本高
🔵 方案 B：嵌入 B2B 前台
嵌入 b2b-storefront
在 B2B 商业前台加 /referrer 路由，新起子域名指向。
优点：复用 Next.js 工程、低成本
缺点：与 B2B 买家逻辑耦合，需严格权限隔离
❌ 方案 C：嵌入 admin
已否决
嵌入 admin-panel。
问题：admin 是平台运营后台，推荐人是外部角色，混在一起会乱套、权限难管。
参考现有架构：vendor-panel（独立 React 18，:5173）、b2b-storefront（Next.js 15，:8000）、admin-panel（React 19，:9001）。各端通过 HTTP API 通信。
🚀10. 分期范围
✅ P0 · 招商分成闭环
做：推荐人档案+国籍 / 运营手动绑定 / 关系+有效期+促销期 / 来源渠道审计 / 平台佣金归集 / 分成计算 / 日本自动+中国手动结算 / 推荐 Panel（方案待定）/ 运营管理端
🔜 P1 · 优化
做：中国推荐人自动化方案（如对接跨境收款）/ 阶梯让利 / 续约自动化 / 税务配置 / 邀请码自助绑定
🔮 P2 · 进阶
做：自助入驻生态 / 推荐人排行榜 / 高级风控
✅11. 决策台
每项决策提供多个选项 + 推荐方案，可现场勾选并导出汇总。勾选状态自动保存到浏览器。