# 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. **日志规范**：关键操作记录日志，便于问题排查
