# 用户使用流程图 — 营养与饮食推荐

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

```mermaid
flowchart TD
    %% ============ 颜色定义 ============
    classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px
    classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
    classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
    classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2
    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3

    %% ============ 角色 ============
    A0(("👤 用户/家长")):::actor

    %% ================================================================
    %% 阶段一：食谱推荐
    %% ================================================================
    subgraph 阶段一[阶段一：食谱推荐]
        direction TB

        P1["🏠 小程序：饮食推荐页"]:::page
        P1 -->|"请求推荐"| A1["🔗 POST /api/meal/recommend"]:::api
        A1 -->|"userId, mealType"| S1["⚙️ MealRecommendService.aggregateContext()"]:::service
        S1 -->|"健康报告"| S1a["⚙️ HealthReportService.getLatestReport()"]:::service
        S1a -->|"最新报告"| D_HR["📦 health_reports 表"]:::data
        S1 -->|"异常指标"| S1b["⚙️ HealthReportService.getReportIndicators()"]:::service
        S1b -->|"指标列表"| D_HRI["📦 health_report_indicators 表"]:::data
        S1 -->|"营养偏好"| S1c["⚙️ UserNutritionProfileService.getByUserId()"]:::service
        S1c -->|"用户偏好"| D_NP["📦 user_nutrition_profile 表"]:::data
        S1 -->|"近期摄入"| S1d["⚙️ MealLogService.getNutritionSummary()"]:::service
        S1d -->|"7日营养汇总"| D_ML["📦 meal_logs 表"]:::data
        S1 -->|"候选食材"| S1e["⚙️ FoodService.listAll() + SeasonalFoodService"]:::service
        S1e -->|"当季活跃食材"| D_FOOD["📦 foods 表"]:::data

        S1 -->|"聚合上下文"| S1_final["⚙️ MealRecommendService.buildDifyInputs()"]:::service
        S1_final -->|"用户画像, 健康摘要, 候选食材"| S_AI["⚙️ AIService.sendNutritionMessage() — Dify AI"]:::service
        S_AI -->|"AI返回JSON食谱"| P1

        P1 -->|"一换一菜"| A2["🔗 POST /api/meal/replace"]:::api
        A2 -->|"foodId, userId"| S2["⚙️ MealRecommendService.findReplaceCandidate()"]:::service
        S2 -->|"同品类同价位替换食材"| D_FOOD
    end

    %% ================================================================
    %% 阶段二：饮食记录
    %% ================================================================
    subgraph 阶段二[阶段二：饮食记录]
        P1 -->|"满意, 记录饮食"| P2["🏠 记录饮食页"]:::page
        P2 -->|"提交饮食日志"| A3["🔗 POST /api/meal/log"]:::api
        A3 -->|"userId, childId, mealType, foods, note, mealDate"| S3["⚙️ MealLogService.create()"]:::service
        S3 -->|"写入一条记录"| D_ML

        P2 -->|"查看近期日志"| A4["🔗 POST /api/meal/logs"]:::api
        A4 -->|"userId, days"| S4["⚙️ MealLogService.getRecentMeals()"]:::service
        S4 -->|"近期饮食列表"| D_ML

        P2 -->|"查看营养统计"| A5["🔗 POST /api/meal/nutrition-summary"]:::api
        A5 -->|"userId, days"| S5["⚙️ MealLogService.getNutritionSummary()"]:::service
        S5 -->|"营养摄入汇总"| D_ML
    end

    %% ================================================================
    %% 阶段三：食材推荐指数
    %% ================================================================
    subgraph 阶段三[阶段三：食材推荐指数]
        P2 -->|"打开食材指数"| P3["🏠 食材推荐指数页"]:::page
        P3 -->|"查看指数"| A6["🔗 POST /api/food/recommendation/index"]:::api
        A6 -->|"userId"| S6["⚙️ FoodRecommendService.getIndexByUser()"]:::service
        S6 -->|"食材推荐指数列表"| D_FRI["📦 food_recommend_index 表"]:::data

        P3 -->|"查看变更历史"| A7["🔗 POST /api/food/recommendation/history"]:::api
        A7 -->|"userId, foodId"| S7["⚙️ FoodRecommendService.getIndexHistory()"]:::service
        S7 -->|"指数变更记录"| D_FRIL["📦 food_recommend_idx_log 表"]:::data

        P3 -->|"按家庭分组"| A8["🔗 POST /api/food/recommendation/by-family"]:::api
        A8 -->|"familyId"| S8["⚙️ FoodRecommendService.getByFamily()"]:::service
        S8 -->|"家庭成员指数（按成员分组）"| D_FRI
    end

    %% ================================================================
    %% 阶段四：营养偏好管理
    %% ================================================================
    subgraph 阶段四[阶段四：营养偏好管理]
        P3 -->|"管理偏好"| P4["🏠 营养偏好设置页"]:::page
        P4 -->|"获取偏好"| A9["🔗 POST /api/nutrition/profile/get"]:::api
        A9 -->|"userId"| S9["⚙️ UserNutritionProfileService.getByUserId()"]:::service
        S9 -->|"当前偏好配置"| D_NP

        P4 -->|"保存偏好"| A10["🔗 POST /api/nutrition/profile/save"]:::api
        A10 -->|"userId, budgetMonthly, familyTastePreferences, cuisineStyle, mealCount, cookingAbility"| S10["⚙️ UserNutritionProfileService.save()"]:::service
        S10 -->|"插入/更新"| D_NP
    end

    %% ================================================================
    %% 阶段五：北京营养知识库
    %% ================================================================
    subgraph 阶段五[阶段五：北京营养知识库]
        P4 -->|"打开精准营养"| P5["🏠 北京精准营养页"]:::page
        P5 -->|"查询菌属"| A11["🔗 POST /api/nutrition/beijing/kb/query"]:::api
        A11 -->|"name（拉丁名/中文名）"| S11["⚙️ BacteriaFoodMapping.findAny()"]:::service
        S11 -->|"菌属详情: 功能, 升降建议, 食物"| D_KBB["📦 BacteriaFoodMapping（内存知识库）"]:::data

        P5 -->|"知识库列表"| A12["🔗 POST /api/nutrition/beijing/kb/list"]:::api
        A12 -->|"无参数"| S12["⚙️ BacteriaFoodMapping.getAllEntries()"]:::service
        S12 -->|"全部菌属列表"| D_KBB

        P5 -->|"知识库概况"| A13["🔗 POST /api/nutrition/beijing/kb/info"]:::api
        A13 -->|"无参数"| S13["⚙️ BacteriaFoodMapping.getMetadata()"]:::service
        S13 -->|"元数据 + 总菌属数"| D_KBB

        P5 -->|"保存菌群状态"| A14["🔗 POST /api/nutrition/beijing/bacteria/save"]:::api
        A14 -->|"userId, bacteriaList[{latinName, chineseName, status}]"| S14["⚙️ BeijingNutritionService.saveBacteriaStatus()"]:::service
        S14 -->|"写入菌群记录"| D_BAC["📦 bacteria_status 表"]:::data

        P5 -->|"基于菌群推荐食材"| A15["🔗 POST /api/nutrition/beijing/recommend"]:::api
        A15 -->|"userId, limit"| S15["⚙️ BeijingNutritionService.recommendFromDb()"]:::service
        S15 -->|"推荐食材, 原因, 注意事项"| D_BAC

        P5 -->|"自定义菌群推荐"| A16["🔗 POST /api/nutrition/beijing/recommend/custom"]:::api
        A16 -->|"userId, bacteriaList[{latinName, chineseName, status}]"| S16["⚙️ BeijingNutritionService.recommend()"]:::service
        S16 -->|"临时菌群状态→推荐食材"| D_KBB
    end

    %% ================================================================
    %% 阶段六：营养师申请
    %% ================================================================
    subgraph 阶段六[阶段六：营养师申请]
        P5 -->|"申请营养师"| P6["🏠 营养师申请页"]:::page
        P6 -->|"提交申请"| A17["🔗 POST /api/nutritionist/apply"]:::api
        A17 -->|"userId（从token提取）"| S17["⚙️ NutritionistController — 设置nutritionistStatus=pending"]:::service
        S17 -->|"更新用户营养师状态 + 添加nutritionist角色"| D_USER["📦 users 表"]:::data

        P6 -->|"查询申请状态"| A18["🔗 POST /api/nutritionist/status"]:::api
        A18 -->|"userId（从token提取）"| S18["⚙️ NutritionistController — 查询状态字段"]:::service
        S18 -->|"nutritionistStatus, rejectReason"| D_USER
    end

    %% ================================================================
    %% 阶段七：推荐商品与复购
    %% ================================================================
    subgraph 阶段七[阶段七：推荐商品与复购]
        P6 -->|"维度页推荐"| P7["🏠 五维推荐商品区"]:::page
        P7 -->|"获取推荐"| A19["🔗 POST /api/recommend/dimension-products"]:::api
        A19 -->|"dimensionCode, familyId, memberId, excludeProductIds, limit"| S19["⚙️ ProductRecommendationService.getDimensionRecommendations()"]:::service
        S19 -->|"维度相关商品列表"| D_PROD["📦 products 表"]:::data

        P7 -->|"复购提醒列表"| A20["🔗 POST /api/recommend/repurchase-reminders/list"]:::api
        A20 -->|"userId（从token提取）"| S20["⚙️ RepurchaseReminderService.getPendingReminders()"]:::service
        S20 -->|"待处理复购提醒"| D_RR["📦 repurchase_reminder_records 表"]:::data

        P7 -->|"标记已点击"| A21["🔗 POST /api/recommend/repurchase-reminders/click"]:::api
        A21 -->|"reminderId"| S21["⚙️ RepurchaseReminderService.onReminderClicked()"]:::service
        S21 -->|"更新点击状态和时间"| D_RR

        P7 -->|"标记已购买"| A22["🔗 POST /api/recommend/repurchase-reminders/purchased"]:::api
        A22 -->|"reminderId, orderId"| S22["⚙️ RepurchaseReminderService.onReminderPurchased()"]:::service
        S22 -->|"更新购买状态和订单关联"| D_RR
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    A0 -.- P1
    A0 -.- P2
    A0 -.- P3
    A0 -.- P4
    A0 -.- P5
    A0 -.- P6
    A0 -.- P7
```

## 端点明细

### 食谱推荐与记录

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/meal/recommend` | 获取AI食谱推荐 | 📱小程序 | `{mealType, conversationId}` | `{answer(JSON食谱), conversationId, replaceOptions, nutritionSummary}` |
| `POST /api/meal/replace` | 一换一菜 — 替换食材 | 📱小程序 | `{foodId}` | `Food`（同类替代食材） |
| `POST /api/meal/log` | 记录饮食日志 | 📱小程序 | `{childId, mealType, foods, note, mealDate}` | `{id, message}` |
| `POST /api/meal/logs` | 获取近期饮食日志 | 📱小程序 | `{days}` | `[MealLog]` |
| `POST /api/meal/nutrition-summary` | 营养摄入统计 | 📱小程序 | `{days}` | `{calories, protein, fat, carb, ...}` |

### 食材推荐指数

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/food/recommendation/index` | 获取用户食材推荐指数 | 📱小程序 | `{userId}` | `[FoodRecommendIndex（食材, 推荐等级, 理由）]` |
| `POST /api/food/recommendation/history` | 指数变更历史 | 📱小程序 | `{userId, foodId}` | `[FoodRecommendIdxLog（变更记录）]` |
| `POST /api/food/recommendation/by-family` | 按家庭分组获取指数 | 📱小程序 | `{familyId}` | `Map<成员ID, [FoodRecommendIndex]>` |

### 营养偏好

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/nutrition/profile/get` | 获取当前用户营养偏好 | 📱小程序 | — | `UserNutritionProfile` |
| `POST /api/nutrition/profile/save` | 保存营养偏好 | 📱小程序 | `{budgetMonthly, familyTastePreferences, cuisineStyle, mealCount, cookingAbility}` | `"ok"` |

### 北京精准营养（菌群知识库）

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/nutrition/beijing/bacteria/save` | 保存用户菌群状态 | 📱小程序 | `{userId, bacteriaList[{latinName, chineseName, status}]}` | `"保存成功"` |
| `POST /api/nutrition/beijing/recommend` | 基于已保存菌群推荐食材 | 📱小程序 | `{userId, limit}` | `NutritionRecommendResponse（分类推荐列表）` |
| `POST /api/nutrition/beijing/recommend/custom` | 自定义菌群状态推荐食材 | 📱小程序 | `{userId, bacteriaList[{latinName, chineseName, status}]}` | `NutritionRecommendResponse` |
| `POST /api/nutrition/beijing/kb/query` | 查询菌属知识库 | 📱小程序 | `{name}` | `BacteriaEntry（功能, 升降建议, 适配食物）` |
| `POST /api/nutrition/beijing/kb/list` | 知识库菌属列表 | 📱小程序 | — | `[BacteriaEntry]` |
| `POST /api/nutrition/beijing/kb/info` | 知识库概况 | 📱小程序 | — | `{metadata, 总菌属数, 菌属列表}` |

### 营养师申请

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/nutritionist/apply` | 提交营养师申请 | 📱小程序 | — | `"营养师申请已提交，请等待审核"` |
| `POST /api/nutritionist/status` | 查询营养师申请状态 | 📱小程序 | — | `{nutritionistStatus, nutritionistRejectReason}` |

### 推荐商品与复购提醒

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/recommend/dimension-products` | 获取维度页推荐商品 | 📱小程序 | `{dimensionCode, familyId, memberId, excludeProductIds, limit}` | `[{productId, name, price, image, ...}]` |
| `POST /api/recommend/repurchase-reminders/list` | 获取待处理复购提醒 | 📱小程序 | — | `[{id, productName, lastPurchaseDate, ...}]` |
| `POST /api/recommend/repurchase-reminders/click` | 标记复购提醒已点击 | 📱小程序 | `{id}` | — |
| `POST /api/recommend/repurchase-reminders/purchased` | 标记复购提醒已购买 | 📱小程序 | `{id, orderId}` | — |

## 数据实体关系

```mermaid
erDiagram
    User ||--o| UserNutritionProfile : "一个用户一个偏好"
    User ||--o{ MealLog : "一个用户多条日志"
    User ||--o{ FoodRecommendIndex : "一个用户多个食材指数"
    FamilyMember ||--o{ FoodRecommendIndex : "一个成员多个食材指数"
    User ||--o{ RepurchaseReminderRecord : "一个用户多个复购提醒"
    Product ||--o{ RepurchaseReminderRecord : "一个商品多个复购提醒"

    UserNutritionProfile {
        Long id PK
        Long userId FK
        int budgetMonthly "月预算(元)"
        string familyTastePreferences "口味偏好"
        string cuisineStyle "菜系偏好"
        int mealCount "每日餐数"
        string cookingAbility "烹饪能力"
    }

    MealLog {
        Long id PK
        Long userId FK
        Long childId "关联孩子(可选)"
        string mealType "早餐/午餐/晚餐/加餐"
        string foods "食物JSON数组"
        string note "备注"
        date mealDate "就餐日期"
    }

    FoodRecommendIndex {
        Long id PK
        Long userId FK
        Long foodId FK
        string recommendLevel "推荐/适量/谨慎/避免"
        string reason "推荐理由"
    }

    RepurchaseReminderRecord {
        Long id PK
        Long userId FK
        Long productId FK
        string status "pending/clicked/purchased"
        date lastPurchaseDate
        date remindDate
    }
```

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖食谱推荐→饮食记录→食材指数→偏好管理→精准营养（北京菌群）→营养师申请→商品推荐7个阶段，构成完整"推荐→记录→分析→优化"闭环 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 食谱推荐失败返回错误信息（catch Exception）；食材替换无候选时返回"没有可替换的食材"；营养师重复提交被拒绝；但AI服务超时/降级等未在流程图体现 |
| 3 | **端点覆盖** | ✅ 完整 | 22个端点全部映射到流程图中，与MealRecommendController、FoodRecommendController、UserNutritionProfileController、BeijingNutritionController、NutritionistController、ProductRecommendationController、RepurchaseReminderController实际代码一致 |
| 4 | **角色覆盖** | ✅ 完整 | 用户/家长端可操全部7个阶段；营养师申请需管理员审核（管理后台操作未在本图展开）；商品推荐可被所有角色使用 |
| 5 | **数据实体** | ✅ 完整 | user_nutrition_profile、meal_logs、foods、food_recommend_index、food_recommend_idx_log、health_reports、health_report_indicators、bacteria_status、repurchase_reminder_records、products 10个实体/数据源均在图中映射 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller中的`@PostMapping`匹配；AI食谱推荐调用的Dify服务链路（aggregateContext→buildDifyInputs→AIService.sendNutritionMessage）与实际Service代码一致 |