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

分销系统

简介

本开发文档面向DouPHP分销系统的运营与开发者，围绕分销层级管理、佣金计算、推广关系追踪等核心能力进行系统化说明。文档覆盖分销商注册、等级晋升、佣金提现等业务规则；解释多级分销算法、防作弊机制、税务处理等技术实现；并提供分销数据看板、业绩统计、排行榜等管理功能说明；同时涵盖小程序分销界面、分享链接生成、推广二维码等前端能力。目标是帮助读者快速理解并高效扩展该系统。

更新系统现已采用领域驱动设计（DDD）架构，将核心业务逻辑和领域模型统一放置在core/domain目录下，并通过新增的DistributionStatus领域模型实现了标准化的状态管理，提升了代码的可维护性和可扩展性。

项目结构

分销模块在后台（Admin）提供申请审核、等级配置与日志查看；在API层提供小程序入口路由；服务层封装业务逻辑；模型层负责数据访问与查询构建器扩展。核心领域模型已迁移至core/domain/distribution目录，实现了更好的职责分离和模块化设计。整体采用控制器-服务-模型的清晰分层，便于维护与扩展。

graph TB
subgraph "核心领域层"
DS["DistributionStatus<br/>分销状态枚举"]
end
subgraph "后台管理"
AC["DistributionController<br/>申请列表/审核/佣金记录"]
LC["LevelController<br/>等级CRUD/日志"]
end
subgraph "API接口"
APIC["DistributionController<br/>小程序入口分流"]
end
subgraph "服务层"
SVC["DistributionService<br/>申请列表/审核/佣金记录"]
LUS["DistributionLevelUpgradeService<br/>等级自动升级"]
end
subgraph "模型层"
DM["Distribution<br/>申请表"]
DR["DistributionRelation<br/>推广关系树"]
end
DS --> SVC
DS --> LUS
AC --> SVC
LC --> SVC
APIC --> SVC
SVC --> DM
SVC --> DR

图表来源

core/domain/distribution/DistributionStatus.php:31-108
admin/controller/distribution/DistributionController.php:28-193
admin/controller/distribution/LevelController.php:28-174
api/controller/distribution/DistributionController.php:27-48
admin/service/distribution/DistributionService.php:35-348
core/service/distribution/DistributionLevelUpgradeService.php:31-187
admin/model/distribution/Distribution.php:24-109
admin/model/distribution/DistributionRelation.php:24-79

章节来源

admin/controller/distribution/DistributionController.php:28-193
admin/controller/distribution/LevelController.php:28-174
api/controller/distribution/DistributionController.php:27-48
admin/service/distribution/DistributionService.php:35-348
core/domain/distribution/DistributionStatus.php:31-108
core/service/distribution/DistributionLevelUpgradeService.php:31-187
admin/model/distribution/Distribution.php:24-109
admin/model/distribution/DistributionRelation.php:24-79

核心组件

核心领域模型：DistributionStatus枚举定义了分销申请的状态管理，包含待审核（pending）、已通过（approved）、已驳回（rejected）三种状态及状态迁移验证。
后台分销控制器：负责分销申请列表、审核详情、佣金记录展示与提交处理。
后台等级控制器：负责分销等级配置（创建/编辑/删除）及等级变更记录查看。
API分销控制器：小程序端统一入口，根据用户是否已开通分销跳转至"我的分销"或"申请页"。
分销服务：聚合申请列表、审核处理、佣金记录查询等核心业务逻辑，集成状态验证机制。
等级升级服务：自动检测用户消费金额并提升分销等级，使用状态常量进行判断。
分销模型：申请表与推广关系表的数据访问与查询构建器扩展。

更新新增的核心领域层提供了统一的业务状态管理，确保分销流程的一致性和安全性，所有相关服务都通过DistributionStatus类进行状态操作。

章节来源

core/domain/distribution/DistributionStatus.php:31-108
admin/controller/distribution/DistributionController.php:28-193
admin/controller/distribution/LevelController.php:28-174
api/controller/distribution/DistributionController.php:27-48
admin/service/distribution/DistributionService.php:35-348
core/service/distribution/DistributionLevelUpgradeService.php:31-187
admin/model/distribution/Distribution.php:24-109
admin/model/distribution/DistributionRelation.php:24-79

架构总览

分销系统采用领域驱动设计（DDD）的架构思想：核心领域层定义业务规则和状态管理，后台管理用于配置与审核，API为小程序等客户端提供统一入口，服务层承载业务规则，模型层专注数据访问。通过控制器-服务-模型的分层设计，职责清晰、易于扩展与维护。

更新新的架构引入了核心领域层，将业务状态管理和领域规则集中管理，提高了系统的可维护性和一致性。DistributionStatus类作为状态管理的核心，被多个服务层组件引用。

sequenceDiagram
participant U as "管理员/用户"
participant AC as "后台分销控制器"
participant AS as "后台等级控制器"
participant DS as "核心领域层"
participant SVC as "分销服务"
participant M1 as "申请表模型"
participant M2 as "推广关系模型"
U->>AC : 打开申请列表/佣金记录
AC->>SVC : 构建列表数据(筛选/分页)
SVC->>DS : 使用DistributionStatus验证状态
DS-->>SVC : 返回状态验证结果
SVC->>M1 : 查询申请记录
M1-->>SVC : 结果集
SVC-->>AC : 组装视图数据
AC-->>U : 渲染页面
U->>AS : 配置等级/查看日志
AS->>SVC : 等级相关操作
SVC-->>AS : 返回结果
AS-->>U : 渲染页面
U->>AC : 提交审核
AC->>SVC : handleApply()
SVC->>DS : 验证状态迁移
DS-->>SVC : 确认迁移合法性
SVC->>M1 : 更新状态/等级
SVC->>M2 : 可选写入等级变更日志
SVC-->>AC : 重定向到详情页
AC-->>U : 显示审核结果

图表来源

admin/controller/distribution/DistributionController.php:55-193
admin/controller/distribution/LevelController.php:59-174
core/domain/distribution/DistributionStatus.php:55-63
admin/service/distribution/DistributionService.php:56-348
admin/model/distribution/Distribution.php:24-109
admin/model/distribution/DistributionRelation.php:24-79

详细组件分析

核心领域层（状态管理）

新增 DistributionStatus类提供了分销申请状态的完整管理，包括：

状态常量定义：PENDING（待审核）、APPROVED（已通过）、REJECTED（已驳回）
状态迁移验证：通过canTransit方法确保状态转换的合法性，只允许从待审核状态转换为已通过或已驳回
状态展示样式：badgeClass方法返回对应的CSS样式类（success/danger/warning）
状态验证：isValid方法验证状态值的有效性
状态列表：all方法返回所有合法状态值

classDiagram
class DistributionStatus {
+const PENDING = 'pending'
+const APPROVED = 'approved'
+const REJECTED = 'rejected'
+static canTransit(from, to) bool
+static all() array
+static isValid(status) bool
+static badgeClass(status) string
}

图表来源

core/domain/distribution/DistributionStatus.php:31-108

章节来源

core/domain/distribution/DistributionStatus.php:31-108

后台分销控制器（申请与佣金）

申请列表：支持按用户名、时间范围筛选与分页，过滤非法参数后交由服务层构建数据，使用DistributionStatus::badgeClass统一状态样式。
审核页：加载申请详情、等级选项与图片附件，支持解锁状态下修改，集成状态检查逻辑。
佣金记录：基于资金流水表筛选直推/间推佣金，支持按得主与来源会员、时间范围过滤。
审核提交：校验参数后调用服务层处理申请，更新申请状态与会员分销等级，必要时记录等级变更日志。

flowchart TD
Start(["进入申请列表"]) --> Parse["解析请求参数<br/>用户名/时间范围/页码"]
Parse --> Validate{"参数合法?"}
Validate -- 否 --> Empty["强制空结果集"]
Validate -- 是 --> Query["调用服务层构建列表数据"]
Query --> Render["渲染列表视图"]
Empty --> Render
Render --> End(["结束"])

图表来源

admin/controller/distribution/DistributionController.php:55-93
admin/service/distribution/DistributionService.php:56-135

章节来源

admin/controller/distribution/DistributionController.php:55-193
admin/service/distribution/DistributionService.php:56-348

后台等级控制器（等级配置与日志）

等级列表：展示所有分销等级，支持新增、编辑、删除与查看等级变更日志。
表单校验：使用表单请求对象进行输入校验，确保等级配置安全有效。
数据绑定：通过服务层方法获取默认数据、编辑数据与选项集合。

classDiagram
class LevelController {
+index()
+create()
+store(request)
+edit(request)
+update(request)
+destroy(request)
}
class DistributionLevelService {
+buildLevelListData()
+buildLevelDefaultData()
+buildLevelEditData(id)
+insert(data)
+update(data)
+delete(id, post)
+options(levelId)
}
LevelController --> DistributionLevelService : "依赖"

图表来源

admin/controller/distribution/LevelController.php:28-174

章节来源

admin/controller/distribution/LevelController.php:59-174

API分销控制器（小程序入口）

统一入口：根据当前用户是否已开通分销，跳转到"我的分销"或"申请页"，简化小程序导航逻辑。

sequenceDiagram
participant MP as "小程序"
participant API as "API分销控制器"
participant Auth as "认证上下文"
participant User as "用户服务"
MP->>API : GET /distribution
API->>Auth : 获取当前用户ID
API->>User : 查询用户分销信息
User-->>API : 分销状态
API-->>MP : 返回redirect地址

图表来源

api/controller/distribution/DistributionController.php:27-48

章节来源

api/controller/distribution/DistributionController.php:27-48

分销服务（核心业务）

申请列表：支持用户名与时间范围筛选，构造分页URL，组装状态语言化与徽章样式，使用DistributionStatus::badgeClass统一样式。
审核处理：校验申请状态，更新申请表与用户分销等级，若等级变化则写入等级日志，集成状态验证机制。
佣金记录：基于资金流水表筛选直推/间推佣金，格式化动作类型与来源会员信息。

更新服务层现在使用核心领域层的DistributionStatus进行状态验证和管理，确保业务逻辑的一致性和安全性。所有状态操作都通过常量引用，避免了硬编码字符串的问题。

flowchart TD
S(["handleApply"]) --> V1["校验id与unlock"]
V1 --> L1["读取申请记录"]
L1 --> C1{"状态允许操作?"}
C1 -- 否 --> E1["抛出异常/重定向"]
C1 -- 是 --> U1["更新申请表状态/等级/处理记录"]
U1 --> U2["更新用户分销等级"]
U2 --> D1{"等级是否变化?"}
D1 -- 是 --> L2["写入等级变更日志"]
D1 -- 否 --> R1["重定向到审核详情"]
L2 --> R1

图表来源

admin/service/distribution/DistributionService.php:295-348

章节来源

admin/service/distribution/DistributionService.php:56-348

等级自动升级服务

新增 DistributionLevelUpgradeService负责自动检测用户消费金额并提升分销等级：

检查用户是否为已批准的分销员，使用DistributionStatus::APPROVED常量进行判断
查询用户的累计消费金额
根据等级配置自动提升分销等级
记录等级变更日志

flowchart TD
Start(["checkLevelUpgrade"]) --> Check1["检查用户ID有效性"]
Check1 --> Check2["检查分销功能是否启用"]
Check2 --> Check3["验证是否为已批准分销员"]
Check3 --> Check4["获取用户当前等级"]
Check4 --> Check5["查询用户累计消费"]
Check5 --> Loop{"遍历更高等级"}
Loop --> Condition{"满足升级条件?"}
Condition -- 是 --> Update["更新用户等级"]
Update --> Log["记录等级变更日志"]
Log --> Next["继续检查更高一级"]
Condition -- 否 --> Next
Next --> End(["返回升级结果"])

图表来源

core/service/distribution/DistributionLevelUpgradeService.php:51-144

章节来源

core/service/distribution/DistributionLevelUpgradeService.php:51-144

模型层（数据访问）

申请表模型：提供按用户ID、创建时间范围筛选与默认排序的查询构建器扩展。
推广关系模型：支持下级会员过滤、上级会员过滤与层级过滤，支撑多级分销关系查询。

classDiagram
class Distribution {
+scopeFilterByUserId(query, userId)
+scopeFilterByCreatedAfter(query, timeStart)
+scopeFilterByCreatedBefore(query, timeEnd)
+scopeApplyDefaultOrder(query)
}
class DistributionRelation {
+scopeFilterByUser(query, userId)
+scopeFilterByParent(query, parentUserId)
+scopeFilterByLevel(query, level)
}

图表来源

admin/model/distribution/Distribution.php:47-109
admin/model/distribution/DistributionRelation.php:31-79

章节来源

admin/model/distribution/Distribution.php:24-109
admin/model/distribution/DistributionRelation.php:24-79

依赖关系分析

控制器依赖服务：后台与API控制器均通过依赖注入使用服务层，保证业务逻辑集中与可测试性。
服务依赖核心领域层：服务层通过核心领域层的DistributionStatus进行状态管理，确保业务规则的一致性。
服务依赖模型：服务层通过模型提供的查询构建器扩展完成复杂筛选与分页。
外部模块：佣金记录依赖资金模块（money），当模块不存在时优雅降级为空结果。

更新新的依赖关系引入了核心领域层，服务层现在依赖于核心领域的状态管理，提高了系统的内聚性。所有涉及状态操作的代码都通过DistributionStatus常量引用，避免了魔法字符串的使用。

graph LR
AC["后台分销控制器"] --> SVC["分销服务"]
LC["后台等级控制器"] --> SVC
APIC["API分销控制器"] --> SVC
DS["核心领域层<br/>DistributionStatus"] --> SVC
SVC --> DM["申请表模型"]
SVC --> DR["推广关系模型"]
SVC --> Money["资金模块(可选)"]

图表来源

admin/controller/distribution/DistributionController.php:28-193
admin/controller/distribution/LevelController.php:28-174
api/controller/distribution/DistributionController.php:27-48
core/domain/distribution/DistributionStatus.php:31-108
admin/service/distribution/DistributionService.php:35-348

章节来源

admin/service/distribution/DistributionService.php:178-293

性能考量

查询优化：使用查询构建器作用域进行条件拼接，避免N+1问题；分页限制每页条数，减少数据传输。
参数校验：在服务层对输入进行严格校验，提前失败以减少无效查询。
模块解耦：佣金记录依赖资金模块，缺失时直接返回空结果，避免运行时错误影响主流程。
缓存建议：对等级选项、用户分销状态等读多写少数据可引入缓存层以提升响应速度。
新增核心领域层的使用减少了重复的状态判断逻辑，提高了代码复用性和执行效率，通过常量引用避免了字符串比较的性能开销。

故障排查指南

申请无法操作：检查申请状态是否为待审核，若非待审核且未解锁将拒绝操作。
佣金记录为空：确认资金模块是否存在以及数据库表是否存在；若不存在则返回空结果。
筛选无结果：检查用户名与时间范围是否合法，非法参数会强制返回空结果集。
等级变更未记录：确认等级是否发生变化，仅当新旧等级不同且日志表存在时才写入日志。
新增状态迁移失败：检查DistributionStatus::canTransit方法是否正确验证状态转换的合法性，确保状态转换符合预定义的迁移规则。
新增状态显示异常：确认DistributionStatus::badgeClass方法是否正确返回对应的CSS样式类。

章节来源

admin/service/distribution/DistributionService.php:295-348
admin/service/distribution/DistributionService.php:178-293
core/domain/distribution/DistributionStatus.php:55-63

结论

本分销系统通过清晰的控制器-服务-模型分层，结合核心领域层的状态管理，实现了分销申请审核、等级配置、佣金记录与推广关系管理等核心能力。API入口为小程序提供便捷导航，服务层封装了关键业务规则，模型层提供了灵活的查询构建器。新增的DistributionStatus领域模型显著提升了系统的可维护性和一致性，通过枚举化的状态管理确保了业务逻辑的正确性。建议在后续迭代中引入缓存与异步任务以进一步提升性能，并完善防作弊与税务处理策略以满足合规需求。

更新新的架构设计通过领域驱动设计原则，将业务状态管理集中在核心领域层，为未来的功能扩展和维护提供了更好的基础。DistributionStatus类的引入使得状态管理更加规范和安全。

附录

业务规则要点
- 分销商注册：小程序入口根据用户分销状态自动跳转至申请或我的分销页面。
- 等级晋升：后台审核通过后更新用户分销等级，若等级变化则记录日志；支持自动升级机制。
- 佣金提现：佣金记录来自资金模块的直推/间推动作，支持按得主与来源会员、时间范围筛选。
技术实现要点
- 多级分销算法：通过推广关系表的层级字段区分直推与间推，结合订单归属进行佣金分配。
- 防作弊机制：建议增加设备指纹、IP频率限制、订单关联校验等策略。
- 税务处理：可在佣金结算前插入税率计算与发票管理流程，确保财务合规。
- 新增状态管理：使用核心领域层的DistributionStatus统一管理分销申请状态，确保状态转换的合法性和一致性，支持待审核、已通过、已驳回三种状态及其迁移规则。
前端功能要点
- 小程序分销界面：统一入口跳转，展示我的分销、下线列表、申请进度。
- 分享链接生成：基于用户ID生成带参数的推广链接，便于追踪转化。
- 推广二维码：将分享链接编码为二维码，提升线下推广效率。
新增状态管理最佳实践
- 使用DistributionStatus常量而非硬编码字符串
- 通过canTransit方法进行状态迁移验证
- 使用badgeClass方法统一状态显示样式
- 在业务逻辑中优先使用isValid方法验证状态有效性

添加日期：2026-10-05