logan

Appearance

双端邀请关系与返佣开发文档 ​

1. 业务边界 ​

邀请关系按平台拆成两套，但账号、邮箱、二级密码、收款地址和余额仍使用同一张 user 表。

场景关系类型被邀请人行为返佣公式入账钱包
用户邀请用户user被邀请用户购买商品订单平台手续费 × user_spread_rate邀请用户的 user_money
商户邀请商户merchant被邀请商户店铺卖出商品订单平台手续费 × spread_rate邀请商户的 freeze_money，随后按原自动解冻流程结算

同一个账号可以各有一个用户邀请人和一个商户邀请人，两类关系互不覆盖。关系写入 user_spread.relation_type，唯一约束为 user_id + relation_type。

2. 首次登录绑定规则 ​

  • 用户端分享参数：user_spread_{邀请人ID}，登录字段：user_spread_id。
  • 商户端分享参数：merchant_spread_{邀请人ID}，登录字段：merchant_spread_id。
  • 只有账号首次注册登录对应平台时，才会读取邀请参数并绑定。
  • 用户端和商户端首次注册状态分别记录在 user_platform_registered_at、merchant_platform_registered_at。
  • 同类型关系绑定后不可覆盖，禁止绑定自己并检查关系环路。
  • user_spread_switch、spread_switch 分别控制用户端、商户端邀请参数：0 关闭、1 必填、2 选填。
  • 管理员手工绑定不受“首次登录”限制，但仍遵循关系唯一、角色和防环规则。

3. 用户返佣待结算 ​

订单支付成功时，以订单 fee 和当时的 user_spread_rate 生成 user_spread_rebate 快照。状态：0 待结算、1 已结算、2 投诉冻结、-1 已取消。

退款期结束后执行 php webman spread:user-rebate-settle，将待结算金额转入邀请用户的 user_money，并记录 business_type=user_spread_rebate 的资金日志。订单退款会取消待结算记录；存在未结束投诉时定时任务暂缓结算。

数据库升级脚本：sql/2026-08-07-split-user-merchant-spread.sql。

4. 管理端 ​

配置中心的网站费率配置增加：

  • user_spread_switch、user_spread_rate：用户邀请关系及用户返佣比例。
  • spread_switch、spread_rate：商户邀请关系及商户返佣比例。

“商户管理 → 推广记录”用于统一查询两类关系，可按关系类型、邀请人 ID、被邀请人 ID 和日期筛选，也可点击“绑定邀请关系”手工新增。

管理接口：

  • POST /adminapi/merchant/spread/lists
  • POST /adminapi/merchant/spread/bind：user_id、parent_id、relation_type=user|merchant
  • POST /adminapi/merchant/spread/delete

5. 上线顺序 ​

  1. 备份数据库并执行升级 SQL。
  2. 发布服务端和管理端 Vue。
  3. 配置用户/商户邀请开关与返佣比例。
  4. 配置每分钟运行的用户返佣结算任务。
  5. 发布用户端与商户端，并配置各自的 Telegram/Web 分享根地址。