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

模块：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 响应格式

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

1.3 分页响应

{
  "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
```
{ "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

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

3.4 作废

URL：POST /cancel

权限：coupon:memberCoupon:cancel

{
"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`

后台接口文档.md 5.9 KB История Исходник