baozaotumao2025
33 lines
3.7 KiB
Markdown
33 lines
3.7 KiB
Markdown
# API 映射
|
||
|
||
所有路径相对 `VITE_API_BASE_URL`，默认为 `/api/v1` 服务。除登录外，请求都携带 Bearer token。
|
||
|
||
| 领域 | 前端操作 | 后端端点 |
|
||
| --- | --- | --- |
|
||
| 认证 | 登录、续约、当前用户、修改密码、退出 | `POST /auth/login`, `POST /auth/refresh`, `GET /auth/me`, `PATCH /auth/password`, `POST /auth/logout` |
|
||
| 用户 | 列表、创建、启停、重置密码、删除 | `GET/POST /auth/users`, `PATCH/DELETE /auth/users/{id}`, `PATCH /auth/users/{id}/password` |
|
||
| 提供商 | 列表、详情、创建、修改、删除 | `GET/POST /providers`, `GET/PATCH/DELETE /providers/{id}` |
|
||
| 提供商 | 连通检查、模型发现 | `POST /providers/{id}/check`, `GET /providers/{id}/models` |
|
||
| 运行 | 列表、创建、详情、取消、删除 | `GET/POST /runs`, `GET/PATCH/DELETE /runs/{id}` |
|
||
| 运行 | 恢复、重试错误、单条重试、逐条结果 | `POST /runs/{id}/resume`, `POST /runs/{id}/retry-errors`, `POST /runs/{id}/results/{execution_id}/retry`, `GET /runs/{id}/results` |
|
||
| 报告 | 列表、详情 | `GET /reports`, `GET /reports/{run_id}` |
|
||
| 系统 | 健康状态 | `GET /health` |
|
||
|
||
## 数据规则
|
||
|
||
- API 响应必须通过 Zod 校验，否则转为 `INVALID_RESPONSE`，不把不可信数据交给 UI。
|
||
- 运行详情必须满足 `processed_count = completed_count + error_count`；`error_count` 仅统计执行异常，不包含 `verdict = fail`；终态必须有 `poll_after_seconds = 0`。
|
||
- 逐条结果使用 `execution_status`（`completed | error`）表示调用是否完成，使用可空 `verdict`（`pass | fail | needs_human_review | judge_format_error | null`）表示仲裁结论；前端不读取旧 `status`。
|
||
- 逐条结果的执行 ID 搜索直接使用 `GET /runs/{id}/results` 已返回的 `execution_id` 在 UI 过滤，不新增请求参数或后端端点。
|
||
- 报告的 `summary.execution_statuses` 与 `summary.verdicts` 分开统计；`by_mode` 下也分别包含 `execution_statuses` 和 `verdicts`。
|
||
- `POST /runs/{id}/retry-errors` 只重试 `execution_status = error`，不重试任何仲裁结论。
|
||
- `POST /runs/{id}/results/{execution_id}/retry` 无请求体，沿用原 Run 的测试范围和自动仲裁配置，并以相同 `execution_id` 替换旧结果；仅 `completed / completed_with_errors` 状态允许提交。
|
||
- `POST /runs/{id}/resume` 无请求体，返回 `skipped_count`；`POST /runs/{id}/retry-errors` 无请求体，返回 `retry_count`。两者返回 202 后必须重新获取运行详情，不能将 POST 响应视为执行完成；409 时也重新获取详情。
|
||
- 单条重试返回 202 后按运行详情的 `poll_after_seconds`（缺省 2 秒）轮询，终态后重新获取结果。重跑期间旧结果可能暂时不存在，UI 保留“重新执行中”状态；404 刷新结果，409 刷新 Run，网络错误或 5xx 先刷新 Run，避免不确定是否受理时重复提交。
|
||
- `POST /runs` 总是携带新的 UUID v4 `Idempotency-Key`；HTTPS 优先使用原生 `crypto.randomUUID()`，HTTP 环境使用 `crypto.getRandomValues()` 兼容生成，后端契约不变。
|
||
- 登录和续约都会原子替换 access/refresh token 及两个过期时间。
|
||
- access token 剩余不超过 30 分钟且用户最近 30 分钟有真实操作时，`POST /auth/refresh` 携带同一共享生成器产生的 UUID v4 `Idempotency-Key`。
|
||
- 网络错误和 5xx 最多尝试 3 次，且一直复用原 refresh token 和原 key；409 保留凭据并等待 `refresh_after`。
|
||
- 普通业务请求首次 401 共享 single-flight 续约，成功后仅重放一次；只有 refresh 本身返回 401 才清除会话。
|
||
- HTTP 204 按无响应体处理；403/404/409/422/502 映射为可操作的用户消息。
|