# 家庭推广体系重构实施计划

设计文档: `docs/superpowers/specs/2026-07-14-family-promotion-redesign.md`

**计划评审**: Momus [OKAY] — 无阻塞性问题

---

## 阶段总览

| 阶段 | 内容 | 工作量估计 |
|:----:|------|:----------:|
| P1 | 二维码改造：全部切 wxacode + env_version 修复 + scene 解析 | ~4h |
| P2 | 家庭公共账户：建表 + CommissionService 改造 + 注册绑定 | ~8h |
| P3 | 前端重构：推广中心重设计 + 成员贡献榜 + 支付集成 | ~12h |
| P4 | 管理后台：家庭收益管理 + 提现审核 | ~4h |

---

## P1 — 二维码改造（第一阶段）

### 目标
所有二维码改为 wxacode 小程序码，修复 env_version，新增 ref= 场景处理。

### 依赖关系
1.1 → 1.2 → (1.3, 1.4 并行) → 1.5 → 1.6 → 1.7

| 任务 | 依赖 | QA 工具 |
|:----:|:----:|---------|
| 1.1 | 无 | `mvn compile` 验证 |
| 1.2 | 1.1 | Postman 调用 `POST /api/common/qrcode` 检查返回图片格式 |
| 1.3 | 1.2 | Postman 调 InviteController 验证异常处理 |
| 1.4 | 1.2 | 同 1.3 |
| 1.5 | 1.2 | 微信开发者工具模拟扫码场景 |
| 1.6 | 1.5 | 微信开发者工具验证注册绑定 |
| 1.7 | 全部 | `mvn clean compile` |

### 任务

#### 1.1 修复 WechatService env_version 硬编码
- **文件**: `cfc-backend/src/main/java/com/etotem/cfc/service/WechatService.java:195`
- **改动**: `env_version` 从硬编码 `"trial"` 改为 `@Value("${wechat.env-version:release}")`
- **配置**: 各 `application-*.yml` 增加 `wechat.env-version`
- **验收**: prod 环境生成 release 版小程序码

#### 1.2 改造 CommonController — 从 ZXing 改为 wxacode
- **文件**: `cfc-backend/src/main/java/com/etotem/cfc/controller/CommonController.java`
- **改动**: 
  - 入参从 `{ content }` 改为 `{ type, referralCode }`
  - 调用 `WechatService.generateWxacode()` 生成小程序码
  - type=register → scene=`ref={referralCode}`, page=`pages/invite/join`
  - 移除 ZXing 依赖（com.google.zxing）
- **验收**: 调用 API 返回 wxacode 格式图片（image/png）

#### 1.3 改造 InviteController — 移除 ZXing 降级
- **文件**: `cfc-backend/src/main/java/com/etotem/cfc/controller/InviteController.java`
- **改动**: 
  - 移除 ZXing 降级 catch 块
  - 异常直接向上抛出
- **验收**: wxacode 失败时返回错误而非降级

#### 1.4 改造 FamilyInviteController — 移除 ZXing 降级
- **文件**: `cfc-backend/src/main/java/com/etotem/cfc/controller/family/FamilyInviteController.java`
- **改动**: 同 1.3

#### 1.5 更新 App.vue scene 解析 — 增加 ref= 前缀处理
- **文件**: `cfc-frontend/App.vue`
- **改动**: `handleScene()` 增加 `ref=` 前缀解析
- **验收**: 扫码注册推广码后能跳转到 /pages/invite/join?refCode=xxx

#### 1.6 更新 pages/invite/join.vue — 处理 refCode 参数
- **文件**: `cfc-frontend/pages/invite/join.vue`
- **改动**: 接收 `refCode` 参数，注册时提交到后端
- **验收**: 注册时正确提交 refCode，用户被绑定推荐关系

#### 1.7 编译验证
- **命令**: `cd cfc-backend && mvn clean compile`

---

## P2 — 家庭公共账户（第二阶段）

### 目标
新增 3 张表 + CommissionService 家庭归因 + 注册绑定。

### 依赖关系
(2.1, 2.3) → 2.2 → (2.4, 2.5, 2.6 并行)

### 任务

#### 2.1 数据库迁移
| 表名 | 操作 | 说明 |
|------|:----:|------|
| `family_earnings` | CREATE | 家庭公共账户余额、可提现额、总收益 |
| `family_earnings_member` | CREATE | 成员分配额度、权限(is_admin)、贡献金额 |
| `family_earnings_record` | CREATE | 流水记录：收入/提现/颁发/消费 |
| `commission_records` | ALTER | 加 `family_id` 列 |
| `schema.sql` | SYNC | 同步建表语句 |
| DatabaseInitializer | 添加 | ensureTable + ensureColumn 迁移 |

- **入口**: `cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java`

#### 2.2 FamilyEarningsService 实现
- **文件**: `cfc-backend/src/main/java/com/etotem/cfc/service/FamilyEarningsService.java`
- **方法**:
  - `getFamilySummary(familyId)` — 家庭总览
  - `getMemberContributions(familyId)` — 成员贡献
  - `earn(familyId, amount, fromUserId)` — 收入
  - `withdraw(familyId, amount, adminUserId)` — 提现
  - `distribute(familyId, toUserId, amount, adminUserId)` — 颁发
  - `consume(familyId, userId, amount)` — 消费扣款
  - `getRecords(familyId, type)` — 流水查询

#### 2.3 CommissionService 改造
- **文件**: `cfc-backend/src/main/java/com/etotem/cfc/service/commission/CommissionService.java`
- **改动**: `settle()` 和 `settleTwoLevel()` 增加家庭归因逻辑
- **逻辑**: 结算时通过 referrerId → familyId → 写入 `family_earnings` + `family_earnings_record`

#### 2.4 6 个订单服务同步改造
- **文件**:
  - `cfc-backend/.../service/assessment/AssessmentOrderService.java`
  - `cfc-backend/.../service/payment/PaymentService.java`
  - `cfc-backend/.../service/PackagePaymentService.java`
  - `cfc-backend/.../service/ProductOrderService.java`
  - `cfc-backend/.../service/MemberSubscriptionService.java`
  - `cfc-backend/.../service/MembershipService.java`
- **改动**: 调用 CommissionService 结算时传入上下文

#### 2.5 FamilyEarningsController 实现
- **文件**: `cfc-backend/src/main/java/com/etotem/cfc/controller/FamilyEarningsController.java`
- **端点**:
  - `POST /api/earnings/family/summary`
  - `POST /api/earnings/family/members`
  - `POST /api/earnings/family/records`
  - `POST /api/earnings/admin/distribute`
  - `POST /api/earnings/admin/toggle-member`
  - `POST /api/earnings/admin/withdraw`

#### 2.6 注册绑定实现
- **逻辑**:
  - 新用户携带 `refCode` 注册
  - 通过 referralCode → user → family 建立关联
  - 更新推荐人 `directCount`
  - 写入 `family_earnings_record`

---

## P3 — 前端重构（第三阶段）

### 目标
推广中心重新设计，家庭级数据展示 + 成员贡献榜 + 管理员面板。

### 任务

#### 3.1 推广中心首页 redesign
- **文件**: `cfc-frontend/pages/promotion/index.vue`
- **改动**:
  - 家庭总数据卡片（可提现余额、总收益、推荐人数）
  - 成员贡献榜（头像、贡献金额、排名）
  - 孩子角色只读视图

#### 3.2 管理员面板（家长/管理员可见）
- **文件**: `cfc-frontend/pages/promotion/` 子组件
- **功能**:
  - 提现弹窗（金额输入、确认）
  - 颁发给成员（选择成员、输入金额）
  - 成员权限开关（toggle 是否为管理员）

#### 3.3 孩子可见
- **文件**: `cfc-frontend/pages/promotion/index.vue`
- **改动**: 孩子角色可访问推广中心，只读模式（不可见管理员面板）

#### 3.4 支付集成
- **改动**: 各订单页面增加「家庭余额」支付选项
- **逻辑**: 优先使用个人分配额度 → 家庭公共池（管理员允许时） → 微信支付补差

#### 3.5 API 对接
- **文件**: `cfc-frontend/utils/api.js`（或类似文件）
- **改动**: 新增 6 个 API 函数

---

## P4 — 管理后台（第四阶段）

### 目标
管理员后台支持家庭收益管理和提现审核。

### 任务

#### 4.1 家庭收益管理页面
- **文件**: `cfc-web/src/views/earnings/`
- **功能**: 列表 + 搜索、家庭总账查看、成员分配情况

#### 4.2 提现审核
- **文件**: `cfc-web/src/views/earnings/`
- **功能**: 家庭提现申请列表、通过/拒绝操作