plates-server/docs/DIET_CONFIRMATION_IMPLEMENTATION_SUMMARY.md

饮食记录确认流程实现总结

项目概述

将原有的饮食记录功能从"自动记录模式"升级为"用户确认模式"，类似于 Cline、Kilo 等开源 AI 工具的交互体验。

实现的功能

1. 两阶段饮食记录流程

• 第一阶段：AI识别图片中的食物，生成多个确认选项
• 第二阶段：用户选择确认选项后，系统记录到数据库并提供营养分析

2. 新增数据结构

AiChoiceOptionDto

{
  id: string;           // 选项唯一标识符
  label: string;        // 显示给用户的文本（如"一条鱼 200卡"）
  value: any;          // 选项对应的数据
  recommended?: boolean; // 是否为推荐选项
}

AiResponseDataDto

{
  content: string;                    // AI回复的文本内容
  choices?: AiChoiceOptionDto[];      // 选择选项（可选）
  interactionType?: string;           // 交互类型
  pendingData?: any;                  // 需要用户确认的数据
  context?: any;                      // 上下文信息
}

FoodConfirmationOption

{
  id: string;
  label: string;
  foodName: string;
  portion: string;
  calories: number;
  mealType: MealType;
  nutritionData: { ... };
}

3. API 增强

请求参数新增

• selectedChoiceId?: string - 用户选择的选项ID
• confirmationData?: any - 用户确认的数据

响应结构新增

• 支持返回结构化数据（选择选项）
• 支持返回传统流式文本

修改的文件

1. DTO 层

• src/ai-coach/dto/ai-chat.dto.ts
  • 新增 AiChoiceOptionDto
  • 新增 AiResponseDataDto
  • 扩展 AiChatRequestDto 和 AiChatResponseDto

2. 服务层

• src/ai-coach/services/diet-analysis.service.ts

  • 新增 FoodConfirmationOption 接口
  • 新增 FoodRecognitionResult 接口
  • 新增 recognizeFoodForConfirmation() 方法
  • 新增 createDietRecordFromConfirmation() 方法
  • 新增 buildFoodRecognitionPrompt() 方法
  • 新增 parseRecognitionResult() 方法

• src/ai-coach/ai-coach.service.ts

  • 更新 streamChat() 方法参数和返回类型
  • 重构饮食记录逻辑，支持两阶段确认流程
  • 新增结构化数据返回逻辑

3. 控制器层

• src/ai-coach/ai-coach.controller.ts
  • 更新 chat() 方法，支持结构化响应
  • 新增确认数据处理逻辑

4. 文档

• docs/diet-confirmation-flow-api.md - 新增API使用文档
• docs/DIET_CONFIRMATION_IMPLEMENTATION_SUMMARY.md - 本总结文档

流程示例

用户上传图片

1. 用户发送 #记饮食 指令并上传图片
2. AI识别食物，返回确认选项：

   {
     "choices": [
       {"id": "food_0", "label": "一条鱼 200卡", "value": {...}},
       {"id": "food_1", "label": "一根玉米 40卡", "value": {...}}
     ],
     "interactionType": "food_confirmation"
   }
   

用户确认选择

1. 用户选择某个选项
2. 客户端发送确认请求，包含 selectedChoiceId 和 confirmationData
3. 系统记录到数据库，返回营养分析

技术特点

1. 向后兼容

• 保留原有的自动记录逻辑（analyzeDietImageEnhanced 方法）
• 新流程不影响其他功能

2. 类型安全

• 所有新增接口都有完整的 TypeScript 类型定义
• 使用 class-validator 进行数据验证

3. 错误处理

• 图片识别失败时回退到普通文本响应
• 确认数据无效时提供友好错误提示

4. 用户体验

• 类似 Cline/Kilo 的交互体验
• 清晰的选项展示（如"一条鱼 200卡"）
• 推荐选项标识

部署说明

1. 代码已通过编译测试，无 TypeScript 错误
2. 保持向后兼容性，可以平滑部署
3. 建议先在测试环境验证新流程

使用建议

1. 客户端适配：需要客户端支持处理结构化响应和选择选项
2. 图片质量：提醒用户上传清晰的食物图片
3. 用户引导：在界面上提供使用说明

后续优化方向

1. 支持批量选择多个食物
2. 支持用户自定义修改份量和热量
3. 添加更多营养素信息展示
4. 支持语音确认
5. 添加食物历史记录快速选择