简介

本设计文档面向DouPHP促销活动的数据层，聚焦“商品促销”和“优惠券”两条主线，给出主表、活动商品关联、规则配置等核心表的设计说明。内容涵盖促销类型定义、活动时间范围、参与商品管理、优惠计算规则、活动状态管理、库存控制与价格计算等业务逻辑的数据模型，并提供表关系图与性能优化建议，帮助营销系统开发者与运营人员快速理解并落地实施。

项目结构与范围

• 商品模块前台模型定义了商品主表映射与基础查询能力，用于承载促销相关字段（如促销价、促销起止时间）及列表展示所需信息。
• 产品升级脚本中明确对商品表增加了促销起止时间字段，体现“按商品维度”的促销能力。
• 优惠券服务实现了基于时间窗与状态的可用券筛选、折扣计算与核销流程，体现“活动规则配置”和“优惠计算规则”的数据支撑。
• 结账服务在下单时完成优惠券可用性校验、折扣计算与日志落库，体现“活动状态管理”和“库存/订单联动”的关键路径。

章节来源

• front/model/product/Product.php:59-76
• _'/module/product/_update/data/upgrade.php:25-29
• _'/module/coupon/core/service/coupon/CouponService.php:37-70
• _'/module/order/front/service/order/CheckoutService.php:170-202

核心数据模型总览

围绕促销体系，数据模型分为三层：

• 商品层：商品主表承载基础信息与促销价、促销时间窗；分类表提供类目组织。
• 优惠券层：优惠券主表定义活动规则（类型、面额、门槛、有效期），用户领取与使用通过日志表记录。
• 订单结算层：结账流程读取购物车与优惠券，进行资格校验与折扣计算，最终落库订单与优惠券使用明细。

graph TB
A["商品表<br/>product"] --> B["商品分类表<br/>product_category"]
C["优惠券主表<br/>coupon"] --> D["优惠券使用日志<br/>coupon_log"]
E["订单结算流程<br/>CheckoutService"] --> C
E --> D
A -.促销价/时间窗.-> E
C -.规则/有效期.-> E

图表来源

• front/model/product/Product.php:59-76
• _'/module/product/_update/data/upgrade.php:25-29
• _'/module/coupon/core/service/coupon/CouponService.php:37-70
• _'/module/order/front/service/order/CheckoutService.php:170-202

架构与关系概览

• 商品促销：以商品为粒度，支持设置促销价与起止时间，前端列表与详情可据此展示促销信息。
• 优惠券促销：以券为粒度，支持满减、折扣等规则，结合用户领取与使用日志实现活动生命周期管理。
• 结算联动：订单结算阶段统一读取购物车金额与可用券，执行资格校验与折扣计算，并记录使用明细。

sequenceDiagram
participant U as "用户"
participant F as "前台页面"
participant O as "订单结算服务"
participant CS as "优惠券服务"
participant DB as "数据库"
U->>F : 进入结算页
F->>O : 提交购物车与可选优惠券ID
O->>CS : 校验优惠券可用性(时间窗/状态/门槛)
CS->>DB : 查询coupon与coupon_log
DB-->>CS : 返回券信息与使用记录
CS-->>O : 返回是否可用及折扣金额
O->>DB : 更新coupon_log(标记已用/写订单号)
O-->>F : 返回折后订单金额

图表来源

• _'/module/order/front/service/order/CheckoutService.php:170-202
• _'/module/coupon/core/service/coupon/CouponService.php:37-70

详细表结构设计

以下表结构说明基于代码与升级脚本中的字段与行为归纳，便于营销系统与运营侧理解与扩展。

商品表（product）

• 作用：承载商品基础信息与促销价、促销时间窗，支撑商品级促销展示与结算时的价格计算。
• 关键字段（依据升级脚本与模型推断）：
  • promote_price：促销价（数值型）
  • promote_start_at：促销开始时间（DATETIME）
  • promote_end_at：促销结束时间（DATETIME）
  • status：上架状态（用于过滤在售商品）
  • stock/sales：库存与销售计数（用于库存控制与热销展示）
• 业务含义：
  • 促销时间窗决定该商品是否处于促销期；
  • 促销价与原价共同决定前端展示与结算折扣；
  • 库存字段用于下单扣减与超卖防护。

章节来源

• _'/module/product/_update/data/upgrade.php:25-29
• front/model/product/Product.php:62-70

商品分类表（product_category）

• 作用：组织商品类目，支持导航与筛选；当前版本包含同步到导航开关与图标字段。
• 关键字段：
  • parent_id：父类ID（树形结构）
  • sort：排序权重
  • sync_to_nav：是否同步到导航
  • icon：分类图标

章节来源

• _'/module/product/_update/data/upgrade.php:30-34
• front/model/product/ProductCategory.php:47-51

优惠券主表（coupon）

• 作用：定义促销活动规则，包括类型、面额、门槛、有效期与状态。
• 关键字段（依据服务代码推断）：
  • type：类型（如百分比或固定金额）
  • face_value：面额（百分比或金额）
  • condition：使用门槛（满额条件）
  • start_at/end_at：活动有效期（DATETIME）
  • status：活动状态（启用/禁用）
  • brief/name：活动名称与摘要
• 业务含义：
  • 通过start_at/end_at与status控制活动是否生效；
  • 根据type与face_value计算折扣；
  • condition限制最低消费门槛。

章节来源

• _'/module/coupon/core/service/coupon/CouponService.php:37-70
• _'/module/coupon/core/service/coupon/CouponService.php:111-164

优惠券使用日志（coupon_log）

• 作用：记录用户领取、使用与过期状态，支撑“活动状态管理”与“使用次数/限领”控制。
• 关键字段（依据服务代码推断）：
  • coupon_id：关联优惠券ID
  • user_id：用户ID
  • status：状态（未使用/已使用/已过期）
  • used_at：使用时间
  • order_sn：关联订单号
• 业务含义：
  • 通过status与used_at判断券是否可用；
  • 通过order_sn追溯使用明细；
  • 支持“每人限领/限用”的业务规则。

章节来源

• _'/module/coupon/core/service/coupon/CouponService.php:73-98
• _'/module/order/front/service/order/CheckoutService.php:421-442

订单结算与价格计算（流程）

• 作用：在结账阶段读取购物车金额与可用券，校验资格并计算折扣，最终生成订单与使用明细。
• 关键步骤：
  • 加载用户拥有的有效券；
  • 校验券是否过期、是否满足门槛；
  • 计算折扣金额并限制不超过商品总额；
  • 更新券使用日志并写入订单关联信息。

章节来源

• _'/module/order/front/service/order/CheckoutService.php:170-202
• _'/module/order/front/service/order/CheckoutService.php:421-442

依赖与关联分析

• 商品与分类：一对多关系，商品归属分类，便于按类目筛选促销商品。
• 优惠券与日志：一对一或多对一关系，一张券可被多次领取但每次使用产生一条日志。
• 结算与服务：结算流程依赖优惠券服务进行资格校验与折扣计算，形成强耦合的服务调用链。

erDiagram
PRODUCT ||--o{ PRODUCT_CATEGORY : "属于"
COUPON ||--o{ COUPON_LOG : "被使用记录"
ORDER ||--o{ COUPON_LOG : "关联订单号"

图表来源

• front/model/product/Product.php:123-137
• _'/module/coupon/core/service/coupon/CouponService.php:73-98
• _'/module/order/front/service/order/CheckoutService.php:421-442

性能优化策略

• 索引建议：
  • product：promote_start_at、promote_end_at、status、category_id建立复合索引，加速促销商品筛选与列表查询。
  • coupon：start_at、end_at、status建立复合索引，提升活动券筛选效率。
  • coupon_log：user_id、coupon_id、status建立复合索引，优化用户券列表与使用状态查询。
• 查询优化：
  • 列表页采用批量预加载（如分类、附件、多语言），减少N+1查询。
  • 结算流程缓存用户可用券集合，避免重复查询。
• 事务与一致性：
  • 优惠券核销与订单创建在同一事务中，保证数据一致性。
• 读写分离与缓存：
  • 活动规则与商品促销信息可缓存至Redis，降低热点读压力。

故障排查指南

• 活动未生效：
  • 检查coupon.start_at/end_at与当前时间关系；
  • 检查coupon.status是否为启用；
  • 核对promotion时间窗是否正确设置。
• 折扣计算异常：
  • 确认coupon.type与face_value组合是否符合预期；
  • 校验condition门槛是否满足；
  • 检查max_discount上限是否截断折扣。
• 券被重复使用：
  • 核查coupon_log.user_id与coupon_id唯一性约束；
  • 检查used_at与status更新逻辑是否覆盖。
• 库存不足导致下单失败：
  • 核对stock扣减逻辑与并发锁机制；
  • 检查超卖保护与回滚策略。

章节来源

• _'/module/coupon/core/service/coupon/CouponService.php:111-164
• _'/module/order/front/service/order/CheckoutService.php:170-202

结论

本设计文档基于DouPHP现有代码与升级脚本，梳理了商品促销与优惠券促销的核心表结构与业务流程。通过明确促销时间窗、活动规则、参与商品管理与优惠计算规则的数据模型，为营销活动的高效落地提供了可靠支撑。建议在后续迭代中完善活动商品关联表与更细粒度的规则配置表，并结合索引与缓存策略提升整体性能。

附录：字段与索引建议

• 商品表（product）
  • 字段：promote_price、promote_start_at、promote_end_at、status、stock、sales
  • 索引：idx_promo_time(status, promote_start_at, promote_end_at)、idx_category(category_id)
• 优惠券主表（coupon）
  • 字段：type、face_value、condition、start_at、end_at、status、brief、name
  • 索引：idx_active(status, start_at, end_at)
• 优惠券使用日志（coupon_log）
  • 字段：coupon_id、user_id、status、used_at、order_sn
  • 索引：idx_user_status(user_id, status)、idx_coupon_user(coupon_id, user_id)

章节来源

• _'/module/product/_update/data/upgrade.php:25-29
• _'/module/coupon/core/service/coupon/CouponService.php:37-70
• _'/module/order/front/service/order/CheckoutService.php:421-442