项目的框架架构

整体概览

• 整体形态：典型的 前后端分离 项目
  • 前端：Vue 3 + Vite 单页应用（SPA）
  • 后端：FastAPI 异步后端 + SQLAlchemy + MySQL + 一套"Agent/Service/Repository"分层
  • 数据层：MySQL 为主，配有脚本和文档来自动化初始化与故障排查
  • AI/Agent 能力：后端内置多种"Agent"用于测试用例生成、需求分析、文档解析、RAG 检索等

---

后端架构（backend）

1. 技术栈

• Web 框架：FastAPI（ASGI，异步）
• 数据库访问：SQLAlchemy + aiomysql（异步 MySQL 驱动）
• 配置管理：pydantic-settings（.env 环境变量）, 参见 app/core/config.py
• 日志：loguru + 自定义 logging.py/logging_safe.py
• 脚本工具：大量 scripts/*.sh、scripts/*.py 用于 MySQL 初始化、修复、测试等

2. 目录分层

后端的主体在 backend/app 下，大致分层如下：

• app/api/v1

  • api.py：聚合所有 v1 版本 API 路由
  • endpoints/*.py：领域化的路由模块，例如：
    • test_case_generator.py：测试用例生成相关接口
    • test_case_management.py：测试用例管理与统计接口
    • projects.py、requirements.py、mindmaps.py 等：项目、需求、思维导图等业务接口
    • sessions.py、agent_logs.py、system.py 等：会话、日志、系统级接口
  • 设计特点：每个业务域一个 endpoints 文件，保持路由层职责单一（接收请求、调用 service、返回响应）。

• app/core

  • config.py：集中管理应用配置（端口、数据库 URL、Redis、AI Key 等），通过 Settings 类 + .env 加载。
  • llms.py：封装大模型调用（如 DeepSeek、Qwen、Volcengine Ark 等）。
  • agents/*：Agent 基础抽象、调度器（agent_selector 等），用于决定调用哪种 Agent 处理任务。
  • enums.py / enum_utils.py / types.py：通用枚举、类型定义。
  • 设计思想：把"系统级横切关注点"（配置、日志、模型调用、Agent 抽象）统一收口到 core，避免散落到业务代码里。

• app/database

  • models/*.py：ORM 模型，对应数据库表（test_case.py、test_point.py、requirement.py 等等）。
  • repositories/*.py：仓储层，封装对模型的 CRUD 和复杂查询逻辑，例如：
    • test_case_repository.py
    • requirement_repository.py
    • page_analysis_repository.py
  • connection.py / aws_connection.py：创建与本地 / AWS RDS MySQL 的连接引擎。
  • 设计思想：Repository 模式，把直接操作数据库的逻辑从业务 Service 中剥离，让上层只关心业务语义（如"获取某项目的用例列表"），不关心具体 SQL / ORM 细节。

• app/services

  • services/data/*.py：面向业务的"服务层"，例如：
    • test_case_service.py：围绕测试用例的增删改查、统计等业务逻辑。
    • requirement_service.py、mindmap_service.py、session_service.py 等。
  • services/core/*.py：
    • file_processor.py：文件处理核心逻辑（上传的文档/Excel/截图等解析）。
    • session_manager.py：会话生命周期管理。
    • agent_selector.py：根据场景选择合适的 Agent。
  • 设计思想：Service 层负责"业务流程编排"，调用 Repository + Agents + 外部服务，把复杂流程封装成清晰的接口供 API 层调用。

• app/agents

  • agents/test_case/*.py：领域 Agent，例如：
    • 需求分析 Agent、测试点抽取 Agent、用例生成 Agent、Excel 导出 Agent、视频/图片分析 Agent、数据库结构解析 Agent、API Spec 解析 Agent、RAG 检索 Agent 等。
  • agents/database/*.py：专门负责把 Agent 生成结果写入数据库的 Agent（如 test_case_saver_agent、test_point_saver_agent）。
  • 设计思想：把"AI 相关的复杂流程"打包为一个个 Agent，对外暴露清晰的调用接口，便于组合和演进；同时将"生成"和"入库"职责拆开（test_case_agent vs saver_agent），更易调试和回放。

• app/utils

  • 通用工具：文件解析 (file_parser.py)、路径工具 (path_utils.py)、会话持久化 (session_db_utils.py)、RAG/Agent 日志工具等。
  • 设计思想：业务无关的通用能力抽到 utils，减少重复。

• 其他关键点

  • main.py / run.py：应用启动入口（挂载 FastAPI、加载路由、中间件、静态文件等）。
  • migrations/：数据库迁移（应是 Alembic 或类似工具）。
  • scripts/ + docs/：
    • 成体系的 MySQL 初始化、修复、迁移、连通性测试脚本（final_mysql_solution.sh、fix_mysql_connection.py 等）。
    • 附带详细的 MySQL 故障排查文档和最佳实践说明。

---

前端架构（frontend）

1. 技术栈

• 构建工具：Vite
• 框架: Vue 3（组合式 API）
• 路由：Vue Router
• 状态管理：Pinia
• UI & 可视化：
  • Element Plus
  • Ant Design X
  • ECharts、D3
  • simple-mind-map（思维导图组件）
• 其他：
  • Axios（调用后端 API）
  • dayjs（时间处理）
  • xlsx、file-saver（导出 Excel / 文件下载）
  • Mermaid（渲染流程图/时序图等）

2. 目录结构（frontend/src）

• main.ts：应用入口，挂载根组件 App.vue，注册路由、Pinia、全局样式等。
• router/：路由配置和路由守卫（菜单、页面跳转、权限控制）。
• stores/：Pinia 状态管理（用户状态、项目/会话状态、页面状态等）。
• views/：按业务拆分的页面组件，例如测试用例管理页、生成会话页、知识库页面等。
• components/：可复用的 UI 组件（表格、表单、对话框、图表等）。
• api/：封装对后端的 HTTP 请求（按业务模块拆分函数，统一错误处理/拦截器）。
• layout/：全局布局（侧边栏、顶部导航、主内容区域），构建完整"平台"界面。
• styles/：全局样式、主题变量等。
• utils/：通用工具函数（如请求封装、缓存工具、格式化函数等）。
• types/：TypeScript 类型定义，约束接口请求/响应结构，保证前端类型安全。

设计特点：

• 典型的 模块化 SPA 架构：layout + router + views + components + stores。
• API 调用集中到 api 目录，方便统一维护后端接口变更。
• 利用 auto-imports.d.ts、components.d.ts 自动导入，减少模板和脚本中的重复引入。

---

典型调用链路示意

以"生成测试用例并统计"为例，大致链路是：

1. 前端：
   views 页面通过 api/testCase.ts 调用对应接口（例如 GET /api/v1/test-cases/stats）。
2. 后端 API 层：
   app/api/v1/endpoints/test_case_management.py 中对应的路由接到请求。
3. 服务层：
   路由调用 test_case_service 中的方法，做参数校验、业务组合。
4. Agent 层（如涉及 AI 生成）：
   Service 调用某个/多个 agents/test_case/*，完成需求分析、测试点提取、用例生成等。
5. Repository + 数据库层：
   保存或查询数据时，通过 repositories/*.py 操作 models/*.py，由 SQLAlchemy + aiomysql 与 MySQL 交互。
6. 返回结果：
   Service 整理结果数据，API 层序列化后返回给前端，前端再通过 ECharts 等组件做可视化展示。

---

架构设计的几个关键点总结

• 前后端完全解耦：HTTP API 作为唯一通信方式，前后端可以独立部署。
• 清晰的分层：
  • API（Controller）层：只负责"收请求 / 回响应"。
  • Service 层：业务流程编排。
  • Repository 层：数据访问抽象。
  • Model 层：数据库结构映射。
  • Agent 层：AI 能力模块化封装。
• 可扩展性：
  • 新增一个业务域（比如"性能测试"）→ 新增一组 endpoints + service + repository + models (+ agents)，不影响已有模块。
  • 新增一种 Agent 或更换模型提供方 → 改 agents 与 llms 层即可。
• 运维友好：
  • 专门的 scripts/ + docs/ 解决 MySQL 布署与故障排查问题。
  • .env + pydantic-settings 管理配置，方便多环境切换。