354 lines
7.0 KiB
Markdown
354 lines
7.0 KiB
Markdown
# AI客服对话窗口 - 技术架构文档
|
||
|
||
## 1. 架构设计
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[用户浏览器] --> B[Vue3 前端应用]
|
||
B --> C[AI API服务]
|
||
B --> D[本地存储 LocalStorage]
|
||
|
||
subgraph "前端层"
|
||
B
|
||
E[组件库]
|
||
F[状态管理 Pinia]
|
||
G[路由管理 Vue Router]
|
||
end
|
||
|
||
subgraph "数据层"
|
||
D
|
||
end
|
||
|
||
subgraph "外部服务"
|
||
C
|
||
end
|
||
|
||
B --> E
|
||
B --> F
|
||
B --> G
|
||
```
|
||
|
||
## 2. 技术描述
|
||
|
||
* **前端**：Vue3\@3.3+ + TypeScript\@5.0+ + Vite\@4.0+ + TailwindCSS\@3.3+
|
||
|
||
* **状态管理**：Pinia\@2.1+
|
||
|
||
* **路由**：Vue Router\@4.2+
|
||
|
||
* **UI组件**：Ant Design Vue\@4.0+ 或 Element Plus\@2.4+
|
||
|
||
* **数据存储**：LocalStorage（历史对话）
|
||
|
||
* **Mock服务**：简单的SSE Mock API（开发测试用）
|
||
|
||
* **流式处理**：Server-Sent Events (SSE)
|
||
|
||
## 3. 路由定义
|
||
|
||
| 路由 | 用途 |
|
||
| --------- | ---------------- |
|
||
| / | 对话主界面，提供实时AI对话功能 |
|
||
| /history | 历史对话页面，查看和管理对话记录 |
|
||
| /settings | 设置页面，配置界面和数据选项 |
|
||
|
||
## 4. API定义
|
||
|
||
### 4.1 Mock API服务
|
||
|
||
由于暂无后端API服务，将创建简单的Mock API用于开发测试：
|
||
|
||
AI对话相关（Mock SSE服务）
|
||
|
||
```
|
||
POST /api/chat/stream
|
||
```
|
||
|
||
请求：
|
||
|
||
| 参数名称 | 参数类型 | 是否必需 | 描述 |
|
||
| ---------------- | ------ | ----- | ------------- |
|
||
| message | string | true | 用户输入的消息内容 |
|
||
| conversation\_id | string | false | 对话会话ID，用于多轮对话 |
|
||
|
||
响应（SSE流式数据格式）：
|
||
|
||
```json
|
||
{
|
||
"session_id": "default",
|
||
"timestamp": "2025-10-15T16:19:07.139531",
|
||
"type": "data",
|
||
"payload": {
|
||
"data_type": "general_chat_stream",
|
||
"content": {
|
||
"chunk": "助手",
|
||
"full_message": "您好！我是您的智能客服助手",
|
||
"is_final": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**订单卡片组件数据格式：**
|
||
|
||
```json
|
||
{
|
||
"session_id": "default",
|
||
"timestamp": "2025-10-15T16:19:07.139531",
|
||
"type": "data",
|
||
"payload": {
|
||
"data_type": "component_data",
|
||
"content": {
|
||
"chunk": "",
|
||
"full_message": "",
|
||
"is_final": true
|
||
},
|
||
"component": {
|
||
"type": "order_card",
|
||
"data": {
|
||
"order_id": "ORD20241015001",
|
||
"product_name": "iPhone 15 Pro",
|
||
"price": 7999.00,
|
||
"status": "已发货",
|
||
"order_time": "2024-10-15 14:30:00"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应格式：**
|
||
|
||
```json
|
||
{
|
||
"session_id": "default",
|
||
"timestamp": "2025-10-15T16:19:07.139531",
|
||
"type": "error",
|
||
"payload": {
|
||
"error_code": "NETWORK_ERROR",
|
||
"error_message": "网络连接异常，请稍后重试"
|
||
}
|
||
}
|
||
```
|
||
|
||
**流式数据处理说明：**
|
||
|
||
* `session_id`: 会话标识符
|
||
|
||
* `timestamp`: 数据时间戳
|
||
|
||
* `type`: 数据类型（data/error/done）
|
||
|
||
* `payload.data_type`: 具体数据类型
|
||
|
||
* `general_chat_stream`: 普通对话流
|
||
|
||
* `thinking_process`: AI思考过程
|
||
|
||
* `component_data`: 订单卡片组件数据
|
||
|
||
* `payload.content.chunk`: 当前数据块
|
||
|
||
* `payload.content.full_message`: 完整消息（累积）
|
||
|
||
* `payload.content.is_final`: 是否为最终数据块
|
||
|
||
### 4.2 TypeScript类型定义
|
||
|
||
```typescript
|
||
// 消息类型
|
||
interface Message {
|
||
id: string;
|
||
type: 'user' | 'ai' | 'thinking' | 'component';
|
||
content: string;
|
||
timestamp: number;
|
||
component?: OrderCardData;
|
||
}
|
||
|
||
// 订单卡片数据（简化版）
|
||
interface OrderCardData {
|
||
type: 'order_card';
|
||
data: {
|
||
order_id: string; // 订单号
|
||
product_name: string; // 商品名称
|
||
price: number; // 价格
|
||
status: string; // 订单状态
|
||
order_time: string; // 下单时间
|
||
};
|
||
}
|
||
|
||
// 对话会话
|
||
interface Conversation {
|
||
id: string;
|
||
title: string;
|
||
messages: Message[];
|
||
created_at: number;
|
||
updated_at: number;
|
||
}
|
||
|
||
// SSE流式响应数据结构
|
||
interface SSEResponse {
|
||
session_id: string;
|
||
timestamp: string;
|
||
type: 'data' | 'error' | 'done';
|
||
payload: {
|
||
data_type: 'general_chat_stream' | 'thinking_process' | 'component_data';
|
||
content: {
|
||
chunk: string;
|
||
full_message: string;
|
||
is_final: boolean;
|
||
};
|
||
component?: OrderCardData;
|
||
};
|
||
}
|
||
|
||
// 错误响应（简化版）
|
||
interface SSEErrorResponse {
|
||
session_id: string;
|
||
timestamp: string;
|
||
type: 'error';
|
||
payload: {
|
||
error_code: string;
|
||
error_message: string;
|
||
};
|
||
}
|
||
|
||
// Mock API 请求类型
|
||
interface ChatRequest {
|
||
message: string;
|
||
conversation_id?: string;
|
||
}
|
||
```
|
||
|
||
## 5. 前端架构图
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[App.vue] --> B[路由层 Router]
|
||
B --> C[页面组件 Views]
|
||
C --> D[业务组件 Components]
|
||
D --> E[基础组件 Base Components]
|
||
|
||
F[状态管理 Pinia] --> G[Chat Store]
|
||
F --> H[Settings Store]
|
||
F --> I[History Store]
|
||
|
||
J[工具层 Utils] --> K[API Client]
|
||
J --> L[Storage Helper]
|
||
J --> M[Stream Handler]
|
||
|
||
subgraph "组件层次"
|
||
A
|
||
B
|
||
C
|
||
D
|
||
E
|
||
end
|
||
|
||
subgraph "状态管理"
|
||
F
|
||
G
|
||
H
|
||
I
|
||
end
|
||
|
||
subgraph "工具服务"
|
||
J
|
||
K
|
||
L
|
||
M
|
||
end
|
||
```
|
||
|
||
## 6. 数据模型
|
||
|
||
### 6.1 数据模型定义
|
||
|
||
```mermaid
|
||
erDiagram
|
||
CONVERSATION ||--o{ MESSAGE : contains
|
||
MESSAGE ||--o| COMPONENT : may_have
|
||
|
||
CONVERSATION {
|
||
string id PK
|
||
string title
|
||
number created_at
|
||
number updated_at
|
||
}
|
||
|
||
MESSAGE {
|
||
string id PK
|
||
string conversation_id FK
|
||
string type
|
||
string content
|
||
number timestamp
|
||
string component_id FK
|
||
}
|
||
|
||
COMPONENT {
|
||
string id PK
|
||
string type
|
||
object data
|
||
}
|
||
```
|
||
|
||
### 6.2 本地存储结构
|
||
|
||
由于使用LocalStorage进行本地数据存储，数据结构如下：
|
||
|
||
```typescript
|
||
// LocalStorage 键值结构
|
||
interface LocalStorageSchema {
|
||
'ai-chat-conversations': Conversation[];
|
||
'ai-chat-settings': {
|
||
theme: 'light' | 'dark';
|
||
fontSize: 'small' | 'medium' | 'large';
|
||
autoSave: boolean;
|
||
};
|
||
'ai-chat-current-session': string; // 当前会话ID
|
||
}
|
||
|
||
// 示例数据
|
||
const exampleConversation: Conversation = {
|
||
id: 'conv_123',
|
||
title: '关于订单查询的对话',
|
||
created_at: 1703123456789,
|
||
updated_at: 1703123456789,
|
||
messages: [
|
||
{
|
||
id: 'msg_1',
|
||
type: 'user',
|
||
content: '我想查询我的订单',
|
||
timestamp: 1703123456789
|
||
},
|
||
{
|
||
id: 'msg_2',
|
||
type: 'thinking',
|
||
content: '正在查询您的订单信息...',
|
||
timestamp: 1703123456790
|
||
},
|
||
{
|
||
id: 'msg_3',
|
||
type: 'ai',
|
||
content: '我找到了您的订单信息',
|
||
timestamp: 1703123456791
|
||
},
|
||
{
|
||
id: 'msg_4',
|
||
type: 'component',
|
||
content: '',
|
||
timestamp: 1703123456792,
|
||
component: {
|
||
type: 'order_card',
|
||
data: {
|
||
orderId: 'ORD123456',
|
||
status: '已发货',
|
||
amount: 299.00
|
||
}
|
||
}
|
||
}
|
||
]
|
||
};
|
||
```
|
||
|