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

促销活动

简介

本开发文档面向营销开发者，系统化说明 DouPHP 促销活动体系中的“优惠券”能力，并给出如何在此基础上扩展限时折扣、买赠、秒杀、拼团等活动的技术路径。文档覆盖活动创建、配置、执行、监控全流程，重点解析规则引擎、价格计算、库存扣减机制、模板与批量操作、A/B测试思路，以及效果分析与ROI评估方法。

项目结构

促销相关代码主要分布在以下区域：

核心服务层：优惠券资格判定与折扣计算
前台服务层：用户领取、列表构建
后台管理：优惠券的增删改查、日志管理
API 层：小程序端领取接口
路由：后台与API路由声明
视图：后台列表页展示
外部集成：支付宝营销活动SDK（用于未来对接）

graph TB
subgraph "后台管理"
AC["CouponController<br/>admin/controller/coupon"]
AR["路由<br/>admin/route/coupon.php"]
AV["视图<br/>admin/view/coupon.htm"]
end
subgraph "前台与小程序"
FS["前台服务<br/>front/service/coupon/CouponService"]
APIC["API控制器<br/>api/controller/coupon/CouponController"]
APR["API路由<br/>_'/module/coupon/api/route/coupon.php"]
end
subgraph "核心服务"
CS["核心服务<br/>core/service/coupon/CouponService"]
CE["资格判定<br/>core/service/coupon/CouponEligibility"]
end
subgraph "外部集成"
ALI["支付宝营销SDK请求类<br/>plugin/alipaywap/.../AlipayMarketingCampaignDiscountOperateRequest"]
end
AR --> AC
AC --> CS
FS --> CS
APIC --> FS
APIC --> CS
CS --> CE
AC --> AV
APIC -.-> ALI

核心组件

核心优惠券服务：提供券列表、状态、过期判断、折扣计算、券码生成等能力
资格判定器：基于范围（全量/模块/分类/商品）、首单限制、时间窗口与门槛金额，判定购物车是否可用
前台服务：负责用户领券入库、分页构建用户券列表
后台控制器：提供券的CRUD、批量动作入口
API控制器：小程序端领券接口
路由：后台与API路由映射
视图：后台券列表展示
外部集成：支付宝营销活动SDK（预留对接点）

架构总览

系统采用分层架构：

表现层：后台控制器与视图、API控制器
业务层：前台服务、核心服务、资格判定器
数据层：数据库表 coupon、coupon_log、order 等
外部集成：支付宝营销活动SDK

sequenceDiagram
participant Admin as "后台管理员"
participant AC as "后台控制器"
participant CS as "核心优惠券服务"
participant DB as "数据库"
participant View as "后台视图"
Admin->>AC : 访问券列表/编辑/删除
AC->>CS : 调用查询/插入/更新/删除
CS->>DB : 读写 coupon / coupon_log
DB-->>CS : 返回数据
CS-->>AC : 返回结果
AC->>View : 渲染页面
View-->>Admin : 展示结果

详细组件分析

优惠券资格判定（规则引擎）

功能：根据券的范围（全量/模块/分类/商品）、首单限制、时间窗口、门槛金额，判定购物车是否满足使用条件，并计算生效范围内金额
关键流程：
- 校验券状态与有效期
- 首单限制检查
- 计算命中范围的购物车金额合计
- 比较门槛金额得出是否可用

flowchart TD
Start(["开始"]) --> CheckStatus["检查券状态与有效期"]
CheckStatus --> |不通过| ReturnFalse["不可用"]
CheckStatus --> |通过| FirstOrder{"是否首单限制?"}
FirstOrder --> |是且非首单| ReturnFalse
FirstOrder --> |否或满足| CalcAmount["计算命中范围金额"]
CalcAmount --> Threshold{"达到门槛?"}
Threshold --> |否| ReturnFalse
Threshold --> |是| ReturnTrue["可用"]

价格计算算法（折扣计算）

支持两种优惠类型：
- 百分比折扣：按订单金额乘以比例，可设置最大减免上限
- 固定金额折扣：直接减去面额
计算步骤：
- 校验券有效性（状态、有效期、已使用）
- 判断订单金额是否满足门槛
- 按类型计算减免金额，必要时应用上限
- 输出最终应付金额与优惠明细

flowchart TD
S(["进入折扣计算"]) --> Validate["校验券状态/有效期/使用记录"]
Validate --> |无效| NoDiscount["无优惠"]
Validate --> |有效| CheckThreshold{"满足门槛?"}
CheckThreshold --> |否| NoDiscount
CheckThreshold --> |是| Type{"类型"}
Type --> |百分比| Percent["按比例计算减免<br/>应用最大减免上限"]
Type --> |固定金额| Fixed["直接减去面额"]
Percent --> Final["计算应付金额"]
Fixed --> Final
Final --> Out["返回优惠明细与应付金额"]

库存扣减机制（与活动联动）

当前代码未实现独立“活动库存”表；如需秒杀/拼团等强一致性场景，建议在订单创建前对活动库存进行原子扣减，并在支付成功后确认扣减，失败则回滚
推荐模式：
- 预占库存：下单时锁定库存（带超时释放）
- 支付成功：确认扣减
- 支付失败/取消：释放预占
- 幂等与防超卖：使用唯一键或分布式锁

活动模板管理与批量操作

后台提供券的创建、编辑、删除、列表展示与批量动作入口
列表页包含关键字段：编号、名称、类型、金额、门槛、起止时间、状态
批量操作通过 action 路由统一处理，便于扩展更多批量任务

sequenceDiagram
participant Admin as "后台管理员"
participant AC as "后台控制器"
participant CS as "核心服务"
participant DB as "数据库"
participant View as "后台视图"
Admin->>AC : 提交批量动作
AC->>CS : 执行批量逻辑
CS->>DB : 批量更新/删除
DB-->>CS : 返回影响行数
CS-->>AC : 返回结果
AC->>View : 重定向并提示

A/B测试与高级功能

在券维度增加实验分组字段（如 campaign_id），结合资格判定器对不同组发放不同券或不同门槛
统计各组的领取率、核销率、客单价提升、转化率等指标，对比评估活动效果
结合埋点与报表，形成闭环优化

小程序领券流程

小程序调用API领取券，若用户未领取过则写入领取记录
返回用户券列表，供前端展示

sequenceDiagram
participant App as "小程序"
participant API as "API控制器"
participant FS as "前台服务"
participant CS as "核心服务"
participant DB as "数据库"
App->>API : POST /api/coupon/claim?id=xxx
API->>FS : claimCouponIfNew(userId, id, ip)
FS->>DB : 检查是否已领取
FS->>DB : 插入领取记录
API->>CS : getCouponList(userId)
CS-->>API : 返回券列表
API-->>App : 返回成功与券列表

依赖关系分析

控制器依赖服务：后台与API控制器均依赖核心服务完成业务逻辑
服务依赖数据库：通过ORM进行读写
资格判定器依赖订单状态常量：用于首单判定
路由将URL映射到控制器方法，支撑前后端交互

graph LR
AR["后台路由"] --> AC["后台控制器"]
APR["API路由"] --> APIC["API控制器"]
AC --> CS["核心服务"]
APIC --> FS["前台服务"]
FS --> CS
CS --> CE["资格判定器"]
CS --> DB["数据库"]

性能与高并发建议

缓存热点数据：券列表、状态、过期信息可缓存，减少数据库压力
索引优化：对 coupon 的 start_at、end_at、status、id 建立合适索引；coupon_log 的 user_id、coupon_id 建立复合索引
限流与熔断：API层增加限流中间件，防止恶意刷领
异步化：领券、统计上报等可异步处理，降低主链路延迟
幂等设计：领券接口需保证幂等，避免重复领取
分库分表：随着数据增长，考虑按用户或时间维度拆分

故障排查指南

券不可用：检查券状态、有效期、门槛金额、首单限制
领取失败：检查用户是否已领取、网络异常、数据库写入失败
折扣异常：核对券类型、面额、最大减免上限、订单金额是否满足门槛
列表为空：检查分页参数、过滤条件、权限控制

结论

DouPHP 的优惠券子系统提供了完整的资格判定与折扣计算能力，并通过后台与API层实现了券的管理与领取。基于此基础，可快速扩展限时折扣、买赠、秒杀、拼团等活动类型。建议在高并发场景下引入缓存、限流、幂等与异步化策略，并结合A/B测试与数据分析持续优化活动效果与ROI。

附录：活动类型与扩展要点

限时折扣：在券中增加“限时”标签与时间窗口，配合资格判定器的时间校验即可实现
买赠活动：通过资格判定器限定参与商品范围，并在结算时叠加赠品逻辑
秒杀活动：需要独立的库存模型与预占机制，结合排队与限流保障稳定性
拼团活动：引入拼团会话、成团条件、团长奖励等模型，结合券与活动规则组合使用
外部集成：可使用支付宝营销活动SDK作为外部渠道的补充能力

添加日期：2026-10-05