简介

本文件面向营销开发者，系统化梳理 DouPHP 的营销能力：优惠券系统、促销活动（含外部平台活动对接）、分销系统、分享推广、投票系统等。文档围绕“业务规则—数据流—接口—扩展点”展开，给出关键流程的时序图与流程图，并提供可操作的扩展建议与最佳实践，帮助快速创建自定义营销活动、扩展促销规则、集成社交分享渠道，并支持效果分析与 A/B 测试思路。

项目结构

营销相关能力以“模块 + 服务层”组织，前后端通过路由与控制器接入，核心计算逻辑集中在 core/service 与各模块 service 中：

• 优惠券：API 与后台路由分别定义领取、查询等入口；CouponService 提供优惠计算、状态判断、券码生成等能力。
• 分销：DistributionService 负责订单完成后的佣金派发、层级关系记录与查询，严格限制返利层级。
• 分享：ShareService 提供分享申请提交、列表构建、待处理计数等能力。
• 投票：VoteService 提供投票时间状态、IP 限票、二维码生成、统计快照等能力。
• 外部活动：支付宝营销 API 请求对象用于与外部平台活动联动。

graph TB
subgraph "前端/客户端"
FE["前台页面/小程序"]
end
subgraph "路由与控制器"
R_API["API 路由<br/>coupon/share/vote"]
R_ADMIN["后台路由<br/>coupon"]
end
subgraph "服务层"
S_COUPON["CouponService"]
S_DIST["DistributionService"]
S_SHARE["ShareService"]
S_VOTE["VoteService"]
end
subgraph "数据与外部"
DB[("数据库")]
ALI["支付宝营销API"]
end
FE --> R_API
FE --> R_ADMIN
R_API --> S_COUPON
R_API --> S_SHARE
R_API --> S_VOTE
R_ADMIN --> S_COUPON
S_COUPON --> DB
S_SHARE --> DB
S_VOTE --> DB
S_DIST --> DB
S_DIST --> ALI

核心组件

• 优惠券服务：提供优惠券列表、用户可用券、折扣计算、状态判定、过期判断、券码生成。
• 分销服务：在订单支付/完成后按直推/间推比例发放佣金，维护上下级关系树，限制返利层级。
• 分享服务：分享申请提交、附件认领、分页列表构建、待处理计数。
• 投票服务：投票时间状态、IP 限票、二维码生成、统计快照。
• 外部活动：支付宝营销活动的请求封装，便于与外部平台联动。

架构总览

营销引擎由“路由/控制器 → 服务层 → 数据/外部系统”构成。优惠券、分享、投票均提供独立的服务类，分销与订单状态变更强耦合，确保并发安全与幂等性。

sequenceDiagram
participant U as "用户"
participant API as "API 路由"
participant CS as "CouponService"
participant DS as "DistributionService"
participant OS as "OrderStatusTransition"
participant DB as "数据库"
U->>API : 领取/使用优惠券
API->>CS : 获取可用券/计算折扣
CS->>DB : 查询券/券日志
DB-->>CS : 券信息/状态
CS-->>API : 返回可用券/折扣结果
Note over OS,DS : 订单支付/完成后触发分销奖励
OS->>DS : orderReward(order_sn)
DS->>DB : 读取订单/检查重复发放
DS->>DB : 写入钱包入账
DB-->>DS : 成功
DS-->>OS : 完成

详细组件分析

优惠券系统

• 功能要点
  • 列出当前有效且未过期的优惠券，附带语言化名称与金额展示。
  • 用户已领取券的状态判定：未领取/已领取/已使用/已过期。
  • 折扣计算：支持按比例或固定金额扣减，支持封顶折扣。
  • 券码生成：唯一短码，冲突时递归重试。
• 关键流程（折扣计算）

  flowchart TD
  Start(["进入 discount"]) --> CheckExist["检查用户是否已领取该券"]
  CheckExist --> |否| EndNo["返回空折扣"]
  CheckExist --> |是| CheckExpire["检查券是否过期"]
  CheckExpire --> |是| EndNo
  CheckExpire --> |否| LoadCoupon["加载券配置"]
  LoadCoupon --> CheckCondition{"满足门槛?"}
  CheckCondition --> |否| EndNo
  CheckCondition --> |是| CalcType{"类型: 百分比/固定"}
  CalcType --> |百分比| Percent["按比例计算并应用封顶"]
  CalcType --> |固定| Fixed["直接扣除固定金额"]
  Percent --> Return["返回折扣明细"]
  Fixed --> Return
  EndNo --> End(["结束"])
  Return --> End

促销活动与外部活动对接

• 内部促销：基于优惠券与分销佣金组合，形成“满减/折扣+佣金”的复合促销。
• 外部活动：通过支付宝营销 API 请求对象进行活动操作（如立减活动），便于与外部平台联动。

分销系统

• 功能要点
  • 订单进入 PAID/COMPLETED 时派发佣金，仅对直推与间推两级发放，法律合规。
  • 关系树记录：沿上级链上溯记录各级关系，用于报表与可视化。
  • 奖励比例：从用户等级配置读取直推/间推百分比。
• 关键流程（订单奖励派发）

  sequenceDiagram
  participant OS as "OrderStatusTransition"
  participant DS as "DistributionService"
  participant DB as "数据库"
  OS->>DS : orderReward(order_sn)
  DS->>DB : 查询订单(状态=PAID/COMPLETED, 有推荐人)
  DB-->>DS : 订单信息
  alt 命中条件
  DS->>DB : 检查是否已发放(幂等)
  DB-->>DS : 无重复
  DS->>DB : 写入钱包入账(直推/间推)
  DB-->>DS : 成功
  else 未命中
  DS-->>OS : 跳过
  end

分享推广

• 功能要点
  • 提交分享申请：创建分享记录并将草稿附件认领到真实主键。
  • 列表构建：分页展示分享项，关联图片与积分奖励（可选）。
  • 待处理计数：统计用户待审核数量。
• 关键流程（提交分享申请）

  flowchart TD
  Start(["提交分享申请"]) --> Create["创建分享记录(status=0)"]
  Create --> Claim["认领草稿附件到分享主键"]
  Claim --> |成功| Done["返回成功"]
  Claim --> |失败| Rollback["删除分享记录并返回失败"]

投票系统

• 功能要点
  • 时间状态：未开始/已结束判断。
  • IP 限票：单 IP 投票次数上限控制。
  • 二维码：为投票详情生成二维码（区分 web/mini）。
  • 统计快照：候选项数、投票日志数、点击量。
• 关键流程（投票校验）

  flowchart TD
  Start(["发起投票"]) --> TimeCheck{"时间允许?"}
  TimeCheck --> |否| ErrTime["提示不可投票"]
  TimeCheck --> |是| IpCheck{"是否已达上限?"}
  IpCheck --> |是| ErrMax["提示达到上限"]
  IpCheck --> |否| Vote["记录投票日志"]
  Vote --> Ok["返回成功"]

依赖关系分析

• 优惠券服务依赖数据库表 coupon、coupon_log，以及语言包与价格格式化。
• 分销服务依赖订单状态常量、钱包服务、用户等级配置，并在订单状态转换中被调用。
• 分享服务依赖附件系统与模型 Share，支持可选积分功能开关。
• 投票服务依赖数据库表 vote、vote_option、vote_log 及二维码库。
• 外部活动依赖支付宝 SDK 的请求对象。

graph LR
Coupon["CouponService"] --> DB1[("coupon / coupon_log")]
Distribution["DistributionService"] --> DB2[("order / money / user / distribution_level")]
Share["ShareService"] --> DB3[("share / attachment")]
Vote["VoteService"] --> DB4[("vote / vote_option / vote_log")]
OrderTrans["OrderStatusTransition"] --> Distribution

性能与并发考量

• 优惠券折扣计算
  • 先查领取记录再读券配置，避免无效计算；过期判断集中处理，减少重复 IO。
  • 百分比折扣支持封顶，防止极端场景下的过度让利。
• 分销奖励派发
  • 在订单状态转换中使用事务与行锁（FOR UPDATE）保证并发安全，结合 from=order_sn 去重，避免重复发放。
  • 返利层级硬封顶至二级，降低复杂度与合规风险。
• 分享与投票
  • 分享附件采用“草稿令牌认领”，减少并发冲突；投票 IP 限票通过计数快速拦截。
• 外部活动
  • 通过 SDK 请求对象统一封装参数，便于缓存与重试策略。

故障排查指南

• 优惠券无法使用
  • 检查券是否在有效期内、是否满足门槛、用户是否已领取且未使用。
  • 关注折扣封顶与金额精度设置。
• 分销奖励未到账
  • 确认订单状态是否为 PAID/COMPLETED，是否存在推荐人，是否已被发放（幂等）。
  • 检查用户等级配置中的直推/间推比例。
• 分享申请失败
  • 检查草稿令牌是否有效，附件认领是否成功，失败会回滚分享记录。
• 投票被拒绝
  • 检查时间状态与 IP 限票是否达到上限。

结论

DouPHP 的营销体系以清晰的服务分层与严格的并发控制为基础，覆盖优惠券、分销、分享、投票等核心场景，并通过外部活动对接增强生态联动。建议在扩展时遵循“规则与服务解耦、幂等与风控优先”的原则，利用现有服务接口快速搭建新的营销活动。

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

• 创建自定义营销活动
  • 基于优惠券与分销组合：在前台路由新增活动入口，调用 CouponService.discount 计算优惠，结合 DistributionService.rewardPercent 获取佣金比例，形成“下单即享折扣+返佣”的活动。
  • 参考路径：
    • module/coupon/api/route/coupon.php:31-39
    • core/service/coupon/CouponService.php:111-164
    • _'/module/distribution/core/service/distribution/DistributionService.php:128-148
• 扩展促销规则
  • 在折扣计算前插入规则钩子：例如叠加限时折扣、会员等级折扣，注意封顶与精度控制。
  • 参考路径：
    • core/service/coupon/CouponService.php:111-164
• 集成社交分享渠道
  • 复用 ShareService.submitShareApply 提交分享申请，结合模板渲染分享落地页，并在分享链接中携带邀请参数以追踪转化。
  • 参考路径：
    • _'\module\share\front\service\share/ShareService.php:50-76
• 营销效果分析与 A/B 测试
  • 利用投票统计快照思路，为活动建立“曝光/点击/转化/收益”指标采集；A/B 测试可通过不同活动 ID 或参数分组，对比转化率与客单价。
  • 参考路径：
    • _'\module\vote\core\service\vote/VoteService.php:227-235
• 用户画像与精准营销
  • 结合分销等级与消费行为，对用户分层（新客/活跃/高价值），定向推送优惠券与活动。
  • 参考路径：
    • _'\module\distribution\core\service/distribution/DistributionService.php:128-148