简介
本文件面向 DouPHP 小程序分销推广功能，围绕“分销关系建立、佣金计算、推广统计”三大主题，系统梳理数据模型、业务流程、接口实现与后台管理。重点说明：
- 分销层级与佣金比例配置（直推/间推）
- 分销资格申请与审核流程
- 订单支付后佣金派发与防重机制
- 小程序端分销入口、我的分销、下线列表、申请页
- 后台分销申请列表、审核、佣金记录查询
- 团队奖励与等级升级联动
- 防作弊与异常监控建议
项目结构
分销模块在前后端分层清晰：
- 小程序 API 层：入口控制器负责分流到“我的分销”或“申请页”，用户侧控制器提供列表、下线、申请等能力
- 前台服务层：封装分销数据组装、申请校验与插入
- 核心服务层：统一佣金派发、关系树维护、等级奖励百分比读取
- 订单状态流转：在订单付款/完成时触发分销奖励发放
- 后台管理：分销申请列表、审核处理、佣金记录查询
graph TB
subgraph "小程序API"
A["DistributionController<br/>入口分流"]
B["UserController<br/>我的分销/下线/申请"]
end
subgraph "前台服务"
C["Front DistributionService<br/>数据组装/申请校验"]
end
subgraph "核心服务"
D["Core DistributionService<br/>佣金派发/关系树/等级比例"]
E["WalletService<br/>钱包记账"]
end
subgraph "订单系统"
F["OrderStatusTransition<br/>付款后触发"]
end
subgraph "后台管理"
G["Admin DistributionController<br/>列表/审核/佣金记录"]
H["Admin DistributionService<br/>审核/查询"]
end
A --> B
B --> C
C --> D
F --> D
D --> E
G --> H核心组件
- 小程序分销入口：根据是否已开通分销，跳转到“我的分销”或“申请页”
- 用户侧分销服务：构建佣金列表、下线列表、申请表单与提交
- 核心分销服务：订单佣金派发、关系树登记、等级奖励百分比读取
- 订单状态过渡：在订单付款/完成时触发分销奖励发放，并做并发保护
- 后台分销管理：申请列表、审核处理、佣金记录查询
架构总览
小程序分销推广的整体调用链如下：
- 用户访问分销入口，若未成为分销员则引导至申请页；否则进入“我的分销”
- “我的分销”展示佣金明细与分页，支持按推荐人筛选
- “我的下线”展示直推与间接下级及其收益汇总
- 订单付款成功后，订单状态过渡层触发分销奖励派发，写入钱包账户
- 后台可查询分销申请、审核通过并设置分销等级，同时查看佣金记录
sequenceDiagram
participant U as "小程序用户"
participant API as "分销入口控制器"
participant UC as "用户侧控制器"
participant FS as "前台服务"
participant CS as "核心服务"
participant OS as "订单状态过渡"
participant WAL as "钱包服务"
U->>API : 访问分销入口
API-->>U : 跳转“我的分销”或“申请页”
U->>UC : 请求“我的分销”列表
UC->>FS : 构建佣金/下线数据
FS-->>UC : 返回分页数据
UC-->>U : 渲染列表
Note over OS,CS : 订单付款后触发佣金派发
OS->>CS : orderReward(订单号)
CS->>WAL : 创建直推/间推佣金记录
WAL-->>CS : 记账成功
CS-->>OS : 完成详细组件分析
小程序分销入口与用户侧接口
- 入口控制器：根据当前用户是否已有分销记录，决定跳转到“我的分销”或“申请页”
- 用户侧控制器：
- 我的分销：获取佣金列表（直推/间推），支持按推荐人 user_sn 筛选
- 我的下线：列出直推与间接下级，附带累计收益与链接
- 申请页：展示表单与附件上传位置
- 提交申请：校验业务规则（如重复申请），插入申请记录
flowchart TD
Start(["进入分销入口"]) --> Check["检查是否已开通分销"]
Check --> |是| MyDist["进入“我的分销”"]
Check --> |否| Apply["进入“申请页”"]
MyDist --> List["加载佣金列表/下线列表"]
Apply --> Submit["提交申请"]
Submit --> Validate{"校验通过?"}
Validate --> |否| Error["返回错误提示"]
Validate --> |是| Insert["插入申请记录"]
Insert --> Done(["完成"])佣金计算与派发
- 触发时机：订单进入 PAID/COMPLETED 状态时，由订单状态过渡层调用核心服务的 orderReward
- 派发范围：仅对直推（level 1）与间推（level 2）派发，超过 level 2 不派发（法律红线）
- 计算公式：佣金 = 商品金额 × 该层级奖励百分比（来自分销等级配置）
- 去重策略：以订单号为 from，结合 action、user_id、money 进行幂等判断，避免重复入账
- 并发安全：同一事务内对订单行加锁，防止回调与后台重跑导致并发问题
flowchart TD
S(["订单付款/完成"]) --> T["订单状态过渡层"]
T --> R["核心服务 orderReward"]
R --> Plan["生成直推/间推派发计划"]
Plan --> CheckLevel{"层级<=2 ?"}
CheckLevel --> |否| Skip["跳过派发"]
CheckLevel --> |是| Calc["计算佣金=商品金额×百分比"]
Calc --> Dedup{"是否已存在相同佣金记录?"}
Dedup --> |是| End(["结束"])
Dedup --> |否| Wallet["钱包服务记账"]
Wallet --> End分销关系与等级体系
- 关系树：基于用户 direct_user_id 向上追溯，记录每个祖先的层级（level 1=直推，level 2=间推，更高用于网络/报表）
- 返利封顶：尽管关系树可无限级，但返利仅派发至 level 1 与 level 2
- 等级比例：从用户关联的分销等级读取直推/间推奖励百分比
- 等级日志：后台调整等级时，若存在日志表则记录变更
classDiagram
class 分销服务 {
+orderReward(订单号)
+rewardPercent(类型, 用户ID) float
+recordRelation(用户ID, 直推上级ID)
+parents(用户ID) array
+children(父用户ID, 层级) array
+username(用户ID) string
}
class 钱包服务 {
+createMoney(用户ID, 来源, 余额, 动作, 金额, 来源单号, 下单用户ID)
}
分销服务 --> 钱包服务 : "记账"后台分销管理与审核
- 申请列表：支持按用户名、时间范围筛选，显示状态、材料、备注等
- 审核处理：通过后写入分销等级（distribution_level_id），更新分销申请状态为已审核，并记录操作时间与说明
- 佣金记录：按得主与来源会员、时间范围筛选，展示直推/间推两类佣金
sequenceDiagram
participant Admin as "管理员"
participant AC as "后台控制器"
participant AS as "后台服务"
Admin->>AC : 打开申请列表
AC->>AS : 构建列表数据
AS-->>AC : 返回分页结果
Admin->>AC : 提交审核选择等级/备注
AC->>AS : 处理申请
AS-->>Admin : 跳转回审核页推广统计与展示
- 我的分销：展示直推/间推佣金明细，支持按推荐人 user_sn 筛选
- 我的下线：展示直推与间接下级，附带累计收益与跳转链接
- 后台佣金记录：支持按得主、来源、时间范围筛选，便于审计与对账
依赖关系分析
- 小程序入口依赖用户认证与分销状态，决定路由跳转
- 用户侧控制器依赖前台服务进行数据组装
- 前台服务依赖核心服务进行佣金比例读取与关系树操作
- 订单状态过渡依赖核心服务进行佣金派发，并与钱包服务交互
- 后台控制器依赖后台服务进行列表构建与审核处理
graph LR
API["小程序API"] --> FS["前台服务"]
FS --> CS["核心服务"]
OS["订单状态过渡"] --> CS
CS --> WAL["钱包服务"]
ADMIN["后台管理"] --> ASV["后台服务"]性能与并发特性
- 并发安全：订单付款后的积分与分销奖励在同一事务中执行，并对订单行加锁，防止重复发放
- 幂等性：佣金记录以订单号为标识进行去重，确保多次触发不会重复入账
- 返利封顶：严格限制仅对直推与间推派发，降低计算复杂度与合规风险
- 分页与过滤：佣金列表与申请列表均支持分页与多条件过滤，提升查询性能
故障排查指南
- 佣金未到账：检查订单状态是否为 PAID/COMPLETED，确认是否存在直推/间推且比例大于 0；核对 money 表是否有对应记录
- 重复发放：检查是否因并发导致重复入账，确认去重逻辑（from=订单号）是否生效
- 申请无法提交：检查是否已存在申请记录；前端会返回提示信息
- 后台审核失败：确认申请状态是否为待审核或未解锁；检查等级选择与备注字段
结论
DouPHP 小程序分销推广模块实现了清晰的职责分离与严格的并发控制：
- 小程序入口与用户侧接口提供友好的分销体验
- 核心服务保证佣金派发的正确性与合规性（仅直推/间推）
- 后台管理支持申请审核与佣金审计
- 通过幂等与事务锁保障资金安全 建议在后续扩展中继续强化异常监控与风控策略，确保平台长期稳定运行。
附录
- 分销等级文案与说明参考：直推奖励、间推奖励、升级条件等
- 相关语言包键值用于界面展示与提示