# 通关解锁功能设计（Unlock Gates）

**版本：** v2.0
**日期：** 2026-08-10
**定位：** 产品设计 + 技术方案
**理念依据：** 《家的算法》书稿（`book/` 目录：第2章测量先行 / 第8章最小输入 / 第9章循环执行 / 第10章反馈校验 / 第11章系统升级）
**关联文档：** `docs/需求分析/新用户引导与留存设计方案.md`（L1-L5 分层，本方案是其门禁机制的落地）

---

## 1. 背景与目标

### 1.1 产品逻辑（书稿 → 功能）

书稿定义的家庭改变算法：**看见 → 最小输入 → 循环 → 反馈 → 传播**。其中"看见从测量开始"（第2章）是起点——用户必须先完成一次测量（五维自检），才能"看见"自己的状态（能量沙盘）。

当前现状：能量沙盘（`WuxingSandbox`）对所有用户可见，无任何前置门禁；五维自检（15题）是首页一张卡片，非必经路径。两者数据源分离（沙盘=能量流水快照，自检分数=独立存储），用户"测不测都能看沙盘"，引导链断裂。

### 1.2 本方案目标

| 目标 | 说明 |
|------|------|
| 分粒度门禁 | 沙盘分**个人/全家**两层，各由独立关卡解锁：自检→个人沙盘；邀请家人→全家沙盘 |
| 递进引导 | 三关递进：看见自己 → 看见全家 → 开始行动（对孩子），步步引导不跳步 |
| 每关有奖 | 每完成一关即时获得积分+能量奖励，强化正反馈循环 |
| 软引导 | 完成主线后，通过"关卡中心页 + 首页引导条"推荐下一步行动（微行动/打卡/复测/购物/上传报告/加入会员），不硬锁 |
| 商业转化 | 增值关卡：下单购物、加入会员、上传报告（可先于主线完成），解锁增值内容，每关同样有奖 |
| 可配置 | cfc-web 管理端完整配置关卡：开关/顺序/奖励/条件，数据驱动不写死 |

### 1.3 已确认的产品决策（澄清结论）

| 决策点 | 结论 |
|--------|------|
| 小测试 | 复用现有五维自检 15 题（`self-check.vue`），不新建测试 |
| 驱动方式 | 行为驱动（完成动作解锁），非时间驱动 |
| 主线形态 | **三关递进硬门禁**：自检→邀请家人→创建家人，依次解锁个人沙盘→全家沙盘→孩子微行动 |
| 沙盘UI | 沙盘增加**个人/全家切换开关**，默认显示个人；全家视角需邀请家人关卡解锁 |
| 判据粒度 | 自检判据为**个人级**（解锁个人沙盘）；邀请/创建家人判据为**家庭级** |
| 每关奖励 | 每完成一关（主线/增值/软引导）均给予积分+能量奖励，即时到账 |
| 增值关卡 | 可扩展多种类型：下单购物、加入会员、上传健康报告，各关独立判定，可先于主线完成 |
| 后台配置 | 完整配置页：开关/顺序/奖励/条件 |

---

## 2. 架构设计

### 2.1 分层架构

```
cfc-web 管理端 views/admin/gates.vue（关卡配置 CRUD）
        ↓ 配置
unlock_gates 表（关卡定义，数据驱动）
        ↓
GateService（统一判定引擎）
        ├── SELF_CHECK            → 查 five_dimension_self_checks + user.family_id
        ├── INVITE_FAMILY         → 查 user 表（family_id 成员数 ≥ 2）
        ├── CREATE_FAMILY_MEMBER  → 查 family_member 表（family_id 成员数 ≥ 1）
        ├── PURCHASE              → 查订单表（支付成功）
        ├── MEMBERSHIP            → 查 family_memberships / member_subscription
        ├── REPORT_UPLOAD         → 查 health_reports（family_id 有记录）
        ├── MICRO_ACTION          → 查 micro_action_records
        └── STREAK_DAYS           → 查 streak
        ↓ 判定结果写入
family_gate_progress 表（家庭通关记录 LOCKED → UNLOCKED）
        ↓
门禁拦截：
  /api/energy/sandbox?view=personal   → 未过 SELF_CHECK 返回 locked
  /api/energy/sandbox?view=family     → 未过 INVITE_FAMILY 返回 locked
  /api/unlock/status                  → 首页引导条 + 关卡中心页
```

### 2.2 核心规则

1. **主线硬门禁**：`is_required=1 AND is_soft=0` 的关卡按 `sort_order` **顺序依赖**——必须依次解锁：
   - 关1（自检）→ 解锁个人沙盘
   - 关2（邀请家人）→ 解锁全家沙盘切换
   - 关3（创建家人）→ 解锁孩子微行动
2. **判据粒度分两层**：
   - 自检关卡：基于**个人**（当前登录用户完成自检即解锁个人沙盘，不依赖家庭其他成员）
   - 邀请/创建家人关卡：基于**家庭级**（家庭内任一成员完成即解锁）
3. **增值/商业关卡**：`is_required=0`（或单独标记为增值），**无前置依赖**，任何时刻可完成。可包含：下单购物（PURCHASE）、加入会员（MEMBERSHIP）、上传报告（REPORT_UPLOAD）。
4. **软引导**：`is_soft=1` 的关卡不锁任何功能，仅在关卡中心页/首页引导条展示为"推荐解锁"。
5. **每关有奖**：所有关卡（主线/增值/软引导）通关即发放 `reward_points` + `reward_energy`，通过通用奖励发放服务即时到账。
6. **可降级**：所有硬门禁关卡均被禁用（`enabled=0`）时，门禁系统整体失效，沙盘对全员开放。

---

## 3. 数据模型

### 3.1 unlock_gates（关卡定义表）

```sql
CREATE TABLE IF NOT EXISTS unlock_gates (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    gate_type VARCHAR(32) NOT NULL COMMENT '关卡类型: SELF_CHECK/INVITE_FAMILY/CREATE_FAMILY_MEMBER/PURCHASE/MEMBERSHIP/REPORT_UPLOAD/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 '解锁目标模块: PERSONAL_SANDBOX/FAMILY_SANDBOX/CHILD_MICRO_ACTION/PREMIUM_MODULES/MICRO_ACTION_DAILY/BADGE_MILESTONE/TREND_COMPARE/HEALTH_INSIGHTS',
    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（家庭通关进度表）

```sql
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`）

```java
public class UnlockGateService {
    // 核心：判定某用户是否已通关某关卡
    // SELF_CHECK:          five_dimension_self_checks 存在该 user_id 的记录，且记录数 ≥ minCount
    // INVITE_FAMILY:       user 表该 family_id 成员数 ≥ 2（用户本人 + 至少1位家人）
    // CREATE_FAMILY_MEMBER: family_member 表该 family_id 记录数 ≥ 1
    // PURCHASE:            商城商品订单存在支付成功订单，且商品类型命中 condition_params
    // MEMBERSHIP:          family_memberships 或 member_subscription 存在该 family_id 的有效订阅
    // REPORT_UPLOAD:       health_reports 存在该 family_id 的记录，且记录数 ≥ minCount
    // MICRO_ACTION:        micro_action_records 中家庭成员的记录数 ≥ count
    // STREAK_DAYS:         家庭成员 max(streakDays) ≥ days
    public boolean isGateUnlocked(Long familyId, UnlockGate gate);

    // 计算当前用户个人沙盘门禁状态（基于个人判据）
    public UnlockGate getCurrentPersonalLockGate(Long userId);

    // 计算家庭门禁状态：当前锁定的家庭级硬门禁关卡
    public UnlockGate getCurrentFamilyLockGate(Long familyId);

    // 重算家庭全部关卡进度并写 family_gate_progress
    public void refreshFamilyGates(Long familyId);

    // 查询用户关卡全景（status 接口数据源）
    public UnlockStatusDTO getUserUnlockStatus(Long userId, Long familyId);

    // 发放关卡通关奖励
    public void grantGateRewards(Long familyId, Long gateId, Long unlockedByUserId);
}
```

### 4.2 判定逻辑细节

| 类型 | 判据粒度 | 判定依据 | 备注 |
|------|---------|---------|------|
| `SELF_CHECK` | **个人级** | `five_dimension_self_checks` 存在该 user_id 的记录，且记录数 ≥ minCount（默认 1） | 与 family_id 无关，仅看当前用户。minCount 来自 condition_params；复测设 `{"minCount":2}` |
| `INVITE_FAMILY` | 家庭级 | `user` 表该 family_id 的成员数 ≥ 2（用户本人 + 至少1位被邀请的家人） |  |
| `CREATE_FAMILY_MEMBER` | 家庭级 | `family_member` 表该 family_id 的记录数 ≥ 1 | 至少创建了一个孩子成员 |
| `PURCHASE` | 家庭级 | 商城商品订单表存在支付成功的订单，且商品 `domain`/`product_type` 命中 condition_params.product_types | 通用购物关卡，不限于特定商品类型 |
| `MEMBERSHIP` | 家庭级 | `family_memberships` 或 `member_subscription` 存在该 family_id 的有效（已支付/激活）订阅记录 | 含付费会员、试用会员等 |
| `REPORT_UPLOAD` | 家庭级 | `health_reports` 存在该 family_id 的记录，且记录数 ≥ minCount（默认 1） | health_reports 已有 family_id 字段，直接查询 |
| `MICRO_ACTION` | 家庭级 | `micro_action_records` 家庭内记录数 ≥ count | 按 family_id 聚合（需通过 family_member 关联） |
| `STREAK_DAYS` | 家庭级 | 家庭成员最大 streak ≥ days | 取 FamilyMember.streakDays 最大值 |

### 4.3 触发钩子

| 触发点 | 位置 | 动作 |
|--------|------|------|
| 登录成功 | `AuthController` 登录/角色切换 | `unlockGateService.refreshFamilyGates(familyId)` |
| 自检提交成功 | `FiveDimensionSelfCheckController.submit()` | `refreshFamilyGates(familyId)` + 发放奖励 |
| 邀请家人成功 | 家庭邀请/加入回调 | `refreshFamilyGates(familyId)` + 发放奖励 |
| 创建家人成功 | 创建家庭成员回调 | `refreshFamilyGates(familyId)` + 发放奖励 |
| 支付成功回调 | 商城支付回调 | `refreshFamilyGates(familyId)` + 发放奖励（PURCHASE 关卡） |
| 会员订阅成功 | 会员支付/激活回调 | `refreshFamilyGates(familyId)` + 发放奖励（MEMBERSHIP 关卡） |
| 报告上传成功 | `HealthReportController.upload/confirm` | `refreshFamilyGates(familyId)` + 发放奖励（REPORT_UPLOAD 关卡） |
| 管理端人工干预 | `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}],
  personalSandboxLocked: true/false,    // 个人沙盘是否锁定
  familySandboxLocked: true/false,      // 全家沙盘是否锁定（含邀请/创建家人关卡）
  childMicroActionLocked: true/false    // 孩子微行动是否锁定
}
```

```
POST /api/energy/sandbox?view=personal|family
入参: view 参数（默认 personal）
逻辑:
  view=personal:
    - SELF_CHECK 未通关 → 返回 { locked: true, gate: {id, name, description, icon} }
    - 已通关 → 返回当前用户个人五维数据
  view=family:
    - INVITE_FAMILY 未通关 → 返回 { locked: true, gate: {id, name, description, icon} }
    - 已通关 → 返回家庭所有成员聚合五维数据
出参(个人):
  {
    locked: false,
    view: "personal",
    personalData: { bodyScore, mindScore, wisdomScore, actionScore, wealthScore, ... },
    familyUnlocked: true/false,   // 全家视角是否可用（前端据此决定是否显示切换开关）
    familyGate: {id, name} | null  // 未解锁时返回当前锁定关卡信息
  }
出参(全家):
  {
    locked: false,
    view: "family",
    familyData: { members: [...], overallScore, ... }
  }
```

### 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 WuxingSandbox 组件改造：个人/全家切换开关

**改造点：**

| 项目 | 说明 |
|------|------|
| 新增 props | `viewMode: 'personal'\|'family'` （默认 'personal'） |
| 新增 props | `familyUnlocked: boolean`（是否显示切换开关） |
| 新增 props | `personalData` / `familyData`（两套数据源） |
| 切换开关 | 沙盘顶部加 `switch` 组件，`familyUnlocked=false` 时隐藏 |
| 默认显示 | 个人数据（登录用户自己的五维） |
| 全家模式 | 切换后显示家庭所有成员聚合数据（雷达图重叠显示各成员） |

**视觉：**
```
┌──────────────────────────────────┐
│  👤 个人  │  👨‍👩‍👧‍👦 全家          │ ← 开关（仅 familyUnlocked 时显示）
│                                  │
│      [雷达图 - 当前模式数据]      │
│                                  │
│  身: ████████░░ 80               │
│  心: ██████░░░░ 60               │
│  ...                              │
└──────────────────────────────────┘
```

### 6.2 锁定态组件 `components/gate-lock.vue`

- 复用组件，props: `gate`（当前锁定关卡信息）
- 根据 gate.gateType 自动映射跳转目标：

| gate_type | 按钮文案 | 跳转目标 |
|-----------|---------|---------|
| SELF_CHECK | "完成五维自检，解锁个人沙盘" | `pages/family/self-check.vue` |
| INVITE_FAMILY | "邀请家人加入，解锁全家沙盘" | 家庭邀请页/成员管理 |
| CREATE_FAMILY_MEMBER | "创建孩子账号，解锁微行动" | 创建家庭成员页 |

- 各处沙盘统一使用 gate-lock：

| 页面 | 改造 |
|------|------|
| `parent-index.vue` | 调用 `/api/energy/sandbox?view=personal`，locked 时渲染 gate-lock；解锁后显示沙盘+切换开关 |
| `child-index.vue` | 同上（孩子端仅供查看个人沙盘，全家开关是否显示取决于 gate 2 解锁状态） |
| `member-home-detail.vue` | 同上 |
| `member-detail/member-detail.vue` | 同上 |
| `discover/index.vue` | 同上 |
| `body-detail/index.vue` | 同上 |
| `mind-detail/index.vue` | 同上 |
| `wisdom-detail/index.vue` | 同上 |

### 6.3 首页引导条 `components/gate-guide-bar.vue`

- 家长首页 `parent-index.vue` 顶部展示："🔓 解锁进度 1/3 · 完成五维自检解锁个人沙盘 →"
- 数据源：`/api/unlock/status` 的 gates 列表（已解锁数/主线总数）
- 全解锁后自动消失
- 点击 → 关卡中心页

### 6.4 关卡中心页 `pages/profile-extra/gates.vue`

- 分区展示：
  - **主线关卡**：锁态（🔒 灰）/ 当前（进行中高亮）/ 已解锁（✅）
    - 关1：五维自检 → 个人沙盘
    - 关2：邀请家人 → 全家沙盘
    - 关3：创建家人 → 孩子微行动
  - **增值关卡**：购买入口（跳商城对应商品/测评），已购显示已解锁
  - **软引导**：推荐卡片（微行动/连续打卡/复测），点击直达
- 每关展示：图标+名称+说明+奖励（+N 积分 · +N 能量）
- 新页面需在 `pages.json` 注册（分包 profile-extra）

### 6.5 沙盘叠加自检分数

- 个人沙盘视角下，雷达图叠加自检结果分数（复用 self-check-result 的雷达图数据）
- 实现位置：`WuxingSandbox` 组件扩展可选 props（selfCheckScores）

---

## 7. 管理端设计（cfc-web）

### 7.1 页面 `views/admin/gates.vue`

- 路由：`/admin/gates`（菜单"系统管理"下"关卡配置"）
- 表格列：排序 | 图标 | 名称 | 类型 | 归属(主线/增值) | 形态(硬门禁/软引导) | 解锁目标 | 条件 | 奖励 | 状态 | 操作
- 操作：编辑（弹窗表单）/ 启停开关 / 删除 / 上下移排序（或数字排序）
- 表单字段（对应 unlock_gates）：
  - 类型下拉：五维自检 / 邀请家人 / 创建家人 / 购买商品 / 加入会员 / 上传报告 / 微行动次数 / 连续打卡天数
  - 条件参数按类型动态渲染：
    - SELF_CHECK → 无参数（或 minCount）
    - INVITE_FAMILY → 无参数（硬编码 ≥2 人）
    - CREATE_FAMILY_MEMBER → 无参数（硬编码 ≥1 个孩子）
    - PURCHASE → 选商品类型（不限/多选或自定义 product_types 输入）
    - MEMBERSHIP → 无参数（硬编码 ≥1 有效订阅）
    - REPORT_UPLOAD → 无参数（或 minCount）
    - 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 种子数据）

### 8.1 主线硬门禁（三关递进）

| 关卡 | gate_type | 归属 | 软/硬 | unlock_target | 条件 | 判据粒度 | 奖励 |
|------|-----------|------|-------|---------------|------|---------|------|
| ① 五维自检 | SELF_CHECK | 主线 | 硬门禁 | PERSONAL_SANDBOX | 完成1次 | 个人级 | +60积分 +10能量 |
| ② 邀请家人 | INVITE_FAMILY | 主线 | 硬门禁 | FAMILY_SANDBOX | 家庭≥2人 | 家庭级 | +80积分 +15能量 |
| ③ 创建家人 | CREATE_FAMILY_MEMBER | 主线 | 硬门禁 | CHILD_MICRO_ACTION | 孩子≥1人 | 家庭级 | +50积分 +10能量 |

### 8.2 软引导与增值关卡

| 关卡 | gate_type | 归属 | 软/硬 | unlock_target | 条件 | 奖励 |
|------|-----------|------|-------|---------------|------|------|
| 首次微行动 | 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能量 |
| 健康报告上传 | REPORT_UPLOAD | 增值 | 硬门禁(增值) | HEALTH_INSIGHTS | ≥1份报告 | +100积分 +20能量 |
| 加入会员 | MEMBERSHIP | 增值 | 硬门禁(增值) | PREMIUM_MODULES | ≥1有效订阅 | +200积分 +50能量 |
| 首次购物 | PURCHASE | 增值 | 硬门禁(增值) | PREMIUM_MODULES | ≥1笔支付成功订单 | +150积分 +30能量 |

> 种子数据写入方式：`DatabaseInitializer.runMigrations()` 迁移（参考项目迁移工作流，编号递增、幂等），管理端可随时增删改。

---

## 9. 风险与注意事项

| 风险 | 缓解 |
|------|------|
| 强制自检导致新用户流失 | 自检入口直达 + 首页引导条强调"5分钟"；门禁仅锁沙盘，其余功能（任务/心愿/成长）不受影响 |
| 老用户（未自检）突然看不到沙盘 | 全部硬门禁关闭可整体失效（运营开关）；上线前对存量家庭数据评估，批量预置完成自检和邀请家人的老用户 |
| 自检判据需按 user_id 反查 family_id | `five_dimension_self_checks` 表无 `family_id` 字段，SELF_CHECK 判定需通过 `userMapper` 关联查询。评估加冗余列 `family_id` 以简化查询 |
| 邀请家人判据覆盖不全 | 邀请流程可能有多种入口（邀请码/二维码/手动添加），需确保所有入口都触发 `refreshFamilyGates` |
| 会员/购物/报告判据口径 | 每种类型需明确对应的状态字段（如会员订阅的有效期、订单的支付成功状态、报告的已确认状态），管理端配置时需提示 |
| 通关奖励发放一致性 | 奖励发放需与 `refreshFamilyGates` 绑定，确保同一事务内完成"解锁 + 发放"；避免解锁但奖励未到账 |
| 门禁判定性能 | 判定结果冗余到 family_gate_progress（判定后写库），沙盘接口只读进度表，不重复扫描业务表 |
| 孩子端首次进入无家庭 | 保持现有 noFamily 逻辑，不套门禁（家庭级判定前置条件：有 family_id） |
| 多角色用户（parent+teacher） | 自检判据基于个人 user_id，天然兼容；家庭级判据基于 family_id，不受角色影响 |

---

## 10. 测试策略（tests/AGENTS.md 分层）

| 层 | 内容 |
|----|------|
| 单元 | UnlockGateService 八类型判定（SELF_CHECK/INVITE_FAMILY/CREATE_FAMILY_MEMBER/PURCHASE/MEMBERSHIP/REPORT_UPLOAD/MICRO_ACTION/STREAK_DAYS）+ 边界条件（count=0、无记录、多记录）；getCurrentPersonalLockGate 与 getCurrentFamilyLockGate 顺序依赖；禁用关卡降级；奖励发放幂等 |
| 集成 | `/api/unlock/status` 返回结构；`/api/energy/sandbox?view=personal` 未通关 SELF_CHECK 返回 locked；`/api/energy/sandbox?view=family` 未通关 INVITE_FAMILY 返回 locked；各触发点（自检/邀请/创建/支付/会员/报告）回调后 refresh + 奖励生效 |
| 前端 | gate-lock 组件渲染（主线3种+增值3种类型+跳转）；WuxingSandbox 切换开关显隐控制；gate-guide-bar 进度计算；关卡中心页三区展示 |
| E2E | 新用户注册→个人沙盘锁定→完成自检→个人沙盘解锁+奖励到账→邀请家人→全家沙盘解锁+奖励→创建孩子→微行动解锁+奖励→购物/会员/报告增值关卡 |

---

## 11. 实施范围与工作量估算

| 模块 | 内容 | 估算 |
|------|------|------|
| 后端 | 2 张表迁移 + UnlockGateService（8 种判定 + 奖励发放）+ UnlockController + AdminUnlockGateController + sandbox 改造（view 参数）+ 7 处钩子 + 种子数据 | 5-6 天 |
| 小程序 | WuxingSandbox 个人/全家切换 + gate-lock 组件（6 种类型映射）+ gate-guide-bar + gates.vue 关卡中心 + 8+ 处沙盘替换 + 自检分数叠加 | 4-5 天 |
| 管理端 | gates.vue 配置页（含新类型）+ 家庭进度管理 | 1-2 天 |
| 测试 | 单测/集成/前端/E2E | 1-2 天 |

**里程碑验收：**
- 后端完成：Postman 验证 `sandbox?view=personal` 与 `sandbox?view=family` 的 locked 分支
- 前端完成：新用户动线"注册→个人沙盘锁定→自检→解锁个人→邀请家人→解锁全家→创建孩子→解锁微行动"全链路走通
- 管理端完成：新增关卡（含新类型）/调整顺序/禁用关卡实时生效

---

## 12. 六步法关卡总表

根据书稿"看见 → 最小输入 → 循环 → 反馈 → 传播"算法，结合当前系统能力，将关卡组织为六步递进链路（四步行为闭环 + 两步升级转化）：

### 12.1 关卡总表

| 步骤 | 关卡 | gate_type | 可见条件 | 判定依据 | 对应打开功能 | 类型 | 奖励 |
|:----:|------|-----------|---------|---------|-------------|:----:|:----:|
| **① 看见** | 五维自检 | SELF_CHECK | 注册后始终可见（首页引导条/关卡中心置顶） | five_dimension_self_checks 存在当前 user_id 记录 ≥1 条 | **个人沙盘**（查看自己的五维数据） | 主线硬门禁 | +60积分 +10能量 |
| **② 凝聚** | 邀请家人 | INVITE_FAMILY | 关①完成后可见 | user 表该 family_id 成员数 ≥2（本人 + ≥1位家人） | **全家沙盘开关**（沙盘顶部出现个人/全家切换） | 主线硬门禁 | +80积分 +15能量 |
| **③ 养育** | 创建家人 | CREATE_FAMILY_MEMBER | 关②完成后可见 | family_member 表该 family_id 记录 ≥1（≥1个孩子） | **孩子微行动**（给孩子下发微行动、查看孩子个人沙盘） | 主线硬门禁 | +50积分 +10能量 |
| **④ 习惯** | 首次微行动 | MICRO_ACTION | 关③完成后可见（软引导） | micro_action_records 该 family 记录 ≥1 | 解锁"每日微行动"推荐（微行动卡常驻） | 软引导 | +50积分 +5能量 |
| | 连续打卡3天 | STREAK_DAYS | 首次微行动完成 + 打卡启用后可见（软引导） | 家庭成员 max(streakDays) ≥3 | 解锁"连续打卡里程碑"（勋章墙展示） | 软引导 | +30积分 +5能量 |
| **⑤ 反馈** | 复测对比 | SELF_CHECK（复测） | 首次自检 ≥7天后可见（软引导） | five_dimension_self_checks 记录 ≥2 | **趋势对比**（第二次自检后显示前后雷达图对比） | 软引导 | +60积分 +10能量 |
| **⑥ 升级** | 首次购物 | PURCHASE | 注册后始终可见（增值，无前置依赖） | 商城订单表存在支付成功订单 ≥1笔 | 解锁"增值内容"（健康报告深度解读、AI分析等） | 增值硬门禁 | +150积分 +30能量 |
| | 加入会员 | MEMBERSHIP | 注册后始终可见（增值，无前置依赖） | family_memberships / member_subscription 存在有效订阅 | 解锁"会员专属模块"（专属徽章、高级分析等） | 增值硬门禁 | +200积分 +50能量 |
| | 健康报告上传 | REPORT_UPLOAD | 注册后始终可见（增值，无前置依赖） | health_reports 该 family_id 记录 ≥1条 | 解锁"健康洞察"（报告解读、指标趋势、AI建议） | 增值硬门禁 | +100积分 +20能量 |

> **主线**（①②③）是硬门禁、顺序依赖、逐关点亮；**习惯/反馈**（④⑤）是不锁功能的软引导；**升级**（⑥）无前置、可先于主线完成、独立判据。

### 12.2 六步法说明

| 步骤 | 书稿依据 | 用户心理 | 产品目标 | 对应功能模块 |
|:----:|---------|---------|---------|-------------|
| ① 看见 | 第2章"测量先行" | 好奇→共鸣 | 15题自检快速"看见"自己的五维，建立初始认知 | self-check → 个人沙盘 |
| ② 凝聚 | 第7章"家庭关系" | 归属感 | 从单人→家庭，邀请家人共建家庭数据，从"我"到"我们" | 邀请码/二维码 → 全家沙盘 |
| ③ 养育 | 第8章"最小输入" | 责任感 | 创建孩子后获得"可行动对象"，开始家庭互动 | 创建成员 → 孩子微行动 |
| ④ 习惯 | 第9章"循环执行" | 成就感 | 微行动+打卡形成日常习惯回路，建立使用粘性 | 微行动卡、每日打卡 |
| ⑤ 反馈 | 第10章"反馈校验" | 获得感 | 复测对比让用户看见进步，强化"我在变好" | 复测 → 雷达图对比 |
| ⑥ 升级 | 第11章"系统升级" | 深度参与 | 购物/会员/报告完成免费→付费转化，获得更深价值 | 商城订单、会员订阅、健康报告 |

### 12.3 前端可见性规则

| 用户状态 | 关卡中心显示 |
|---------|-------------|
| 未登录 | 不显示关卡，显示引导注册内容 |
| 已登录·无家庭 | 只显示关①（自检），其他家庭级关卡隐藏（无 family_id 无法判定） |
| 有家庭·关①未完成 | 关① = CURRENT（高亮），其余主线/增值显示 🔒 锁定态 |
| 关①完成 | 关① = ✅，关② = CURRENT，后续主线/增值 = 🔒 |
| 关②完成 | 关② = ✅，关③ = CURRENT，软引导④⑤可见，增值 = 🔒 |
| 关③完成 | 关③ = ✅，软引导④⑤ = CURRENT，增值 = 🔒 |
| 主线全完成 | ①②③ = ✅，④⑤ = CURRENT，增值 = 🔒 |
| 增值关完成 | 对应关卡 = ✅（+奖励到账），其余不受影响 |