feat: 实现饮食记录确认流程
- 新增饮食记录确认流程，将自动记录模式升级为用户确认模式，提升用户交互体验。 - 实现两阶段饮食记录流程，支持AI识别食物并生成确认选项，用户选择后记录到数据库并提供营养分析。 - 扩展DTO层，新增相关数据结构以支持确认流程。 - 更新服务层，新增处理确认逻辑的方法，优化饮食记录的创建流程。 - 增强API文档，详细说明新流程及使用建议，确保开发者理解和使用新功能。
This commit is contained in:
richarjiang
148
docs/DIET_CONFIRMATION_IMPLEMENTATION_SUMMARY.md
Normal file
148
docs/DIET_CONFIRMATION_IMPLEMENTATION_SUMMARY.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 饮食记录确认流程实现总结
|
||||
|
||||
## 项目概述
|
||||
|
||||
将原有的饮食记录功能从"自动记录模式"升级为"用户确认模式"，类似于 Cline、Kilo 等开源 AI 工具的交互体验。
|
||||
|
||||
## 实现的功能
|
||||
|
||||
### 1. 两阶段饮食记录流程
|
||||
|
||||
- **第一阶段**：AI识别图片中的食物，生成多个确认选项
|
||||
- **第二阶段**：用户选择确认选项后，系统记录到数据库并提供营养分析
|
||||
|
||||
### 2. 新增数据结构
|
||||
|
||||
#### AiChoiceOptionDto
|
||||
```typescript
|
||||
{
|
||||
id: string; // 选项唯一标识符
|
||||
label: string; // 显示给用户的文本（如"一条鱼 200卡"）
|
||||
value: any; // 选项对应的数据
|
||||
recommended?: boolean; // 是否为推荐选项
|
||||
}
|
||||
```
|
||||
|
||||
#### AiResponseDataDto
|
||||
```typescript
|
||||
{
|
||||
content: string; // AI回复的文本内容
|
||||
choices?: AiChoiceOptionDto[]; // 选择选项（可选）
|
||||
interactionType?: string; // 交互类型
|
||||
pendingData?: any; // 需要用户确认的数据
|
||||
context?: any; // 上下文信息
|
||||
}
|
||||
```
|
||||
|
||||
#### FoodConfirmationOption
|
||||
```typescript
|
||||
{
|
||||
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识别食物，返回确认选项：
|
||||
```json
|
||||
{
|
||||
"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. 添加食物历史记录快速选择
|
||||
Reference in New Issue
Block a user