Hoolinks 自动化测试平台

架构说明

开发模式:

浏览器 :5173  →  Vite Dev Server  →  /api/* proxy  →  FastAPI :8000  →  SQLite / AI Provider

生产一体化模式:

浏览器 :5173  →  FastAPI :5173  →  frontend/dist + /api/*  →  SQLite / AI Provider

开发模式用于本地调试，前后端独立进程；生产一体化模式用于小型单机部署，由后端托管前端构建产物。若部署到公网或生产环境，必须配置 SYSTEM_ACCESS_KEY，因为终端 WebSocket 具备服务器 shell 能力。

---

快速开始

1. 安装并配置 Python 后端

cd backend
uv sync
cp .env.example .env
# 编辑 .env 文件，填入模型供应商 API Key。

2. 安装前端依赖

cd frontend
bun install

方式一：一键脚本启动

在项目根目录下直接运行我们编写的一键管理脚本：

./start.sh

常用命令：

命令	说明
./start.sh dev 或 ./start.sh start	开发启动：后端 8000 + Vite 5173
./start.sh api-start	仅启动后端 API：8000
./start.sh prod-start	生产一体化启动：构建前端，并由 FastAPI 5173 托管
./start.sh stop	停止所有服务并释放端口
./start.sh status	查看当前服务状态

prod-start 会注入 SERVE_FRONTEND=true。开发模式默认 SERVE_FRONTEND=false，避免后端误接管前端路由。

方式二：手动双终端独立启动

• 终端 1：启动 Python 后端

  cd backend
  uv run uvicorn app.main:app --reload --port 8000

• 终端 2：启动前端开发服务器

  cd frontend
  VITE_API_TARGET=http://127.0.0.1:8000 bun run dev -- --port 5173

• 启动后，浏览器访问：http://localhost:5173

---

核心技术栈

分层	技术选型
前端 (frontend)	React 19 + Tailwind CSS v4 + Framer Motion + TypeScript + Vite
后端 (backend)	Python FastAPI + Uvicorn + Pydantic v2 + SQLite3 + Openpyxl
AI 引擎	DeepSeek V4 / 阿里云百炼 / OpenCode Go
构建管理	Bun (前端) + uv (后端)

---

优化后的项目目录结构

auto_test_platform/
├── frontend/               # React 前端工程
│   ├── src/                # React 源代码与组件
│   ├── public/             # 静态公开资源
│   ├── index.html          # 前端 HTML 入口
│   ├── package.json        # 前端依赖配置
│   ├── tsconfig.json       # TypeScript 配置
│   ├── vite.config.ts      # Vite 开发代理及编译配置
│   └── bun.lock            # Bun 依赖锁文件
├── backend/                # Python FastAPI 后端工程
│   ├── ai/                 # AI 处理逻辑 (Client、Prompts、Generator 等)
│   ├── routes/             # API 接口路由 (Generate、Cases、Export、TestData)
│   ├── services/           # 业务服务层 (Excel 导出格式化等)
│   ├── main.py             # 后端服务入口
│   ├── database.py         # SQLite 数据库管理
│   ├── config.py           # Pydantic 环境变量配置
│   ├── models.py           # Pydantic HTTP 请求/响应数据模型
│   ├── data/               # 存放 SQLite 数据库文件 (hootest.db)
│   ├── pyproject.toml      # 后端 UV 项目配置
│   └── uv.lock             # 后端 Python 依赖锁文件
├── .agent/                 # AI 代理技能集 (.skills/)
└── README.md               # 项目主说明文档

---

核心 API 端点

方法	路径	说明
POST	/api/generate	触发 DeepSeek V4 流式生成测试用例并自动写入 SQLite
GET	/api/cases	获取所有用例列表
GET	/api/cases/:id	获取单个用例详情
PATCH	/api/cases/:id	更新用例内容 (状态/执行人/执行结果等)
DELETE	/api/cases/:id	删除用例 (级联删除关联的测试数据)
GET	/api/test-data	查询用例的测试数据
POST	/api/export	导出专业的 Excel 用例清单
GET	/api/health	后端服务健康状态检查