简介
本文件面向DouPHP电商系统的营销推广模块，聚焦优惠券、促销活动、分销商、分享记录等核心表的数据模型与业务逻辑。文档基于仓库中已实现的优惠券与分销等级模型、服务与路由进行梳理，给出表结构设计、发放使用流程、活动规则引擎、分销佣金计算、推广效果追踪、营销分析与ROI计算的数据支撑方案，并提供并发控制、防刷机制与性能优化建议，帮助开发者构建高可用、可观测的营销活动体系。
项目结构
营销相关代码主要分布在以下位置：
- 后台管理：admin/model、admin/service、admin/route
- 前台服务：front/service
- 核心能力：_'/module/...（如优惠券资格判定）
- API路由：_'/module/coupon/api/route
graph TB
subgraph "后台管理"
A["admin/model/coupon/Coupon.php"]
B["admin/model/coupon/CouponLog.php"]
C["admin/service/coupon/CouponService.php"]
D["admin/route/coupon.php"]
end
subgraph "前台服务"
E["front/service/coupon/CouponService.php"]
end
subgraph "核心能力"
F["_'/module/coupon/core/service/coupon/CouponEligibility.php"]
end
subgraph "API路由"
G["_'/module/coupon/api/route/coupon.php"]
end
D --> C
C --> A
C --> B
E --> F
G --> E核心组件
- 优惠券主数据：coupon（名称、券码、类型、面值、门槛、有效期、状态、排序等）
- 优惠券流水：coupon_log（领取/使用记录、用户、券、状态、时间戳）
- 优惠券资格判定：CouponEligibility（依据 scope_type/scope_value/is_first_order_only/condition 判断购物车是否可用并计算生效金额）
- 后台服务：CouponService（管理券、日志等）
- 前台服务：CouponService（面向用户的领券、查看等）
- 分销等级：distribution_level（直推/间推奖励比例、升级条件）
架构总览
营销推广的核心链路包括：活动配置（券/活动/分销等级）、用户行为（领取/使用/分享）、订单结算（券抵扣/分销佣金）、数据分析（转化/ROI）。
sequenceDiagram
participant U as "用户"
participant API as "API路由"
participant FS as "前台服务"
participant CE as "资格判定"
participant AS as "后台服务"
participant DB as "数据库(coupon/coupon_log)"
U->>API : 请求领券/查看券
API->>FS : 调用前台服务
FS->>CE : 校验券可用性(范围/门槛/首单限制)
CE-->>FS : 返回可用性与生效金额
FS->>DB : 写入领取记录(coupon_log)
FS-->>U : 返回结果
Note over FS,DB : 后台通过CouponService管理券与日志详细组件分析
优惠券表（coupon）设计
- 用途：定义营销券的基础信息与规则，支撑前台展示、后台管理与结算抵扣。
- 关键字段（依据模型映射推断）：id、name、coupon_sn、type、face_value、condition、start_at、end_at、brief、status、sort、created_at。
- 索引建议：
- coupon_sn 唯一索引（防重复发放）
- status + start_at + end_at 复合索引（活动期筛选）
- type 索引（按券类型查询）
- 扩展点：scope_type、scope_value、is_first_order_only 用于限定适用商品/分类/首单等场景。
优惠券流水表（coupon_log）设计
- 用途：记录每次领取与使用，支持审计、统计与风控。
- 关键字段（依据模型映射推断）：id、user_id、coupon_id、status、claimed_at、used_at、created_at。
- 索引建议：
- user_id + coupon_id 联合索引（去重与查询）
- status + claimed_at / used_at 复合索引（报表统计）
- 行为约束：同一用户在同一券上的领取/使用需幂等；状态机包含未使用/已使用/已过期等。
优惠券资格判定（规则引擎）
- 职责：根据券的适用范围、门槛、首单限制等规则，判断购物车行是否满足使用条件，并计算“生效范围内金额”。
- 输入约定：购物车行数组含 module、category_id、item_id、amount 等。
- 输出：是否可用、生效金额、剩余门槛等。
- 扩展性：可通过策略模式新增不同 scope_type 的匹配器（如按品牌、按满减区间）。
flowchart TD
Start(["开始"]) --> LoadRule["加载券规则<br/>scope_type/scope_value/is_first_order_only/condition"]
LoadRule --> CheckScope{"命中范围?"}
CheckScope --> |否| Reject["不可用"]
CheckScope --> |是| CheckThreshold{"满足门槛?"}
CheckThreshold --> |否| CalcRemainder["计算剩余门槛"]
CheckThreshold --> |是| CalcAmount["计算生效金额"]
CalcRemainder --> Return["返回不可用+剩余门槛"]
CalcAmount --> Return
Reject --> End(["结束"])
Return --> End后台与前台服务
- 后台 CouponService：负责券的创建、编辑、上下架、日志管理等。
- 前台 CouponService：封装用户侧领券、查看可用券等能力，并委托核心资格判定。
- 路由：
- 后台：admin/route/coupon.php 提供资源型路由与日志操作。
- 前台API：_'/module/coupon/api/route/coupon.php 暴露 /api/?route=coupon 系列接口。
classDiagram
class Admin_CouponService {
+管理券
+管理券日志
}
class Front_CouponService {
+领券
+查看可用券
}
class Coupon_Eligibility {
+判断券可用
+计算生效金额
}
Admin_CouponService --> "使用" Coupon_Log : "读写"
Admin_CouponService --> "使用" Coupon : "读写"
Front_CouponService --> "委托" Coupon_Eligibility : "规则判定"促销活动表（promotion）设计建议
- 目标：统一管理限时折扣、满减、秒杀等活动，与券解耦但可叠加。
- 建议字段：id、name、type、scope_type、scope_value、start_at、end_at、priority、status、config(json)。
- 关联：可与 product/product_category 建立范围映射；与 order 关联以统计活动贡献。
- 索引：status + start_at + end_at；scope_type + scope_value。
分销商表（distributor）与分销等级（distribution_level）
- 分销等级：直推/间推奖励比例、升级条件（金额阈值），用于计算佣金。
- 分销商：记录邀请关系、等级、累计业绩、可提现余额等。
- 佣金计算：order_amount × direct_reward_percent（直推）/ indirect_reward_percent（间推），结合等级与升级条件动态调整。
- 索引：inviter_id、level_id、status、created_at。
分享记录表（share）设计建议
- 目标：追踪分享渠道、来源、点击与转化，支撑推广效果分析。
- 建议字段：id、user_id、target_type、target_id、channel、source、campaign、click_count、conversion_count、created_at。
- 索引：user_id + channel；campaign + created_at。
依赖关系分析
- 路由层：后台与API路由分别将请求分发至对应控制器与服务。
- 服务层：前台服务依赖资格判定核心；后台服务管理券与日志。
- 数据层：coupon、coupon_log、distribution_level 为核心数据表。
graph LR
R1["admin/route/coupon.php"] --> S1["admin/service/coupon/CouponService.php"]
R2["_'/module/coupon/api/route/coupon.php"] --> S2["front/service/coupon/CouponService.php"]
S2 --> E["_'/module/coupon/core/service/coupon/CouponEligibility.php"]
S1 --> M1["admin/model/coupon/Coupon.php"]
S1 --> M2["admin/model/coupon/CouponLog.php"]性能与并发控制
- 并发控制
- 领券/使用采用数据库唯一约束或乐观锁（version）防止超发。
- 热点券发放引入分布式锁（Redis SETNX）+ 队列异步落库。
- 防刷机制
- 接口限流：基于IP/用户ID的滑动窗口限流。
- 验证码/设备指纹：高风险操作增加验证。
- 风控规则：异常频率、批量领取拦截。
- 查询优化
- 合理索引：coupon(status,start_at,end_at)、coupon_log(user_id,coupon_id,status,claimed_at)。
- 分页与只读缓存：热门券列表使用缓存，减少DB压力。
- 事务与一致性
- 领券/使用写库在事务内完成，保证状态一致。
- 对账任务定期核对券状态与订单抵扣。
故障排查指南
- 常见问题
- 券不可用：检查 scope_type/scope_value 与购物车行匹配；确认 is_first_order_only 与 condition。
- 领取失败：检查 coupon_log 是否存在重复记录；确认并发锁与唯一约束。
- 使用失败：核对订单金额是否达到门槛；检查券有效期与状态。
- 定位方法
- 通过 coupon_log 的 status、claimed_at、used_at 定位问题阶段。
- 使用后台日志与接口监控定位异常路径。
- 恢复策略
- 回滚错误状态；补录缺失流水；清理脏数据后重试。
结论
本方案围绕 coupon、coupon_log、distribution_level 等核心表，构建了从活动配置到用户行为、订单结算与数据分析的完整营销数据模型。通过规则引擎、并发控制与防刷机制，确保系统在大规模促销场景下的稳定性与准确性。后续可扩展 promotion、share 等表以完善活动与推广追踪能力，并结合埋点与报表实现ROI评估。
附录：数据模型与字段说明
- 优惠券表（coupon）
- 字段：id、name、coupon_sn、type、face_value、condition、start_at、end_at、brief、status、sort、created_at
- 索引：coupon_sn(唯一)、status+start_at+end_at、type
- 优惠券流水表（coupon_log）
- 字段：id、user_id、coupon_id、status、claimed_at、used_at、created_at
- 索引：user_id+coupon_id、status+claimed_at/used_at
- 分销等级表（distribution_level）
- 字段：id、name、direct_reward_percent、indirect_reward_percent、upgrade_condition_amount、sort、created_at
- 索引：sort、name
- 促销活动表（promotion，建议）
- 字段：id、name、type、scope_type、scope_value、start_at、end_at、priority、status、config
- 索引：status+start_at+end_at、scope_type+scope_value
- 分享记录表（share，建议）
- 字段：id、user_id、target_type、target_id、channel、source、campaign、click_count、conversion_count、created_at
- 索引：user_id+channel、campaign+created_at