分销商系统表 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

分销商系统表

简介

本文件面向电商平台开发者，系统化梳理 DouPHP 电商系统中“分销商模块”的数据模型与业务流程。围绕分销商主表、分销等级表、分销佣金（奖励）记录、提现管理等核心表，给出字段设计、索引策略、业务语义与流程时序，并提供防作弊、防重复计算与性能优化的实践建议。文档以仓库内实际 SQL 与模型代码为依据，确保可落地、可追溯。

项目结构

分销相关数据定义集中在以下位置：

分销模块 SQL：包含分销申请、等级、等级升级日志、关系链等表结构
提现模块 SQL：包含提现申请单表结构
后台模型：分销申请、等级、关系链的 ORM 模型封装
提现状态枚举：提现生命周期状态定义

graph TB
subgraph "分销模块"
A["dou_distribution<br/>分销申请表"]
B["dou_distribution_level<br/>分销等级表"]
C["dou_distribution_relation<br/>分销关系链"]
D["dou_distribution_level_log<br/>等级升级日志"]
end
subgraph "提现模块"
E["dou_withdraw<br/>提现申请单"]
end
A --> C
B --> A
B --> D
C --> E

核心组件

分销申请表（dou_distribution）：记录会员申请成为分销商的审批流与结果
分销等级表（dou_distribution_level）：定义直推/间推奖励比例与升级条件
分销关系链（dou_distribution_relation）：维护上下级推广关系与层级
等级升级日志（dou_distribution_level_log）：记录等级变更触发条件与订单关联
提现申请单（dou_withdraw）：记录分销佣金提现申请、审核与打款状态

架构总览

分销数据模型围绕“申请—关系—等级—佣金—提现”的主线展开。用户申请成为分销商后，建立推广关系；根据累计业绩达到等级升级条件时更新等级并记录日志；产生订单后按等级比例计算直推/间推佣金；最终通过提现模块完成资金结算。

sequenceDiagram
participant U as "会员"
participant DC as "分销控制器"
participant DS as "分销服务"
participant DB as "数据库"
participant W as "提现模块"
U->>DC : 提交分销申请
DC->>DS : handleApply(申请数据)
DS->>DB : 写入 dou_distribution(状态=pending)
Note over DS,DB : 创建申请记录，等待审核
DC-->>U : 返回申请成功
U->>W : 发起提现申请
W->>DB : 写入 dou_withdraw(状态=pending)
Note over W,DB : 申请成立即扣减可用余额

详细组件分析

分销申请表（dou_distribution）

用途：记录会员申请成为分销商的信息与审批过程
关键字段
- user_id：会员ID
- name：申请人姓名
- remark：申请备注
- level_id：申请等级（关联等级表）
- status：申请状态（如 pending 待审核）
- handled_at：处理时间
- handle_record：处理记录
索引
- idx_user(user_id)：按会员查询申请历史
- idx_status(status)：按状态筛选列表
模型能力
- 支持按 user_id、创建时间范围过滤与默认排序
- 提供批量可写字段白名单控制

flowchart TD
Start(["申请入口"]) --> Create["创建申请记录<br/>status=pending"]
Create --> Review{"管理员审核"}
Review --> |通过| Approve["更新状态为通过<br/>设置level_id"]
Review --> |驳回| Reject["更新状态为驳回"]
Approve --> End(["结束"])
Reject --> End

分销等级表（dou_distribution_level）

用途：配置不同等级的直推/间推奖励比例与升级门槛
关键字段
- name：等级名称
- direct_reward_percent：直推奖励百分比
- indirect_reward_percent：间推奖励百分比
- upgrade_condition_amount：升级所需累计金额
- sort：排序权重
模型能力
- 默认按 sort 升序、id 升序排列
- 提供按 id 获取名称的工具方法

classDiagram
class DistributionLevel {
+int id
+string name
+decimal direct_reward_percent
+decimal indirect_reward_percent
+decimal upgrade_condition_amount
+tinyint sort
+datetime created_at
+applyDefaultOrder(query)
+getNameById(id)
}

分销关系链（dou_distribution_relation）

用途：维护推广上下级关系与层级，支撑直推/间推佣金归属
关键字段
- user_id：下级会员ID
- parent_user_id：上级会员ID
- level：层级（1=直推，2=间推）
索引
- uniq_user_parent(user_id,parent_user_id)：防止重复绑定同一对上下级
- idx_parent(parent_user_id)：快速查询某上级的全部下级
模型能力
- 支持下级过滤、上级过滤、层级过滤

erDiagram
DOU_DISTRIBUTION_RELATION {
int id PK
int user_id
int parent_user_id
tinyint level
datetime created_at
}

等级升级日志（dou_distribution_level_log）

用途：记录等级变更原因、触发条件值与关联订单号，便于审计与回溯
关键字段
- user_id：会员ID
- old_level_id：原等级
- new_level_id：新等级
- condition_value：触发升级的条件值（如累计金额）
- order_sn：关联订单号
幂等性：脚本支持 IF NOT EXISTS，可重复执行

flowchart TD
Check["检查累计业绩是否达标"] --> |是| Upgrade["更新会员等级"]
Upgrade --> Log["写入等级升级日志"]
Check --> |否| Skip["不处理"]
Log --> End(["结束"])
Skip --> End

提现申请单（dou_withdraw）

用途：记录分销佣金的提现申请、审核与打款全流程
关键字段
- withdraw_sn：提现单号（唯一）
- user_id：会员ID
- money：提现金额
- card_number/card_bank/card_name：收款信息
- card_status：到账标记
- status：状态（pending/approved/rejected/paid）
- handled_at/handle_record：处理时间与记录
索引
- withdraw_sn 唯一键：保证单号唯一
- idx_user(user_id,status)：按会员与状态检索
状态语义
- pending：待审核（申请成立即扣减可用余额）
- approved：已通过（线下打款中）
- paid：已打款（终态）
- rejected：已驳回（退回余额）

stateDiagram-v2
[*] --> 待审核 : "提交申请"
待审核 --> 已通过 : "管理员批准"
待审核 --> 已驳回 : "管理员驳回"
已通过 --> 已打款 : "线下打款完成"
已驳回 --> [*]
已打款 --> [*]

依赖关系分析

分销申请（dou_distribution）依赖等级（dou_distribution_level）决定初始或目标等级
关系链（dou_distribution_relation）用于佣金归属判定，影响佣金分配逻辑
等级升级日志（dou_distribution_level_log）与订单号关联，支撑业绩统计与升级判定
提现（dou_withdraw）与分销佣金结算联动，状态机驱动资金流转

graph LR
Level["分销等级表"] --> Apply["分销申请表"]
Relation["分销关系链"] --> Commission["佣金归属(概念)"]
Apply --> Relation
Level --> Log["等级升级日志"]
Relation --> Withdraw["提现申请单"]

性能与优化

索引策略
- 分销申请：user_id、status 索引提升列表与明细查询效率
- 关系链：parent_user_id 索引加速下级聚合；唯一键避免重复绑定
- 提现：user_id+status 复合索引优化会员维度统计
幂等与去重
- 关系链使用唯一约束防止重复绑定
- 等级升级日志脚本支持 IF NOT EXISTS，可重复执行
事务与一致性
- 申请审核、等级升级、佣金入账、提现扣款等关键路径建议使用事务包裹，保证多表一致
缓存与异步
- 等级配置、关系树热点查询可引入缓存层
- 佣金结算、打款通知等耗时操作采用队列异步处理
防作弊与风控
- 绑定关系校验：限制自绑、频繁切换上级、异常层级增长
- 订单反作弊：退货/退款冲销佣金，黑名单过滤恶意订单
- 提现风控：限额、频次、银行卡白名单、二次验证

故障排查指南

申请未生效
- 检查 dou_distribution.status 是否为通过，handled_at 是否填写
- 核对 level_id 是否正确指向有效等级
佣金归属错误
- 核查 dou_distribution_relation 中 user_id 与 parent_user_id 是否匹配
- 确认 level 层级是否符合预期（1=直推，2=间推）
等级未升级
- 检查累计业绩是否达到 upgrade_condition_amount
- 查看 dou_distribution_level_log 是否有对应升级记录
提现失败
- 核对 dou_withdraw.status 与卡信息完整性
- 关注 WithdrawStatus 的状态迁移是否合法（pending→approved→paid 或 rejected）

结论

DouPHP 的分销数据模型以清晰的表划分与合理的索引设计，支撑了从申请、关系绑定、等级升级到佣金结算与提现的全链路业务。结合状态机与日志记录，既保证了可审计性，也为后续扩展（如多级分销、动态佣金规则、风控策略）提供了良好基础。建议在关键路径引入事务与异步化，配合缓存与风控策略，进一步提升系统的稳定性与可扩展性。

附录：表结构与字段说明

分销申请表（dou_distribution）

字段
- id：自增主键
- user_id：会员ID
- name：申请人姓名
- remark：申请备注
- level_id：申请等级
- handle_record：处理记录
- handled_at：处理时间
- status：申请状态
- created_at：创建时间
索引
- PRIMARY KEY (id)
- KEY idx_user (user_id)
- KEY idx_status (status)

分销等级表（dou_distribution_level）

字段
- id：自增主键
- name：等级名称
- direct_reward_percent：直推奖励百分比
- indirect_reward_percent：间推奖励百分比
- upgrade_condition_amount：升级条件金额
- sort：排序
- created_at：创建时间
索引
- PRIMARY KEY (id)

分销关系链（dou_distribution_relation）

字段
- id：自增主键
- user_id：下级会员ID
- parent_user_id：上级会员ID
- level：层级（1=直推，2=间推）
- created_at：创建时间
索引
- PRIMARY KEY (id)
- UNIQUE KEY uniq_user_parent (user_id, parent_user_id)
- KEY idx_parent (parent_user_id)

等级升级日志（dou_distribution_level_log）

字段
- id：自增主键
- user_id：会员ID
- old_level_id：原等级
- new_level_id：新等级
- condition_value：触发升级的条件值
- order_sn：关联订单号
- created_at：创建时间
索引
- PRIMARY KEY (id)
- KEY user_id (user_id)
- KEY order_sn (order_sn)

提现申请单（dou_withdraw）

字段
- id：自增主键
- withdraw_sn：提现单号（唯一）
- user_id：会员ID
- money：提现金额
- card_number：银行卡号
- card_bank：开户银行
- card_name：持卡人姓名
- card_status：到账标记
- handle_record：处理记录
- handled_at：处理时间
- status：状态（pending/approved/rejected/paid）
- created_at：创建时间
索引
- PRIMARY KEY (id)
- UNIQUE KEY withdraw_sn (withdraw_sn)
- KEY idx_user (user_id, status)

添加日期：2026-10-05