日期:2026-10-24 状态:待派发(批 F) 前置文档:
2026-08-12-platform-points-family-pool-design.md、2026-09-01-cf-commission-redesign.md本方案取代上述两份文档中与"CF 值归属维度"相关的全部结论
| # | 新口径 | 取代的旧口径 |
|---|---|---|
| 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 次 |
| # | 决策 | 结论 |
|---|---|---|
| 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 值 —— 获得来源与可见余额不在同一账本。
合并后共 24 条有效获取途径(原 23 条:F01 删除,F02/F03 重写,新增 F24,F06 修正,F07/F09/F14-F16/F22 按会员等级分级)。
| # | 途径 | 数量规则 | 参数来源 | 落账 |
|---|---|---|---|---|
| 删除(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 |
| # | 途径 | 数量规则 | 参数来源 | 代码出处 |
|---|---|---|---|---|
| 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 |
— |
| # | 途径 | 数量规则 | 参数来源 | 代码出处 |
|---|---|---|---|---|
| F20 | 问题域全部任务完成奖励 | domain.reward_cf_value |
problem_domain.reward_cf_value(管理端配置) |
ProblemCompletionService.java:127 |
| F21 | 关卡通关奖励 | gate.reward_points |
unlock_gate.reward_points(管理端配置) |
UnlockGateService.java:300 |
| # | 途径 | 数量规则 | 参数来源 | 代码出处 |
|---|---|---|---|---|
| F22 | 任务完成 CF | task.cf_amount(现双发个人+家庭池,取消家庭池那条) |
任务配置 | TaskService.java:998(保留)/ :1001(删除) |
| F23 | 成员间转让(收款方) | 转入方 +金额,转出方 -金额,同一事务 | 转账金额 | CfTransferController.java:63 |
| 会员等级 | 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_tierJSON 字段或单独表cf_earn_daily_limit(rule_code, level_code, daily_limit)。
F08、F18 两处 CF 数量为硬编码,需迁到 cf_earn_rule(F07/F14-F16 已在规则表配置,F09 已公式化,F13 已 sys_config)。F10 家庭挑战按人各发或家庭合计待确认。
总原则:发放收口到单一入口。24 条途径全部改调 CfBalanceService.earnByRule(memberId, ruleCode, refId, ctx),代码中不再保留任何 CF 数量常量——否则"随时调整"落不了地。
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值获取规则(运营可配置)';
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值规则变更历史';
CfBalanceService.earnByRule执行顺序(任一步失败即不发):
code + 当前时间落在 effective_from/to 内)→ enabled=0 直接返回daily_limit_per_member(按日聚合当日流水)、total_limit_per_member(按 total_earned 或累计)、cooldown_seconds(查最近一笔流水时间)fixed 取 amount;formula 用 params_json 求值(公式白名单函数:floor/amt/qty/cfg);per_item 由 ctx 提供逐人数量(member_id, dedup_ref_type, ref_id) 唯一键)+ 写 cf_balance_log硬约束:
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)。
AdminCfEarnRuleController:/list(分页)//save(新建+编辑)//toggle(开关)//history(变更历史)cfc-web 新增 views/admin/CfEarnRuleManage.vue:规则列表 + 开关 + 编辑抽屉(名称/类型/数量或公式/参数/三道闸/生效期)+ 变更历史抽屉见 §三 各条「参数来源」列,初始值按现状录入,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,禁止散落常量或裸改库。
核心原则(本次调整):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 |
新增配置的标准动作:
service_config 或 cf_earn_rule/admin/configs UI 或 seed SQL(Flyway 初始化),修改必须走审计(W0.3)(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)缓存与变更
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 |
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 | 前端配置管理页只保留一个"配置中心"入口 | 前端 |
service_config 或 cf_earn_rule.params_json)cf.{module}.{key} 命名规则?/admin/configs 或 /admin/cf-earn-rules)?CfConfigCache.invalidate 覆盖到了吗)?两套配置现状(合并背景):
ProductConfigItem(product 侧):与 product 服务绑定的价格/参数/开关ServiceConfigItem(service 侧):与 cf 服务绑定的价格/参数/开关service_config 一张表,product 侧只留 product_key 关联键。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_configOrderConstants.java / AdminConstants.java(仅订单/锁/超时等 CF 无关的技术参数)cfc-backend/src/main/resources/db/migration/backend/src/main/java/com/cfc/backend/config/ConfigService.java + backend/src/main/java/com/cfc/backend/constant/ConfigService.getConfig("cf.*") 或 CfEarnRuleService 读取,禁止硬编码业务数值(比例、档位、天数、系数、开关、价格)sys_config/products 中 CF 相关参数已清空并归档service_config 与 product_config 合并ProductConfigServiceImpl 改造 + 前端配置管理页合并product_config 表已下线,配置中心只有一个入口(/admin/configs)audit_log 表 + AOP 切面(所有 @Admin 修改操作自动落审计,含 CfEarnRuleController.save/toggle 与 AdminConfigController.save)CfConfigCache.invalidate()| 维度 | 规则 |
|---|---|
| 基数 | 直接推荐人的消费 P 点(即被 A 直接推荐的人 B,B 消费产生的 P 点) |
| 比例档位 | 按 A 的团队(8 层以内)年度累计 P 点 分档 |
| 最高比例 | 70% |
| 累计窗口 | 滚动一年(按消费时间),累计单位 P 点(非金额) |
| 降级 | 支持:滚动窗口内 P 点累计下降则降档 |
| 落账 | A 的 cf_balance |
| 维度 | 规则 |
|---|---|
| 基数 | 间接推荐人的消费 P 点(即 B 的消费 P 点,由 A 的间接推荐链路上溯) |
| 比例档位 | 按 A 自身年度累计消费 P 点 分档 |
| 最高比例 | 20% |
| 累计窗口 | 滚动一年,累计单位 P 点 |
| 降级 | 支持 |
| 落账 | A 的 cf_balance |
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留痕。
| 旧体系 | 处理 |
|---|---|
cf_rate_tier(团队规模阶梯,5 档 5/10/15/20/25%) |
废弃:表保留只读,停止引用 |
commission_dist_log(旧 L1/L2 分佣日志) |
保留只读,停止写入 |
| 直接销售奖与间接销售奖 | 按新档位表计算,写入 cf_balance + cf_balance_log |
cf_referral_service.getTeamAnnualPpoints(referrerId, 8):按 referral_tree 取 referrerId 向下 8 层所有成员,统计其最近一年消费产生的 P 点累计。P 点来源:PpointConfigService.getEffectivePpoint() × 实付金额。需新增 P 点消费日志表 ppoint_consumption_log(如不存在)或聚合 orders.ppoint_amount。
| 新体系 | 旧体系 | |
|---|---|---|
| 服务 | 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 |
理由:cf_rate_tier 是按团队规模可配置的比例表,与"财富成长等级"(财富积累折算)是两套互斥的比例模型;2026-09-01 设计 D1 已明确"纯团队规模阶梯"为确认决策,旧体系标记废弃却未收口属实现遗漏。
改造动作:
CommissionDistService.settleTwoLevel 全库调用点(套餐/测评/会员/订阅 5 处)改调 CfCommissionService.settle / settleReferrerOnly。CommissionDistService 保留读接口、写接口标记 410 Gone,commission_dist_log 转只读历史表。PromotionTierService 的 wealthPercent 从分佣链路移除,仅保留在等级展示/权益场景。cf_rate_tier 阶梯比例变更后按新比例计算,不影响历史流水。| 原途径 | 处理 |
|---|---|
旧 L1 推荐人分润(CommissionDistService.java:152) |
并入 F03 |
旧 L2 推荐人分润(CommissionDistService.java:156) |
并入 F03 |
家庭池商品返积分(ProductOrderService.java:1565) |
改投购买人 member,合并到 F01 |
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值余额(家庭成员维度)';
cf_balance_logCREATE 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) 唯一键,重复发放直接拦截。
coupon / user_coupon 增加 family_id(2026-08-31-coupon-family-based-design.md 已设计,本次落地)。cf_balance.available → exchanged)→ 发券挂 family_id → 家庭内任意成员可用。| 消费场景 | 旧 | 新 |
|---|---|---|
| 会员续费抵扣 | 家庭池 FamilyPlatformPointsService |
cf_balance(支付人 member) |
| 商品购买抵扣 | 家庭池 | cf_balance(购买人 member) |
| 优惠券兑换 | 家庭池(exchangeCouponByCf) |
cf_balance 扣款 + 券挂家庭 |
| 提现 | 家庭池 WithdrawalService |
cf_balance(个人申请、个人提现) |
| 家庭内部许愿兑换 | system_points(deductCfPoints) |
cf_balance |
| 管理员手动调整 | 家庭池 adjust |
cf_balance adjust |
一次性脚本,DatabaseInitializer.runMigrations() 幂等执行(新增迁移编号,接续现有最大编号):
family_platform_balance → 家庭 creator 的 family_member → cf_balance(available + frozen 合入 available,withdrawn/exchanged 原样带入),写 cf_balance_log(ref_type='migration_family_pool',ref_id=0,幂等)。family_members.system_points > 0 → 各成员 cf_balance,写流水(ref_type='migration_system_points')。user_platform_balance.available + frozen → 用户自己的 family_member 对应 cf_balance,写流水(ref_type='migration_user_wallet')。ref_type 独立,天然幂等,可重复执行不重复入账。family_platform_balance / family_members.system_points / user_platform_balance 三表保留为只读历史,写接口标记 410 Gone。| 子批 | 内容 | 依赖 | 验收 |
|---|---|---|---|
| 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值=家庭池"残留表述 |
| # | 问题 | 建议 |
|---|---|---|
| Q1 | F10 家庭挑战奖励"每个完成成员各发一次"还是"家庭合计一次"?现实现为每个成员各发,数量可能放大 | 建议改为家庭合计一次、发给挑战发起人 |
| 已定:F01 删除,统一走 F02 消费返 CF(N6) | ||
| Q3 | wealth 页五维「富」维度中"财务积累"(现 5000CF=100 分)改读个人 CF 后,家长维度如何聚合?家庭成员 CF 合计还是仅本人? |
建议:家长本人 CF + 家庭其他成员 CF 合计(体现"家庭共同富裕") |
| Q4 | 提现是否仍支持(N2 改为个人后,个人 CF 直接提现涉及合规审查) | 建议本次保留功能但默认关闭,走管理端开关 |
| Q5 | 存量迁移后历史流水是否需要在新流水页可查 | 建议:只在新流水页展示迁移后的流水,历史三表保留独立查询入口 |
| 已定:F01 删除(N6) | ||
| 已定:F03 改为两级销售奖,基数=消费 P 点(N7) | ||
| 已定:1 元=100 CF 口径下 1990 恰自洽(N6),兜底常量去除改为公式 | ||
已定:必须留痕(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) |