docs(cfclub): 小程序改版设计+分阶段实施计划（需求驱动·逐步解锁，C类问题域闭环优先）

docs/cfc-redesign-progressive-unlock.md

@@ -0,0 +1,252 @@
+# 浠艾福小程序改版：需求驱动 · 逐步解锁
+
+> 阶段：实施计划 v1.0 | 分支：cfclub | 产品决策已确认（2026-08-13）
+
+## 一、背景与目标
+
+现状：小程序首页对所有用户一视同仁地堆内容（商品/活动/文章/任务），未区分用户需求深度，转化链路不清晰。
+
+改版核心：**从用户需求出发，先识别用户类型，按需求深度逐步解锁内容与功能，无关内容不展示。**
+
+三类用户：
+- **A类 目标明确型**：已接受平台理念，直接买 DAN测评 / 菌群检测 → 上传报告 → 出方案 → 生成任务 → 执行（方案任务需会员）
+- **B类 观望型**：登录看看 → 轻问卷 → 按答案开放相关科普内容
+- **C类 问题导向型**：带具体问题来（减肥/睡眠/便秘）→ 服务流程介绍 → 专项调研 → 匹配推荐套餐 → 购买 → 试剂盒寄送/样本寄回 → 报告完成系统通知 → 方案确认 → 任务分解执行 → 全部完成奖励 CF 值
+
+已确认决策：
+1. 入口呈现：**首次登录强制选择**；已登录但从未选过的用户，下次进入也要弹出选择
+2. 问题域首版：**减肥 / 睡眠 / 便秘** 三个
+3. 会员任务边界：**仅"方案生成"的任务需会员**；未缴费用户可以自己创建任务自己完成（免费）
+4. 完成回馈奖励：**主要奖励 CF 值**（复用 PlatformPointsService）
+5. 实施优先级：**C类优先 → A类会员任务解锁 → B类问卷引流**
+
+## 二、现状摸底结论（已核实）
+
+| 模块 | 现状 | 结论 |
+|------|------|------|
+| 首页分流 | `pages/index-home/index.vue` 内嵌登录/游客两态，游客看商品+活动+文章，登录看沙盘+动态+会员入口+快捷功能+任务+挑战+推荐 | 需重构为"旅程状态驱动" |
+| 测评链路 | `DanAssessmentController`: order/create→pay→appointment→record→result→report 全链路已有 | ★★★ 直接复用 |
+| 报告解析 | `DanReportController`: upload→edit→confirm→complete-analysis | ★★★ 直接复用 |
+| 菌群检测 | `BeijingNutritionController`: bacteria/save + analysis + recommend；送会员走 `TrialMembership` | ★★★ 直接复用 |
+| 会员 | `FamilyMembership`(FREE/BASIC/PROFESSIONAL/ENTERPRISE) + `MembershipController`(upgrade/trial/my/can-use/benefits) | ★★★ 直接复用 |
+| 问卷 | `SurveyTemplate`(questionsJson 题目JSON) + `SurveyRecord`(answersJson) + `ReportSurveyController`(create/submit/status)；前端 `pages/health/survey-questionnaire.vue` 通用渲染页已有 | ★★ 扩展（题目JSON 加 resultMapping） |
+| 套餐 | `GuidePackage`(price/validityDays) + `TaskTemplatePackage`(cycleDays/category/price) + `AssessmentProduct`(single/bundle) | ★★ 需补"套餐→检测→任务模板"关联 |
+| 任务 | `Task` 有 sourceType/sourceId/dimensionCode，**无会员字段** | ★ 需加 `member_only` |
+| CF值 | `PlatformPointsService.earn/spend/freeze/unfreeze` + 家庭池 `FamilyPlatformPointsService`；`UnlockGateService` 已实现关卡奖励发 CF 值（幂等） | ★★★ 复用 earn() 发奖励 |
+| 优惠券 | `Coupon`/`UserCoupon`/`CouponController`(exchange/claim) | ★★★ 备用 |
+| 通知 | `NoticeController` 仅 `/list`（GET，且不合规），无主动通知 | ★ 需新建通知表+写入+列表接口 |
+
+## 三、数据模型设计
+
+### 3.1 新增 `problem_domains`（问题域表）
+
+```sql
+CREATE TABLE IF NOT EXISTS problem_domains (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  code VARCHAR(50) NOT NULL COMMENT '唯一编码: weight_loss/sleep/constipation',
+  name VARCHAR(50) NOT NULL COMMENT '名称: 减肥/睡眠/便秘',
+  icon VARCHAR(255) DEFAULT '' COMMENT '图标',
+  description VARCHAR(500) DEFAULT '' COMMENT '一句话描述',
+  flow_intro_json TEXT COMMENT '服务流程介绍(7步) JSON',
+  survey_template_id BIGINT DEFAULT NULL COMMENT '专项调研问卷模板ID(SurveyTemplate.id)',
+  content_tags VARCHAR(500) DEFAULT '' COMMENT '内容标签,逗号分隔(过滤文章/知识库)',
+  recommended_product_ids VARCHAR(500) DEFAULT '' COMMENT '推荐产品ID,逗号分隔(Product.id)',
+  task_template_package_ids VARCHAR(500) DEFAULT '' COMMENT '套餐绑定的任务模板包ID(TaskTemplatePackage.id)',
+  reward_cf_value INT DEFAULT 0 COMMENT '全部完成奖励CF值',
+  status TINYINT DEFAULT 1 COMMENT '1启用 0停用',
+  sort_order INT DEFAULT 0,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_code (code)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='问题域定义(改版v1)';
+```
+
+### 3.2 新增 `user_intents`（用户意图/旅程表）
+
+```sql
+CREATE TABLE IF NOT EXISTS user_intents (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  user_id BIGINT NOT NULL COMMENT '用户ID',
+  intent_type VARCHAR(20) DEFAULT '' COMMENT 'A/B/C 用户类型',
+  problem_domain_code VARCHAR(50) DEFAULT '' COMMENT '问题域编码(仅C类)',
+  journey_stage INT DEFAULT 0 COMMENT '旅程阶段 0-7，语义见下方状态机',
+  stage_updated_at DATETIME DEFAULT NULL COMMENT '最近阶段变化时间',
+  survey_template_id BIGINT DEFAULT NULL COMMENT '最近作答问卷模板ID',
+  survey_submitted_at DATETIME DEFAULT NULL COMMENT '最近问卷提交时间',
+  survey_result_json TEXT COMMENT '问卷答案→推荐结果快照',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_user (user_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户意图与服务旅程(改版v1)';
+```
+
+**journey_stage 状态机（C类，0-7）**：
+| stage | 语义 | 进入条件 | 推进动作 |
+|-------|------|----------|----------|
+| 0 | 已选择问题域，未看流程 | 用户选择 C 类+问题域 | 打开流程介绍页 |
+| 1 | 已看流程介绍 | 流程介绍页曝光完成 | 提交调研 |
+| 2 | 调研已提交 | 调研提交成功 | 购买套餐 |
+| 3 | 已购买 | 支付回调成功 | 管理员发货 |
+| 4 | 试剂盒已发/样本已收 | 物流状态更新 | 报告生成 |
+| 5 | 报告已出 | completeAnalysis 完成 | 用户确认方案 |
+| 6 | 方案已确认，任务已生成 | 方案确认接口 | 任务全部完成 |
+| 7 | 任务完成，CF奖励已发 | 奖励发放成功 | —（终态，展示回馈） |
+
+A类简化：0=已选A类，1=已购测评/检测，2=报告已出，3=方案确认，4=任务完成。B类简化：0=已选B类，1=问卷已答（此后首页按结果定向展示内容）。
+
+### 3.2b 通知表与既有 `notices` 的边界
+
+- `notices`（`Notice.java`, @TableName("notices")）：**平台级公告**，管理员发布（platform/activity/promotion），全员可见，`NoticeController` 仅 GET /list（遗留不合规，不动）。
+- `user_notifications`（新增）：**用户级主动通知**，按 user_id 定向（报告完成/奖励到账/物流变化），带 ref_type/ref_id 可跳转。二者并存不冲突。
+
+### 3.3 Task 表加会员字段
+
+```sql
+ALTER TABLE task ADD COLUMN member_only TINYINT DEFAULT 0 COMMENT '1=会员任务(方案生成),执行需会员';
+```
+
+### 3.4 新增 `user_notifications`（站内通知表）
+
+```sql
+CREATE TABLE IF NOT EXISTS user_notifications (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  user_id BIGINT NOT NULL COMMENT '接收用户ID',
+  type VARCHAR(30) DEFAULT 'report_ready' COMMENT 'report_ready/reward_granted/system',
+  title VARCHAR(200) NOT NULL,
+  content VARCHAR(1000) DEFAULT '',
+  ref_type VARCHAR(30) DEFAULT '' COMMENT '关联对象类型: report/package/task',
+  ref_id BIGINT DEFAULT NULL COMMENT '关联对象ID',
+  is_read TINYINT DEFAULT 0,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_user_read (user_id, is_read)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='站内通知(改版v1)';
+```
+
+### 3.5 套餐/物流状态扩展（复用 PackageOrder / ProductOrder）
+
+- `package_orders` 表（`entity/PackageOrder.java` 已存在，含 userId/familyId/packageId/contactName/contactPhone/contactAddress）加：
+  - `logistics_status VARCHAR(20) DEFAULT 'none'`（none/kit_shipped/kit_received/sample_shipped/sample_received）
+  - `tracking_no VARCHAR(100) DEFAULT ''`
+
+### 3.6 调研问卷 → 推荐结果映射
+
+`SurveyTemplate.questionsJson` 题目结构扩展：每题的 option 支持 `resultTags`：
+
+```json
+[
+  {"text": "您的睡眠问题持续多久了？", "options": [
+    {"text": "1-3个月", "resultTags": "短期,轻中度"},
+    {"text": "半年以上", "resultTags": "长期,重度"}
+  ]}
+]
+```
+
+后端提交问卷时汇总所有选中 option 的 resultTags + 问题域 code，返回推荐产品列表快照，存入 `user_intents.survey_result_json`。
+
+## 四、后端改动清单（cfc-backend）
+
+### 阶段1：C类问题导向型闭环（优先交付）
+
+| # | 文件 | 改动 | 验证 |
+|---|------|------|------|
+| B1 | `entity/ProblemDomain.java` | 新实体（§3.1） | compile |
+| B2 | `mapper/ProblemDomainMapper.java` | 新 Mapper | compile |
+| B3 | `entity/UserIntent.java` | 新实体（§3.2） | compile |
+| B4 | `mapper/UserIntentMapper.java` | 新 Mapper | compile |
+| B5 | `entity/UserNotification.java` | 新实体（§3.4） | compile |
+| B6 | `mapper/UserNotificationMapper.java` | 新 Mapper | compile |
+| B7 | `entity/Task.java` | 加 `memberOnly` 字段 | compile |
+| B8 | `config/DatabaseInitializer.java` | 迁移：3 张新表 + task.member_only + package_order 物流字段 | compile |
+| B9 | `resources/schema.sql` | 同步建表语句 | — |
+| B10 | `controller/ProblemDomainController.java` | 接口：`POST /api/problem-domain/list`(启用中,含问卷模板+推荐产品+任务模板) | compile |
+| B11 | `controller/UserIntentController.java` | 接口：`POST /api/user-intent/get`(当前意图) / `POST /api/user-intent/choose`(首次选择A/B/C) / `POST /api/user-intent/update-stage`(旅程推进) | compile |
+| B12 | `controller/UserNotificationController.java` | 接口：`POST /api/notification/list` / `POST /api/notification/read` | compile |
+| B13 | `controller/ProblemSurveyController.java` | 接口：`POST /api/problem-survey/submit`(提交调研→汇总resultTags→查推荐产品→存快照→返回推荐列表) | compile |
+| B14 | `controller/ProblemPackageController.java` | 接口：`POST /api/problem-package/detail`(套餐详情:介绍/使用方式/包含检测/任务模板/奖励说明) | compile |
+| B15 | `controller/TaskController.java` | 补会员校验：`/{id}/complete`、`/accept` 时若 `task.memberOnly==1` 且非会员 → 拒绝(提示开通会员) | compile |
+| B16 | `service/DanReportService.completeAnalysis`（报告确认处） | 报告完成解析后：写 `user_notifications`(report_ready) + 更新 `user_intents.journey_stage`=5 | compile |
+| B17 | `service/ProblemCompletionService.java` | 新 Service：任务全部完成后发放 CF 值。**奖励对象：家庭池（FamilyPlatformPointsService.earn，familyId 维度）**，金额=问题域配置 reward_cf_value；幂等：按 (familyId, problemDomainCode, 'completion') 查唯一发放记录；写通知(reward_granted) + 更新旅程 stage=7 | compile |
+| B18 | `entity/PackageOrder.java` | 加 `logisticsStatus` / `trackingNo`（表 package_orders） | compile |
+| B19 | `controller/LogisticsController.java` | 接口：`POST /api/logistics/update`(管理端发货/收样) / `POST /api/logistics/my`(用户查状态) | compile |
+
+### 阶段2：A类会员任务解锁
+
+| # | 文件 | 改动 |
+|---|------|------|
+| B20 | `service/TaskPlanService`（任务实例生成处）+ `TaskService.createSingleTask` | 方案/套餐确认生成任务实例时标记 `memberOnly=1`；`createSingleTask` 从 DTO 透传 memberOnly |
+| B21 | `service/RepeatTaskGenerator` | 重复任务复制模板时**透传 memberOnly 字段**（否则方案任务实例的会员标记丢失） |
+| B22 | `TaskController.create` | 未缴费用户自建任务：`memberOnly=0`，不校验会员（确认现有 create 已放行） |
+
+### 阶段3：B类问卷引流
+
+| # | 文件 | 改动 |
+|---|------|------|
+| B23 | `SurveyTemplate` 扩展 | questionsJson 支持 resultTags；`getActiveTemplates` 支持按问题域过滤 |
+| B24 | `controller/ContentFilterController.java` | 接口：`POST /api/content/by-tags`(按 resultTags + 问题域 code 过滤文章/知识库/饮食推荐) |
+
+## 五、前端改动清单（cfc-frontend）
+
+### 阶段1：C类闭环
+
+| # | 文件 | 改动 |
+|---|------|------|
+| F1 | `pages/index-home/index.vue` | **首页重构**：登录后顶部"旅程状态卡"(进度+下一步)；未选择过意图的用户弹"首次选择"层(A直达/B问卷/C问题域) |
+| F2 | `components/intent-picker.vue`（新） | 首次选择弹层：三个入口卡片 |
+| F3 | `components/journey-card.vue`（新） | 旅程进度条 + 下一步动作按钮（按 user_intents 渲染） |
+| F4 | `pages/problem/domain-list.vue`（新） | 问题域列表页（3个卡片） |
+| F5 | `pages/problem/flow-intro.vue`（新） | 服务流程介绍页（7步，来自 flow_intro_json） |
+| F6 | `pages/problem/survey.vue`（新） | 专项调研页（复用 survey-questionnaire 模式，提交走 problem-survey/submit） |
+| F7 | `pages/problem/package-match.vue`（新） | 调研结果→推荐套餐列表（只显示相关） |
+| F8 | `pages/problem/package-detail.vue`（新） | 套餐详情（介绍/使用方式/包含检测/任务模板/奖励）→ 购买按钮 |
+| F9 | `pages/problem/logistics.vue`（新） | 试剂盒寄送/样本寄回状态 |
+| F10 | `pages/problem/plan-confirm.vue`（新） | 报告出来后查看方案 → 确认 → 生成任务 |
+| F11 | `pages/notification/index.vue`（新） | 站内通知列表（报告完成/奖励到账） |
+| F12 | `pages/tasks/tasks.vue` | 会员任务角标（memberOnly 显示🔒，点击提示开通会员） |
+| F13 | `utils/api.js` | 新接口封装（problem-domain/user-intent/notification/problem-survey/problem-package/logistics） |
+
+### 阶段2：A类
+
+| # | 文件 | 改动 |
+|---|------|------|
+| F14 | `pages/index-home/index.vue` | 入口A直达"测评/检测选购页" |
+| F15 | 方案确认页复用 F10 | A类报告出方案→确认→生成任务(带 memberOnly) |
+
+### 阶段3：B类
+
+| # | 文件 | 改动 |
+|---|------|------|
+| F16 | `pages/problem/quick-survey.vue`（新） | 5-8题轻问卷 |
+| F17 | `pages/index-home/index.vue` | 按调研结果定向展示科普内容模块 |
+
+## 六、管理端改动清单（cfc-web）
+
+| # | 文件 | 改动 |
+|---|------|------|
+| W1 | `views/admin/ProblemDomainManage.vue`（新） | 问题域 CRUD：编码/名称/图标/描述/流程介绍(7步编辑)/绑定问卷模板/内容标签/推荐产品/任务模板包/奖励CF值 |
+| W2 | 套餐管理增强 | 绑定检测项目、任务模板包、完成奖励CF值 |
+| W3 | 通知模板管理 | report_ready / reward_granted 文案配置（可选） |
+| W4 | 物流管理 | 试剂盒发货/样本签收状态更新（可选，后端接口已备） |
+
+## 七、实施顺序（里程碑）
+
+| 里程碑 | 内容 | 验收标准 |
+|--------|------|----------|
+| M1 数据层 | B1-B9 | mvn clean compile 通过；3 张新表 + task.member_only 迁移幂等 |
+| M2 C类后端接口 | B10-B19 | compile 通过；关键接口（survey submit→推荐、报告完成→通知+旅程推进、任务完成→CF奖励）逻辑可测 |
+| M3 C类前端闭环 | F1-F13 + W1 | 用户在开发者工具可走通：选减肥→流程介绍→调研→套餐→购买→物流→通知→方案确认→任务→完成得CF值 |
+| M4 A类会员任务 | B20-B21 + F14-F15 | 方案任务带锁，非会员执行被拦截；自建任务免费可用 |
+| M5 B类问卷引流 | B22-B23 + F16-F17 | 观望用户填问卷后首页只显示相关内容 |
+
+## 八、风险与注意事项
+
+1. **首次选择弹层**：必须在登录后数据加载前弹出一次，且"跳过"不得导致下次不再弹出（storage 标记 `intent_skipped`，弹层关闭时写标记但 user_intents 未创建 → 下次仍弹）。决策1要求"未选过就要弹"。**teacher(规划师)角色不弹**（服务商不是 C 类客户，仅 parent/child 视角弹）。
+2. **memberOnly 校验**：校验点在 TaskController complete/accept，需同时覆盖规划师批量审核路径（GuideFamilyTaskController）与家长代完成路径（complete-parent）。
+3. **CF 奖励幂等 + 归属**：按 (familyId, problemDomainCode, 'completion') 唯一记录防重复发放（参照 UnlockGateService 已实现模式）；**奖励进家庭池**（FamilyPlatformPointsService），不落个人池，避免"执行者是孩子、购买者是家长"的归属争议。
+4. **问卷 resultTags**：老模板无 resultTags 时兼容（option 是纯字符串），解析器需双态处理。
+5. **小程序规范**：新页面全部 Options API、禁止可选链、禁止 :key 表达式、日期用 parseDate、路由用 POST。
+6. **通知合规**：`NoticeController` 现有 `/list` 是 GET（不合规遗留），新建的 `UserNotificationController` 一律 POST；不动旧接口。
+7. **问卷模板 JSON 迁移**：现有调研模板数据结构不含 resultTags，提交接口需对"无 resultTags"模板返回空推荐（不报错）。
+8. **物流状态**：已确认 `package_orders` 表存在（`PackageOrder.java`），物流字段加其上；kit_shipped 即"试剂盒已寄出"。
+9. **会员判断复用**：调 `MembershipController.can-use` 或直接查 `FamilyMembership` levelCode != FREE 且未过期。
+10. **C类流程承载物**：流程描述页/套餐详情页写死"菌群检测试剂盒"是错误的——**套餐（TaskTemplatePackage/GuidePackage）是承载物**，flow_intro_json 每步文案可配置，检测项目通过套餐绑定的 assessmentProduct 决定。减肥/睡眠/便秘各自的套餐与检测项在管理端配置，代码不写死。
+11. **新增 Controller 前置检查**：新增 ProblemDomainController/UserIntentController 等前，先跑路由重复检查（AGENTS.md 工作流）与 Bean 名冲突检查。