PoJie/ruoyi-modules/ruoyi-ai/MODULE_STRUCTURE.md

AI模块结构说明

模块简介

ruoyi-ai 是 PoJie 项目的 AI 服务中心模块，提供统一的 AI 能力接入，标准化接入主流模型与平台，支持聊天、流式对话、AI创作、智能PPT、多模态理解、代码助手、RAG增强与统一监控等功能。

模块结构

ruoyi-ai 是一个独立的业务模块，采用分层架构设计：

org.dromara.ai
├── config/              # 模块配置类
│   ├── AiAutoConfiguration.java          # 自动配置类
│   ├── AiGatewayProperties.java          # 网关配置属性
│   ├── AiProviderRegistrar.java          # Provider注册器
│   ├── AiConfigurationManager.java       # 配置管理器
│   ├── AiApiConfig.java                  # API配置
│   └── *ProviderConfig.java              # 各Provider配置类（OpenAI、Azure、Qwen、Zhipu等）
├── controller/          # REST API控制器
│   ├── admin/                           # 管理端接口
│   │   ├── AdminAiChatRecordController.java    # 聊天记录管理接口
│   │   ├── AdminAiUsageStatsController.java    # 使用统计管理接口
│   │   ├── AdminAiRatingRecordController.java  # 评价记录管理接口
│   │   ├── AdminAiProviderController.java      # Provider管理接口
│   │   ├── AdminAiProviderConfigController.java # Provider配置管理接口
│   │   ├── AdminAiProviderConfigHistoryController.java # Provider配置历史管理接口
│   │   ├── AdminAiSensitiveWordController.java # 敏感词管理接口
│   │   ├── AdminAiPaintingRecordController.java # 绘画历史记录管理接口
│   │   ├── AdminAiPaintingTemplateController.java # 绘画参数模板管理接口
│   │   ├── AdminAiPaintingFavoriteController.java # 绘画作品收藏管理接口
│   │   ├── AdminAiUserQuotaController.java # 用户配额管理接口
│   │   └── AdminSysModelController.java        # 系统模型管理接口
│   └── app/                             # 用户端接口
│       ├── AiChatController.java                # 聊天接口
│       ├── AiAssistantController.java           # 代码助手接口
│       ├── AiPaintingController.java            # 绘画接口
│       ├── AiImageController.java               # DALL·E-3接口
│       ├── PptController.java                   # PPT生成接口
│       ├── MultimodalController.java            # 多模态接口
│       ├── SimpleAiController.java              # Simple AI接口
│       ├── FastGptController.java               # FastGPT接口
│       ├── CozeController.java                  # Coze接口
│       ├── DifyController.java                  # DIFY接口
│       ├── McpController.java                   # MCP工具接口
│       ├── QueueMetricsController.java          # 队列指标接口
│       ├── AppAiRatingRecordController.java     # 评价记录接口（用户端）
│       ├── AppAiPaintingFavoriteController.java # 绘画作品收藏接口（用户端）
│       └── AppAiUserQuotaController.java        # 用户配额接口（用户端）
├── domain/              # 领域对象
│   ├── AiChatRecord.java                # 聊天记录实体
│   ├── AiUsageStats.java                # 使用统计实体
│   ├── AiRatingRecord.java              # 评价记录实体
│   ├── AiProviderConfig.java            # Provider配置实体
│   ├── AiProviderConfigHistory.java     # Provider配置历史实体
│   ├── AiSensitiveWord.java             # 敏感词实体
│   ├── AiPaintingRecord.java            # 绘画历史记录实体
│   ├── AiPaintingTemplate.java          # 绘画参数模板实体
│   ├── AiPaintingFavorite.java          # 绘画作品收藏实体
│   ├── AiUserQuota.java                 # 用户配额实体
│   ├── bo/                              # 业务对象(BO)
│   │   ├── AiChatRecordBo.java          # 聊天记录BO
│   │   ├── AiUsageStatsBo.java          # 使用统计BO
│   │   ├── AiRatingRecordBo.java        # 评价记录BO
│   │   ├── AiProviderConfigBo.java      # Provider配置BO
│   │   ├── AiProviderConfigHistoryBo.java # Provider配置历史BO
│   │   ├── AiSensitiveWordBo.java       # 敏感词BO
│   │   ├── AiPaintingRecordBo.java      # 绘画历史记录BO
│   │   ├── AiPaintingTemplateBo.java    # 绘画参数模板BO
│   │   ├── AiPaintingFavoriteBo.java    # 绘画作品收藏BO
│   │   └── AiUserQuotaBo.java           # 用户配额BO
│   ├── vo/                              # 视图对象(VO)
│   │   ├── AiChatRecordVo.java          # 聊天记录VO
│   │   ├── AiUsageStatsVo.java          # 使用统计VO
│   │   ├── AiRatingRecordVo.java        # 评价记录VO
│   │   ├── AiProviderConfigVo.java      # Provider配置VO
│   │   ├── AiProviderConfigHistoryVo.java # Provider配置历史VO
│   │   ├── AiSensitiveWordVo.java       # 敏感词VO
│   │   ├── AiPaintingRecordVo.java      # 绘画历史记录VO
│   │   ├── AiPaintingTemplateVo.java    # 绘画参数模板VO
│   │   ├── AiPaintingFavoriteVo.java    # 绘画作品收藏VO
│   │   └── AiUserQuotaVo.java           # 用户配额VO
│   ├── dto/                             # 数据传输对象(DTO)
│   │   ├── AiChatRequest.java           # 聊天请求DTO
│   │   ├── AiChatResponse.java          # 聊天响应DTO
│   │   └── AiModelInfo.java             # 模型信息DTO
│   └── enums/                           # 枚举类
│       └── AiProviderType.java          # Provider类型枚举
├── provider/            # 模型 Provider 实现
│   ├── AiProvider.java                  # Provider接口
│   ├── AbstractAiProvider.java          # Provider抽象基类
│   ├── AiProviderManager.java           # Provider管理器
│   ├── OpenAiProvider.java              # OpenAI Provider
│   ├── AzureOpenAiProvider.java         # Azure OpenAI Provider
│   ├── QwenProvider.java                # 通义千问 Provider
│   ├── ZhipuAiProvider.java             # 智谱AI Provider
│   ├── FastGptProvider.java             # FastGPT Provider
│   ├── CozeProvider.java                # Coze Provider
│   ├── DifyProvider.java                # DIFY Provider
│   └── impl/                            # Provider实现
│       └── MockAiProvider.java          # Mock Provider（测试用）
├── service/             # 核心业务服务
│   ├── AiChatService.java               # 聊天服务
│   ├── AiChatHistoryService.java        # 聊天历史服务
│   ├── AiCodingAssistantService.java    # 代码助手服务
│   ├── AiModelService.java              # 模型服务
│   ├── AiPaintingService.java           # 绘画服务
│   └── SimpleAiService.java             # Simple AI服务
├── orchestration/       # AI 编排引擎
│   └── AiOrchestrationEngine.java       # 编排引擎（智能路由、负载均衡、降级）
├── painting/            # 绘画服务与 Provider
│   ├── PaintingEngineType.java          # 绘画引擎类型枚举
│   ├── PaintingTask.java                # 绘画任务模型
│   ├── PaintingStatus.java              # 绘画状态枚举
│   ├── PaintingProvider.java            # 绘画Provider接口
│   └── provider/                        # 绘画Provider实现
│       ├── DallE3Provider.java          # DALL·E-3 Provider
│       ├── MidJourneyProvider.java      # MidJourney Provider
│       └── StableDiffusionProvider.java # Stable Diffusion Provider
├── platform/            # 外部平台集成
│   ├── FastGptService.java              # FastGPT服务
│   ├── CozeService.java                 # Coze服务
│   └── DifyClientService.java           # DIFY客户端服务
├── mcp/                 # MCP 工具链与集成
│   ├── McpToolRegistry.java             # MCP工具注册表
│   ├── McpTool.java                     # MCP工具接口
│   ├── McpIntegrationService.java       # MCP集成服务
│   └── tools/                           # MCP工具实现
│       ├── ProjectScaffoldTool.java     # 项目脚手架工具
│       ├── DataTransformTool.java       # 数据转换工具
│       ├── ApiCallTool.java             # API调用工具
│       ├── AlgorithmComputeTool.java    # 算法计算工具
│       ├── FileParseTool.java           # 文件解析工具
│       └── HttpFetchTool.java           # HTTP获取工具
├── queue/               # 任务队列服务
│   └── TaskQueueService.java            # 任务队列服务（优先级队列、任务状态管理）
├── security/            # 安全管理器
│   ├── AiSecurityManager.java           # 安全管理器
│   ├── AiContentFilterService.java      # 内容过滤服务
│   └── AiAccessControlService.java      # 访问控制服务
├── monitor/             # 监控指标与度量
│   ├── AiMonitorService.java            # 监控服务
│   ├── BaseMetrics.java                 # 基础指标
│   ├── SystemMetrics.java               # 系统指标
│   ├── ProviderMetrics.java             # Provider指标
│   ├── ModelMetrics.java                # 模型指标
│   └── UserMetrics.java                 # 用户指标
├── websocket/           # WebSocket 处理器
│   ├── ChatWebSocketConfig.java         # WebSocket配置
│   └── ChatWebSocketHandler.java        # WebSocket处理器
├── error/               # 全局异常处理
│   └── AiErrorHandler.java              # AI异常处理器
└── model/               # 通用模型
    └── ApiResult.java                   # API结果模型

已完成工作

1. 模块结构

• ✅ 创建了完整的模块目录结构
• ✅ 创建了 pom.xml 配置文件
• ✅ 配置了模块依赖关系（ruoyi-common-*、ruoyi-knowledge等）

2. 自动配置

• ✅ 创建了 AiAutoConfiguration 自动配置类
• ✅ 配置了组件扫描
• ✅ 支持通过 ruoyi.ai.enabled 配置启用/禁用模块

3. Provider 管理与编排 ✅

• ✅ 统一接口：AiProviderManager 管理所有模型提供商，支持热切换
• ✅ 智能路由：AiOrchestrationEngine 支持最快响应、最佳质量、成本最优、负载均衡等策略
• ✅ 自动降级：错误率>30%或响应超时自动熔断与故障转移
• ✅ 多模型接入：统一调度 OpenAI、Azure、ChatGLM、通义千问、智谱等主流模型
• ✅ Provider配置管理：支持数据库配置和动态更新
• ✅ Provider配置可视化界面（管理端）：CRUD管理、启用/禁用、导出功能
• ✅ Provider配置历史管理：自动记录配置变更历史，支持查询、导出

4. 聊天与流式交互 ✅

• ✅ 同步/异步聊天接口
• ✅ SSE 流式推送
• ✅ WebSocket 实时通道 (/ws/ai/chat)
• ✅ 聊天历史管理：自动保存聊天记录到Redis和数据库，支持历史查询、清除和会话统计
• ✅ 聊天记录持久化：Redis + 数据库双重存储
• ✅ 聊天记录管理：查询、导出、批量删除
• ✅ 批量聊天支持

5. AI 辅助编码 ✅

• ✅ 代码分析：提供代码审查与重构建议
• ✅ 脚手架生成：自动生成项目结构与配置

6. Simple AI & RAG ✅

• ✅ 知识库问答：基于知识库的精准问答
• ✅ 向量检索：支持多模型向量相似度搜索
• ✅ 知识库统计

7. AI 创作与多模态 ✅

• ✅ 绘画调度：统一管理 DALL·E-3、MidJourney、Stable Diffusion 任务
• ✅ 绘画历史管理：数据库存储、CRUD管理、查询、导出功能
• ✅ 绘画参数模板：数据库存储、CRUD管理、公开/私有模板、用户模板管理
• ✅ 绘画作品收藏：数据库存储、CRUD管理、收藏/取消收藏、收藏列表查询
• ✅ 智能 PPT：文本生成 PPTX，支持导出图片序列
• ✅ 多模态：文件解析（PDF/Word）、OCR识别、图像理解（部分占位）

8. 平台集成 ✅

• ✅ FastGPT：深度对接 FastGPT 平台
• ✅ Coze：深度对接 Coze 平台（SSE流式）
• ✅ DIFY：深度对接 DIFY 平台

9. MCP 生态 ✅

• ✅ 工具注册：McpToolRegistry 支持动态工具加载与调用
• ✅ 工具模板：提供多个内置工具（ProjectScaffold、DataTransform、ApiCall、AlgorithmCompute、FileParse、HttpFetch）

10. 安全与监控 ✅

• ✅ 安全卫士：AiSecurityManager 提供内容过滤、IP黑白名单、速率限制
• ✅ 敏感词库管理：数据库存储、CRUD管理、启用/禁用、导出功能
• ✅ 全链路监控：实时监控队列深度、模型健康度、响应时间与 Token 消耗
• ✅ 使用统计：记录和统计AI使用情况

11. 数据库

• ✅ 创建了 script/sql/ry_ai.sql 文件
• ✅ 添加了 Provider配置表（ai_provider_config）
• ✅ 添加了 Provider配置历史表（ai_provider_config_history）
• ✅ 添加了聊天记录表（ai_chat_record）
• ✅ 添加了使用统计表（ai_usage_stats）
• ✅ 添加了评价记录表（ai_rating_record）
• ✅ 添加了敏感词库表（ai_sensitive_word）
• ✅ 添加了绘画历史记录表（ai_painting_record）
• ✅ 添加了绘画参数模板表（ai_painting_template）
• ✅ 添加了绘画作品收藏表（ai_painting_favorite）
• ✅ 添加了用户配额管理表（ai_user_quota）

12. 文档

• ✅ 创建了模块 README.md 文件

数据库表结构说明

1. AI Provider配置表 (ai_provider_config)

• 功能: 存储AI模型提供商的配置信息
• 关键字段: provider_name, provider_type, enabled, priority, weight, max_concurrency, timeout_seconds, max_retries, api_config, model_config
• 索引: uk_provider_name (唯一), idx_provider_type, idx_enabled, idx_priority
• 状态说明:
  • enabled: 0=禁用, 1=启用
• 配置说明:
  • priority: 优先级（数字越小优先级越高）
  • weight: 权重（用于负载均衡）
  • max_concurrency: 最大并发数
  • timeout_seconds: 超时时间（秒）
  • max_retries: 最大重试次数
  • api_config: API配置（JSON格式，包含apiKey、baseUrl等）
  • model_config: 模型配置（JSON格式，包含defaultModel、supportedModels等）

2. AI Provider配置历史表 (ai_provider_config_history)

• 功能: 记录Provider配置的变更历史
• 关键字段: config_id, provider_name, config_data, operation_type, operation_time, operation_by
• 索引: idx_config_id, idx_provider_name, idx_operation_time
• 操作类型说明:
  • CREATE: 创建配置
  • UPDATE: 更新配置
  • DELETE: 删除配置

3. AI聊天记录表 (ai_chat_record)

• 功能: 存储AI聊天记录
• 关键字段: session_id, user_id, provider_name, model_name, message_type, content, tokens_used, cost, response_time, is_stream
• 索引: idx_session_id, idx_user_id, idx_provider_name, idx_create_time
• 消息类型说明:
  • USER: 用户消息
  • ASSISTANT: AI助手消息
• 状态说明:
  • is_stream: 0=非流式, 1=流式响应

4. AI使用统计表 (ai_usage_stats)

• 功能: 按用户、Provider、模型、日期统计AI使用情况
• 关键字段: user_id, provider_name, model_name, stat_date, request_count, success_count, error_count, total_tokens, total_cost, avg_response_time
• 索引: uk_user_provider_date (唯一), idx_provider_name, idx_stat_date
• 统计说明:
  • request_count: 请求次数
  • success_count: 成功次数
  • error_count: 错误次数
  • total_tokens: 总Token数
  • total_cost: 总成本
  • avg_response_time: 平均响应时间（毫秒）

5. AI评价记录表 (ai_rating_record)

• 功能: 记录用户对AI回复的评价
• 关键字段: message_id, user_id, provider_name, rating, feedback, dimension, anonymous
• 索引: uk_message_user (唯一), idx_provider_name, idx_rating, idx_create_time
• 评价说明:
  • rating: 评分（1-5）
  • dimension: 评价维度（可选）
  • anonymous: 0=非匿名, 1=匿名

功能清单

已实现功能 ✅

1. Provider 管理与编排

• ✅ Provider配置管理（数据库配置、动态更新）
• ✅ Provider注册与发现
• ✅ 智能路由策略（最快响应、最佳质量、成本最优、负载均衡）
• ✅ 自动降级与熔断
• ✅ Provider健康检查
• ✅ Provider统计与监控

2. 聊天与流式交互

• ✅ 同步聊天接口
• ✅ 异步聊天接口
• ✅ SSE流式推送
• ✅ WebSocket实时通道
• ✅ 聊天历史管理（Redis存储）
• ✅ 会话统计
• ✅ 批量聊天支持

3. AI 辅助编码

• ✅ 代码分析（代码审查、重构建议）
• ✅ 项目脚手架生成

4. Simple AI & RAG

• ✅ 知识库问答（基于ruoyi-knowledge模块）
• ✅ 向量检索
• ✅ 知识库统计

5. AI 创作与多模态

• ✅ 绘画任务管理（DALL·E-3、MidJourney、Stable Diffusion）
• ✅ 绘画任务状态查询
• ✅ 绘画任务流式进度推送（SSE）
• ✅ 智能PPT生成（文本生成PPTX）
• ✅ PPT导出PNG序列
• ✅ 文件解析（PDF/Word等，基于Apache Tika）
• ✅ 文本分析
• ✅ OCR识别（占位接口，需配置OCR服务）
• ⏳ 图像识别（占位接口）
• ⏳ 图生文（占位接口）

6. 平台集成

• ✅ FastGPT平台集成（知识搜索、工作流运行、上下文管理）
• ✅ Coze平台集成（SSE流式对话）
• ✅ DIFY平台集成（应用列表、创建/更新应用）

7. MCP 生态

• ✅ MCP工具注册与管理
• ✅ 工具调用接口
• ✅ 内置工具（ProjectScaffold、DataTransform、ApiCall、AlgorithmCompute、FileParse、HttpFetch）

8. 安全与监控

• ✅ 内容过滤
• ✅ IP访问控制（黑白名单）
• ✅ 速率限制
• ✅ 全链路监控（队列深度、模型健康度、响应时间、Token消耗）
• ✅ 使用统计（用户、Provider、模型维度）

9. AI评价功能 ✅

• ✅ 评价记录管理（用户评价AI回复）
• ✅ 评价记录查询与导出
• ✅ 评价记录统计（平均评分）
• ✅ 用户端评价接口（提交评价、查询评价）

10. 系统模型管理

• ✅ 模型信息查询
• ✅ 模型可用性检查

待实现功能 ⏳

1. 聊天功能增强

• ✅ 聊天记录持久化到数据库（Redis + 数据库双重存储）
• ✅ 聊天记录导出（Excel格式）
• ✅ 聊天记录搜索（支持多条件查询）
• ✅ 聊天记录批量删除
• ✅ 聊天记录归档（删除指定日期之前的记录）
• 多轮对话上下文优化

2. Provider管理增强

• ✅ Provider配置可视化界面（管理端）
• ✅ Provider配置导入导出（Excel导出）
• ✅ Provider配置版本管理增强（配置历史记录、查询、导出）
• Provider性能分析报告
• Provider成本分析
• Provider自动故障恢复

3. 监控与统计增强

• ✅ 使用统计报表导出（Excel格式）
• 使用趋势分析（图表）
• 成本分析报表
• 性能分析报表
• 异常告警（邮件、短信、Webhook等）
• 实时大屏展示

4. 安全功能增强

• ✅ 敏感词库管理（可配置）：数据库存储、CRUD管理、启用/禁用、导出功能
• ✅ 用户配额管理：数据库存储、CRUD管理、配额重置、使用量统计
• 内容审核规则配置
• 企业级权限控制
• 审计日志

5. 多模态功能完善

• OCR识别完整实现（集成OCR服务）
• 图像识别完整实现
• 图生文完整实现
• 视频理解（占位）
• 音频处理（占位）

6. 绘画功能增强

• ✅ 绘画历史管理：数据库存储、CRUD管理、查询、导出功能
• ✅ 绘画参数模板：数据库存储、CRUD管理、公开/私有模板、用户模板管理
• ✅ 绘画作品收藏：数据库存储、CRUD管理、收藏/取消收藏、收藏列表查询
• ✅ 绘画作品分享：分享码生成、取消分享、通过分享码查看作品（无需登录）
• 批量绘画任务

7. PPT功能增强

• PPT主题模板管理
• PPT样式自定义
• PPT动画支持
• PPT导出PDF
• PPT在线预览

8. MCP工具生态扩展

• 工具市场/插件系统
• 工具版本管理
• 工具权限控制
• 工具性能监控
• 自定义工具开发框架

9. 代码助手增强

• 代码生成（根据需求生成代码）
• 代码优化建议
• 代码测试用例生成
• 代码文档生成
• 代码安全扫描集成

10. RAG功能增强

• 多知识库联合检索
• 检索结果排序优化
• 检索结果来源标注
• RAG效果评估
• 知识库更新通知

11. 平台集成扩展

• 更多平台集成（如：LangChain、LlamaIndex等）
• 平台配置管理界面
• 平台使用统计

12. 其他功能

• 用户评价反馈系统完善
• 客服机器人集成
• 多语言支持
• API限流策略细化
• 任务队列持久化（当前仅内存）
• 分布式任务调度

API接口详细说明

管理端接口

1. AI聊天记录管理 (/ai/chat/record)

• GET /ai/chat/record/list - 查询AI聊天记录列表（分页、多条件搜索）
• GET /ai/chat/record/{id} - 获取AI聊天记录详情
• DELETE /ai/chat/record/{ids} - 批量删除AI聊天记录
• POST /ai/chat/record/export - 导出AI聊天记录到Excel
• POST /ai/chat/record/archive - 归档聊天记录（删除指定日期之前的记录）

2. AI使用统计管理 (/ai/usage/stats)

• GET /ai/usage/stats/list - 查询AI使用统计列表（分页、多条件搜索）
• GET /ai/usage/stats/{id} - 获取AI使用统计详情
• POST /ai/usage/stats/export - 导出AI使用统计到Excel
• GET /ai/usage/stats/summary - 获取汇总统计
• GET /ai/usage/stats/user/{userId} - 获取用户统计
• GET /ai/usage/stats/provider/{providerName} - 获取Provider统计
• GET /ai/usage/stats/trend - 获取趋势数据

3. Provider管理 (/ai/provider)

• GET /ai/provider/list - 列出所有Provider
• GET /ai/provider/models - 列出所有模型
• GET /ai/provider/default - 获取默认Provider
• POST /ai/provider/setDefault - 设置默认Provider
• GET /ai/provider/stats/system - 系统统计
• GET /ai/provider/stats/providers - Provider统计
• POST /ai/provider/stats/reset - 重置统计

3.1. Provider配置管理 (/ai/provider/config)

• GET /ai/provider/config/list - 查询Provider配置列表（分页、多条件搜索）
• GET /ai/provider/config/{id} - 获取Provider配置详情
• POST /ai/provider/config - 新增Provider配置
• PUT /ai/provider/config - 修改Provider配置
• DELETE /ai/provider/config/{ids} - 批量删除Provider配置
• POST /ai/provider/config/export - 导出Provider配置到Excel
• PUT /ai/provider/config/changeEnabled - 启用/禁用Provider配置
• GET /ai/provider/config/name/{providerName} - 根据Provider名称查询配置

3.2. Provider配置历史管理 (/ai/provider/config/history)

• GET /ai/provider/config/history/list - 查询Provider配置历史列表（分页、多条件搜索）
• GET /ai/provider/config/history/{id} - 获取Provider配置历史详情
• GET /ai/provider/config/history/config/{configId} - 根据配置ID查询历史记录列表
• DELETE /ai/provider/config/history/{ids} - 批量删除Provider配置历史
• POST /ai/provider/config/history/export - 导出Provider配置历史到Excel

4. 系统模型管理 (/system/model)

• GET /system/model/modelList - 获取模型列表（用于前端下拉选择）
• GET /system/model/list - 根据分类获取模型列表

5. AI评价记录管理 (/ai/rating/record)

• GET /ai/rating/record/list - 查询AI评价记录列表（分页、多条件搜索）
• GET /ai/rating/record/{id} - 获取AI评价记录详情
• DELETE /ai/rating/record/{ids} - 批量删除AI评价记录
• POST /ai/rating/record/export - 导出AI评价记录到Excel
• GET /ai/rating/record/average/{providerName} - 获取指定Provider的平均评分

6. AI敏感词管理 (/ai/sensitive/word)

• GET /ai/sensitive/word/list - 查询AI敏感词列表（分页、多条件搜索）
• GET /ai/sensitive/word/{id} - 获取AI敏感词详情
• POST /ai/sensitive/word - 新增AI敏感词
• PUT /ai/sensitive/word - 修改AI敏感词
• DELETE /ai/sensitive/word/{ids} - 批量删除AI敏感词
• POST /ai/sensitive/word/export - 导出AI敏感词到Excel
• PUT /ai/sensitive/word/changeEnabled - 启用/禁用敏感词

7. AI绘画历史记录管理 (/ai/painting/record)

• GET /ai/painting/record/list - 查询AI绘画历史记录列表（分页、多条件搜索）
• GET /ai/painting/record/{id} - 获取AI绘画历史记录详情
• GET /ai/painting/record/task/{taskId} - 根据任务ID获取记录
• DELETE /ai/painting/record/{ids} - 批量删除AI绘画历史记录
• POST /ai/painting/record/export - 导出AI绘画历史记录到Excel
• POST /ai/painting/record/{id}/share - 生成分享码
• DELETE /ai/painting/record/{id}/share - 取消分享

8. AI绘画参数模板管理 (/ai/painting/template)

• GET /ai/painting/template/list - 查询AI绘画参数模板列表（分页、多条件搜索）
• GET /ai/painting/template/{id} - 获取AI绘画参数模板详情
• POST /ai/painting/template - 新增AI绘画参数模板
• PUT /ai/painting/template - 修改AI绘画参数模板
• DELETE /ai/painting/template/{ids} - 批量删除AI绘画参数模板
• POST /ai/painting/template/export - 导出AI绘画参数模板到Excel

9. AI绘画作品收藏管理 (/ai/painting/favorite)

• GET /ai/painting/favorite/list - 查询AI绘画作品收藏列表（分页、多条件搜索）
• GET /ai/painting/favorite/{id} - 获取AI绘画作品收藏详情
• DELETE /ai/painting/favorite/{ids} - 批量删除AI绘画作品收藏
• POST /ai/painting/favorite/export - 导出AI绘画作品收藏到Excel

10. AI用户配额管理 (/ai/user/quota)

• GET /ai/user/quota/list - 查询AI用户配额列表（分页、多条件搜索）
• GET /ai/user/quota/{id} - 获取AI用户配额详情
• GET /ai/user/quota/user/{userId} - 根据用户ID获取配额信息
• POST /ai/user/quota - 新增AI用户配额
• PUT /ai/user/quota - 修改AI用户配额
• DELETE /ai/user/quota/{ids} - 批量删除AI用户配额
• POST /ai/user/quota/reset/{userId} - 重置用户配额（按日/按月）
• POST /ai/user/quota/export - 导出AI用户配额到Excel

用户端接口

1. 聊天接口 (/ai/chat)

同步聊天

• POST /ai/chat/sync - 同步聊天（返回完整响应）
  • 请求体：AiChatRequest（包含model、messages、sessionId等）
  • 响应：AiChatResponse（包含content、tokensUsed、cost等）

异步聊天

• POST /ai/chat/async - 异步聊天（返回任务ID）
  • 请求体：AiChatRequest
  • 响应：CompletableFuture<AiChatResponse>

流式聊天

• POST /ai/chat/stream - SSE流式聊天
  • 请求体：AiChatRequest（stream=true）
  • 响应：SSE流（事件类型：chunk、done、error）
• POST /ai/chat/stream-chunks - 流式聊天（分块返回）
  • 请求体：AiChatRequest
  • 响应：分块响应列表

批量聊天

• POST /ai/chat/batch - 批量聊天请求
  • 请求体：批量AiChatRequest列表
  • 响应：批量AiChatResponse列表

聊天历史

• GET /ai/chat/history/{sessionId} - 获取聊天历史
  • 路径参数：sessionId（会话ID）
  • 查询参数：limit（限制数量，可选）
  • 响应：聊天记录列表
• DELETE /ai/chat/history/{sessionId} - 清除聊天历史
  • 路径参数：sessionId（会话ID）

会话统计

• GET /ai/chat/stats/{sessionId} - 获取会话统计
  • 路径参数：sessionId（会话ID）
  • 响应：会话统计数据（消息数、Token数、成本等）

2. AI代码助手接口 (/ai/assistant)

• POST /ai/assistant/analyze - 代码分析
  • 请求参数：code（代码内容）、model（模型名称，可选）
  • 响应：代码分析结果（审查建议、重构建议等）
• POST /ai/assistant/scaffold - 生成项目脚手架
  • 请求参数：appType（应用类型）、options（选项JSON）
  • 响应：项目结构（文件列表、内容等）

3. Simple AI接口 (/ai)

• POST /ai/ask - 知识库问答
  • 查询参数：knowledgeId（知识库ID）、question（问题）
  • 响应：问答结果
• POST /ai/search - 向量搜索
  • 查询参数：knowledgeId（知识库ID）、queryText（查询文本）、topK（返回数量，可选）
  • 响应：搜索结果列表
• GET /ai/stats/{knowledgeId} - 知识库统计
  • 路径参数：knowledgeId（知识库ID）
  • 响应：知识库统计数据
• GET /ai/model/check/{modelName} - 检查模型可用性
  • 路径参数：modelName（模型名称）
  • 响应：模型可用性状态
• GET /ai/models - 获取可用模型列表
  • 响应：可用模型列表
• GET /ai/health - 健康检查
  • 响应：健康状态

4. 绘画接口 (/ai/painting)

• POST /ai/painting/task - 创建绘画任务
  • 请求体：{"engine": "DALL_E_3", "prompt": "描述", "params": {...}}
  • 响应：{"taskId": "..."}
• GET /ai/painting/status/{taskId} - 查询任务状态
  • 路径参数：taskId（任务ID）
  • 响应：任务状态（pending、processing、completed、failed）
• GET /ai/painting/stream/{taskId} - SSE流式获取任务进度
  • 路径参数：taskId（任务ID）
  • 响应：SSE流（任务状态更新）

5. AI绘画参数模板 (/ai/painting/template)

• GET /ai/painting/template/list/{engineType} - 查询可用的模板列表（公开模板 + 用户私有模板）
• GET /ai/painting/template/{id} - 获取模板详情
• POST /ai/painting/template - 新增用户私有模板
• PUT /ai/painting/template - 修改用户私有模板
• DELETE /ai/painting/template/{id} - 删除用户私有模板

6. AI绘画作品收藏 (/ai/painting/favorite)

• GET /ai/painting/favorite/list - 查询当前用户的收藏列表
• POST /ai/painting/favorite - 收藏绘画作品
• DELETE /ai/painting/favorite/{paintingRecordId} - 取消收藏
• GET /ai/painting/favorite/check/{paintingRecordId} - 检查是否已收藏

6.1. AI绘画作品分享 (/app/ai/painting/record)

• POST /app/ai/painting/record/{id}/share - 生成分享码
• DELETE /app/ai/painting/record/{id}/share - 取消分享
• GET /app/ai/painting/record/share/{shareCode} - 根据分享码查看作品（无需登录）

7. DALL·E-3接口 (/dall3)

• POST /dall3 - 文生图
  • 请求体：{"prompt": "描述", "size": "1024x1024"}
  • 响应：图片URL或Base64
• POST /dall3/edit - 图片编辑（image+mask）
  • 请求体：{"prompt": "描述", "image": "base64", "mask": "base64", "size": "1024x1024"}
  • 响应：编辑后的图片URL或Base64
• POST /dall3/variations - 图片变体
  • 请求体：{"image": "base64", "size": "1024x1024"}
  • 响应：变体图片URL或Base64

8. 智能PPT接口 (/ppt)

• POST /ppt/generate - 生成PPTX文件
  • 查询参数：content（内容，按行分隔，空行分隔不同页）
  • 响应：PPTX文件（下载）
• POST /ppt/export/pngs - 导出PNG序列
  • 查询参数：content（内容）
  • 响应：PNG图片Base64列表

9. 多模态接口 (/multimodal)

• POST /multimodal/extract - 文件解析（PDF/Word等）
  • 请求：multipart/form-data，字段：file
  • 响应：解析后的文本内容
• POST /multimodal/ocr - OCR识别
  • 请求：multipart/form-data，字段：file
  • 响应：OCR识别结果（需配置OCR服务）
• POST /multimodal/analyze/text - 文本分析
  • 请求体：{"text": "文本内容"}
  • 响应：分析结果（title、summary、keywords等）
• POST /multimodal/analyze/image - 图像识别（占位）
  • 请求：multipart/form-data，字段：file
  • 响应：识别结果（占位接口）
• POST /multimodal/caption - 图生文（占位）
  • 请求：multipart/form-data，字段：file
  • 响应：图片描述（占位接口）

10. 平台集成接口

FastGPT (/ai/fastgpt)

• POST /ai/fastgpt/knowledge/search - 知识搜索
  • 请求体：{"query": "查询内容"}
  • 响应：搜索结果
• POST /ai/fastgpt/workflow/run - 运行工作流
  • 请求体：{"workflowId": "...", "inputs": {...}}
  • 响应：工作流执行结果
• GET /ai/fastgpt/context/{sessionId} - 获取上下文
  • 路径参数：sessionId（会话ID）
  • 响应：上下文信息

Coze (/ai/coze)

• POST /ai/coze/stream - SSE流式对话
  • 请求体：{"botId": "...", "message": "消息内容"}
  • 响应：SSE流

DIFY (/ai/dify)

• GET /ai/dify/apps - 获取应用列表
  • 响应：应用列表
• POST /ai/dify/apps - 创建/更新应用
  • 请求体：应用配置
  • 响应：应用信息

11. MCP工具接口 (/ai/mcp)

• GET /ai/mcp/tools - 获取工具列表
  • 响应：可用工具列表
• POST /ai/mcp/invoke/{name} - 调用工具
  • 路径参数：name（工具名称）
  • 请求体：工具参数（JSON）
  • 响应：工具执行结果

12. 队列指标接口 (/ai/queue)

• GET /ai/queue/metrics - 获取队列指标
  • 响应：队列指标（队列深度、处理速率等）

13. AI评价接口 (/ai/rating)

• POST /ai/rating/submit - 提交评价（用户对AI回复进行评价）
  • 请求体：AiRatingRecordBo（包含messageId、rating、feedback等）
• GET /ai/rating/{messageId} - 查询评价记录（根据消息ID查询当前用户的评价记录）

13. AI用户配额 (/ai/user/quota)

• GET /ai/user/quota - 查询当前用户的配额信息

WebSocket实时通道

聊天WebSocket

• 端点: ws://localhost:8080/ws/ai/chat
• 协议: JSON格式，支持实时双向对话
• 消息格式: AiChatRequest（JSON）
• 响应格式: AiChatResponse（JSON）

模块依赖关系

ruoyi-ai (AI模块)
├── 依赖: ruoyi-common-core (通用核心工具)
├── 依赖: ruoyi-common-web (Web通用组件)
├── 依赖: ruoyi-common-redis (Redis缓存)
├── 依赖: ruoyi-common-security (安全组件)
├── 依赖: ruoyi-common-log (日志组件)
├── 依赖: ruoyi-common-mybatis (MyBatis组件)
├── 依赖: ruoyi-common-doc (文档组件)
├── 依赖: ruoyi-knowledge (知识库模块，RAG增强)
└── 外部依赖:
    ├── okhttp (HTTP客户端)
    ├── okhttp-sse (SSE支持)
    ├── jackson (JSON解析)
    ├── spring-boot-starter-websocket (WebSocket支持)
    ├── poi-ooxml (PPT生成)
    └── tika-core (文件解析)

技术栈与开发规范

技术栈

• 框架: Spring Boot 3.x
• ORM: MyBatis-Plus（部分功能）
• 数据库: MySQL 8.0+
• 缓存: Redis
• 认证: Sa-Token（通过ruoyi-common-security）
• API文档: Swagger/OpenAPI 3.0
• 构建工具: Maven
• HTTP客户端: OkHttp
• JSON解析: Jackson
• WebSocket: Spring WebSocket

开发规范

包结构规范

• config - 配置类（自动配置类、属性配置类）
• controller - 控制器层（REST API）
  • controller/admin - 管理端接口（需要权限控制）
  • controller/app - 用户端接口
• domain - 数据传输对象（包含 dto 和 enums 子包）
• provider - Provider实现（模型提供商实现）
• service - 服务接口和实现
• orchestration - 编排引擎
• painting - 绘画相关（任务模型、Provider等）
• platform - 外部平台集成
• mcp - MCP工具链
• queue - 任务队列
• security - 安全管理
• monitor - 监控指标
• websocket - WebSocket处理器
• error - 异常处理

代码规范

• 统一使用 Lombok 简化代码
• 统一异常处理，使用 ServiceException 抛出业务异常
• 统一返回格式，使用 R<T> 封装返回结果
• 统一日志记录，使用 @Log 注解记录操作日志
• 统一权限控制，管理端接口使用 @SaCheckPermission 注解
• Provider实现需继承 AbstractAiProvider 或实现 AiProvider 接口
• 配置类使用 @ConfigurationProperties 绑定配置属性

数据库设计规范

• 表名使用 ai_ 前缀
• 字段命名使用下划线命名法（snake_case）
• 必须包含 create_by, create_time, update_by, update_time 字段
• 删除标记使用逻辑删除（deleted 字段，如需要）
• 状态字段统一使用 status 或 enabled，0表示禁用/异常，1表示启用/正常
• JSON字段使用 json 类型存储配置信息

API设计规范

• RESTful 风格设计
• 接口路径：
  • 管理端接口：/ai/{module}/{resource} 或 /system/{resource}
  • 用户端接口：/ai/{module}/{resource}
• 使用 HTTP 标准方法：GET（查询）、POST（新增/操作）、PUT（修改）、DELETE（删除）
• 统一使用 JSON 格式进行数据交互
• 使用 Swagger 注解完善接口文档
• 管理端接口使用 @SaCheckPermission 进行权限控制
• 流式接口使用 SSE（Server-Sent Events）或 WebSocket

模块集成说明

知识库模块集成 (ruoyi-knowledge)

• 集成方式: Maven依赖
• 核心功能:
  • RAG增强（知识库问答）
  • 向量检索
  • 知识库管理
• 配置要求: 在 application.yml 中配置知识库相关配置

Redis集成

• 用途:
  • 聊天历史存储
  • 任务状态缓存
  • 会话管理
  • 缓存热点数据
• 配置要求: 在 application.yml 中配置Redis连接信息

外部服务集成

• OpenAI: 通过API Key访问
• Azure OpenAI: 通过Endpoint和API Key访问
• 通义千问: 通过API Key访问
• 智谱AI: 通过API Key访问
• FastGPT/Coze/DIFY: 通过平台API访问
• OCR服务: 需配置OCR服务地址（可选）

开发指南

新增Provider开发步骤

1. 创建Provider配置类

   • 在 config 包下创建配置类（如 XxxProviderConfig.java）
   • 使用 @ConfigurationProperties 绑定配置

2. 实现Provider接口

   • 实现 AiProvider 接口或继承 AbstractAiProvider
   • 实现核心方法：chat()、chatStream()等

3. 注册Provider

   • 在 AiProviderRegistrar 中注册Provider
   • 在 AiProviderType 枚举中添加新的Provider类型

4. 配置数据库

   • 在 ai_provider_config 表中添加Provider配置记录
   • 配置API密钥等信息

5. 测试验证

   • 编写单元测试
   • 使用Swagger UI测试接口
   • 验证Provider功能

新增MCP工具开发步骤

1. 实现工具接口

   • 实现 McpTool 接口
   • 实现 execute() 方法

2. 注册工具

   • 在 McpToolRegistry 中注册工具（可通过Spring Bean自动注册）
   • 工具会自动出现在工具列表中

3. 测试验证

   • 使用 /ai/mcp/tools 接口查看工具列表
   • 使用 /ai/mcp/invoke/{name} 接口测试工具调用

新增功能开发步骤

1. 数据库设计（如需要）

   • 在 script/sql/ry_ai.sql 中设计表结构
   • 确保字段命名规范，包含必要的索引

2. 创建DTO/实体类（如需要）

   • 在 domain/dto 包下创建DTO类
   • 创建对应的请求/响应对象

3. 创建Service

   • 在 service 包下创建Service接口
   • 在 service/impl 包下创建Service实现类（如需要）

4. 创建Controller

   • 管理端接口：在 controller/admin 包下创建Controller
   • 用户端接口：在 controller/app 包下创建Controller
   • 添加Swagger注解完善接口文档
   • 管理端接口添加权限控制注解（@SaCheckPermission）

5. 测试验证

   • 编写单元测试（可选）
   • 使用Swagger UI测试接口
   • 验证业务逻辑正确性

后续功能完善计划

短期计划（1-2个月）

1. 聊天功能增强 ✅（大部分已完成）

   • ✅ 聊天记录持久化到数据库
   • ✅ 聊天记录导出功能（Excel）
   • ✅ 聊天记录搜索功能
   • ✅ 聊天记录批量删除功能

2. 监控与统计增强

   • 使用统计报表导出
   • 使用趋势分析图表
   • 异常告警功能

3. 多模态功能完善

   • OCR识别完整实现
   • 图像识别完整实现
   • 图生文完整实现

4. 安全功能增强

   • 敏感词库管理
   • 用户配额管理
   • 审计日志

中期计划（3-6个月）

1. Provider管理增强

   • Provider配置可视化界面
   • Provider性能分析报告
   • Provider成本分析

2. 绘画功能增强

   • 绘画历史管理
   • 绘画作品收藏
   • 批量绘画任务

3. PPT功能增强

   • PPT主题模板管理
   • PPT样式自定义
   • PPT导出PDF

4. 代码助手增强

   • 代码生成功能
   • 代码优化建议
   • 代码测试用例生成

5. RAG功能增强

   • 多知识库联合检索
   • 检索结果排序优化
   • RAG效果评估

长期计划（6个月以上）

1. MCP工具生态扩展

   • 工具市场/插件系统
   • 工具版本管理
   • 自定义工具开发框架

2. 平台集成扩展

   • 更多平台集成
   • 平台配置管理界面

3. 系统优化

   • 分布式任务调度
   • 任务队列持久化
   • 性能优化与扩展

4. 企业级功能

   • 多租户支持
   • 企业级权限控制
   • 数据隔离

注意事项

1. 密钥安全：生产环境务必通过环境变量注入 API Key，不要将密钥写入配置文件或代码中
2. 流式代理：Nginx/Gateway 需配置 proxy_buffering off 以支持 SSE
3. 依赖服务：Redis 必须可用，用于存储任务状态与缓存
4. 性能优化：建议对热点数据使用Redis缓存
5. 错误处理：模块提供自动降级和熔断机制，但建议监控错误率
6. 并发控制：Provider支持最大并发数配置，合理设置以避免资源耗尽
7. 成本控制：建议设置使用配额和成本预警，避免意外高额费用
8. 内容安全：启用内容过滤和安全检查，防止不当内容生成
9. 数据隐私：注意用户数据隐私保护，敏感信息加密存储
10. API限流：合理配置API限流策略，防止API滥用
11. 监控告警：建议配置监控告警，及时发现和解决问题
12. 版本兼容：升级Provider SDK时注意API兼容性
13. 文档更新：新增功能时及时更新API文档和README
14. 测试覆盖：关键功能建议编写单元测试和集成测试
15. 日志规范：关键操作记录日志，便于问题排查