2026-10-24-cf-value-unification-plan.md 38 KB

CF 值体系统一方案 · 个人维度 + 优惠券家庭化

日期:2026-10-24 状态:待派发(批 F) 前置文档:2026-08-12-platform-points-family-pool-design.md、2026-09-01-cf-commission-redesign.md 本方案取代上述两份文档中与"CF 值归属维度"相关的全部结论


一、需求口径变更(2026-10-24 用户拍板,单一事实源)

# 新口径 取代的旧口径
N1 取消家庭 CF 值,家庭池不再承接任何 CF 值发放/余额 2026-08-12:CF 值=家庭共享池
N2 CF 值是个人的,记账维度=家庭成员(family_member.id) 206-08-12 家庭池 / 2026-09-01 个人钱包(user 维度)
N3 优惠券是家庭的:个人用 CF 值兑换的优惠券一律归属家庭共享 2026-08-12 需求第 3 条"CF 值不参与券兑换"
N4 必须落实所有个人 CF 值获取途径的规则与数量(本文档 §三) —
N5 推荐分润合并为一条:团队规模阶梯分佣 + 旧 L1/L2 分佣合并 2026-09-01 双体系并存
N6 消费返 CF:按实际消费,1 元 = 100 CF,所有消费都返,商品收货规则(F01)去掉 2026-08-12 F01 商品收货 1元=1积分 + F02 消费返 CF(双轨)
N7 推荐分润两级:
① 直接销售奖:基数=直接推荐人的消费 P 点,按团队(8 层以内)年度累计 P 点分档,最高 70%
② 间接销售奖:基数=间接推荐人的消费 P 点,按自身年度累计消费 P 点分档,最高 20%
累计按一年滚动计算,累计单位是 P 点(非金额),用户级别可降级
2026-09-01 单一团队规模阶梯
N8 分享奖励:推荐他人注册平台即获得 CF 值(新增 F24) —
N9 F07 文章答题 日限 5 次 原无日限
N10 F09 测评建档:第 1 份报告 50 CF,后续每份 10 CF,重复报告不计 原仅首次 50
N11 任务、打卡获取 CF 值按会员等级不同次数上限:
• 9.9 体验会员(BASIC):3 次/天
• 家庭会员(FAMILY)& 终身会员(LIFETIME):10 次/天
• 高级会员(PREMIUM):20 次/天
• 免费会员(FREE)与标准会员(PROVIDER)待定
原固定每日 1 次

1.1 配套决策(已确认)

# 决策 结论
D1 记账维度 家庭成员维度(family_members.id),非登录用户维度
D2 存量家庭池余额处理 迁移到家庭创建者账号,一次性脚本,写迁移流水,幂等

为何选成员维度而非用户维度:答题、打卡、家庭挑战、成长任务、测评建档这 13 条获取途径当前全部挂在 family_member 维度;若改挂 user,则无独立账号的孩子(memberType=local)无法持有 CF 值,打卡/答题/挑战将静默失效。成员维度实现零改动、零损失,且与家庭关系树天然对齐。


二、现状:三套账本

账本 表/字段 维度 获取途径数 唯一键
A · 家庭 CF 值 family_platform_balance 家庭 4 family_id
B · 个人 CF 钱包 user_platform_balance 用户 9 user_id
C · 孩子 CF 值 family_members.system_points 家庭成员 13 family_member.id

问题:system_points 注释写作"CF值余额"(PointsService.java:106),但用户端 wealth-cf 页展示的是家庭 CF 值 —— 获得来源与可见余额不在同一账本。


三、个人 CF 值获取规则与数量总表(N4 核心交付)

合并后共 24 条有效获取途径(原 23 条:F01 删除,F02/F03 重写,新增 F24,F06 修正,F07/F09/F14-F16/F22 按会员等级分级)。

3.1 消费返佣类(5 条)

# 途径 数量规则 参数来源 落账
F01 商品确认收货返积分 删除(N6) — —
F02 消费返 CF(所有订单) floor(实付金额(分)/100) × 100
即 1 元 = 100 CF;所有消费订单(商品/套餐/测评/会员/订阅/调研)均返
固定系数 100,可外置 sys_config.cf_per_yuan(默认 100) member
F03a 直接销售奖 基数 = 直接推荐人消费的 P 点
比例档 = 按团队(8 层以内)年度累计 P 点分档,最高 70%
累计:滚动一年(以消费时间为准),累计单位 P 点
可降级
cf_direct_sales_tier 表(档位可配,见 §四)
cf_referral_service.getTeamAnnualPpoints(referrerId, 8)(团队 8 层内一年 P 点累计)
member
F03b 间接销售奖 基数 = 间接推荐人消费的 P 点
比例档 = 按自身年度累计消费 P 点分档,最高 20%
累计:滚动一年,累计单位 P 点
可降级
cf_indirect_sales_tier 表(档位可配,见 §四)
cf_referral_service.getSelfAnnualPpoints(referrerId)
member
F04 商品赠品 CF 赠品配置的 CF 数量 product_order_gift.cf_value(赠品规则管理端配置) member
F05 活动签到 CF 活动配置的 CF 数量 activities.platform_points member
F06 菌群健康调研打卡返还 cf_refund_amount,为空按 floor(项目价/100) × 100(1 元=100 CF)
示例:19.9 元 → 1,990 CF(原兜底 1990 恰自洽)
GutHealthProject.cf_refund_amount / sys_config.gut_health_project_price(兜底常量去除) member

3.2 成长行为类(14 条)

# 途径 数量规则 参数来源 代码出处
F07 文章答题奖励 答对题数 + (全对 ? 3 : 0)
日限 5 次(N9)
cf_earn_rule.amount(固定公式),daily_limit_per_member=5 ArticleCommentController.java:213
F08 AI 阅读答题奖励 5(仅全部答对才发) cf_earn_rule.amount=5(固定) ArticleService.java:1071
F09 完成测评建档 第 1 份报告 50 CF,后续每份 10 CF,重复报告不计(N10)
需按报告文件哈希/编号去重
cf_earn_rule.formula=first_report?50:10,去重键 report_hash GuideRecordController.java:58
F10 家庭挑战完成 challenge.reward_points,按每个完成成员各发一次(待确认是否改家庭合计) family_challenge.reward_points(管理端配置) FamilyChallengeService.java:465-475
F11 邀请里程碑 milestone.reward_points,按里程碑配置 里程碑配置表 InviteMilestoneService.java:120
F12 成长任务 task.reward_points,按任务模板配置 成长任务模板配置 GrowthTaskService.java:108
F13 分享阅读奖励 默认 5 sys_config.share_read_reward_points / cf_earn_rule.amount=5 ShareService.java:103
F14 喝水打卡 固定 5 CF/次
日限按会员等级(N11):
FREE=1/天(建议),BASIC=3/天,FAMILY=10/天,LIFETIME=10/天,PREMIUM=20/天,PROVIDER=待定
cf_earn_rule.amount=5,daily_limit_by_tier 映射表(见 §3.4) HealthWaterController.java:103
F15 饮食打卡 固定 5 CF/次
日限同上(N11)
同上 HealthMealController.java:294
F16 每日健康打卡 固定 10 CF/次
日限同上(N11)
同上 DailyCheckinService.java:78
F17 挑战赛子任务完成 progress.reward_cf,按任务配置 挑战赛任务配置 ChallengeServiceImpl.java:142
F18 健康启航计划付费 floor(实付金额/100) × 100(1 元=100 CF) cf_earn_rule.formula=同 F02 PurchaseServiceImpl.java:109
F19 管理员手动调整 正负任意,需家长密码校验 管理端输入 PointsService.java:70
F24 分享奖励(推荐注册) 推荐他人注册平台即获得 CF 值(N8)
数量可配(建议 20 CF/人)
cf_earn_rule.amount(建议 20),daily_limit_per_member=10 —

3.3 问题域与关卡类(2 条)

# 途径 数量规则 参数来源 代码出处
F20 问题域全部任务完成奖励 domain.reward_cf_value problem_domain.reward_cf_value(管理端配置) ProblemCompletionService.java:127
F21 关卡通关奖励 gate.reward_points unlock_gate.reward_points(管理端配置) UnlockGateService.java:300

3.4 任务与成员间流转(2 条)

# 途径 数量规则 参数来源 代码出处
F22 任务完成 CF task.cf_amount(现双发个人+家庭池,取消家庭池那条) 任务配置 TaskService.java:998(保留)/ :1001(删除)
F23 成员间转让(收款方) 转入方 +金额,转出方 -金额,同一事务 转账金额 CfTransferController.java:63

3.4 会员等级 → 每日次数上限映射表(N11)

会员等级 level_code 任务/打卡每日上限次数 备注
免费会员 FREE 1(建议) 未明确口径,建议 1
9.9 体验会员 BASIC 3 N11 明确
家庭会员 FAMILY 10 N11 明确
终身会员 LIFETIME 10 N11 明确
高级会员 PREMIUM 20 N11 明确
标准会员 PROVIDER 待定 规划师/专家向,非消费端

实现:CfBalanceService.earnByRule 在执行前查 member 关联的 user → family_memberships → membership_levels.level_code,按上表取 daily_limit。cf_earn_rule 增加 daily_limit_by_tier JSON 字段或单独表 cf_earn_daily_limit(rule_code, level_code, daily_limit)。

3.5 待外置的硬编码清单(合规改造项)

F08、F18 两处 CF 数量为硬编码,需迁到 cf_earn_rule(F07/F14-F16 已在规则表配置,F09 已公式化,F13 已 sys_config)。F10 家庭挑战按人各发或家庭合计待确认。


3.6 规则与数量数据库化设计(N4 落地核心)

总原则:发放收口到单一入口。24 条途径全部改调 CfBalanceService.earnByRule(memberId, ruleCode, refId, ctx),代码中不再保留任何 CF 数量常量——否则"随时调整"落不了地。

3.6.1 规则表 cf_earn_rule(24 行种子,F02–F24)

CREATE TABLE IF NOT EXISTS cf_earn_rule (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    code VARCHAR(20) NOT NULL COMMENT '规则编码 F02~F24',
    name VARCHAR(100) NOT NULL COMMENT '途径名称',
    category VARCHAR(20) NOT NULL COMMENT 'consume消费返佣/behavior成长行为/admin管理员',
    enabled TINYINT NOT NULL DEFAULT 1 COMMENT '1启用 0停用(随时开关)',
    rule_type VARCHAR(20) NOT NULL COMMENT 'fixed固定/formula公式/per_item逐人发放',
    amount INT COMMENT '固定数量(rule_type=fixed)',
    formula VARCHAR(500) COMMENT '计算公式(rule_type=formula)',
    params_json TEXT COMMENT '公式参数(bps/倍数等)',
    daily_limit_per_member INT COMMENT '单成员每日上限,空=不限',
    total_limit_per_member INT COMMENT '单成员累计上限,空=不限',
    cooldown_seconds INT COMMENT '同一成员冷却秒数,空=不限',
    dedup_ref_type VARCHAR(50) NOT NULL COMMENT '幂等refType,写入cf_balance_log',
    effective_from DATETIME COMMENT '生效起,空=立即',
    effective_to DATETIME COMMENT '生效止,空=长期',
    sort_order INT NOT NULL DEFAULT 0,
    remark VARCHAR(255),
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    updated_by BIGINT COMMENT '最后修改人',
    UNIQUE KEY uk_code (code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='CF值获取规则(运营可配置)';

3.6.2 变更历史 cf_earn_rule_history(审计)

CREATE TABLE IF NOT EXISTS cf_earn_rule_history (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    rule_code VARCHAR(20) NOT NULL,
    old_json TEXT COMMENT '变更前整行快照',
    new_json TEXT COMMENT '变更后整行快照',
    changed_by BIGINT NOT NULL,
    change_reason VARCHAR(255),
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    KEY idx_rule (rule_code, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='CF值规则变更历史';

3.6.3 统一发放入口 CfBalanceService.earnByRule

执行顺序(任一步失败即不发):

  1. 读规则(按 code + 当前时间落在 effective_from/to 内)→ enabled=0 直接返回
  2. 上限校验:daily_limit_per_member(按日聚合当日流水)、total_limit_per_member(按 total_earned 或累计)、cooldown_seconds(查最近一笔流水时间)
  3. 计算数量:fixed 取 amount;formula 用 params_json 求值(公式白名单函数:floor/amt/qty/cfg);per_item 由 ctx 提供逐人数量
  4. 幂等写入((member_id, dedup_ref_type, ref_id) 唯一键)+ 写 cf_balance_log
  5. 发送通知

硬约束:points_multiplier、product_platform_points_share、commission_service_rate、share_read_reward_points、gut_health_project_price 等散落在 sys_config/products 的 CF 参数,一律迁入 cf_earn_rule.params_json 或作为 formula 参数,避免规则散落两处。cf_rate_tier 废弃停用(保留只读),替代者 cf_direct_sales_tier / cf_indirect_sales_tier(§4.2)。

3.6.4 管理端

  • AdminCfEarnRuleController:/list(分页)//save(新建+编辑)//toggle(开关)//history(变更历史)
  • cfc-web 新增 views/admin/CfEarnRuleManage.vue:规则列表 + 开关 + 编辑抽屉(名称/类型/数量或公式/参数/三道闸/生效期)+ 变更历史抽屉
  • 权限:仅 admin 角色;修改即时生效(无需重启),历史可追溯

3.6.5 24 条规则种子初始值

见 §三 各条「参数来源」列,初始值按现状录入,F06、F18 两处按修正后数值录入(见 §九)。

归口说明:CF 规则本身的参数(比例、档位、基数、窗口、三道闸)→ 挂 cf_earn_rule.params_json(§3.6.3);CF 通用运营参数(如 commission_service_rate、points_multiplier、share_read_reward_points 等散落项)→ 迁到 service_config 表(§3.6.6 L2)。两类均走 L2 后台 UI,禁止散落常量或裸改库。

3.6.6 配置治理 SOP(Phase 1-2 全程遵守)⚠️

核心原则(本次调整):CF 值相关的一切业务/算法参数一律归入 L2(service_config + cf_earn_rule),L1 常量类只保留与 CF 算法无关的纯订单/技术参数,L3 环境变量不变。CF 参数不再硬编码,一律通过 ConfigService.getConfig(key) 读取(含缓存)。

层 位置 谁能改 谁读 适用范围
L1 硬编码常量 Java 常量类 开发者(改代码) 全局 仅订单/锁/超时等纯技术参数,与 CF 值算法无关
L2 数据库配置 service_config 表 + cf_earn_rule 表 超级管理员(/admin/configs 后台 UI) ConfigService.getConfig(key) + CfEarnRuleService(含缓存) CF 值全部业务/算法参数(含 24 条规则种子)
L3 环境变量 .env / 系统属性 运维(重启生效) Spring @Value DB 连接、第三方 API key

新增配置的标准动作:

  1. CF 业务/算法参数 → 一律 L2:包括任何涉及积分、分润、佣金、比例、档位、有效期、扣减策略、价格系数的配置,无论是否"当前基本不变",都放 service_config 或 cf_earn_rule
  2. CF 无关的纯技术参数 → 放 L1 常量:订单锁 TTL、请求超时、缓存 TTL 等,与 CF 值算法无耦合
  3. 基础设施 → 放 L3 环境变量:DB/密钥
  4. 禁止直接改数据库:所有 L2 改动走 /admin/configs UI 或 seed SQL(Flyway 初始化),修改必须走审计(W0.3)

W0.1 CF 值配置清单(全部入 L2)

(1)cf_earn_rule.params_json 承载(挂到对应规则行)

见 §3.6.3 与 §三 各条「参数来源」列,24 条规则(F01–F24)的比例档位、基数口径、时间窗口、三道闸、生效期全部落在 cf_earn_rule.params_json,不再散落到 sys_config/products。

(2)service_config 承载(CF 通用运营参数,key 前缀 cf.)

配置项 config key 默认值 说明
积分倍数(消费 → CF 换算) cf.rate.points_multiplier 1.0 原散落 sys_config
复购率默认系数 cf.rate.repeat_rate_default 1.0 未匹配规则时不加权
佣金结算周期 cf.commission.settle_days 7 财务口径常用
邀请码有效期 cf.invite.valid_days 7 兼顾转化与时限
默认价格系数 cf.price.default_factor 1.0 未定价时原价
库存扣减策略 cf.stock.deduction_mode immediate immediate/on_pay 由 Phase 4 决定
分享阅读奖励积分 cf.rate.share_read_reward_points 现有值 原散落 sys_config
佣金服务费率 cf.commission.service_rate 现有值 原散落 sys_config
肠道健康项目定价 cf.product.gut_health_price 现有值 原散落 products
产品平台积分分成比例 cf.product.platform_points_share 现有值 原散落 products

(3)缓存与变更

  • 每次 CF 参数改动后,通过 CfConfigCache.invalidate() 清缓存(可挂在 CfEarnRuleController.save/toggle 与 AdminConfigController.save 的 AOP 上)
  • 版本号:service_config.cf_version 单调递增,前端可根据版本号做局部刷新提示
  • 读路径:ConfigService.getConfig("cf.rate.points_multiplier") → 命中本地缓存(TTL 60s)→ 失效回源 DB → 兜底 Java 常量

(4)L1 常量类仅保留的技术参数(不进 L2)

这些项与 CF 值算法无耦合,属订单/请求/缓存基础设施,仍留在 Java 常量类:

配置项 常量类 默认值
订单超时取消 OrderConstants.ORDER_TIMEOUT_MIN 30 分钟
库存锁时间窗口 OrderConstants.STOCK_LOCK_WINDOW_MS 30 分钟
库存锁 TTL OrderConstants.STOCK_LOCK_TTL_SEC 20 分钟
锁超时告警 OrderConstants.STOCK_LOCK_WARN_AFTER_MIN 20 分钟
订单状态刷新 TTL OrderConstants.ORDER_STATUS_REFRESH_SEC 60 秒
后台 API 超时 AdminConstants.ADMIN_API_TIMEOUT_MS 5000
前端请求超时 前端常量 15000

W0.2 双配置中心合并(service_config ← product_config)

CF 参数归 L2 后,product 侧遗留的 product_config 也应并入,形成唯一的 service_config 入口。

步骤 动作 负责人
1 备份 product_config 全表数据(含审计日志) 运维
2 写 Flyway 脚本:ALTER TABLE service_config ADD COLUMN product_key VARCHAR(64) 开发者
3 批量 INSERT INTO service_config 从 product_config 迁数据,product_key 填对应产品标识 开发者
4 改 ProductConfigServiceImpl 从查 product_config 改为查 service_config WHERE product_key = ? 开发者
5 保留 product_config 表 30 天只读(回滚用),第 31 天删除表 运维
6 前端配置管理页只保留一个"配置中心"入口 前端

SOP 检查清单(Phase 1-2 每个新配置项落地前问一遍)

  • 这是 CF 值相关参数吗?是 → 一律 L2(service_config 或 cf_earn_rule.params_json)
  • 如果是 L2 配置,key 是否符合 cf.{module}.{key} 命名规则?
  • 管理员 UI 有没有入口(/admin/configs 或 /admin/cf-earn-rules)?
  • 改完后缓存是否失效(CfConfigCache.invalidate 覆盖到了吗)?
  • 有没有走审计(W0.3 的 AOP 切面拦截到了吗)?
  • 是否属于 CF 无关的纯技术参数(订单/锁/超时)?是 → 才允许放 L1 常量
  • 是否属于基础设施(DB/API key)?是 → 放 L3 环境变量

两套配置现状(合并背景):

  • ProductConfigItem(product 侧):与 product 服务绑定的价格/参数/开关
  • ServiceConfigItem(service 侧):与 cf 服务绑定的价格/参数/开关
  • 二者 schema 高度相似(groupKey + configKey + configValue + valueType),Phase 1-2 期间统一到 service_config 一张表,product 侧只留 product_key 关联键。

3.7 待办(W 项)

W0.1 CF 值配置全部归口 L2

  • 交付物:
    • Flyway seed SQL:把 §3.6.6 的 10 项 CF 通用运营参数写入 service_config(key 前缀 cf.)
    • ConfigService.getConfig(key) 读取封装(含本地缓存 + TTL 60s + CfConfigCache.invalidate() 主动失效钩子)
    • 迁移脚本:把散落在 sys_config/products 的 CF 参数(points_multiplier、product_platform_points_share、commission_service_rate、share_read_reward_points、gut_health_project_price)迁到 service_config
    • L1 常量类:OrderConstants.java / AdminConstants.java(仅订单/锁/超时等 CF 无关的技术参数)
  • 位置:
    • Flyway:cfc-backend/src/main/resources/db/migration/
    • Java:backend/src/main/java/com/cfc/backend/config/ConfigService.java + backend/src/main/java/com/cfc/backend/constant/
  • 验收:
    • Phase 1 结束:任何 CF 业务/算法参数只能通过 ConfigService.getConfig("cf.*") 或 CfEarnRuleService 读取,禁止硬编码业务数值(比例、档位、天数、系数、开关、价格)
    • sys_config/products 中 CF 相关参数已清空并归档
    • 每次 L2 修改走审计(W0.3)+ 缓存失效钩子被触发

W0.2 service_config 与 product_config 合并

  • 交付物:Flyway 迁移脚本 + ProductConfigServiceImpl 改造 + 前端配置管理页合并
  • 迁移路径:见 §3.6.6 六步流程
  • 验收:Phase 2 结束时 product_config 表已下线,配置中心只有一个入口(/admin/configs)

W0.3 审计日志统一

  • 交付物:audit_log 表 + AOP 切面(所有 @Admin 修改操作自动落审计,含 CfEarnRuleController.save/toggle 与 AdminConfigController.save)
  • 验收:管理员每次配置/规则改动在后台可追溯(谁、何时、改前、改后),且审计触发时同步调用 CfConfigCache.invalidate()

四、推荐分润设计(N7 核心改造)

4.1 两级销售奖(取代原团队规模阶梯)

4.1.1 直接销售奖(F03a)

维度 规则
基数 直接推荐人的消费 P 点(即被 A 直接推荐的人 B,B 消费产生的 P 点)
比例档位 按 A 的团队(8 层以内)年度累计 P 点 分档
最高比例 70%
累计窗口 滚动一年(按消费时间),累计单位 P 点(非金额)
降级 支持:滚动窗口内 P 点累计下降则降档
落账 A 的 cf_balance

4.1.2 间接销售奖(F03b)

维度 规则
基数 间接推荐人的消费 P 点(即 B 的消费 P 点,由 A 的间接推荐链路上溯)
比例档位 按 A 自身年度累计消费 P 点 分档
最高比例 20%
累计窗口 滚动一年,累计单位 P 点
降级 支持
落账 A 的 cf_balance

4.2 档位配置表设计

cf_direct_sales_tier(直接销售奖档位)

CREATE TABLE IF NOT EXISTS cf_direct_sales_tier (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    tier_name VARCHAR(50) NOT NULL COMMENT '档位名称',
    min_annual_ppoints INT NOT NULL COMMENT '团队8层内年度累计P点下限',
    rate_percent INT NOT NULL COMMENT '分润比例(%)',
    sort_order INT NOT NULL DEFAULT 0,
    remark VARCHAR(255),
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_min (min_annual_ppoints)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='直接销售奖档位(按团队8层内年度P点累计)';

cf_indirect_sales_tier(间接销售奖档位)

CREATE TABLE IF NOT EXISTS cf_indirect_sales_tier (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    tier_name VARCHAR(50) NOT NULL,
    min_self_ppoints INT NOT NULL COMMENT '自身年度累计消费P点下限',
    rate_percent INT NOT NULL COMMENT '分润比例(%)',
    sort_order INT NOT NULL DEFAULT 0,
    remark VARCHAR(255),
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_min (min_self_ppoints)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='间接销售奖档位(按自身年度消费P点累计)';

档位数值由运营在管理端配置,不在此方案硬编码。两表均需 enabled 字段与 cf_earn_rule_history 留痕。

4.3 与旧体系的迁移

旧体系 处理
cf_rate_tier(团队规模阶梯,5 档 5/10/15/20/25%) 废弃:表保留只读,停止引用
commission_dist_log(旧 L1/L2 分佣日志) 保留只读,停止写入
直接销售奖与间接销售奖 按新档位表计算,写入 cf_balance + cf_balance_log

4.4 团队 8 层查询

cf_referral_service.getTeamAnnualPpoints(referrerId, 8):按 referral_tree 取 referrerId 向下 8 层所有成员,统计其最近一年消费产生的 P 点累计。P 点来源:PpointConfigService.getEffectivePpoint() × 实付金额。需新增 P 点消费日志表 ppoint_consumption_log(如不存在)或聚合 orders.ppoint_amount。

4.1 现状双轨

新体系 旧体系
服务 CfCommissionService.distributeToReferrers CommissionDistService.settleTwoLevel(@Deprecated 仍被 5 个订单服务调用)
比例来源 cf_rate_tier 团队规模阶梯(5%/10%/15%/20%/25%) 推荐人财富成长等级 PromotionTierService.getCurrentTier().wealthPercent
基数 商品=有效P点;非商品=金额×serviceRateBps sourcePpoint(商品 P 点)
层级 只返第一个非同家庭引荐人 L1 + L2 各发一次
落库 platform_points_service.earn + cf_transfer_record platform_points_service.earn + commission_dist_log

4.2 合并结论:统一走团队规模阶梯,废弃旧体系

理由:cf_rate_tier 是按团队规模可配置的比例表,与"财富成长等级"(财富积累折算)是两套互斥的比例模型;2026-09-01 设计 D1 已明确"纯团队规模阶梯"为确认决策,旧体系标记废弃却未收口属实现遗漏。

改造动作:

  1. CommissionDistService.settleTwoLevel 全库调用点(套餐/测评/会员/订阅 5 处)改调 CfCommissionService.settle / settleReferrerOnly。
  2. CommissionDistService 保留读接口、写接口标记 410 Gone,commission_dist_log 转只读历史表。
  3. PromotionTierService 的 wealthPercent 从分佣链路移除,仅保留在等级展示/权益场景。
  4. 幂等:cf_rate_tier 阶梯比例变更后按新比例计算,不影响历史流水。

4.3 合并后被取消的途径(不计入 24 条)

原途径 处理
旧 L1 推荐人分润(CommissionDistService.java:152) 并入 F03
旧 L2 推荐人分润(CommissionDistService.java:156) 并入 F03
家庭池商品返积分(ProductOrderService.java:1565) 改投购买人 member,合并到 F01

五、目标数据模型

5.1 新建 cf_balance(成员维度个人 CF 值)

CREATE TABLE IF NOT EXISTS cf_balance (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    member_id BIGINT NOT NULL COMMENT '家庭成员ID(family_members.id)',
    user_id BIGINT COMMENT '关联登录用户ID(可为空,孩子无账号)',
    family_id BIGINT COMMENT '所属家庭ID(冗余,便于聚合)',
    total_earned INT NOT NULL DEFAULT 0 COMMENT '累计获得',
    available INT NOT NULL DEFAULT 0 COMMENT '可用',
    frozen INT NOT NULL DEFAULT 0 COMMENT '提现冻结',
    withdrawn INT NOT NULL DEFAULT 0 COMMENT '已提现',
    exchanged INT NOT NULL DEFAULT 0 COMMENT '已兑换消费',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_member (member_id),
    KEY idx_family (family_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='个人CF值余额(家庭成员维度)';

5.2 新建 cf_balance_log

CREATE TABLE IF NOT EXISTS cf_balance_log (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    member_id BIGINT NOT NULL,
    user_id BIGINT,
    family_id BIGINT,
    type VARCHAR(20) NOT NULL COMMENT 'earn/spend/freeze/unfreeze/withdraw/adjust',
    ref_type VARCHAR(50) NOT NULL COMMENT '见 F02-F24 编码',
    ref_id BIGINT,
    amount INT NOT NULL,
    balance_after INT NOT NULL,
    remark VARCHAR(255),
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    KEY idx_member (member_id),
    KEY idx_family (family_id),
    UNIQUE KEY uk_ref (member_id, ref_type, ref_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='个人CF值流水';

幂等:(member_id, ref_type, ref_id) 唯一键,重复发放直接拦截。

5.3 优惠券家庭化(N3)

  • coupon / user_coupon 增加 family_id(2026-08-31-coupon-family-based-design.md 已设计,本次落地)。
  • 兑换:个人扣 CF(cf_balance.available → exchanged)→ 发券挂 family_id → 家庭内任意成员可用。
  • 退券:CF 返还原兑换成员(非家庭池)。

5.4 消费侧改造

消费场景 旧 新
会员续费抵扣 家庭池 FamilyPlatformPointsService cf_balance(支付人 member)
商品购买抵扣 家庭池 cf_balance(购买人 member)
优惠券兑换 家庭池(exchangeCouponByCf) cf_balance 扣款 + 券挂家庭
提现 家庭池 WithdrawalService cf_balance(个人申请、个人提现)
家庭内部许愿兑换 system_points(deductCfPoints) cf_balance
管理员手动调整 家庭池 adjust cf_balance adjust

六、存量迁移(D2)

一次性脚本,DatabaseInitializer.runMigrations() 幂等执行(新增迁移编号,接续现有最大编号):

  1. family_platform_balance → 家庭 creator 的 family_member → cf_balance(available + frozen 合入 available,withdrawn/exchanged 原样带入),写 cf_balance_log(ref_type='migration_family_pool',ref_id=0,幂等)。
  2. family_members.system_points > 0 → 各成员 cf_balance,写流水(ref_type='migration_system_points')。
  3. user_platform_balance.available + frozen → 用户自己的 family_member 对应 cf_balance,写流水(ref_type='migration_user_wallet')。
  4. 三类流水 ref_type 独立,天然幂等,可重复执行不重复入账。
  5. 迁移后 family_platform_balance / family_members.system_points / user_platform_balance 三表保留为只读历史,写接口标记 410 Gone。

七、派发批次(批 F,待 A 批 3 会话完成后派发)

子批 内容 依赖 验收
F-1 数据层 建 cf_balance + cf_balance_log、cf_earn_rule + cf_earn_rule_history、cf_direct_sales_tier、cf_indirect_sales_tier、cf_earn_daily_limit(会员等级日限映射);coupon/user_coupon 补 family_id;同步 schema.sql;DatabaseInitializer 新增迁移 无 mvn clean compile 通过;迁移幂等
F-2 服务层 新建 CfBalanceService(earn/spend/freeze/unfreeze/withdraw/adjust/getBalance/getLogs,SELECT ... FOR UPDATE 锁行,(member_id,ref_type,ref_id) 幂等)+ earnByRule(memberId, ruleCode, refId, ctx) 统一发放入口(读规则 → 会员等级日限/冷却校验 → 计算数量 → 幂等写入) F-1 单测覆盖 earn/spend/幂等拦截/等级日限
F-3 发放接入 24 条途径全部改投 earnByRule:F02 消费返 CF(1元=100CF)、F03a/F03b 两级销售奖、F04-F06、F07-F24(见 §三);F08/F18 硬编码外置到 cf_earn_rule;F09 报告去重 F-2 每条途径有流水、有 refType、可追溯;F09 第 1 份 50/后续 10
F-4 分佣收口 §四改造:cf_rate_tier 停用;新建直接/间接销售奖档位表并实现 getTeamAnnualPpoints(referrerId, 8) / getSelfAnnualPpoints(referrerId);CommissionDistService 写接口标 410 F-2 两级分润按新档位计算;滚动一年可降级
F-5 消费侧 会员续费/商品抵扣/券兑换/提现/许愿兑换/管理员调整 6 处改投 cf_balance;券挂家庭 F-2 6 场景端到端可走通
F-6 存量迁移 §六脚本,三类迁移流水幂等 F-1 迁移前后总 CF 值守恒校验
F-7 前端 wealth-cf 页改个人 CF 值视图(我的 CF 值 + 家庭共享优惠券);wealth 页五维「富」维度中"财务积累"改读 cf_balance.total_earned(现读家庭池 totalEarned,EnergyService.java:457);管理端新增规则/档位配置页面 F-3/F-5 页面余额与流水一致
F-8 清理 PointsService/PlatformPointsService/FamilyPlatformPointsService 写接口标 410 并注释;清理 system_points "CF值"误导性注释;补《CF 值获取/消耗单一事实源》文档 F-1~F-7 全库无"CF值=家庭池"残留表述

八、待确认点(不阻塞 F-1/F-2)

# 问题 建议
Q1 F10 家庭挑战奖励"每个完成成员各发一次"还是"家庭合计一次"?现实现为每个成员各发,数量可能放大 建议改为家庭合计一次、发给挑战发起人
Q2 F01 商品返积分倍数是否保留 已定:F01 删除,统一走 F02 消费返 CF(N6)
Q3 wealth 页五维「富」维度中"财务积累"(现 5000CF=100 分)改读个人 CF 后,家长维度如何聚合?家庭成员 CF 合计还是仅本人? 建议:家长本人 CF + 家庭其他成员 CF 合计(体现"家庭共同富裕")
Q4 提现是否仍支持(N2 改为个人后,个人 CF 直接提现涉及合规审查) 建议本次保留功能但默认关闭,走管理端开关
Q5 存量迁移后历史流水是否需要在新流水页可查 建议:只在新流水页展示迁移后的流水,历史三表保留独立查询入口
Q6 F01 是否关停(与 F02 重叠) 已定:F01 删除(N6)
Q7 F03 非商品基数是否统一 已定:F03 改为两级销售奖,基数=消费 P 点(N7)
Q8 F06 的 1990 CF 是否已知晓 已定:1 元=100 CF 口径下 1990 恰自洽(N6),兜底常量去除改为公式
Q9 F19 管理员调整是否必须审批+留痕 已定:必须留痕(N11 体系下 admin 调整写入 cf_balance_log + cf_earn_rule_history)
Q10 直接销售奖/间接销售奖的档位数值(如铜/银/金/钻对应多少 P 点、各档比例) 建议运营在管理端配置,档位表已在 §4.2 设计
Q11 FREE 免费会员任务/打卡每日次数上限(N11 未提及) 建议 1 次/天(最低体验)
Q12 PROVIDER 标准会员是否纳入 N11 次数体系(该等级为规划师/专家向) 建议不纳入(非消费端会员),或按 20 次/天对齐 PREMIUM
Q13 分享奖励(F24)数量:推荐注册得多少 CF(N8 未给数值) 建议 20 CF/人,日限 10 次

九、逐条数值核算(新口径,供修正评估)

按 1 元 = 100 CF(N6)新口径核算:

# 途径 示例场景 新数值 问题/备注
F02 消费返 CF ¥199 实付 199 × 100 = 19,900 CF 所有消费都返(N6)
F03a 直接销售奖 团队年度 P 点 1000,直接推荐人消费 P 点 500 按档位表计算(比例待定) 档位待运营配置(Q10)
F03b 间接销售奖 自身年度消费 P 点 800,间接推荐人消费 P 点 300 按档位表计算(比例待定) 同上
F04 商品赠品 配置 按赠品规则 管理端配置
F05 活动签到 配置 按活动配置 管理端配置
F06 菌群打卡返还 项目价 19.9 元 19.9 × 100 = 1,990 CF 与旧兜底值 1990 自洽(N6 修正)
F07 文章答题 3 题全对 3+3 = 6 CF;日限 5 次 N9 已定日限
F08 AI 阅读答题 全对 5 CF 建议日限 3 次
F09 测评建档 第 1 份 50 CF;第 2 份起 10 CF;重复不计 N10 已定
F10 家庭挑战 3 成员各完成 reward_points × 3(待确认改家庭合计) Q1 待确认
F11 邀请里程碑 配置 按里程碑配置 —
F12 成长任务 配置 按任务模板配置 —
F13 分享阅读 默认 5 CF 建议日限 5 次
F14 喝水打卡 每日 5 CF/次;日限:BASIC=3/FAMILY=10/LIFETIME=10/PREMIUM=20 N11 已定按会员等级
F15 饮食打卡 每日 5 CF/次;同上 同上
F16 每日健康打卡 每日 10 CF/次;同上 叠加 F14+F15=20 CF/天(BASIC 档 3 次即 60 CF/天,PREMIUM 档 20 次即 400 CF/天)
F17 挑战赛子任务 配置 reward_cf 需补流水(原 P1)
F18 健康启航付费 按实付 floor(实付/100) × 100 改为与 F02 同口径
F19 管理员调整 任意 正负任意,需密码 需审批+留痕(Q9 已定)
F20 问题域完成 配置 domain.reward_cf_value 管理端配置
F21 关卡通关 配置 gate.reward_points 管理端配置
F22 任务完成 CF task.cf_amount 保留个人;日限按会员等级 N11 已定
F23 成员间转让 转入+X/转出−X 同事务 —
F24 分享奖励(推荐注册) 推荐 1 人注册 建议 20 CF;日限 10 次 N8 新增,数量待定(Q13)

建议初始配置值(待你修正)

规则 建议数量 建议 daily_limit 建议 total_limit 说明
F02 1 元 = 100 CF — — 全消费返
F06 项目价 × 100 7 1 一周项目只发一次
F07 score + (全对?3:0) 5 次(N9) — 按篇去重由 refId 保证
F08 5 3 — 限制每日刷题
F09 第 1 份 50 / 后续 10 3 — 重复报告不计(N10)
F10 保留配置值 1 1 建议改家庭合计一次
F13 5 5 — 每日分享上限 5 篇
F14/F15/F16 5 / 5 / 10 按会员等级(N11) — BASIC=3,FAMILY/LIFETIME=10,PREMIUM=20
F18 floor(实付/100) × 100 1 1 与 F02 同口径
F24 20(建议) 10 — 分享注册奖励(N8)