Security: - 添加 API 认证中间件 (PLATFORM_API_TOKEN Bearer Token) - SSRF 防护: 校验 git URL scheme + 过滤内网 IP - 路径遍历修复: module 参数添加 is_relative_to 校验 - 异常信息泄露修复: 统一错误处理不返回内部信息 - API Key 不持久化到数据库 - 硬编码 SSH Key 移至环境变量 - CORS 生产环境校验 Rate Limiting: - 新增内存滑动窗口速率限制 (6个POST端点) Performance: - ThreadPoolExecutor(max_workers=4) 限制并发 - 任务超时 _enforce_proc_timeout (默认3600s) - JSON 原子写入 tempfile+os.replace - 日志轮转 RotatingFileHandler - httpx 连接池配置 - 随机名改用 uuid4 - 前端 Error Boundary - 前端统一 EventSource 使用 Docs: - 更新 .env.example, CHANGELOG, API.md, CONFIG.md, AGENTS.md - .gitignore 添加 .venv/ 和 backend/db.json
309 lines
6.8 KiB
Markdown
309 lines
6.8 KiB
Markdown
# TestAgent API 文档
|
||
|
||
Base URL: `http://localhost:5002`
|
||
|
||
## 认证
|
||
|
||
当设置了 `PLATFORM_API_TOKEN` 环境变量时,所有 API 请求(`/api/health` 除外)必须在请求头中携带 Bearer Token:
|
||
|
||
```
|
||
Authorization: Bearer <your-token>
|
||
```
|
||
|
||
未设置 `PLATFORM_API_TOKEN` 时认证关闭(仅开发模式推荐)。
|
||
|
||
## 速率限制
|
||
|
||
以下 POST 端点受速率限制保护(按客户端 IP,滑动窗口):
|
||
|
||
| 端点 | 限制 |
|
||
|------|------|
|
||
| `POST /api/repos` | 10 次/60 秒 |
|
||
| `POST /api/repos/compare` | 10 次/60 秒 |
|
||
| `POST /api/repos/<id>/full` | 5 次/60 秒 |
|
||
| `POST /api/repos/check-ui` | 5 次/60 秒 |
|
||
| `POST /api/repos/fix-ui` | 5 次/60 秒 |
|
||
| `POST /api/tasks` | 10 次/60 秒 |
|
||
|
||
超过限制返回 `429 Too Many Requests`。
|
||
|
||
## SSRF 防护
|
||
|
||
所有接受 Git URL 的端点(`POST /api/repos`、`GET /api/repos/branches`、`POST /api/repos/compare`、`POST /api/repos/check-ui`、`POST /api/repos/fix-ui`、`POST /api/repos/<id>/full`)均执行 URL 校验:
|
||
- 仅允许 HTTPS 协议(拒绝 `git://`、`ssh://`、`git@` 等)
|
||
- 拒绝内网 IP 地址(10.x / 172.16-31.x / 192.168.x / 169.254.x / 127.x / ::1 / fc00:: / fe80::)
|
||
|
||
---
|
||
|
||
## 系统
|
||
|
||
### GET /api/health
|
||
健康检查。
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"version": "1.0.0",
|
||
"tasks_count": 10,
|
||
"reports_count": 8,
|
||
"repos_count": 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 控制台
|
||
|
||
### GET /api/dashboard/stats
|
||
获取控制台统计概览。
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"tasks": { "total": 10, "pass": 5, "fail": 3, "running": 2, "pass_rate": 50.0 },
|
||
"reports": { "total": 8, "pass": 5, "pass_rate": 62.5 },
|
||
"repos": { "total": 0 },
|
||
"existing_tests": { "modules": 35 }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 仓库分支
|
||
|
||
### GET /api/repos/branches?url=<repo-url>
|
||
获取远程仓库所有分支列表,自动识别最新提交分支。
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"branches": [{"name": "dev", "commit": "8c45c92"}, {"name": "main", "commit": "6f6053f"}],
|
||
"total": 15,
|
||
"default": "main",
|
||
"latest": "dev"
|
||
}
|
||
```
|
||
|
||
### POST /api/repos/compare
|
||
对比两个分支的变更文件列表。
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"url": "https://github.com/user/repo.git",
|
||
"base": "main",
|
||
"compare": "dev"
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"base": "main",
|
||
"compare": "dev",
|
||
"changed_files": ["agent/llm_client.py", "backend/app.py"],
|
||
"total_changes": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 仓库管理
|
||
|
||
### GET /api/repos
|
||
获取所有已扫描仓库列表。
|
||
|
||
### POST /api/repos
|
||
扫描新仓库(clone + AST 分析 + DDD 建模)。
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"url": "https://github.com/user/repo.git",
|
||
"branch": "main"
|
||
}
|
||
```
|
||
|
||
> **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。
|
||
|
||
### DELETE /api/repos/<repo_id>
|
||
删除仓库。
|
||
|
||
### POST /api/repos/<repo_id>/analyze
|
||
DDD 领域分析。
|
||
|
||
### POST /api/repos/<repo_id>/generate
|
||
生成测试用例。
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"test_types": ["smoke", "unit", "integration"]
|
||
}
|
||
```
|
||
|
||
> **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。
|
||
|
||
### POST /api/repos/<repo_id>/diff
|
||
精确回归(仅对 git diff 变更文件生成测试)。
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"against": "HEAD~1"
|
||
}
|
||
```
|
||
|
||
> **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。
|
||
|
||
### POST /api/repos/<repo_id>/full
|
||
全流程(扫描 + 分析 + 生成)。
|
||
|
||
### POST /api/repos/check-ui
|
||
UI 变更检查(克隆前端仓库,比对 Robogo 脚本中的 UI 选择器)。
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"url": "https://gitea.d-robotics.cc/d-cloud/d_cloud_artificer_frontend",
|
||
"branch": "main"
|
||
}
|
||
```
|
||
|
||
> **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。
|
||
|
||
### POST /api/repos/fix-ui
|
||
UI 自动修复(检测 + 备份 + LLM 修复 + 覆盖原文件 + 重新测试验证)。
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"url": "https://gitea.d-robotics.cc/d-cloud/d_cloud_artificer_frontend",
|
||
"branch": "main"
|
||
}
|
||
```
|
||
|
||
> **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。
|
||
|
||
**流程:** 克隆前端 → 提取选择器 → 比对 → 备份 → LLM 分批修复 → 覆盖 → 运行验证
|
||
|
||
---
|
||
|
||
## 任务管理
|
||
|
||
### GET /api/tasks
|
||
获取所有任务列表。支持 `?product=` 过滤。
|
||
|
||
### POST /api/tasks
|
||
创建并启动任务。
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"name": "任务名称",
|
||
"task_type": "run_existing",
|
||
"platform": "dcloud",
|
||
"module": "data_space",
|
||
"test_marker": "smoke",
|
||
"test_file": "tests/data_space/tests/test_data_space_e2e.py",
|
||
"headless": "false",
|
||
"env": "PROD",
|
||
"scope": "all"
|
||
}
|
||
```
|
||
|
||
> **注意**:`api_key`、`account`、`password` 字段仅用于内存传递,不会持久化到数据库。建议通过 `.env` 环境变量配置凭据。
|
||
|
||
**任务类型 (task_type):**
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `scan` | 扫描仓库 |
|
||
| `analyze` | DDD 分析 |
|
||
| `generate` | 生成测试 |
|
||
| `repo_full` | 全流程 |
|
||
| `diff` | 精确回归 |
|
||
| `run_existing` | 运行已有用例 |
|
||
| `ui_check` | UI 变更检查 |
|
||
|
||
### DELETE /api/tasks/<tid>
|
||
删除任务。
|
||
|
||
### POST /api/tasks/<tid>/stop
|
||
停止运行中的任务(发送 SIGKILL)。
|
||
|
||
### GET /api/tasks/<tid>/logs
|
||
SSE 日志流。实时推送任务执行日志。
|
||
|
||
**Event 格式:**
|
||
```
|
||
data: {"ts":"14:21:11","level":"INFO","msg":"执行: pytest ..."}
|
||
data: {"ts":"14:21:11","level":"SUCCESS","msg":"测试通过"}
|
||
data: {"level":"PING","msg":"","ts":"--:--:--"}
|
||
data: {"level":"DONE","msg":"","ts":"--:--:--"}
|
||
```
|
||
|
||
---
|
||
|
||
## 测试报告
|
||
|
||
### GET /api/reports
|
||
获取所有报告列表。
|
||
|
||
### GET /api/reports/<tid>
|
||
获取报告详情(含日志、结果、截图)。
|
||
|
||
---
|
||
|
||
## 已有用例
|
||
|
||
### GET /api/existing-tests/modules
|
||
获取已有用例模块列表。
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"dcloud": [
|
||
{
|
||
"name": "data_space",
|
||
"path": "tests/data_space",
|
||
"test_files": [
|
||
{
|
||
"name": "test_data_space_e2e.py",
|
||
"tests": [
|
||
{ "name": "test_dataspace_full_pipeline", "readable": "dataspace full pipeline", "doc": "创建→列表→文件→文件夹→删除" }
|
||
],
|
||
"count": 10
|
||
}
|
||
],
|
||
"test_count": 80
|
||
}
|
||
],
|
||
"robogo": [
|
||
{
|
||
"name": "robogo",
|
||
"label": "Robogo 全量巡检",
|
||
"description": "串行运行全部 13 个场景脚本",
|
||
"section": "product"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### GET /api/existing-tests/markers
|
||
获取所有 pytest 标记列表。
|
||
|
||
**响应:**
|
||
```json
|
||
["smoke", "e2e", "api", "ui", "flow", "data_space", "dataspace", ...]
|
||
```
|
||
|
||
---
|
||
|
||
## 静态资源
|
||
|
||
### GET /artifacts/screenshots/<filename>
|
||
获取测试截图。
|
||
|
||
### GET /<path>
|
||
SPA 前端(所有非 API 路径自动 fallback 到 index.html)。 |