通关解锁功能设计（Unlock Gates）
版本： v1.0
日期： 2026-08-10
定位： 产品设计 + 技术方案
理念依据： 《家的算法》书稿（book/ 目录：第2章测量先行 / 第8章最小输入 / 第9章循环执行 / 第10章反馈校验 / 第11章系统升级）
关联文档： docs/需求分析/新用户引导与留存设计方案.md（L1-L5 分层，本方案是其门禁机制的落地）
1. 背景与目标
1.1 产品逻辑（书稿 → 功能）
书稿定义的家庭改变算法：看见 → 最小输入 → 循环 → 反馈 → 传播。其中"看见从测量开始"（第2章）是起点——用户必须先完成一次测量（五维自检），才能"看见"自己的状态（能量沙盘）。
当前现状：能量沙盘（WuxingSandbox）对所有用户可见，无任何前置门禁；五维自检（15题）是首页一张卡片，非必经路径。两者数据源分离（沙盘=能量流水快照，自检分数=独立存储），用户"测不测都能看沙盘"，引导链断裂。
1.2 本方案目标
| 目标 |
说明 |
| 硬门禁 |
未完成五维自检的家庭，任何入口都看不到能量沙盘（家长端/孩子端/发现页/成员详情统一加门） |
| 软引导 |
完成自检后，通过"关卡中心页 + 首页引导条"不断推荐下一步行动（微行动/打卡/复测），不硬锁 |
| 商业转化 |
增值关卡：下单菌群检测/DAN测评（可先于主线完成），解锁增值内容 |
| 可配置 |
cfc-web 管理端完整配置关卡：开关/顺序/奖励/条件，数据驱动不写死 |
1.3 已确认的产品决策（澄清结论）
| 决策点 |
结论 |
| 小测试 |
复用现有五维自检 15 题（self-check.vue），不新建测试 |
| 驱动方式 |
行为驱动（完成动作解锁），非时间驱动 |
| 主线形态 |
单硬关卡（自检→沙盘）+ 后续软引导（推荐不锁死） |
| 门禁范围 |
全家沙盘统一加门（parent-index / child-index / discover / member-detail / member-home-detail） |
| 判据粒度 |
家庭级：家庭内任一成员完成自检即解锁全家 |
| 增值关卡 |
下单菌群检测/DAN测评，可选，可先于主线关卡完成 |
| 后台配置 |
完整配置页：开关/顺序/奖励/条件 |
2. 架构设计
2.1 分层架构
cfc-web 管理端 views/admin/gates.vue（关卡配置 CRUD）
↓ 配置
unlock_gates 表（关卡定义，数据驱动）
↓
GateService（统一判定引擎）
├── SELF_CHECK → 查 five_dimension_self_checks
├── PURCHASE → 查订单表（支付成功）
├── MICRO_ACTION → 查 micro_action_records
└── STREAK_DAYS → 查 streak
↓ 判定结果写入
family_gate_progress 表（家庭通关记录 LOCKED → UNLOCKED）
↓
门禁拦截：/api/energy/sandbox 未通关返回 locked 标记 → 前端渲染锁定态
状态查询：POST /api/unlock/status → 首页引导条 + 关卡中心页
2.2 核心规则
- 主线硬门禁：
is_required=1 AND is_soft=0 的关卡按 sort_order 顺序依赖——必须依次解锁，当前锁定关卡是最小 sort_order 的未通关关卡；其 unlock_target 对应模块对全家锁定。
- 增值关卡：
is_required=0，无前置依赖，任何时刻可完成（满足"关2可在关1前完成"）。
- 软引导：
is_soft=1 的关卡不锁任何功能，仅在关卡中心页/首页引导条展示为"推荐解锁"，点击直达对应功能。
- 判据粒度：所有判定基于
family_id（家庭级），与当前登录人无关。
- 可降级：所有硬门禁关卡均被禁用（
enabled=0）时，门禁系统整体失效，沙盘对全家开放——保证运营可随时撤回。
3. 数据模型
3.1 unlock_gates（关卡定义表）
CREATE TABLE IF NOT EXISTS unlock_gates (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
gate_type VARCHAR(32) NOT NULL COMMENT '关卡类型: SELF_CHECK/PURCHASE/MICRO_ACTION/STREAK_DAYS',
name VARCHAR(50) NOT NULL COMMENT '关卡名称',
description VARCHAR(200) COMMENT '关卡说明',
icon VARCHAR(10) COMMENT '图标emoji',
sort_order INT DEFAULT 0 COMMENT '排序号(后台可调,主线顺序依赖依据)',
enabled TINYINT DEFAULT 1 COMMENT '启用/禁用: 1启用 0禁用',
is_required TINYINT DEFAULT 1 COMMENT '归属: 1主线必过 0增值可选',
is_soft TINYINT DEFAULT 0 COMMENT '形态: 1软引导(不锁功能) 0硬门禁(锁定功能)',
unlock_target VARCHAR(32) COMMENT '解锁目标模块: SANDBOX/MICRO_ACTION_DAILY/BADGE_MILESTONE/TREND_COMPARE/PREMIUM_MODULES',
condition_params VARCHAR(500) COMMENT '条件参数JSON: {"count":1} / {"days":3} / {"product_types":["dan","microbiome"]}',
reward_points INT DEFAULT 0 COMMENT '通关奖励积分',
reward_energy INT DEFAULT 0 COMMENT '通关奖励能量',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_sort (enabled, is_required, is_soft, sort_order)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='通关解锁关卡定义';
3.2 family_gate_progress（家庭通关进度表）
CREATE TABLE IF NOT EXISTS family_gate_progress (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
family_id BIGINT NOT NULL COMMENT '家庭ID',
gate_id BIGINT NOT NULL COMMENT '关卡ID(unlock_gates.id)',
status VARCHAR(16) DEFAULT 'LOCKED' COMMENT '状态: LOCKED/UNLOCKED',
unlocked_by BIGINT COMMENT '解锁人user_id',
unlocked_at DATETIME COMMENT '解锁时间',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_family_gate (family_id, gate_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭关卡通关进度';
说明：进度按家庭维度冗余存储（而非实时计算），一是支付回调等场景可直接写库触发，二是管理端可人工干预（解锁/重置），三是避免每次沙盘请求重复扫描各业务表。
4. GateService 设计
4.1 类结构（service/UnlockGateService.java）
public class UnlockGateService {
// 核心：判定家庭是否已通关某关卡（幂等，可重复调用）
// SELF_CHECK: five_dimension_self_checks 存在 family 内任一 user 的记录，且记录数 >= condition_params.minCount(默认1)
// PURCHASE: 商城商品订单存在支付成功订单，且商品 product_type/domain 命中 condition_params.product_types
// MICRO_ACTION: micro_action_records 中家庭成员的记录数 >= condition_params.count
// STREAK_DAYS: 家庭成员 streak >= condition_params.days
public boolean isGateUnlocked(Long familyId, UnlockGate gate);
// 计算家庭门禁状态：当前锁定的硬门禁关卡（无则返回 null）
public UnlockGate getCurrentLockGate(Long familyId);
// 重算家庭全部关卡进度并写 family_gate_progress（自检提交/支付回调后调用）
public void refreshFamilyGates(Long familyId);
// 查询家庭关卡全景（status 接口数据源）
public UnlockStatusDTO getFamilyUnlockStatus(Long familyId);
}
4.2 判定逻辑细节
| 类型 |
判定依据 |
备注 |
SELF_CHECK |
five_dimension_self_checks 存在该 family 内任一 user_id 的记录，且记录数 ≥ minCount（默认 1） |
minCount 来自 condition_params；复测关卡设 {"minCount":2} |
PURCHASE |
商城商品订单表（ProductOrderController 对应订单表）存在支付成功的订单，且商品 domain/product_type 命中 condition_params.product_types（多类型 OR 匹配） |
DAN测评/菌群检测以商城商品形式购买时走此判定；若 DAN测评走独立流程（dan-assessment/record），在实现计划中确认其订单接入点 |
MICRO_ACTION |
micro_action_records 家庭内记录数 ≥ count |
按 family 聚合 |
STREAK_DAYS |
家庭成员最大 streak ≥ days |
复用现有 streak 计算 |
4.3 触发钩子
| 触发点 |
位置 |
动作 |
| 登录成功 |
AuthController 登录/角色切换 |
unlockGateService.refreshFamilyGates(familyId)（兜底：老用户已自检但进度表未初始化时自动补齐；同时保证进度新鲜度） |
| 自检提交成功 |
FiveDimensionSelfCheckController.submit() |
unlockGateService.refreshFamilyGates(familyId) |
| 支付成功回调 |
PaymentController.wechat/callback、alipay/callback、wechat/v3-notify |
refreshFamilyGates(familyId) |
| 管理端人工干预 |
AdminUnlockGateController |
重置/手动解锁某家庭某关卡 |
读路径：/api/unlock/status 与 /api/energy/sandbox 只读 family_gate_progress 冗余表（不实时扫描业务表）；refreshFamilyGates 由上述钩子触发重算写库，保证进度表与业务数据一致。存量家庭首次登录即被登录钩子预置，无需额外迁移。
5. 接口设计
5.1 用户端
POST /api/unlock/status
入参: 无（@RequestAttribute userId 取家庭）
出参: {
currentLockGate: {id, name, description, icon, gateType} | null, // 当前硬门禁(家庭级)
gates: [{id, gateType, name, description, icon, isRequired, isSoft,
status: LOCKED|UNLOCKED|CURRENT, rewardPoints, rewardEnergy}],
sandboxLocked: true/false // 便捷标记，前端四处沙盘共用
}
说明: 未加入家庭时返回 sandboxLocked=false（不拦截，保持现有 noFamily 逻辑）
POST /api/energy/sandbox （改造）
现有: 直接返回 EnergySandboxDTO
改造后: 未通过当前硬门禁时返回:
{ locked: true, gate: {id, name, description, icon}, code: 0 }
通过时: 原逻辑 + sandbox 数据
说明: 保持 code=0（非业务错误），前端以 data.locked 分支渲染锁定态；
门禁判定为家庭级，孩子端/发现页/成员详情调用同一接口自动生效
5.2 管理端
POST /api/admin/unlock-gates/list — 关卡列表
POST /api/admin/unlock-gates/save — 新增/编辑关卡
POST /api/admin/unlock-gates/delete — 删除关卡（同时清理 family_gate_progress）
POST /api/admin/unlock-gates/sort — 批量排序
POST /api/admin/unlock-gates/toggle — 启停
POST /api/admin/unlock-gates/reset-family — 重置某家庭进度（运营干预）
接口统一 @PostMapping，遵循项目规范。
6. 前端设计（小程序）
6.1 锁定态组件 components/gate-lock.vue
- 新组件，props:
gate（当前锁定关卡信息）
- 视觉：锁图标 + 关卡名 + 引导文案（*"完成五维自检，解锁能量沙盘"*）+ 主按钮（跳转对应功能：自检→
pages/family/self-check.vue）
- 替换位置（原
v-if="sandboxData" / error-state 逻辑）：
| 页面 |
现状 |
改造 |
pages/home-pages/parent-index.vue |
v-if="sandboxData" 渲染沙盘 |
门禁状态 sandboxLocked → 渲染 gate-lock；未加入家庭保持现状 |
pages/home-pages/child-index.vue |
渲染沙盘 |
同上 |
pages/home-pages/member-home-detail.vue |
渲染沙盘 |
同上 |
pages/member-detail/member-detail.vue |
渲染沙盘 |
同上 |
pages/discover/index.vue |
渲染沙盘 |
同上 |
6.2 首页引导条 components/gate-guide-bar.vue
- 家长首页
parent-index.vue 顶部（自检卡附近）展示："🔓 解锁进度 1/4 · 完成五维自检解锁能量沙盘 →"
- 数据源：
/api/unlock/status 的 gates 列表（已解锁数/主线总数）
- 全解锁后自动消失（避免打扰老用户）
- 点击 → 关卡中心页
6.3 关卡中心页 pages/profile-extra/gates.vue
- 分区展示：
- 主线关卡：锁态（🔒 灰）/ 当前（进行中高亮）/ 已解锁（✅）
- 增值关卡：购买入口（跳商城对应商品/测评），已购显示已解锁
- 软引导：推荐卡片（微行动/连续打卡/复测），点击直达
- 每关展示：图标+名称+说明+奖励（+N 积分 · +N 能量）
- 新页面需在
pages.json 注册（分包 profile-extra）
6.4 沙盘叠加自检分数
- 解锁后沙盘数据来源不变（energy/sandbox），新增叠加：自检结果页分数作为雷达叠加层（复用 self-check-result 的雷达图数据）
- 实现位置：
WuxingSandbox 组件扩展可选 props（selfCheckScores），首版仅家长端首页叠加，其余位置保持纯能量快照
7. 管理端设计（cfc-web）
7.1 页面 views/admin/gates.vue
- 路由：
/admin/gates（菜单"系统管理"下"关卡配置"）
- 表格列：排序 | 图标 | 名称 | 类型 | 归属(主线/增值) | 形态(硬门禁/软引导) | 解锁目标 | 条件 | 奖励 | 状态 | 操作
- 操作：编辑（弹窗表单）/ 启停开关 / 删除 / 上下移排序（或数字排序）
- 表单字段（对应 unlock_gates）：
- 类型下拉：五维自检 / 购买商品 / 微行动次数 / 连续打卡天数
- 条件参数按类型动态渲染：SELF_CHECK 无参数；PURCHASE 选商品类型（DAN测评/菌群检测/自定义 product_types 输入）；MICRO_ACTION 填次数；STREAK_DAYS 填天数
- 奖励：积分 + 能量 两个数字输入
- 归属/形态：单选
- 额外区块：家庭进度管理（输入 family_id 查看/重置该家庭关卡进度，运营干预）
7.2 后端 controller/admin/AdminUnlockGateController.java
@RequestMapping("/api/admin/unlock-gates")，@PostMapping 各操作- 校验：同名关卡、sort_order 唯一、condition_params 按类型解析失败报错
- 删除关卡时级联清理 family_gate_progress 对应记录
8. 首版默认关卡配置（DatabaseInitializer 种子数据）
| 关卡 |
gate_type |
归属 |
软/硬 |
unlock_target |
条件 |
奖励 |
| 五维自检 |
SELF_CHECK |
主线 |
硬门禁 |
SANDBOX |
完成1次 |
+60积分 +10能量 |
| 首次微行动 |
MICRO_ACTION |
主线 |
软引导 |
MICRO_ACTION_DAILY |
count≥1 |
+50积分 +5能量 |
| 连续打卡3天 |
STREAK_DAYS |
主线 |
软引导 |
BADGE_MILESTONE |
days≥3 |
+30积分 +5能量 |
| 复测对比 |
SELF_CHECK |
主线 |
软引导 |
TREND_COMPARE |
minCount=2 |
+60积分 +10能量 |
| 菌群检测/DAN测评 |
PURCHASE |
增值 |
硬门禁(增值) |
PREMIUM_MODULES |
任一支付成功 |
+100积分 +20能量 |
种子数据写入方式：DatabaseInitializer.runMigrations() 迁移（参考项目迁移工作流，编号递增、幂等），管理端可随时增删改。
9. 风险与注意事项
| 风险 |
缓解 |
| 强制自检导致新用户流失 |
自检入口直达 + 首页引导条强调"5分钟"；门禁仅锁沙盘，其余功能（任务/心愿/成长）不受影响 |
| 老用户（未自检）突然看不到沙盘 |
全部硬门禁关闭可整体失效（运营开关）；上线前对存量家庭数据评估，必要时种子迁移按"有自检记录即解锁"批量预置 |
| 增值关卡商品匹配口径不清 |
condition_params.product_types 用商品 domain/product_type 精确匹配；管理端下拉选择避免手输 |
| 门禁判定性能 |
判定结果冗余到 family_gate_progress（判定后写库），沙盘接口只读进度表，不重复扫描业务表 |
| 孩子端首次进入无家庭 |
保持现有 noFamily 逻辑，不套门禁（家庭级判定前置条件：有 family_id） |
| 多角色用户（parent+teacher） |
判据基于 family_id 与 family 内任一用户的自检记录，不依赖角色，天然兼容 |
10. 测试策略（tests/AGENTS.md 分层）
| 层 |
内容 |
| 单元 |
UnlockGateService 四类型判定（SELF_CHECK/PURCHASE/MICRO_ACTION/STREAK_DAYS）+ 边界（count=0、无记录、多记录）；getCurrentLockGate 顺序依赖；禁用关卡降级 |
| 集成 |
/api/unlock/status 返回结构；/api/energy/sandbox 未通关返回 locked；自检 submit 后 refresh 生效；支付回调后 PURCHASE 关卡解锁 |
| 前端 |
gate-lock 组件渲染（锁定态/解锁态）；gate-guide-bar 进度计算与消失条件；关卡中心页三区展示 |
| E2E |
新用户注册→首页沙盘锁定→完成自检→沙盘解锁→关卡中心显示已解锁 |
11. 实施范围与工作量估算
| 模块 |
内容 |
估算 |
| 后端 |
2 张表迁移 + UnlockGateService + UnlockController + AdminUnlockGateController + sandbox 改造 + 2 处钩子 + 种子数据 |
3-4 天 |
| 小程序 |
gate-lock 组件 + gate-guide-bar + gates.vue 关卡中心 + 4 处沙盘替换 + 自检分数叠加 |
3-4 天 |
| 管理端 |
gates.vue 配置页 + 家庭进度管理 |
1-2 天 |
| 测试 |
单测/集成/前端/E2E |
1-2 天 |
里程碑验收：
- 后端完成：
/api/unlock/status + sandbox 门禁可用（Postman 验证 locked 分支）
- 前端完成：新用户动线"注册→沙盘锁定→自检→解锁"全链路走通
- 管理端完成：新增关卡/调整顺序/禁用关卡实时生效
