# LinkWeChat AI 模块开发文档

## 模块概述

linkwe-ai 是 LinkWeChat 项目中的 AI 助手功能模块，虽然项目描述中标注"该项目没有用到"，但实际上该模块实现了基于阿里云大模型的 AI 对话功能。该模块集成了阿里云通义千问（DashScope）服务，提供了单次对话、多轮对话和流式对话等 AI 交互能力。

## 技术架构

### 核心技术栈
- **Spring Boot 2.6.6**: 基础框架
- **Spring Cloud**: 微服务架构支持
- **MyBatis-Plus**: 数据访问层框架
- **Druid**: 数据库连接池
- **Redis**: 缓存服务
- **Nacos**: 服务注册与配置中心
- **WebFlux**: 响应式编程支持（用于流式响应）
- **Apache Commons Net**: FTP 客户端支持

### AI 服务集成
- **阿里云 DashScope SDK** (版本 2.18.2): 通义千问大模型服务
- **支持的模型**:
  - deepseek-r1: DeepSeek 推理模型
  - qwen-plus: 通义千问增强版
  - qwq-32b: 通义千问 32B 参数模型

## 项目结构

```
linkwe-ai/
├── src/main/java/com/linkwechat/coal/
│   ├── LinkweAiApplication.java         # 应用程序入口
│   ├── config/
│   │   └── Constant.java                # 常量配置类
│   ├── datasource/
│   │   ├── AiDataSourceConfig.java      # AI 数据源配置
│   │   └── QwDataSourceConfig.java      # 企微数据源配置
│   ├── exception/
│   │   └── SystemHandlerException.java  # 系统异常处理
│   ├── filter/
│   │   └── HttpServletRequestWrapperFilter.java # 请求过滤器
│   └── modules/
│       ├── ai/
│       │   ├── controller/
│       │   │   ├── AliAiController.java  # 阿里云 AI 控制器
│       │   │   ├── FileController.java   # 文件处理控制器
│       │   │   └── ZmAiController.java   # 智能AI控制器
│       │   ├── domain/dto/
│       │   │   ├── AliAiTextDto.java     # AI 文本交互 DTO
│       │   │   └── RequestIdDto.java     # 请求 ID DTO
│       │   ├── mapper/
│       │   │   ├── SysUserMapper1.java   # 用户 Mapper1
│       │   │   └── SysUserMapper2.java   # 用户 Mapper2
│       │   ├── service/impl/
│       │   │   └── FtpStorageService.java # FTP 存储服务
│       │   └── utils/
│       │       ├── AliAiUtils.java       # 阿里 AI 工具类
│       │       ├── FileUtils.java        # 文件工具类
│       │       ├── SSEHelper.java        # SSE (Server-Sent Events) 辅助类
│       │       └── WordUtils.java        # Word 文档处理工具
│       └── qw/mapper/
│           └── SysUserMapper1.java      # 企微用户 Mapper
├── src/main/resources/
│   ├── application.properties            # 应用配置
│   └── spy.properties                   # P6Spy 监控配置
├── bin/                                 # 构建输出目录
├── pom.xml                              # Maven 配置文件
└── CLAUDE.md                           # 本文档
```

## 核心功能

### 1. AI 对话功能

#### AliAiController 提供的接口：

1. **单次对话** (`/aliAi/single`)
   - 支持文本输入和 Word 文档内容解析
   - 返回完整的 AI 响应结果
   - 包含思考过程和最终回答

2. **多轮对话** (`/aliAi/multiwheel`)
   - 支持上下文连续对话
   - 通过 Redis 缓存会话历史
   - 维护对话的连贯性

3. **流式对话** (`/aliAi/stream`)
   - 基于 Server-Sent Events (SSE) 的实时流式响应
   - 使用 WebFlux 的 Flowable 实现响应式流
   - 支持大文本的流式输出

#### ZmAiController 提供的接口：

1. **智能聊天** (`/zmAi/chat`)
   - 支持阿里云和本地模型切换
   - 支持跨域请求
   - 使用 SSE 实现实时响应

### 2. 文件处理功能

1. **Word 文档解析**
   - 使用 Apache POI 解析 Word 文档
   - 提取文档内容作为 AI 对话上下文
   - 支持控制字符转义

2. **FTP 文件存储**
   - 支持文件上传到 FTP 服务器
   - 生成唯一文件标识
   - 支持文件的存储和检索

### 3. 多数据源配置

模块配置了两个数据源：
- **AI 数据源**: 用于 AI 相关业务数据
- **企微数据源**: 用于企业微信相关业务数据

## 配置说明

### 应用配置 (application.properties)

```properties
# 应用名称
spring.application.name=linkwe-ai

# FTP 服务器配置
ftp.server=ftp.example.com
ftp.port=21
ftp.username=your_username
ftp.password=your_password
ftp.base-dir=/path/to/base/directory
```

### 常量配置 (Constant.java)

```java
public class Constant {
    // 阿里云 API Key (注意：生产环境应从配置中心或环境变量获取)
    public static String KEY = "sk-1f095e5103dd4567a9afec6b17ec0187";

    // 支持的模型
    public static String DEEPSEEK_R1 = "deepseek-r1";
    public static String QWEN_PLUS = "qwen-plus";
    public static String QWQ_32B = "qwq-32b";

    // 文件上传路径
    public static final String FILE_UPLOAD_PATH = "path/to/upload/directory";
}
```

## API 接口文档

### 1. 阿里云 AI 接口

#### 单次对话
- **URL**: `/aliAi/single`
- **Method**: POST
- **Request Body**:
```json
{
  "content": "用户输入的问题",
  "filePath": "Word文档路径（可选）"
}
```
- **Response**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "output": {
      "choices": [{
        "message": {
          "reasoning_content": "AI的思考过程",
          "content": "AI的最终回答"
        }
      }]
    }
  }
}
```

#### 多轮对话
- **URL**: `/aliAi/multiwheel`
- **Method**: POST
- **Request Body**: 同单次对话
- **Features**: 支持会话上下文管理

#### 流式对话
- **URL**: `/aliAi/stream`
- **Method**: POST
- **Content-Type**: `text/event-stream`
- **Response**: 流式返回 GenerationResult

### 2. 智能聊天接口

#### 聊天对话
- **URL**: `/zmAi/chat`
- **Method**: POST
- **CORS**: 支持跨域
- **Request Body**:
```json
{
  "content": "聊天内容",
  "filePath": "文件路径（可选）"
}
```
- **Response**: SseEmitter 对象，支持流式输出

## 开发指南

### 环境要求

1. **JDK 1.8+**
2. **Maven 3.5+**
3. **Redis 3.0+**（用于会话缓存）
4. **MySQL 5.7+**
5. **FTP 服务器**（文件存储）

### 本地开发

1. **配置修改**
   - 修改 `Constant.java` 中的 API Key
   - 配置 `application.properties` 中的 FTP 连接信息
   - 确保数据库和 Redis 连接正常

2. **启动步骤**
   ```bash
   # 构建项目
   mvn clean install

   # 启动应用
   mvn spring-boot:run
   ```

### 代码规范

1. **API Key 安全**
   - 生产环境应使用环境变量或配置中心存储 API Key
   - 避免将密钥硬编码在代码中

2. **异常处理**
   - 统一使用 `SystemException` 处理业务异常
   - 记录详细的错误日志

3. **资源清理**
   - 及时关闭 FTP 连接
   - 管理 SSE 连接的生命周期

## 扩展开发

### 添加新的 AI 模型

1. 在 `Constant.java` 中添加模型常量
2. 在 `AliAiUtils.java` 中实现调用方法
3. 在 Controller 中添加对应的接口

### 自定义文件处理

1. 扩展 `WordUtils.java` 支持更多文件格式
2. 在 `FileController.java` 中添加新的处理接口
3. 配置相应的文件解析器

### 集成其他 AI 服务

1. 添加新的 SDK 依赖到 `pom.xml`
2. 创建新的工具类封装 API 调用
3. 实现 Controller 层的接口

## 部署说明

### Docker 部署

```dockerfile
FROM openjdk:8-jre-alpine
COPY target/lw-ai.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]
```

### 配置管理

- 使用 Nacos 配置中心管理动态配置
- API Key、数据库连接等信息应外部化配置
- 支持多环境配置切换（dev/test/prod）

## 注意事项

1. **API Key 安全**
   - 当前代码中的 API Key 仅用于测试
   - 生产环境必须使用安全的配置管理方案

2. **性能优化**
   - 大文件处理建议使用异步方式
   - 合理设置 Redis 过期时间
   - FTP 连接池复用

3. **监控告警**
   - 添加 API 调用量监控
   - 设置异常响应时间告警
   - 监控文件存储使用情况

## 常见问题

### Q: 如何切换不同的 AI 模型？
A: 在调用 `AliAiUtils` 的方法时传入不同的 model 参数，支持的模型见 `Constant.java`。

### Q: Word 文档解析失败怎么办？
A: 检查文档格式是否为 `.docx`，确保文档没有损坏，查看 `WordUtils.java` 的错误日志。

### Q: 流式响应中断如何处理？
A: 检查网络连接，查看 SSE 连接状态，参考 `SSEHelper.java` 的错误处理逻辑。

### Q: 如何扩展支持本地大模型？
A: 参考 `ZmAiController.java` 中的 LOCAL 模式实现，添加新的配置和调用逻辑。

## 版本历史

- **v3.1.0**: 初始版本，集成阿里云 DashScope 服务
- 支持单次、多轮、流式对话
- 集成 Word 文档解析
- 支持 FTP 文件存储

## 联系方式

如有问题或建议，请联系项目维护团队或提交 Issue。