first commit

2026-07-18 21:10:39 +08:00
commit 1b90e552a5
91 changed files with 9056 additions and 0 deletions
@@ -0,0 +1,32 @@
+# 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 `Idempotency-Key`。
+- 登录和续约都会原子替换 access/refresh token 及两个过期时间。
+- access token 剩余不超过 30 分钟且用户最近 30 分钟有真实操作时，`POST /auth/refresh` 携带 UUID `Idempotency-Key`。
+- 网络错误和 5xx 最多尝试 3 次，且一直复用原 refresh token 和原 key；409 保留凭据并等待 `refresh_after`。
+- 普通业务请求首次 401 共享 single-flight 续约，成功后仅重放一次；只有 refresh 本身返回 401 才清除会话。
+- HTTP 204 按无响应体处理；403/404/409/422/502 映射为可操作的用户消息。