# 2026-07-22-comprehensive-implementation - Work Plan

**计划状态:** ✅ 大部分已完成（Tasks 1-4, 6-10 全部完成, Task 5 基础完成, Tasks 11-13 Phase 4 待实施）

## TL;DR (For humans)

**What you'll get:** 浠艾福平台按3个Phase逐步完成8项核心功能的实施。Phase 2（本月）把LangGraph AI能力真正接入小程序前端 + 上线家庭推广体系让用户能邀请有酬。Phase 3（Q3）打磨五维核心体验——财富维度重新设计、家庭成员辈分体系、公众号文章发布流程。Phase 4（Q4）扩展供应商生态和健康功能。

**Why this approach:** LangGraph Docker已部署运行，目前卡在"有服务无前端"。先打通AI通道才能做AI管家。推广体系后端已完工只差前端，是快速可见的商业化产出。五维增强排Phase 3因为涉及前后端联动改动量大。

**What it will NOT do:** 不会移除Dify（保留fallback），不会升级Java 8，不会动数据库架构（除必要的推广/辈分扩展表）。

**Effort:** XL - 横跨4个Phase、8项核心功能
**Risk:** Medium - LangGraph前端集成是最大风险点（新通道首次联调）
**Decisions to sanity-check:** 1) LangGraph集成方案（直接替换 vs 渐进替换）；2) 辈分重构的UI交互设计

Your next move: **approve** this plan, then use `$start-work 2026-07-22-comprehensive-implementation` to begin Phase 2 execution.

---

> TL;DR (machine): XL effort, Med risk, 4 phases, 8 items. Phase 2 = LangGraph frontend integration + family promotion frontend. Phase 3 = wealth sub-dimensions + generation refactor + article publishing. Phase 4 = supplier + health 7-dim + growth record.

## Scope
### Must have
- ✅ Phase 2 (2026-07~08): LangGraph Frontend Integration (replace Dify calls) + Family Promotion System P2-P4 (frontend pages + public account + management UI)
- ✅ Phase 3 (2026-Q3): Wealth sub-dimension split + Body-restrains-wealth leverage + Family member generation refactor + Article publishing/audit system
- ⏳ Phase 4 (2026-Q4): Supplier distribution system + Health 7-dim model + Growth record rebuild

### Must NOT have (guardrails, anti-slop, scope boundaries)
- Dify完全移除：保留fallback直到LangGraph验证通过
- Java 8/Spring Boot 2.7.18 不升级
- 不引入新中间件（PostgreSQL、Redis等）
- 不做国际化/SSR/SEO优化
- 不做代码质量重构（已有A类8项已结束）
- 小程序端禁止 Composition API、可选链 `?.`、CSS Grid

## Verification strategy
> Zero human intervention - all verification is agent-executed.
- Test decision: tests-after (项目无TDD基础设施) + mvn compile + 小程序预览
- Evidence: .omo/evidence/task-<N>-2026-07-22-comprehensive-implementation.<ext>

## Execution strategy
### Phase dependency (每个Phase独立，Phase内任务并行)

Phase 2 (当前窗口 - 2026-07~08):
  Wave 1: 任务1 (LangGraph后端适配) + 任务3 (推广后端API) — 并行
  Wave 2: 任务2 (前端LangGraph集成) + 任务4 (推广前端页面) — 并行
  Wave 3: 任务5 (AI健康管家) — 紧跟Wave 2

Phase 3 (2026-Q3):
  Wave 1: 任务6 (富维度后端) + 任务8 (辈分后端) — 并行
  Wave 2: 任务7 (富维度前端) + 任务9 (辈分前端) — 并行
  Wave 3: 任务10 (文章发布系统) — 独立执行

Phase 4 (2026-Q4):
  Wave 1: 任务11 + 任务12 + 任务13 — 可并行

### Dependency matrix
| Todo | Depends on | Blocks | Can parallelize with |
| --- | --- | --- | --- |
| 1 | — | 2, 5 | 3 |
| 2 | 1 | 5 | 4 |
| 3 | — | 4 | 1 |
| 4 | 3 | — | 2 |
| 5 | 2 | — | — |
| 6 | Phase 2 done | 7 | 8 |
| 7 | 6 | — | 9 |
| 8 | Phase 2 done | 9 | 6 |
| 9 | 8 | — | 7 |
| 10 | Phase 2 done | — | 7, 9 |
| 11 | Phase 3 done | — | 12, 13 |
| 12 | Phase 3 done | — | 11, 13 |
| 13 | Phase 3 done | — | 11, 12 |

## Todos

> Implementation + Test = ONE todo. Never separate.

### PHASE 2: 商业模式 & AI 落地

- [x] 1. LangGraph 后端适配层：创建前端可调用的 LangGraph API 路由 ✅ 完成
  What to do / Must NOT do: 在 cfc-langgraph/app/api/ 中创建适配层路由，暴露与 Dify 相同语义的 endpoints（chat/completion, analysis/run）。前端无需改接口格式只改 base_url。必须保留 Dify 路由作为 fallback 不删除。
  Parallelization: Wave 1 | Blocked by: — | Blocks: 2
  References: cfc-langgraph/app/api/adapter.py (Dify兼容端点 /api/v1/chat/completion + /api/v1/analysis/run), chat.py, analyze.py, recommend.py, tongue.py, health.py
  Acceptance criteria: ✅ adapter.py 完整实现 Dify 格式请求/响应模型
  QA scenarios: done
  Commit: Phase 2 Wave 1 统一提交 · Verified: 2026-07-23

- [x] 2. 前端 LangGraph 集成：替换 Dify 调用 ✅ 完成
  What to do / Must NOT do: 修改 cfc-frontend 中所有直接调用 Dify 的代码，将 base_url 切换到 LangGraph 适配层。保留 DIFY_BASE_URL fallback 配置。不改页面逻辑只改请求目标地址。禁止重构。
  Parallelization: Wave 2 | Blocked by: 1 | Blocks: 5
  References: cfc-frontend/config.js (LANGGRAPH_BASE_URL + DIFY_BASE_URL fallback 已配置), api.js (langgraphRequest() 带自动回退, aiSendMessage/aiSendNutritionMessage 调用 LangGraph)
  Acceptance criteria: ✅ 小程序端 AI 功能通过 LangGraph 响应，Dify fallback 可通过配置开关切换
  QA scenarios: done
  Commit: Phase 2 Wave 2 · Verified: 2026-07-23

- [x] 3. 推广体系后端 API 补齐 + 家庭公共账户 ✅ 完成
  What to do / Must NOT do: 实现 P2 家庭公共账户（建表 commission 表 + CommissionService 改造 + 注册绑定）。P4 管理后台推迟。wxacode 改造已在 P1 完成的保留。不重构现有邀请流程。
  Parallelization: Wave 1 | Blocked by: — | Blocks: 4
  References: CommissionService, PromotionTierService, PromotionBindingService, ButlerCommissionService, rebate_commission_config 表, Migration 42
  Acceptance criteria: ✅ 家庭公共账户表已创建，CommissionService 可记录推广佣金，注册绑定流程完成
  QA scenarios: done
  Commit: 03610631 · Verified: 2026-07-23

- [x] 4. 推广前端页面（推广中心 + 成员贡献榜 + 支付集成） ✅ 完成
  What to do / Must NOT do: 实现 P3 前端推广中心重设计（页面+组件+路由）。包含成员推广贡献榜、绑定关系展示、收益概览。支付集成留接口不做真实支付。管理后台 P4 推迟。
  Parallelization: Wave 2 | Blocked by: 3 | Blocks: —
  References: cfc-frontend/pages/promotion/ (index, team, leaderboard, withdraw, material, commission — 6 页面)
  Acceptance criteria: ✅ 小程序可访问推广中心页面，展示绑定关系+推广收益概览
  QA scenarios: done
  Commit: c5e23cc5 · Verified: 2026-07-23

- [x] 5. AI健康管家（MVP版） ✅ 完成
  What to do / Must NOT do: 基于 LangGraph 通道构建 AI 健康管家对话界面。复用已有 chat_graph.py，创建专门 health_butler_graph.py（含健康知识检索+个性化建议）。前端嵌入健康页面底部。不做完整订阅付费墙。
  Parallelization: Wave 3 | Blocked by: 2 | Blocks: —
  References: health_coach_graph.py (已有RAG检索), health_butler_graph.py (新建, Java KB集成), adapter.py (/health/coach endpoint), AIFloatingAvatar.vue (body页面浮动入口 mode=health), chat.vue (三模式: nutrition/health/default), api.js (aiSendHealthCoachMessage)
  Acceptance criteria: ✅ 小程序健康页可唤起 AI 教练对话（AIFloatingAvatar + mode=health 路由），回答基于健康知识库 + RAG 检索
  QA scenarios: done
  Commit: 7b26b657 · Verified: 2026-07-23

### PHASE 3: 五维增强

- [x] 6. 富维度后端子维度拆分 + 身克富杠杆 ✅ 完成
  What to do / Must NOT do: 重构 EnergyService calcChildWealth/calcParentWealth 拆为子维度。实现身克富杠杆（健康风险扣减 + 透支预警标记）。新增 API GET /api/energy/wealth-detail。更新 DTO MemberEnergyDTO 增加子维度字段和身克富字段。不改已有 schema/表结构。
  Parallelization: Wave 1 | Blocked by: Phase 2 done | Blocks: 7
  References: EnergyService 已改造, getWealthDetail API, MemberEnergyDTO 已更新
  Acceptance criteria: ✅ 新 API 返回子维度拆分后的财富数据，身克富逻辑在能量计算中生效
  QA scenarios: done
  Commit: be3b6c3d · Verified: 2026-07-23

- [x] 7. 富维度前端页面重写 + API 对接 ✅ 完成
  What to do / Must NOT do: 重写 pages/wealth/index.vue 为角色感知的富展示（家长看利他创富数据，孩子看积分效率）。对接新 API GET /api/energy/wealth-detail。移除旧混搭内容（任务/购买/活动数据）。不改其他维度页面。
  Parallelization: Wave 2 | Blocked by: 6 | Blocks: —
  References: pages/wealth/index.vue 已重写, wealth-sub 分包, 子维度组件已有
  Acceptance criteria: ✅ 家长端显示推广收益+积分资产，孩子端显示积分获取效率+任务数据
  QA scenarios: done
  Commit: 8112eac6 · Verified: 2026-07-23

- [x] 8. 家庭成员辈分重构后端链路 ✅ 完成
  What to do / Must NOT do: 基于 GenerationLevel.java 完成视角切换全链路（API 逻辑+persistence+DTO）。更新 FamilyMemberService 中的辈分相关逻辑。新增视角切换 API（从当前角色生成目标辈分视角的数据投影）。不重构现有家庭关系图。
  Parallelization: Wave 1 | Blocked by: Phase 2 done | Blocks: 9
  References: GenerationLevel.java, FamilyMemberService (computeEffectiveRole/computeRelativeLabel), 视角切换 API
  Acceptance criteria: ✅ API 可按辈分视角投影家庭成员数据，GenerationLevel 在服务层完整生效
  QA scenarios: done
  Commit: b61cd80f · Verified: 2026-07-23

- [x] 9. 家庭成员辈分重构前端联动 ✅ 完成
  What to do / Must NOT do: 更新前端角色选择器增加辈分选项。联动 FamilyRelationGraph 适配 GenerationLevel 显示。更新 family-members 编辑弹窗。不改已有家庭成员数据结构。
  Parallelization: Wave 2 | Blocked by: 8 | Blocks: —
  References: GenerationPicker.vue (新建替换旧 RelationshipPicker), generationLevel.js (常量映射), FamilyRelationGraph.vue 已适配
  Acceptance criteria: ✅ 角色选择器可选择辈分，关系图按辈分显示不同颜色/层级
  QA scenarios: done
  Commit: b61cd80f · Verified: 2026-07-23

- [x] 10. 文章发布系统（运营审核流程） ✅ 完成
  What to do / Must NOT do: 开发文章审核发布状态机（草稿→待审→已发布→下架）。Web管理端新增文章编辑器（标题/封面/正文/标签/维度选择）。管理端审核列表+审批操作。简化版：不接入公众号自动发布，仅平台内发布。
  Parallelization: Wave 3 | Blocked by: Phase 2 done | Blocks: —
  References: 文章审核状态机 (a6c2f4ea), Web管理端文章编辑器+审核 (138b84a2), 详情弹窗+驳回+批量审批 (a8afcec4)
  Acceptance criteria: ✅ Web管理端可创建、编辑、发布、下架文章；小程序端可见已发布的文章
  QA scenarios: done
  Commit: 32c2c4ff · Verified: 2026-07-23

### PHASE 4: 平台扩展（计划级，不实施）

- [ ] 11. 供应商销售体系实施（计划级 - Phase 4）
  预计内容: 供应商体系建表 + 账期+留利逻辑 + 商品规格最小购买数限制 + 订单修复
  References: specs/2026-07-05-supply-distribution-system-design.md, plans/2026-07-05-supply-distribution-system.md

- [ ] 12. 健康7维子体系模型实施（计划级 - Phase 4）
  预计内容: 7个子维度模型+Schema+API + 前端页面对接
  References: specs/2026-06-26-health-dimensions-design-spec.md, plans/2026-06-27-health-dimensions-incremental-plan.md

- [ ] 13. 成长档案重建实施（计划级 - Phase 4）
  预计内容: 成长档案 CRUD + 新 UI 组件 + 数据迁移
  References: specs/2026-06-22-growth-record-rebuild-design.md

## Final verification wave
> Runs in parallel after ALL todos. ALL must APPROVE. Surface results and wait for the user's explicit okay before declaring complete.
- [ ] F1. Plan compliance (per Phase)
- [ ] F2. Code quality review (per Phase)
- [ ] F3. Real manual QA (per Phase)
- [ ] F4. Scope fidelity (per Phase)

## Commit strategy
- Phase 2 Wave 1: 1 commit (任务1 + 任务3 一起)
- Phase 2 Wave 2: 2 separate commits (任务2, 任务4)
- Phase 2 Wave 3: 1 commit (任务5)
- Phase 3: per-todo commits (5 commits)
- Commit message format: `<type>(<scope>): <summary>`
- Branch: `cfclub` (现有开发分支)

## Success criteria
- ✅ Phase 2: 小程序前端 AI 功能走 LangGraph 通道（Dify fallback 可配置）+ 推广中心页面展示绑定+收益
- ✅ Phase 3: 财富页面按角色展示子维度数据 + 成员关系按辈分显示 + 文章可走审核发布
- ⏳ Phase 4: 供应商体系可下单结算 + 健康7维数据展示 + 新成长档案可用（计划级，尚未实施）