分销与邀请模块业务说明
本文档描述分销体系（合作商管理、佣金、提现）和邀请有礼活动的完整链路。
帮助开发人员快速理解"为什么这样设计"以及各环节的特殊处理方式。
一、分销体系概览
合作商 (Distributor)
├── 推荐用户 (DistributorReferral)
│ └── 用户下单 → 产生佣金 (DistributorCommission)
├── 佣金余额管理
│ ├── commissionBalance（可用余额）
│ ├── frozenAmount（冻结金额）
│ ├── totalCommission（累计佣金）
│ └── totalWithdrawn（已提现总额）
├── 提现管理 (DistributorWithdrawal)
└── 月度报表 (DistributorMonthlyReport)
二、合作商管理
2.1 Distributor 实体
| 字段 |
类型 |
说明 |
| id |
Long |
雪花算法主键（@JsonSerialize(using = ToStringSerializer.class)） |
| code |
String |
合作商编码（唯一标识） |
| name |
String |
合作商名称 |
| phone |
String |
联系电话 |
| status |
Integer |
状态 |
| qrcodeContent |
String |
推广二维码内容 |
| totalReferrals |
Integer |
总推荐人数 |
| validReferrals |
Integer |
有效推荐人数 |
| commissionBalance |
BigDecimal |
可用佣金余额 |
| frozenAmount |
BigDecimal |
冻结金额 |
| totalCommission |
BigDecimal |
累计佣金总额 |
| totalWithdrawn |
BigDecimal |
已提现总额 |
| remark |
String |
备注 |
| creatorId |
Long |
创建人ID |
| creatorName |
String |
创建人姓名 |
| deleted |
Integer |
逻辑删除 |
2.2 DistributorConfig（合作商配置）
| 字段 |
说明 |
| commissionRate |
佣金比例 |
| minWithdrawAmount |
最低提现金额 |
| commissionFreezeDays |
佣金冻结天数 |
三、推荐与佣金
3.1 DistributorReferral（推荐记录）
| 关键字段 |
说明 |
| distributorId |
合作商ID |
| userId |
被推荐用户ID |
| status |
推荐状态 |
| sourceChannel |
来源渠道 |
| firstOrderAmount |
首单金额 |
| firstOrderTime |
首单时间 |
3.2 DistributorCommission（佣金记录）
| 关键字段 |
说明 |
| distributorId |
合作商ID |
| orderId |
订单ID |
| referralId |
推荐记录ID |
| orderAmount |
订单金额 |
| commissionRate |
佣金比例 |
| commissionAmount |
佣金金额 |
| status |
状态：0-待结算 1-已结算 2-已冻结 3-已取消 |
3.3 佣金产生流程
被推荐用户下单 → 订单完成（payStatus=PAID）
↓
检查该用户是否有推荐记录（DistributorReferral）
↓
计算佣金 = 订单金额 × 佣金比例
↓
创建佣金记录（DistributorCommission，status=待结算）
↓
佣金冻结期过后 → 状态变为已结算
↓
更新合作商 commissionBalance
为什么佣金有冻结期？
订单可能发生退款，如果在退款前佣金已结算并提现，会造成资金损失。冻结期（commissionFreezeDays）确保订单度过退款风险期后佣金才变为可用，这是分销业务的标准风控手段。
冻结期由 DistributorConfig.commissionFreezeDays 配置，不同合作商可设置不同天数。
四、提现管理
4.1 DistributorWithdrawal（提现记录）
| 关键字段 |
说明 |
| distributorId |
合作商ID |
| amount |
提现金额 |
| status |
状态：0-待审核 1-已通过 2-已拒绝 3-已打款 |
| bankName |
收款银行 |
| bankAccount |
收款账号 |
| accountName |
收款人姓名 |
| reviewRemark |
审核备注 |
| reviewerId |
审核人ID |
| reviewTime |
审核时间 |
4.2 提现流程
合作商申请提现
↓
检查：余额 >= 提现金额 >= 最低提现额度
↓
冻结金额（frozenAmount += amount）
↓
创建提现记录（status=待审核）
↓
运营平台审核
├── 通过 → 打款 → 状态变为已打款
│ → 扣减 commissionBalance 和 frozenAmount
│ → 累加 totalWithdrawn
└── 拒绝 → 解冻（frozenAmount -= amount）→ 状态变为已拒绝
提现审核的合规原因
分销业务涉及资金流出，需要人工审核确认：
- 防止恶意刷单后提现
- 确认银行账户信息正确
- 满足财务合规要求
提现冻结机制确保审核期间这部分金额不会被二次提现。
五、月度报表
5.1 DistributorMonthlyReport
| 关键字段 |
说明 |
| distributorId |
合作商ID |
| year / month |
年月 |
| totalOrders |
月度总订单数 |
| totalOrderAmount |
月度总订单金额 |
| totalCommission |
月度总佣金 |
| newReferrals |
月度新增推荐人数 |
| validReferrals |
月度有效推荐人数 |
六、小程序端分销接口
| 接口 |
控制器 |
说明 |
| 获取合作商信息 |
DistributorMpController |
合作商个人中心 |
| 获取推荐列表 |
DistributorMpController |
推荐用户列表 |
| 获取佣金记录 |
DistributorMpController |
佣金明细 |
| 申请提现 |
DistributorMpController |
发起提现 |
| 获取提现记录 |
DistributorMpController |
提现历史 |
| 生成推广码 |
DistributorMpController |
推广二维码 |
七、邀请有礼体系
7.1 与分销的区别
| 维度 |
分销（Distributor） |
邀请有礼（InviteActivity） |
| 角色 |
合作商（B端） |
普通用户（C端） |
| 奖励 |
佣金（金额） |
优惠券 |
| 管理 |
运营平台分配 |
用户自主参与 |
| 触发 |
被推荐人下单 |
被邀请人首单/绑定 |
为什么邀请有礼发优惠券而非佣金？
分销面向B端合作商，发佣金合理且合规。邀请有礼面向C端普通用户，发佣金涉及个人税务和支付通道问题，而发优惠券：
- 无合规风险
- 促进复购（优惠券只能在平台消费）
- 实现成本低（无需对接提现通道）
- 双向奖励（邀请人和被邀请人各得一张券）更容易实施
7.2 邀请流程
邀请人分享邀请码/链接
↓
被邀请人扫码 → 绑定邀请关系（InviteRecord，status=待激活）
↓
被邀请人完成首单（满足 minOrderAmount 条件）
↓
InviteActivityServiceImpl 处理邀请激活
↓
更新 InviteRecord.status = 已激活/已奖励
↓
发放奖励：
├── 邀请人 → 发放 couponTemplateId 对应的优惠券
└── 被邀请人 → 发放 inviteeCouponTemplateId 对应的优惠券（双向奖励时）
7.3 邀请限制
- 每日邀请上限：dailyLimit
- 活动期间总上限：totalLimit
- 首单金额门槛：requireFirstOrder + minOrderAmount
- 防重复：同一被邀请人只能被同一邀请人邀请一次
八、核心代码文件索引
| 文件 |
职责 |
haha-entity/.../Distributor.java |
合作商实体 |
haha-entity/.../DistributorCommission.java |
佣金记录实体 |
haha-entity/.../DistributorConfig.java |
合作商配置实体 |
haha-entity/.../DistributorReferral.java |
推荐记录实体 |
haha-entity/.../DistributorWithdrawal.java |
提现记录实体 |
haha-entity/.../DistributorMonthlyReport.java |
月度报表实体 |
haha-entity/.../InviteActivity.java |
邀请活动实体 |
haha-entity/.../InviteRecord.java |
邀请记录实体 |
haha-entity/.../InviteReward.java |
邀请奖励实体 |
haha-service/.../DistributorServiceImpl.java |
合作商服务 |
haha-service/.../DistributorCommissionServiceImpl.java |
佣金服务 |
haha-service/.../DistributorWithdrawalServiceImpl.java |
提现服务 |
haha-service/.../DistributorReportServiceImpl.java |
报表服务 |
haha-service/.../InviteActivityServiceImpl.java |
邀请活动服务（含激活逻辑） |
haha-admin/.../DistributorAdminController.java |
运营平台-合作商API |
haha-miniapp/.../InviteController.java |
小程序-邀请API |
