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. 推荐算法：社区内容推荐可以使用机器学习算法