aiagent/docs/architecture.md

# 🏛️ 架构设计文档

> **Architecture Design Document**

---

## 一、系统概述

天工智能体平台是一个企业级 AI 智能体（Agent）平台，提供智能对话、知识库管理、智能体编排等核心能力，采用**前后端分离** + **异步任务队列** 的架构设计。

---

## 二、技术选型

| 层级 | 技术 | 版本 | 选型理由 |
|:----|:-----|:-----|:---------|
| **前端框架** | Vue 3 (Composition API) | 3.4+ | 轻量、响应式、TypeScript 友好 |
| **前端构建** | Vite | 5+ | 极速 HMR，开发体验优异 |
| **状态管理** | Pinia | 2+ | Vue 3 官方推荐，TypeScript 支持完善 |
| **路由** | Vue Router | 4+ | SPA 路由，支持导航守卫 |
| **HTTP 客户端** | Axios | 1+ | 请求/响应拦截，统一错误处理 |
| **后端框架** | FastAPI | 0.110+ | 高性能异步框架，自动生成 OpenAPI 文档 |
| **ORM** | SQLAlchemy | 2.0+ | 成熟的 Python ORM，异步支持 |
| **数据验证** | Pydantic | 2+ | 类型安全，与 FastAPI 深度集成 |
| **数据库迁移** | Alembic | 1.13+ | 版本化管理数据库变更 |
| **数据库** | MySQL (腾讯云) | 8.0+ | 稳定可靠的关系型数据库 |
| **缓存** | Redis | 7+ | 高性能缓存 + 消息队列 |
| **任务队列** | Celery | 5.3+ | 分布式异步任务处理 |
| **认证** | JWT | — | 无状态认证，支持 Token 刷新 |
| **容器化** | Docker + Docker Compose | 最新 | 简化部署，环境一致 |

---

## 三、架构分层

```
┌─────────────────────────────────────────────────────────────┐
│                   客户端层 (Client Layer)                     │
│  浏览器 (Chrome/Edge)  │  移动端  │  第三方 API 调用         │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTPS
┌───────────────────────▼─────────────────────────────────────┐
│                  接入层 (Gateway Layer)                      │
│  Nginx 反向代理 │  SSL 终止 │ 静态资源服务 │ 端口 8038/8037  │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                 前端应用层 (Frontend Layer)                   │
│  Vue 3 SPA  │  Pinia Store  │  Vue Router  │  Axios Client   │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ Views   │  │Components│  │  Stores  │  │   Utils      │  │
│  │ 页面组件 │  │ 公共组件  │  │ 状态管理  │  │ 工具/请求封装│  │
│  └─────────┘  └──────────┘  └──────────┘  └──────────────┘  │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTP/JSON
┌───────────────────────▼─────────────────────────────────────┐
│                 后端服务层 (Backend Layer)                    │
│  FastAPI  │  中间件  │  路由  │  依赖注入                    │
│  ┌──────────────┐  ┌──────────────────┐                    │
│  │  API 路由层   │  │  认证/授权中间件  │                    │
│  │  (api/v1/*)  │  │  (JWT、CORS)     │                    │
│  ├──────────────┤  ├──────────────────┤                    │
│  │  Service 层   │  │  任务调度         │                    │
│  │  (业务逻辑)   │  │  (Celery 任务)   │                    │
│  ├──────────────┤  ├──────────────────┤                    │
│  │  Models 层    │  │  Schemas 层       │                    │
│  │  (ORM 定义)   │  │  (数据验证)      │                    │
│  └──────────────┘  └──────────────────┘                    │
└──────┬────────────────────────────┬─────────────────────────┘
       │                            │
       ▼                            ▼
┌──────────────┐          ┌──────────────────┐
│  MySQL 8.0   │          │    Redis 7        │
│ (腾讯云)     │          │ 缓存 / 任务队列   │
│ 持久化存储   │          │ 会话 / 锁        │
└──────────────┘          └──────────────────┘
                                │
                                ▼
                      ┌──────────────────┐
                      │   Celery Worker   │
                      │ 异步任务处理       │
                      │ 文件处理 / 通知   │
                      └──────────────────┘
```

---

## 四、核心业务模块

### 1. 用户模块
- **注册/登录**：邮箱 + 密码，JWT Token 发放
- **Token 刷新**：Access Token (短期) + Refresh Token (长期)
- **个人中心**：信息查看与修改

### 2. 智能体模块
- 智能体的创建、配置、发布、下架
- 支持配置 LLM 参数、提示词、工具调用
- 知识库关联

### 3. 知识库模块
- 文档上传与解析（PDF、TXT、Markdown）
- 向量化存储（对接嵌入模型）
- 语义检索

### 4. 对话模块
- 用户与智能体的实时对话
- 上下文管理
- 流式输出（SSE）

---

## 五、数据流示例（对话请求）

```
1. 用户输入消息
       │
2. Axios POST /api/v1/conversations/{id}/messages
       │
3. Nginx 代理到后端 8037
       │
4. FastAPI 接收请求
   ├── JWT 中间件验证 Token
   ├── 路由分发到对应 Handler
   ├── Service 层处理业务逻辑
   │   ├── 查询对话历史 (MySQL)
   │   ├── 检索相关知识 (知识库)
   │   └── 调用 LLM API (异步)
   │
5. Celery 异步执行 LLM 调用
   ├── 进度通过 Redis Pub/Sub 推送
   └── SSE 推送给前端
       │
6. 前端流式渲染响应内容
```

---

## 六、安全设计

| 安全措施 | 说明 |
|:---------|:-----|
| JWT 认证 | Access Token 有效期短，Refresh Token 轮换 |
| 密码加密 | bcrypt 哈希存储 |
| CORS 配置 | 仅允许指定域名跨域访问 |
| 输入验证 | Pydantic 严格校验所有输入 |
| SQL 注入防护 | SQLAlchemy ORM 参数化查询 |
| HTTPS | Nginx 侧终止 SSL（生产环境） |

---

## 七、扩展性 & 可维护性

- **水平扩展**：FastAPI 为无状态应用，可多实例部署 + Nginx 负载均衡
- **异步任务**：Celery Worker 可独立扩展，处理大量异步任务
- **模块化**：后端按业务拆分为 `modules/`，新增功能不影响现有模块
- **数据库迁移**：Alembic 管理 Schema 变更，支持回滚
- **前端组件化**：Vue 组件按功能拆解，提升复用性

---

> 📎 **相关文档**：[项目结构概览](./project-structure.md) | [开发指南](./development-guide.md)