营销服务实现 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

营销服务实现

简介

本文件面向DouPHP框架的营销子系统，围绕优惠券、分销、分享、VIP会员四大能力，系统梳理其业务目标、服务职责、数据流转与协作关系。重点说明：

营销活动规则引擎与优惠计算的基本思路
分销层级管理与佣金结算流程
分享裂变与积分激励机制
VIP会员权益体系与生命周期管理
营销服务与订单、用户、支付等核心服务的协作方式并提供可落地的开发与配置示例，帮助快速构建复杂营销策略。

项目结构

营销相关功能在后台（admin）提供管理入口，在前台（front）和小程序（api）暴露消费端接口；核心业务逻辑集中在各模块的服务层（service），控制器负责请求校验、编排与视图渲染。

graph TB
subgraph "后台管理(admin)"
AC["优惠券控制器<br/>CouponController"]
DC["分销控制器<br/>DistributionController"]
SC["分享控制器<br/>ShareController"]
VC["VIP控制器<br/>VipController"]
end
subgraph "前台/小程序(front/api)"
FC["前端优惠券服务<br/>Front CouponService"]
ACC["小程序优惠券控制器<br/>Api CouponController"]
end
subgraph "核心服务(core)"
CS["核心优惠券服务<br/>Core CouponService"]
end
AC --> |"调用"| 后台服务
DC --> |"调用"| 后台服务
SC --> |"调用"| 后台服务
VC --> |"调用"| 后台服务
ACC --> |"领取/查询"| FC
FC --> |"规则/计算"| CS

核心组件

优惠券
- 后台管理：创建、编辑、删除、日志查看、批量操作
- 小程序领取：新用户优先领取、返回用户券包列表
分销
- 申请审核、等级配置、佣金记录查询、批量处理
分享
- 分享记录审核、批量取消、参数初始化
VIP
- 会员日志管理、批量删除、套餐管理入口

架构总览

营销子系统采用“控制器-服务-模型”分层设计：

控制器：接收请求、参数校验、调用服务、渲染响应
服务：封装业务规则、协调多域服务（订单、用户、支付）、持久化数据
模型：数据访问与实体映射

sequenceDiagram
participant U as "用户/运营"
participant A as "后台控制器"
participant S as "后台服务"
participant M as "模型/数据库"
U->>A : 提交表单/查询
A->>S : 调用业务方法
S->>M : 读写数据
M-->>S : 结果集
S-->>A : 业务结果
A-->>U : 页面/JSON响应

详细组件分析

优惠券模块

后台能力
- 列表分页、新建、编辑、删除、日志、批量动作
- 通过服务组装默认数据、编辑数据与列表数据
小程序能力
- 领取优惠券：仅对新用户开放一次领取机会，成功后返回当前用户券包列表
- 依赖前台服务进行领取判定与发放，再调用核心服务获取券列表

sequenceDiagram
participant C as "小程序客户端"
participant API as "Api CouponController"
participant F as "Front CouponService"
participant CORE as "Core CouponService"
C->>API : POST /coupon/claim?id=...
API->>F : claimCouponIfNew(userId, id, ip)
F-->>API : 领取结果
API->>CORE : getCouponList(userId)
CORE-->>API : 券列表
API-->>C : 成功响应(含券列表)

分销模块

申请审核
- 支持按用户名、时间范围筛选，展示申请明细与解锁状态
- 审核通过后更新分销身份与等级
佣金记录
- 支持按推广人、被推广人、时间范围查询佣金流水
批量处理
- 提供占位入口用于后续扩展批量操作

flowchart TD
Start(["进入分销列表"]) --> Filter["过滤条件解析<br/>用户名/时间范围"]
Filter --> Query["查询申请列表"]
Query --> Show["渲染列表/分页"]
Show --> Detail{"查看详情?"}
Detail -- 是 --> Edit["加载详情/解锁状态"]
Detail -- 否 --> End(["结束"])
Edit --> Handle["提交审核处理"]
Handle --> Update["更新分销状态/等级"]
Update --> End

分享模块

分享记录审核
- 支持按用户名、分享单号、时间范围筛选
- 支持批量取消分享记录
参数初始化
- 提供一键初始化分享积分参数的入口

sequenceDiagram
participant Admin as "运营人员"
participant ShareCtrl as "ShareController"
participant ShareSvc as "ShareService"
Admin->>ShareCtrl : 查询/审核/批量操作
ShareCtrl->>ShareSvc : buildShareListData/handle/batchCancel
ShareSvc-->>ShareCtrl : 列表/处理结果
ShareCtrl-->>Admin : 页面/重定向

VIP会员模块

会员日志管理
- 支持按用户名、时间范围筛选会员日志
- 支持删除单条或批量删除
套餐管理入口
- 提供VIP套餐配置的跳转入口

flowchart TD
VStart(["进入VIP日志"]) --> VFilter["筛选条件解析"]
VFilter --> VQuery["查询日志列表"]
VQuery --> VRender["渲染列表/分页"]
VRender --> VAction{"删除/批量操作?"}
VAction -- 是 --> VDelete["执行删除/批量删除"]
VAction -- 否 --> VEnd(["结束"])
VDelete --> VEnd

依赖关系分析

控制器与服务解耦：控制器仅负责入参校验、调用服务与响应渲染
服务间协作：
- 优惠券：前台服务负责领取策略，核心服务负责券集合查询
- 分销：后台服务负责申请审核、等级与佣金记录
- 分享：后台服务负责记录审核与参数初始化
- VIP：后台服务负责日志管理与批量操作
外部协作点（概念性）：
- 订单服务：优惠券核销、分销佣金结算触发点
- 用户服务：用户身份、等级、邀请关系
- 支付服务：支付完成后结算与分佣

graph LR
Order["订单服务"] --> Coupon["优惠券服务"]
Order --> Distribution["分销服务"]
User["用户服务"] --> Distribution
User --> VIP["VIP服务"]
Payment["支付服务"] --> Distribution
Payment --> Coupon

[此图为概念示意，不直接对应具体源码文件]

性能考量

列表分页与筛选：控制器将筛选条件交由服务层处理，建议在服务层使用索引字段优化查询
领取并发控制：小程序领取需防重复领取，建议在服务层加入幂等键（如用户ID+券ID+IP）
批量操作：后台批量删除/取消应分批执行，避免长事务阻塞
缓存策略：券列表、分销等级、VIP权益等读多写少数据可引入缓存层降低DB压力

故障排查指南

控制器抛出非法参数异常
- 现象：编辑/删除时传入无效ID导致异常
- 定位：检查控制器对id的校验与异常抛出位置
- 参考路径
  - admin/controller/coupon/CouponController.php:110-158
  - admin/controller/vip/VipController.php:89-97
列表为空或筛选无效
- 现象：输入用户名或时间范围后无结果
- 定位：检查控制器对输入清洗与过滤条件构造
- 参考路径
  - admin/controller/distribution/DistributionController.php:61-93
  - admin/controller/share/ShareController.php:60-82
小程序领取失败
- 现象：领取接口返回空或错误
- 定位：检查userId、券id、IP参数传递与前台服务领取逻辑
- 参考路径
  - api/controller/coupon/CouponController.php:57-75

结论

DouPHP营销子系统以清晰的控制器-服务分层组织，覆盖优惠券、分销、分享、VIP四大场景。通过后台管理完成规则配置与运营操作，通过前台/小程序暴露消费端能力，并与订单、用户、支付等服务协同完成完整交易闭环。建议在生产环境中结合缓存、幂等与异步任务提升稳定性与性能。

附录：开发示例与配置要点

优惠券
- 后台创建/编辑：通过控制器调用服务构建默认数据与编辑数据，保存后跳转到编辑页
- 小程序领取：调用领取接口，仅允许新用户领取一次，成功后返回用户券包列表
- 参考路径
  - admin/controller/coupon/CouponController.php:75-142
  - api/controller/coupon/CouponController.php:57-75
分销
- 申请审核：支持用户名与时间范围筛选，审核后更新分销身份与等级
- 佣金记录：支持按推广人与被推广人维度查询
- 参考路径
  - admin/controller/distribution/DistributionController.php:55-193
分享
- 分享记录审核与批量取消：支持多维度筛选与批量操作
- 参数初始化：一键初始化分享积分参数
- 参考路径
  - admin/controller/share/ShareController.php:56-138
VIP
- 会员日志管理：支持筛选、删除与批量删除
- 套餐管理入口：跳转至VIP套餐配置
- 参考路径
  - admin/controller/vip/VipController.php:56-109

添加日期：2026-10-05