# 🏗️ 项目结构概览

> **Project Structure Overview**

天工智能体平台采用前后端分离的架构，使用 pnpm + Vite + Vue 3 构建前端，FastAPI + SQLAlchemy 构建后端，通过 Celery + Redis 实现异步任务处理。

---

## 📁 顶层结构

```
aiagent/
├── frontend/              # 前端项目
│   ├── src/               # 源码目录
│   │   ├── views/         # 页面组件
│   │   ├── components/    # 公共组件
│   │   ├── stores/        # Pinia 状态管理
│   │   ├── utils/         # 工具函数
│   │   └── router/        # 路由配置
│   ├── public/            # 静态资源
│   ├── index.html         # 入口 HTML
│   ├── vite.config.js     # Vite 配置
│   └── package.json       # 前端依赖
│
├── backend/               # 后端项目
│   ├── app/               # 应用主目录
│   │   ├── modules/       # 业务模块
│   │   ├── core/          # 核心功能（配置、安全、Celery）
│   │   ├── models/        # SQLAlchemy 数据模型
│   │   ├── schemas/       # Pydantic 数据验证模型
│   │   ├── api/           # API 路由定义
│   │   ├── services/      # 业务逻辑层
│   │   └── utils/         # 通用工具函数
│   ├── tests/             # 测试用例
│   ├── alembic/           # 数据库迁移
│   ├── requirements.txt   # Python 依赖
│   └── Dockerfile         # 后端 Docker 镜像
│
├── docker-compose.dev.yml # Docker Compose 开发配置
├── nginx.conf             # Nginx 反向代理配置
├── .gitignore             # Git 忽略规则
└── README.md              # 项目总览文档
```

---

## 🖥️ 前端结构详解

### 目录路径约定

| 目录 | 用途 |
|:----|:------|
| `frontend/src/views/` | 页面级组件，按功能模块组织（如 `smart-assistant/`, `market/`） |
| `frontend/src/components/` | 可复用 UI 组件 |
| `frontend/src/stores/` | Pinia store，按模块管理全局状态 |
| `frontend/src/router/` | 路由配置，含权限控制守卫 |
| `frontend/src/utils/` | 通用工具函数（如 API 请求封装） |
| `frontend/public/` | 无需编译的静态资源 |

---

## ⚙️ 后端结构详解

### 模块化组织

```
backend/app/
├── main.py                # FastAPI 应用入口
├── config.py              # 配置管理（读取 .env）
├── core/
│   ├── security.py        # JWT 认证、密码加密
│   ├── celery_app.py      # Celery 异步任务配置
│   ├── database.py        # 数据库连接与会话管理
│   └── exceptions.py      # 全局异常处理
├── modules/
│   ├── user/              # 用户模块（注册、登录、个人信息）
│   ├── agent/             # 智能体模块
│   ├── knowledge/         # 知识库模块
│   └── conversation/      # 对话模块
├── models/                # SQLAlchemy ORM 模型
│   ├── user.py
│   ├── agent.py
│   └── knowledge.py
├── schemas/               # Pydantic 请求/响应模型
│   └── ...
├── api/                   # API 路由
│   ├── v1/                # API v1 路由
│   │   ├── users.py
│   │   ├── agents.py
│   │   └── ...
│   └── deps.py            # 依赖注入（当前用户等）
└── services/              # 业务逻辑层
    ├── user_service.py
    └── agent_service.py
```

---

## 🗄️ 数据流向

```
浏览器 (Vue 3)
    │
    ▼  HTTP/HTTPS
Nginx（反向代理，端口 8038/8037）
    │
    ├──► 前端静态资源 ──── 返回 HTML/CSS/JS
    │
    └──► 后端 API (FastAPI, 端口 8037)
            │
            ├──► Redis（缓存 / 会话）
            │
            ├──► MySQL（持久化数据）
            │
            └──► Celery Worker（异步任务，如文件处理）
```

---

## 🔗 依赖关系

```mermaid
flowchart TD
    subgraph 前端
        Vue[Vue 3 + Pinia]
        Router[Vue Router]
        Axios[Axios HTTP]
    end
    subgraph 后端
        FastAPI[FastAPI]
        SA[SQLAlchemy]
        Celery[Celery]
        Redis[Redis]
    end
    subgraph 数据
        MySQL[(MySQL)]
    end

    Vue --> Axios
    Axios --> FastAPI
    FastAPI --> SA --> MySQL
    FastAPI --> Redis
    Celery --> Redis
    Celery --> MySQL
```

---

> 💡 **提示**：实际目录结构以最新代码为准，本文档仅供参考。