docs(cf): 打卡获取CF值体系设计（会员等级×打卡内容差异化，D1-D8待确认）

docs/superpowers/plans/2026-10-31-checkin-cf-points-design.md

@@ -0,0 +1,130 @@
+# 打卡获取 CF 值体系设计 · 会员等级 × 打卡内容差异化
+
+> 生成：2026-10-31 · 状态：待确认（D1–D8）· 依据：既有 CF 规则引擎 + 打卡模块现状
+> 范围：用户端「打卡 → CF 值」发放体系设计；不同会员等级、不同打卡内容 CF 值不同
+
+---
+
+## 一、目标与原则
+
+**目标**：把「打卡」纳入 CF 值获取体系，形成「按打卡内容类别差异化定价 × 按会员等级加乘」的激励矩阵，驱动家庭成员养成健康/成长/理财/社交/心理习惯，并可用 CF 兑换权益（如兑换券、商城优惠）。
+
+**原则**：
+1. **复用既有 CF 架构**：CF 已走统一账本（`cf_balance` + `cf_balance_log` 幂等键）+ 规则引擎（`cf_earn_rule`，F02–F24），打卡 CF 只做**增量规则接入**，不另起炉灶。
+2. **内容差异化**：不同打卡内容对应不同基础 CF 值（身/智/富/行/心 五维对齐）。
+3. **等级差异化**：会员等级（非会员 / FAMILY / PREMIUM）乘数不同，等级越高单位打卡 CF 越高。
+4. **防刷可审计**：幂等（每类每日 1 次）+ 每日/每周上限 + 冷却 + 可选审核，全程落 `cf_balance_log` 留痕。
+
+---
+
+## 二、现状盘点（核查结论）
+
+| 模块 | 现状 | 本方案动作 |
+|---|---|---|
+| CF 账本 | `cf_balance`（成员维度 uk_member）+ `cf_balance_log`（幂等键 member_id+type+ref_type+ref_id） | 复用，不改表 |
+| CF 规则引擎 | `cf_earn_rule`（code F02–F24；category=consume/behavior/admin；rule_type=fixed/formula/per_item；amount；params_json；daily_limit_per_member；total_limit_per_member；cooldown_seconds；dedup_ref_type；enabled） | **新增打卡类规则 F25–F33**（category=behavior，rule_type=fixed） |
+| 已有打卡相关规则 | **F05 活动签到CF**（source=activities.platform_points，dedup=activity_checkin）；F07 文章答题（daily 限 5）；F08 AI阅读答题（fixed 5） | 保留，纳入统一口径 |
+| 打卡模块 | `activities.checkin_points`（0=默认）+ `require_checkin_review`；`HealthCheckinService`/`FinanceCheckinService`/`MicroActionService`/`ActivityService`；习惯打卡种子（专注/睡眠，daily）；`emotion_checkin` 表 | 打卡成功后**追加 CF 发放钩子** |
+| 打卡积分现状 | `health_checkin_points=5`、`finance_checkin_points=5`、`activity_checkin_default_points=5`（sys_config）；发的是 **points 积分**（能量体系） | 与 CF 的关系见 **D7** |
+| 会员等级 | `MembershipService.getMemberLevel` → FAMILY / PREMIUM（membership_levels 表） | 等级乘数来源，可扩展 |
+
+---
+
+## 三、核心设计：CF 值矩阵
+
+### 3.1 打卡内容分类（对齐五维，建议 9 类）
+
+| 维度 | 打卡内容 | 规则码（ref_type） | 说明 |
+|---|---|---|---|
+| 身 | 健康打卡 | checkin_health | 健康指标/饮食记录 |
+| 身 | 睡眠打卡 | checkin_sleep | 21:30 前入睡等 |
+| 身 | 运动/专注力 | checkin_focus | 专注时长/运动 |
+| 智 | 文章答题 | article_answer | 每日答题（已有 F07） |
+| 智 | AI 阅读答题 | ai_reading_answer | AI 伴读答题（已有 F08） |
+| 富 | 理财打卡 | checkin_finance | 记账/理财学习 |
+| 行 | 活动签到 | activity_checkin | 线下/线上活动（已有 F05） |
+| 心 | 情绪/冥想打卡 | checkin_emotion | 情绪记录/冥想 |
+| 行 | 微小行动 | checkin_micro | 家庭协作小行动 |
+
+### 3.2 CF 值建议矩阵（内容 × 等级）
+
+> 数值为**建议档**，可整体缩放（D3 待确认）。
+
+| 打卡内容 ref_type | 非会员(0.5×) | FAMILY(1.0×) | PREMIUM(1.5×) | 每日限次 |
+|---|---|---|---|---|
+| checkin_health | 2 | 5 | 8 | 1 |
+| checkin_finance | 2 | 5 | 8 | 1 |
+| checkin_focus | 2 | 4 | 6 | 1 |
+| checkin_sleep | 2 | 4 | 6 | 1 |
+| checkin_emotion | 1 | 3 | 5 | 1 |
+| checkin_micro | 1 | 3 | 5 | 1 |
+| article_answer | 1 | 3 | 5 | 5（N9） |
+| ai_reading_answer | 1 | 3 | 5 | 3 |
+| activity_checkin | 1 | 3 | 5 | 1/场 |
+
+### 3.3 等级乘数
+
+| 等级 | 乘数 | 依据 |
+|---|---|---|
+| 非会员 | 0.5× | 基础激励，可关（0） |
+| FAMILY | 1.0× | 基准 |
+| PREMIUM | 1.5× | 高价值用户加乘 |
+| （未来等级） | 可扩展 | membership_levels 表加行即可 |
+
+---
+
+## 四、机制设计
+
+| 机制 | 设计 | 说明 |
+|---|---|---|
+| 幂等防重 | `cf_balance_log` 唯一键（member_id+type+ref_type+ref_id），ref_type=规则码、ref_id=打卡记录 id | 同一次打卡重复触发只发一次 |
+| 每日限次 | `daily_limit_per_member` 每类 1 次（文章答题 5、AI阅读 3） | 规则引擎已有字段 |
+| 总上限 | `total_limit_per_member`（如每类年上限，可空） | 规则引擎已有字段 |
+| 冷却 | `cooldown_seconds`（如同类 6h） | 规则引擎已有字段 |
+| 连续打卡加成（可选） | streak≥7 → ×1.2；streak≥30 → ×1.5（封顶 1.5） | D4 待确认；用 `activities.streak_days` 已有字段 |
+| 审核 | 默认免审 + 后端校验（打卡时间/时长/频率），高值活动可 `require_checkin_review=1` 人工审 | 复用既有字段 |
+| 留痕 | 全部落 `cf_balance_log`（type=earn，operator_user_id=打卡人） | 审计可回溯 |
+
+---
+
+## 五、技术落地方案
+
+### 5.1 数据（增量，无破坏）
+1. `cf_earn_rule` 新增规则 F25–F33（每类打卡一条）：category=behavior、rule_type=fixed、`dedup_ref_type`=上表 ref_type、`daily_limit_per_member`、`cooldown_seconds`、`params_json`=`{"levels":{"NONE":2,"FAMILY":5,"PREMIUM":8},...}`。
+2. **等级差异化落点**：`cf_earn_rule.amount` 存 FAMILY 基准值；`params_json.levels` 存各等级值，发放时按等级覆盖取额（**不改表结构**，规则引擎已有 params_json 通道）。若后续等级更多，可升级为独立 `cf_earn_rule_level` 表（预留）。
+3. DatabaseInitializer 迁移：新增规则种子（幂等 upsert，参照 F05 模式）。
+
+### 5.2 服务
+- `CfEarnService.earnCheckin(memberId, ruleCode, checkinId, levelCode)`：查规则 → 查成员等级 → `params_json.levels[level]` 取额 → 幂等写 `cf_balance_log` → 更新 `cf_balance`。
+- 打卡服务（Health/Finance/Micro/Activity/emotion）在打卡成功路径**末尾**调用 earnCheckin（try/catch 只 warn，绝不因 CF 发放失败回滚打卡主流程——与 NormalizeIndicatorPipeline/总览重算同纪律）。
+- 等级获取：`membershipService.getMemberLevel(userId)`（FAMILY/PREMIUM，非会员 NONE）。
+
+### 5.3 接口
+- 无新增用户接口：打卡接口已有，仅打卡成功后异步触发 CF。
+- 管理端：可在 CF 规则管理页复用 `cf_earn_rule` CRUD（已有）配置 F25–F33 金额与上限。
+
+### 5.4 边界
+- 不新增 CF 兑换/消费逻辑（已有 `exchange-coupon` 等）。
+- 不改 `cf_balance`/`cf_balance_log` 表结构；不动既有 F02–F24。
+
+---
+
+## 六、关键决策点（待廖总确认）
+
+| # | 决策点 | 建议默认 | 说明 |
+|---|---|---|---|
+| D1 | 打卡内容分类清单 | 9 类（§3.1） | 可增删，类别对齐五维 |
+| D2 | 等级档位与乘数 | 非会员0.5 / FAMILY1.0 / PREMIUM1.5 | 非会员可设 0 关闭 |
+| D3 | CF 值定价矩阵 | §3.2 建议档 | 可整体缩放或逐格调整 |
+| D4 | 连续打卡加成 | 7天×1.2 / 30天×1.5 封顶 | 可关闭 |
+| D5 | 每日总上限 | 每类每日1次，总≤50CF | 防刷 |
+| D6 | 审核 | 免审+后端校验，高值人工 | 复用 require_checkin_review |
+| D7 | **points 与 CF 关系** | **并存**：打卡 points（能量/展示）保留不动，CF 为新增可兑换积分，二者不合并 | 若合并需迁移既有 points 消费链，工作量大 |
+| D8 | 规则接入方式 | **复用 cf_earn_rule 规则引擎**（F25–F33 + params_json.levels） | 不新建独立打卡CF表 |
+
+---
+
+## 七、待确认后的实施路径
+1. 廖总确认 D1–D8（可整体"按默认"或逐项改）。
+2. 方案文档合入 cfclub → 生成任务入池（backend：规则种子+earnCheckin+打卡钩子；如需管理端配置页，补 cfc-web）。
+3. 开发 → 独立核验（幂等/等级矩阵/上限/留痕）→ 合入 cfclub。