简介
本设计文档聚焦于 DouPHP 分销佣金功能模块的数据库表结构设计，围绕分销商管理、分销等级、分销关系链、佣金计算与结算、提现记录等关键业务进行系统化说明。文档基于仓库中的模型定义与 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["money_*<br/>资金/钱包相关表"]
F["withdraw_*<br/>提现记录表"]
end
A --> B
C --> B
D --> B
A --> C
A -.-> E
A -.-> F核心组件
- 分销申请表（dou_distribution）：记录会员申请成为分销商的申请信息、处理状态与时间戳，支撑分销准入与审核流程。
- 分销等级表（dou_distribution_level）：配置直推与间推奖励比例、升级条件与展示排序，作为佣金计算的规则源。
- 分销关系表（dou_distribution_relation）：维护“用户—上级”关系及层级（直推/间推），构建分销网络拓扑。
- 等级变动日志（dou_distribution_level_log）：记录等级变更前后、触发条件值与订单号，支持审计与溯源。
- 提现与资金表（withdraw* / money*）：承载佣金结算后的余额变动与提现申请、审批、打款等全链路记录。
架构总览
分销系统的核心数据流围绕“关系—等级—申请—日志—结算—提现”展开：
- 关系层：通过关系表建立上下级与层级，决定佣金归属路径
- 规则层：等级表提供直推/间推比例与升级门槛
- 申请层：分销申请表承载准入与审核
- 审计层：等级日志记录变更原因与依据
- 结算层：结合订单与等级规则计算佣金，落库至资金表
- 提现层：提现记录驱动余额扣减与打款
sequenceDiagram
participant U as "用户"
participant R as "关系表(dou_distribution_relation)"
participant L as "等级表(dou_distribution_level)"
participant A as "申请表(dou_distribution)"
participant G as "等级日志(dou_distribution_level_log)"
participant M as "资金表(money_*)"
participant W as "提现表(withdraw_*)"
U->>A : 提交分销申请
A-->>U : 返回申请单号/状态
U->>R : 绑定上级(直推/间推)
R-->>U : 确认关系与层级
U->>L : 满足升级条件
L-->>G : 写入等级变更日志
U->>M : 佣金入账(按等级比例)
U->>W : 发起提现
W-->>U : 提现结果详细组件分析
分销申请表（dou_distribution）
- 用途：记录分销商申请信息、审核状态与处理时间，支撑分销准入流程。
- 关键字段
- id：自增主键
- user_id：申请人会员ID
- name：申请人姓名
- remark：申请备注
- level_id：申请等级（关联等级表）
- handle_record：处理记录
- handled_at：处理时间
- status：申请状态（如待处理/已通过/已拒绝）
- created_at：创建时间
- 索引
- idx_user：user_id
- idx_status：status
- 模型能力
- 支持按用户、时间范围筛选与默认排序
classDiagram
class Distribution {
+int id
+int user_id
+string name
+text remark
+int level_id
+text handle_record
+datetime handled_at
+string status
+datetime created_at
}分销等级表（dou_distribution_level）
- 用途：配置直推与间推奖励比例、升级金额门槛与排序，作为佣金计算与升级判定依据。
- 关键字段
- id：自增主键
- name：等级名称
- direct_reward_percent：直推奖励百分比
- indirect_reward_percent：间推奖励百分比
- upgrade_condition_amount：升级所需累计金额
- sort：排序权重
- created_at：创建时间
- 模型能力
- 默认排序：按 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
}分销关系表（dou_distribution_relation）
- 用途：维护“用户—上级”关系与层级（1=直推，2=间推），构成分销网络拓扑。
- 关键字段
- id：自增主键
- user_id：下级用户ID
- parent_user_id：上级用户ID
- level：层级（1 直推，2 间推）
- created_at：创建时间
- 索引
- uniq_user_parent：(user_id, parent_user_id) 唯一约束，防止重复关系
- idx_parent：parent_user_id 便于查下级
- 模型能力
- 支持下级过滤、上级过滤、层级过滤
classDiagram
class DistributionRelation {
+int id
+int user_id
+int parent_user_id
+tinyint level
+datetime created_at
}等级变动日志（dou_distribution_level_log）
- 用途：记录等级变更的前后等级、触发条件值与订单号，支持审计与溯源。
- 关键字段
- id：自增主键
- user_id：用户ID
- old_level_id：变更前等级ID
- new_level_id：变更后等级ID
- condition_value：触发升级的条件值（如累计金额）
- order_sn：订单号（自动升级时携带）
- created_at：变更时间
- 索引
- user_id：按用户查询
- order_sn：按订单溯源
- 模型能力
- 支持按用户、来源（auto/admin）筛选
classDiagram
class DistributionLevelLog {
+int id
+int user_id
+int old_level_id
+int new_level_id
+decimal condition_value
+string order_sn
+datetime created_at
}提现记录与资金流水（withdraw* / money*）
- 用途：提现记录表承载提现申请、审核与打款状态；资金表承载余额增减流水，用于佣金结算后的入账与提现扣减。
- 典型字段（以模块命名约定为准）
- 提现表：id、user_id、amount、status、bank_info、audit_time、created_at 等
- 资金表：id、user_id、type、amount、balance、remark、created_at 等
- 与分销的关系
- 佣金结算：根据等级比例将佣金写入资金表
- 提现发放：从资金表扣减并生成提现记录
依赖关系分析
- 分销申请表 → 分销等级表：level_id 外键语义，决定申请等级
- 分销关系表 → 分销等级表：通过用户当前等级确定佣金比例
- 等级日志 → 分销等级表：old/new_level_id 指向等级表
- 佣金结算 → 资金表：按等级比例入账
- 提现 → 资金表：扣减余额并生成提现记录
erDiagram
dou_distribution ||--o{ dou_distribution_level : "level_id"
dou_distribution_relation ||--|| dou_distribution_level : "按用户等级"
dou_distribution_level_log ||--|| dou_distribution_level : "old/new_level_id"
dou_distribution ||--o{ dou_distribution_relation : "申请后绑定关系"
dou_distribution_level ||--o{ dou_distribution_level_log : "等级变更"
dou_distribution ||--o{ money_* : "佣金入账"
money_* ||--o{ withdraw_* : "提现扣减"性能考虑
- 索引优化
- 关系表使用 (user_id, parent_user_id) 唯一索引避免重复关系，同时为 parent_user_id 建索引加速下级查询
- 等级日志对 user_id、order_sn 建索引，便于按用户与订单溯源
- 申请表对 user_id、status 建索引，提升列表与筛选性能
- 读写分离与分表
- 高并发场景下，可将日志类表（等级日志、资金流水、提现记录）按时间分表或归档
- 事务一致性
- 佣金入账与余额更新应在同一事务中完成，确保数据一致
- 缓存策略
- 等级配置（直推/间推比例、升级门槛）可缓存，减少热点读取压力
- 批量操作
- 批量导入关系与日志时使用批量插入，降低 IO 开销
故障排查指南
- 重复关系冲突
- 现象：插入关系时报唯一索引冲突
- 排查：检查 (user_id, parent_user_id) 是否已存在
- 等级升级未生效
- 现象：达到升级条件但等级未变化
- 排查：核对升级条件字段与累计金额计算逻辑，查看等级日志是否有记录
- 佣金未到账
- 现象：订单完成后佣金未写入资金表
- 排查：检查订单状态、等级比例配置、结算任务执行日志
- 提现失败
- 现象：提现申请被拒或打款失败
- 排查：核对提现表状态、资金余额、银行信息与风控规则
结论
DouPHP 分销佣金模块通过清晰的分层表设计，实现了分销商管理、等级规则、关系链、等级审计与结算提现的完整闭环。借助合理的索引与事务控制，可在保证数据一致性的前提下支撑较高并发。建议在扩展佣金规则与结算策略时，优先复用现有等级与日志表，保持审计可追溯性。
附录
- 常见业务场景与表映射
- 申请成为分销商：dou_distribution
- 绑定上下级关系：dou_distribution_relation
- 配置佣金比例与升级门槛：dou_distribution_level
- 记录等级变更：dou_distribution_level_log
- 佣金入账与提现：money* / withdraw*