mirror of
https://codeup.aliyun.com/67c68d4e484ca2f0a13ac3c1/ydc/jsowell-charger-web.git
synced 2026-06-14 12:20:04 +08:00
87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# 优惠券兑换 API 文档
|
||
|
||
本文档提供了**用户端兑换优惠券接口**的详细说明。当前接口主要用于 App 或小程序中，用户消耗对应的积分来兑换相应的优惠券（如洗车券、折扣券等）。
|
||
|
||
---
|
||
|
||
## 接口说明
|
||
|
||
**接口路径**: `/coupon/exchange`
|
||
**请求方法**: `POST`
|
||
**功能描述**: 用户通过指定的积分兑换某一种优惠券。系统将自动扣除该用户的积分并向其发放对应的一张优惠券。该接口具有防重放设计，依赖 `requestId` 保证请求幂等性。
|
||
|
||
### 接口鉴权
|
||
建议配合 JWT 认证/统一网关身份校验后使用。（接口本身会读取入参 `memberId`，在实际部署时可能需要由网关/会话态中解析并传递此参数，防止越权）。
|
||
|
||
---
|
||
|
||
## 请求参数
|
||
|
||
| 参数名称 | 参数位置 | 参数类型 | 是否必填 | 示例值 | 描述说明 |
|
||
|----------|----------|----------|----------|--------|----------|
|
||
| `memberId` | Query/Form | `String` | 是 | `u_1001` | 会员用户的全局唯一标识 |
|
||
| `templateId` | Query/Form | `Long` | 是 | `102` | 需要兑换的优惠券所属的券模板 ID |
|
||
| `requestId` | Query/Form | `String` | 是 | `9b1deb4d-3b7d-...` | 客户端生成的防重放幂等键 (UUID)，防止网络原因导致的重复提交和重复扣积分 |
|
||
|
||
**注意事项**：
|
||
- `requestId` 务必保证在至少一次完整的业务生命周期内保持唯一，建议客户端每次通过点击或提交生成唯一的 UUID 字符串。
|
||
- `templateId` 必须处于“上架”状态，并处于允许兑换的时间范围内。
|
||
|
||
---
|
||
|
||
## 响应数据
|
||
|
||
返回标准的 `AjaxResult` (或标准格式的 JSON 对象)，其中包含接口处理的状态码、提示信息以及新发放的优惠券明细。
|
||
|
||
### 成功响应示例
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"id": 50012,
|
||
"couponNo": "CP20260311ABCDE",
|
||
"exchangeRequestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
||
"templateId": 102,
|
||
"memberId": "u_1001",
|
||
"couponType": 1,
|
||
"pointsCost": 500.00,
|
||
"discountRate": null,
|
||
"status": 0,
|
||
"source": 1,
|
||
"exchangeTime": "2026-03-11 10:30:15",
|
||
"expireTime": "2026-04-10 10:30:15",
|
||
"useTime": null,
|
||
"useStoreId": null,
|
||
"useOperator": null
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败响应示例
|
||
|
||
| 场景 | Code | Msg 示例 |
|
||
|------|------|----------|
|
||
| 积分不足 | 500 | `用户积分不足，仅剩余 100 积分` |
|
||
| 券库存不足 | 500 | `该券已兑完` |
|
||
| 兑换次数达上限 | 500 | `此券单日仅支持兑换 1 次` / `累计兑换次数已达上限` |
|
||
| 模板不存在或已下架 | 500 | `此券无法兑换` |
|
||
| 不在指定范围内 | 500 | `您当前所在站点不支持兑换该券` |
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "用户积分不足，仅剩余 100 积分"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 业务逻辑说明
|
||
|
||
本接口在服务端实现了以下前置校验与扣除逻辑：
|
||
1. **幂等性判定**：如果之前已有相同的 `requestId` 被成功处理过，将直接返回上次处理并落库的该张优惠券数据，不对积分和库存进行额外消耗。
|
||
2. **时效与库存判定**：若该券已下架、不在兑换时间范围内，或余量已被耗穿，则终止请求并抛出异常。
|
||
3. **频次限制判定**：验证该用户对本模板的单日 (`dailyLimit`)、单月 (`monthlyLimit`) 及总兑换 (`totalLimit`) 限流次数表现。
|
||
4. **事务与原子操作**：在单次事务中执行“扣减用户积分”与“扣减优惠券剩余库存/新增用户持券记录”的原子操作，确保资产的一致性。
|