# smart_ticket

**Repository Path**: yckonnnn/smart_ticket

## Basic Information

- **Project Name**: smart_ticket
- **Description**: 智能工单系统ai智能辅助
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-01-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Ticket 智能工单系统 (Python 1.1.2)

本系统包含一个完整的 AI 智能客服与工单管理平台，支持 AI 自动回复、人工客服接入及工单流转。

---

## 🚀 如何运行 (How to Run)

您可以根据自己的情况选择以下任意一种方式启动：

### 方式 1：我是最终用户（免安装模式）✅ **推荐**
> 适用于：只想使用软件，电脑没装 Python 或不懂配置的人。

1. 解压文件夹。
2. 双击运行 **`启动绿色版.bat`**。
3. 系统会自动启动并打开浏览器。
   - **用户界面**: 员工咨询入口
   - **客服界面**: 客服接待工作台

---

### 方式 2：我是开发者（本机环境）
> 适用于：电脑已安装 Python，想使用本机环境运行。

1. 双击运行 **`一键启动.bat`**。
2. 脚本会自动创建虚拟环境、安装依赖并启动。

---

### 方式 3：制作绿色分发包（仅管理员）
> 适用于：您想把这个软件打包发给没装 Python 的同事。

1. 双击运行 **`构建绿色版环境.bat`**。
2. 等待脚本自动下载 Python 嵌入包并配置环境（需联网）。
3. 完成后，文件夹内会生成 `python_runtime` 目录。
4. 现在您可以把整个文件夹压缩发给任何人，他们只需使用 **方式 1** 即可运行。

---

## 📁 目录结构

```
Smart Ticket/
├── backend/                    # Python 后端服务
│   ├── main.py                 # 主程序入口
│   ├── database.py             # 数据库结构定义与初始化
│   ├── socket_events.py        # WebSocket 事件处理
│   ├── services/               # 业务逻辑 (AI, 邮件, Excel等)
│   └── ...
├── frontend/                   # 前端界面
│   ├── index.html              # 用户聊天界面
│   └── agent.html              # 客服工作台界面
├── data/                       # 数据文件
│   ├── agents.json             # 客服账号配置
│   ├── users.xlsx              # 用户信息表
│   ├── knowledge_base.json     # 知识库
│   └── service.db              # SQLite 数据库文件
├── python_runtime/             # [绿色版] 自带的 Python 环境
├── 一键启动.bat                # [开发者] 启动脚本
├── 启动绿色版.bat              # [用户] 启动脚本
└── 构建绿色版环境.bat          # [管理员] 构建脚本
```

---

## ⚙️ 核心配置说明

所有数据和配置均在 `data/` 目录下，您可以直接修改文件：

- **用户名单**: 修改 `data/users.xlsx`
- **客服账号**: 修改 `data/agents.json`
- **知识库**: 修改 `data/knowledge_base.json`
- **系统配置**: 修改 `data/config.json` (或在客服端设置中修改)
- **环境变量**: 修改 `backend/.env` (配置 API Key 和邮件服务)

### 🔐 默认测试账号

客服端登录地址：`http://localhost:3000/agent`

| 角色 | 邮箱 (账号) | 密码 | 说明 |
|------|------------|------|------|
| 客服 | kefu01@example.com | password123 | 普通客服 |
| 客服 | kefu02@example.com | password123 | 普通客服 |
| 经理 | manager@example.com | admin123 | 管理员权限 |

> **提示**：也可以使用 ID 登录，例如直接输入 `1001` 和密码。

### 📧 环境变量配置 (.env)

进入 `backend` 目录可以看到 `.env` 文件，用于配置 AI 和邮件服务：

```env
# API 配置
API_KEY=your_deepseek_api_key
API_BASE_URL=https://api.deepseek.com

# 邮件配置
EMAIL_USER=your_email@example.com
EMAIL_PASSWORD=your_email_password
EMAIL_SMTP=smtp.example.com
EMAIL_PORT=465

# 服务配置
PORT=3000
```

---

## 🗄️ 数据库结构说明

系统使用 SQLite 数据库存储数据，数据库文件位于 `data/service.db`。以下是各表的详细说明：

### 1. agents 表 (客服人员)

| 列名 | 类型 | 说明 |
|------|------|------|
| `id` | TEXT | 客服唯一标识 (主键) |
| `password` | TEXT | 登录密码 |
| `name` | TEXT | 客服姓名 |
| `email` | TEXT | 客服邮箱 |
| `department` | TEXT | 所属部门 |
| `role` | TEXT | 角色 (`agent` 普通客服 / `manager` 经理)，默认 `agent` |
| `online` | INTEGER | 是否在线 (0=离线, 1=在线) |
| `socket_id` | TEXT | 当前 WebSocket 连接 ID |
| `last_active_at` | TEXT | 最后活跃时间 |
| `created_at` | TEXT | 账号创建时间 |

---

### 2. tickets 表 (工单)

| 列名 | 类型 | 说明 |
|------|------|------|
| `id` | INTEGER | 自增主键 |
| `ticket_id` | TEXT | 工单唯一标识 (如 `TKT_1234567890`) |
| `ticket_no` | TEXT | 外部工单号 (可选) |
| `user_name` | TEXT | 申请人姓名 |
| `user_email` | TEXT | 申请人邮箱 |
| `user_department` | TEXT | 申请人部门 |
| `intent` | TEXT | 工单意图标签 (如 `IT 设备申请`) |
| `intent_key` | TEXT | 工单意图键名 (如 `it_device_request`) |
| `slots` | TEXT | 工单详情 (JSON 格式) |
| `status` | TEXT | 工单状态：`pending` (待处理) / `processing` (处理中) / `completed` (已完成) |
| `assigned_agent` | TEXT | 负责处理的客服姓名 |
| `created_at` | TEXT | 工单创建时间 |
| `accepted_at` | TEXT | 客服接单时间 |
| `completed_at` | TEXT | 工单完成时间 |
| `sent_at` | TEXT | 工单发送时间 (邮件发送) |

---

### 3. knowledge_base 表 (知识库)

| 列名 | 类型 | 说明 |
|------|------|------|
| `id` | TEXT | 知识条目唯一标识 (主键) |
| `questions` | TEXT | 触发问题列表 (JSON 数组格式) |
| `answer_zh` | TEXT | 中文答案 |
| `answer_en` | TEXT | 英文答案 |
| `category` | TEXT | 分类标签 |
| `created_at` | TEXT | 创建时间 |
| `updated_at` | TEXT | 最后更新时间 |

---

### 4. chat_rooms 表 (聊天会话)

| 列名 | 类型 | 说明 |
|------|------|------|
| `id` | INTEGER | 自增主键 |
| `room_id` | TEXT | 聊天室唯一标识 |
| `user_id` | TEXT | 用户 ID |
| `user_name` | TEXT | 用户姓名 |
| `user_email` | TEXT | 用户邮箱 |
| `user_department` | TEXT | 用户部门 |
| `agent_id` | TEXT | 接待客服 ID |
| `agent_name` | TEXT | 接待客服姓名 |
| `agent_email` | TEXT | 接待客服邮箱 |
| `status` | TEXT | 会话状态：`waiting` (等待接入) / `active` (服务中) / `closed` (已结束) |
| `created_at` | TEXT | 创建时间 |
| `updated_at` | TEXT | 最后更新时间 |
| `closed_at` | TEXT | 会话关闭时间 |

---

### 5. chat_messages 表 (聊天消息)

| 列名 | 类型 | 说明 |
|------|------|------|
| `id` | INTEGER | 自增主键 |
| `room_id` | TEXT | 所属聊天室 ID (外键关联 `chat_rooms.room_id`) |
| `sender_type` | TEXT | 发送者类型：`user` (用户) / `agent` (客服) / `bot` (AI 机器人) / `system` (系统消息) |
| `sender_name` | TEXT | 发送者姓名 |
| `content` | TEXT | 消息内容 |
| `created_at` | TEXT | 发送时间 |

---

### 6. logs 表 (操作日志)

| 列名 | 类型 | 说明 |
|------|------|------|
| `id` | INTEGER | 自增主键 |
| `level` | TEXT | 日志级别 (`info` / `warn` / `error`)，默认 `info` |
| `action` | TEXT | 操作类型 (如 `ai_interaction`, `kb_resolution`, `ticket_status_update`) |
| `user_id` | TEXT | 操作用户 ID |
| `user_name` | TEXT | 操作用户姓名 |
| `user_email` | TEXT | 操作用户邮箱 |
| `user_department` | TEXT | 操作用户部门 |
| `question` | TEXT | 用户提问内容 (AI 交互时) |
| `answer` | TEXT | AI/知识库回答内容 |
| `source` | TEXT | 回答来源：`ai` (AI 生成) / `kb` (知识库匹配) |
| `resolved` | INTEGER | 用户反馈状态：`-1` (未解决) / `0` (未反馈) / `1` (已解决) |
| `details` | TEXT | 其他详情 (JSON 格式) |
| `created_at` | TEXT | 记录创建时间 |

> **resolved 字段说明**：
> - `0`：AI 给出了回答，但用户未点击任何反馈按钮（默认状态）
> - `1`：用户点击了"✅ 已解决"按钮，表示问题已被解决
> - `-1`：用户点击了"❌ 未解决"按钮，表示问题未被解决

---

### 7. config 表 (系统配置)

| 列名 | 类型 | 说明 |
|------|------|------|
| `key` | TEXT | 配置项键名 (主键) |
| `value` | TEXT | 配置项值 |
| `updated_at` | TEXT | 最后更新时间 |

---

## 📝 开发者指南

### 后端核心文件

| 文件 | 功能 |
|------|------|
| `main.py` | 应用入口，定义 REST API 和 Socket.IO 服务器 |
| `socket_events.py` | 处理所有 WebSocket 事件（连接/断开/消息/接受用户等） |
| `database.py` | SQLite 数据库初始化和表结构管理 |
| `services/ai_service.py` | 调用 AI API 生成智能回复 |
| `services/data_service.py` | 数据访问层，封装所有数据库 CRUD 操作 |
| `services/excel_service.py` | Excel 报表生成服务 |

### 前端核心文件

| 文件 | 功能 |
|------|------|
| `index.html` | 用户聊天界面 |
| `agent.html` | 客服工作台 (接收 `index.html` 的请求) |

### WebSocket 事件列表

**Client → Server:**
- `agent_login` - 客服登录
- `user_request_agent` - 用户请求转人工
- `agent_accept_user` - 客服接受用户
- `chat_message` - 发送聊天消息
- `ticket_update` - 更新工单状态
- `end_chat` - 结束聊天会话

**Server → Client:**
- `login_success` - 登录成功
- `waiting_users` - 等待中的用户列表
- `chat_started` - 聊天会话开始
- `new_message` - 新消息到达
- `tickets_update` - 工单列表更新
- `agent_status_update` - 客服状态变更

---

## 📊 数据统计查询示例

以下是一些常用的 SQL 查询示例，可用于数据分析：

```sql
-- 统计 AI 解答满意率
SELECT 
    COUNT(*) AS total,
    SUM(CASE WHEN resolved = 1 THEN 1 ELSE 0 END) AS resolved_count,
    SUM(CASE WHEN resolved = -1 THEN 1 ELSE 0 END) AS unresolved_count,
    SUM(CASE WHEN resolved = 0 THEN 1 ELSE 0 END) AS no_feedback_count,
    ROUND(100.0 * SUM(CASE WHEN resolved = 1 THEN 1 ELSE 0 END) / 
          NULLIF(SUM(CASE WHEN resolved != 0 THEN 1 ELSE 0 END), 0), 2) AS satisfaction_rate
FROM logs 
WHERE action = 'ai_interaction';

-- 按部门统计工单数量
SELECT user_department, COUNT(*) AS ticket_count
FROM tickets
GROUP BY user_department
ORDER BY ticket_count DESC;

-- 查看最近 7 天的工单趋势
SELECT DATE(created_at) AS date, COUNT(*) AS count
FROM tickets
WHERE created_at >= DATE('now', '-7 days')
GROUP BY DATE(created_at)
ORDER BY date;
```