# 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
        }
      }
    }
  ]
};
```