简介
本文件面向分销平台开发者，提供分销系统的完整API参考与集成指南。内容覆盖分销商注册、审核、等级管理、佣金计算与结算、推广链接与数据统计、上下级关系维护、订单跟踪联动、提现申请与审核、业绩排行榜与激励政策，以及数据安全性与准确性保障机制。文档基于仓库中分销模块的控制器、服务与路由实现进行梳理，确保与实际代码一致。
项目结构
分销相关能力由“API层路由 + 控制器 + 前台/核心服务”构成：
- API路由负责声明式映射 /api/?route=distribution 与 /api/?route=withdraw 等入口。
- 控制器处理认证、参数校验、业务分流与响应封装。
- 前台服务负责页面数据组装（我的分销、下线列表、申请表单）。
- 核心服务承担佣金派发、关系树记录、等级升级等关键逻辑。
- 订单状态机在付款成功后触发分销奖励发放与等级升级检查。
graph TB
Client["客户端"] --> API["API路由<br/>distribution / withdraw"]
API --> DC["DistributionController<br/>入口分流"]
API --> UC["UserController<br/>会员侧分销"]
API --> WUC["Withdraw UserController<br/>会员侧提现"]
UC --> FDS["Front DistributionService<br/>列表/下线/表单"]
UC --> CDS["Core DistributionService<br/>佣金/关系/等级"]
WUC --> WS["提现服务(外部)"]
CDS --> OrderST["OrderStatusTransition<br/>付款后联动"]核心组件
- 分销入口控制器：根据是否已开通分销，跳转到“我的分销”或“申请页”。
- 会员侧分销控制器：提供我的分销列表、下线列表、申请表单与提交申请。
- 前台分销服务：构建分销资金明细、下线列表与申请表单数据。
- 核心分销服务：订单佣金派发、奖励百分比查询、上下级关系记录与查询、用户名脱敏。
- 分销等级升级服务：按累计消费自动提升分销等级并记录日志。
- 提现用户控制器：提现申请与提交流程。
架构总览
分销系统的关键流程包括：
- 分销商注册与审核：会员通过“申请”接口提交资料，后台审核后生效。
- 佣金计算与结算：订单进入已支付/已完成时，按直推与间推比例发放佣金到资金账户。
- 推广链接与统计：通过直推/间推关系与资金明细展示推广效果。
- 等级管理与升级：根据累计消费自动升级分销等级，影响后续佣金比例。
- 提现申请与审核：会员发起提现，后台审核打款。
sequenceDiagram
participant U as "会员"
participant R as "API路由"
participant C as "分销控制器"
participant S as "分销服务"
participant O as "订单状态机"
participant W as "钱包服务"
U->>R : GET /api/?route=distribution/user
R->>C : index()
C->>S : buildDistributionListData(...)
S-->>C : 资金明细/分页
C-->>U : 成功响应
U->>R : POST /api/?route=distribution/user/apply_post
R->>C : applyPost()
C->>S : validateApplyBusiness()/insertNewApplication(...)
S-->>C : 写入申请
C-->>U : 成功响应
Note over O,S : 订单PAID/COMPLETED时触发
O->>S : orderReward(order_sn)
S->>W : createMoney(direct_reward/indirect_reward)
W-->>S : 入账完成
S-->>O : 完成详细组件分析
分销商注册与审核接口
- 获取申请表单：GET /api/?route=distribution/user/apply
- 若已存在分销记录则重定向至“我的分销”。
- 返回申请表单所需字段与图片附件。
- 提交申请：POST /api/?route=distribution/user/apply_post
- 参数校验通过后，执行业务前置校验（防止重复申请），写入申请记录。
- 后台审核：通过后台分销管理界面完成（不在本API范围内）。
flowchart TD
Start(["开始"]) --> CheckExist{"是否存在分销记录?"}
CheckExist -- 是 --> Redirect["重定向到我的分销"]
CheckExist -- 否 --> ShowForm["返回申请表单数据"]
ShowForm --> Submit["POST 提交申请"]
Submit --> Validate["参数与业务校验"]
Validate --> Insert["写入申请记录"]
Insert --> End(["结束"])佣金计算规则与结算流程
- 佣金派发时机：订单进入 PAID 或 COMPLETED 时，由订单状态机调用核心服务的 orderReward。
- 派发层级限制：仅直推（level 1）与间推（level 2）可获佣金，level >= 3 不派发（法律红线）。
- 金额计算：以订单商品金额乘以对应等级的直推/间推百分比。
- 去重机制：同一订单号作为 from，避免重复发放。
- 入账方式：通过钱包服务创建资金记录，动作类型为 direct_reward / indirect_reward。
sequenceDiagram
participant OS as "订单状态机"
participant DS as "核心分销服务"
participant WAL as "钱包服务"
OS->>DS : orderReward(order_sn)
DS->>DS : 读取直推/间推用户与百分比
DS->>WAL : createMoney(user, action, amount, from)
WAL-->>DS : 入账成功
DS-->>OS : 完成推广链接生成与推广数据统计
- 推广链接：当前API未暴露“生成推广链接”的专用接口；推广关系通过 user.direct_user_id 与 distribution_relation 表维护，前端可通过“我的分销/下线”接口查看推广效果。
- 推广统计：
- 我的分销资金明细：GET /api/?route=distribution/user
- 返回直推/间推两类奖励的资金流水，支持按上级用户筛选。
- 下线列表：GET /api/?route=distribution/user/people
- 返回直推下级及其间推信息，包含累计奖励与跳转链接。
- 我的分销资金明细：GET /api/?route=distribution/user
classDiagram
class 分销控制器 {
+index(request)
+people(request)
+apply()
+apply_post(formRequest)
}
class 前台分销服务 {
+buildDistributionListData(userId, page, urlBase, userSnFilter)
+buildDistributionPeopleListData(userId, page, url)
+buildDistributionShowData(userId)
+hasApplicationRow(userId)
+validateApplyBusiness(userId)
+insertNewApplication(userId, validated)
}
分销控制器 --> 前台分销服务 : "调用"分销层级管理与上下级关系维护
- 关系记录：当会员注册或绑定推荐人时，核心服务会沿上级链向上遍历，将每个祖先按真实层级写入关系表，用于网络与报表展示。
- 查询接口：
- 上级链：core 服务提供 parents(userId)，返回按层级升序的上级集合。
- 下级集合：core 服务提供 children(parentUserId, level)，默认直推。
- 等级升级：订单完成后，系统检查累计消费是否达到下一等级条件，满足则更新用户分销等级并记录日志。
flowchart TD
A["记录关系(userId, directUserId)"] --> B{"directUserId > 0 ?"}
B -- 否 --> Z["结束"]
B -- 是 --> C["循环上溯祖先"]
C --> D{"到达深度上限或环?"}
D -- 是 --> Z
D -- 否 --> E["写入关系(user_id,parent_user_id,level)"]
E --> C分销订单跟踪与佣金自动结算机制
- 订单跟踪：订单物流与状态变更由订单模块提供；分销系统在订单状态变为 PAID/COMPLETED 时自动结算佣金。
- 自动结算：orderReward 在事务内执行，使用订单行锁防并发重复发放，并通过钱包服务入账。
sequenceDiagram
participant Admin as "管理员/系统"
participant Order as "订单服务"
participant ST as "订单状态机"
participant Dist as "分销服务"
Admin->>Order : 更新物流/状态
Order->>ST : changeStatus(PAID/COMPLETED)
ST->>Dist : orderReward(order_sn)
Dist-->>ST : 完成分销商提现申请与审核流程接口
- 获取提现申请表单：GET /api/?route=withdraw/user/apply
- 若有待处理提现申请则拒绝再次申请。
- 返回最近一次提现信息与可用余额。
- 提交提现申请：POST /api/?route=withdraw/user/apply_post
- 参数校验通过后，调用提现服务创建申请记录。
- 后台审核：通过后台提现管理界面完成（不在本API范围内）。
sequenceDiagram
participant U as "会员"
participant R as "API路由"
participant WC as "提现用户控制器"
U->>R : GET /api/?route=withdraw/user/apply
R->>WC : apply()
WC-->>U : 返回表单与余额
U->>R : POST /api/?route=withdraw/user/apply_post
R->>WC : apply_post(formRequest)
WC-->>U : 成功响应分销业绩排行榜与激励政策
- 排行榜：当前API未提供专门的排行榜接口；可通过“我的分销”资金明细与“下线”列表聚合统计，结合后台报表实现。
- 激励政策：分销等级配置与升级条件由后台管理；系统会在订单完成后自动检查并升级等级，间接体现激励效果。
安全性与准确性保障机制
- 并发安全：订单状态机在付款联动中使用行锁保护，防止重复发放佣金与积分。
- 去重机制：佣金发放以订单号为 from，避免重复入账。
- 法律合规：佣金派发层级硬封顶为2级，任何 level>=3 的路径被运行期守卫与静态扫描双重钉死。
- 数据安全：用户名与联系方式在输出时进行脱敏处理。
- 错误处理：参数校验失败与业务规则违反均返回明确的错误码与消息，便于前端提示与重试。
依赖关系分析
- 控制器依赖：
- 分销控制器依赖前台分销服务进行数据组装。
- 提现控制器依赖提现服务进行申请处理。
- 服务依赖：
- 前台分销服务依赖核心分销服务与钱包模块。
- 核心分销服务依赖钱包服务与数据库操作。
- 订单联动：
- 订单状态机在付款成功后触发分销奖励与等级升级检查。
graph LR
UC["分销用户控制器"] --> FDS["前台分销服务"]
UC --> CDS["核心分销服务"]
WUC["提现用户控制器"] --> WS["提现服务"]
CDS --> WAL["钱包服务"]
ST["订单状态机"] --> CDS性能与并发考虑
- 幂等性：佣金发放以订单号为唯一标识，避免重复入账。
- 行锁保护：订单状态机在付款联动中对订单行加锁，防止并发冲突。
- 层级限制：佣金派发仅至2级，降低计算复杂度与合规风险。
- 分页查询：资金明细与下线列表采用分页，减少单次响应体积。
故障排查指南
- 参数校验失败：检查请求参数是否符合 FormRequest 定义，关注错误码与字段错误。
- 业务规则违反：如重复申请提现或分销，检查前置校验逻辑与状态。
- 佣金未到账：确认订单状态是否为 PAID/COMPLETED，检查 orderReward 是否被调用与钱包入账是否成功。
- 等级未升级：检查累计消费是否达到升级条件，查看等级升级日志。
结论
本分销API围绕“注册申请—佣金结算—等级升级—提现”形成闭环，结合订单状态机实现自动化结算与合规控制。开发者可基于现有接口快速集成分销功能，并通过后台管理完成审核与运营。建议在集成时重点关注并发安全、去重机制与层级限制，确保系统稳定与合规。
附录：接口清单与集成要点
- 分销入口：GET /api/?route=distribution
- 作用：根据是否已开通分销，重定向至“我的分销”或“申请页”。
- 我的分销：GET /api/?route=distribution/user
- 作用：返回资金明细与分页，支持按上级用户筛选。
- 下线列表：GET /api/?route=distribution/user/people
- 作用：返回直推下级及间推信息，含累计奖励与跳转链接。
- 申请表单：GET /api/?route=distribution/user/apply
- 作用：返回申请表单与附件。
- 提交申请：POST /api/?route=distribution/user/apply_post
- 作用：校验并写入申请记录。
- 提现表单：GET /api/?route=withdraw/user/apply
- 作用：返回提现表单与可用余额。
- 提交提现：POST /api/?route=withdraw/user/apply_post
- 作用：校验并创建提现申请。
集成要点：
- 认证：所有会员侧接口需携带有效会话令牌。
- 参数：严格遵循 FormRequest 校验规则。
- 错误：根据返回错误码与消息进行前端提示与重试。
- 联动：订单状态变化会自动触发佣金发放与等级升级检查，无需额外调用。