Web端商户优惠券核销接口文档

模块概述

本模块提供优惠券的核销功能,包括核销前效验和核销订单两个接口,支持代金券和团购券的核销处理。

接口列表

核销订单前效验 - 验证券是否可用
核销订单 - 实际执行核销操作

接口一:核销订单前效验

接口信息

接口名称:核销订单前效验
接口路径:GET /couponManage/verifyOrder
请求方式:GET
接口描述:在核销订单前进行效验,验证券是否满足核销条件(有效期、不可用日期、使用时间段等)

请求参数

参数名	类型	必填	说明
orderCode	String	是	劵code(券码)

请求示例

GET /couponManage/verifyOrder?orderCode=ABC123456789

响应参数

成功响应(效验通过)

{
    "code": 200,
    "success": true,
    "data": "效验通过",
    "msg": "效验通过"
}

失败响应示例

{
    "code": 500,
    "success": false,
    "data": null,
    "msg": "该劵不在有效期内"
}

业务规则

详见核销前效验规则章节。

接口二:核销订单

接口信息

接口名称:核销订单
接口路径:GET /couponManage/verifyCoupon
请求方式:GET
接口描述:执行券的核销操作,更新券状态、计算收入、更新店铺余额

请求参数

参数名	类型	必填	说明
storeId	String	是	门店ID
quanCode	String	是	券码

请求示例

GET /couponManage/verifyCoupon?storeId=102&quanCode=ABC123456789

响应参数

成功响应(核销成功)

{
    "code": 200,
    "success": true,
    "data": {
        "code": "true",
        "message": "核销成功"
    }
}

失败响应示例

1. 重复核销

{
    "code": 200,
    "success": true,
    "data": {
        "code": "false",
        "message": "请勿重复核销"
    }
}

2. 券不存在或状态不正确

{
    "code": 200,
    "success": true,
    "data": {
        "code": "false",
        "message": "核销失败"
    }
}

3. 订单不存在

{
    "code": 200,
    "success": true,
    "data": {
        "code": "false",
        "message": "订单不存在"
    }
}

4. 门店不存在

{
    "code": 200,
    "success": true,
    "data": {
        "code": "false",
        "message": "门店不存在"
    }
}

核销业务流程

完整核销流程图

┌─────────────────────────────────────────────┐
│  客户端调用核销接口                           │
│  /couponManage/verifyCoupon                  │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  1. Redis分布式锁                             │
│  检查 coupon:use:{quanCode} 是否存在          │
│  存在 → 返回"请勿重复核销"                    │
│  不存在 → 设置锁并继续                        │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  2. 查询订单券中间表                          │
│  - 根据券码查询                               │
│  - 状态必须为:待使用(1) 或 退款失败(8)       │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  3. 更新订单券状态                            │
│  - status → 已使用(2)                        │
│  - usedTime → 当前时间                       │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  4. 查询用户订单信息                          │
│  - 根据 orderId 查询                         │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  5. 检查平台优惠券                            │
│  - 查询 quanId                               │
│  - 如果 type=3,标记为平台券                  │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  6-7. 查询订单下所有券                        │
│  - 检查是否全部已核销                        │
│  - 筛选未完成的券                            │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  8. 订单完成判断                              │
│  如果所有券都已核销 或 无未完成券             │
│  → 更新订单状态为已完成(3)                   │
│  → 设置完成时间                              │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  9. 查询门店信息                              │
│  - 获取抽成比例 commissionRate               │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  10. 计算抽成和收入                           │
│  抽成 = 券价 × 100 × 抽成比例                │
│  收入 = 券价 × 100 - 抽成                    │
│  (如有平台券,需加上平均优惠价格)             │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  11. 插入收入明细记录                         │
│  - storeId, userOrderId                      │
│  - incomeType, businessId                    │
│  - commission, money                         │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  12. 更新店铺账户余额                         │
│  - store_user.money += 收入金额              │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  13. 返回核销成功                             │
│  { code: "true", message: "核销成功" }       │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  14. 释放分布式锁 (finally)                   │
│  删除 coupon:use:{quanCode}                  │
└─────────────────────────────────────────────┘

核销前效验规则

效验内容

核销前效验(verifyOrder)会根据券类型进行不同的验证:

代金券验证(couponType=1)

有效期验证
- 指定天数:支付时间 + 天数 > 当前时间
- 指定时间段:开始时间 ≤ 当前时间 ≤ 结束时间
不可用日期验证
- 限制星期:检查当前是否为不可用星期
- 限制节日:检查当前是否在节日范围
- 自定义日期:检查当前是否在自定义不可用日期
使用时间段验证
- 检查当前小时是否在允许使用的时间段内
- 支持跨天时间段(如22点-3点)
单次核销数量验证
- 检查今日已核销次数是否达到上限

团购券验证(couponType=2)

有效期验证
- 指定天数:支付时间 + 天数 > 当前时间
- 指定时间段:开始日期 ≤ 当前日期 ≤ 结束日期
不可用日期验证
- 限制星期:检查当前是否为不可用星期
- 限制节日:检查当前是否在节日范围
- 自定义日期:检查当前是否在自定义不可用日期

金额计算规则

基础计算公式

1. 抽成金额计算

抽成比例(小数) = storeInfo.commissionRate ÷ 100
抽成金额(分) = 券价(元) × 100 × 抽成比例

示例:

券价 = 100元
抽成比例 = 4%
抽成金额 = 100 × 100 × 0.04 = 400分(4元)

2. 实际收入计算

普通订单(无平台优惠券)

实际收入(分) = 券价(元) × 100 - 抽成金额(分)

示例:

券价 = 100元
抽成 = 400分
实际收入 = 100 × 100 - 400 = 9600分(96元)

使用平台优惠券的订单

实际收入(分) = (券价(元) + 平均优惠券价格(元)) × 100 - 抽成金额(分)

示例:

券价 = 100元
平台优惠 = 10元
抽成 = 400分
实际收入 = (100 + 10) × 100 - 400 = 10600分(106元)

金额单位说明

存储单位	显示单位	转换关系
分(数据库)	元(前端)	1元 = 100分

注意:

所有金额计算使用 BigDecimal,精度为2位小数
金额存储到数据库时转换为整数(分)
显示给用户时转换为元(除以100)

并发控制

Redis分布式锁机制

锁的生命周期

┌─────────────────────────────────────────────┐
│  1. 检查锁                                    │
│  getString("coupon:use:{quanCode}")          │
│  如果返回值不为空 → 锁已存在 → 拒绝核销      │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  2. 设置锁                                    │
│  setListRight("coupon:use:{quanCode}",       │
│               quanCode)                      │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  3. 执行核销业务逻辑                          │
│  (数据库操作、金额计算等)                   │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│  4. 释放锁 (finally块)                       │
│  delete("coupon:use:{quanCode}")             │
│  确保无论成功失败都会释放                    │
└─────────────────────────────────────────────┘

锁的作用

防止重复核销:同一券码在处理过程中不允许再次核销
并发安全:多个核销请求同时到达时,只有一个能获取锁
自动释放:finally块确保锁一定会被释放

数据库操作

涉及的表

1. order_coupon_middle(订单券中间表)

查询操作:

SELECT * FROM order_coupon_middle
WHERE coupon_code = ?
  AND status IN (1, 8)  -- 待使用或退款失败

更新操作:

UPDATE order_coupon_middle
SET status = 2,           -- 已使用
    used_time = NOW()
WHERE id = ?

2. life_user_order(用户订单表)

查询操作:

SELECT * FROM life_user_order
WHERE id = ?

更新操作(订单完成时):

UPDATE life_user_order
SET status = 3,              -- 已完成
    finish_time = NOW(),
    created_time = NOW()
WHERE id = ?

3. life_discount_coupon(优惠券表)

查询操作(检查平台券):

SELECT * FROM life_discount_coupon
WHERE id = ?
  AND type = 3  -- 平台券

4. store_info(门店信息表)

查询操作:

SELECT * FROM store_info
WHERE id = ?

5. store_income_details_record(收入明细表)

插入操作:

INSERT INTO store_income_details_record
(store_id, user_order_id, income_type, business_id, commission, money)
VALUES (?, ?, ?, ?, ?, ?)

6. store_user(门店用户表)

更新操作:

UPDATE store_user
SET money = money + ?
WHERE store_id = ?
  AND delete_flag = 0

订单状态说明

order_coupon_middle 状态

Status	枚举常量	说明
1	WAIT_USE	待使用
2	USED	已使用(核销完成)
3	REFUND	已退款
8	REFUND_FAILED	退款失败

life_user_order 状态

Status	枚举常量	说明
1	WAIT_PAY	待支付
2	WAIT_USE	待使用
3	COMPLETE	已完成
4	REFUND	已退款
5	CANCEL	已取消
6	EXPIRE	已过期

收入明细记录

StoreIncomeDetailsRecord 字段说明

字段名	类型	说明	示例
storeId	Integer	门店ID	102
userOrderId	Integer	订单券ID	12345
incomeType	Integer	收入类型(券类型)	1-代金券, 2-团购
businessId	Integer	业务ID(券ID)	67890
commission	Integer	抽成金额(分)	400
money	Integer	实际收入(分)	9600

事务管理

事务范围

核销订单接口使用 @Transactional 注解,确保以下操作的原子性:

更新订单券状态
更新用户订单状态(如需要)
插入收入明细记录
更新店铺账户余额

回滚机制

@Transactional(rollbackFor = Exception.class)
public Map<String, String> verifyCoupon(String storeId, String quanCode) {
    // 任何异常都会触发回滚
}

异常处理

异常场景

场景	返回code	返回message	处理方式
重复核销	"false"	"请勿重复核销"	检测到锁存在
券不存在	"false"	"核销失败"	查询结果为空
订单不存在	"false"	"订单不存在"	订单查询失败
门店不存在	"false"	"门店不存在"	门店查询失败
系统异常	"false"	"核销失败:{异常信息}"	捕获Exception

迁移说明

原接口(app端)

路径:/alienStore/coupon/newVerify
Controller:LifeCouponController
Service:LifeCouponService.newCouponVerify()

新接口(web端)

路径:/couponManage/verifyCoupon
Controller:CouponManageController
Service:CouponManageService.verifyCoupon()

差异说明

项目	app端	web端	说明
好友券发放	✅ 支持	⚠️ 暂不支持	需通过Feign调用实现
其他逻辑	✅	✅	完全一致

更新日志

2025-11-14

新增接口:

✅ GET /couponManage/verifyOrder - 核销订单前效验
✅ GET /couponManage/verifyCoupon - 核销订单

核心功能:

✅ Redis分布式锁防止重复核销
✅ 券状态更新(待使用→已使用)
✅ 订单状态更新(所有券核销完成→订单完成)
✅ 平台优惠券识别和处理
✅ 抽成计算(从门店信息获取比例)
✅ 收入记录插入
✅ 店铺余额更新
✅ 完整的事务管理
✅ 详细的日志记录
✅ 异常处理和回滚机制

涉及文件:

CouponManageController.java - 更新
CouponManageService.java - 更新
CouponManageServiceImpl.java - 更新(新增200行)

文档版本:v1.0
最后更新:2025-11-14
维护人员:ssk

API_COUPON_MANAGEMENT.md 18 KB Patstāvīgā saite Vēsture Neapstrādāts

Web端商户优惠券核销接口文档

模块概述

接口列表

接口一:核销订单前效验

接口信息

请求参数

请求示例

响应参数

成功响应(效验通过)

失败响应示例

业务规则

接口二:核销订单

接口信息

请求参数

请求示例

响应参数

成功响应(核销成功)

失败响应示例

1. 重复核销

2. 券不存在或状态不正确

3. 订单不存在

4. 门店不存在

核销业务流程

完整核销流程图

核销前效验规则

效验内容

代金券验证(couponType=1)

团购券验证(couponType=2)

金额计算规则

基础计算公式

1. 抽成金额计算

2. 实际收入计算

普通订单(无平台优惠券)

使用平台优惠券的订单

金额单位说明

并发控制

Redis分布式锁机制

锁的生命周期

锁的作用

数据库操作

涉及的表

1. order_coupon_middle(订单券中间表)

2. life_user_order(用户订单表)

3. life_discount_coupon(优惠券表)

4. store_info(门店信息表)

5. store_income_details_record(收入明细表)

6. store_user(门店用户表)

订单状态说明

order_coupon_middle 状态

life_user_order 状态

收入明细记录

StoreIncomeDetailsRecord 字段说明

事务管理

事务范围

回滚机制

异常处理

异常场景

迁移说明

原接口(app端)

新接口(web端)

差异说明

更新日志

2025-11-14

API_COUPON_MANAGEMENT.md 18 KB

Patstāvīgā saite Vēsture Neapstrādāts