# 优惠券全链路改为家庭维度 — 设计文档

**文档版本:** v1.0
**日期:** 2026-08-31
**状态:** 待确认（Design Review）
**决策:** 用户确认 ① 两张入口都改为家庭（CouponManagement + Families.vue） ② 先写设计文档 + 计划

---

## 一、背景与审计发现

### 1.1 业务诉求

用户要求"优惠券只发放给家庭"（"不放在用户身上，应该在家庭管理中实现"）。本次变更把优惠券从**个人维度**重构为**家庭维度**，覆盖全部发放和消费链路。

### 1.2 当前系统审计结果

| 类别 | 位置 | 现状 |
|------|------|------|
| **模板** | `coupon` 表 | 复用，不动 |
| **发放载体** | `user_coupon` 表 | per-user：`user_id, coupon_id, status(AVAILABLE/USED), received_at, used_at, order_id` |
| **发放流水** | `coupon_grant_log` 表 | per-user：`user_id, coupon_id, grant_type(JOIN/PERIODIC/POPULATION/EXCHANGE), period, quantity, source`，唯一键 `uk_grant(user_id, coupon_id, grant_type, period)` |
| **发放路径** | 6 条 | 见下表 |
| **消费接口** | `CouponController` | `/api/coupon/list`, `/api/coupon/my`, `/api/coupon/apply`, `/api/coupon/claim`, `/api/coupon/checkout-list` |
| **订单绑定** | `PackageOrder.userCouponId`, `PaymentOrder.userCouponId` | 存 wallet record id |

#### 六条发放路径（当前都发到用户）

| # | 触发场景 | 调用方 | 目标 |
|---|----------|--------|------|
| 1 | 后台批量发放 | `AdminCouponController.issue` | `List<Long> userIds` |
| 2 | 开通/续费会员赠券 | `MembershipService.grantJoinCoupons` | family 管理员 userId |
| 3 | 新成员加入家庭人口券 | `FamilyMemberService.grantPopulationCoupons` | 成员 userId / 家庭创建者 |
| 4 | 周期补发（每天 5:00） | `CouponGrantTask.grantPeriodicCoupons` | 有效会员 userId 列表 |
| 5 | 积分兑换 | `PointsExchangeService.exchangeCoupon` | 操作用户 userId |
| 6 | CF 值兑换 | `FamilyPlatformPointsService.exchangeCouponByCf` | 操作用户 refUserId（已有 familyId） |

### 1.3 改造影响面

- **后端（Java）**：`CouponService` 核心、6 个发放调用方、`CouponController`、`AdminCouponController`
- **前端管理端（cfc-web）**：`Families.vue`（新增按钮）、`CouponManagement.vue`（批量发放改为家庭 ID）
- **小程序前端（cfc-frontend）**：**零改动**（API 路径与响应字段不变，内部改为读 `family_coupon`）

---

## 二、目标架构

### 2.1 新数据表

```sql
-- family_coupon：家庭维度的优惠券实例表
CREATE TABLE IF NOT EXISTS family_coupon (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    family_id BIGINT NOT NULL COMMENT '所属家庭ID',
    coupon_id BIGINT NOT NULL COMMENT '券模板ID',
    status VARCHAR(16) DEFAULT 'AVAILABLE' COMMENT 'AVAILABLE/USED',
    received_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    used_at DATETIME,
    order_id BIGINT COMMENT '核销时写入的订单号',
    INDEX idx_family_coupon (family_id, coupon_id),
    INDEX idx_status (status),
    INDEX idx_order_id (order_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭优惠券表';

-- family_coupon_grant_log：家庭维度发券流水（防重 + 审计）
CREATE TABLE IF NOT EXISTS family_coupon_grant_log (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    family_id BIGINT NOT NULL COMMENT '受赠家庭ID',
    coupon_id BIGINT NOT NULL COMMENT '券模板ID',
    grant_type VARCHAR(16) NOT NULL COMMENT 'JOIN/PERIODIC/POPULATION/EXCHANGE/CF_EXCHANGE（与coupon_grant_log枚举对齐，新增CF_EXCHANGE）',
    period VARCHAR(16) COMMENT '周期标识(YYYY-MM或YYYY-Qn),PERIODIC防重用',
    quantity INT DEFAULT 1 COMMENT '发放数量',
    source VARCHAR(64) COMMENT '触发来源(订单号/成员ID等)',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_family_grant (family_id, coupon_id, grant_type, period),
    INDEX idx_coupon (coupon_id),
    INDEX idx_family (family_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭优惠券发放流水表';
```

> `user_coupon` 与 `coupon_grant_log` **保留**，不删除、不迁移历史数据。新发放一律写 `family_coupon`/`family_coupon_grant_log`。

### 2.2 关键设计决策

| 决策 | 方案 | 理由 |
|------|------|------|
| **API 路径与响应字段是否变化？** | 不变 | 小程序已上线（coupons.vue / checkout.vue / pay.vue / wealth-cf），不能破坏 |
| **家庭券的 id 如何用于订单？** | 写入 `PackageOrder.userCouponId` / `PaymentOrder.userCouponId` | 保持字段名不动，语义上存储的是 `family_coupon.id`（wallet record id） |
| **admin 订单详情页如何展示家庭券？** | 暂不改动显示逻辑；字段名为 userCouponId，查 `family_coupon` 表 | 最小改动原则 |
| **历史 user_coupon 如何处理？** | 保留，不再写入也不读取（旧家庭券静默过期） | 避免大规模数据迁移风险 |

---

## 三、服务层改动（CouponService）

### 3.1 新增 Mapper / Entity

- `FamilyCoupon` 实体（`@TableName("family_coupon")`）
- `FamilyCouponGrantLog` 实体（`@TableName("family_coupon_grant_log")`）
- `FamilyCouponMapper`、`FamilyCouponGrantLogMapper`（均继承 `BaseMapper`）

### 3.2 方法签名变更

**保留向后兼容的方法（签名不变，内部替换实现）：**

| 旧签名 | 新签名 | 说明 |
|--------|--------|------|
| `listAvailable(Long userId)` | `listAvailable(Long userId)` | 内部：`userMapper.selectById(userId).getFamilyId()` → 查 family_coupon |
| `listMyCoupons(Long userId)` | `listMyCoupons(Long userId)` | 同上 |
| `apply(Long userId, Long userCouponId, String orderType, Integer orderAmount)` | **不变** | 内部：userId→familyId，校验 family_coupon.family_id == familyId |
| `claim(Long userId, Long couponId)` | **不变** | 内部：发给家庭，插入 family_coupon |
| `markUsed(Long userCouponId, Long orderId)` | **不变** | 内部：操作 family_coupon 行 |
| `revert(Long userCouponId)` | **不变** | 同上 |
| `listUnownedExchangeable(Long userId, Long productId)` | **不变** | 内部：familyId |

**新增/改名的私用方法：**

| 新方法 | 说明 |
|--------|------|
| `issueToFamily(Long couponId, Long familyId)` | 单条发放到家庭（替代 issueToUser） |
| `grantFamily(familyId, couponId, grantType, period, source)` | 通用家庭发放（含去重 + 落流水） |
| `grantFamilyJoinCoupons(familyId, levelCode, source)` | JOIN 赠券（替换原 grantJoinCoupons(userId, ...)） |
| `grantFamilyPopulationCoupons(familyId, memberId)` | 家庭人口券（替换原 grantPopulationCoupons(userId, ...)） |
| `listActiveMemberFamilyIds(String levelCode)` | 查指定等级的活跃家庭 ID 列表（供 CouponGrantTask） |

### 3.3 方法实现要点

- `listAvailable(userId)`：通过 User 实体拿 familyId，查 `family_coupon` where family_id=familyId and status=AVAILABLE，join coupon 模板过滤有效期
- `listMyCoupons(userId)`：同理，返回包含 `userCouponId`（= family_coupon.id）+ 模板字段的 Map 列表，**与现有 coupons.vue 兼容**
- `apply(userId, userCouponId, ...)`：familyId 校验必须通过；否则返回 null（不可用）
- `grantFamilyJoinCoupons(familyId, levelCode, source)`：取模板 grantType=JOIN, grantLevelCode=levelCode 的券 → 逐张调用 `grantFamily`
- `grantFamilyPopulationCoupons(familyId, memberId)`：取模板 grantType=POPULATION → 逐张 `grantFamily(familyId, ...)`
- `listActiveMemberFamilyIds(levelCode)`：等价于 `MembershipService.listActiveMemberUserIds`，但返回 `Set<Long> familyIds`

---

## 四、发放路径改写（6 条）

| # | 场景 | 改写点 |
|---|------|--------|
| 1 | Admin 发放 | `AdminCouponController.issue` 改为支持 `familyIds`（同时保留旧 `userIds` 参数兼容，但返回警告日志） |
| 2 | JOIN 会员赠券 | `MembershipService` 中 `grantJoinCoupons(adminUserId, ...)` → `grantFamilyJoinCoupons(order.getFamilyId(), levelCode, order.getOrderNo())` |
| 3 | 新成员人口券 | `FamilyMemberService` 中 `grantPopulationCoupons(targetUserId, memberId)` → `grantFamilyPopulationCoupons(familyId, member.getId())` |
| 4 | PERIODIC 周期补发 | `CouponGrantTask` 改为调用 `listActiveMemberFamilyIds` + `grantFamily` |
| 5 | 积分兑换 | `PointsExchangeService.exchangeCoupon(userId, childId, couponId)` → 取 `familyMemberMapper.selectOne(FamilyMember.userId=userId).getFamilyId()` 得 `familyId`，调 `grantFamily(familyId, ...)` |
| 6 | CF 值兑换 | `FamilyPlatformPointsService.exchangeCouponByCf(familyId, couponId, refUserId)` → 直接 `grantFamily(familyId, ...)` |

---

## 五、控制器层改动

### 5.1 `CouponController`（小程序端）

- 不修改路由或响应字段
- 内部所有 `userId` → 解析 `userMapper.selectById(userId).getFamilyId()`
- `apply` 方法中增加 familyCouponId 归属校验：`familyCoupon.getFamilyId() == user.familyId`

### 5.2 `AdminCouponController`（管理端）

- `/issue`：body 改为 `{ couponId, familyIds: [Long] }`，逐条调用 `issueToFamily`
- 新增 `/issue-family`：`(familyId, couponId, quantity)` 快捷单家庭发放（供 Families.vue 调用）
- `/grant-log`：支持 `familyId` 查询，返回时 join family.name

### 5.3 路由冲突检查

- `/api/admin/coupon/issue-family`：经全量扫描 admin 下所有 `@PostMapping` 路径，无冲突（现有 `/issue` 与 `/issue-family` 不重叠）
- 二次验证命令：`Get-ChildItem cfc-backend/src/main/java/com/etotem/cfc/controller/admin -Filter *.java | Select-String '@PostMapping'`

---

## 六、前端改动（cfc-web）

### 6.1 `Families.vue`

- 「更多」下拉新增 **「发放优惠券」** 按钮
- 点击打开 `el-dialog`，表单包含：
  - 优惠券下拉（调 `/api/admin/coupon/list`）
  - 发放数量（默认 1）
  - 确认按钮 → POST `/api/admin/coupon/issue-family`
- 弹窗底部加「查看该家庭发放记录」链接 → 打开 `CouponGrantLog.vue` 并预填 `familyId`

### 6.2 `CouponManagement.vue`

- 批量发放弹窗：由"用户ID列表（每行一个）"改为"家庭ID列表（每行一个）"
- 文案与 placeholder 同步调整

### 6.3 `CouponGrantLog.vue`

- 搜索框新增「家庭ID」输入项（与现有"用户ID"并存，两者可选其一）
- 查询条件支持 `familyId`
- 列表列"用户"改为"家庭"（显示家庭 name 或 ID）

### 6.4 `api/coupon.js`

- 新增 `issueFamilyCoupon(data)` → POST `/api/admin/coupon/issue-family`
- 新增 `getFamilyCouponGrantLog(data)` → POST `/api/admin/coupon/grant-log`（支持 familyId 参数）

---

## 七、数据库迁移

- **迁移编号**: 迁移 269
- 入口：`DatabaseInitializer.runMigrations()`，参照 AGENTS.md 规范用 `ensureColumn` 或 `try-catch` 包裹
- 同步 `schema.sql`

迁移内容：
```
// 迁移269: 创建 family_coupon 表 + family_coupon_grant_log 表
// （优惠券全链路改为家庭维度：2026-08-31）
```

---

## 八、验证步骤

1. **编译**：`mvn clean compile` — 必须通过
2. **API 路径检查**：
   ```bash
   grep -rn '@PostMapping("' cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminCouponController.java
   ```
   确认无冲突
3. **Bean 命名检查**：新增 `FamilyCouponMapper` / `FamilyCouponGrantLogMapper` 的 Bean name 不冲突
4. **API 端点注册**（如适用）：确认 `FamilyCouponController` 不在（本次不改小程序控制器的路由）
5. **Admin 操作流**：在 cfc-web 家庭管理页测试发放 → 管理端查看记录

---

## 九、风险与降级

| 风险 | 缓解 |
|------|------|
| 小程序用户现有优惠券消失 | `user_coupon` 历史数据保留，但前端 `/api/coupon/my` 改读 family_coupon → 旧券不可见。**影响面**：已使用的券不受影响；未使用的历史券会"消失"。建议：本功能上线前清理或迁移旧券（本设计暂不包含迁移，留作一期后续） |
| `CouponGrantTask` 跑批前 family 尚未存在 | 迁移后首次运行即按家庭发券，行为一致 |
| 旧订单（PackageOrder.userCouponId）指向 user_coupon 历史数据 | 订单详情中的优惠券展示逻辑不变（字段名不更名），仅新订单写入 family_coupon.id |

**关键注意**：用户现有 `user_coupon` 未使用券在新链路下不可用（因为 `/api/coupon/my` 改读 family_coupon）。建议在上线说明中告知历史券有效期内的使用方式（如有）。

---

## 十、不在本次范围内

- 小程序端优惠券展示/核销流程的优化（API 路径与字段不变，但页面逻辑暂不动）
- `user_coupon` 历史数据清理/迁移
- 订单详情页（cfc-web）中优惠券信息的增强展示

---

## 十一、关联文档

- 实施计划：`plans/2026-08-31-coupon-family-based.md`（编写中）
- API 参考：`docs/superpowers/api/API_REFERENCE.md`（发放相关章节需更新）
- 项目管理：`docs/superpowers/PROJECT-OVERVIEW.md`（本项完成后需同步更新状态）