简介

本技术文档面向 DouPHP 营销子系统，覆盖优惠券系统、分销系统、分享推广与 VIP 会员四大业务域。文档从系统架构、数据流、处理逻辑、集成点、错误处理与性能特征等维度展开，并结合源码级图示说明营销活动与电商系统的集成方式，提供可操作的配置与扩展建议，帮助开发者快速落地营销功能并评估活动效果与 ROI。

项目结构

营销相关能力分布在多个模块中，采用“控制器-服务-模型/基础库”的分层组织：

• 优惠券：核心服务在 coupon 模块 core/service，前端入口在 front/controller，资格判定在 CouponEligibility。
• 分销：核心服务在 distribution 模块 core/service，API 入口在 api/controller，订单支付后联动由 order 模块触发。
• 分享：前端入口在 share 模块 front/controller，负责展示当前用户的分享记录。
• VIP：前台服务在 front/service/vip，VIP 状态枚举在 core/foundation/vip。

graph TB
subgraph "优惠券"
CCtrl["前端控制器<br/>CouponController"]
CSvc["核心服务<br/>CouponService"]
CEli["资格判定<br/>CouponEligibility"]
end
subgraph "分销"
DSvc["核心服务<br/>DistributionService"]
DUserCtrl["用户API控制器<br/>UserController"]
OStTrans["订单状态流转<br/>OrderStatusTransition"]
end
subgraph "分享"
SCtrl["分享入口控制器<br/>ShareController"]
end
subgraph "VIP"
VSvc["VIP服务<br/>VipService"]
VStat["VIP状态枚举<br/>VipStatus"]
end
CCtrl --> CSvc
CSvc --> CEli
OStTrans --> DSvc
DUserCtrl --> DSvc
SCtrl --> |"渲染分享列表"| SCtrl
VSvc --> VStat

核心组件

• 优惠券系统
  • 发放与领取：前端控制器接收领取请求，调用服务完成幂等领取。
  • 使用与折扣：服务根据券类型（满减/比例）计算折扣金额，支持上限控制与条件门槛。
  • 资格判定：基于时间窗口、首单限制、范围匹配（按商品/分类/全量）计算生效金额并判断可用。
• 分销系统
  • 佣金派发：订单进入已支付/已完成时，按直推/间推比例计算佣金，写入钱包账户，具备去重保护。
  • 奖励比例：读取用户等级对应的直推/间推百分比。
  • 关系树：维护上下级关系链，用于统计与展示；返利派发层级硬封顶为 2 级。
• 分享推广
  • 分享记录：统一入口展示当前登录用户的分享记录分页。
• VIP 会员
  • 套餐与记录：获取 VIP 套餐列表与开通记录，结合订单状态展示。
  • 生命周期：通过状态枚举区分生效、过期与无记录三种状态。

架构总览

营销子系统围绕“订单事件驱动 + 领域服务编排”的架构模式：

• 订单支付成功后，触发会员积分、分销奖励、VIP 等级升级等联动。
• 优惠券在下单前进行资格校验与折扣计算。
• 分享与 VIP 作为独立业务域，提供用户侧页面与服务接口。

sequenceDiagram
participant U as "用户"
participant CC as "优惠券控制器"
participant CS as "优惠券服务"
participant CE as "资格判定"
participant OS as "订单状态流转"
participant DS as "分销服务"
participant W as "钱包服务"
U->>CC : 提交领取优惠券
CC->>CS : claimCouponIfNew(...)
CS-->>U : 返回领取结果
U->>OS : 完成支付
OS->>DS : orderReward(order_sn)
DS->>W : createMoney(佣金, from=订单号)
W-->>DS : 入账成功
DS-->>OS : 完成

详细组件分析

优惠券系统

• 领取流程
  • 前端控制器校验登录态与参数，调用服务执行领取，确保幂等。
• 使用与折扣
  • 服务根据券类型（满减/比例）与订单金额计算折扣，支持最大折扣上限。
  • 资格判定器依据时间窗口、首单限制、范围匹配计算生效金额并判断是否满足门槛。
• 状态与过期
  • 服务提供券状态查询与过期判断，便于前端展示与禁用。

flowchart TD
Start(["开始"]) --> CheckTime["检查券有效期"]
CheckTime --> TimeOK{"在有效期内?"}
TimeOK --> |否| EndNo["不可用"]
TimeOK --> |是| CheckFirst["是否限首单?"]
CheckFirst --> FirstOnly{"是首单?"}
FirstOnly --> |否| EndNo
FirstOnly --> |是| CalcScope["计算生效金额"]
CalcScope --> Enough{"达到门槛?"}
Enough --> |否| EndNo
Enough --> |是| ApplyDiscount["应用折扣(满减/比例/上限)"]
ApplyDiscount --> EndYes["可用并返回折扣"]

分销系统

• 佣金派发
  • 订单进入已支付/已完成时，按直推/间推比例计算佣金，写入钱包账户，以订单号为 from 字段实现幂等。
  • 法律红线：仅派发至直推与间推两级，level>=3 一律不派发。
• 奖励比例
  • 读取用户等级对应的直推/间推百分比，未命中则返回 0。
• 关系树
  • 维护上下级关系链，用于统计与展示；写入过程具备环检测与深度上限保护。

classDiagram
class DistributionService {
+orderReward(order_sn) void
+rewardPercent(type, user_id) float
+recordRelation(userId, directUserId) void
+parents(userId) array
+children(parentUserId, level) array
}
class WalletService {
+createMoney(user_id, source, balance, action, money, from, from_user_id) void
}
DistributionService --> WalletService : "调用"

分享推广

• 分享记录
  • 统一入口展示当前登录用户的分享记录分页，便于用户查看推广明细。
• 与分销联动
  • 分享行为通常作为分销链路的前置动作，具体转化与佣金结算由分销服务在订单完成后处理。

sequenceDiagram
participant U as "用户"
participant SC as "分享控制器"
participant SS as "分享服务"
U->>SC : 访问 /share
SC->>SS : buildShareListData(userId, page, url)
SS-->>SC : 分享列表+分页
SC-->>U : 渲染分享记录页面

VIP 会员

• 套餐与记录
  • 获取 VIP 套餐列表与开通记录，结合订单状态展示，便于用户续费与查看历史。
• 生命周期
  • 通过状态枚举区分生效、过期与无记录，供会员中心展示与续费提示。

stateDiagram-v2
[*] --> 无记录
无记录 --> 生效中 : "购买成功且start_at<=now<end_at"
生效中 --> 已过期 : "end_at<=now"
已过期 --> 无记录 : "清理或不再显示"

依赖关系分析

• 订单状态流转对营销的驱动
  • 订单支付成功后，触发积分消费与分销奖励派发，保证幂等与并发安全。
• 优惠券与购物车
  • 资格判定器依赖购物车行结构与券配置，计算生效金额并判断可用性。
• 分销与钱包
  • 分销服务通过钱包服务写入佣金，使用订单号作为幂等键。
• 分享与用户中心
  • 分享控制器聚合用户分享记录，服务于用户中心展示。

graph LR
Order["订单状态流转"] --> Point["积分"]
Order --> Dist["分销奖励"]
Cart["购物车"] --> Elig["优惠券资格判定"]
Dist --> Wallet["钱包服务"]
Share["分享控制器"] --> UserCenter["用户中心"]

性能与并发特性

• 幂等性保障
  • 优惠券领取与使用：通过日志表与状态字段避免重复发放与重复使用。
  • 分销佣金：以订单号为 from 字段，配合钱包写入去重，防止重复入账。
• 并发安全
  • 订单支付联动在同一事务内对订单行加锁，避免回调与后台重跑并发导致重复发放。
• 性能优化建议
  • 优惠券资格判定尽量使用索引字段（时间、状态、用户ID）。
  • 分销关系树写入设置深度上限，避免异常数据导致的长链遍历。
  • 分享列表分页加载，减少大结果集传输。

故障排查指南

• 优惠券无法使用
  • 检查券是否在有效期内、是否限首单、购物车金额是否达到门槛。
  • 参考资格判定器的时间窗口与生效金额计算逻辑。
• 分销佣金未到账
  • 确认订单状态是否为已支付/已完成，是否存在推荐人及有效等级配置。
  • 检查钱包写入是否因幂等键冲突被跳过。
• 分享记录为空
  • 确认当前用户是否已登录，分享服务是否正确构建列表数据。
• VIP 状态异常
  • 核对 VIP 记录的 start_at/end_at 与当前时间，确认状态枚举输出是否符合预期。

结论

DouPHP 营销子系统以订单事件为核心驱动，结合优惠券、分销、分享与 VIP 四大模块，形成完整的拉新、促活、转化与留存闭环。系统在幂等性与并发安全方面做了充分设计，具备较强的可扩展性与可观测性。通过合理的规则配置与数据分析，可有效提升营销活动的转化率与 ROI。

附录：开发示例与最佳实践

• 配置营销活动
  • 优惠券：设置时间窗口、适用范围（全量/分类/商品）、门槛金额、折扣类型与上限。
  • 分销：为用户等级配置直推/间推百分比，确保推荐关系正确建立。
  • 分享：在用户中心启用分享记录展示，便于追踪推广效果。
  • VIP：配置套餐价格、有效期与权益内容，结合订单状态展示。
• 处理用户参与
  • 优惠券领取：调用前端控制器接口，确保幂等领取。
  • 分销申请：调用 API 控制器进行业务校验与申请登记。
  • 分享统计：通过分享控制器获取用户分享记录，结合后端统计口径进行分析。
• 计算营销效果与 ROI
  • 优惠券：统计领取率、核销率、带动 GMV 与折扣成本。
  • 分销：统计佣金支出、新增用户数、复购率与贡献利润。
  • 分享：统计分享次数、点击转化率、最终成交数。
  • VIP：统计购买转化率、续费率与客单价提升。
• 灵活配置与扩展机制
  • 优惠券范围与门槛可通过配置项与数据库字段灵活调整。
  • 分销奖励比例按用户等级动态读取，便于分层激励。
  • 分享与 VIP 页面可通过模板与路由扩展，适配不同业务场景。