myblog

Appearance

顾客优惠券控制器文档 ​

接口信息 ​

  • 控制器类: CustomerCouponController
  • 包路径: com.qisheng.customer.web
  • 功能描述: 负责处理顾客优惠券的增删改查操作

类图 ​

uml diagram

接口列表 ​

1. 获取顾客优惠券 ​

  • 请求方式: GET
  • URL: /{merchantId}/customer_coupon 或 /{merchantId}/mp_customer_coupon
  • 功能: 根据操作类型获取不同的顾客优惠券数据
  • 参数:
    • merchantId: 商户ID (路径参数)
    • request: 顾客优惠券查询请求对象 (查询参数)
  • 返回: ObjectResponse
  • 备注: 已标记为过时 (Deprecated)，建议使用 POST 方式的 /customer_coupon/list 接口

2. 获取顾客优惠券信息 ​

  • 请求方式: POST
  • URL: /{merchantId}/customer_coupon/list 或 /{merchantId}/mp_customer_coupon/list
  • 功能: 根据操作类型获取不同的顾客优惠券数据
  • 参数:
    • merchantId: 商户ID (路径参数)
    • request: 顾客优惠券查询请求对象 (请求体)
  • 返回: ObjectResponse
  • 支持的操作类型:
    • activity_num: 活动数量汇总查询
    • coupon_activity_promotion_num: 活动推广数量查询
    • coupon_num: 优惠券数量查询
    • appCustomerRecord: APP顾客优惠券记录
    • customerRecord: 顾客优惠券记录
    • customerExchangeRecord: 顾客兑换券记录
    • couponCount: 优惠券正常状态数量
    • detailReport: 优惠券明细报表
    • couponReport: 优惠券统计报表
    • coupon_by_Code: 扫码查询兑换券信息

3. 获取即将过期的优惠券 ​

  • 请求方式: GET
  • URL: /{merchantId}/customer_expiring_coupon
  • 功能: 获取3天内即将过期的优惠券
  • 参数:
    • merchantId: 商户ID (路径参数)
  • 返回: ObjectResponse<CustomerCoupon>

4. 根据ID获取优惠券 ​

  • 请求方式: GET
  • URL: /{merchantId}/customer_coupon/{id}
  • 功能: 获取指定ID的顾客优惠券详情
  • 参数:
    • merchantId: 商户ID (路径参数)
    • id: 顾客优惠券ID (路径参数)
  • 返回: ObjectResponse

5. 导出优惠券数据 ​

  • 请求方式: POST
  • URL: /{merchantId}/customer_coupon/export
  • 功能: 导出优惠券数据到Excel文件
  • 参数:
    • response: HttpServletResponse对象
    • merchantId: 商户ID (路径参数)
    • request: 顾客优惠券查询请求对象 (请求体)
  • 返回: void (直接下载文件)

6. 添加顾客优惠券 ​

  • 请求方式: POST
  • URL: /{merchantId}/customer_coupon
  • 功能: 添加顾客优惠券
  • 参数:
    • merchantId: 商户ID (路径参数)
    • request: 添加顾客优惠券请求对象 (请求体)
  • 返回: ObjectResponse
  • 支持的操作类型:
    • SEND: 发送优惠券
    • CARD_BONUS: 美管加开卡赠送
    • MANY_SEND: 美管加群发赠送
    • CUSTOMER_BONUS: 顾客转赠
    • INVITE_ACTIVITY: 邀请活动送券

7. 更新顾客优惠券 ​

  • 请求方式: PUT 或 PATCH
  • URL: /{merchantId}/customer_coupon
  • 功能: 更新顾客优惠券状态
  • 参数:
    • merchantId: 商户ID (路径参数)
    • request: 更新顾客优惠券请求对象 (请求体)
  • 返回: BaseResponse
  • 支持的操作类型:
    • activity_cancel: 活动撤回
    • send_cancel: 私发撤回
    • manual_use: 手动核销
    • mall_cancel: 商城撤回
    • write_off_certificate: 兑换券验券

8. 商城使用优惠券 ​

  • 请求方式: POST
  • URL: /{merchantId}/customer_coupon/mallUse
  • 功能: 商城使用优惠券
  • 参数:
    • merchantId: 商户ID (路径参数)
    • msg: 顾客优惠券消息 (请求体)
  • 返回: ObjectResponse

调用流程 ​

1. 获取顾客优惠券信息流程 ​

uml diagram

2. 添加顾客优惠券流程 ​

uml diagram

3. 更新顾客优惠券流程 ​

uml diagram

主要功能说明 ​

查询功能 (Query Operations) ​

  • ACTIVITY_NUM: 活动数量汇总查询
  • COUPON_ACTIVITY_PROMOTION_NUM: 活动推广数量查询
  • COUPON_NUM: 优惠券数量查询
  • APP_CUSTOMER_RECORD: APP顾客优惠券记录
  • CUSTOMER_RECORD: 顾客优惠券记录
  • CUSTOMER_EXCHANGE_RECORD: 顾客兑换券记录
  • COUPON_COUNT: 优惠券正常状态数量
  • DETAIL_REPORT: 优惠券明细报表
  • COUPON_REPORT: 优惠券统计报表
  • COUPON_BY_CODE: 扫码查询兑换券信息

添加功能 (Add Operations) ​

  • SEND: 发送优惠券
  • CARD_BONUS: 美管加开卡赠送
  • MANY_SEND: 美管加群发赠送
  • CUSTOMER_BONUS: 顾客转赠
  • INVITE_ACTIVITY: 邀请活动送券

更新功能 (Update Operations) ​

  • ACTIVITY_CANCEL: 活动撤回
  • SEND_CANCEL: 私发撤回
  • MANUAL_USE: 手动核销
  • MALL_CANCEL: 商城撤回
  • WRITE_OFF_CERTIFICATE: 兑换券验券

优惠券状态 ​

  • UN_USE: 未使用
  • USED: 已使用
  • DELETED: 已删除
  • SEND_ED: 已赠送
  • EXPIRED: 已过期

优惠券类型 ​

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

注意事项 ​

1. 接口变更 ​

  • GET /{merchantId}/customer_coupon 接口已标记为过时 (Deprecated)，建议使用 POST /{merchantId}/customer_coupon/list 接口

2. 导出功能 ​

  • 导出功能需要设置正确的表头和文件名
  • 对于报表类型的导出，会自动设置 neStatus=SEND_ED 以排除已赠送的优惠券

3. 操作类型 ​

  • 所有接口都基于 optType 参数来确定具体的处理逻辑
  • 请确保传递正确的操作类型，否则可能导致请求无法正确处理

4. 商城使用优惠券 ​

  • mallUse 接口专门用于商城场景下的优惠券使用
  • 该接口通过 CustomerCouponUtil 工具类处理优惠券使用逻辑