# 优惠券功能规划（先规划，后执行）

## 1. 目标与范围

- 支持租户侧创建/管理优惠券模板。
- 支持用户领取/选择/使用优惠券，订单创建时自动校验与核销。
- 优惠券状态可追踪：未使用/已使用/已过期。
- 保持多租户隔离，避免跨租户误用。

## 2. 当前现状

- 数据表已存在：`coupons`、`user_coupons`、`orders.coupon_id`。
- 服务层已有部分能力：`Coupon.ListUserCoupons`、`Coupon.Validate`、`Coupon.MarkUsed`。
- 用户侧 API 已有：`GET /t/:tenantCode/v1/me/coupons`。
- 前端已有「我的优惠券」页面，但暂无领取/选择流程。

## 3. 领域规则（V1）

- `total_quantity = 0` 表示不限量；>0 表示最多可领取次数。
- 每个用户对同一优惠券默认只允许领取一次（可通过规则调整）。
- 过期判断以 `end_at` 为准：`end_at < now` 则视为过期。
- 使用时：订单金额需满足 `min_order_amount`；折扣券需遵守 `max_discount`。

## 4. 枚举与类型规范（必做）

- 新增枚举类型并统一使用（避免硬编码字符串）：
  - `consts.CouponType`：`fix_amount` / `discount`
  - `consts.UserCouponStatus`：`unused` / `used` / `expired`
- `backend/database/.transform.yaml` 映射：
  - `coupons.type -> consts.CouponType`
  - `user_coupons.status -> consts.UserCouponStatus`
- 运行 `atomctl gen enum` + `atomctl gen model`，保持生成文件一致性。

## 5. 接口规划（按模块）

### 5.1 用户侧（UserCenter）

- `GET /t/:tenantCode/v1/me/coupons?status=unused|used|expired`
  - 已有，补齐过期自动标记逻辑。
- `GET /t/:tenantCode/v1/me/coupons/available?amount=<int64>`
  - 返回「当前订单金额可用」的优惠券列表（用于结算页选择）。
- `POST /t/:tenantCode/v1/me/coupons/receive`
  - 领取优惠券（参数：`coupon_id`）。

### 5.2 租户侧（CreatorCenter）

- `POST /t/:tenantCode/v1/creator/coupons`
  - 创建优惠券模板。
- `GET /t/:tenantCode/v1/creator/coupons`
  - 分页查询模板列表（支持状态、有效期、类型过滤）。
- `GET /t/:tenantCode/v1/creator/coupons/:id<int>`
  - 查看模板详情。
- `PUT /t/:tenantCode/v1/creator/coupons/:id<int>`
  - 更新模板（仅未开始或未领取时允许修改核心字段）。
- `POST /t/:tenantCode/v1/creator/coupons/:id<int>/grant`
  - 定向发放给用户（参数：`user_ids` 批量）。

## 6. 服务层设计（关键逻辑）

- `Coupon.Create/Update/List/Get`：模板管理。
- `Coupon.Receive`：
  - 校验有效期与库存（`total_quantity`）。
  - 校验用户是否已领取。
  - 事务内写入 `user_coupons`。
- `Coupon.ListUserCoupons`：
  - join `coupons` 读取模板信息。
  - 对过期券自动标记 `expired`（可更新 DB）。
- `Coupon.ListAvailable`：
  - `status = unused`
  - `start_at <= now <= end_at`
  - `min_order_amount <= amount`
- `Coupon.Validate` / `MarkUsed`：
  - 已有，改用枚举类型 + 统一错误码语义。

## 7. 并发与一致性

- 领取优惠券时在事务中锁定 `coupons` 行或使用条件更新，防止超发：
  - `total_quantity > 0` 时，基于 `COUNT(user_coupons)` 判断库存。
  - 若性能成为瓶颈，再考虑新增 `claimed_quantity` 字段（V2 优化）。

## 8. 前端联动

- 结算页新增「选择优惠券」抽屉（参考 `docs/design/portal/PAGE_ORDER.md`）。
- 用户中心「优惠券」页保持与后端状态一致（unused/used/expired）。
- 订单创建前调用 `available` 接口，展示可用券。

## 9. 测试规划

- Service 单测：
  - 领取成功/重复领取/超库存/过期不可领取。
  - Validate：金额不足、折扣封顶、跨租户禁止。
  - MarkUsed：幂等/重复使用失败。
- Order 相关：
  - 使用优惠券创建订单成功并核销。

## 10. 实施顺序（建议）

1) 枚举 + transform + gen（保证类型安全）。
2) Service：Receive/ListAvailable/ListUserCoupons 过期处理。
3) HTTP：用户端 + CreatorCenter 管理端接口。
4) 前端：结算页优惠券选择 + 领券入口。
5) 补测试 + 回归订单流程。