From 265b7e3cc644e5d1891705e3b5d8f0101d1d6ad8 Mon Sep 17 00:00:00 2001 From: wangbo Date: Mon, 11 May 2026 00:43:59 +0800 Subject: [PATCH] =?UTF-8?q?docs(test):=20=E6=B7=BB=E5=8A=A0=20AI=20Gateway?= =?UTF-8?q?=20=E5=9B=9E=E7=8E=AF=E6=B5=8B=E8=AF=95=E4=BB=BB=E5=8A=A1?= =?UTF-8?q?=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 loopback-test-checklist.md 文档 - 包含完整的测试原则和执行环境记录表格 - 提供测试数据准备、任务执行链路、历史记录验证流程 - 添加定价规则、权限控制、运行策略和限流控制测试用例 - 设计验收总表、失败处理记录和清理清单 - 支持 Chat、图像、视频等多模态功能验证 - 集成计费、认证、授权等核心业务逻辑测试 - 提供详细的测试状态跟踪和结果记录模板 --- docs/test/loopback-test-checklist.md | 188 +++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/test/loopback-test-checklist.md diff --git a/docs/test/loopback-test-checklist.md b/docs/test/loopback-test-checklist.md new file mode 100644 index 0000000..9bff7d3 --- /dev/null +++ b/docs/test/loopback-test-checklist.md @@ -0,0 +1,188 @@ +# AI Gateway 回环测试任务清单 + +本文档用于记录 AI Gateway 回环测试的准备、执行、断言和最终结果。执行过程中，所有测试必须跑通；失败项先标记为 `失败`，定位原因并修复后重新执行，通过后再把状态更新为 `成功`，同时写入具体结果。 + +## 1. 测试原则 + +- 测试批次使用统一 `loopbackRunId`，建议格式：`loopback-YYYYMMDD-HHMMSS`。 +- 用户提前创建真实测试平台、真实测试模型和真实平台 KEY；这些真实对象只用于成功链路验证。 +- 内部测试用的用户、用户组、API Key、定价规则、访问规则、运行策略、模拟平台和模拟模型可以由测试过程创建，统一带 `loopbackRunId` 元数据。 +- 成功链路可以走真实客户端，必须拿到真实返回结果；策略链路必须走 `runMode=simulation` 或模拟平台，不提交真实任务。 +- 每个通过项都要写入任务 ID、结果 ID、计费金额、关键事件或错误码等可复查证据。 +- 任一测试失败时，不能只记录失败；必须继续排查到代码、配置或测试数据层面的原因，修复后重跑。 + +## 2. 执行环境记录 + +| 项目 | 值 | +| --- | --- | +| 测试批次 `loopbackRunId` | 待填写 | +| Gateway 地址 | 待填写 | +| 数据库地址 | 待填写 | +| 管理员账号 / token | 待填写 | +| 真实 Chat 模型 | 用户创建后填写 | +| 真实图像测试模型 | `doubao-4.5图像编辑` | +| 真实文生图模型 | `doubao-4.5图像编辑`，若平台配置中该模型不支持文生图则补充用户创建的文生图模型 | +| 真实图生图模型 | `doubao-4.5图像编辑` | +| 真实视频生成模型 | `豆包Seedance-1.5-pro` | +| 视频能力覆盖 | 文生视频、图生视频、首尾帧 | +| 测试源图 | 测试过程自行选择并上传，记录 source image URL | +| 测试 mask 图 | 测试过程自行生成并上传，记录 mask image URL | +| 测试首帧图 | 测试过程自行选择并上传，记录 first frame URL | +| 测试尾帧图 | 测试过程自行选择并上传，记录 last frame URL | +| 真实平台 KEY | 用户创建后填写 | +| 执行人 | 待填写 | +| 开始时间 | 待填写 | +| 结束时间 | 待填写 | + +状态约定：`未执行`、`执行中`、`成功`、`失败`、`阻塞`。 + +## 3. 测试数据准备 + +| ID | 任务 | 接口 / 方式 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | --- | +| SETUP-01 | 确认服务可用 | `GET /healthz`、`GET /readyz` | `healthz.ok=true`，`readyz.ok=true` | 未执行 | 待填写 | +| SETUP-02 | 准备管理员权限 | 本地注册 / 登录，必要时将测试用户提升为 `admin` 或 `manager` | `GET /api/v1/me` 返回 `role` 具备 `manager` 权限 | 未执行 | 待填写 | +| SETUP-03 | 记录用户提供的真实平台、模型和 KEY | `GET /api/v1/platforms`、`GET /api/v1/models` | Chat 模型、`doubao-4.5图像编辑`、`豆包Seedance-1.5-pro` 均已启用，并能被管理员看到 | 未执行 | 待填写 | +| SETUP-04 | 创建内部测试用户组 | `POST /api/v1/user-groups` | 创建 `loopback-allow-group`、`loopback-deny-group`、`loopback-limit-group` | 未执行 | 待填写 | +| SETUP-05 | 创建内部测试 API Key | `POST /api/v1/api-keys` | 至少创建全量 Key、Chat-only Key、受限 Key、禁用验证 Key | 未执行 | 待填写 | +| SETUP-06 | 创建内部定价规则集 | `POST /api/v1/pricing/rule-sets` | 规则覆盖 `text_input`、`text_output`、`image`、`image_edit`、`video` | 未执行 | 待填写 | +| SETUP-07 | 创建内部运行策略集 | `POST /api/v1/runtime/policy-sets` | 规则覆盖重试、错误禁用、降级、RPM、TPM、并发 | 未执行 | 待填写 | +| SETUP-08 | 创建模拟平台和模拟模型 | `POST /api/v1/platforms`、`POST /api/v1/platforms/{platformID}/models` | 模拟平台 `credentials.mode=simulation`，同一模型至少有失败候选和成功候选 | 未执行 | 待填写 | +| SETUP-09 | 准备图像 / 视频测试素材 | 本地选择或生成图片，必要时先上传为网关可访问 URL | source、mask、first frame、last frame 均可被 Gateway 读取；素材不依赖易失效外链 | 未执行 | 待填写 | + +建议内部策略命名： + +- 定价规则集：`loopback-pricing-{loopbackRunId}`。 +- 运行策略集：`loopback-runtime-{loopbackRunId}`。 +- 用户组：`loopback-allow-{loopbackRunId}`、`loopback-deny-{loopbackRunId}`、`loopback-limit-{loopbackRunId}`。 +- 模拟平台：`loopback-sim-fail-{loopbackRunId}`、`loopback-sim-success-{loopbackRunId}`。 + +测试图片选择原则： + +- 使用清晰、非敏感、无版权争议的普通物体或风景图，避免真人肖像和复杂文字。 +- 图生图源图建议使用 1:1 或 4:3 PNG/JPG；mask 使用黑白图，明确覆盖需要编辑的区域。 +- 图生视频和首尾帧建议使用 16:9 横图；首帧和尾帧主体一致，但动作、视角或场景状态有可观察变化。 +- 所有图片先上传或转换成 Gateway 能读取的 URL，再写入本表环境记录。 + +默认素材方案： + +- source image：本地生成或选取一张“明亮桌面上的红色马克杯”普通物体图，用于 `doubao-4.5图像编辑` 图生图和 `豆包Seedance-1.5-pro` 图生视频。 +- mask image：基于 source image 生成黑白 mask，覆盖背景或杯身局部，验证图像编辑是否真正使用参考图和 mask。 +- first frame：16:9 桌面物体静止画面，主体与 source image 保持一致。 +- last frame：同一主体移动位置或状态变化的 16:9 画面，用于首尾帧视频验证过渡是否生效。 + +## 4. 完整任务执行链路 + +每个能力都需要验证同步响应、任务详情、事件流、历史记录和计费字段。非兼容路由预期返回 `202 Accepted` 和 `task`；兼容路由预期直接返回 OpenAI 风格结果。 + +| ID | 能力 | 请求 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | --- | +| TASK-CHAT-01 | Chat 成功 | `POST /api/v1/chat/completions`，真实 Chat 模型 | `task.status=succeeded`，`result.object=chat.completion`，`choices[0].message.content` 非空 | 未执行 | taskId、requestId、content 摘要、charge 待填写 | +| TASK-CHAT-02 | Chat 兼容路由成功 | `POST /v1/chat/completions`，真实 Chat 模型 | HTTP 200，返回 `object=chat.completion`，内容非空 | 未执行 | requestId、content 摘要待填写 | +| TASK-IMAGE-01 | 文生图成功 | `POST /api/v1/images/generations`，模型 `doubao-4.5图像编辑` 或用户补充的文生图模型 | `task.status=succeeded`，`result.id` 非空，`data[0].url` 或文件 URL 可访问 | 未执行 | taskId、image URL、charge 待填写 | +| TASK-IMAGE-02 | 图生图成功 | `POST /api/v1/images/edits`，模型 `doubao-4.5图像编辑`，传入测试源图和 mask | `task.status=succeeded`，`result.id` 非空，`data[0].url` 或文件 URL 可访问 | 未执行 | taskId、source URL、mask URL、image URL、charge 待填写 | +| TASK-VIDEO-01 | 文生视频成功 | `POST /api/v1/videos/generations`，模型 `豆包Seedance-1.5-pro`，仅传 prompt | `task.status=succeeded`，返回可下载或可播放的视频结果，任务事件完整 | 未执行 | taskId、video URL、duration、charge 待填写 | +| TASK-VIDEO-02 | 图生视频成功 | `POST /api/v1/videos/generations`，模型 `豆包Seedance-1.5-pro`，传 prompt 和测试源图 | `task.status=succeeded`，输出视频能体现源图主体，任务事件完整 | 未执行 | taskId、source URL、video URL、duration、charge 待填写 | +| TASK-VIDEO-03 | 首尾帧视频成功 | `POST /api/v1/videos/generations`，模型 `豆包Seedance-1.5-pro`，传 prompt、首帧图、尾帧图 | `task.status=succeeded`，输出视频首尾状态与输入帧一致或可明确对应 | 未执行 | taskId、first frame URL、last frame URL、video URL、duration、charge 待填写 | +| TASK-EVENT-01 | 任务事件保存 | 对上述每个 task 调 `GET /api/v1/tasks/{taskID}/events` | 至少包含 `task.progress` 和 `task.completed`，seq 连续递增 | 未执行 | 每个 task 的事件数量和关键 phase 待填写 | +| TASK-DETAIL-01 | 任务详情查询 | 对上述每个 task 调 `GET /api/v1/tasks/{taskID}` | 返回 `requestId`、`resolvedModel`、`usage`、`metrics`、`billingSummary`、`finalChargeAmount` | 未执行 | 每个 task 的详情摘要待填写 | + +## 5. 历史任务记录保存 + +`docs/design.md` 中说明业务对话、绘图历史最终仍可由 `server-main` 汇总；Gateway 侧必须保存执行事实源。这里按 Gateway 当前数据模型验证 `gateway_tasks`、`gateway_task_attempts`、`gateway_task_events` 和 callback outbox。若产品口径确实是“历史人物记录”，需要补充对应业务表和接口后再加专项用例。 + +| ID | 任务 | 验证点 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | --- | +| HISTORY-01 | 任务主记录保存 | `gateway_tasks` 或 `GET /api/v1/tasks/{taskID}` | 每个成功任务均有一条主记录，状态、模型、用户、租户、API Key、结果和计费字段完整 | 未执行 | taskId 列表待填写 | +| HISTORY-02 | 尝试记录保存 | `gateway_task_attempts` | 每次候选客户端执行都有 attempt，成功和失败尝试均保存 request/response/error 快照 | 未执行 | attempt 数量待填写 | +| HISTORY-03 | 事件记录保存 | `gateway_task_events` | 事件包含接收、运行、重试、完成或失败，`simulated` 标记准确 | 未执行 | 事件摘要待填写 | +| HISTORY-04 | 回调 outbox 保存 | `gateway_task_callback_outbox`，开启回调配置时验证 | 每个 task event 写入幂等 outbox，`task_id + seq + callback_url` 唯一 | 未执行 | outbox 数量待填写 | +| HISTORY-05 | API Key 身份保存 | 任务详情或数据库字段 | `apiKeyId`、`apiKeyName`、`apiKeyPrefix` 可追溯到发起 Key | 未执行 | key 信息待填写 | + +## 6. 定价规则绑定与扣费计算 + +定价必须验证“绑定有效”和“计算正确”两个层面。测试时建议使用独立内部规则集，价格设置成易人工核算的值。 + +| ID | 任务 | 请求 / 数据 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | --- | +| PRICE-01 | 绑定规则集到基准模型 | `PATCH /api/v1/catalog/base-models/{baseModelID}` 或创建自定义基准模型 | 模型返回 `pricingRuleSetId=loopback-pricing-*` | 未执行 | baseModelId、ruleSetId 待填写 | +| PRICE-02 | 绑定规则集到平台模型 | `POST /api/v1/platforms/{platformID}/models` 或更新模型 | 平台模型返回 `pricingRuleSetId=loopback-pricing-*` 或 `billingConfigOverride` 生效 | 未执行 | platformModelId 待填写 | +| PRICE-03 | Chat 预估计费 | `POST /api/v1/pricing/estimate`，Chat 请求体 | 返回 `resolver=effective-pricing-v1`，`text_input` 与 `text_output` 金额按 tokens 计算 | 未执行 | estimate items 待填写 | +| PRICE-04 | Chat 最终扣费 | 执行 Chat 成功任务 | `finalChargeAmount=sum(billings.amount)`，输入/输出 token 数与 usage 对齐 | 未执行 | usage、billings、finalChargeAmount 待填写 | +| PRICE-05 | 文生图扣费 | 执行文生图成功任务 | `resourceType=image`，数量、尺寸、质量权重参与计算 | 未执行 | billings 待填写 | +| PRICE-06 | 图生图扣费 | 执行图生图成功任务 | `resourceType=image_edit`，优先使用编辑价格，缺省时回退图片价格 | 未执行 | billings 待填写 | +| PRICE-07 | 视频扣费 | 执行文生视频、图生视频、首尾帧视频成功任务 | `resourceType=video`，数量、分辨率或时长权重按规则计算，三类视频请求均有计费记录 | 未执行 | billings 待填写 | +| PRICE-08 | 用户组折扣 | 将测试用户放入带 `billingDiscountPolicy.discountFactor` 的用户组后执行 | `discountFactor` 同时体现模型折扣和用户组折扣，最终金额符合乘积 | 未执行 | groupId、discount、charge 待填写 | + +## 7. 权限控制 + +权限控制分为认证可用性、API Key 层访问规则、用户组层访问规则。API Key 的 `scopes` 也要纳入检查；如果当前实现只保存不拦截，需要按失败项修复。 + +| ID | 层级 | 任务 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | --- | +| AUTH-01 | API Key | 全量 Key 可调用 Chat、文生图、图生图、文生视频、图生视频、首尾帧视频 | 所有真实任务链路均成功，任务记录含对应 Key 身份 | 未执行 | taskId 列表待填写 | +| AUTH-02 | API Key | 禁用 Key 后调用任一任务 | HTTP 401，不能创建新任务 | 未执行 | 状态码和响应待填写 | +| AUTH-03 | API Key | 删除 Key 后调用任一任务 | HTTP 401，不能创建新任务 | 未执行 | 状态码和响应待填写 | +| AUTH-04 | API Key | Chat-only Key 调图片或视频能力 | 应被拒绝；若当前仅保存 scopes 不拦截，则标记失败并修复 | 未执行 | 状态码和修复结论待填写 | +| AUTH-05 | API Key | 给 API Key 添加 `deny platform_model` 访问规则后调用被拒模型 | `ListModelCandidates` 无候选，任务返回 404 或失败码 `no_model_candidate` | 未执行 | ruleId、响应待填写 | +| AUTH-06 | API Key | 给 API Key 添加 `allow platform_model` 后调用允许模型 | 允许模型成功，未被 allow 的受控资源不可用 | 未执行 | ruleId、taskId 待填写 | +| AUTH-07 | 用户组 | 给用户组添加 `deny platform_model` 后该组用户调用 | 该组用户被拒，非该组用户不受影响 | 未执行 | groupId、响应待填写 | +| AUTH-08 | 用户组 | 给用户组添加 `allow platform_model` 和 `minPermissionLevel` | 权限等级不足被拒，满足等级后成功 | 未执行 | groupId、角色、响应待填写 | +| AUTH-09 | 可见模型列表 | `GET /api/v1/playground/models` | 列表同样遵守 API Key / 用户组访问规则，不只在执行时过滤 | 未执行 | 模型数量和过滤结果待填写 | + +## 8. 运行策略与模拟客户端 + +本节只使用模拟平台或 `runMode=simulation`，通过请求体 `simulationProfile` 或平台凭证 `simulationFailure` 制造不同错误。已知模拟客户端支持 `success`、`retryable_failure`、`fatal_failure` / `non_retryable_failure`。 + +| ID | 策略 | 准备 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | --- | +| POLICY-RETRY-01 | 可重试错误触发重试 | 同一模型配置两个候选，第一候选 `simulationFailure=retryable_failure`，第二候选成功，`retryPolicy.enabled=true,maxAttempts=2` | 任务最终 `succeeded`，事件含 `task.retrying`，attempt 先失败后成功 | 未执行 | taskId、attempts、events 待填写 | +| POLICY-RETRY-02 | 重试策略禁用 | 第一候选 `retryable_failure`，`retryPolicy.enabled=false` | 任务失败，不出现 `task.retrying`，不会调用第二候选 | 未执行 | taskId、attempts 待填写 | +| POLICY-RETRY-03 | 非重试错误不重试 | `simulationProfile=fatal_failure` 或 `non_retryable_failure` | 任务失败，错误码为 bad_request 类，不出现 `task.retrying` | 未执行 | taskId、errorCode 待填写 | +| POLICY-DISABLE-01 | 错误策略自动禁用 | 配置 `autoDisablePolicy.enabled=true,threshold=1,keywords=[invalid_api_key]`，模拟命中关键词 | 命中后平台或模型被禁用，后续候选查询不再使用该客户端 | 未执行 | platformId、状态变化待填写 | +| POLICY-DISABLE-02 | 非命中关键词不禁用 | 同样策略下模拟不在关键词中的错误 | 平台和模型状态不变，仅记录失败 | 未执行 | 状态变化待填写 | +| POLICY-DEGRADE-01 | 降级策略生效 | 配置 `degradePolicy.enabled=true,cooldownSeconds=300,keywords=[rate_limit,overloaded]`，模拟命中关键词 | 失败平台被降级或进入冷却，下一次路由优先使用其他候选 | 未执行 | priority/cooldown 变化待填写 | +| POLICY-DEGRADE-02 | 非命中关键词不降级 | 模拟普通 bad_request | 不调整优先级、不进入冷却 | 未执行 | priority/cooldown 变化待填写 | +| POLICY-ORDER-01 | 候选排序 | 两个平台同模型，优先级和 running_count 不同 | 路由按优先级、限流占用、运行中数量排序 | 未执行 | 候选顺序证据待填写 | + +## 9. 限流控制 + +限流需要覆盖平台模型维度和用户组维度。RPM / TPM 使用同一分钟窗口断言；并发使用 lease 断言。 + +| ID | 限流 | 准备 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | --- | +| LIMIT-RPM-01 | 平台模型 RPM | 平台模型 `rateLimitPolicy.rules=[{metric:rpm,limit:1,windowSeconds:60}]` | 第一次成功，第二次同窗口返回 429 或任务失败码 `rate_limit` | 未执行 | taskId、窗口计数待填写 | +| LIMIT-RPM-02 | 用户组 RPM | 用户组 `rateLimitPolicy` 设置 RPM=1，用户归属该组 | 同组第二次被限流，不同组用户不受影响 | 未执行 | groupId、响应待填写 | +| LIMIT-TPM-01 | 平台模型 TPM | 设置 `tpm_total` 极小值，发送长 prompt | 当估算 token 超出 limit 时被拒绝 | 未执行 | token 估算、响应待填写 | +| LIMIT-TPM-02 | 用户组 TPM | 用户组设置 `tpm_total` 极小值 | 该组用户被限制，非该组用户不受影响 | 未执行 | groupId、响应待填写 | +| LIMIT-CONC-01 | 并发限制 | 设置 `concurrent=1`，并发发起两个慢模拟任务或保留未释放 lease | 第二个任务被限流，`gateway_concurrency_leases` 记录正确 | 未执行 | leaseId、响应待填写 | +| LIMIT-CONC-02 | 并发释放 | 成功任务结束后再次发起 | lease 释放后新任务可成功 | 未执行 | released_at、taskId 待填写 | +| LIMIT-WINDOW-01 | 限流窗口查询 | `GET /api/v1/runtime/rate-limit-windows` | 返回对应 `scopeType/scopeKey/metric/usedValue/resetAt` | 未执行 | 窗口记录待填写 | + +## 10. 成功验收总表 + +| 模块 | 必须通过的用例 | 状态 | 结果摘要 | +| --- | --- | --- | --- | +| 基础准备 | SETUP-01 到 SETUP-09 | 未执行 | 待填写 | +| 完整任务执行 | TASK-CHAT-01 到 TASK-DETAIL-01 | 未执行 | 待填写 | +| 历史任务记录 | HISTORY-01 到 HISTORY-05 | 未执行 | 待填写 | +| 定价与扣费 | PRICE-01 到 PRICE-08 | 未执行 | 待填写 | +| 权限控制 | AUTH-01 到 AUTH-09 | 未执行 | 待填写 | +| 运行策略 | POLICY-RETRY-01 到 POLICY-ORDER-01 | 未执行 | 待填写 | +| 限流控制 | LIMIT-RPM-01 到 LIMIT-WINDOW-01 | 未执行 | 待填写 | + +## 11. 失败处理记录 + +| 时间 | 用例 ID | 失败现象 | 初步原因 | 修复位置 | 重跑结果 | +| --- | --- | --- | --- | --- | --- | +| 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | + +## 12. 清理清单 + +| ID | 清理对象 | 成功判定 | 状态 | 结果记录 | +| --- | --- | --- | --- | --- | +| CLEAN-01 | 内部测试 API Key | 禁用或删除所有 `loopbackRunId` 关联 Key | 未执行 | 待填写 | +| CLEAN-02 | 内部访问规则 | 删除 `loopbackRunId` 关联 `gateway_access_rules` | 未执行 | 待填写 | +| CLEAN-03 | 内部模拟平台和模型 | 删除或禁用 `loopback-sim-*` 平台和模型 | 未执行 | 待填写 | +| CLEAN-04 | 内部测试用户组和用户 | 删除或禁用 `loopback-*` 用户组和用户 | 未执行 | 待填写 | +| CLEAN-05 | 内部策略和规则集 | 删除非默认 `loopback-*` 运行策略和定价规则集 | 未执行 | 待填写 |