175 lines
6.2 KiB
Markdown
175 lines
6.2 KiB
Markdown
## api/ai-agent 目录代码结构分析
|
||
|
||
### 一、模块概述
|
||
|
||
ai-agent 是一个基于 **LangChain4J** 的 AI 智能助手模块，用于实现对话式电商管理功能。
|
||
|
||
**核心技术栈：**
|
||
- LangChain4J (AI 框架)
|
||
- Ollama (本地大模型)
|
||
- SSE (Server-Sent Events) 实时通信
|
||
- Spring Cloud 微服务
|
||
|
||
---
|
||
|
||
### 二、目录结构
|
||
|
||
```
|
||
api/ai-agent/
|
||
├── src/main/java/cn/qihangerp/erp/
|
||
│ ├── AiAgent.java # 启动类
|
||
│ ├── controller/
|
||
│ │ ├── SseController.java # SSE实时通信控制器 ⭐核心
|
||
│ │ ├── HomeController.java # 主页控制器
|
||
│ │ ├── OllamaController.java # Ollama模型控制器
|
||
│ │ └── AiUserRoleController.java # AI用户角色控制器
|
||
│ ├── service/
|
||
│ │ ├── OrderService.java # 订单服务 (模拟数据)
|
||
│ │ └── OrderToolService.java # AI订单工具 ⭐核心
|
||
│ ├── serviceImpl/
|
||
│ │ ├── AiService.java # AI服务核心逻辑 ⭐⭐核心
|
||
│ │ ├── ConversationHistoryManager.java # 对话历史管理
|
||
│ │ ├── SessionManager.java # 会话管理
|
||
│ │ └── InventorySalesAnalyzer.java # 库存销售分析（本地规则报告）
|
||
│ ├── feign/
|
||
│ │ ├── OpenApiService.java # 内部API调用
|
||
│ │ └── EchoService.java
|
||
│ └── config/
|
||
│ └── MybatisPlusConfig.java
|
||
└── src/main/resources/
|
||
├── application.yml # 配置文件
|
||
└── page-rules.md # 页面跳转规则
|
||
```
|
||
|
||
---
|
||
|
||
### 三、核心业务逻辑
|
||
|
||
#### 1. SseController (SseController.java:30-240)
|
||
|
||
**职责：** 处理前端 SSE 实时通信
|
||
|
||
```
|
||
客户端连接 → 鉴权 → 创建会话 → 心跳保活 → AI处理 → 返回响应
|
||
```
|
||
|
||
**关键接口：**
|
||
- `GET /sse/connect` - 建立 SSE 连接
|
||
- `GET /sse/send` - 发送消息并获取 AI 回复
|
||
- `GET /sse/disconnect` - 断开连接
|
||
- `GET /sse/history` - 获取对话历史
|
||
- `GET /sse/status` - 获取服务状态
|
||
|
||
---
|
||
|
||
#### 2. AiService (AiService.java:24-302)
|
||
|
||
**职责：** AI 消息处理核心服务
|
||
|
||
```
|
||
用户消息 → 页面规则匹配 → 上下文增强 → 模型调用 → 返回响应
|
||
```
|
||
|
||
**核心流程：**
|
||
|
||
1. **页面规则匹配** (`checkPageRules`)
|
||
- 从 `page-rules.md` 加载规则
|
||
- 匹配关键词 → 返回导航指令 JSON
|
||
|
||
2. **上下文增强**
|
||
- 将"今天"替换为实际日期
|
||
- 限制历史上下文最长 2000 字符
|
||
|
||
3. **模型选择**
|
||
- 仅支持 **Ollama 本地模型**（`deepseek` 前缀会提示已移除云端能力）
|
||
|
||
4. **Tool 集成**
|
||
- 绑定 `OrderToolService` 提供订单查询能力
|
||
|
||
---
|
||
|
||
#### 3. OrderToolService (OrderToolService.java:11-115)
|
||
|
||
**职责：** AI 可调用的订单查询工具
|
||
|
||
| 方法 | 功能 |
|
||
|------|------|
|
||
| `getOrderById` | 按订单号查询 |
|
||
| `getAllOrders` | 获取所有订单 |
|
||
| `getOrdersByStatus` | 按状态查询 |
|
||
| `getPendingOrders` | 待发货订单 |
|
||
| `getOrdersByDate` | 按日期查询 |
|
||
|
||
使用 `@Tool` 注解声明为 LangChain4J 工具
|
||
|
||
---
|
||
|
||
#### 4. ConversationHistoryManager (ConversationHistoryManager.java:17-145)
|
||
|
||
**职责：** 对话历史持久化管理
|
||
|
||
- 依赖 `IAiConversationHistoryService` 存储到数据库
|
||
- 支持获取历史、获取最近N条、清空历史
|
||
|
||
---
|
||
|
||
#### 5. SessionManager (SessionManager.java:16-101)
|
||
|
||
**职责：** 用户会话管理
|
||
|
||
- 内存缓存 + 数据库持久化
|
||
- `userId ↔ sessionId` 双向映射
|
||
|
||
---
|
||
|
||
#### 6. InventorySalesAnalyzer
|
||
|
||
**职责：** 库存销售分析（独立工具类 / 示例 `main`）
|
||
|
||
- 解析库存和销售 JSON 数据
|
||
- 计算关键指标：日均销量、可售天数、库存状态
|
||
- **本地规则**生成 Markdown 式报告（不调用外部大模型）
|
||
|
||
---
|
||
|
||
### 四、数据流图
|
||
|
||
```
|
||
┌─────────────┐ SSE ┌──────────────────┐
|
||
│ 前端 Vue │ ──────────→ │ SseController │
|
||
└─────────────┘ └────────┬─────────┘
|
||
│
|
||
┌────────────────┼────────────────┐
|
||
▼ ▼ ▼
|
||
┌──────────────┐ ┌─────────────┐ ┌──────────────┐
|
||
│ SessionManager│ │Conversation │ │ AiService │
|
||
│ │ │ HistoryMgr │ │ │
|
||
└──────────────┘ └─────────────┘ └──────┬───────┘
|
||
│
|
||
┌──────────────────┼──────────────────┐
|
||
▼ ▼ ▼
|
||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
│ PageRules │ │OrderToolSvc │ │ LLM Model │
|
||
│ (页面导航) │ │ (订单查询) │ │ (Ollama) │
|
||
└─────────────┘ └──────────────┘ └─────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
### 五、配置说明 (application.yml)
|
||
|
||
```yaml
|
||
server.port: 8084 # AI服务端口
|
||
spring.datasource: MySQL连接配置
|
||
spring.data.redis: Redis连接配置
|
||
# 大模型：本机 Ollama（默认 http://localhost:11434），无云端 API 配置项
|
||
```
|
||
|
||
---
|
||
|
||
### 六、待优化点
|
||
|
||
1. **OrderService.java** - 目前使用模拟数据，需对接真实 ERP 订单数据
|
||
2. **SessionManager** - 内存缓存无持久化，重启丢失
|
||
3. **错误处理** - AI 服务调用失败时需更完善的降级策略
|