TBC/docs/API.md
D-Robotics 637b1026df release: v1.2.0 - 安全加固与性能优化
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
2026-07-16 15:00:05 +08:00

309 lines
6.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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)。