ai-courseware/vue3-frontend/.trae/documents/AI客服对话窗口-技术架构文档.md

AI客服对话窗口 - 技术架构文档

1. 架构设计

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流式数据格式）：

{
    "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
        }
    }
}

订单卡片组件数据格式：

{
    "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"
            }
        }
    }
}

错误响应格式：

{
    "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类型定义

// 消息类型
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. 前端架构图

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 数据模型定义

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进行本地数据存储，数据结构如下：

// 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
        }
      }
    }
  ]
};