2026-07-09-family-membership-core.md 11 KB
浠艾福「一生一世家庭会员」实施计划 — Plan 1：订阅+推广核心
版本： v1.1 日期： 2026-07-09 设计文档： docs/superpowers/specs/2026-07-09-family-membership-design.md 姊妹计划： docs/superpowers/plans/2026-07-09-family-membership-ai-butler.md（AI+管家+推荐） 总体工作量估算： 12-15天（后端7-9天 + 前端5-6天）
实施总览
本计划覆盖会员订阅与推广体系的核心建设，分为两个阶段：
| 阶段 | 主题 | 核心交付 | 估算人天 |
|---|---|---|---|
| P0 | 会员订阅+推广基础 | 数据库 + 后端 API + 支付对接 + 推广等级体系 | 7-9天 |
| P1 | 小程序前端 & 管理端 | 会员中心页面 + 推广中心 + 管理端配置 | 5-6天 |
P0：会员订阅+推广基础（后端核心）
P0.1 数据库迁移
方式：通过 DatabaseInitializer.runMigrations() 添加
新表：
| 表名 | 用途 | 关键字段 |
|---|---|---|
member_subscription |
家庭订阅记录 | id, family_id, level(L1/L2), status(active/expired/cancelled), start_time, expire_time, payment_id |
member_subscription_order |
订阅订单 | id, family_id, level, amount, status, payment_type, created_at |
subscription_benefit_log |
权益使用日志 | id, subscription_id, benefit_code, used_at, detail |
commission_record |
佣金/返利记录 | id, order_id, referrer_id, referee_id, type(referral/consumption_share), amount, status(pending/settled/cancelled), settle_time |
referral_tree |
推荐关系树 | id, parent_id, child_id, level(depth), path(materialized path), created_at |
promotion_tier |
推广等级(R0-R4) | id, user_id, tier(R0利他者/R1传福人/R2聚能师/R3启慧者/R4传承者), team_size_1st_layer, team_size_2nd_layer, team_size_3rd_layer, team_member_count, total_team_earnings, promoted_at, last_change_at |
promotion_tier_change_log |
等级变更记录 | id, user_id, old_tier, new_tier, reason(qualify/demotion_protect/admin_adjust), changed_at |
product_ppoint |
产品P点配置 | id, product_id, ppoint(平台利润分), start_date, end_date, created_by |
现有表改造：
users 表新增字段已存在（referrerId/referralCode/memberLevel），无需重复。
sys_config 新增配置项：
| key | 默认值 | 说明 |
|---|---|---|
subscription.l1.price |
131400 | 一生一世卡价格(分) |
subscription.l2.price.monthly |
131400 | 久久一生月费价格(分) |
subscription.l1.upgrade_to_l2 |
按月折算 | L1→L2升级补差价计算(按剩余天数折抵首月) |
subscription.l1.discount_rate |
8500 | 商品折扣率(bps) |
subscription.l2.discount_rate |
7000 | 久久一生折扣率(bps) |
subscription.grace_days |
30 | 到期后数据保留宽限天数 |
promotion.tier.r0.team_1st |
3 | R0→R1条件：一层团队人数≥3 |
promotion.tier.r1.team_1st |
10 | R1→R2条件：一层团队人数≥10 |
promotion.tier.r2.team_3rd |
50 | R2→R3条件：三层团队总人数≥50 |
promotion.tier.r3.team_3rd |
200 | R3→R4条件：三层团队总人数≥200 |
promotion.commission.r0 |
2000 | R0利他者推荐佣金(bps=20%) |
promotion.commission.r1 |
2200 | R1传福人推荐佣金(bps=22%) |
promotion.commission.r2 |
2600 | R2聚能师推荐佣金(bps=26%) |
promotion.commission.r3 |
3000 | R3启慧者推荐佣金(bps=30%) |
promotion.commission.r4 |
3500 | R4传承者推荐佣金(bps=35%) |
promotion.consumption_share.r0 |
2000 | R0返利率(bps=20%) |
promotion.consumption_share.r1 |
2500 | R1返利率(bps=25%) |
promotion.consumption_share.r2 |
3000 | R2返利率(bps=30%) |
promotion.consumption_share.r3 |
3500 | R3返利率(bps=35%) |
promotion.consumption_share.r4 |
4000 | R4返利率(bps=40%) |
promotion.l2_share_bonus |
500 | L2会员额外返利加成(bps=5%) |
promotion.tier_check_interval_days |
7 | 等级考核周期(天) |
P0.2 后端新服务
| 类 | 职责 |
|---|---|
MemberSubscriptionService |
订阅核心逻辑：创建/续费/升级/降级/过期检查 |
SubscriptionBenefitService |
权益校验：checkBenefit(familyId, benefitCode) |
MemberSubscriptionController |
订阅API端点 |
SubscriptionExpiryTask |
定时任务：每日检查过期订阅 |
PromotionTierService |
推广等级(R0-R4)管理：晋级判定（三层团队人数）、等级有效期、L2加成判定 |
PromotionTierController |
推广等级API端点 |
PromotionTierCheckTask |
定时任务：定期检查推广人是否满足升级条件 |
CommissionService |
佣金/返利计算（基于推广等级的阶梯计算）：按tier查佣金率+按tier+产品P点算消费返利 |
ConsumptionShareTask |
消费返利结算任务：7天冷静期后按P点×等级返利率自动结算 |
ReferralService |
推荐关系管理：推荐码生成、关系树构建、三层团队人数查询 |
PpointService |
P点管理：按产品查询当前生效P点、Admin调整P点 |
AdminCommissionService |
管理端佣金/返利管理（审核、手动结算、退款冲正） |
AdminPromotionTierService |
推广等级管理（手动升降、查看团队结构） |
AdminPpointService |
产品P点配置管理 |
API 端点（统一 @PostMapping）：
| 端点 | 说明 | 认证 |
|---|---|---|
/api/subscription/plans |
获取订阅方案列表(含权益说明) | 公开 |
/api/subscription/my |
当前家庭订阅信息 | 需登录 |
/api/subscription/create |
创建订阅订单(返回支付参数) | 需登录 |
/api/subscription/renew |
续费(L1年付延续) | 需登录 |
/api/subscription/cancel |
取消订阅(L2连续包月取消) | 需登录 |
/api/subscription/upgrade |
L1→L2升级(按剩余天数折算抵扣) | 需登录 |
/api/subscription/downgrade |
L2→L1降级(当前月结束后切换) | 需登录 |
/api/subscription/notify |
支付回调 | 公开(签名验证) |
/api/subscription/benefit/check |
检查某项权益是否可用 | 需登录 |
/api/promotion/my-tier |
我的推广等级(R0-R4)详情+晋级进度 | 需登录 |
/api/promotion/tiers |
所有等级定义及晋级条件 | 公开 |
/api/promotion/tier-history |
等级变更记录 | 需登录 |
/api/promotion/team-tree |
我的三层团队树状结构 | 需登录 |
/api/commission/referral-code |
获取/刷新推荐码 | 需登录 |
/api/commission/my-earnings |
我的收益汇总(佣金+返利) | 需登录 |
/api/commission/records |
收益明细列表(分页) | 需登录 |
/api/commission/withdraw |
提现申请 | 需登录 |
/api/commission/ppoint/products |
查看各产品当前P点值 | 需登录 |
/api/referral/tree |
我的推荐关系树 | 需登录 |
P0.3 定时任务
| 任务 | 频率 | 逻辑 |
|---|---|---|
SubscriptionExpiryTask.checkExpiry() |
每日 04:00 | 查出 expire_time < now 的订阅，status→expired，更新用户折扣权益 |
SubscriptionExpiryTask.checkGracePeriod() |
每日 04:30 | 查出 expired 超过 grace_days 的订阅，清理缓存的健康档案 |
PromotionTierCheckTask.checkTiers() |
每7天 | 扫描所有推广人，按三层团队人数判定是否满足晋级条件。满足即升级，终身不掉级 |
ConsumptionShareTask.settle() |
每日 | 扫描已过7天冷静期的 commission_record(type=consumption_share)，按推广等级对应返利率+P点值自动结算 |
P0.4 支付集成
- 复用现有
PaymentOrder系统 - 新增
payment_type = 'subscription'（L1年付） - 新增
payment_type = 'subscription_monthly'（L2连续包月） - 支付成功回调 →
MemberSubscriptionService.activateSubscription() - 首次购买自动创建推广人身份（referral_code + 初始化R0等级）
P0.5 管理端基础页面
管理端新增页面：
| 页面 | 用途 |
|---|---|
views/admin/SubscriptionManagement.vue |
订阅管理：查看所有订阅、手动激活/取消/退款 |
views/admin/BenefitConfig.vue |
权益配置：L0/L1/L2 权益开关、折扣率配置 |
views/admin/PromotionTierConfig.vue |
推广等级配置：R0-R4晋级条件、佣金率、返利率、L2加成 |
views/admin/PromotionTierManagement.vue |
推广人管理：查看推广人等级、手动调整等级、查看三层团队结构 |
views/admin/CommissionConfig.vue |
佣金配置：推广佣金率、消费返利率（按等级） |
views/admin/CommissionRecords.vue |
佣金流水：查看/手动调整/退款冲正 |
views/admin/ProductPpointConfig.vue |
P点配置：各产品P点（平台利润）设置、有效期管理 |
P1：小程序前端 & 管理端
P1.1 小程序页面
| 页面路径 | 用途 | 说明 |
|---|---|---|
pages/membership/index.vue |
会员中心主页 | 展示当前订阅状态、权益清单、升级入口 |
pages/membership/plans.vue |
订阅方案对比 | L0/L1/L2 权益对比表 + 购买按钮 |
pages/membership/benefits.vue |
我的权益 | 已用/可用权益列表 |
pages/promotion/index.vue |
推广中心主页 | 推广等级(R0-R4)、推荐码、收益概览、晋级进度条 |
pages/promotion/team.vue |
我的团队 | 三层团队人数统计+树状结构（禁?.用&&） |
pages/promotion/tiers.vue |
等级详情 | R0-R4升级条件、各等级权益对比、当前进度 |
pages/promotion/earnings.vue |
收益明细 | 佣金+消费返利记录列表（分页） |
pages/promotion/ppoints.vue |
返利商品 | 各产品P点值展示 |
前端适配注意事项：
- 遵循项目规范：Vue 2 Options API，禁
?.，禁 CSS Grid，使用 flexbox - 设计 Token 体系：
--color-primary: #F97316（暖橙主色） - 与 TabBar "富"维度入口连接
P1.2 现有前端改造点
| 页面 | 改动 |
|---|---|
| 商品详情页 | 一生一世会员显示折扣价（划线原价 + 会员价） |
| 活动列表 | 会员专属活动打标"👑 一生一世专享" |
| 课程页面 | L1/L2 会员价显示 |
| 个人中心 | 增加"一生一世会员"入口和状态展示 + 推广中心入口（含当前推广等级徽标） |
| "富"Tab页 | 增加推广中心快捷入口、收益概览小部件 |
里程碑检查点
| 里程碑 | 验证标准 |
|---|---|
| M0: 订阅可购买 | POST /api/subscription/create → 支付 → 回调 → 订阅激活成功（L1年付+L2连续包月） |
| M1: 折扣生效 | L1/L2会员购买商品显示对应折扣价，普通用户显示原价 |
| M2: 推广晋级可自动 | 推广人推荐新用户 → 三层团队人数增长 → 自动晋级R0→R1...更新推广等级 |
| M3: 佣金按等级结算 | 推广人推荐会员购买 → 按等级对应的佣金率结算（R0 20%/R1 22%/.../R4 35%） |
| M4: P点消费返利可追踪 | Admin为商品设P点 → 被推荐人购买商品 → 推荐人 CommissionRecord(type=consumption_share) 按等级+P点创建 |
| 质量门 | mvn clean compile -pl cfc-backend -q 退出码0；小程序前端无?.无CSS Grid |
依赖关系
P0 (数据库+API+支付) ──→ P1 (前端页面+管理端)
- P0 和 P1 可并行（前端可用Mock先开发）
- Plan 2（AI+管家+推荐）与本计划完全可并行，详见该计划的 Stub 解耦策略
参考
- 设计文档：
docs/superpowers/specs/2026-07-09-family-membership-design.md - 姊妹计划：
docs/superpowers/plans/2026-07-09-family-membership-ai-butler.md