# 优惠券模块 — 移动端接口文档

> **模块**：business-coupon（入口在 business-mobile-gateway）  
> **前缀**：`${jeesharp.web.mobilePath}`（默认 `/mobile`）  
> **更新日期**：2026-06-05

---

## 一、接口规范

### 1.1 请求头（登录接口）

```
Content-Type: application/json;charset=UTF-8
access_token: {token}
X-Platform: MINI | APP | H5
X-Device-Id: {deviceId}
```

### 1.2 响应格式

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": { },
  "requestId": "uuid-xxx"
}
```

---

## 二、会员优惠券（核心）`member/coupon`

**Controller**：`CouponMobileController`  
**基础路径**：`/mobile/member/coupon`

### 2.1 可领取优惠券列表

- **URL**：`POST /available`
- **认证**：需要登录

```json
{
  "pageNo": 1,
  "pageSize": 10,
  "couponName": "",
  "couponType": 1
}
```

**响应 data**：

| 字段 | 说明 |
|------|------|
| list | 可领模板列表 |
| totalCount | 总数 |
| pageNo / pageSize | 分页 |

**list 项**：`templateId`、`couponName`、`couponType`、`discountValue`、`validStartDate`、`validEndDate`、`remainCount`、`isReceived` 等。

### 2.2 领取优惠券

- **URL**：`POST /receive`

```json
{ "templateId": "模板ID" }
```

### 2.3 我的优惠券

- **URL**：`POST /my` 或 `POST /myList`

```json
{
  "pageNo": 1,
  "pageSize": 10,
  "status": 0
}
```

`status`：0未用 1已用 2过期 3冻结 4作废。

### 2.4 优惠券详情

- **URL**：`GET /detail?couponId={会员券ID}`

### 2.5 卡面详情（与领券中心 UI 一致）

- **URL**：`GET /walletDetail?memberCouponId={id}`

### 2.6 订单可用优惠券（试算列表）⭐

- **URL**：`POST /usable`
- **说明**：结算页展示可用/不可用券及预估抵扣

**当前请求体**：

```json
{
  "orderAmount": 299.00
}
```

**当前响应 data**：

```json
{
  "usableCoupons": [
    {
      "memberCouponId": "…",
      "couponName": "…",
      "minConsumeAmount": 100,
      "estimatedDiscount": 20.00
    }
  ],
  "unusableCoupons": [
    {
      "memberCouponId": "…",
      "couponName": "…",
      "reason": "未满最低消费100元"
    }
  ]
}
```

**规划扩展**（见 [doc/优惠券架构设计.md](./doc/优惠券架构设计.md)）：

```json
{
  "sceneCode": "MALL",
  "platform": "MINI",
  "orderAmount": 299.00,
  "scopeItemIds": ["spuId1", "spuId2"]
}
```

### 2.7 积分兑换

- **URL**：`POST /exchange`

```json
{ "templateId": "模板ID" }
```

---

## 三、优惠券模板（规范路径）`coupon/couponTemplate`

**Controller**：`CouponTemplateMobileController`  
**基础路径**：`/mobile/coupon/couponTemplate`

| 方法 | URL | 说明 |
|------|-----|------|
| POST | `/list` | 进行中模板分页 |
| GET | `/info?id=` | 模板详情 |

---

## 四、领券中心（免登录浏览）`coupon`

**Controller**：`CouponCatalogMobileController`  
**路径**：`/mobile/coupon`（白名单，前端须 `skipAuth: true`）

| 方法 | URL | 说明 |
|------|-----|------|
| GET | `/templates` | 可浏览模板列表 |
| GET | `/template/{id}` | 模板详情 |

---

## 五、业务线结账对接说明

移动端 **不直接调用** 冻结/核销接口；由业务订单接口在服务端编排：

| 阶段 | 负责方 | 券模块方法（服务端） |
|------|--------|----------------------|
| 结算页拉券 | 各业务结算 API 或统一转发 | `usableForOrder` → 目标 `listForCheckout` |
| 下单试算 | 商城/酒店下单 API | `resolveMallCouponDiscount` → 目标 `resolveDiscount` |
| 下单冻结 | 创建订单事务内 | `freezeForMallOrder` → 目标 `freezeForOrder` |
| 支付成功 | 支付回调 | `confirmMallOrderCouponPaid` → 目标 `confirmOrderPaid` |

C 端只需：结算页调 **可用券列表** + 提交订单时传 `memberCouponId`（字段名以各业务订单 DTO 为准）。

---

## 六、状态码

| code | 说明 |
|------|------|
| 200 | 成功 |
| 201 | 需要登录 |
| 203 | 参数错误 |
| 202 | 服务器错误 |

券业务常见错误：`优惠券不存在`、`未满最低消费`、`优惠券不可用`、`优惠券抵扣金额已变化，请重新选择`。

---

## 七、已知限制（与架构文档对齐）

1. `/usable` 未按 `sceneCode`、商品 ID 过滤，多场景上线前须升级接口。
2. `/my`、`/detail` 部分字段（如 `useScope`）仍为占位，待返回真实场景与范围文案。
3. 仅 **商城订单** 服务端完整走冻结/核销；酒店/美食结算须按架构文档接入。

---

## 八、更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-05-07 | 领券、我的券、usable 试算 |
| 1.1 | 2026-06-05 | 补充架构对接说明与接口演进规划 |