# ai-customer-service

**Repository Path**: KitonDg/ai-customer-service

## Basic Information

- **Project Name**: ai-customer-service
- **Description**: AI客服智能知识库系统是基于“Spring Boot + MySQL 8.0 + Dify”架构的企业级智能客服支撑平台，核心解决PCB业务场景下“客服响应慢、知识管理乱、SOP不统一、培训无数据”的痛点，通过AI检索增强（RAG）、知识闭环管理、SOP智能生成，实现“客服提效、知识沉淀、业务标准化”的目标。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-11-13
- **Last Updated**: 2025-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dify知识库管理系统

基于Spring Boot 3和Dify集成的AI知识库管理系统，提供智能问答、问题记录、未解答问题管理、SOP生成以及知识库文档管理等核心功能。

## 🚀 快速开始

### Dify设置（必读）⭐

**第一次使用？** 请先阅读 → [DIFY_SETUP_SUMMARY.md](DIFY_SETUP_SUMMARY.md) 📖

#### 快速配置（3步完成）

```bash
# 1. 运行配置向导
./configure-dify.sh

# 2. 测试连接
./test-dify-connection.sh

# 3. 启动服务
./start-all.sh
```

#### 详细文档

| 文档 | 说明 | 适合人群 |
|------|------|----------|
| [DIFY_SETUP_SUMMARY.md](DIFY_SETUP_SUMMARY.md) | 📖 文档导航和学习路径 | **推荐首先阅读** |
| [DIFY_SETUP_GUIDE.md](DIFY_SETUP_GUIDE.md) | 📚 完整设置指南（从零开始） | 新手用户 |
| [DIFY_QUICK_REFERENCE.md](DIFY_QUICK_REFERENCE.md) | 📋 快速参考卡片 | 快速查找 |
| [DIFY_CONFIGURATION.md](DIFY_CONFIGURATION.md) | ⚙️ 详细配置说明 | 深入配置 |

#### 核心步骤概览

1. **安装Dify** → 使用Docker启动Dify服务
2. **创建知识库** → 在Dify控制台创建知识库
3. **创建应用** → 创建Chat应用并关联知识库
4. **获取密钥** → 复制API密钥（app-开头）
5. **配置系统** → 运行 `./configure-dify.sh`
6. **测试验证** → 运行 `./test-dify-connection.sh`

**遇到问题？** 查看 [DIFY_QUICK_REFERENCE.md](DIFY_QUICK_REFERENCE.md) 的常见问题部分

## 功能特性

### 1. AI问答知识库
- 基于Dify的智能问答
- 知识来源引用
- 问答记录保存
- 无相关知识提示

### 2. 问题记录管理
- 历史记录查询
- 用户筛选
- 时间范围筛选
- 分页展示

### 3. 未解答问题管理
- 未解答问题列表
- 人工解答提交
- 解答评分（有用/无用）
- 每日评分限制
- 定时同步高分答案到知识库

### 4. SOP文档生成
- 基于知识库生成SOP
- 支持PDF和Markdown格式
- 知识来源标注

### 5. 知识库文档管理
- 支持PDF/Word/Excel上传
- 文档文本提取
- Dify向量化处理
- 文档版本管理
- 版本对比功能

## 技术栈

### 后端
- **框架**: Spring Boot 3.x
- **Java**: JDK 21
- **数据库**: MySQL 8.0
- **ORM**: MyBatis-Plus
- **HTTP客户端**: Spring WebClient
- **文档处理**: Apache POI, Apache PDFBox

### 前端
- **框架**: Vue 3
- **路由**: Vue Router
- **HTTP客户端**: Axios
- **构建工具**: Vite

### 第三方服务
- **AI服务**: Dify API

## 快速开始

### 前置要求
- JDK 21
- Maven 3.6+
- MySQL 8.0
- Node.js 16+

### 1. 克隆项目

```bash
git clone <repository-url>
cd ai-customer-service
```

### 2. 初始化数据库

```bash
# 启动MySQL服务
# macOS: brew services start mysql
# Linux: sudo systemctl start mysql

# 执行初始化脚本
mysql -h localhost -P 3306 -u root -p < init-database.sql
```

### 3. 配置Dify API（可选）

编辑 `src/main/resources/application.yml`:

```yaml
dify:
  api:
    base-url: https://api.dify.ai/v1
    key: your-dify-api-key-here
```

### 4. 启动服务

#### 方法1: 使用一键启动脚本

```bash
./start-all.sh
```

#### 方法2: 手动启动

**启动后端**:
```bash
mvn spring-boot:run
```

**启动前端**:
```bash
cd frontend
npm install
npm run dev
```

### 5. 访问应用

- **前端**: http://localhost:5173
- **后端**: http://localhost:8080

### 6. 停止服务

```bash
./stop-all.sh
```

## 测试

### 运行集成测试

```bash
./test-integration.sh
```

### 查看测试清单

详细的测试检查清单请参考 [TEST_CHECKLIST.md](TEST_CHECKLIST.md)

### 集成测试指南

完整的集成测试步骤请参考 [INTEGRATION_TEST_GUIDE.md](INTEGRATION_TEST_GUIDE.md)

## 项目结构

```
.
├── src/main/java/com/dify/knowledge/
│   ├── controller/          # REST控制器
│   ├── service/            # 业务逻辑层
│   ├── repository/         # 数据访问层
│   ├── entity/             # 实体类
│   ├── dto/                # 数据传输对象
│   ├── config/             # 配置类
│   ├── exception/          # 异常处理
│   └── util/               # 工具类
├── src/main/resources/
│   ├── application.yml     # 应用配置
│   └── schema.sql          # 数据库脚本
├── frontend/
│   ├── src/
│   │   ├── views/          # 页面组件
│   │   ├── api/            # API调用
│   │   └── router/         # 路由配置
│   └── package.json
├── init-database.sql       # 数据库初始化脚本
├── start-all.sh           # 一键启动脚本
├── stop-all.sh            # 停止服务脚本
├── test-integration.sh    # 集成测试脚本
└── pom.xml                # Maven配置
```

## API文档

### 问答接口

**提交问题**
```
POST /api/qa/ask
Content-Type: application/json

{
  "question": "问题内容",
  "userId": 1
}
```

**获取历史记录**
```
GET /api/qa/history?page=0&size=10&userId=1
```

### 未解答问题接口

**获取列表**
```
GET /api/unanswered/list?page=0&size=10
```

**提交解答**
```
POST /api/unanswered/{questionId}/answer
Content-Type: application/json

{
  "answer": "解答内容",
  "userId": 1
}
```

**评分**
```
POST /api/unanswered/answer/{answerId}/rate
Content-Type: application/json

{
  "rating": "useful",
  "userId": 1
}
```

### SOP生成接口

**生成SOP**
```
POST /api/sop/generate
Content-Type: application/json

{
  "topic": "主题",
  "format": "markdown",
  "userId": 1
}
```

### 文档管理接口

**上传文档**
```
POST /api/documents/upload
Content-Type: multipart/form-data

file: <文件>
userId: 1
```

**获取列表**
```
GET /api/documents/list?page=0&size=10
```

**删除文档**
```
DELETE /api/documents/{documentId}
```

**获取版本**
```
GET /api/documents/{documentId}/versions
```

**对比版本**
```
GET /api/documents/compare?version1Id=1&version2Id=2
```

## 配置说明

### 数据库配置

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/dify_knowledge_system
    username: root
    password: root
```

### Dify API配置

```yaml
dify:
  api:
    base-url: https://api.dify.ai/v1
    key: your-api-key
    timeout: 30000
    max-retries: 3
```

### 文件上传配置

```yaml
file:
  upload:
    path: ./uploads
    allowed-types: pdf,doc,docx,xls,xlsx

spring:
  servlet:
    multipart:
      max-file-size: 50MB
      max-request-size: 50MB
```

### 定时任务配置

```yaml
scheduled:
  sync-answers:
    cron: 0 0 2 * * ?  # 每天凌晨2点执行
    enabled: true
```

## 常见问题

### 1. 后端启动失败

**问题**: `Communications link failure`

**解决方案**:
- 检查MySQL是否运行
- 验证数据库连接配置
- 确认数据库已创建

### 2. Dify API调用失败

**问题**: `DifyApiException`

**解决方案**:
- 验证API密钥是否正确
- 检查网络连接
- 确认Dify服务可访问

### 3. 文件上传失败

**问题**: `DocumentProcessingException`

**解决方案**:
- 检查上传目录权限
- 验证文件类型是否支持
- 确认文件大小未超限

## 开发指南

### 添加新功能

1. 创建实体类（entity）
2. 创建Mapper接口（repository）
3. 实现业务逻辑（service）
4. 创建REST控制器（controller）
5. 添加前端页面（frontend/src/views）
6. 配置路由（frontend/src/router）

### 代码规范

- 遵循阿里巴巴Java开发手册
- 使用Lombok简化代码
- 统一异常处理
- RESTful API设计

## 许可证

[MIT License](LICENSE)

## 联系方式

如有问题或建议，请提交Issue或Pull Request。