myblog

Appearance

商城优惠券控制器文档 ​

接口信息 ​

  • 控制器类: CouponController
  • 包路径: com.qisheng.mall.web
  • 功能描述: 负责处理商户优惠券模板的增删改查操作

类图 ​

uml diagram

接口列表 ​

1. 添加优惠券 ​

  • 请求方式: POST
  • URL: /{merchantId}/coupon
  • 功能: 创建新的优惠券模板
  • 参数:
    • merchantId: 商户ID (路径参数)
    • request: 优惠券请求对象 (请求体)
  • 返回: BaseResponse
  • 示例:
http
POST /82/coupon
{
  "name": "满100减10元",
  "type": "MONEY",
  "amount": 1000,
  "validType": "FIXED",
  "invalidStartTime": "2023-01-01T00:00:00",
  "invalidEndTime": "2023-12-31T23:59:59",
  "isEnableMall": "Y",
  "isEnableOrderAmount": "Y",
  "orderAmount": 10000
}

2. 获取优惠券列表 ​

  • 请求方式: GET
  • URL: /{merchantId}/coupon 或 /{merchantId}/mp_coupon
  • 功能: 获取商户的优惠券模板列表
  • 参数:
    • merchantId: 商户ID (路径参数)
    • request: 优惠券查询请求对象 (查询参数)
    • limitPageSize: 限制页面大小，为0时返回所有优惠券
  • 返回: ObjectResponse
  • 示例:
http
GET /82/coupon?limitPageSize=0

3. 编辑优惠券 ​

  • 请求方式: PATCH
  • URL: /{merchantId}/coupon/{id}
  • 功能: 编辑或删除单个优惠券
  • 参数:
    • merchantId: 商户ID (路径参数)
    • id: 优惠券ID (路径参数)
    • request: 包含操作类型和更新数据的JSON对象 (请求体)
  • 返回: BaseResponse
  • 示例:
http
PATCH /82/coupon/123
{
  "optType": "edit",
  "name": "满200减20元",
  "orderAmount": 20000
}

4. 批量删除优惠券 ​

  • 请求方式: PATCH
  • URL: /{merchantId}/coupon
  • 功能: 批量删除优惠券
  • 参数:
    • merchantId: 商户ID (路径参数)
    • request: 包含要删除的优惠券ID列表的请求对象 (请求体)
  • 返回: BaseResponse
  • 示例:
http
PATCH /82/coupon
{
  "ids": [123, 456, 789]
}

5. 获取优惠券详情 ​

  • 请求方式: GET
  • URL: /{merchantId}/couponById
  • 功能: 获取指定ID的优惠券详情
  • 参数:
    • merchantId: 商户ID (路径参数)
    • id: 优惠券ID列表 (查询参数)
  • 返回: ObjectResponse<List<CouponVo>>
  • 示例:
http
GET /82/couponById?id=123&id=456

调用流程 ​

1. 获取优惠券列表流程 ​

uml diagram

2. 添加优惠券流程 ​

uml diagram

主要功能说明 ​

优惠券类型 ​

  • MONEY: 定额优惠券
  • RANDOM: 随机优惠券
  • DISCOUNT: 折扣优惠券
  • CASH: 代金券

有效期类型 ​

  • FIXED: 固定有效期
  • RELATIVE: 相对有效期

优惠券状态 ​

  • NORMAL: 正常
  • DELETED: 已删除

使用场景 ​

  • 商城购物抵扣: 是否启用商城购物抵扣
  • 订单满减: 是否启用商城订单满减
  • 店内消费抵扣: 是否启用店内消费抵扣
  • 消费金额满减: 是否启用消费金额满减

注意事项 ​

1. 数据表说明 ​

  • META_COUPON: 优惠券模板表，存储优惠券的基本信息和规则
  • T_CUSTOMER_COUPON: 顾客优惠券表，存储顾客实际拥有的优惠券实例

2. 权限控制 ​

  • dataRole=MERCHANT: 商户角色，只能查看自己商户的优惠券
  • JWT验证: 通过JWT获取当前用户信息和门店权限

3. 业务逻辑 ​

  • limitPageSize=0: 返回所有优惠券，不进行分页
  • limitPageSize>0: 返回分页优惠券，包含统计信息
  • 状态过滤: 只查询STATUS='NORMAL'的优惠券

4. 统计信息 ​

  • receiveNum: 领取数量
  • useNum: 使用数量
  • unUseNum: 未使用数量
  • validNum: 有效数量

5. 优惠券规则 ​

  • 商城购物抵扣: 是否可用于商城购物
  • 订单满减: 是否启用订单满减功能
  • 店内消费抵扣: 是否可用于店内消费
  • 消费金额满减: 是否启用消费金额满减
  • 指定商品: 是否限制特定商品使用
  • 指定项目: 是否限制特定项目使用
  • 指定卖品: 是否限制特定卖品使用
  • 指定套餐: 是否限制特定套餐使用