# 优惠券模块 — 后台管理接口文档

> **模块**：business-coupon  
> **前缀**：`${jeesharp.web.adminPath}`（默认 `/api`）  
> **完整路径示例**：`/api/coupon/couponTemplate/v1/list`  
> **更新日期**：2026-06-05

---

## 一、接口规范

### 1.1 请求头

```
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {token}
```

### 1.2 响应格式

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

### 1.3 分页响应

```json
{
  "records": [],
  "total": 100,
  "pageNo": 1,
  "pageSize": 10
}
```

---

## 二、优惠券模板 `couponTemplate`

**基础路径**：`/coupon/couponTemplate/v1`

### 2.1 分页列表

- **URL**：`POST /list`
- **权限**：`coupon:couponTemplate:list`

**请求体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| pageNo | Long | 页码 |
| pageSize | Long | 每页条数 |
| couponCode | String | 券编码 |
| couponName | String | 券名称 |
| couponType | Integer | 类型 |
| getType | Integer | 领取方式 |
| status | Integer | 状态 |

**列表字段要点**：`sceneCode`、`sceneName`（场景名称由服务端补全）、`useScope`、`statusName` 等。

### 2.2 详情

- **URL**：`GET /info?id={id}`
- **权限**：`coupon:couponTemplate:info` 或 `list`

### 2.3 保存（新增/编辑）

- **URL**：`POST /save`
- **权限**：`coupon:couponTemplate:save`

**请求体要点**：

| 字段 | 必填 | 说明 |
|------|------|------|
| id | 编辑必填 | 新增为空 |
| couponCode | ✅ | 券编码 |
| couponName | ✅ | 券名称 |
| couponType | ✅ | 1满减 2折扣 3无门槛 4兑换 |
| discountType | ✅ | 1金额 2折扣 |
| discountValue | ✅ | 面额或折扣值 |
| minConsumeAmount | | 门槛 |
| maxDiscountAmount | | 折扣封顶 |
| **sceneCode** | ✅ | 使用场景编号，须在 `biz_coupon_scene` 启用 |
| useScope | ✅ | 1全场 2指定项 3分类 4品牌 |
| scopeIds | | JSON 数组字符串，适用 ID |
| excludeScopeIds | | JSON 数组，排除 ID |
| totalCount | | -1 不限 |
| perMemberLimit | | 每人限领 |
| getType | ✅ | 领取方式 |
| validityType | ✅ | 1固定 2领后N天 |
| status | ✅ | 0下架 1进行中 2结束 3待开始 |

### 2.4 删除

- **URL**：`GET /delete?ids={id1,id2}`
- **权限**：`coupon:couponTemplate:delete`

### 2.5 更新状态

- **URL**：`POST /updateStatus`
- **权限**：`coupon:couponTemplate:updateStatus`

```json
{ "id": "模板ID", "status": 1 }
```

---

## 三、会员优惠券 `memberCoupon`

**基础路径**：`/coupon/memberCoupon/v1`

列表/详情含 **会员编号、会员姓名、会员手机**（`MemberService.enrichMemberDisplay` 补全，非表字段）。

### 3.1 分页列表

- **URL**：`POST /list`
- **权限**：`coupon:memberCoupon:list`

**查询**：`memberKeyword`（编号/昵称/姓名/手机）、`couponSn`、`status`、`templateId` 等。

**列表字段**：`memberNo`、`memberNickname`、`memberMobile`、`couponSn`、`couponName`、`statusName`、`useAmount`、`useOrderNo` 等。

### 3.2 详情

- **URL**：`GET /info?id={id}`
- **权限**：`coupon:memberCoupon:info` 或 `list`

### 3.3 管理端发放

- **URL**：`POST /grant`
- **权限**：`coupon:memberCoupon:grant`

```json
{
  "memberId": "会员ID",
  "templateId": "模板ID",
  "remarks": "发放说明"
}
```

### 3.4 作废

- **URL**：`POST /cancel`
- **权限**：`coupon:memberCoupon:cancel`

```json
{
  "id": "会员券ID",
  "remarks": "作废原因"
}
```

---

## 四、使用场景 `couponScene`

**基础路径**：`/coupon/couponScene/v1`

### 4.1 分页列表

- **URL**：`POST /list`
- **权限**：`coupon:couponScene:list`

### 4.2 详情

- **URL**：`GET /info?id={id}`
- **权限**：`coupon:couponScene:info`

### 4.3 新增

- **URL**：`POST /create`
- **权限**：`coupon:couponScene:create`

### 4.4 更新

- **URL**：`POST /update`
- **权限**：`coupon:couponScene:update`

**请求体**：

| 字段 | 必填 | 说明 |
|------|------|------|
| sceneName | ✅ | 场景名称 |
| sceneCode | ✅ | 场景编号（大写，唯一） |
| requestUrl | ✅ | 管理端 POST 分页路径，供模板选品 |
| keywordField | | 搜索参数字段，默认 keyword |
| nameField | | 展示名称字段，默认 name |
| supportCategoryBrand | | 0否 1是（商城类开启分类/品牌范围） |
| sort | | 排序 |
| status | ✅ | 0禁用 1启用 |

### 4.5 删除

- **URL**：`GET /delete?ids={ids}`
- **权限**：`coupon:couponScene:delete`

### 4.6 启用场景下拉（模板表单用）

- **URL**：`GET /enabledOptions`
- **权限**：`coupon:couponTemplate:list` 或 `save`

返回：`sceneCode`、`sceneName`、`requestUrl`、`keywordField`、`nameField`、`supportCategoryBrand`、`scopeItemLabel`（来自 `cfg_biz_scene.ext_json`，如商品/房型/套餐）。

---

## 五、权限标识汇总

| 资源 | 权限 |
|------|------|
| 模板 | `coupon:couponTemplate:list`、`info`、`save`、`delete`、`updateStatus` |
| 会员券 | `coupon:memberCoupon:list`、`info`、`grant`、`cancel` |
| 使用场景 | `coupon:couponScene:list`、`info`、`create`、`update`、`delete` |

---

## 六、枚举速查

### 优惠券类型 `couponType`

| 值 | 说明 |
|----|------|
| 1 | 满减券 |
| 2 | 折扣券 |
| 3 | 无门槛券 |
| 4 | 兑换券 |

### 使用范围 `useScope`

| 值 | 说明 |
|----|------|
| 1 | 全场通用 |
| 2 | 指定商品/房型/套餐等 |
| 3 | 指定分类（需场景支持） |
| 4 | 指定品牌（需场景支持） |

### 会员券状态 `status`

| 值 | 说明 |
|----|------|
| 0 | 未使用 |
| 1 | 已使用 |
| 2 | 过期 |
| 3 | 冻结 |
| 4 | 作废 |

### 默认场景编号 `scene_code`

| 编号 | 名称 |
|------|------|
| MALL | 商城 |
| HOTEL | 酒店 |
| FOOD | 美食 |

---

## 七、更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-05-07 | 模板、会员券 |
| 1.1 | 2026-06-05 | 使用场景 CRUD；模板 `sceneCode` |