assist/TSP智能助手完整文档.md

# TSP智能助手完整文档

## 📋 目录
- [项目概述](#项目概述)
- [系统架构](#系统架构)
- [核心功能](#核心功能)
- [技术栈](#技术栈)
- [安装部署](#安装部署)
- [配置说明](#配置说明)
- [使用指南](#使用指南)
- [API接口](#api接口)
- [数据库设计](#数据库设计)
- [开发指南](#开发指南)
- [故障排除](#故障排除)
- [更新日志](#更新日志)

---

## 🚀 项目概述

TSP智能助手是一个基于大语言模型的智能客服系统，专为TSP（Telematics Service Provider）车辆服务提供商设计。系统集成了智能对话、工单管理、知识库、数据分析、飞书集成等核心功能。

### 核心特性
- **智能Agent架构**: 多工具集成，智能规划，自主学习
- **实时对话系统**: WebSocket支持，上下文理解，VIN识别
- **数据驱动分析**: 真实数据统计，可视化展示，系统监控
- **企业级管理**: 多环境部署，版本控制，热更新，自动备份
- **飞书集成**: 支持飞书多维表格数据同步和管理
- **AI准确率优化**: 智能判断AI建议质量，优先使用高质量内容入库

---

## 🏗️ 系统架构

### 整体架构
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端界面      │    │   后端服务      │    │   数据存储      │
│                 │    │                 │    │                 │
│ • 仪表板        │◄──►│ • Flask API     │◄──►│ • MySQL DB      │
│ • 智能对话      │    │ • WebSocket     │    │ • 知识库        │
│ • Agent管理     │    │ • Agent核心     │    │ • 工单系统      │
│ • 数据分析      │    │ • LLM集成       │    │ • 车辆数据      │
│ • 飞书同步      │    │ • 备份系统      │    │ • SQLite备份    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### 模块化设计
- **Web层**: Flask蓝图架构，模块化API设计
- **业务层**: Agent核心、对话管理、工单处理
- **数据层**: MySQL主库 + SQLite备份，ORM映射
- **集成层**: 飞书API、LLM服务、监控系统

---

## 🎯 核心功能

### 1. 智能对话系统 💬
- **多轮对话**: 支持上下文关联的连续对话
- **VIN识别**: 自动识别车辆VIN并获取实时数据
- **知识库检索**: 基于TF-IDF和余弦相似度的智能检索
- **工单创建**: 对话中直接创建和关联工单

### 2. Agent管理系统 🤖
- **工具管理**: 10+内置工具，支持自定义工具注册
- **执行监控**: 实时监控Agent任务执行状态
- **性能统计**: 工具使用频率和成功率分析
- **智能规划**: 基于目标的任务分解和执行

### 3. 工单管理系统 📋
- **AI建议生成**: 基于知识库生成工单处理建议
- **人工审核**: 支持人工输入和AI建议对比
- **语义相似度**: 使用sentence-transformers进行准确度评估
- **智能入库**: AI准确率<90%时优先使用人工描述入库
- **知识库更新**: 高相似度建议自动入库

### 4. 知识库管理 📚
- **多格式支持**: TXT、PDF、DOC、DOCX、MD文件
- **智能提取**: 自动从文档中提取Q&A对
- **向量化检索**: TF-IDF + 余弦相似度搜索
- **质量验证**: 支持知识条目验证和置信度设置

### 5. 数据分析系统 📊
- **实时趋势**: 基于真实数据的性能趋势分析
- **多维度统计**: 工单、预警、满意度等关键指标
- **系统健康**: CPU、内存、响应时间监控
- **可视化展示**: 丰富的图表和仪表板

### 6. 飞书集成系统 📱
- **多维表格同步**: 自动同步飞书多维表格数据
- **字段映射**: 智能映射飞书字段到本地数据库
- **实时更新**: 支持增量同步和全量同步
- **数据预览**: 同步前预览数据，确保准确性

### 7. 系统设置管理 ⚙️
- **API管理**: 支持多种LLM提供商配置
- **模型参数**: 温度、最大令牌数等参数调节
- **端口配置**: Web服务和WebSocket端口管理
- **日志级别**: 灵活的日志级别控制

---

## 🛠️ 技术栈

### 后端技术
- **Python 3.8+**: 核心开发语言
- **Flask**: Web框架和API服务
- **SQLAlchemy**: ORM数据库操作
- **WebSocket**: 实时通信支持
- **psutil**: 系统资源监控

### 前端技术
- **Bootstrap 5**: UI框架
- **Chart.js**: 数据可视化
- **JavaScript ES6+**: 前端逻辑
- **WebSocket**: 实时通信客户端

### AI/ML技术
- **大语言模型**: 支持OpenAI、通义千问等
- **sentence-transformers**: 语义相似度计算
- **TF-IDF**: 文本向量化
- **余弦相似度**: 语义相似度计算
- **Agent框架**: 智能任务规划

### 部署运维
- **Docker**: 容器化部署
- **Nginx**: 反向代理和静态文件服务
- **Systemd**: 服务管理
- **Git**: 版本控制

---

## 🚀 安装部署

### 环境要求
- Python 3.8+
- Node.js 16+ (可选，用于前端构建)
- Git
- MySQL 8.0+

### 安装步骤

1. **克隆项目**
```bash
git clone http://jeason.online:3000/zhaojie/assist.git
cd assist
```

2. **安装依赖**
```bash
pip install -r requirements.txt
```

3. **配置数据库**
```bash
# 创建MySQL数据库
mysql -u root -p
CREATE DATABASE tsp_assistant CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

4. **初始化数据库**
```bash
python init_database.py
```

5. **启动服务**
```bash
python start_dashboard.py
```

6. **访问系统**
- 打开浏览器访问: `http://localhost:5000`
- 默认端口: 5000 (可在系统设置中修改)

### Windows快速启动
```cmd
# 双击运行
快速启动.bat
```

---

## ⚙️ 配置说明

### 环境变量
```bash
# 数据库配置
DATABASE_URL=mysql+pymysql://user:password@host:port/database

# LLM配置
LLM_PROVIDER=openai
LLM_API_KEY=your_api_key
LLM_MODEL=gpt-3.5-turbo

# 服务配置
SERVER_PORT=5000
WEBSOCKET_PORT=8765
LOG_LEVEL=INFO
```

### 配置文件结构
```
config/
├── llm_config.py              # LLM客户端配置
├── integrations_config.json   # 飞书集成配置
├── ai_accuracy_config.py      # AI准确率配置
└── README.md                  # 配置说明文档
```

### 飞书集成配置
```json
{
  "feishu": {
    "app_id": "cli_a8b50ec0eed1500d",
    "app_secret": "ccxkE7ZCFQZcwkkM1rLy0ccZRXYsT2xK",
    "app_token": "XXnEbiCmEaMblSs6FDJcFCqsnIg",
    "table_id": "tblnl3vJPpgMTSiP",
    "status": "active"
  },
  "system": {
    "sync_limit": 10,
    "ai_suggestions_enabled": true,
    "auto_sync_interval": 0
  }
}
```

### AI准确率配置
```python
# 默认配置
auto_approve_threshold = 0.95      # 自动审批阈值
use_human_resolution_threshold = 0.90  # 使用人工描述阈值
manual_review_threshold = 0.80     # 人工审核阈值
```

---

## 📖 使用指南

### 基础操作

#### 1. 智能对话
1. 在"智能对话"页面输入问题
2. 系统自动检索知识库并生成回答
3. 支持VIN码识别和车辆数据查询

#### 2. 工单管理
1. 创建工单并获取AI建议
2. 输入人工处理描述
3. 系统自动计算语义相似度
4. 根据相似度决定入库策略

#### 3. 知识库维护
1. 手动添加Q&A对
2. 上传文档自动提取知识
3. 设置置信度和验证状态

#### 4. 飞书数据同步
1. 配置飞书应用凭证
2. 在主仪表板"飞书同步"标签页
3. 测试连接并执行数据同步

### 高级功能

#### 1. Agent工具管理
- 查看工具使用统计
- 注册自定义工具
- 监控执行历史

#### 2. 数据分析
- 多维度数据统计
- 自定义时间范围
- 导出分析报告

#### 3. 系统配置
- API和模型参数配置
- 端口和日志级别设置
- 环境变量管理

---

## 🔌 API接口

### 工单管理API
```http
POST /api/workorders/{id}/ai-suggestion
POST /api/workorders/{id}/human-resolution
POST /api/workorders/{id}/approve-to-knowledge
GET  /api/workorders
POST /api/workorders
PUT  /api/workorders/{id}
DELETE /api/workorders/{id}
```

### 知识库API
```http
GET  /api/knowledge
POST /api/knowledge
PUT  /api/knowledge/{id}
DELETE /api/knowledge/{id}
POST /api/knowledge/search
POST /api/knowledge/upload
```

### 对话API
```http
POST /api/chat/session
GET  /api/chat/session/{id}
DELETE /api/chat/session/{id}
POST /api/chat/message
```

### Agent管理API
```http
GET  /api/agent/status
POST /api/agent/tools/execute
POST /api/agent/tools/register
GET  /api/agent/tools/stats
```

---

## 🗄️ 数据库设计

### 核心表结构

#### work_orders (工单表)
```sql
CREATE TABLE work_orders (
    id INT PRIMARY KEY AUTO_INCREMENT,
    order_id VARCHAR(50) UNIQUE NOT NULL,
    title VARCHAR(200) NOT NULL,
    description TEXT NOT NULL,
    category VARCHAR(100) NOT NULL,
    priority VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    resolution TEXT,
    satisfaction_score FLOAT,
    
    -- 飞书集成字段
    feishu_record_id VARCHAR(100),
    source VARCHAR(50),
    module VARCHAR(100),
    created_by VARCHAR(100),
    wilfulness VARCHAR(100),
    date_of_close DATETIME,
    vehicle_type VARCHAR(100),
    vin_sim VARCHAR(50),
    app_remote_control_version VARCHAR(100),
    hmi_sw VARCHAR(100),
    parent_record VARCHAR(100),
    has_updated_same_day VARCHAR(50),
    operating_time VARCHAR(100)
);
```

#### work_order_suggestions (工单建议表)
```sql
CREATE TABLE work_order_suggestions (
    id INT PRIMARY KEY AUTO_INCREMENT,
    work_order_id INT NOT NULL,
    ai_suggestion TEXT,
    human_resolution TEXT,
    ai_similarity FLOAT,
    approved BOOLEAN DEFAULT FALSE,
    use_human_resolution BOOLEAN DEFAULT FALSE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (work_order_id) REFERENCES work_orders(id)
);
```

#### knowledge_entries (知识库表)
```sql
CREATE TABLE knowledge_entries (
    id INT PRIMARY KEY AUTO_INCREMENT,
    question TEXT NOT NULL,
    answer TEXT NOT NULL,
    category VARCHAR(100),
    confidence_score FLOAT DEFAULT 0.5,
    usage_count INT DEFAULT 0,
    is_active BOOLEAN DEFAULT TRUE,
    is_verified BOOLEAN DEFAULT FALSE,
    verified_by VARCHAR(100),
    verified_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

---

## 👨‍💻 开发指南

### 项目结构
```
tsp-assistant/
├── src/                        # 源代码
│   ├── agent/                  # Agent核心模块
│   ├── analytics/              # 数据分析模块
│   ├── config/                 # 配置模块
│   ├── core/                   # 核心模块
│   ├── dialogue/               # 对话模块
│   ├── integrations/           # 集成模块
│   ├── knowledge_base/         # 知识库模块
│   ├── utils/                  # 工具模块
│   ├── vehicle/                # 车辆数据模块
│   └── web/                    # Web应用模块
├── config/                     # 配置文件
├── scripts/                    # 脚本文件
├── uploads/                    # 上传文件
├── requirements.txt            # 依赖文件
├── init_database.py           # 数据库初始化
└── start_dashboard.py         # 启动脚本
```

### 代码规范
- **Python**: 遵循PEP 8规范
- **JavaScript**: 使用ES6+语法
- **提交信息**: 使用约定式提交格式
- **文档**: 新功能需要添加相应的文档

### 开发流程
1. Fork项目到个人仓库
2. 创建功能分支: `git checkout -b feature/new-feature`
3. 提交更改: `git commit -m "Add new feature"`
4. 推送分支: `git push origin feature/new-feature`
5. 创建Pull Request

---

## 🚨 故障排除

### 常见问题

#### 1. 数据库连接失败
```bash
# 检查数据库服务状态
systemctl status mysql

# 检查连接配置
python -c "from src.core.database import db_manager; print(db_manager.test_connection())"
```

#### 2. 飞书集成问题
- 检查飞书应用权限配置
- 验证app_token和table_id是否正确
- 确认网络连接和API访问权限

#### 3. AI建议生成失败
- 检查LLM API配置
- 验证知识库数据完整性
- 查看应用日志

#### 4. 数据库字段缺失
```bash
# 运行数据库迁移
python init_database.py

# 手动添加字段
mysql -u root -p tsp_assistant
ALTER TABLE work_order_suggestions ADD COLUMN use_human_resolution BOOLEAN DEFAULT FALSE;
```

### 日志位置
- **应用日志**: `logs/tsp_assistant.log`
- **访问日志**: Nginx访问日志
- **错误追踪**: 详细的错误堆栈信息

### 性能优化
- **数据库索引**: 为常用查询字段添加索引
- **缓存策略**: 使用Redis缓存热点数据
- **异步处理**: 耗时操作使用异步处理
- **连接池**: 配置数据库连接池

---

## 📝 更新日志

### v1.4.0 (2025-09-19)
- ✅ 飞书集成功能：支持飞书多维表格数据同步
- ✅ 页面功能合并：飞书同步页面合并到主仪表板
- ✅ 数据库架构优化：扩展工单表字段，支持飞书数据
- ✅ 代码重构优化：大文件拆分，降低运行风险
- ✅ 字段映射完善：智能映射飞书字段到本地数据库
- ✅ 数据库初始化改进：集成字段迁移到初始化流程
- ✅ AI准确率优化：AI准确率<90%时优先使用人工描述入库
- ✅ 语义相似度计算：使用sentence-transformers提升准确度

### v1.3.0 (2025-09-17)
- ✅ 数据库架构优化：MySQL主数据库+SQLite备份系统
- ✅ 工单详情API修复：解决数据库会话管理问题
- ✅ 备份管理系统：自动备份MySQL数据到SQLite
- ✅ 数据库状态监控：实时监控MySQL和SQLite状态
- ✅ 备份管理API：支持数据备份和恢复操作

### v1.2.0 (2025-09-16)
- ✅ 系统设置扩展：API管理、模型参数配置、端口管理
- ✅ 真实数据分析：修复性能趋势图表显示问题
- ✅ 工单AI建议功能：智能生成处理建议
- ✅ 知识库搜索优化：提升检索准确率
- ✅ Agent管理改进：工具使用统计和自定义工具

---

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 支持与联系

- **项目地址**: http://jeason.online:3000/zhaojie/assist
- **问题反馈**: 请在Issues中提交问题
- **功能建议**: 欢迎提交Feature Request

## 🙏 致谢

感谢所有为项目做出贡献的开发者和用户！

---

**TSP智能助手** - 让车辆服务更智能，让客户体验更美好！ 🚗✨