简介

本文件面向营销平台开发者，提供优惠券模块的完整API参考与使用说明。覆盖优惠券创建、发放、领取、使用、核销等生命周期管理；说明优惠券类型（满减券、折扣券、现金券）及适用规则配置；提供用户侧“我的优惠券”列表、状态查询、绑定等能力；并给出后台批量操作、日志审计、统计分析与自动化发放策略的建议方案。同时包含并发控制与防刷机制建议，帮助在高并发场景下稳定运行。

项目结构

本项目采用前后端分离与多入口设计：

• API层：面向小程序/移动端/第三方系统，暴露REST风格接口
• Admin层：面向运营后台，提供可视化CRUD与批量操作
• Service层：业务逻辑封装，统一处理数据访问与领域规则
• Model/ORM：数据模型与持久化（通过框架ORM访问数据库表）

graph TB
Client["客户端<br/>小程序/APP/第三方"] --> API["API控制器<br/>CouponController / UserController"]
API --> SvcFront["前端服务<br/>Front Service CouponService"]
API --> CoreSvc["核心服务<br/>Core Service CouponService"]
CoreSvc --> DB["数据库<br/>coupon / user_coupon / order_coupon 等"]
Admin["后台管理"] --> AdminCtrl["后台控制器<br/>Admin CouponController / LogController"]
AdminCtrl --> AdminSvc["后台服务<br/>Admin Service"]
AdminSvc --> DB

核心组件

• API控制器
  • 小程序优惠券控制器：负责领取、返回用户可用券列表
  • 会员中心控制器：负责“我的优惠券”分页列表展示
• 后台控制器
  • 优惠券管理：列表、新增、编辑、删除、批量动作
  • 领取记录：列表、筛选、批量删除
• 服务层
  • 核心服务：查询可领/已领券、计算状态、格式化展示数据
  • 前台服务：构建用户券列表数据、分页、链接生成
  • 后台服务：表单校验、CRUD、批量操作、日志聚合

架构总览

优惠券API遵循“控制器→服务→数据源”的分层架构。控制器仅做参数接收与响应组装，核心业务逻辑下沉至服务层，保证可测试性与复用性。

sequenceDiagram
participant C as "客户端"
participant AC as "API控制器"
participant FS as "前台服务"
participant CS as "核心服务"
participant DB as "数据库"
C->>AC : 请求领取优惠券(携带id, ip)
AC->>FS : 调用领取方法(用户ID, id, ip)
FS->>CS : 校验并发/限流/库存
CS->>DB : 检查有效期/状态/已领标记
DB-->>CS : 返回券信息与状态
CS-->>FS : 返回结果(成功/失败)
FS-->>AC : 返回用户券列表
AC-->>C : 响应{coupon_list}

详细组件分析

小程序优惠券控制器

职责

• 接收领取请求，校验用户身份与参数
• 调用前台服务完成领取流程
• 返回用户当前券列表（如领取成功）

关键流程

• 获取当前用户ID与IP
• 调用领取方法（含防重与并发控制）
• 若领取成功，拉取用户券列表并返回

flowchart TD
Start(["进入领取接口"]) --> GetCtx["获取用户ID与IP"]
GetCtx --> CallClaim["调用服务领取方法"]
CallClaim --> CheckResult{"领取成功?"}
CheckResult -- 否 --> ReturnFail["返回错误信息"]
CheckResult -- 是 --> FetchList["获取用户券列表"]
FetchList --> ReturnSuccess["返回{coupon_list}"]

会员中心“我的优惠券”接口

职责

• 按页返回当前用户的优惠券列表
• 支持分页参数与路由上下文

关键流程

• 解析分页参数
• 调用服务构建列表数据
• 组装标题、列表、分页、总数后返回

sequenceDiagram
participant U as "用户"
participant UC as "UserController"
participant FS as "前台服务"
U->>UC : GET /route=coupon/user?page=1
UC->>FS : buildCouponListData(userId, page, route)
FS-->>UC : {coupon_list, pager}
UC-->>U : {title, coupon_list, pager, total}

后台优惠券管理

职责

• 列表查询、新增、编辑、删除、批量动作
• 与后台服务交互完成表单校验与数据持久化

关键流程

• 列表：分页+过滤条件
• 新增/编辑：表单校验→写入→跳转提示
• 删除：校验ID→执行删除→返回结果
• 批量动作：根据选择项执行统一动作

flowchart TD
A["后台列表"] --> B["新增/编辑"]
B --> C["表单校验"]
C --> D{"校验通过?"}
D -- 否 --> E["返回错误"]
D -- 是 --> F["保存/更新"]
F --> G["跳转并提示"]
A --> H["删除/批量动作"]
H --> I["执行并返回结果"]

后台领取记录管理

职责

• 查看领取日志，支持时间范围、券ID、关键词筛选
• 批量删除记录

关键流程

• 合并会话中的筛选条件
• 构建日志列表与分页
• 支持批量删除

sequenceDiagram
participant OA as "运营人员"
participant LC as "LogController"
participant LS as "后台服务"
OA->>LC : 查询日志(时间/券ID/关键词)
LC->>LS : mergeSessionFilter + buildCouponLogListData
LS-->>LC : {list, pager}
LC-->>OA : 渲染列表
OA->>LC : 批量删除
LC->>LS : action(data)
LS-->>LC : 成功
LC-->>OA : 重定向并提示

核心服务：券列表与状态计算

职责

• 查询当前有效且开启的券
• 计算每个券的用户状态（可领/已领/不可用等）
• 格式化金额与类型标签

复杂度

• 单次查询为O(n)遍历结果集进行状态计算与格式化

优化建议

• 对高频列表接口增加缓存（Redis）
• 将状态判断拆分为独立方法，便于单元测试

flowchart TD
Q["查询有效券集合"] --> L["遍历每条券"]
L --> S["计算用户状态"]
S --> T["格式化类型与金额"]
T --> R["组装列表项"]
R --> End["返回列表"]

依赖关系分析

• 控制器依赖服务：API控制器依赖前台服务与核心服务；后台控制器依赖后台服务
• 服务依赖ORM：通过框架ORM访问数据库表（如coupon、user_coupon、order_coupon）
• 外部依赖：语言包用于文案国际化；中间件用于鉴权、限流与安全头

graph LR
AC["API控制器"] --> FS["前台服务"]
AC --> CS["核心服务"]
AdminC["后台控制器"] --> AdminS["后台服务"]
FS --> ORM["ORM/数据库"]
CS --> ORM
AdminS --> ORM

性能与并发控制

• 领取接口防刷
  • 基于用户ID+券ID的分布式锁或原子计数，防止重复领取
  • 结合IP与设备指纹进行短期限流（如令牌桶/滑动窗口）
• 列表接口优化
  • 对“可领券列表”进行缓存（TTL按券有效期动态设置）
  • 分页与索引优化（start_at、end_at、status、sort）
• 事务与一致性
  • 领取、绑定、使用、核销涉及多表变更时，使用事务保证一致性
  • 幂等键设计（如领取流水号），避免重复提交导致的数据不一致
• 监控与告警
  • 对高QPS接口进行指标采集（成功率、延迟、错误码分布）
  • 异常阈值触发告警，快速定位热点券或异常流量

故障排查指南

常见问题与定位思路

• 领取失败
  • 检查券是否过期、状态是否启用、用户是否已领取
  • 核对并发锁与限流策略是否误拦截
• 列表为空
  • 确认用户是否有权限、是否已绑定到账户
  • 检查缓存是否命中旧数据
• 后台批量操作失败
  • 校验输入参数与权限
  • 查看事务回滚日志与数据库约束冲突

结论

本模块以清晰的分层架构实现了优惠券的核心能力：领取、列表展示、后台管理与日志审计。通过服务层抽象，保证了业务规则的集中管理与可扩展性。建议在现有基础上完善并发控制、缓存策略与统计报表，以满足大规模营销活动的高可用与可观测性需求。

附录：接口清单与示例

小程序API

• 领取优惠券

  • 路径：/route=coupon（POST）
  • 参数：id（券ID）、ip（可选，用于风控）
  • 返回：成功时包含coupon_list（用户券列表）
  • 说明：内部调用前台服务完成领取与并发控制
  • 参考实现：领取流程:49-73

• 我的优惠券列表

  • 路径：/route=coupon/user（GET）
  • 参数：page（默认1）
  • 返回：title、coupon_list、pager、total
  • 说明：分页展示当前用户券列表
  • 参考实现：列表流程:43-63

后台管理API

• 优惠券列表

  • 路径：/admin/route=coupon（GET）
  • 参数：page
  • 返回：列表与分页
  • 参考实现：列表:54-73

• 新增优惠券

  • 路径：/admin/route=admin.coupon.create（POST）
  • 参数：表单字段（名称、简介、类型、面额、门槛、起止时间等）
  • 返回：成功后跳转到编辑页
  • 参考实现：新增:91-104

• 编辑优惠券

  • 路径：/admin/route=admin.coupon.edit（GET/PUT）
  • 参数：id、表单字段
  • 返回：成功后停留在编辑页
  • 参考实现：编辑/更新:106-142

• 删除优惠券

  • 路径：/admin/route=coupon（DELETE）
  • 参数：id
  • 返回：删除结果
  • 参考实现：删除:144-158

• 批量动作

  • 路径：/admin/route=coupon/action（POST）
  • 参数：批量操作数据
  • 返回：重定向并提示
  • 参考实现：批量动作:160-171

• 领取记录列表

  • 路径：/admin/route=coupon.log（GET）
  • 参数：coupon_id、time_start、time_end、page、key
  • 返回：日志列表与分页
  • 参考实现：日志列表:55-87

• 批量删除记录

  • 路径：/admin/route=coupon.log/action（POST）
  • 参数：批量操作数据
  • 返回：重定向并提示
  • 参考实现：批量删除:104-113

优惠券类型与规则

• 类型
  • 满减券：满足门槛减免固定金额
  • 折扣券：按比例打折
  • 现金券：无门槛或低门槛直接抵扣
• 规则配置要点
  • 生效时间：start_at、end_at
  • 门槛：condition（最低消费金额）
  • 面额：money或百分比（percent）
  • 状态：status（启用/禁用）
  • 排序：sort（影响列表顺序）
• 参考实现：类型与金额格式化:37-68

使用与核销

• 使用
  • 下单时选择可用券，计算优惠金额
  • 订单关联券（order_coupon），记录抵扣金额
• 核销
  • 订单完成后标记券为已使用
  • 记录核销时间与订单号，便于审计
• 参考实现：订单中券汇总:264-288

统计与分析

• 指标建议
  • 领取量、使用率、核销率、ROI（活动投入产出比）
  • 分券维度：领取/使用/核销趋势
  • 分渠道：不同推广渠道的效果对比
• 数据来源
  • 领取日志（coupon_log）
  • 订单关联（order_coupon）
  • 券模板（coupon）
• 实施建议
  • 建立定时任务汇总指标
  • 提供后台报表与导出功能

自动化发放策略

• 触发方式
  • 新用户注册赠送
  • 指定活动页面分享领取
  • 购物车满额自动发放
• 策略配置
  • 目标人群：标签/等级/地域
  • 发放频率：每日/每周上限
  • 风控：同一设备/IP限制
• 实施建议
  • 使用消息队列异步发放
  • 幂等键避免重复发放
  • 灰度发布与A/B测试