aiagent/docs/project-structure.md

# 🏗️ 项目结构概览

> **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 应用入口，路由注册，中间件配置
├── core/
│   ├── config.py          # 配置管理（读取 .env）
│   ├── database.py        # 数据库连接、会话管理、init_db()
│   ├── security.py        # JWT 认证、密码加密
│   ├── exceptions.py      # 全局异常处理（BaseAPIException）
│   ├── error_handler.py   # 异常 → HTTP 响应映射
│   ├── rate_limiter.py    # Redis 滑动窗口限流中间件
│   ├── security_headers.py# HSTS/安全头中间件
│   ├── behavior_middleware.py # 用户行为采集中间件
│   └── metrics.py         # Prometheus 指标暴露
├── api/                   # API 路由（45 个模块，245+ 端点）
│   ├── agents.py          # Agent CRUD/执行/导入导出
│   ├── agent_chat.py      # 对话/SSE 流式/编排
│   ├── agent_market.py    # Agent 技能市场
│   ├── agent_swarm.py     # Agent 蜂群
│   ├── workflows.py       # 工作流 CRUD/执行/版本
│   ├── knowledge_base.py  # 知识库/文档/搜索/RAG
│   ├── tools.py           # 工具管理
│   ├── scene_contracts.py # 统一 DSL 场景契约
│   ├── template_market.py # 工作流模板市场
│   ├── platform_templates.py # 场景模板一键创建
│   ├── plugins.py         # 插件系统
│   ├── alert_rules.py     # 告警规则
│   ├── monitoring.py      # 系统监控
│   ├── feishu_bind.py     # 飞书集成
│   ├── auth.py            # 认证（注册/登录/JWT）
│   ├── workspaces.py      # 多租户工作区
│   ├── push.py            # 浏览器推送通知
│   ├── fcm.py             # Firebase Cloud Messaging
│   ├── voice.py           # 语音/TTS
│   ├── uploads.py         # 文件上传
│   └── ...                # 更多 API 模块
├── models/                # SQLAlchemy ORM 模型（37 个文件，50+ 张表）
│   ├── agent.py           # Agent, GlobalKnowledge, KnowledgeEntity, etc.
│   ├── workflow.py        # Workflow
│   ├── workflow_version.py# WorkflowVersion
│   ├── workflow_template.py # WorkflowTemplate, TemplateRating, TemplateFavorite
│   ├── execution.py       # Execution
│   ├── execution_log.py   # ExecutionLog
│   ├── agent_llm_log.py   # AgentLLMLog（LLM 调用日志）
│   ├── agent_vector_memory.py # AgentVectorMemory（向量记忆）
│   ├── knowledge_base.py  # KnowledgeBase, Document, DocumentChunk
│   ├── node_template.py   # NodeTemplate（提示词模板）
│   ├── scene_contract.py  # SceneContract（统一 DSL 契约）
│   ├── alert_rule.py      # AlertRule, AlertLog
│   ├── plugin.py          # NodePlugin
│   ├── workspace.py       # Workspace, WorkspaceMembership
│   └── ...
├── services/              # 业务逻辑层
│   ├── scene_templates.py # 11 个场景模板注册 + prompt 生成
│   ├── scene_contract_service.py # DSL 契约服务（prompt/验收/验证）
│   ├── workflow_validator.py # 工作流 DAG 验证
│   ├── permission_service.py  # 权限检查
│   └── ...
├── tests/                 # 测试用例（148+ tests）
└── alembic/               # 数据库迁移版本
```

---

## 🗄️ 数据流向

```
浏览器 (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
```

---

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