ai-safety-console-web/docs/api-contracts.md

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 /runs/{id}/export
报告	列表、详情	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 过滤，不新增请求参数或后端端点。
• GET /runs/{id}/export 仅允许终态 Run，返回 text/markdown 文件而非 JSON；可组合传入 execution_status=completed|error 与 verdict=pass|fail|needs_human_review|judge_format_error|none，其中 none 表示未评价。前端复用结果筛选器，但执行 ID 搜索不参与导出。
• 报告的 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 按无响应体处理；Markdown 成功响应按 Blob 读取；错误响应仍按 JSON 归一化。403/404/409/422/502 映射为可操作的用户消息。