cfc/docs/superpowers/specs/2026-08-09-coupon-fix-plan.md

优惠券系统修复计划

日期: 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 通过后无编译错误