# 优惠券系统修复计划

**日期**: 2026-08-09
**问题**: 开通会员赠券未收到 + 缺少"我的优惠券"管理入口

---

## 任务清单（按优先级）

### T1: 修复 JOIN 赠券发放逻辑（后端）
- 文件: `cfc-backend/src/main/java/com/etotem/cfc/service/CouponService.java`
- 改动:
  1. `grantJoinCoupons()` 增加日志（查出模板数量，发券失败时详细日志）
  2. `grant()` 中 period=null 改为写入固定 period="JOIN"，使 uk_grant 生效防重
  3. 新增 `resendUnreceivedJoinCoupons(userId, levelCode)` 补偿方法

### T2: 修复会员支付回调补发逻辑（后端）
- 文件: `cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java`
- 改动:
  1. `activateMembership()` 中记录是否成功发券（新增字段标记到 order 或 Membership）
  2. `processPaymentCallback()` 中 membershipCount>0 时检查发券记录，未发则补发

### T3: 新增"我的优惠券"接口（后端）
- 文件: `cfc-backend/src/main/java/com/etotem/cfc/controller/CouponController.java`
- 文件: `cfc-backend/src/main/java/com/etotem/cfc/service/CouponService.java`
- 改动:
  1. `CouponService` 新增 `listMyCoupons(Long userId)` — user_coupon LEFT JOIN coupon，返回含 status/receivedAt/usedAt/userCouponId
  2. `CouponController` 新增 `GET /api/coupon/my` 端点

### T4: 修复前端 coupons.vue
- 文件: `cfc-frontend/pages/profile-extra/coupons.vue`
- 改动:
  1. 改调新接口 `/api/coupon/my`（而非 `/api/coupon/list`）
  2. 数据结构适配（coupon.status 来自 user_coupon.status，不是 Coupon 模板）
  3. 每个 tab 正确过滤（AVAILABLE/USED/EXPIRED）

### T5: 新增前端 API 函数
- 文件: `cfc-frontend/utils/api.js`
- 改动: 新增 `getMyCoupons()` 函数

### T6: 修复用券链路（pay.vue 传 userCouponId）
- 文件: `cfc-frontend/pages/membership/pay.vue`
- 改动: 选券后传 userCouponId 而非模板 id

### T7: 数据库种子 — 添加 JOIN 券模板
- 文件: `cfc-backend/src/main/resources/schema.sql`
- 改动: 在 coupon 表定义后追加 JOIN 券种子数据
- 文件: `cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java`
- 改动: 新增迁移 204 插入 JOIN 券模板（如不存在）

---

## 验收标准

1. 数据库中 coupon 表存在 grant_type='JOIN' 的模板（至少 3 条：FREE/FAMILY/PREMIUM）
2. 开通会员支付成功后，CouponGrantLog 表出现对应记录
3. 小程序"我的"→"我的优惠券"页显示正确数量（可使用/已使用/已过期）
4. 重复支付回调不会重复发券
5. `mvn clean compile` 通过后无编译错误