qihang-ecom-erp-open/docs/ai-agent-analysis.md

## 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 服务调用失败时需更完善的降级策略