msh-system/msh_crmeb_22/documents/实现方案_Tool模块API接口.md

# Tool模块API接口实现方案

## 概述

本文档说明如何根据数据库设计和前端API接口（`documents/api/tool.js`）实现后端服务。

## 已完成的工作

### 1. 数据库设计
- ✅ `sql/eb_msh_2.2.sql` - 完整的数据库表结构设计
- ✅ 所有表使用 `v2_` 前缀
- ✅ 使用现有表扩展：`eb_user_sign`（打卡）、`eb_article`（AI视频）、`eb_user_integral_record`（积分流水）

### 2. 前端Controller
- ✅ `crmeb-front/src/main/java/com/zbkj/front/controller/ToolController.java` - 已存在，包含所有接口定义

### 3. Service接口
- ✅ 所有Service接口已存在（`crmeb-service/src/main/java/com/zbkj/service/service/tool/`）

### 4. 已创建的实现类
- ✅ `ToolCalculatorServiceImpl.java` - 食谱计算器服务实现
- ✅ `ToolPointsServiceImpl.java` - 积分系统服务实现
- ✅ `ToolUploadServiceImpl.java` - 文件上传服务实现（已存在）

### 5. 已创建的DAO接口
- ✅ `V2CalculatorResultDao.java` - 食谱计算器结果表DAO
- ✅ `V2NutritionPlanDao.java` - 营养计划表DAO

### 6. 已创建的Model类
- ✅ `V2CalculatorResult.java` - 食谱计算器结果实体
- ✅ `V2NutritionPlan.java` - 营养计划实体

## 待完成的工作

### 1. Model实体类（需要创建）

需要在 `crmeb-common/src/main/java/com/zbkj/common/model/tool/` 目录下创建以下实体类：

1. **V2Food.java** - 食物百科表（`v2_foods`）
2. **V2Knowledge.java** - 营养知识表（`v2_knowledge`）
3. **V2Recipe.java** - 食谱表（`v2_recipes`）
4. **V2CommunityPost.java** - 社区内容表（`v2_community_posts`）
5. **V2CommunityInteraction.java** - 社区互动表（`v2_community_interactions`）
6. **V2CommunityComment.java** - 社区评论表（`v2_community_comments`）
7. **V2CommunityFollow.java** - 关注关系表（`v2_community_follows`）
8. **V2AiConversation.java** - AI营养师对话表（`v2_ai_conversations`）
9. **V2AiMessage.java** - AI营养师消息表（`v2_ai_messages`）
10. **V2NutritionistConsultation.java** - 营养师咨询记录表（`v2_nutritionist_consultations`）
11. **V2UserPoints.java** - 用户积分表（`v2_user_points`）
12. **V2QuickCheckinRecord.java** - 一键打卡记录表（`v2_quick_checkin_records`）

**注意**：
- `eb_user_sign` 表已存在，需要扩展字段（通过ALTER TABLE）
- `eb_article` 表已存在，需要扩展字段（通过ALTER TABLE）
- `eb_user_integral_record` 表已存在，需要扩展字段（通过ALTER TABLE）

### 2. DAO接口（需要创建）

需要在 `crmeb-service/src/main/java/com/zbkj/service/dao/tool/` 目录下创建以下DAO接口：

1. **V2FoodDao.java**
2. **V2KnowledgeDao.java**
3. **V2RecipeDao.java**
4. **V2CommunityPostDao.java**
5. **V2CommunityInteractionDao.java**
6. **V2CommunityCommentDao.java**
7. **V2CommunityFollowDao.java**
8. **V2AiConversationDao.java**
9. **V2AiMessageDao.java**
10. **V2NutritionistConsultationDao.java**
11. **V2UserPointsDao.java**
12. **V2QuickCheckinRecordDao.java**

### 3. Service实现类（需要创建）

需要在 `crmeb-service/src/main/java/com/zbkj/service/service/impl/tool/` 目录下创建以下实现类：

1. **ToolCheckinServiceImpl.java** - 饮食打卡服务实现（核心功能）
2. **ToolFoodServiceImpl.java** - 食物百科服务实现
3. **ToolKnowledgeServiceImpl.java** - 营养知识服务实现
4. **ToolRecipeServiceImpl.java** - 食谱服务实现
5. **ToolCommunityServiceImpl.java** - 打卡社区服务实现（核心功能）
6. **ToolAiNutritionistServiceImpl.java** - AI营养师服务实现
7. **ToolHomeServiceImpl.java** - 首页数据服务实现

### 4. 核心实现逻辑说明

#### 4.1 ToolCheckinServiceImpl（饮食打卡）

**主要功能**：
- `submit()` - 提交打卡记录
  - 保存到 `eb_user_sign` 表（type=3）
  - 调用AI识别服务（如果启用）
  - 计算营养数据
  - 生成营养分析报告
  - 计算并发放积分
  - 更新连续打卡天数
  
- `getList()` - 获取打卡记录列表
  - 查询 `eb_user_sign` 表（type=3）
  - 支持按日期、餐次筛选
  
- `getDetail()` - 获取打卡详情
  - 包含AI识别结果、营养分析等
  
- `getStreak()` - 获取连续打卡统计
  - 从 `v2_user_points` 表获取
  
- `getCalendar()` - 获取打卡日历数据
  - 按月统计打卡情况
  
- `copy()` - 一键复制打卡
  - 复制现有打卡记录
  
- `learn()` - 一键借鉴打卡
  - 从社区内容创建打卡记录

#### 4.2 ToolCommunityServiceImpl（打卡社区）

**主要功能**：
- `getList()` - 获取社区内容列表
  - 支持推荐/最新/关注/热门等Tab
  - 需要实现推荐算法
  
- `publish()` - 发布社区内容
  - 保存到 `v2_community_posts` 表
  - 关联打卡记录（可选）
  
- `toggleLike()` - 点赞/取消点赞
  - 操作 `v2_community_interactions` 表
  
- `addComment()` - 发表评论
  - 保存到 `v2_community_comments` 表
  - 支持二级评论

#### 4.3 ToolAiNutritionistServiceImpl（AI营养师）

**主要功能**：
- `sendMessage()` - 发送消息
  - 保存到 `v2_ai_messages` 表
  - 调用AI接口获取回复
  - 保存AI回复
  
- `getHistory()` - 获取对话历史
  - 查询 `v2_ai_conversations` 和 `v2_ai_messages` 表

#### 4.4 ToolFoodServiceImpl（食物百科）

**主要功能**：
- `search()` - 搜索食物
  - 支持关键词和分类搜索
  - 查询 `v2_foods` 表
  
- `getDetail()` - 获取食物详情
  - 包含营养成分、适宜性等信息

#### 4.5 ToolKnowledgeServiceImpl（营养知识）

**主要功能**：
- `getList()` - 获取知识列表
  - 支持按类型、分类筛选
  - 查询 `v2_knowledge` 表

#### 4.6 ToolRecipeServiceImpl（食谱）

**主要功能**：
- `getList()` - 获取食谱列表
  - 支持按餐次筛选
  - 查询 `v2_recipes` 表

#### 4.7 ToolHomeServiceImpl（首页数据）

**主要功能**：
- `getData()` - 获取首页数据
  - 整合各种数据源
  
- `getRecommendedRecipes()` - 获取推荐食谱
  - 根据用户健康数据推荐
  
- `getRecommendedKnowledge()` - 获取推荐营养知识
  - 根据用户CKD分期推荐

## 实现步骤建议

### 第一步：创建所有Model实体类
参考 `V2CalculatorResult.java` 的格式，根据数据库表结构创建所有实体类。

### 第二步：创建所有DAO接口
参考 `V2CalculatorResultDao.java` 的格式，创建所有DAO接口。

### 第三步：实现核心Service
按优先级实现：
1. ToolCheckinServiceImpl（核心功能）
2. ToolPointsServiceImpl（已完成）
3. ToolCommunityServiceImpl（核心功能）
4. ToolCalculatorServiceImpl（已完成）
5. 其他Service

### 第四步：测试和优化
- 单元测试
- 集成测试
- 性能优化

## 注意事项

1. **用户认证**：所有接口都需要通过 `FrontTokenComponent.getUserId()` 获取当前用户ID
2. **事务管理**：涉及多表操作的接口需要使用 `@Transactional` 注解
3. **异常处理**：统一使用 `CrmebException` 抛出业务异常
4. **分页查询**：使用 `PageHelper.startPage()` 进行分页
5. **JSON字段**：使用 `JSON.toJSONString()` 和 `JSON.parseObject()` 处理JSON字段
6. **日期处理**：注意 `LocalDate` 和 `Date` 的转换
7. **积分计算**：参考PRD文档中的积分规则实现
8. **AI识别**：AI识别功能需要对接第三方服务（如腾讯云、百度AI等）

## 数据库字段映射

### eb_user_sign 扩展字段（打卡专用）
- `plan_id` - 关联的营养计划ID
- `meal_type` - 餐次
- `photos_json` - 照片数组
- `notes` - 备注
- `voice_url` - 语音URL
- `ai_recognized_foods_json` - AI识别结果
- `ai_recognition_status` - AI识别状态
- `actual_protein` - 实际蛋白质
- `actual_energy` - 实际能量
- `nutrition_score` - 营养评分
- 等等...

### eb_article 扩展字段（AI视频专用）
- `post_id` - 关联的社区内容ID
- `check_in_record_id` - 关联的打卡记录ID
- `thumbnail_url` - 视频缩略图
- `duration` - 视频时长
- `script_json` - 视频脚本
- `dishes_json` - 菜品清单
- `nutrition_json` - 营养数据
- `generation_method` - 生成方式
- `ai_provider` - AI提供商
- 等等...

## 参考代码

- `ToolCalculatorServiceImpl.java` - 食谱计算器实现示例
- `ToolPointsServiceImpl.java` - 积分系统实现示例
- `UserSignServiceImpl.java` - 用户签到服务实现（可参考）
- `ArticleServiceImpl.java` - 文章服务实现（可参考）

## 后续优化

1. 缓存优化：使用Redis缓存热点数据
2. 异步处理：AI识别、视频生成等耗时操作使用异步处理
3. 消息队列：使用消息队列处理积分计算、统计等任务
4. 搜索引擎：食物搜索、知识搜索可以使用Elasticsearch
5. 推荐算法：社区内容推荐可以使用机器学习算法