cfc/docs/superpowers/plans/2026-07-14-family-promotion.md

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

设计文档: 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/
• 功能: 家庭提现申请列表、通过/拒绝操作