|
@@ -0,0 +1,315 @@
|
|
|
|
|
+# 通关解锁功能设计（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 核心规则
|
|
|
|
|
+
|
|
|
|
|
+1. **主线硬门禁**：`is_required=1 AND is_soft=0` 的关卡按 `sort_order` **顺序依赖**——必须依次解锁，当前锁定关卡是最小 sort_order 的未通关关卡；其 `unlock_target` 对应模块对全家锁定。
|
|
|
|
|
+2. **增值关卡**：`is_required=0`，**无前置依赖**，任何时刻可完成（满足"关2可在关1前完成"）。
|
|
|
|
|
+3. **软引导**：`is_soft=1` 的关卡不锁任何功能，仅在关卡中心页/首页引导条展示为"推荐解锁"，点击直达对应功能。
|
|
|
|
|
+4. **判据粒度**：所有判定基于 `family_id`（家庭级），与当前登录人无关。
|
|
|
|
|
+5. **可降级**：所有硬门禁关卡均被禁用（`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/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（家庭通关进度表）
|
|
|
|
|
+
|
|
|
|
|
+```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 存在 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 分支）
|
|
|
|
|
+- 前端完成：新用户动线"注册→沙盘锁定→自检→解锁"全链路走通
|
|
|
|
|
+- 管理端完成：新增关卡/调整顺序/禁用关卡实时生效
|
