cfc/docs/运营推广设计

浠艾福小程序运营推广功能设计和实施计划

状态：已批准 | 分支：cfclub | Effort: Large | Risk: Medium

---

TL;DR

目标： 小程序推广功能全面升级——完成3个"即将上线"占位页（分享邀请卡、推广团队、微信转发），新增6个增长功能（新手任务奖励、每日任务、优惠券、邀请里程碑、推广排行榜），外加后台管理页面。

策略： AARRR增长框架（拉新→激活→留存→变现→推荐），按优先级分3层：先补齐已有的半成品（P0），再补核心增长缺口（P1），最后加强推荐（P2，利用现有两级佣金体系）。

不包含： 推送通知、免费试用会员、拼团/限时抢购、百分比优惠券、三级以上团队树、AOP/事件系统、web/静态站修改。

决策： 分享邀请卡用Canvas本地生成、仅固定金额优惠券、邀请里程碑3/5/10人档、每周排行榜重置、直接服务层调用触发而非AOP。

---

目录

• 一、现状分析
• 二、设计决策
• 三、功能模块
• 四、实施计划
• 五、成功标准

---

一、现状分析

1.1 已有完整系统（无需新建后端）

系统	关键文件	说明
推荐码	InviteController.java /api/invite/code	生成、绑定、追踪推荐关系
两级佣金	CommissionService.settleTwoLevel()	L1=20%, L2=5%, 产品利润分成10%
提现	WithdrawalService	最低100元，审核流程
积分	PointsService	余额、赚取、消费、流水
签到/连续	StreakService	3/7/14/30天里程碑奖励
家庭邀请QR	FamilyInviteController + QrCodeService	令牌式邀请，7天有效期
小程序码	WechatService.generateWxacode()	生成小程序码用于分享
能量系统	EnergyService.awardEnergy()	日上限：身50/心40/智80/行60/富50/全局200

1.2 现有占位页（需补全）

位置	当前代码	需实现
promotion/index.vue:131	shareCard() → "即将上线"	Canvas海报保存到相册
promotion/invite.vue:143	shareInvite() → "即将上线"	微信分享给好友
promotion/index.vue:142	goTeam() → "即将上线"	L1/L2团队成员列表

1.3 完全缺失的系统

• 新用户引导奖励体系
• 每日成长任务
• 优惠券系统
• 邀请里程碑奖励（3/5/10人）
• 推广排行榜

---

二、设计决策

2.1 关键决策

决策项	选择方案	理由	是否可逆
分享邀请卡	Canvas本地生成，保存相册	uni-app Canvas稳定；服务端图片需额外基础设施	是，后续可加
团队页深度	仅L1/L2成员列表	两级佣金模型已够用，树形可视化边际价值低	是，后续可加
邀请里程碑	3/5/10人三档（200/500/1000积分+能量）	经典三档模型；奖励约2-10元，有激励性且不滥用	是，数据库可配置
排行榜范围	每周重置，显示前20名	每周防止固化；20名足够激励	是，后续可加月度/总榜
每日任务类型	签到/完成任务/分享/AI对话	覆盖已有功能，驱动日活	是，数据库可配置
优惠券类型	仅固定金额（无百分比、无试用）	最简实现，无复杂边界情况	是，后续可加
任务触发方式	直接服务层调用，非AOP/事件	与现有代码风格一致，简单可调试	是，后续可改为事件驱动
新手任务追溯	仅统计上线后行为，不追溯历史	避免复杂的数据迁移和边界情况	是

2.2 佣金费率配置（来自sys_config）

费率项	值
L1会员佣金	20% (2000 bps)
L2会员佣金	5% (500 bps)
产品利润分成	10% (1000 bps)
服务佣金	10% (1000 bps)

---

三、功能模块

3.1 P0 — 补全占位页（最高ROI）

C1: 分享邀请卡

• Canvas海报：用户头像+昵称+邀请码+小程序二维码+品牌元素
• 保存到相册：uni.canvasToTempFilePath → uni.saveImageToPhotosAlbum
• 处理相册权限拒绝：uni.openSetting 引导
• 替换 promotion/index.vue 和 invite.vue 中的"即将上线"占位

C2: 推广团队页

• 新后端接口：POST /api/commission/team/list（分页，L1/L2筛选）
• 新前端页：promotion/team.vue
• Tab切换：直推(L1) / 间推(L2)
• 替换 promotion/index.vue 的 goTeam() 占位

C3: 微信转发

• 3个页面接入 onShareAppMessage：
  • promotion/index
  • promotion/invite
  • parent/invite/index
• 分享路径：/pages/invite/join?inviteCode=推荐码
• 封面图：分享海报图片（待C1完成后可用）

3.2 P1 — 激活+变现

C4: 新用户引导奖励

• 6个新手指引任务：REGISTER / COMPLETE_PROFILE / ADD_CHILD / FIRST_CHECKIN / FIRST_TASK / BIND_REFERRAL
• 每个任务奖励积分+能量（REGISTER=100分+10能量，其余递减）
• 用户注册时自动初始化6个任务
• 各现有服务触发自动完成（UserService注册→REGISTER、HealthCheckinService签到→FIRST_CHECKIN等）
• 前端展示进度和领取按钮

C5: 每日成长任务

• 4个每日任务：DAILY_CHECKIN / DAILY_TASK / DAILY_SHARE / DAILY_AI
• 3个新手指引任务（复用C4）：COMPLETE_PROFILE / ADD_CHILD / BIND_REFERRAL
• 每日任务按日重置（新的一天=新的一行日志）
• 前端展示任务列表和进度，领取奖励

C6: 优惠券系统

• 后端实体：Coupon（优惠券定义）+ UserCoupon（用户持有）
• 固定金额、无门槛限制、适用范围（ALL/MEMBERSHIP/PRODUCT/ASSESSMENT）
• 用户领取 → 订单结账时使用
• 管理端：创建/编辑/删除/批量发放
• 集成到 PackagePaymentController 和 MembershipService 支付流程

3.3 P2 — 推荐放大器

C7: 邀请里程碑奖励

• 3个档位：邀请3人→200积分+20能量 / 邀请5人→500积分+50能量 / 邀请10人→1000积分+100能量
• 在 bindReferral 成功时检查：DB级别COUNT，防止并发问题
• 前端在推广邀请页显示3个里程碑进度条

C8: 推广排行榜

• 每周前20名，按本周邀请人数排序
• 个人排名展示（不在前20也显示"未上榜"）
• 每周一重置（用周一开始计算，UTC+8）
• 新增 ReferralLeaderboard 实体和服务

---

四、实施计划

4.1 工作波次

波次	内容	包含任务
Wave 1 (P0)	补全占位页	C1分享卡、C2团队API、C3微信转发、C4团队前端
Wave 2 (P1)	新手引导	C5后端、C6前端
Wave 3 (P1)	成长+变现	C7每日任务、C8优惠券后端、C9每日任务前端、C10优惠券前端、C11优惠券集成
Wave 4 (P2)	推荐放大	C12邀请里程碑后端、C13邀请里程碑前端、C14排行榜后端、C15排行榜前端
Wave 5	管理+集成	C16管理端优惠券、C17管理端任务、C18管理端里程碑+排行榜、C19端到端测试

4.2 新建数据库表（通过 DatabaseInitializer）

表名	用途
onboarding_task	新手任务进度和状态
growth_task	每日/新手指引任务定义
growth_task_log	用户每日任务完成日志
coupon	优惠券定义
user_coupon	用户持有优惠券
invite_milestone	邀请里程碑达成记录
referral_leaderboard	每周排行榜数据

4.3 新建Java类

类	所属波次
OnboardingTask, OnboardingTaskMapper, OnboardingService, OnboardingController	Wave 2
GrowthTask, GrowthTaskLog, GrowthTaskMapper, GrowthTaskService, GrowthTaskController, GrowthTaskDailyResetTask	Wave 3
Coupon, UserCoupon, CouponMapper, CouponService, CouponController, AdminCouponController	Wave 3
InviteMilestone, InviteMilestoneMapper, InviteMilestoneService, InviteMilestoneController	Wave 4
ReferralLeaderboard, ReferralLeaderboardMapper, ReferralLeaderboardService, ReferralLeaderboardController	Wave 4

4.4 新建前端页面

页面路径	用途	波次
pages/promotion/team.vue	团队成员列表	Wave 1
pages/profile/onboarding.vue	新手任务进度	Wave 2
pages/tasks/daily-tasks.vue	每日+新手任务	Wave 3
pages/profile/coupons.vue	我的优惠券	Wave 3
pages/promotion/leaderboard.vue	推广排行榜	Wave 4

4.5 新建管理端页面（cfc-web）

页面	用途
views/admin/CouponManagement.vue	优惠券CRUD+批量发放
views/admin/GrowthTaskManagement.vue	成长任务+新手任务配置
views/admin/PromotionManagement.vue	里程碑+排行榜管理

---

五、成功标准

• 所有3个"即将上线"占位页替换为可工作功能
• 新用户可完成6个新手任务并领取奖励
• 用户可完成4个每日任务并领取奖励
• 用户可领取固定金额优惠券并在结账时使用
• 用户可在邀请3/5/10人时获得里程碑奖励
• 每周排行榜显示前20名和自己的排名
• 管理端可管理所有新功能配置
• mvn compile -pl cfc-backend -q 退出码0
• 前端无可选链(?.)、无CSS Grid

---

附：现有代码库关键引用

cfc-backend/src/main/java/com/etotem/cfc/
├── controller/
│   ├── InviteController.java          # 推荐码API
│   ├── CommissionController.java       # 佣金API
│   ├── FamilyInviteController.java    # 家庭邀请
│   └── reward/RewardController.java    # 奖励系统
├── service/
│   ├── CommissionService.java          # 两级佣金结算
│   ├── PointsService.java              # 积分系统
│   ├── EnergyService.java               # 能量系统（含日上限）
│   ├── StreakService.java               # 签到/连续奖励
│   └── WechatService.java              # 小程序码生成
├── config/
│   └── DatabaseInitializer.java       # 数据库初始化和种子数据
└── entity/
    └── CommissionRecord.java            # 佣金记录（referrerId/buyerId/level）

cfc-frontend/
├── pages/promotion/index.vue           # 推广中心（含3个stub）
├── pages/promotion/invite.vue         # 邀请好友（含stub）
├── pages/parent/invite/index.vue       # 家长邀请（含微信转发）
└── utils/api.js                         # API函数定义

---

文档生成时间：2026-06-26 | 状态：已批准待实施