# testflow

**Repository Path**: zqsssss/testflow

## Basic Information

- **Project Name**: testflow
- **Description**: 测试用例管理平台
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TestFlow 测试管理平台

TestFlow 是一个现代化的全栈测试管理平台，旨在为测试团队提供高效的项目管理、用例管理、缺陷跟踪以及 AI 辅助测试能力。

## 核心特性

## 快速开始

### 系统要求

**最低配置：**
- CPU: 双核
- 内存: 4GB
- 硬盘: 1GB 可用空间
- 操作系统: Windows 10+, macOS 10.15+, Ubuntu 20.04+

**软件依赖：**
- Python 3.11+ (推荐 3.11 或 3.12)
- Node.js 20+
- MySQL 8.0+
- Docker Desktop (用于 Redis，推荐)
- Git

### 本地开发环境搭建

> 💡 **启动顺序**: MySQL → Redis (可选) → 后端 → 前端
*   **缺陷跟踪**: 完整的缺陷生命周期管理，支持缺陷状态流转、指派与统计。
*   **AI 辅助**: 集成 Google Gemini AI，支持一键生成测试用例，提升编写效率。
**方案 3：使用 Docker（推荐，最简单）**

1. 启动 Docker Desktop（如未安装，请访问 [Docker 官网](https://www.docker.com/products/docker-desktop)）
2. 运行 Redis 容器：
*   **全栈架构**: 采用 React + FastAPI + MySQL + Redis 的主流技术栈，性能优异且易于扩展。
# 拉取并运行 Redis 7 Alpine 镜像
docker run -d -p 6379:6379 --name testflow-redis redis:7-alpine

# 验证 Redis 运行
docker exec testflow-redis redis-cli ping
# 返回 PONG 表示成功
## 技术栈

**Docker Redis 管理命令：**
```bash
# 查看容器状态
docker ps -a --filter name=testflow-redis

# 停止 Redis
docker stop testflow-redis

# 启动 Redis
docker start testflow-redis

# 重启 Redis
docker restart testflow-redis

# 查看日志
docker logs testflow-redis

# 删除容器（需要先停止）
docker stop testflow-redis
docker rm testflow-redis
```

### 前端 (Frontend)
*   **框架**: React 19
*   **构建工具**: Vite 6
*   **语言**: TypeScript
*   **路由**: React Router 7
*   **UI 组件**: Lucide React (图标)
启动成功时，控制台会显示：
```
==================================================
TestFlow Backend Starting...
==================================================
[Database] 数据库表已初始化
[WebSocket] Redis Pub/Sub 已连接  # Redis 已连接
# 或
[WebSocket] Redis 连接失败，使用单机模式  # Redis 未连接（仍可正常使用）
[Server] 服务启动于 http://0.0.0.0:8000
[API Docs] Swagger UI: http://localhost:8000/docs
==================================================
INFO:     Application startup complete.
```

*   **AI 集成**: Google GenAI SDK

### 后端 (Backend)

如果你已经完成环境配置，使用以下命令快速启动：

```bash
# 1. 启动 Redis（可选，推荐使用 Docker）
docker start testflow-redis
# 如果容器不存在，使用以下命令创建：
# docker run -d -p 6379:6379 --name testflow-redis redis:7-alpine

# 2. 启动后端（在 backend 目录）
cd backend
venv\Scripts\activate     # Windows
# source venv/bin/activate  # Linux/Mac
python run.py

# 3. 启动前端（在项目根目录，新终端）
cd ..
npm run dev
```

**访问地址：**
- 前端: http://localhost:3000 （默认账号: `admin` / `admin123`）
- 后端: http://localhost:8000
- API 文档: http://localhost:8000/docs

---

### 容器化部署 (Docker Compose)
*   **框架**: FastAPI (Python 3.11+)
*   **服务器**: Uvicorn
## 故障排查

### 后端问题

**问题 1: `ModuleNotFoundError: No module named 'uvicorn'`**
- 原因：未激活虚拟环境
- 解决：运行 `venv\Scripts\activate` (Windows) 或 `source venv/bin/activate` (Linux/Mac)

**问题 2: `pydantic-core` 编译失败，需要 Rust**
- 原因：Python 版本太新（如 3.14），没有预编译包
- 解决方案 1（推荐）：使用 Python 3.11 或 3.12
- 解决方案 2：先运行 `pip install "pydantic>=2.10" --only-binary :all:`

**问题 3: Redis 连接失败**
- 原因：Redis 服务未启动
- 影响：降级为单机模式，WebSocket 实时推送不可用，其他功能正常
- 解决：按照文档安装并启动 Redis（推荐使用 Docker）

**问题 4: 数据库连接失败**
- 检查 MySQL 服务是否运行
- 检查 `.env` 文件中的 `DATABASE_URL` 配置
- 确认数据库 `testflow` 已创建

### 前端问题

**问题 1: 端口 3000 被占用**
- 解决：修改 `vite.config.ts` 中的端口配置，或关闭占用端口的程序

**问题 2: 无法连接后端**
- 检查后端服务是否正常运行（访问 http://localhost:8000/health）
- 检查 `.env.local` 中的 `VITE_API_BASE_URL` 配置
- 检查浏览器控制台的网络请求错误

**问题 3: 登录失败**
- 确认使用默认账号：`admin` / `admin123`
- 检查后端日志，确认数据库初始化成功
- 尝试重新运行 `python -m scripts.init_db`

### Docker 问题

**问题 1: Docker Desktop 未启动**
- 错误信息：`cannot connect to the docker daemon`
- 解决：手动启动 Docker Desktop，等待 20-30 秒后重试

**问题 2: Redis 容器无法启动**
- 检查端口 6379 是否被占用：`netstat -ano | findstr 6379` (Windows)
- 删除旧容器：`docker rm -f testflow-redis`
- 重新创建容器

---

## 性能优化建议

### 生产环境部署

1. **修改默认密钥和密码**
    ```env
    JWT_SECRET_KEY=使用强随机字符串
    DATABASE_URL=使用复杂密码
    ```

2. **启用 Redis**
    - 提升 WebSocket 性能
    - 支持多实例部署

3. **配置 Nginx 反向代理**
    - 启用 HTTPS
    - 配置请求限流
    - 启用 Gzip 压缩

4. **数据库优化**
    - 定期备份数据
    - 添加适当的索引
    - 监控慢查询

### 开发最佳实践

1. **使用虚拟环境**
    - 隔离项目依赖
    - 避免版本冲突

2. **启用热重载**
    - 后端：`--reload` 参数
    - 前端：Vite 自动支持

3. **查看 API 文档**
    - Swagger UI: http://localhost:8000/docs
    - 支持在线测试 API

4. **使用浏览器开发者工具**
    - Network 标签查看 API 请求
    - Console 标签查看错误信息

---

*   **数据库 ORM**: SQLAlchemy
*   **数据验证**: Pydantic
*   **认证**: JWT (JSON Web Tokens)
*   **AI 集成**: Google Generative AI

### 基础设施 (Infrastructure)
*   **数据库**: MySQL 8.0
*   **缓存**: Redis 7
*   **容器化**: Docker & Docker Compose
*   **反向代理**: Nginx

## 界面预览

![项目截图 1](./testflow/img/image1.png)
![项目截图 2](./testflow/img/image2.png)
![项目截图 3](./testflow/img/image3.png)
![项目截图 4](./testflow/img/image4.png)
![项目截图 5](./testflow/img/image5.png)
![项目截图 6](./testflow/img/image6.png)

## 快速开始

### 本地开发环境搭建

#### 1. 后端启动

**前置依赖：** Python 3.11+、MySQL 8+、Redis 7+（可选）

> 💡 **Python 版本说明**: 推荐使用 Python 3.11 或 3.12 以获得最佳兼容性。Python 3.14 等较新版本虽然可用，但部分依赖包可能需要从源码编译。

> 💡 **Redis 说明**: Redis 用于 WebSocket 消息分发。**如果未安装，应用会自动降级为单机模式**，不影响核心功能使用。

**步骤 1：确保数据库运行（Redis 可选）**
```bash
# 必需：确保 MySQL 服务已启动（默认端口 3306）
# 可选：确保 Redis 服务已启动（默认端口 6379）
```
> 💡 **Redis 说明**: Redis 用于 WebSocket 消息分发。如果未启动，应用会自动降级为单机模式，基础功能不受影响。

**步骤 2：进入后端目录**
```bash
cd backend
```
> ⚠️ **重要**: 后续所有步骤都需要在 `backend` 目录下执行

**步骤 3：配置环境变量**

复制环境变量模板文件：
```bash
# Windows PowerShell
copy env.example .env

# Linux/Mac
cp env.example .env
```

编辑 `.env` 文件，修改以下关键配置：
```env
# 数据库配置（根据实际情况修改）
DATABASE_URL=mysql+pymysql://root:your_password@localhost:3306/testflow

# Redis 配置
REDIS_URL=redis://localhost:6379/0

# JWT 密钥（生产环境请使用强密码）
JWT_SECRET_KEY=your-secret-key-change-in-production

# AI 功能（可选）
GOOGLE_API_KEY=your_gemini_api_key
```

**步骤 4：创建并激活虚拟环境（推荐）**
```bash
# Windows - 创建虚拟环境
python -m venv venv

# Windows - 激活虚拟环境（每次打开新终端都需要执行）
venv\Scripts\activate

# Linux/Mac - 创建虚拟环境
python -m venv venv

# Linux/Mac - 激活虚拟环境
source venv/bin/activate
```
> ⚠️ **重要**: 激活后，命令提示符前会显示 `(venv)`，表示当前在虚拟环境中

**步骤 5：安装依赖**
```bash
# 确保你在 backend 目录下
# 先升级 pip（推荐）
python -m pip install --upgrade pip

# 安装所有依赖
pip install -r requirements.txt
```
> 💡 如果出现 "No such file" 错误，请确认当前在 backend 目录
> 
> ⚠️ **遇到编译错误？** 如果遇到 `pydantic-core` 需要 Rust 编译器的错误：
> - 方案 1：使用 Python 3.11 或 3.12（推荐，有预编译包）
> - 方案 2：先运行 `pip install "pydantic>=2.10" --only-binary :all:` 然后再安装其他依赖

**步骤 6：初始化数据库**
```bash
# 创建数据库表结构和初始数据
python -m scripts.init_db
```

**步骤 7：启动后端服务**
```bash
# ⚠️ 重要：确保已激活虚拟环境
# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

# 然后启动服务（开发模式，支持热重载）
python run.py

# 或使用 uvicorn 命令
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
> ⚠️ **注意**: 必须先激活虚拟环境才能运行，否则会提示找不到模块

**验证启动成功：**
*   后端 API: `http://localhost:8000`
*   Swagger 文档: `http://localhost:8000/docs`
*   健康检查: `http://localhost:8000/health`

**常见启动问题：**
*   ❌ `ModuleNotFoundError: No module named 'uvicorn'` → 需要先激活虚拟环境
*   ⚠️ `Redis 连接失败` → Redis 未启动，应用会降级为单机模式（可继续使用）
*   ❌ 数据库连接失败 → 检查 MySQL 服务和 `.env` 中的数据库配置

---

**如何安装 Redis（可选）：**

<details>
<summary>📦 Windows 安装 Redis（点击展开）</summary>

**方案 1：使用 Memurai（推荐）**
1. 访问 [Memurai 官网](https://www.memurai.com/get-memurai) 下载 Windows 版 Redis
2. 安装并启动 Memurai 服务

**方案 2：使用 WSL2**
```bash
# 在 WSL2 中安装
sudo apt-get update
sudo apt-get install redis-server

# 启动 Redis
sudo service redis-server start
```

**方案 3：使用 Docker**
```bash
docker run -d -p 6379:6379 --name redis redis:7-alpine
```

</details>

<details>
<summary>📦 Linux/Mac 安装 Redis（点击展开）</summary>

**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server
```

**macOS (使用 Homebrew):**
```bash
brew install redis
brew services start redis
```

**验证 Redis 运行：**
```bash
redis-cli ping
# 返回 PONG 表示成功
```

</details>

---

#### 2. 前端启动

**前置依赖：** Node.js 20+

**步骤 1：返回项目根目录**
```bash
# 如果在 backend 目录，先返回根目录
cd ..
```

**步骤 2：安装依赖**
```bash
npm install
```

**步骤 3：配置环境变量（可选）**

如需自定义后端 API 地址，创建 `.env.local` 文件：
```env
# 后端 API 地址（默认值，可不配置）
VITE_API_BASE_URL=http://localhost:8000/api/v1

# 仅当前端直连 Gemini 时配置（不推荐，建议通过后端代理）
# GEMINI_API_KEY=YOUR_GEMINI_KEY
```

**步骤 4：启动开发服务器**
```bash
npm run dev
```

**验证启动成功：**
*   前端应用: `http://localhost:3000`
*   默认管理员账号: `admin` / `admin123`

**常见问题：**
*   如果提示端口被占用，可修改 `vite.config.ts` 中的端口配置
*   如果无法连接后端，请检查 `VITE_API_BASE_URL` 配置和后端服务状态

### 容器化部署 (Docker Compose)

推荐使用 Docker Compose 进行一键部署，适合测试或生产环境。

**前置依赖：** Docker Desktop (包含 Docker Compose v2)

1.  **配置环境变量**：
    确保已设置必要的环境变量，特别是 `JWT_SECRET_KEY`。可以在 `backend/.env` 中设置，或者在运行 docker compose 命令时传入。

2.  **一键启动**：
    在项目根目录下执行：
    ```bash
    docker compose -f ./backend/docker-compose.yml up -d --build
    ```

3.  **访问服务**：
    *   **前端应用**: `http://localhost:3000`
    *   **后端 API 文档**: `http://localhost:8000/docs`

4.  **端口映射说明**：
    *   MySQL: `3307` (宿主机) -> `3306` (容器)
    *   Redis: `6380` (宿主机) -> `6379` (容器)
    *   Backend: `8000` (宿主机) -> `8000` (容器)
    *   Frontend: `3000` (宿主机) -> `80` (容器，经 Nginx 转发)

## 目录结构

```
testflow/
├── backend/                # 后端代码
│   ├── app/                # 应用核心逻辑
│   │   ├── api/            # API 路由
│   │   ├── core/           # 核心配置与工具
│   │   ├── models/         # 数据库模型
│   │   ├── schemas/        # Pydantic 数据模型
│   │   └── services/       # 业务逻辑服务
│   ├── scripts/            # 脚本文件 (如数据库初始化)
│   ├── Dockerfile          # 后端 Docker 构建文件
│   ├── docker-compose.yml  # Docker Compose 配置文件
│   └── requirements.txt    # Python 依赖
├── src/                    # 前端代码 (假设在根目录或 src 目录下，根据实际情况调整)
│   ├── components/         # React 组件
│   ├── context/            # Context API
│   ├── services/           # API 请求服务
│   └── ...
├── Dockerfile.frontend     # 前端 Docker 构建文件
├── nginx.conf              # Nginx 配置文件
├── package.json            # 前端依赖配置
└── vite.config.ts          # Vite 配置文件
```

## 环境变量详解

### 前端
| 变量名 | 说明 | 默认值 |
| :--- | :--- | :--- |
| `VITE_API_BASE_URL` | 后端 API 接口地址 | `http://localhost:8000/api/v1` |
| `GEMINI_API_KEY` | Gemini API Key (前端直连模式) | - |

### 后端
| 变量名 | 说明 | 示例 |
| :--- | :--- | :--- |
| `DATABASE_URL` | MySQL 数据库连接串 | `mysql+pymysql://root:root@mysql:3306/testflow` |
| `REDIS_URL` | Redis 连接串 | `redis://redis:6379/0` |
| `JWT_SECRET_KEY` | JWT 签名密钥 (生产环境务必修改) | `your-secret-key` |
| `GOOGLE_API_KEY` | Google Gemini API Key | - |
| `CORS_ORIGINS` | 允许跨域的源 (逗号分隔) | `http://localhost:3000` |
| `DEBUG` | 调试模式开关 | `false` |

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进 TestFlow！

1.  Fork 本仓库
2.  创建特性分支 (`git checkout -b feature/AmazingFeature`)
3.  提交更改 (`git commit -m 'Add some AmazingFeature'`)
4.  推送到分支 (`git push origin feature/AmazingFeature`)
5.  提交 Pull Request

## 许可证

[MIT](LICENSE)