meal_manager/jeesharp-business/business-coupon

优惠券模块 (business-coupon)

模块概述

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

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

架构设计（必读）

详细分析与目标架构见：

• 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 — 领券、我的券、下单可用券试算

管理端路径前缀：${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	架构设计文档：多场景结账能力中心与接入协议