chore: auto bump version and changelog [skip ci]

cfc-web/.last_build_commit

@@ -1 +1 @@
-65760d3da8572d6d32d9e2fc7d1690cc4924779d
+d0133ac91ee50dbbe1d6386130143a21fc3597f4

cfc-web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "cfc-web",
-  "version": "1.0.539",
+  "version": "1.0.540",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "cfc-web",
-      "version": "1.0.539",
+      "version": "1.0.540",
       "dependencies": {
         "@wangeditor/editor": "^5.1.23",
         "@wangeditor/editor-for-vue": "^1.0.2",

cfc-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfc-web",
-  "version": "1.0.540",
+  "version": "1.0.541",
   "private": true,
   "scripts": {
     "dev": "vue-cli-service serve",

cfc-web/public/CHANGELOG-v1.0.md

@@ -4,6 +4,12 @@
 
 ---
 
+## v1.0.541 (2026-07-25)
+
+### Bug 修复
+- products表添加min_quantity列（迁移103）+ schema.sql同步
+
+
 ## v1.0.540 (2026-07-25)
 
 ### Bug 修复

cfc-web/public/CHANGELOG.md

@@ -1,6 +1,6 @@
 # 更新日志
 
-> 当前版本: v1.0.540
+> 当前版本: v1.0.541
 
 ## 历史版本
 
@@ -8,6 +8,12 @@
 
 ---
 
+## v1.0.541 (2026-07-25)
+
+### Bug 修复
+- products表添加min_quantity列（迁移103）+ schema.sql同步
+
+
 ## v1.0.540 (2026-07-25)
 
 ### Bug 修复

docs/flows/activity-flow.md

@@ -0,0 +1,73 @@
+# 用户使用流程图 — 活动管理
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 活动浏览
+        A1(("用户")) --> A2[获取活动列表 /list]
+        A2 --> A3[获取活动详情 /detail]
+    end
+
+    subgraph 报名参与
+        A3 --> B1[报名活动 /register]
+        B1 --> B2[取消报名 /cancel-registration]
+        B2 --> B3[获取我的报名 /my-registrations]
+        B3 --> B4[活动签到 /checkin]
+    end
+
+    subgraph 规划师活动管理
+        A1 --> C1[获取活动列表 /guide/activities/list]
+        C1 --> C2[获取详情 /guide/activities/detail]
+        C2 --> C3[创建活动 /guide/activities/create]
+        C3 --> C4[更新活动 /guide/activities/update]
+        C4 --> C5[发布活动 /guide/activities/publish]
+        C5 --> C6[取消活动 /guide/activities/cancel]
+        C6 --> C7[删除活动 /guide/activities/delete]
+    end
+
+    subgraph 管理员审核
+        C5 --> D1[活动审核 /admin/activity/review]
+        D1 --> D2[提交审核 /admin/activity/submit-review]
+        D2 --> D3[审批通过/驳回 /admin/activity/audit]
+        D3 --> D4[撤回审核 /admin/activity/withdraw]
+        D4 --> D5[重新编辑 /admin/activity/re-draft]
+    end
+
+    R1(("👤 用户/规划师")):::actor
+    R2(("🔧 管理员")):::role
+
+    A1 -.- R1
+    D1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/activity/list` | 活动列表 |
+| `/api/activity/detail` | 活动详情 |
+| `/api/activity/create` | 创建活动 |
+| `/api/activity/update` | 更新活动 |
+| `/api/activity/publish` | 发布活动 |
+| `/api/activity/end` | 结束活动 |
+| `/api/activity/register` | 报名活动 |
+| `/api/activity/cancel-registration` | 取消报名 |
+| `/api/activity/my-registrations` | 我的报名 |
+| `/api/activity/checkin` | 签到 |
+| `/api/guide/activities/list` | 规划师活动列表 |
+| `/api/guide/activities/detail` | 规划师活动详情 |
+| `/api/guide/activities/create` | 创建活动(规划师) |
+| `/api/guide/activities/update` | 更新活动 |
+| `/api/guide/activities/publish` | 发布活动 |
+| `/api/guide/activities/cancel` | 取消活动 |
+| `/api/guide/activities/delete` | 删除活动 |
+| `/api/admin/activity/list` | 管理员活动列表 |
+| `/api/admin/activity/review` | 活动审核 |
+| `/api/admin/activity/audit` | 审批操作 |

docs/flows/admin-overview-flow.md

@@ -0,0 +1,113 @@
+# 用户使用流程图 — 管理后台
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 管理员登录
+        A1(("管理员")) --> A2[发送验证码 /send-code]
+        A2 --> A3[登录 /login]
+        A3 --> A4[获取信息 /info]
+        A4 --> A5[修改密码 /change-password]
+        A5 --> A6[密码登录 /login-by-password]
+    end
+
+    subgraph 用户管理
+        A6 --> B1[用户列表 /admin/users]
+        B1 --> B2[创建用户 /admin/users/create]
+        B2 --> B3[用户详情 /admin/users/{id}]
+        B3 --> B4[更新用户 /admin/users/{id}/update]
+        B4 --> B5[重置密码 /admin/users/{id}/reset-password]
+        B5 --> B6[搜索用户 /admin/user/search]
+        B6 --> B7[删除用户 /admin/users/{id}/delete]
+    end
+
+    subgraph 孩子管理
+        B7 --> C1[孩子列表 /admin/children]
+        C1 --> C2[详情 /admin/children/{id}]
+        C2 --> C3[更新 /admin/children/{id}/update]
+        C3 --> C4[调整积分 /admin/children/{id}/adjust-points]
+    end
+
+    subgraph 家庭管理
+        C4 --> D1[家庭列表 /admin/families]
+        D1 --> D2[详情 /admin/families/{id}]
+        D2 --> D3[成员 /admin/families/{id}/members]
+        D3 --> D4[更新 /admin/families/{id}/update]
+        D4 --> D5[删除 /admin/families/{id}/delete]
+    end
+
+    subgraph 任务审核
+        D5 --> E1[任务列表 /admin/tasks]
+        E1 --> E2[任务统计 /admin/tasks/stats]
+    end
+
+    subgraph 奖励审核
+        E2 --> F1[奖励列表 /admin/rewards]
+        F1 --> F2[模板列表 /admin/rewards/templates]
+        F2 --> F3[创建模板 /admin/rewards/create]
+        F3 --> F4[审批 /admin/rewards/{id}/approve]
+    end
+
+    subgraph 积分管理
+        F4 --> G1[积分日志 /admin/points/logs]
+        G1 --> G2[积分统计 /admin/points/stats]
+    end
+
+    subgraph 任务模板管理
+        G2 --> H1[模板列表 /admin/task-templates]
+        H1 --> H2[创建 /admin/task-templates/create]
+    end
+
+    subgraph 规划师审核
+        H2 --> I1[待审批列表 /admin/guide/applications/pending]
+        I1 --> I2[审批通过 /admin/guide/applications/{id}/approve]
+        I2 --> I3[驳回 /admin/guide/applications/{id}/reject]
+        I3 --> I4[列表 /admin/guide/guides]
+    end
+
+    subgraph 商品审核
+        I4 --> J1[商品列表 /admin/product/list]
+        J1 --> J2[审核商品 /admin/product/review]
+        J2 --> J3[上下架 /admin/product/shelve]
+    end
+
+    subgraph 订单管理
+        J3 --> K1[订单列表 /admin/product/order/list]
+        K1 --> K2[发货 /admin/product/order/ship]
+        K2 --> K3[退款审核 /admin/product/order/refund/approve]
+    end
+
+    subgraph 系统管理
+        K3 --> L1[健康检查 /system/health]
+    end
+
+    R1(("🔧 管理员")):::actor
+    R2(("📊 统计系统")):::system
+
+    A1 -.- R1
+    E2 -.- R2
+```
+
+## 主要管理端点
+
+| 领域 | 端点示例 | 说明 |
+|------|----------|------|
+| 认证 | `/api/admin-auth/login` | 管理员登录 |
+| 用户 | `/api/admin/users` | 用户管理 |
+| 孩子 | `/api/admin/children` | 孩子管理 |
+| 家庭 | `/api/admin/families` | 家庭管理 |
+| 任务 | `/api/admin/tasks` | 任务管理 |
+| 奖励 | `/api/admin/rewards` | 奖励审批 |
+| 积分 | `/api/admin/points/logs` | 积分管理 |
+| 模板 | `/api/admin/task-templates` | 任务模板 |
+| 规划师 | `/api/admin/guide/applications/pending` | 规划师审批 |
+| 商品 | `/api/admin/product/review` | 商品审核 |
+| 订单 | `/api/admin/product/order/list` | 订单管理 |
+| 健康 | `/api/system/health` | 运行状态 |

docs/flows/ai-assistant-flow.md

@@ -0,0 +1,82 @@
+# 用户使用流程图 — AI助手
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph AI聊天
+        A1(("用户")) --> A2[发送聊天消息 /chat/send]
+        A2 --> A3{消息类型}
+        A3 -->|普通咨询| A4[Dify AI 响应]
+        A3 -->|报告解读| A5[传入reportId]
+        A5 --> A6[AI解读健康报告指标]
+        A4 --> A7[返回AI回答]
+        A6 --> A7
+    end
+
+    subgraph 会话管理
+        A7 --> B1[获取会话列表 /chat/conversations]
+        B1 --> B2[获取消息历史 /chat/messages]
+        B2 --> B3[删除会话 /chat/conversations/{id}/delete]
+    end
+
+    subgraph AI营养分析
+        B3 --> C1[发送营养分析 /nutrition/send]
+        C1 --> C2[基于菌群报告]
+        C2 --> C3[AI生成营养建议]
+    end
+
+    subgraph AI管家
+        C3 --> D1[创建新会话 /sessions/create]
+        D1 --> D2[更新Dify会话ID /sessions/update-conversation]
+        D2 --> D3[归档会话 /sessions/archive]
+        D3 --> D4[获取会话列表 /sessions/list]
+        D4 --> D5[会话详情 /sessions/detail]
+        D5 --> D6[删除会话 /sessions/delete]
+    end
+
+    subgraph AI上下文
+        D6 --> E1[供LangGraph调用的上下文 /api/ai/context]
+    end
+
+    subgraph AI推荐
+        E1 --> F1[按标签搜索推荐 /recommend/search]
+        F1 --> F2[获取复购提醒 /recommend/repurchase-reminders]
+        F2 --> F3[标记提醒已点击 /repurchase-reminder/{id}/click]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🤖 Dify AI引擎")):::system
+
+    A1 -.- R1
+    A4 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/ai/chat/send` | 发送聊天消息 |
+| `/api/ai/chat/conversations` | 会话列表 |
+| `/api/ai/chat/messages` | 消息历史 |
+| `/api/ai/chat/conversations/{id}/delete` | 删除会话 |
+| `/api/ai/nutrition/send` | 营养分析消息 |
+| `/api/ai/butler/sessions/create` | 创建AI管家会话 |
+| `/api/ai/butler/sessions/update-conversation` | 更新会话ID |
+| `/api/ai/butler/sessions/archive` | 归档会话 |
+| `/api/ai/butler/sessions/list` | 会话列表 |
+| `/api/ai/butler/sessions/detail` | 会话详情 |
+| `/api/ai/butler/sessions/delete` | 删除会话 |
+| `/api/ai/context` | AI上下文数据 |
+| `/api/recommend/search` | 营养标签搜索 |
+| `/api/recommend/repurchase-reminders` | 复购提醒 |
+| `/api/recommend/repurchase-reminder/{id}/click` | 标记已点击 |
+| `/api/feedback/today` | 获取今日AI反馈 |
+| `/api/feedback/read` | 标记已读 |
+| `/api/feedback/recent` | 最近反馈列表 |

docs/flows/badge-microaction-flow.md

@@ -0,0 +1,65 @@
+# 用户使用流程图 — 勋章与微行动
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 勋章浏览
+        A1(("用户")) --> A2[获取启用的勋章列表 /list]
+        A2 --> A3[获取勋章详情 /detail]
+        A3 --> A4[收藏/取消收藏 /favorite]
+    end
+
+    subgraph 勋章获得
+        A4 --> B1[获取孩子勋章列表 /child/list]
+        B1 --> B2[孩子勋章统计 /statistics/child]
+        B2 --> B3[家庭勋章排行 /ranking/family]
+    end
+
+    subgraph 管理员授勋
+        B3 --> C1[获取所有勋章 /all]
+        C1 --> C2[创建勋章 /create]
+        C2 --> C3[更新勋章 /update]
+        C3 --> C4[删除勋章 /delete]
+        C4 --> C5[手动授予勋章 /grant]
+    end
+
+    subgraph 微行动
+        A1 --> D1[获取所有微行动列表 /micro-action/list]
+        D1 --> D2[获取今日推荐 /micro-action/today]
+        D2 --> D3[完成微行动 /micro-action/complete]
+        D3 --> D4[检查今日完成 /micro-action/check-today]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🔧 管理员")):::role
+
+    A1 -.- R1
+    C1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/badges/list` | 启用的勋章列表 |
+| `/api/badges/all` | 所有勋章(管理端) |
+| `/api/badges/detail` | 勋章详情 |
+| `/api/badges/create` | 创建勋章 |
+| `/api/badges/update` | 更新勋章 |
+| `/api/badges/delete` | 删除勋章 |
+| `/api/badges/grant` | 手动授予勋章 |
+| `/api/badges/child/list` | 孩子勋章列表 |
+| `/api/badges/favorite` | 收藏/取消 |
+| `/api/badges/statistics/child` | 孩子勋章统计 |
+| `/api/badges/ranking/family` | 家庭勋章排行 |
+| `/api/micro-action/list` | 微行动列表 |
+| `/api/micro-action/today` | 今日推荐 |
+| `/api/micro-action/complete` | 完成微行动 |
+| `/api/micro-action/check-today` | 检查今日完成 |

docs/flows/cart-coupon-flow.md

@@ -0,0 +1,58 @@
+# 用户使用流程图 — 购物车与优惠券
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 购物车
+        A1(("用户")) --> A2[添加购物车 /cart/add]
+        A2 --> A3[获取购物车列表 /cart/list]
+        A3 --> A4[更新数量 /cart/update]
+        A4 --> A5[移除商品 /cart/remove]
+        A5 --> A6[获取数量 /cart/count]
+    end
+
+    subgraph 优惠券
+        A6 --> B1[获取可用优惠券 /coupon/list]
+        B1 --> B2[领取优惠券 /coupon/claim]
+        B2 --> B3[应用优惠券 /coupon/apply]
+    end
+
+    subgraph 管理员优惠券
+        B3 --> C1[优惠券列表 /admin/coupon/list]
+        C1 --> C2[创建优惠券 /admin/coupon/create]
+        C2 --> C3[更新 /admin/coupon/update]
+        C3 --> C4[发放 /admin/coupon/issue]
+        C4 --> C5[删除 /admin/coupon/delete]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🔧 管理员")):::role
+
+    A1 -.- R1
+    C1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/cart/add` | 添加购物车 |
+| `/api/cart/list` | 购物车列表 |
+| `/api/cart/update` | 更新购物车 |
+| `/api/cart/remove` | 移除商品 |
+| `/api/cart/count` | 购物车数量 |
+| `/api/coupon/list` | 优惠券列表 |
+| `/api/coupon/claim` | 领取优惠券 |
+| `/api/coupon/apply` | 应用优惠券 |
+| `/api/admin/coupon/list` | 管理优惠券列表 |
+| `/api/admin/coupon/create` | 创建优惠券 |
+| `/api/admin/coupon/update` | 更新优惠券 |
+| `/api/admin/coupon/issue` | 发放优惠券 |
+| `/api/admin/coupon/delete` | 删除优惠券 |

docs/flows/circle-contact-flow.md

@@ -0,0 +1,98 @@
+# 用户使用流程图 — 圈子与联系人
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 圈子管理
+        A1(("用户")) --> A2[获取我的圈子 /my-circles]
+        A2 --> A3[发现圈子 /discover]
+        A3 --> A4[加入圈子 /join]
+        A4 --> A5[退出圈子 /leave]
+        A5 --> A6[创建圈子 /create]
+    end
+
+    subgraph 健康圈子
+        A6 --> B1[获取健康圈子列表 /health/circle/list]
+        B1 --> B2[创建健康圈子 /health/circle/create]
+        B2 --> B3[加入 /health/circle/join]
+        B3 --> B4[退出 /health/circle/leave]
+        B4 --> B5[排行榜 /health/circle/ranking]
+    end
+
+    subgraph 圈子挑战
+        B5 --> C1[挑战列表 /health/circle/challenge/list]
+        C1 --> C2[挑战历史 /health/circle/challenge/history]
+    end
+
+    subgraph 家庭挑战
+        C2 --> D1[家庭挑战列表 /health/challenge/list]
+        D1 --> D2[挑战历史 /health/challenge/history]
+        D2 --> D3[挑战进度 /health/challenge/progress]
+    end
+
+    subgraph 联系人
+        A1 --> E1[获取联系人列表 /contact/list]
+        E1 --> E2[创建联系人 /contact/create]
+        E2 --> E3[更新联系人 /contact/update]
+        E3 --> E4[删除联系人 /contact/delete]
+        E4 --> E5[获取详情 /contact/detail]
+        E5 --> E6[导入手机联系人 /contact/import-phone]
+        E6 --> E7[记录互动 /contact/interaction]
+        E7 --> E8[邀请到家庭 /contact/invite-to-family]
+    end
+
+    subgraph 联系人匹配
+        E8 --> F1[发送匹配请求 /contact/match/send]
+        F1 --> F2[接受匹配 /contact/match/accept]
+        F2 --> F3[拒绝匹配 /contact/match/reject]
+        F3 --> F4[收到的请求 /contact/match/received]
+        F4 --> F5[发出的请求 /contact/match/sent]
+        F5 --> F6[已匹配 /contact/match/matched]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🤝 社交系统")):::system
+
+    A1 -.- R1
+    E1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/circle/my-circles` | 我的圈子 |
+| `/api/circle/discover` | 发现圈子 |
+| `/api/circle/join` | 加入圈子 |
+| `/api/circle/leave` | 退出圈子 |
+| `/api/circle/create` | 创建圈子 |
+| `/api/health/circle/list` | 健康圈子列表 |
+| `/api/health/circle/create` | 创建健康圈子 |
+| `/api/health/circle/join` | 加入健康圈子 |
+| `/api/health/circle/leave` | 退出健康圈子 |
+| `/api/health/circle/ranking` | 健康圈子排行 |
+| `/api/health/circle/challenge/list` | 挑战列表 |
+| `/api/health/circle/challenge/history` | 挑战历史 |
+| `/api/health/challenge/list` | 家庭挑战列表 |
+| `/api/health/challenge/history` | 家庭挑战历史 |
+| `/api/health/challenge/progress` | 挑战进度 |
+| `/api/health/family/ranking` | 家庭健康排行 |
+| `/api/contact/list` | 联系人列表 |
+| `/api/contact/create` | 创建联系人 |
+| `/api/contact/update` | 更新联系人 |
+| `/api/contact/delete` | 删除联系人 |
+| `/api/contact/detail` | 联系人详情 |
+| `/api/contact/import-phone` | 导入手机联系人 |
+| `/api/contact/interaction` | 记录互动 |
+| `/api/contact/invite-to-family` | 邀请到家庭 |
+| `/api/contact/match/send` | 发送匹配 |
+| `/api/contact/match/accept` | 接受匹配 |
+| `/api/contact/match/reject` | 拒绝匹配 |
+| `/api/contact/match/matched` | 已匹配 |

docs/flows/content-media-flow.md

@@ -0,0 +1,82 @@
+# 用户使用流程图 — 内容与媒体
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616111,stroke-width:1px,shape:box
+
+    subgraph 文章浏览
+        A1(("用户")) --> A2[获取文章列表 /list]
+        A2 --> A3[获取文章分类 /categories]
+        A3 --> A4[获取文章详情 /detail]
+        A4 --> A5[获取精选文章 /featured]
+        A5 --> A6[记录阅读 /record-read]
+        A6 --> A7[获取阅读统计 /reading-stats]
+    end
+
+    subgraph 每日贴士
+        A7 --> B1[获取每日贴士 /daily-tip]
+        B1 --> B2[获取AI问题列表 /ai-questions]
+        B2 --> B3[提交答案 /submit-answers]
+    end
+
+    subgraph 内容发布
+        B3 --> C1[发布文章 /publish]
+        C1 --> C2[获取我的帖子 /my-posts]
+    end
+
+    subgraph 内容分享
+        C2 --> D1[创建分享记录 /share/create]
+        D1 --> D2[记录点击 /share/click]
+        D2 --> D3[记录阅读 /share/read]
+        D3 --> D4[获取我的分享 /share/my]
+        D4 --> D5[获取分享统计 /share/stats]
+        D5 --> D6[获取家庭足迹 /share/family-footprint]
+    end
+
+    subgraph 媒体管理
+        D6 --> E1[上传媒体文件 /media/upload]
+        E1 --> E2[保存文字记录 /media/upload-text]
+        E2 --> E3[获取任务媒体 /media/task/{taskId}]
+        E3 --> E4[删除媒体 /media/{mediaId}]
+        E4 --> E5[批量关联 /media/attach]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("📱 分享系统")):::system
+
+    A1 -.- R1
+    D1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/articles/list` | 文章列表 |
+| `/api/articles/categories` | 文章分类 |
+| `/api/articles/detail` | 文章详情 |
+| `/api/articles/featured` | 精选文章 |
+| `/api/articles/record-read` | 记录阅读 |
+| `/api/articles/reading-stats` | 阅读统计 |
+| `/api/articles/daily-tip` | 每日贴士 |
+| `/api/articles/ai-questions` | AI问题列表 |
+| `/api/articles/submit-answers` | 提交答案 |
+| `/api/articles/publish` | 发布文章 |
+| `/api/articles/my-posts` | 我的帖子 |
+| `/api/share/create` | 创建分享 |
+| `/api/share/click` | 记录点击 |
+| `/api/share/read` | 记录阅读 |
+| `/api/share/my` | 我的分享 |
+| `/api/share/stats` | 分享统计 |
+| `/api/share/family-footprint` | 家庭足迹 |
+| `/api/media/upload` | 上传媒体 |
+| `/api/media/upload-text` | 保存文字 |
+| `/api/media/task/{taskId}` | 任务媒体 |
+| `/api/media/{mediaId}` | 删除媒体 |
+| `/api/media/attach` | 批量关联 |

docs/flows/energy-system-flow.md

@@ -0,0 +1,76 @@
+# 用户使用流程图 — 五维能量沙盘
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 能量概览
+        A1(("家长/孩子")) --> A2[获取能量沙盘 /sandbox]
+        A2 --> A3[获取五维概览 /overview]
+        A3 --> A4[获取家庭五维聚合 /family-score-history]
+        A4 --> A5[获取五维分数历史 /score-history]
+    end
+
+    subgraph 能量流水
+        A5 --> B1[查询能量流水 /logs]
+        B1 --> B2[获取富维度详情 /wealth-detail]
+    end
+
+    subgraph 能量操作
+        A3 --> C1[发放能量 /grant]
+        C1 --> C2[心愿兑换扣除 /deduct-for-wish]
+        C2 --> C3[配置来源比例 /configure]
+    end
+
+    subgraph 维度管理
+        C3 --> D1[获取维度概览 /overview]
+        D1 --> D2[手动录入维度 /upload]
+        D2 --> D3[问卷提交维度 /questionnaire]
+        D3 --> D4[获取维度历史 /history]
+    end
+
+    subgraph 年度能量
+        D4 --> E1[获取年度五维能量 /energy]
+    end
+
+    subgraph 家庭收入
+        C3 --> F1[获取家庭收入汇总 /family/summary]
+        F1 --> F2[获取成员收入 /family/members]
+        F2 --> F3[获取收入记录 /family/records]
+    end
+
+    R1(("👤 家长/孩子")):::actor
+    R2(("🌍 五维引擎")):::system
+
+    A1 -.- R1
+    A2 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 控制器 | 说明 |
+|------|--------|------|
+| `/api/energy/sandbox` | EnergyController | 获取能量沙盘 |
+| `/api/energy/overview` | EnergyController | 获取五维概览 |
+| `/api/energy/logs` | EnergyController | 查询能量流水 |
+| `/api/energy/grant` | EnergyController | 发放能量 |
+| `/api/energy/deduct-for-wish` | EnergyController | 心愿扣除能量 |
+| `/api/energy/configure` | EnergyController | 配置来源比例 |
+| `/api/energy/score-history` | EnergyController | 五维分数历史 |
+| `/api/energy/family-score-history` | EnergyController | 家庭五维聚合 |
+| `/api/energy/wealth-detail` | EnergyController | 富维度详情 |
+| `/api/energy/seed` | SeedEnergyController | 生成种子数据 |
+| `/api/zodiac/energy` | ZodiacEnergyController | 年度五维能量 |
+| `/api/dimension/overview` | HealthDimensionController | 维度概览 |
+| `/api/dimension/upload` | HealthDimensionController | 手动录入维度 |
+| `/api/dimension/questionnaire` | HealthDimensionController | 问卷提交 |
+| `/api/dimension/history` | HealthDimensionController | 维度历史 |
+| `/api/earnings/family/summary` | FamilyEarningsController | 家庭收入汇总 |
+| `/api/earnings/family/members` | FamilyEarningsController | 成员收入 |
+| `/api/earnings/family/records` | FamilyEarningsController | 收入记录 |

docs/flows/extra-features-flow.md

@@ -0,0 +1,70 @@
+# 用户使用流程图 — 其他功能
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 用户吉祥物
+        A1(("用户")) --> A2[设置吉祥物 /user/mascot/set]
+        A2 --> A3[获取吉祥物 /user/mascot/get]
+    end
+
+    subgraph 用户分群
+        A3 --> B1[RFM计算 /segmentation/rfm/calculate]
+        B1 --> B2[RFM详情 /segmentation/rfm/detail]
+        B2 --> B3[触发规则 /segmentation/trigger/rules]
+    end
+
+    subgraph 外部同步
+        B3 --> C1[同步客户到zkxz /sncp/addClient/{clientId}]
+        C1 --> C2[获取通知 /sncp/notice/{userLogin}]
+    end
+
+    subgraph 每日反馈
+        C2 --> D1[获取今日反馈 /feedback/today]
+        D1 --> D2[标记已读 /feedback/read]
+        D2 --> D3[获取最近反馈 /feedback/recent]
+    end
+
+    subgraph 健康互动
+        D3 --> E1[点赞 /health/interact/like]
+    end
+
+    subgraph 商品推荐
+        E1 --> F1[维度页推荐 /recommend/dimension-products]
+    end
+
+    subgraph 通用工具
+        F1 --> G1[生成小程序码 /common/qrcode]
+    end
+
+    R1(("👤 用户")):::actor
+
+    A1 -.- R1
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/user/mascot/set` | 设置吉祥物 |
+| `/api/user/mascot/get` | 获取吉祥物 |
+| `/api/segmentation/rfm/calculate` | RFM计算 |
+| `/api/segmentation/rfm/detail` | RFM详情 |
+| `/api/segmentation/trigger/rules` | 触发规则 |
+| `/api/sncp/addClient/{clientId}` | 同步客户 |
+| `/api/sncp/notice/{userLogin}` | 获取通知 |
+| `/api/feedback/today` | 今日反馈 |
+| `/api/feedback/read` | 标记已读 |
+| `/api/feedback/recent` | 最近反馈 |
+| `/api/health/interact/like` | 点赞 |
+| `/api/recommend/dimension-products` | 维度推荐 |
+| `/api/common/qrcode` | 生成小程序码 |
+| `/api/onboarding/progress` | 引导进度 |
+| `/api/onboarding/claim` | 领取奖励 |

docs/flows/family-management-flow.md

@@ -0,0 +1,105 @@
+# 用户使用流程图 — 家庭管理
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 家庭创建与加入
+        A1(("家长")) --> A2{是否有家庭?}
+        A2 -->|无| A3[创建新家庭 /create-family]
+        A2 -->|有| A4[加入其他家庭 /join-family]
+        A3 --> A5[生成邀请码 /qrcode]
+        A4 --> A6[通过邀请码加入 /accept-by-code]
+        A5 --> A7[生成家庭邀请二维码 /generate]
+        A7 --> A8[校验邀请令牌 /validate]
+        A8 --> A9[接受邀请 /accept]
+    end
+
+    subgraph 家庭成员管理
+        A9 --> B1[添加家庭成员 /add]
+        B1 --> B2[获取家庭成员列表 /list]
+        B2 --> B3[更新成员信息 /update]
+        B3 --> B4[切换到成员视图 /switch]
+        B4 --> B5[检查成员可编辑性 /editable]
+        B5 --> B6[踢出成员 /kick]
+        B6 --> B7[成员变更日志 /logs]
+    end
+
+    subgraph 家庭设置
+        B7 --> C1[转让家庭管理员 /transfer-admin]
+        C1 --> C2[查询家庭状态 /check-family]
+        C2 --> C3[吊销邀请链接 /revoke]
+    end
+
+    subgraph 家庭关系管理
+        C3 --> D1[AI生成关系问卷 /generate]
+        D1 --> D2[提交问卷答案 /submit]
+        D2 --> D3[获取关系质量评分 /scores]
+        D3 --> D4[计算保存评分 /calculate]
+        D4 --> D5[获取健康预警 /health-alerts]
+        D5 --> D6[获取里程碑 /milestones]
+        D6 --> D7[互动记录 /add]
+        D7 --> D8[互动列表 /list]
+    end
+
+    subgraph 家长绑定指导师
+        C3 --> E1[确认绑定指导师 /accept]
+        E1 --> E2[获取绑定指导师列表 /guides]
+        E2 --> E3[解除绑定 /unbind]
+    end
+
+    R1(("👤 家长")):::actor
+    R2(("👶 孩子")):::role
+    R3(("👨‍🏫 规划师")):::role
+
+    B2 -.- R2
+    E2 -.- R3
+```
+
+## 端点明细
+
+| 端点 | 控制器 | 说明 |
+|------|--------|------|
+| `/api/family/user/create-family` | FamilyUserController | 创建新家庭 |
+| `/api/family/user/join-family` | FamilyUserController | 加入家庭 |
+| `/api/family/user/info` | FamilyUserController | 获取用户信息 |
+| `/api/family/user/update` | FamilyUserController | 更新用户信息 |
+| `/api/family/user/children` | FamilyUserController | 创建孩子 |
+| `/api/family/user/children/list` | FamilyUserController | 获取孩子列表 |
+| `/api/family/user/kick` | FamilyUserController | 踢出家庭成员 |
+| `/api/family/user/switch-role` | FamilyUserController | 切换角色 |
+| `/api/family/user/roles` | FamilyUserController | 获取角色列表 |
+| `/api/family/user/members/visible` | FamilyUserController | 可见成员列表 |
+| `/api/family/invite/generate` | FamilyInviteController | 生成邀请 |
+| `/api/family/invite/qrcode` | FamilyInviteController | 生成邀请二维码 |
+| `/api/family/invite/accept-by-code` | FamilyInviteController | 通过邀请码加入 |
+| `/api/family/invite/validate` | FamilyInviteController | 校验邀请令牌 |
+| `/api/family/invite/accept` | FamilyInviteController | 接受邀请 |
+| `/api/family/invite/revoke` | FamilyInviteController | 吊销邀请 |
+| `/api/family/invite/transfer-admin` | FamilyInviteController | 转让管理员 |
+| `/api/family/member/add` | FamilyMembersController | 添加家庭成员 |
+| `/api/family/member/list` | FamilyMembersController | 获取成员列表 |
+| `/api/family/member/switch` | FamilyMembersController | 切换成员视图 |
+| `/api/family/member/kick` | FamilyMembersController | 踢出成员 |
+| `/api/family/member/update` | FamilyMembersController | 更新成员信息 |
+| `/api/family/member/editable` | FamilyMembersController | 检查可编辑性 |
+| `/api/family/member/logs` | FamilyMembersController | 变更日志 |
+| `/api/bind/accept` | BindController | 确认绑定指导师 |
+| `/api/bind/guides` | BindController | 获取绑定指导师 |
+| `/api/bind/unbind` | BindController | 解除绑定规划师 |
+| `/api/family/relationship/scores` | RelationshipQualityController | 关系质量评分 |
+| `/api/family/relationship/calculate` | RelationshipQualityController | 计算评分 |
+| `/api/family/relationship/health-alerts` | RelationshipQualityController | 健康预警 |
+| `/api/family/relationship/milestones` | RelationshipQualityController | 里程碑 |
+| `/api/family/questionnaire/generate` | RelationshipQuestionnaireController | AI生成问卷 |
+| `/api/family/questionnaire/submit` | RelationshipQuestionnaireController | 提交问卷 |
+| `/api/family/interaction/add` | InteractionLogController | 添加互动记录 |
+| `/api/family/interaction/list` | InteractionLogController | 互动记录列表 |
+| `/api/family/teacher-bindings/pending` | TeacherFamilyBindingController | 待审批绑定 |
+| `/api/family/teacher-bindings/approve` | TeacherFamilyBindingController | 审批通过 |

docs/flows/growth-record-flow.md

@@ -0,0 +1,82 @@
+# 用户使用流程图 — 成长档案
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 成长档案创建
+        A1(("家长")) --> A2{创建方式}
+        A2 -->|手动创建| A3[创建成长档案 /record/create]
+        A2 -->|上传PDF报告| A4[上传测评报告PDF /upload-and-parse]
+        A2 -->|创建并购买测评| A5[创建档案+购买 /create-with-order]
+        A4 --> A6[PDF解析引擎 (Stage 1)]
+        A6 --> A7{是否重复?}
+        A7 -->|重复| A8[检查哈希去重 /check-duplicate]
+        A7 -->|新记录| A9[创建成长档案 (Stage 2) /create-from-upload]
+        A3 --> A10[录入基础信息]
+        A9 --> A10
+    end
+
+    subgraph 补充材料
+        A10 --> B1[创建补充记录 /supplement]
+        B1 --> B2[获取补充记录列表 /{id}/supplements]
+    end
+
+    subgraph 外部数据同步
+        A10 --> C1[外部系统测评同步 /external/sync]
+        C1 --> C2[数据融合]
+    end
+
+    subgraph 查询与管理
+        C2 --> D1[获取家长的成长档案列表 /list]
+        D1 --> D2[获取指定孩子的档案 /child/{childId}]
+        D2 --> D3[获取孩子的档案 /child-records]
+        D3 --> D4[获取档案详情 /{id}]
+        D4 --> D5[删除成长档案 /{id}/delete]
+    end
+
+    subgraph 生长记录
+        D1 --> E1[获取生长记录列表 /list]
+        E1 --> E2[获取生长记录详情 /detail]
+        E2 --> E3[创建生长记录 /create]
+        E3 --> E4[更新生长记录 /update]
+        E4 --> E5[删除生长记录 /delete]
+    end
+
+    R1(("👤 家长")):::actor
+    R2(("👶 孩子")):::role
+    R3(("📄 PDF解析引擎")):::system
+
+    A1 -.- R1
+    D2 -.- R2
+    A6 -.- R3
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/growth/record/create` | 创建成长档案 |
+| `/api/growth/record/create-with-order` | 创建档案并购买测评 |
+| `/api/growth/record/list` | 获取家长的档案列表 |
+| `/api/growth/record/child/{childId}` | 获取指定孩子档案 |
+| `/api/growth/record/child-records` | 获取孩子的成长档案 |
+| `/api/growth/record/{id}` | 获取档案详情 |
+| `/api/growth/record/{id}/delete` | 删除成长档案 |
+| `/api/growth/external/sync` | 外部系统同步 |
+| `/api/growth/record/upload-and-parse` | 上传并解析PDF |
+| `/api/growth/record/create-from-upload` | 创建成长档案（从上传） |
+| `/api/growth/record/supplement` | 创建补充记录 |
+| `/api/growth/record/check-duplicate` | 检查重复记录 |
+| `/api/growth/record/{id}/supplements` | 获取补充记录 |
+| `/api/health/growth/list` | 获取生长记录列表 |
+| `/api/health/growth/detail` | 获取生长记录详情 |
+| `/api/health/growth/create` | 创建生长记录 |
+| `/api/health/growth/update` | 更新生长记录 |
+| `/api/health/growth/delete` | 删除生长记录 |

docs/flows/growth-task-flow.md

@@ -0,0 +1,33 @@
+# 用户使用流程图 — 成长任务
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 成长任务
+        A1(("孩子")) --> A2[获取成长任务列表 /list]
+        A2 --> A3{任务状态}
+        A3 -->|可领取| A4[领取任务 /claim]
+        A3 -->|动态任务| A5[接受动态任务 /accept-dynamic]
+        A4 --> A6[执行成长任务]
+        A5 --> A6
+    end
+
+    R1(("👶 孩子")):::actor
+
+    A1 -.- R1
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/growth-task/list` | 成长任务列表 |
+| `/api/growth-task/claim` | 领取任务 |
+| `/api/growth-task/accept-dynamic` | 接受动态任务 |

docs/flows/guide-system-flow.md

@@ -0,0 +1,127 @@
+# 用户使用流程图 — 成长规划师体系
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 规划师入驻
+        A1(("成长规划师")) --> A2{是否已注册}
+        A2 -->|否| A3[规划师注册 /register]
+        A3 --> A4[提交申请 /application/submit]
+        A4 --> A5[管理员审批]
+        A5 --> A6{审批结果}
+        A6 -->|通过| A7[规划师激活]
+        A6 -->|驳回| A8[撤回申请 /withdraw]
+        A8 --> A9[重新提交 /resubmit]
+        A7 --> A10[获取申请记录 /applications]
+    end
+
+    subgraph 团队管理
+        A10 --> B1[获取我的团队 /my-team]
+        B1 --> B2[获取邀请码 /invite-code]
+        B2 --> B3[生成邀请码 /invite-code/generate]
+        B3 --> B4[获取成员列表 /members]
+        B4 --> B5[通过邀请码加入 /join-by-invite]
+        B5 --> B6[检查邀请状态 /check-status]
+        B6 --> B7[离开团队 /leave]
+        B7 --> B8[获取团队统计 /stats]
+    end
+
+    subgraph 绑定家庭
+        A10 --> C1[生成绑定邀请 /invite]
+        C1 --> C2[校验邀请 /validate]
+        C2 --> C3[家长审批绑定]
+        C3 --> C4[获取绑定家庭列表 /bound-families]
+    end
+
+    subgraph 任务模板管理
+        C4 --> D1[获取我的模板 /my]
+        D1 --> D2[创建模板 /create]
+        D2 --> D3[更新模板 /update]
+        D3 --> D4[更新状态 /update-status]
+        D4 --> D5[删除模板 /delete]
+        D5 --> D6[增加销量 /increment-sales]
+        D6 --> D7[获取模板列表 /templates]
+    end
+
+    subgraph 训练方案
+        C4 --> E1[获取方案列表 /list]
+        E1 --> E2[创建方案 /create]
+        E2 --> E3[添加项目 /items/add]
+        E3 --> E4[从推荐生成 /generate-from-recommendations]
+        E4 --> E5[下发方案 /deploy]
+        E5 --> E6[执行看板 /execution-board]
+        E6 --> E7[删除方案 /delete]
+    end
+
+    subgraph 咨询消息
+        C4 --> F1[家长发送咨询 /send]
+        F1 --> F2[规划师回复 /{messageId}/reply]
+        F2 --> F3[咨询列表 /list]
+        F3 --> F4[未读消息数 /unread-count]
+    end
+
+    subgraph 订单佣金
+        C4 --> G1[获取订单列表 /list]
+        G1 --> G2[获取订单统计 /stats]
+        G2 --> G3[获取订单详情 /detail]
+    end
+
+    R1(("📋 成长规划师")):::actor
+    R2(("👤 家长")):::role
+    R3(("🔧 管理员")):::role
+
+    A1 -.- R1
+    C3 -.- R2
+    A5 -.- R3
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/guide/register` | 规划师注册 |
+| `/api/guide/application/submit` | 提交申请 |
+| `/api/guide/application/withdraw` | 撤回申请 |
+| `/api/guide/application/resubmit` | 重新提交 |
+| `/api/guide/applications` | 申请列表 |
+| `/api/guide/invite-code/generate` | 生成邀请码 |
+| `/api/guide/invite-codes` | 邀请码列表 |
+| `/api/guide/invite-code/validate` | 验证邀请码 |
+| `/api/guide/child-guides` | 下级规划师列表 |
+| `/api/guide/parent-guide` | 上级规划师 |
+| `/api/guide/package/add` | 添加任务模板 |
+| `/api/guide/package/{packageId}` | 查看模板定价 |
+| `/api/guide/team/my-team` | 获取团队 |
+| `/api/guide/team/invite-code` | 团队邀请码 |
+| `/api/guide/team/members` | 团队成员 |
+| `/api/guide/team/join-by-invite` | 通过邀请码加入 |
+| `/api/guide/team/leave` | 离开团队 |
+| `/api/guide/team/stats` | 团队统计 |
+| `/api/guide/bind/invite` | 生成绑定邀请 |
+| `/api/guide/bind/validate` | 校验邀请 |
+| `/api/guide/families/bound-families` | 绑定家庭列表 |
+| `/api/guide/families/{familyId}/overview` | 家庭概览 |
+| `/api/guide/families/{familyId}/children/{childId}/tasks` | 孩子任务 |
+| `/api/guide/packages/my` | 我的模板 |
+| `/api/guide/packages/create` | 创建模板 |
+| `/api/guide/packages/update` | 更新模板 |
+| `/api/guide/packages/delete` | 删除模板 |
+| `/api/guide/training-plans/list` | 方案列表 |
+| `/api/guide/training-plans/create` | 创建方案 |
+| `/api/guide/training-plans/items/add` | 添加项目 |
+| `/api/guide/training-plans/deploy` | 下发方案 |
+| `/api/guide/training-plans/execution-board` | 执行看板 |
+| `/api/guide/orders/list` | 订单列表 |
+| `/api/guide/orders/stats` | 订单统计 |
+| `/api/guide/messages/send` | 发送咨询 |
+| `/api/guide/messages/list` | 咨询列表 |
+| `/api/guide/messages/{messageId}/reply` | 回复咨询 |
+| `/api/guide/assessment/materials` | 可用测评资料 |
+| `/api/guide/assessment/family/enable` | 启用家庭测评 |

docs/flows/health-checkin-flow.md

@@ -0,0 +1,89 @@
+# 用户使用流程图 — 健康打卡体系
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 每日健康打卡
+        A1(("家长/孩子")) --> A2[获取打卡列表 /list]
+        A2 --> A3[获取打卡详情 /detail]
+        A3 --> A4{打卡类型}
+        A4 -->|综合打卡| B1[创建打卡 /create]
+        A4 -->|运动打卡| B2[创建运动打卡 /create]
+        A4 -->|饮食打卡| B3[创建饮食打卡 /create]
+        A4 -->|睡眠打卡| B4[创建睡眠打卡 /create]
+        A4 -->|喝水打卡| B5[创建喝水打卡 /create]
+        A4 -->|冥想打卡| B6[创建冥想打卡 /create]
+    end
+
+    subgraph 打卡管理
+        B1 --> C1[更新打卡 /update]
+        C1 --> C2[删除打卡 /delete]
+    end
+
+    subgraph 连续打卡
+        C2 --> D1[获取打卡进度 /progress/{childId}]
+        D1 --> D2[获取打卡统计 /stats]
+        D2 --> D3{打卡中断?}
+        D3 -->|是| D4[重置中断打卡 /reset]
+        D3 -->|否| D5[保持连续]
+    end
+
+    subgraph 健康积分
+        D5 --> E1[获取健康积分信息 /info]
+        E1 --> E2[获取连续打卡天数 /streak]
+    end
+
+    subgraph 健康时间线
+        C2 --> F1[获取健康时间线 /list]
+        F1 --> F2[查看历史故事]
+    end
+
+    subgraph 健康预警
+        F2 --> G1[获取活跃预警 /list]
+        G1 --> G2[关闭预警 /dismiss]
+    end
+
+    R1(("👤 家长/孩子")):::actor
+    R2(("🔥 连续打卡系统")):::system
+
+    A1 -.- R1
+    D1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 控制器 | 说明 |
+|------|--------|------|
+| `/api/health/checkin/list` | HealthCheckinController | 获取打卡列表 |
+| `/api/health/checkin/create` | HealthCheckinController | 创建打卡记录 |
+| `/api/health/checkin/delete` | HealthCheckinController | 删除打卡记录 |
+| `/api/health/checkin/stats` | HealthCheckinController | 打卡统计 |
+| `/api/daily/checkin/list` | DailyCheckinController | 获取打卡列表 |
+| `/api/daily/checkin/detail` | DailyCheckinController | 获取打卡详情 |
+| `/api/daily/checkin/create` | DailyCheckinController | 创建打卡 |
+| `/api/daily/checkin/update` | DailyCheckinController | 更新打卡 |
+| `/api/daily/checkin/delete` | DailyCheckinController | 删除打卡 |
+| `/api/health/exercise/list` | HealthExerciseController | 运动打卡列表 |
+| `/api/health/exercise/create` | HealthExerciseController | 创建运动打卡 |
+| `/api/health/meal/list` | HealthMealController | 饮食打卡列表 |
+| `/api/health/meal/create` | HealthMealController | 创建饮食打卡 |
+| `/api/health/sleep/list` | HealthSleepController | 睡眠打卡列表 |
+| `/api/health/sleep/create` | HealthSleepController | 创建睡眠打卡 |
+| `/api/health/water/list` | HealthWaterController | 喝水打卡列表 |
+| `/api/health/water/create` | HealthWaterController | 创建喝水打卡 |
+| `/api/health/meditation/list` | HealthMeditationController | 冥想打卡列表 |
+| `/api/health/meditation/create` | HealthMeditationController | 创建冥想打卡 |
+| `/api/streak/progress/{childId}` | StreakController | 打卡进度 |
+| `/api/streak/reset` | StreakController | 重置中断打卡 |
+| `/api/health/score/info` | HealthScoreController | 健康积分信息 |
+| `/api/health/score/streak` | HealthScoreController | 连续天数 |
+| `/api/health/alert/list` | HealthAlertController | 活跃预警列表 |
+| `/api/health/alert/dismiss` | HealthAlertController | 关闭预警 |
+| `/api/health/timeline/list` | HealthTimelineController | 健康时间线 |

docs/flows/health-detection-flow.md

@@ -52,19 +52,19 @@ flowchart TD
     end
 
     subgraph 7维健康评分
-        D4 --> E1[维度评分引擎<br>DimensionScoreService]
-        E1 --> E2[刷新7维健康评分<br>refreshFromGutReport]
-        E2 --> E3[营养缺乏分析<br>NutritionDeficiencyService]
-        E3 --> E4[食材推荐指数<br>FoodRecommendService]
-        E4 --> E5[健康分析报告<br>HealthAnalysisService]
+        D4 --> E1[维度评分引擎]
+        E1 --> E2[刷新7维健康评分]
+        E2 --> E3[营养缺乏分析]
+        E3 --> E4[食材推荐指数]
+        E4 --> E5[健康分析报告]
     end
 
     subgraph AI教练解读
         E5 --> F1[家长查看健康报告]
         F1 --> F2{是否需要<br>AI解读?}
-        F2 -->|是| F3[Dify AI聊天<br>POST /api/ai/chat/send]
+        F2 -->|是| F3[AI聊天解读报告]
         F3 --> F4[AI解析报告指标<br>生成改善建议]
-        F4 --> F5[AI生成任务计划<br>TaskParseService]
+        F4 --> F5[AI生成任务计划]
         F5 --> F6[家长查看解读结果]
         F2 -->|否| G1
     end
@@ -77,22 +77,16 @@ flowchart TD
         G1 -->|自行跟进| G5[结束]
 
         G2 --> G2a[申请营养师服务]
-        G2a --> G2b[营养师审核家长需求]
-        G2b --> G2c[开具个性化营养方案]
-        G2c --> G2d[餐食推荐<br>MealRecommendService]
-        G2d --> G5
+        G2a --> G2b[营养师审核需求]
+        G2b --> G2c[开具营养方案]
 
         G3 --> G3a[申请管家服务]
-        G3a --> G3b[管家审核通过]
-        G3b --> G3c[管家分配 + 建档<br>ButlerProfile]
-        G3c --> G3d[管家定期跟进健康数据]
-        G3d --> G3e[管家协调营养师/规划师]
-        G3e --> G5
+        G3a --> G3b[管家审核]
+        G3b --> G3c[管家建档]
+        G3c --> G3d[定期跟进]
 
         G4 --> G4a[规划师查看报告]
         G4a --> G4b[规划师下发改善任务]
-        G4b --> G4c[任务执行与跟踪]
-        G4c --> G5
     end
 
     subgraph 持续跟踪
@@ -102,27 +96,39 @@ flowchart TD
         H3 --> F1
     end
 
-    %% ============ 角色标注 ============
     R1(("👤 家长")):::actor
     R2(("🤖 AI教练")):::role
     R3(("🥗 营养师")):::role
     R4(("🏠 管家")):::role
     R5(("📋 规划师")):::role
-
-    A4 -.- R1
-    F3 -.- R2
-    G2 -.- R3
-    G3 -.- R4
-    G4 -.- R5
 ```
 
-## 角色说明
-
-| 角色 | 系统映射 | 职责 |
-|:----|:---------|:-----|
-| **家长** | `role=parent` | 发起检测、上传报告、确认数据、查看解读、选择服务 |
-| **AI教练** | `AiChatController` + Dify API | 自动解析报告、生成解读与改善建议、任务计划 |
-| **营养师** | `NutritionistController` / `nutritionist` role | 审核通过的专业人士，出具营养方案与饮食推荐 |
-| **管家** | `ButlerService` / `butler` role | 全方位家庭健康管家，协调资源、定期跟进 |
-| **规划师** | `GuideController` / `teacher` role | 成长规划师，基于报告制定改善任务并跟踪 |
-| **管理员** | `role=admin` | 审核草稿、管理知识库、系统配置（后台） |
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/health/report/create` | 创建健康报告 |
+| `/api/health/report/latest` | 获取最新报告 |
+| `/api/health/report/list` | 报告列表 |
+| `/api/health/report/admin-list` | 管理端报告列表 |
+| `/api/health/report/detail` | 报告完整详情 |
+| `/api/health/report/edit` | 编辑报告 |
+| `/api/health/report/upload` | 上传PDF报告 |
+| `/api/health/report/parse-preview` | 解析预览 |
+| `/api/health/report/confirm` | 确认入库 |
+| `/api/health/report/discard` | 放弃草稿 |
+| `/api/health/report/bind` | 绑定到成员 |
+| `/api/health/report/unlinked` | 未绑定报告 |
+| `/api/health/report/permission/add` | 添加查看权限 |
+| `/api/health/report/permission/remove` | 移除权限 |
+| `/api/health/report/permission/check` | 检查权限 |
+| `/api/health/indicator/list` | 指标明细 |
+| `/api/health/body/detail` | 身体维度数据 |
+| `/api/health/nutrition/deficiency` | 营养缺乏分析 |
+| `/api/health/nutrition/profile` | 孩子营养档案 |
+| `/api/health/survey/create` | 创建调研问卷 |
+| `/api/health/survey/submit` | 提交问卷 |
+| `/api/health/survey/status` | 问卷状态 |
+| `/api/dan-report/upload` | DAN报告上传 |
+| `/api/dan-report/{id}/confirm` | 确认DAN报告 |
+| `/api/dan-report/list` | DAN报告列表 |

docs/flows/knowledge-invite-flow.md

@@ -0,0 +1,89 @@
+# 用户使用流程图 — 健康知识库与邀请
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 健康知识库
+        A1(("管理员")) --> A2[查询知识库 /query]
+        A2 --> A3[批量查询 /batch-query]
+        A3 --> A4[列表查询 /list]
+        A4 --> A5[新增条目 /add]
+        A5 --> A6[更新条目 /update]
+        A6 --> A7[删除条目 /delete]
+        A7 --> A8[从JSON导入 /import]
+    end
+
+    subgraph KB v3查询
+        A8 --> B1[查询菌属功能 /v3/bacteria/query]
+        B1 --> B2[批量查询菌属 /v3/bacteria/batch-query]
+        B2 --> B3[查询指标调整 /v3/indicator/query]
+        B3 --> B4[查询食物营养 /v3/food/query]
+        B4 --> B5[获取原始数据 /v3/section]
+    end
+
+    subgraph 邀请码管理
+        C1(("用户")) --> C2[生成邀请码 /invite/code]
+        C2 --> C3[绑定邀请 /invite/bind]
+        C3 --> C4[获取邀请列表 /invite/list]
+        C4 --> C5[获取邀请汇总 /invite/summary]
+        C5 --> C6[获取邀请二维码 /invite/qrcode]
+    end
+
+    subgraph 邀请卡片
+        C6 --> D1[生成邀请码 /invite-card/generate]
+        D1 --> D2[验证邀请码 /invite-card/verify]
+        D2 --> D3[接受邀请 /invite-card/accept]
+    end
+
+    subgraph 邀请里程碑
+        D3 --> E1[获取里程碑列表 /invite/milestone/list]
+        E1 --> E2[领取里程碑奖励 /invite/milestone/claim]
+    end
+
+    subgraph 入门引导
+        C1 --> F1[获取引导进度 /onboarding/progress]
+        F1 --> F2[领取奖励 /onboarding/claim]
+    end
+
+    R1(("🔧 管理员")):::actor
+    R2(("👤 用户")):::role
+
+    A1 -.- R1
+    C1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/health/knowledge/query` | 查询知识库 |
+| `/api/health/knowledge/batch-query` | 批量查询 |
+| `/api/health/knowledge/list` | 列表查询 |
+| `/api/health/knowledge/add` | 新增条目 |
+| `/api/health/knowledge/update` | 更新条目 |
+| `/api/health/knowledge/delete` | 删除条目 |
+| `/api/health/knowledge/import` | 导入数据 |
+| `/api/health/knowledge/v3/bacteria/query` | 菌属功能查询 |
+| `/api/health/knowledge/v3/bacteria/batch-query` | 批量菌属查询 |
+| `/api/health/knowledge/v3/indicator/query` | 指标调整建议 |
+| `/api/health/knowledge/v3/food/query` | 食物营养数据 |
+| `/api/health/knowledge/v3/section` | 原始数据 |
+| `/api/invite/code` | 生成邀请码 |
+| `/api/invite/bind` | 绑定邀请 |
+| `/api/invite/list` | 邀请列表 |
+| `/api/invite/summary` | 邀请汇总 |
+| `/api/invite/qrcode` | 邀请二维码 |
+| `/api/invite-card/generate` | 生成邀请卡片 |
+| `/api/invite-card/verify` | 验证邀请码 |
+| `/api/invite-card/accept` | 接受邀请 |
+| `/api/invite/milestone/list` | 里程碑列表 |
+| `/api/invite/milestone/claim` | 领取奖励 |
+| `/api/onboarding/progress` | 引导进度 |
+| `/api/onboarding/claim` | 领取奖励 |

docs/flows/market-flow.md

@@ -0,0 +1,78 @@
+# 用户使用流程图 — 任务模板市场
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 市场浏览
+        A1(("家长")) --> A2[获取公开模板列表 /packages]
+        A2 --> A3[获取模板详情 /packages/{id}]
+        A3 --> A4[获取任务项 /packages/{id}/items]
+        A4 --> A5[通过分享码获取 /share/{code}]
+    end
+
+    subgraph 购买流程
+        A5 --> B1[获取模板价格 /price]
+        B1 --> B2[获取可用指导师 /available-guides]
+        B2 --> B3[创建订单 /order/create]
+        B3 --> B4[获取微信支付参数 /wechat params]
+        B4 --> B5[微信支付回调 /notify]
+        B5 --> B6[支付成功后应用 /apply]
+        B6 --> B7[购买并应用模板 /packages/{id}/purchase]
+    end
+
+    subgraph 我的计划
+        B7 --> C1[获取我的计划 /plans]
+        C1 --> C2[获取计划详情 /plans/{id}]
+        C2 --> C3[获取计划任务项 /plans/{id}/items]
+        C3 --> C4[取消计划 /plans/{id}/cancel]
+    end
+
+    subgraph 模板创建(管理员/规划师)
+        A2 --> D1[创建模板 /create]
+        D1 --> D2[更新模板 /{id}/update]
+        D2 --> D3[添加任务项 /{id}/items]
+        D3 --> D4[提交审核 /{id}/submit]
+        D4 --> D5[审核通过后发布 /{id}/publish]
+    end
+
+    R1(("👤 家长")):::actor
+    R2(("📋 规划师/管理员")):::role
+    R3(("💳 微信支付")):::system
+
+    A1 -.- R1
+    D1 -.- R2
+    B5 -.- R3
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/market/packages` | 获取公开模板列表 |
+| `/api/market/packages/{id}` | 获取模板详情 |
+| `/api/market/packages/{id}/items` | 获取任务项 |
+| `/api/market/share/{code}` | 通过分享码获取 |
+| `/api/market/packages/{id}/purchase` | 购买并应用 |
+| `/api/market/plans` | 获取我的计划 |
+| `/api/market/plans/{id}` | 计划详情 |
+| `/api/market/plans/{id}/items` | 计划任务项 |
+| `/api/market/plans/{id}/cancel` | 取消计划 |
+| `/api/package/price` | 模板价格 |
+| `/api/package/available-guides` | 可用指导师 |
+| `/api/package/order/create` | 创建订单 |
+| `/api/package/order/{orderNo}` | 订单详情 |
+| `/api/payment/create` | 创建支付订单 |
+| `/api/payment/wechat params` | 微信支付参数 |
+| `/api/payment/notify` | 支付回调 |
+| `/api/payment/apply` | 应用模板 |
+| `/api/packages/create` | 创建模板 |
+| `/api/packages/{id}/update` | 更新模板 |
+| `/api/packages/{id}/submit` | 提交审核 |
+| `/api/packages/{id}/publish` | 发布/下架 |

docs/flows/membership-flow.md

@@ -0,0 +1,86 @@
+# 用户使用流程图 — 会员与订阅
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 会员查看
+        A1(("家长")) --> A2[获取会员等级列表 /levels]
+        A2 --> A3[获取我的会员信息 /my]
+        A3 --> A4[获取当前会员等级 /level]
+        A4 --> A5[获取会员等级详情 /current]
+        A5 --> A6[获取升级记录 /records]
+    end
+
+    subgraph 会员升级
+        A6 --> B1[创建会员升级订单 /upgrade]
+        B1 --> B2[创建订单 /orders]
+        B2 --> B3{是否需要支付?}
+        B3 -->|是| B4[支付回调 /notify]
+        B3 -->|否| B5[直接升级]
+        B4 --> B5
+    end
+
+    subgraph 会员权益
+        B5 --> C1[检查功能权限 /can-use]
+        C1 --> C2[应用会员折扣 /discount]
+        C2 --> C3[获取任务模板价格 /plans]
+    end
+
+    subgraph 会员试用
+        A6 --> D1[激活试用会员 /trial]
+        D1 --> D2[试用期体验]
+    end
+
+    subgraph 订阅管理
+        A3 --> E1[获取订阅状态 /status]
+        E1 --> E2[获取订阅计划 /plans]
+        E2 --> E3[创建订阅 /create]
+        E3 --> E4[确认订阅 /subscribe]
+        E4 --> E5[取消订阅 /cancel]
+        E5 --> E6[自动续费设置 /auto-renew]
+        E6 --> E7[获取我的权益 /benefits/my]
+        E7 --> E8[检查权益 /benefit/check]
+        E8 --> E9[获取当前订阅层级 /tier]
+        E9 --> E10[更新订阅层级 /tier/update]
+    end
+
+    R1(("👤 家长")):::actor
+    R2(("💳 微信支付")):::system
+
+    A1 -.- R1
+    B4 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 控制器 | 说明 |
+|------|--------|------|
+| `/api/membership/levels` | MembershipController | 会员等级列表 |
+| `/api/membership/my` | MembershipController | 我的会员信息 |
+| `/api/membership/level` | MembershipController | 当前等级 |
+| `/api/membership/current` | MembershipController | 等级详情 |
+| `/api/membership/records` | MembershipController | 升级记录 |
+| `/api/membership/upgrade` | MembershipController | 创建升级订单 |
+| `/api/membership/trial` | MembershipController | 激活试用 |
+| `/api/membership/orders` | MembershipController | 创建订单 |
+| `/api/membership/plans` | MembershipController | 任务模板价格 |
+| `/api/membership/notify` | MembershipController | 支付回调 |
+| `/api/membership/can-use` | MembershipController | 功能权限检查 |
+| `/api/membership/discount` | MembershipController | 应用折扣 |
+| `/api/subscription/status` | SubscriptionController | 订阅状态 |
+| `/api/subscription/plans` | SubscriptionController | 订阅计划 |
+| `/api/subscription/create` | SubscriptionController | 创建订阅 |
+| `/api/subscription/subscribe` | SubscriptionController | 确认订阅 |
+| `/api/subscription/cancel` | SubscriptionController | 取消订阅 |
+| `/api/subscription/auto-renew` | SubscriptionController | 自动续费 |
+| `/api/subscription/benefits/my` | SubscriptionController | 我的权益 |
+| `/api/subscription/benefit/check` | SubscriptionController | 检查权益 |
+| `/api/subscription/tier` | SubscriptionController | 订阅层级 |
+| `/api/subscription/tier/update` | SubscriptionController | 更新层级 |

docs/flows/mind-emotion-flow.md

@@ -0,0 +1,88 @@
+# 用户使用流程图 — 心理与情绪管理
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 情绪打卡
+        A1(("用户")) --> A2[创建情绪打卡 /mind/checkin/create]
+        A2 --> A3[获取情绪列表 /mind/checkin/list]
+        A3 --> A4[获取最新情绪 /mind/checkin/latest]
+        A4 --> A5[获取情绪趋势 /mind/checkin/trend]
+        A5 --> A6[获取情绪统计 /mind/checkin/stats]
+        A6 --> A7[获取周报 /mind/checkin/weekly-report]
+    end
+
+    subgraph 情绪预警
+        A7 --> B1[获取活跃预警 /mind/alert/active]
+        B1 --> B2[获取打卡预警 /mind/alert/checkin-alerts]
+        B2 --> B3[处理预警 /mind/alert/resolve]
+    end
+
+    subgraph 心理测评
+        A1 --> C1[提交筛查问卷 /mind/screening/submit]
+        C1 --> C2[获取筛查历史 /mind/screening/history]
+        C2 --> C3[获取最新结果 /mind/screening/latest]
+    end
+
+    subgraph 脑科学与神经递质
+        C3 --> D1[获取神经递质分析 /mind/neurotransmitters]
+        D1 --> D2[获取肠脑洞察 /mind/gut-emotion-insight]
+        D2 --> D3[获取EMI报告 /mind/emireport/latest]
+    end
+
+    subgraph 心理运势
+        D3 --> E1[获取心理运势 /mind/fortune]
+        E1 --> E2[刷新运势 /mind/fortune/refresh]
+        E2 --> E3[导出运势 /mind/fortune/export]
+    end
+
+    subgraph 传统心理镜像
+        E3 --> F1[获取心理镜像 /mind/traditional/mirror]
+        F1 --> F2[获取家庭看板 /mind/traditional/family-dashboard]
+        F2 --> F3[获取兼容性 /mind/traditional/compatibility]
+    end
+
+    subgraph EMI心理报告
+        F3 --> G1[获取EMI心理报告 /emireport/latest]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🧠 心理引擎")):::system
+
+    A1 -.- R1
+    D1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 控制器 | 说明 |
+|------|--------|------|
+| `/api/mind/checkin/create` | EmotionCheckinController | 创建情绪打卡 |
+| `/api/mind/checkin/list` | EmotionCheckinController | 情绪列表 |
+| `/api/mind/checkin/latest` | EmotionCheckinController | 最新情绪 |
+| `/api/mind/checkin/trend` | EmotionCheckinController | 情绪趋势 |
+| `/api/mind/checkin/stats` | EmotionCheckinController | 情绪统计 |
+| `/api/mind/checkin/weekly-report` | EmotionCheckinController | 周报 |
+| `/api/mind/alert/active` | EmotionAlertController | 活跃预警 |
+| `/api/mind/alert/checkin-alerts` | EmotionAlertController | 打卡预警 |
+| `/api/mind/alert/resolve` | EmotionAlertController | 处理预警 |
+| `/api/mind/neurotransmitters` | MindController | 神经递质 |
+| `/api/mind/gut-emotion-insight` | MindController | 肠脑洞察 |
+| `/api/mind/emireport/latest` | MindController | EMI报告 |
+| `/api/mind/fortune` | MindFortuneController | 心理运势 |
+| `/api/mind/fortune/refresh` | MindFortuneController | 刷新运势 |
+| `/api/mind/fortune/export` | MindFortuneController | 导出运势 |
+| `/api/mind/screening/submit` | ScreeningController | 提交筛查 |
+| `/api/mind/screening/history` | ScreeningController | 筛查历史 |
+| `/api/mind/screening/latest` | ScreeningController | 最新结果 |
+| `/api/mind/traditional/mirror` | TraditionalMirrorController | 心理镜像 |
+| `/api/mind/traditional/family-dashboard` | TraditionalMirrorController | 家庭看板 |
+| `/api/mind/traditional/compatibility` | TraditionalMirrorController | 兼容性 |
+| `/api/emireport/latest` | EmiReportController | EMI心理报告 |

docs/flows/minigame-flow.md

@@ -0,0 +1,70 @@
+# 用户使用流程图 — 小游戏
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 游戏浏览
+        A1(("孩子")) --> A2[获取小游戏列表 /list]
+        A2 --> A3[获取游戏详情 /{gameCode}]
+    end
+
+    subgraph 游戏执行
+        A3 --> B1{游戏类型}
+        B1 -->|舒尔特方格| B2[完成专注力训练]
+        B1 -->|猜数字| B3[完成逻辑训练]
+        B1 -->|数独| B4[完成思维训练]
+        B2 --> B5[游戏完成 /complete]
+        B3 --> B5
+        B4 --> B5
+    end
+
+    subgraph 游戏记录
+        B5 --> C1[保存游戏记录 /game/record]
+        C1 --> C2[获取游戏历史 /game/history]
+        C2 --> C3[获取最佳成绩 /game/best]
+        C3 --> C4[获取统计概览 /game/stats]
+        C4 --> C5[获取排行榜 /game/leaderboard]
+    end
+
+    subgraph 管理端
+        A2 --> D1[获取所有游戏 /all]
+        D1 --> D2[更新游戏状态 /{id}/status]
+    end
+
+    subgraph 智慧数学
+        A1 --> E1[开始答题 /api/wisdom/math/start]
+        E1 --> E2[验证答案 /api/wisdom/math/verify]
+        E2 --> E3[完成游戏 /api/wisdom/math/complete]
+    end
+
+    R1(("👶 孩子")):::actor
+    R2(("🎮 游戏引擎")):::system
+
+    A1 -.- R1
+    C5 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/mini-game/list` | 小游戏列表 |
+| `/api/mini-game/{gameCode}` | 游戏详情 |
+| `/api/mini-game/all` | 所有游戏(管理端) |
+| `/api/mini-game/{id}/status` | 更新游戏状态 |
+| `/api/mini-game/complete` | 完成游戏 |
+| `/api/game/record` | 保存游戏记录 |
+| `/api/game/history` | 游戏历史 |
+| `/api/game/best` | 最佳成绩 |
+| `/api/game/stats` | 统计概览 |
+| `/api/game/leaderboard` | 排行榜 |
+| `/api/wisdom/math/start` | 开始数学游戏 |
+| `/api/wisdom/math/verify` | 验证答案 |
+| `/api/wisdom/math/complete` | 完成游戏 |

docs/flows/nutrition-diet-flow.md

@@ -0,0 +1,75 @@
+# 用户使用流程图 — 营养与饮食推荐
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 食谱推荐
+        A1(("用户")) --> A2[获取食谱推荐 /meal/recommend]
+        A2 --> A3{对推荐满意?}
+        A3 -->|不满意| A4[替换指定食材(一换一菜) /meal/replace]
+        A4 --> A3
+        A3 -->|满意| A5[记录饮食日志 /meal/log]
+    end
+
+    subgraph 饮食记录查询
+        A5 --> B1[获取近期日志 /meal/logs]
+        B1 --> B2[获取营养摄入统计 /meal/nutrition-summary]
+    end
+
+    subgraph 食材推荐指数
+        B2 --> C1[获取食材推荐指数 /food/recommendation/index]
+        C1 --> C2[获取指数变更历史 /food/recommendation/history]
+        C2 --> C3[按家庭分组获取 /food/recommendation/by-family]
+    end
+
+    subgraph 营养偏好
+        C3 --> D1[获取营养偏好 /nutrition/profile/get]
+        D1 --> D2[保存营养偏好 /nutrition/profile/save]
+    end
+
+    subgraph 营养师服务
+        D2 --> E1[申请营养师 /nutritionist/apply]
+        E1 --> E2[获取申请状态 /nutritionist/status]
+    end
+
+    subgraph 推荐商品
+        E2 --> F1[获取维度页推荐 /recommend/dimension-products]
+        F1 --> F2[获取复购提醒 /recommend/repurchase-reminders/list]
+        F2 --> F3[标记已点击 /repurchase-reminders/click]
+        F3 --> F4[标记已购买 /repurchase-reminders/purchased]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🥗 食谱引擎")):::system
+
+    A1 -.- R1
+    A2 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/meal/recommend` | 获取食谱推荐 |
+| `/api/meal/replace` | 替换指定食材 |
+| `/api/meal/log` | 记录饮食日志 |
+| `/api/meal/logs` | 获取近期日志 |
+| `/api/meal/nutrition-summary` | 营养摄入统计 |
+| `/api/food/recommendation/index` | 食材推荐指数 |
+| `/api/food/recommendation/history` | 指数变更历史 |
+| `/api/food/recommendation/by-family` | 按家庭分组 |
+| `/api/nutrition/profile/get` | 获取营养偏好 |
+| `/api/nutrition/profile/save` | 保存营养偏好 |
+| `/api/nutritionist/apply` | 申请营养师 |
+| `/api/nutritionist/status` | 申请状态 |
+| `/api/recommend/dimension-products` | 维度推荐商品 |
+| `/api/recommend/repurchase-reminders/list` | 复购提醒列表 |
+| `/api/recommend/repurchase-reminders/click` | 标记已点击 |
+| `/api/recommend/repurchase-reminders/purchased` | 标记已购买 |

docs/flows/points-exchange-flow.md

@@ -0,0 +1,66 @@
+# 用户使用流程图 — 积分兑换
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 积分概览
+        A1(("家长/孩子")) --> A2[获取积分余额 /balance]
+        A2 --> A3[获取积分流水 /logs]
+        A3 --> A4[按分类查询 /logs-by-category]
+        A4 --> A5[管理系统余额 /system-balance]
+    end
+
+    subgraph 积分调整
+        A5 --> B1[手动调整积分 /adjust]
+    end
+
+    subgraph 兑换商城
+        A2 --> C1[获取兑换商品列表 /product/list]
+        C1 --> C2[获取商品详情 /product/detail]
+        C2 --> C3[提交兑换 /submit]
+        C3 --> C4[获取兑换记录 /records]
+        C4 --> C5[获取兑换统计 /stats]
+    end
+
+    subgraph 奖励系统
+        A4 --> D1[创建奖励 /create]
+        D1 --> D2[获取奖励模板 /templates]
+        D2 --> D3[兑换奖励 /{id}/exchange]
+        D3 --> D4[审批奖励 /{id}/approve]
+        D4 --> D5[兑换历史 /exchange-history]
+    end
+
+    R1(("👤 家长/孩子")):::actor
+    R2(("💎 积分引擎")):::system
+
+    A1 -.- R1
+    A3 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 控制器 | 说明 |
+|------|--------|------|
+| `/api/points/balance` | PointsController | 获取积分余额 |
+| `/api/points/logs` | PointsController | 获取积分流水 |
+| `/api/points/adjust` | PointsController | 手动调整积分 |
+| `/api/points/system-balance` | PointsController | 系统余额 |
+| `/api/points/logs-by-category` | PointsController | 按分类查询流水 |
+| `/api/points/exchange/product/list` | PointsExchangeController | 兑换商品列表 |
+| `/api/points/exchange/product/detail` | PointsExchangeController | 商品详情 |
+| `/api/points/exchange/submit` | PointsExchangeController | 提交兑换 |
+| `/api/points/exchange/records` | PointsExchangeController | 兑换记录 |
+| `/api/points/exchange/stats` | PointsExchangeController | 兑换统计 |
+| `/api/rewards/create` | RewardController | 创建奖励 |
+| `/api/rewards/wishlist` | RewardController | 奖励清单 |
+| `/api/rewards/{id}/exchange` | RewardController | 兑换奖励 |
+| `/api/rewards/{id}/approve` | RewardController | 审批奖励 |
+| `/api/rewards/templates` | RewardController | 奖励模板 |
+| `/api/rewards/exchange-history` | RewardController | 兑换历史 |

docs/flows/promotion-flow.md

@@ -0,0 +1,92 @@
+# 用户使用流程图 — 推广分销
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 推广绑定
+        A1(("推广员")) --> A2[绑定推广关系 /bind]
+        A2 --> A3[获取佣金列表 /commission/list]
+        A3 --> A4[获取绑定列表 /bindings/list]
+    end
+
+    subgraph 销售邀请
+        A1 --> B1[生成销售邀请码 /generate]
+        B1 --> B2[校验邀请码 /validate]
+        B2 --> B3[获取我的虚拟团队 /my-teams]
+        B3 --> B4[获取团队位置 /my-position]
+    end
+
+    subgraph 佣金系统
+        A3 --> C1[获取佣金汇总 /summary]
+        C1 --> C2[获取佣金明细 /list]
+        C2 --> C3[获取团队佣金 /team]
+        C3 --> C4[获取佣金统计 /stats]
+        C4 --> C5[获取佣金余额 /balance]
+        C5 --> C6[团队列表 /team/list]
+        C6 --> C7[获取转化漏斗 /funnel]
+    end
+
+    subgraph 推广素材
+        C7 --> D1[获取素材列表 /list]
+        D1 --> D2[获取素材详情 /detail]
+        D2 --> D3[按场景获取 /by-scenario]
+    end
+
+    subgraph 佣金记录
+        A3 --> E1[记录佣金 /record]
+        E1 --> E2[家庭佣金汇总 /family-total]
+    end
+
+    subgraph 提现
+        C5 --> F1[申请提现 /apply]
+        F1 --> F2[提现记录 /history]
+    end
+
+    subgraph 推广排行榜
+        E2 --> G1[获取排行榜 /top]
+        G1 --> G2[获取我的排名 /my-rank]
+    end
+
+    R1(("👤 推广员")):::actor
+    R2(("💰 佣金系统")):::system
+
+    A1 -.- R1
+    C1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/promotion/bind` | 绑定推广关系 |
+| `/api/promotion/commission/list` | 佣金列表 |
+| `/api/promotion/bindings/list` | 绑定列表 |
+| `/api/commission/summary` | 佣金汇总 |
+| `/api/commission/list` | 佣金明细 |
+| `/api/commission/team` | 团队佣金 |
+| `/api/commission/stats` | 佣金统计 |
+| `/api/commission/balance` | 余额 |
+| `/api/commission/team/list` | 团队列表 |
+| `/api/commission/funnel` | 转化漏斗 |
+| `/api/promotion/commission/record` | 记录佣金 |
+| `/api/promotion/commission/family-total` | 家庭佣金汇总 |
+| `/api/promotion/material/list` | 素材列表 |
+| `/api/promotion/material/detail` | 素材详情 |
+| `/api/promotion/material/by-scenario` | 按场景获取 |
+| `/api/distribution/invite/generate` | 生成邀请码 |
+| `/api/distribution/invite/validate` | 校验邀请码 |
+| `/api/distribution/invite/my-teams` | 我的团队 |
+| `/api/distribution/invite/my-position` | 团队位置 |
+| `/api/withdrawal/apply` | 申请提现 |
+| `/api/withdrawal/history` | 提现记录 |
+| `/api/leaderboard/top` | 排行榜 |
+| `/api/leaderboard/my-rank` | 我的排名 |
+| `/api/invite/milestone/list` | 里程碑列表 |
+| `/api/invite/milestone/claim` | 领取里程碑 |

docs/flows/shop-flow.md

@@ -0,0 +1,114 @@
+# 用户使用流程图 — 商城交易
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 商品浏览
+        A1(("用户")) --> A2[获取商品分类 /category/tree]
+        A2 --> A3[查看分类商品 /category/products]
+        A3 --> A4[获取商品列表 /list]
+        A4 --> A5[获取商品详情 /detail]
+        A5 --> A6[获取规格映射 /spec/map]
+    end
+
+    subgraph 购物车
+        A6 --> B1[添加购物车 /cart/add]
+        B1 --> B2[获取购物车列表 /cart/list]
+        B2 --> B3[更新购物车 /cart/update]
+        B3 --> B4[移除商品 /cart/remove]
+        B4 --> B5[获取购物车数量 /cart/count]
+    end
+
+    subgraph 下单支付
+        B5 --> C1[创建订单 /product/order/create]
+        C1 --> C2[支付 /product/order/pay]
+        C2 --> C3[支付回调 /product/order/notify]
+        C3 --> C4[处理支付成功 /handlePaymentSuccess]
+    end
+
+    subgraph 订单管理
+        C4 --> D1[获取我的订单 /my]
+        D1 --> D2[订单数量统计 /my/counts]
+        D2 --> D3[订单详情 /detail]
+        D3 --> D4{订单状态}
+        D4 -->|待发货| D5[取消订单 /cancel]
+        D4 -->|已发货| D6[确认收货 /confirm]
+        D4 -->|待退款| D7[申请退款 /refund/apply]
+    end
+
+    subgraph 商家发货
+        D6 --> E1[商家发货 /ship]
+        E1 --> E2[查询物流 /logistics/query]
+    end
+
+    subgraph 售后
+        D7 --> F1[创建售后 /after-sales/create]
+        F1 --> F2[售后列表 /after-sales/list]
+        F2 --> F3[售后详情 /after-sales/detail]
+    end
+
+    subgraph 评价
+        D6 --> G1[发表评价 /review/order]
+        G1 --> G2[评价详情 /review/order/detail]
+        G2 --> G3[评价状态 /review/order/status]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🏪 商家")):::role
+    R3(("💳 支付")):::system
+
+    A1 -.- R1
+    E1 -.- R2
+    C2 -.- R3
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/product/list` | 商品列表 |
+| `/api/product/detail` | 商品详情 |
+| `/api/product/create` | 创建商品(商家) |
+| `/api/product/update` | 更新商品 |
+| `/api/product/my` | 我的商品 |
+| `/api/product/shelve` | 上下架 |
+| `/api/product/images/update` | 更新图片 |
+| `/api/product/spec/map` | 规格映射 |
+| `/api/product/order/create` | 创建订单 |
+| `/api/product/order/pay` | 支付 |
+| `/api/product/order/cancel` | 取消订单 |
+| `/api/product/order/my` | 我的订单 |
+| `/api/product/order/my/counts` | 订单数量统计 |
+| `/api/product/order/detail` | 订单详情 |
+| `/api/product/order/vendor` | 商家订单 |
+| `/api/product/order/confirm` | 确认收货 |
+| `/api/product/order/ship` | 发货 |
+| `/api/product/order/refund/apply` | 申请退款 |
+| `/api/product/order/handlePaymentSuccess` | 处理支付成功 |
+| `/api/product/order/notify` | 支付回调 |
+| `/api/product/order/activity/audit` | 活动审核 |
+| `/api/product/order/activity/sign-in` | 活动签到 |
+| `/api/product/order/activity/complete` | 活动完成 |
+| `/api/product/order/activity/provision` | 活动供应 |
+| `/api/product/order/activity/qr-image` | 活动二维码 |
+| `/api/cart/add` | 添加购物车 |
+| `/api/cart/list` | 购物车列表 |
+| `/api/cart/update` | 更新购物车 |
+| `/api/cart/remove` | 移除商品 |
+| `/api/cart/count` | 购物车数量 |
+| `/api/shop/category/tree` | 分类树 |
+| `/api/shop/category/products` | 分类商品 |
+| `/api/shop/after-sales/create` | 创建售后 |
+| `/api/shop/after-sales/list` | 售后列表 |
+| `/api/shop/after-sales/detail` | 售后详情 |
+| `/api/shop/logistics/query` | 查询物流 |
+| `/api/review/order` | 发表评价 |
+| `/api/review/order/detail` | 评价详情 |
+| `/api/review/order/status` | 评价状态 |

docs/flows/stats-report-flow.md

@@ -0,0 +1,84 @@
+# 用户使用流程图 — 统计报表
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 统计报表
+        A1(("管理员/家长")) --> A2[孩子数据概览 /child/overview]
+        A2 --> A3[家庭汇总统计 /family/summary]
+        A3 --> A4[积分排行榜 /points/ranking]
+    end
+
+    subgraph 任务统计
+        A4 --> B1[仪表盘汇总 /dashboard]
+        B1 --> B2[孩子完成率 /child-completion]
+        B2 --> B3[家庭完成率 /family-completion]
+        B3 --> B4[数据总览 /overview]
+        B4 --> B5[收入统计 /revenue]
+        B5 --> B6[会员分布 /membership]
+        B6 --> B7[每日趋势 /trend]
+    end
+
+    subgraph 地址区域
+        A1 --> C1[获取省份 /provinces]
+        C1 --> C2[获取子级 /children/{parentId}]
+        C2 --> C3[获取详情 /{id}]
+        C3 --> C4[获取完整路径 /{id}/path]
+        C4 --> C5[地址搜索 /search]
+        C5 --> C6[区域回退匹配 /{id}/match]
+        C6 --> C7[按区域统计 /stats]
+    end
+
+    subgraph 用户地址
+        A1 --> D1[地址列表 /user/address/list]
+        D1 --> D2[获取地址 /user/address/get]
+        D2 --> D3[创建地址 /user/address/create]
+        D3 --> D4[更新地址 /user/address/update]
+        D4 --> D5[删除地址 /user/address/delete]
+        D5 --> D6[设为默认 /user/address/setDefault]
+    end
+
+    R1(("👤 管理员/家长")):::actor
+    R2(("📊 统计引擎")):::system
+
+    A1 -:- R1
+    B1 -:- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/stats/child/overview` | 孩子数据概览 |
+| `/api/stats/family/summary` | 家庭汇总 |
+| `/api/stats/points/ranking` | 积分排行榜 |
+| `/api/stats/dashboard` | 仪表盘汇总 |
+| `/api/stats/child-completion` | 孩子完成率 |
+| `/api/stats/family-completion` | 家庭完成率 |
+| `/api/stats/overview` | 数据总览 |
+| `/api/stats/revenue` | 收入统计 |
+| `/api/stats/membership` | 会员分布 |
+| `/api/stats/trend` | 每日趋势 |
+| `/api/region/provinces` | 省份列表 |
+| `/api/region/cities` | 城市列表 |
+| `/api/region/districts` | 区县列表 |
+| `/api/region/streets` | 街道列表 |
+| `/api/streets/provinces` | 所有省份 |
+| `/api/streets/children/{parentId}` | 子级地址 |
+| `/api/streets/{id}` | 地址详情 |
+| `/api/streets/{id}/path` | 地址路径 |
+| `/api/streets/search` | 搜索地址 |
+| `/api/streets/{id}/match` | 区域回退匹配 |
+| `/api/streets/stats` | 区域统计 |
+| `/api/user/address/list` | 地址列表 |
+| `/api/user/address/create` | 创建地址 |
+| `/api/user/address/update` | 更新地址 |
+| `/api/user/address/delete` | 删除地址 |
+| `/api/user/address/setDefault` | 设为默认 |

docs/flows/task-management-flow.md

@@ -0,0 +1,90 @@
+# 用户使用流程图 — 任务管理
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 任务创建
+        A1(("家长/规划师")) --> A2{创建来源}
+        A2 -->|手动创建| A3[创建任务 /create]
+        A2 -->|从模板| A4[市场购买模板 → 应用]
+        A2 -->|AI推荐| A5[AI生成任务建议 → 一键添加]
+        A2 -->|训练方案| A6[训练方案下发 /deploy]
+        A3 --> A7[获取可选小游戏 /minigame-options]
+    end
+
+    subgraph 任务执行
+        A7 --> B1[获取今日任务 /today]
+        B1 --> B2{任务类型}
+        B2 -->|普通任务| B3[完成任务 /{id}/complete]
+        B2 -->|小游戏| B4[完成小游戏 /{id}/complete-minigame]
+        B2 -->|家长任务| B5[家长完成任务 /{id}/complete-parent]
+        B3 --> B6{需要审核?}
+        B6 -->|是| B7[进入待审核 /pending-review]
+        B6 -->|否| B8[任务完成]
+        B4 --> B8
+        B5 --> B8
+    end
+
+    subgraph 任务审核
+        B7 --> C1[获取待审核列表 /pending-review]
+        C1 --> C2[审核任务 /{id}/review]
+        C2 --> C3{审核结果}
+        C3 -->|通过| C4[任务完成 发放能量]
+        C3 -->|驳回| C5[任务退回]
+    end
+
+    subgraph 规划师批量管理
+        A1 --> D1[获取关联家庭 /bound-families]
+        D1 --> D2[获取家庭任务概览 /{familyId}/overview]
+        D2 --> D3[获取孩子任务 /{familyId}/children/{childId}/tasks]
+        D3 --> D4[批量审核 /batch-review]
+        D4 --> D5[修改任务 /{taskId}]
+        D5 --> D6[删除任务 /{taskId}/delete]
+    end
+
+    subgraph 任务历史与统计
+        B8 --> E1[获取任务历史 /history]
+        E1 --> E2[批量完成任务 /batch-complete]
+        E2 --> E3[批量删除任务 /batch-delete]
+    end
+
+    R1(("👤 家长/规划师")):::actor
+    R2(("👶 孩子")):::actor
+    R3(("📋 规划师")):::role
+
+    A1 -.- R1
+    B3 -.- R2
+    D1 -.- R3
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/tasks/create` | 创建任务 |
+| `/api/tasks/today` | 获取今日任务 |
+| `/api/tasks/{id}/complete` | 完成任务 |
+| `/api/tasks/{id}/review` | 审核任务 |
+| `/api/tasks/history` | 获取任务历史 |
+| `/api/tasks/pending-review` | 获取待审核任务 |
+| `/api/tasks/today-parent` | 获取家长今日任务 |
+| `/api/tasks/{id}/complete-parent` | 家长完成任务 |
+| `/api/tasks/{id}/complete-minigame` | 完成小游戏任务 |
+| `/api/tasks/batch-complete` | 批量完成任务 |
+| `/api/tasks/batch-delete` | 批量删除任务 |
+| `/api/tasks/minigame-options` | 获取可选小游戏 |
+| `/api/guide/families/bound-families` | 获取关联家庭 |
+| `/api/guide/families/{familyId}/overview` | 家庭任务概览 |
+| `/api/guide/families/{familyId}/children/{childId}/tasks` | 孩子任务列表 |
+| `/api/guide/families/{familyId}/children/{childId}/pending-review` | 待审核列表 |
+| `/api/guide/families/{familyId}/tasks/{taskId}/review` | 审核任务 |
+| `/api/guide/families/{familyId}/tasks/batch-review` | 批量审核 |
+| `/api/guide/families/{familyId}/tasks/{taskId}/delete` | 删除任务 |
+| `/api/guide/families/dashboard-stats` | 规划师首页统计 |

docs/flows/tianpan-fortune-flow.md

@@ -0,0 +1,39 @@
+# 用户使用流程图 — 天盘与运势
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 天盘首页
+        A1(("用户")) --> A2[获取天盘首页 /dashboard]
+        A2 --> A3[查看成员天盘 /member/{memberId}]
+    end
+
+    subgraph 天盘分析
+        A3 --> B1[查看成员兼容性 /compatibility]
+        B1 --> B2[获取年度能量 /annual-energy]
+        B2 --> B3[获取每日运势 /daily-fortune]
+        B3 --> B4[获取相关项目 /related-items]
+    end
+
+    R1(("👤 用户")):::actor
+
+    A1 -.- R1
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/tianpan/dashboard` | 天盘首页 |
+| `/api/tianpan/member/{memberId}` | 成员天盘 |
+| `/api/tianpan/compatibility` | 成员兼容性 |
+| `/api/tianpan/annual-energy` | 年度能量 |
+| `/api/tianpan/daily-fortune` | 每日运势 |
+| `/api/tianpan/related-items` | 相关项目 |

docs/flows/user-auth-flow.md

@@ -0,0 +1,86 @@
+# 用户使用流程图 — 认证与用户管理
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 注册登录
+        A1(("用户")) --> A2{已有账号?}
+        A2 -->|否| A3{注册方式}
+        A3 -->|微信授权| A4[微信静默登录 /silent-login]
+        A3 -->|手机号| A5[发送验证码 /send-code]
+        A5 --> A6[手机号验证码登录 /phone-login]
+        A3 -->|手机号+身份证| A7[注册登录 /register-with-idcard]
+        A3 -->|邀请码| A8[邀请码注册 /register-with-invite]
+        A3 -->|直接注册| A9[直接注册 /direct-register]
+        A4 --> A10[系统自动创建账号]
+        A6 --> A10
+        A7 --> A10
+        A8 --> A10
+        A9 --> A10
+        A2 -->|是| A11{登录方式}
+        A11 -->|微信| A12[微信code登录 /wechat-login]
+        A11 -->|手机号| A13[手机验证码登录 /phone-login]
+        A11 -->|openid| A14[openid自动登录 /auto-login]
+        A12 --> A15[JWT签发]
+        A13 --> A15
+        A14 --> A15
+        A10 --> A15
+    end
+
+    subgraph 认证与安全
+        A15 --> B1[验证JWT Token /verify]
+        B1 --> B2{Token有效?}
+        B2 -->|有效| B3[获取用户信息 /info]
+        B2 -->|过期| B4[重新登录]
+        B3 --> B5[设置密码 /set-password]
+        B3 --> B6[验证密码 /verify-password]
+        B3 --> B7[检查手机号 /check-phone]
+    end
+
+    subgraph 角色切换
+        B3 --> C1{当前角色}
+        C1 -->|家长| C2[切换到孩子视图 /switch-role]
+        C1 -->|孩子| C3[切换回家长 /switch-back-to-parent]
+        C1 -->|带密码校验| C4[密码校验切换 /switch-back-verify]
+        C2 --> C5[获取用户角色列表 /roles]
+        C3 --> C5
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🔐 JWT认证")):::system
+
+    A1 -.- R1
+    A15 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/auth/send-code` | POST | 发送短信验证码 |
+| `/api/auth/phone-login` | POST | 手机号+验证码登录 |
+| `/api/auth/wechat-phone-login` | POST | 微信手机号登录 |
+| `/api/auth/silent-login` | POST | 微信静默登录 |
+| `/api/auth/auto-login` | POST | openid自动登录 |
+| `/api/auth/register-with-idcard` | POST | 手机号+身份证注册登录 |
+| `/api/auth/wechat-login` | POST | 微信code登录 |
+| `/api/auth/info` | POST | 获取当前用户信息 |
+| `/api/auth/set-password` | POST | 设置密码 |
+| `/api/auth/verify` | POST | 验证JWT Token有效性 |
+| `/api/auth/verify-password` | POST | 验证密码 |
+| `/api/auth/check-phone` | POST | 检查手机号是否已注册 |
+| `/api/auth/direct-register` | POST | 直接注册用户 |
+| `/api/auth/register-with-invite` | POST | 使用邀请码注册 |
+| `/api/auth/switch-role` | POST | 切换角色 |
+| `/api/user/info` | POST | 获取用户信息 |
+| `/api/user/update` | POST | 更新用户信息 |
+| `/api/user/children/list` | POST | 获取子女列表 |
+| `/api/user/family-members` | POST | 获取家庭成员列表 |
+| `/api/user/action-stats` | POST | 获取用户行动统计 |

docs/flows/vendor-butler-flow.md

@@ -0,0 +1,49 @@
+# 用户使用流程图 — 管家与商家入驻
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 管家服务
+        A1(("用户")) --> A2[申请管家 /apply]
+        A2 --> A3[获取管家资料 /profile]
+        A3 --> A4[更新资料 /update-profile]
+        A4 --> A5[获取家庭成员 /members]
+    end
+
+    subgraph 商家入驻
+        A1 --> B1[申请入驻 /vendor/apply]
+        B1 --> B2[获取入驻状态 /vendor/status]
+        B2 --> B3[获取商家信息 /vendor/info]
+    end
+
+    subgraph 商家管理
+        B3 --> C1[商家商品列表]
+        C1 --> C2[处理订单]
+        C2 --> C3[发货管理]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("🏪 商家")):::role
+
+    A1 -.- R1
+    B3 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/butler/apply` | 申请管家 |
+| `/api/butler/profile` | 管家资料 |
+| `/api/butler/update-profile` | 更新资料 |
+| `/api/butler/members` | 家庭成员 |
+| `/api/vendor/apply` | 申请入驻 |
+| `/api/vendor/status` | 入驻状态 |
+| `/api/vendor/info` | 商家信息 |

docs/flows/wealth-insurance-flow.md

@@ -0,0 +1,52 @@
+# 用户使用流程图 — 财富与保险
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 财商打卡
+        A1(("用户")) --> A2[获取打卡列表 /wealth/checkin/list]
+        A2 --> A3[获取打卡统计 /wealth/checkin/stats]
+        A3 --> A4[创建打卡 /wealth/checkin/create]
+        A4 --> A5[删除打卡 /wealth/checkin/delete]
+    end
+
+    subgraph 保险规划
+        A5 --> B1[获取保险规划报告 /insurance/planning]
+    end
+
+    subgraph 保单管理
+        B1 --> C1[获取保单列表 /wealth/insurance/list]
+        C1 --> C2[获取保单详情 /wealth/insurance/detail]
+        C2 --> C3[创建保单 /wealth/insurance/create]
+        C3 --> C4[更新保单 /wealth/insurance/update]
+        C4 --> C5[删除保单 /wealth/insurance/delete]
+    end
+
+    R1(("👤 用户")):::actor
+    R2(("💰 财务系统")):::system
+
+    A1 -.- R1
+    C1 -.- R2
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/wealth/checkin/list` | 财商打卡列表 |
+| `/api/wealth/checkin/stats` | 打卡统计 |
+| `/api/wealth/checkin/create` | 创建打卡 |
+| `/api/wealth/checkin/delete` | 删除打卡 |
+| `/api/insurance/planning` | 保险规划报告 |
+| `/api/wealth/insurance/list` | 保单列表 |
+| `/api/wealth/insurance/detail` | 保单详情 |
+| `/api/wealth/insurance/create` | 创建保单 |
+| `/api/wealth/insurance/update` | 更新保单 |
+| `/api/wealth/insurance/delete` | 删除保单 |

docs/flows/wish-management-flow.md

@@ -0,0 +1,71 @@
+# 用户使用流程图 — 心愿管理
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
+    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
+    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef endpoint fill:#f5f5f5,stroke:#616161,stroke-width:1px,shape:box
+
+    subgraph 心愿创建
+        A1(("孩子")) --> A2[创建心愿 /create]
+        A2 --> A3{家长审批}
+        A3 -->|通过| A4[家长定价 /{id}/set-price]
+        A3 -->|拒绝| A5[家长拒绝 /{id}/reject]
+        A4 --> A6[心愿上架 显示积分价格]
+        A5 --> A7[心愿关闭]
+    end
+
+    subgraph 心愿兑换
+        A6 --> B1[孩子申请兑换 /{id}/exchange]
+        B1 --> B2[系统检查积分余额]
+        B2 --> B3{积分充足?}
+        B3 -->|是| B4[家长审批兑换 /{id}/approve-exchange]
+        B3 -->|否| B5[积分不足 提示赚积分]
+        B4 --> B6{家长审批}
+        B6 -->|通过| B7[家长标记已购买 /{id}/fulfill]
+        B6 -->|拒绝| B8[兑换驳回]
+    end
+
+    subgraph 收货完成
+        B7 --> C1[家长购买商品]
+        C1 --> C2[孩子确认收货 /{id}/confirm]
+        C2 --> C3[心愿完成 扣除积分]
+    end
+
+    subgraph 查询管理
+        A6 --> D1[获取心愿列表 /list]
+        D1 --> D2[获取待处理列表 /pending]
+        D2 --> D3[获取心愿详情 /{id}]
+        A7 --> D3
+        C3 --> D1
+        D3 --> E1[取消心愿 /{id}/cancel]
+    end
+
+    R1(("👶 孩子")):::actor
+    R2(("👤 家长")):::role
+    R3(("💎 积分系统")):::system
+
+    A1 -.- R1
+    A3 -.- R2
+    B3 -.- R3
+```
+
+## 端点明细
+
+| 端点 | 说明 |
+|------|------|
+| `/api/wishes/create` | 创建心愿 |
+| `/api/wishes/{id}/set-price` | 家长定价 |
+| `/api/wishes/{id}/reject` | 家长拒绝心愿 |
+| `/api/wishes/{id}/exchange` | 孩子申请兑换 |
+| `/api/wishes/{id}/approve-exchange` | 家长审批兑换 |
+| `/api/wishes/{id}/fulfill` | 家长标记已购买 |
+| `/api/wishes/{id}/confirm` | 孩子确认收货 |
+| `/api/wishes/{id}/cancel` | 取消心愿 |
+| `/api/wishes/list` | 获取心愿列表 |
+| `/api/wishes/pending` | 获取待处理列表 |
+| `/api/wishes/{id}` | 获取心愿详情 |