# 优惠券模块 (business-coupon)

## 模块概述

优惠券模块为在线订餐平台提供 **统一的营销券能力中心**：运营在后台配置券模板与使用场景，C 端会员领券/持券，各业务线（订餐、美食等）在 **下单结账** 时调用本模块完成「可用券查询 → 试算抵扣 → 冻结 → 支付核销 → 取消/退款释放」。

本模块 **不承载订单支付本身**，只负责券的规则、生命周期与金额计算；业务订单模块负责编排调用时机。

## 架构设计（必读）

详细分析与目标架构见：

- **[doc/优惠券架构设计.md](./doc/优惠券架构设计.md)** — 能力中心模式、结账四阶段协议、场景匹配、业务接入规范、演进路线

## 模块结构

```
business-coupon/
├── business-coupon-bean/          # Entity、DTO、VO、Convert、Enum
├── business-coupon-service/       # Domain Service + Mapper
├── business-coupon-application/   # 对外能力编排（业务线主要依赖此层）
├── business-coupon-controller/    # 管理端 REST
├── coupon_schema.sql              # 模板 + 会员券表
├── coupon_scene_schema.sql        # 使用场景表 + template.scene_code
├── coupon_seed.sql / coupon_scene_seed.sql
└── doc/                           # 架构与对接说明
```

移动端 HTTP 入口在 **`business-mobile-gateway`**（`CouponMobileController` 等），Maven 依赖 **`business-coupon-application`**。

## 功能特性

| 能力域 | 说明 |
|--------|------|
| **券模板** | 满减/折扣/无门槛/兑换；有效期、领取方式、渠道与等级限制 |
| **使用场景** | `biz_coupon_scene`：商城/酒店/美食等场景编号与列表接口配置 |
| **使用范围** | 全场 / 指定商品(项) / 分类 / 品牌；适用与排除 ID 列表 |
| **会员券** | 领取、积分兑换、管理端发放、作废；状态：未用/已用/过期/冻结/作废 |
| **结账能力** | 试算抵扣、下单冻结、支付确认（详见架构文档） |
| **对外发券** | 年卡权益、商城首单赠券等通过 `grantByAdmin` 接入 |

## 核心数据表

| 表 | 说明 |
|----|------|
| `app_coupon_template` | 券模板；含 `scene_code`、`use_scope`、`scope_ids` |
| `app_member_coupon` | 会员持券实例；优惠规则快照 + 使用/冻结状态 |
| `biz_coupon_scene` | 使用场景配置（名称、编号、管理端列表 `request_url`） |

建表脚本执行顺序：`coupon_schema.sql` → `coupon_scene_schema.sql` → 种子与菜单权限 SQL。

## 对外依赖与被依赖

### 本模块依赖

- `business-member-service`：会员展示补全、积分兑换扣减

### 依赖本模块的业务（示例）

| 业务模块 | 集成方式 | 现状 |
|----------|----------|------|
| **商城 mall** | `MallOrderApplicationService` → `MemberCouponApplicationService` | 试算、冻结、支付确认已接入 |
| **年卡 yearcard** | `grantByAdmin` 发券 | 仅发券 |
| **商城首单** | 支付后 `grantByAdmin` | 仅发券 |
| **酒店 / 美食 / 景区** | 待按架构文档接入结账四阶段 | 未接入 |

业务线 Maven 须依赖 **`business-coupon-application`**（按需加 `business-coupon-bean`）。

## API 文档

- [后台接口文档.md](./后台接口文档.md) — 模板、会员券、使用场景
- [移动端接口文档.md](./移动端接口文档.md) — 领券、我的券、下单可用券试算

管理端路径前缀：`${jeesharp.web.adminPath}/coupon/...`（TravelWebFront 多为 `/api/coupon/...`）。  
移动端路径前缀：`${jeesharp.web.mobilePath}/member/coupon/...`（多为 `/mobile/member/coupon/...`）。

## 权限配置

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

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-05-07 | 模板、会员券、移动端领券与试算 |
| 1.1 | 2026-06-05 | 使用场景 `biz_coupon_scene`、模板 `scene_code`、管理端场景配置 |
| 1.2 | 2026-06-05 | 架构设计文档：多场景结账能力中心与接入协议 |