chore: bump version to 3.6.0

Co-authored-by: Codex <noreply@openai.com>

.agents/skills/dev-guide/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: dev-guide
+description: 当前仓库开发指南。修改或排查本仓库的 Rust 网关、Vue 管理端、账号与出站代理、接口协议、部署、CI、发布或文档时使用，定位权威规范和验证入口。Use for development in the repository containing this skill; not for generic Rust/Vue questions in unrelated repositories.
+---
+
+# 开发指南
+
+先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。
+本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。
+
+## 按任务读取
+
+| 任务 | 文档入口 |
+| --- | --- |
+| 用户能力、快速开始 | [README](../../../README.md) |
+| 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) |
+| HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.md) |
+| 管理端组件、主题 Token、视觉验证 | [管理端主题](../../../docs/theme.md) |
+| 部署、客户端配置、备份与恢复 | [部署说明](../../../deploy/README.md) |
+| 数据迁移、冻结清单与本地测试库 | [迁移说明](../../../backend/migrations/README.md) |
+| 验证命令与提交规范 | [贡献与审查](../../../CONTRIBUTING.md) |
+| 创建或审查 PR | [github-pr](../github-pr/SKILL.md) |
+| 整理或提交 Issue | [github-issue](../github-issue/SKILL.md) |
+| 发布说明、版本规划与发版 | [release](../release/SKILL.md) |
+
+## 执行顺序
+
+1. 从仓库根目录确认工作区、当前任务范围和相关运行实例；保留已有改动。
+2. 按 `AGENTS.md` 的 CodeGraph 约定定位入口、调用链和职责归属，再阅读相关实现。
+3. 按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实触发条件、问题发生版本与目标分支现状，
+   优先依据适用的官方源码确定方案。结合上表读取所需文档，先找可复用的同类实现，再修改所属模块。
+4. 文档和运行结果不一致时，追查当前源码、配置与版本，区分实现缺陷和文档过期；同步受影响的说明。
+5. 按 `CONTRIBUTING.md` 验证并报告结果。后端 Cargo 命令从 `backend/` 执行，或显式指定该目录的 manifest。
+
+发布任务按 `release` 技能读取当前版本、发布入口和工作流，发布说明语言遵循 `CONTRIBUTING.md`。

.agents/skills/dev-guide/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-guide"
+  short_description: "从仓库规范与架构文档定位实现、验证和交付的正确入口"
+  default_prompt: "使用 $dev-guide 按当前仓库规范与架构完成开发、验证或发布。"

.agents/skills/github-issue/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: github-issue
+description: 整理与提交 GitHub Issue（问题反馈 / 功能建议）。用于“提个 Issue”“把这个问题反馈到仓库”“帮我报个 bug”“整理成 Issue”，以及通过 Issue 提议功能或协作规则的场景；区分草拟正文和实际提交。Use for drafting or filing bug reports and feature requests; not for debugging-only, editing Issue Forms/templates, or skill-authoring requests.
+---
+
+# 整理与提交 Issue
+
+本仓库流程见 [贡献与审查](../../../CONTRIBUTING.md)，问题反馈使用当前的
+[YAML Issue Form](../../../.github/ISSUE_TEMPLATE/bug_report.yml)。从表单读取字段与必填项，不在技能中复制一份字段清单。
+用户指定其他仓库时，使用该仓库当前的贡献规则与 Issue 模板，不能把这里的表单套过去。
+
+## 确定目标和动作
+
+- 根据用户 URL、仓库上下文和 remote 确认接收 Issue 的仓库。fork 场景核对用户要反馈给自己的 fork 还是上游。
+- “写一份、整理内容、草拟 Issue”只准备正文；明确要求“提交、创建 Issue”才发布。
+  已经授权提交且信息足够时直接完成，不重复索要确认；仅自动选中技能不能授权发布。
+- “有个 bug”“这个报错怎么修”本身是排障语境，不能推断要发 Issue；结合已有反馈任务识别省略的目标和动作。
+- 缺少无法推断的目标或关键复现事实时，只问必要信息，并先整理其余已有证据。
+- 使用可用的 GitHub 连接器或 `gh`。不要为提交 Issue 安装新工具、修改仓库配置或启用额外服务。
+
+## 证据与去重
+
+1. 读取目标仓库实际 Issue 模板和配置，区分缺陷、功能建议与协作规则提案。
+   本仓库后两类允许普通 Issue；其他仓库按其配置选择入口。
+2. 先搜索 open 和 closed Issues，结合关键词、错误信息与触发条件检查重复，而不只比较标题。
+   同时核对相关 PR 与发布记录，关联已有修复及其发布版本；仅主分支已修复时明确尚未发布。
+   同一问题已有记录且没有新增证据时返回已有链接；用户仍明确要求新建时按其要求处理。
+   不因发现重复而擅自评论、重开或关闭已有 Issue。
+3. 从用户描述、当前版本与已有诊断中整理事实：区分实际结果、预期结果、稳定复现条件和未经证实的推测。
+   不把本地开发版本当作发生问题的部署版本；无法复现时如实说明已知条件。
+   引用官方行为或提出实现方案时，按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 注明来源、版本与缺口；
+   不把找到官方源码或证明根因作为提交症状反馈的前提。
+4. 只收集定位所需信息。正文、日志片段和附件去除密钥、Cookie、令牌、代理认证、私人请求内容等敏感信息；
+   不直接附完整配置或请求转储。记录与复现相关的代理、TUN、证书条件，不擅自修改这些环境来收集材料。
+
+## 编写正文
+
+- 标题写具体症状或所需行为，不预先断言尚未证明的根因。语言与目标仓库及用户要求一致。
+- YAML Issue Form 按字段顺序使用 `attributes.label` 作为 Markdown 小标题，填写相应答案。
+  `gh issue create --body-file` 直接提交正文，不会替你完成网页表单校验；手动核对必填字段、选项和必选确认项。
+  不把原始 YAML、占位文字或尚未确认的勾选项当成答案提交。
+- 无法获知的信息明确写未提供或不适用，并说明理由；如果该事实关系到能否理解或复现问题，发布前补齐。
+  功能或规则提案说明当前场景、缺少的能力、建议结果和必要取舍，不强行填写缺陷复现步骤。
+- 附件只使用用户授权发布且实际可访问的地址；本机 `/tmp/...` 路径不能作为 GitHub 附件。
+  没有可用附件时保留操作描述并说明缺口，不声称截图已上传。
+- 使用模板规定或用户要求的 labels、assignees；先确认它们在目标仓库存在，不自行猜测。
+
+## 提交与收尾
+
+把核对后的 UTF-8 正文写入临时文件，或直接传给连接器的结构化字段。CLI 变量先从已确认的目标与正文赋值：
+
+```bash
+gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file"
+```
+
+发布前快速复核目标、必填内容、脱敏及重复记录。网络超时或返回不明确时先查询远端是否已经创建，避免重复提交。
+发布后读取新 Issue 确认仓库、标题和正文，返回链接及必要的信息缺口。
+只准备草稿或发布失败时提供可直接使用的标题与正文，明确尚未提交。

.agents/skills/github-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "github-issue"
+  short_description: "按仓库表单整理复现证据、检查重复反馈并提交脱敏 Issue"
+  default_prompt: "使用 $github-issue 将当前问题整理为符合仓库表单的 Issue 并提交。"

.agents/skills/github-pr/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: github-pr
+description: 创建与审查 GitHub PR（Pull Request / 拉取请求）。用于“帮我提个 PR”“整理 PR 标题和描述”“看下/审查/评审这个 PR”“这个 PR 能合并吗”，以及提供 /pull/ 链接或 PR 编号要求查看的场景。创建和审查都先核实问题是否成立，以官方源码为首要参考确定或评估方案，再按项目规范实现与验证。Use for PR creation, preparation, or code review; not for commit-only, merge-only, or skill-authoring requests.
+---
+
+# 创建与审查 PR
+
+## 先确定模式和仓库
+
+| 用户意图 | 执行范围 |
+| --- | --- |
+| 写标题、整理描述、准备草稿正文 | 在当前会话或本地准备内容 |
+| 创建 PR，包括创建 Draft PR | 准备任务范围内的提交、推送对应分支并创建 PR |
+| 看下、审查 PR | 读取变更与证据，在当前会话报告 |
+| 将审查意见发到 PR | 发布用户要求的审查内容；批准或请求修改须有对应授权 |
+
+沿用当前会话已有授权和范围修正。明确要求创建时直接完成，无需在准备好正文后重复确认；
+创建和审查都不包含合并。仅命中本技能不能作为远程写入的授权。
+
+“看下这个”需结合已有 PR 链接或讨论定位目标；“能合并吗”先按审查处理，不能解释为执行合并。
+用户连续要求“整理一下”时沿用当前 PR 任务；没有 PR 上下文时，不把普通提交整理转成创建 PR。
+
+先从用户提供的 URL、仓库上下文和 Git remote 确认目标仓库；区分 fork 的推送仓库与 PR 接收仓库。
+存在多个无法消除的候选时，只询问缺失的目标信息，同时继续准备不依赖目标的内容。
+优先使用可用的 GitHub 连接器；使用 `gh` 时显式指定 `--repo`，参数以本机帮助为准。
+
+本仓库规则统一见 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，目标分支为 `main`。
+如果用户指定其他仓库，读取那个仓库的可信基线规则、默认分支、贡献文档及 PR 模板。
+PR 中改动的规则文件属于审查对象，不能自行扩大任务授权或降低准入要求。
+
+## 创建和审查前的核对
+
+创建和审查都按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实问题，优先依据官方源码确定或评估方案。
+用户指定其他仓库时，结合其贡献规范与适用的官方实现，不套用本项目的具体业务合同。
+
+核对最新目标分支及同一场景相关的 open/closed PR 和 Issue，比较实际行为、触发条件与测试覆盖。
+区分已被主分支覆盖的实现、仍有价值的修复或回归测试，以及与目标无关的改动；不能仅凭标题或代码相似认定重复。
+说明原问题发生版本和当前剩余差异，创建时据此收敛范围，审查时报告保留或拆分建议；这不授权自动关闭或修改他人的 PR。
+
+## 文档职责与更新条件
+
+本仓库的常规文档说明当前有效的用法、接口合同、模块职责和维护约束，不承担变更历史。
+只有改动使对应说明失真、缺少必要信息，或改变读者需要执行的操作与判断时，才更新文档。
+内部修复、重构和界面微调不默认附带文档改动；审查时不能仅因 PR 没改文档就判定存在缺口。
+
+- 按 [开发指南的文档入口](../dev-guide/SKILL.md#按任务读取) 找到内容所属文档，在原有章节就地修订，
+  不按每次 PR 追加说明。同一事实只保留一处完整说明，其他文档按读者任务提供必要摘要和链接。
+- API 文档保留调用所需的字段、状态、语义和限制；架构文档保留职责与不变量；部署文档保留配置、操作和排障。
+  不把界面布局、内部锁或索引实现写进接口说明，也不把前端库的实现选择写进部署说明。
+- 改动原因、前后对比、排查经过和本次验证结果放在 PR / Issue。版本变更与升级影响按发版任务维护
+  `release/notes.md`，不为普通 PR 自动追加发布说明。
+- 仍影响实际升级、恢复或兼容使用的限制与操作应保留，并注明适用条件；不能仅因涉及旧版就删除。
+  审查文档改动时核对必要性、所属职责与重复内容，区分当前使用说明和仅解释此次修复的内容。
+
+## 创建 PR
+
+1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。
+   不用提交日志拼接正文，也不假定仓库一定有模板。
+2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
+   只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
+3. 按上述核对流程，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。
+   若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口，
+   不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。
+   实现应职责清晰、表达直接、复用合理；提交前主动清理本次变更引入的重复逻辑、冗余状态、死代码、
+   多余抽象及无依据的兼容分支。功能可用和检查通过不能替代可维护性自查。
+4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
+   更新现有标题或正文须在本次整理/更新请求范围内。
+5. 按贡献文档执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。
+   前端改动提供实际界面证据或预览步骤；缺少证据时写明，不用构建成功替代视觉验收。
+6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为，
+   再给必要的设计取舍、验证与遗留事项。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、
+   本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。
+7. 明确要求草稿或仍有阻塞项时创建 Draft PR，并解释原因；具备审查条件且未要求草稿时创建普通 PR。
+   GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。
+8. 创建后核对链接、base、head、草稿状态和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。
+
+CLI 示例中的变量必须先根据上述检查赋值；`pr_body_file` 是精确写入 UTF-8 正文的临时文件：
+
+```bash
+gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \
+  --title "$pr_title" --body-file "$pr_body_file"
+```
+
+按需添加 `--draft`。不要用 `gh pr create --dry-run` 做只读预览，它仍可能推送 Git 变更。
+多行正文通过文件或连接器的结构化字段传递，不把未转义正文拼进 shell 命令。
+创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。
+
+## 审查 PR
+
+1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。
+   需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。
+2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。
+   按上述核对流程收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
+3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、
+   是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。
+4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。
+   对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
+   主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
+   不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。
+5. UI 改动同时对照主题、共用组件、数据展示逻辑和同类页面。浏览器可用时检查相关交互及状态；
+   未运行的页面检查列为验证缺口，不从截图或源码推断所有状态都正确。
+6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
+   工具不可用、集成测试跳过或环境不足时具体说明影响范围。
+7. 按 [审查标准](../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理，
+   再列出实现问题与验证缺口，结论附具体依据。
+   实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。
+   每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。
+   复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。
+8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
+
+审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
+用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容；
+需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。

.agents/skills/github-pr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "github-pr"
+  short_description: "创建与审查拉取请求，先核实问题，以官方源码为首要依据确定或评估实现方案"
+  default_prompt: "使用 $github-pr 按当前请求创建或审查 PR，先核实问题是否成立，以官方源码为首要参考确定或评估解决方案，说明源码依据及必要的偏离原因，并按仓库规范实现与验证或报告审查结论。"

.agents/skills/release/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: release
+description: 准备或执行当前仓库发版，维护中文发布说明。用于“发版”“发个新版本”“准备 vX.Y.Z”“推荐版本号”“整理更新日志/发布说明”“更新 release/notes.md”“打版本 tag”等发行任务。Use for version planning, release notes, and publishing a repository release; not for deploying/restarting an instance, publishing application data, or authoring a release skill.
+---
+
+# 发版
+
+## 识别任务范围
+
+| 用户意图 | 执行范围 |
+| --- | --- |
+| 推荐版本号 | 根据本次变更与已有版本给出建议及理由 |
+| 整理更新日志、写 note、准备发版 | 核对变更、编写说明、检查发布条件；未要求提交时保留本地改动 |
+| 正式发布、发布指定版本、打版本 tag | 在已授权范围内执行对应步骤；仅打 tag 的请求不自动扩展为完整发版 |
+| 重试失败的发版 | 核对上次执行状态，从未完成的步骤恢复 |
+
+沿用当前会话明确的版本、范围与授权；用户已要求正式发版且条件满足时直接执行，不重复确认。
+“准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。
+发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。
+
+## 读取当前流程
+
+先读 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，再按任务检查：
+
+| 事实 | 权威入口 |
+| --- | --- |
+| 当前版本 | [release/version.yaml](../../../release/version.yaml) |
+| 本次发布说明及语言约定 | [release/notes.md](../../../release/notes.md)、贡献文档的项目约定 |
+| 版本提交、tag、推送与工作流触发 | [release/publish](../../../release/publish) |
+| 构建、检查、GitHub Release 和镜像发布 | [发布工作流](../../../.github/workflows/release.yml) |
+| 平台与产物清单 | [release/platforms.yaml](../../../release/platforms.yaml) |
+
+命令从仓库根目录执行；每次以当前脚本和工作流为准，不另写发布脚本或绕过已有质量检查。
+用户明确指定其他仓库时先读取其发布流程，不能直接套用这里的路径和命令。
+
+## 准备版本与说明
+
+1. 确认发布分支、upstream、目标仓库、工作区和完整待推送范围。本仓库沿用 `main`；
+   未提交或未跟踪内容分别核对，不因脚本只检查已跟踪文件就认定所有内容都已纳入发布。
+2. 读取版本文件、已有 tag 和实际发行记录，确认上一发布基线与本次目标提交。
+   根据基线到目标的提交和最终差异归纳变更，剔除回退、重复和未进入发布范围的内容。
+   不能只用当前版本文件或最近几条提交判断“本次更新”。
+3. 使用用户指定或当前会话已确定的目标版本；需要建议时按兼容性、能力新增和修复范围说明理由。
+   目标 tag 必须未被占用；遇到已有同名版本先判断是重试还是新发版，不自动递增版本掩盖冲突。
+4. 按贡献文档维护 `release/notes.md`。正文写中文，保留版本号和必要技术标识；
+   按用户可感知的最终行为归并，不逐条翻译 commit，也不把排查过程或未验证承诺写入说明。
+   可按新增功能、问题修复、体验优化、升级说明组织，省略没有内容的章节。
+5. 替换为本次版本说明，首行与目标 tag 一致且正文非空。升级事项应能追溯到实际迁移、配置或兼容变化；
+   敏感信息脱敏，未合入功能不宣称已发布。已有准确说明仅需翻译时保持其事实和范围。
+6. 按贡献规范检查变更与现有 CI 证据，明确通过、失败、跳过和未执行。
+   只修改说明时无需重建前后端；正式发版仍要跟踪发布工作流针对目标提交的检查与产物。
+
+## 执行正式发版
+
+调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。
+当前脚本要求先提交 `release/notes.md`，再由脚本更新 `release/version.yaml` 并创建版本提交，
+不要提前把版本文件改成目标版本，否则脚本会判定该版本已设置。
+本任务需要的提交按贡献文档保留英文 Conventional Commits 与相应署名。
+
+在准备完成且用户已授权正式发布后，将 `release_version` 设为已确定的版本，执行：
+
+```bash
+release/publish "$release_version"
+```
+
+该命令会创建版本提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。
+它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。
+
+## 恢复与验收
+
+- 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。
+  若本地已创建版本提交或 tag，不直接重跑入口，也不通过删 tag、回退版本或强推来消除报错。
+- 提交和 tag 已推送但工作流未触发时，核对目标后使用脚本提示的 dispatch 命令补触发；
+  工作流已存在则跟踪或恢复对应 run，避免重复发布。发现 tag 指向不同提交时报告冲突，不移动已发布 tag。
+- 跟踪与本次 tag 对应的 run ID，核对工作流解析的目标提交。触发工作流成功只表示已开始，不能当作发布完成。
+- 发布完成后核对 GitHub Release 的版本、正式版/预发行状态和中文变更正文；对照平台清单与工作流确认归档、校验和及镜像产物。
+  工作流附加的安装说明和自动提交列表按其当前配置处理，不用它们替代手写的中文变更说明。
+- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明，不能称为发布成功；
+  Release 和镜像已生成也不表示用户的运行实例已经升级。

.agents/skills/release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "release"
+  short_description: "按仓库流程整理中文发布说明、核对版本并完成发行与验证"
+  default_prompt: "使用 $release 准备下一个版本的中文发布说明，并核对发版条件。"

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,120 @@
+name: 问题反馈
+description: 提交可复现的问题，帮助定位和修复
+body:
+  - type: markdown
+    attributes:
+      value: |
+        请提供最小复现信息。请求、日志和截图发布前请移除密钥、令牌、Cookie、代理认证及私人内容。
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: 问题类型
+      options:
+        - 接口请求或响应异常
+        - 页面或交互异常
+        - 配置或部署异常
+        - 其他问题
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题描述
+      description: 说明发生了什么、实际结果以及出现的频率。
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: 服务版本
+      description: 填写具体版本号；从源码运行时填写提交号。
+      placeholder: 版本号或提交号
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: 部署方式
+      options:
+        - Docker Compose
+        - 其他容器部署
+        - 二进制运行
+        - 源码运行
+        - 其他方式（请在环境信息中说明）
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: 环境信息
+      description: 填写操作系统与版本；页面问题同时填写浏览器与版本。
+      placeholder: |
+        操作系统与版本：
+        浏览器与版本（页面问题）：
+    validations:
+      required: true
+
+  - type: textarea
+    id: account-client
+    attributes:
+      label: 账号与客户端
+      description: 接口问题请填写平台、认证类型、模型和客户端信息，不要提供账号凭据。
+      placeholder: |
+        平台与认证类型：
+        模型名称：
+        客户端名称与版本：
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 复现步骤
+      description: 描述触发问题的操作；无法稳定复现时，说明已知触发条件。
+      placeholder: |
+        1. 使用什么配置或输入
+        2. 执行什么操作
+        3. 出现什么结果
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: 预期行为
+      description: 说明原本期望得到的结果。
+    validations:
+      required: true
+
+  - type: textarea
+    id: request-response
+    attributes:
+      label: 请求与响应
+      description: |
+        接口问题请提供脱敏后的最小请求、网关实际状态/响应片段和客户端终端显示，区分两者。
+        优先附管理端默认诊断包并检查其缺失说明；原始错误与日志片段需另行审阅脱敏。
+        先按部署文档的“请求错误排查”检查关联 ID、错误详情与 application 日志，不默认开启完整 dump。
+      placeholder: |
+        发生时间与时区：
+        传输（HTTP JSON / SSE / WebSocket）：
+        网关关联 ID（x-gateway-request-id / 配置的入口头）：
+        上游关联 ID（x-request-id / x-oai-request-id，注明来源）：
+        网关实际状态与响应片段：
+        客户端终端显示：
+        诊断包或无法取得的信息：
+      render: text
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: 截图或录屏
+      description: 页面或交互问题可在此拖入相关截图、录屏，并说明对应的操作。
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 补充信息
+      description: 最近的升级或配置变更；网络问题补充系统代理、TUN 和自定义证书等相关环境。

.github/actions/verify-container/action.yml

@@ -0,0 +1,242 @@
+name: Verify container
+description: Scan and validate a built image with the deployment Compose configuration
+inputs:
+  image:
+    description: Local image tag or immutable registry digest to validate
+    required: true
+  platform:
+    description: Native runner image platform
+    required: true
+  artifact-name:
+    description: Unique diagnostics artifact name within the workflow run
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Define isolated runtime values
+      shell: bash
+      env:
+        IMAGE: ${{ inputs.image }}
+      run: |
+        set -euo pipefail
+        admin_password="$(openssl rand -hex 24)"
+        postgres_password="$(openssl rand -hex 24)"
+        redis_password="$(openssl rand -hex 24)"
+        echo "::add-mask::$admin_password"
+        echo "::add-mask::$postgres_password"
+        echo "::add-mask::$redis_password"
+        {
+          echo "CPR_IMAGE=$IMAGE"
+          echo "COMPOSE_PROJECT_NAME=cpr-check-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RUNNER_ARCH,,}"
+          echo "DIAGNOSTICS_DIR=$RUNNER_TEMP/codex-proxy-rs-diagnostics"
+          echo "CI_ADMIN_PASSWORD=$admin_password"
+          echo "CI_POSTGRES_PASSWORD=$postgres_password"
+          echo "CI_REDIS_PASSWORD=$redis_password"
+        } >> "$GITHUB_ENV"
+
+    - name: Scan container image
+      uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+      env:
+        TRIVY_PLATFORM: ${{ inputs.platform }}
+        TRIVY_QUIET: 'true'
+        TRIVY_SKIP_VERSION_CHECK: 'true'
+      with:
+        image-ref: ${{ inputs.image }}
+        version: v0.72.0
+        format: json
+        output: trivy-results.json
+        severity: HIGH,CRITICAL
+        vuln-type: os,library
+        scanners: vuln
+        ignore-unfixed: true
+        exit-code: '0'
+
+    - name: Generate Trivy SARIF
+      shell: bash
+      run: trivy convert --format sarif --output trivy-results.sarif trivy-results.json
+
+    - name: Upload Trivy SARIF
+      if: >-
+        ${{ always() && hashFiles('trivy-results.sarif') != '' &&
+            (github.event_name != 'pull_request' ||
+             github.event.pull_request.head.repo.full_name == github.repository) }}
+      uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+      with:
+        sarif_file: trivy-results.sarif
+        category: runtime-container-${{ inputs.platform }}
+
+    - name: Enforce Trivy vulnerability gate
+      shell: bash
+      run: trivy convert --format table --severity HIGH,CRITICAL --exit-code 1 trivy-results.json
+
+    - name: Prepare isolated runtime
+      shell: bash
+      run: |
+        set -euo pipefail
+        umask 0077
+        # Bind roots hand off ownership to the image-specific database users.
+        # Sticky directories keep that initialization compatible with user-namespaced runners.
+        install -d -m 1777 .runtime/postgres .runtime/redis
+        mkdir -p "$DIAGNOSTICS_DIR"
+        sudo install -d -m 0770 -o "$(id -u)" -g 10001 \
+          .runtime/data .runtime/logs
+        ruby <<'RUBY'
+        path = "deploy/config.example.yaml"
+        content = File.read(path)
+        replacements = {
+          "password: &postgres_password ''" => "password: &postgres_password '#{ENV.fetch("CI_POSTGRES_PASSWORD")}'",
+          "password: &redis_password ''" => "password: &redis_password '#{ENV.fetch("CI_REDIS_PASSWORD")}'",
+          "default_password: ''" => "default_password: '#{ENV.fetch("CI_ADMIN_PASSWORD")}'",
+        }
+        replacements.each do |placeholder, configured|
+          raise "missing config placeholder: #{placeholder}" unless content.sub!(placeholder, configured)
+        end
+        File.write("deploy/config.yaml", content)
+        RUBY
+        sudo chown "$(id -u):10001" deploy/config.yaml
+        chmod 0640 deploy/config.yaml
+
+    - name: Validate Docker Compose
+      shell: bash
+      run: |
+        set -euo pipefail
+        docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml config --quiet
+
+    - name: Configure Redis host memory overcommit
+      shell: bash
+      run: |
+        set -euo pipefail
+        sudo sysctl -w vm.overcommit_memory=1
+        test "$(sysctl -n vm.overcommit_memory)" = 1
+
+    - name: Verify PostgreSQL and Redis volume persistence
+      shell: bash
+      run: |
+        set -euo pipefail
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" up -d --no-build --wait postgres redis
+        test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
+          psql -At -U codex_proxy -d codex_proxy -c "SHOW TimeZone;" | tr -d '\r')" = Asia/Shanghai
+        "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
+          psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
+          "CREATE TABLE cpr_ci_persistence_probe (value text PRIMARY KEY); INSERT INTO cpr_ci_persistence_probe VALUES ('persisted');"
+        "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
+          redis-cli SET cpr:ci:persistence-probe persisted
+        "${compose[@]}" up -d --no-build --wait --force-recreate postgres redis
+        test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
+          psql -At -U codex_proxy -d codex_proxy -c \
+          "SELECT value FROM cpr_ci_persistence_probe;")" = persisted
+        test "$("${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
+          redis-cli --raw GET cpr:ci:persistence-probe | tr -d '\r')" = persisted
+        "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
+          psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
+          "DROP TABLE cpr_ci_persistence_probe;"
+        "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
+          redis-cli DEL cpr:ci:persistence-probe
+
+    - name: Start and verify application
+      shell: bash
+      run: |
+        set -euo pipefail
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" up -d --no-build --wait codex-proxy-rs
+        status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
+          "http://127.0.0.1:8080/healthz")"
+        test "$status" = 204
+        test "$("${compose[@]}" exec -T codex-proxy-rs id -u | tr -d '\r')" = 10001
+        test "$("${compose[@]}" exec -T codex-proxy-rs id -g | tr -d '\r')" = 10001
+        test "$("${compose[@]}" exec -T codex-proxy-rs date +%z | tr -d '\r')" = +0800
+        test "$("${compose[@]}" exec -T codex-proxy-rs cat /etc/timezone | tr -d '\r')" = Asia/Shanghai
+        "${compose[@]}" exec -T codex-proxy-rs sh -c \
+          'touch /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write && rm /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write'
+
+    - name: Verify clean logs and graceful shutdown
+      shell: bash
+      run: |
+        set -euo pipefail
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" stop --timeout 30 codex-proxy-rs
+        container_id="$("${compose[@]}" ps -a -q codex-proxy-rs)"
+        test -n "$container_id"
+        test "$(docker inspect --format '{{.State.ExitCode}}' "$container_id")" = 0
+        "${compose[@]}" logs --no-color --timestamps codex-proxy-rs \
+          > "$DIAGNOSTICS_DIR/application.log"
+        "${compose[@]}" logs --no-color --timestamps postgres \
+          > "$DIAGNOSTICS_DIR/postgres.log"
+        "${compose[@]}" logs --no-color --timestamps redis \
+          > "$DIAGNOSTICS_DIR/redis.log"
+        if grep --extended-regexp --ignore-case \
+          '"level"[[:space:]]*:[[:space:]]*"(warn|error|fatal|panic)"|(^|[^[:alnum:]_])panic([^[:alnum:]_]|$)' \
+          "$DIAGNOSTICS_DIR/application.log" \
+          || grep --extended-regexp --ignore-case \
+            '(^|[[:space:]])(warning|error|fatal|panic):' \
+            "$DIAGNOSTICS_DIR/postgres.log" \
+          || grep --extended-regexp --ignore-case \
+            '[0-9]+:[A-Z][[:space:]].*[[:space:]]#[[:space:]]|(^|[|[:space:]])(warning|error|fatal|panic)(:|[[:space:]])' \
+            "$DIAGNOSTICS_DIR/redis.log"; then
+          echo "container logs contain a warning or error severity" >&2
+          exit 1
+        fi
+
+    - name: Collect container diagnostics
+      if: always()
+      shell: bash
+      run: |
+        set +e
+        mkdir -p "$DIAGNOSTICS_DIR"
+        raw_dir="$(mktemp -d)"
+        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml)
+        "${compose[@]}" config > "$raw_dir/compose-config.yaml" 2>&1
+        "${compose[@]}" ps -a > "$raw_dir/compose-ps.txt" 2>&1
+        "${compose[@]}" logs --no-color --timestamps > "$raw_dir/compose.log" 2>&1
+        mapfile -t container_ids < <("${compose[@]}" ps -a -q)
+        if [ "${#container_ids[@]}" -gt 0 ]; then
+          docker inspect "${container_ids[@]}" > "$raw_dir/docker-inspect.json" 2>&1
+        fi
+        RAW_DIR="$raw_dir" OUTPUT_DIR="$DIAGNOSTICS_DIR" ruby <<'RUBY'
+        raw_dir = ENV.fetch("RAW_DIR")
+        output_dir = ENV.fetch("OUTPUT_DIR")
+        secrets = [
+          ENV.fetch("CI_ADMIN_PASSWORD"),
+          ENV.fetch("CI_POSTGRES_PASSWORD"),
+          ENV.fetch("CI_REDIS_PASSWORD"),
+        ]
+        encoded_secrets = secrets.map do |secret|
+          secret.encode("UTF-8").bytes.map do |byte|
+            character = byte.chr
+            character.match?(/[A-Za-z0-9]/) ? character : format("%%%02X", byte)
+          end.join
+        end
+
+        Dir.children(raw_dir).each do |name|
+          content = File.binread(File.join(raw_dir, name))
+          (secrets + encoded_secrets).each do |secret|
+            content = content.gsub(secret, "<redacted>")
+          end
+          File.binwrite(File.join(output_dir, name), content)
+        end
+        RUBY
+        rm -rf "$raw_dir"
+        cp trivy-results.json trivy-results.sarif "$DIAGNOSTICS_DIR/" 2>/dev/null || true
+
+    - name: Upload container diagnostics
+      if: always()
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ runner.temp }}/codex-proxy-rs-diagnostics
+        if-no-files-found: warn
+        retention-days: 7
+
+    - name: Remove isolated runtime
+      if: always()
+      shell: bash
+      run: |
+        docker compose --project-name "$COMPOSE_PROJECT_NAME" \
+          -f deploy/compose.yaml down --remove-orphans || true
+        sudo rm -rf "$GITHUB_WORKSPACE/.runtime" "$GITHUB_WORKSPACE/deploy/config.yaml"

.github/workflows/_container.yml

@@ -17,35 +17,43 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 45
     env:
-      COMPOSE_PROJECT_NAME: cpr-ci-${{ github.run_id }}-${{ github.run_attempt }}
       CPR_IMAGE: codex-proxy-rs:ci-${{ inputs.ref }}
       TRIVY_QUIET: 'true'
       TRIVY_SKIP_VERSION_CHECK: 'true'
     steps:
-      - name: Define isolated runtime values
-        shell: bash
-        run: |
-          set -euo pipefail
-          admin_password="$(openssl rand -hex 24)"
-          postgres_password="$(openssl rand -hex 24)"
-          redis_password="$(openssl rand -hex 24)"
-          echo "::add-mask::$admin_password"
-          echo "::add-mask::$postgres_password"
-          echo "::add-mask::$redis_password"
-          {
-            echo "DIAGNOSTICS_DIR=$RUNNER_TEMP/codex-proxy-rs-diagnostics"
-            echo "CI_ADMIN_PASSWORD=$admin_password"
-            echo "CI_POSTGRES_PASSWORD=$postgres_password"
-            echo "CI_REDIS_PASSWORD=$redis_password"
-          } >> "$GITHUB_ENV"
-
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ inputs.ref }}
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        id: buildx
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+
+      - name: Cache Cargo mounts
+        id: cargo-cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ runner.temp }}/container-cargo
+          key: container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('backend/Cargo.lock', 'backend/**/Cargo.toml', 'deploy/Dockerfile') }}-${{ inputs.ref }}
+          restore-keys: |
+            container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('backend/Cargo.lock', 'backend/**/Cargo.toml', 'deploy/Dockerfile') }}-
+            container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-
+
+      # The GHA layer exporter does not persist RUN --mount=type=cache contents.
+      # Extraction runs before actions/cache saves its directories in post steps.
+      - name: Restore Cargo mounts to BuildKit
+        uses: reproducible-containers/buildkit-cache-dance@5422eac04292c961a382e0f584ea0f03ad9da723 # v3.4.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          scratch-dir: ${{ runner.temp }}/container-cache-dance
+          cache-map: |
+            {
+              "${{ runner.temp }}/container-cargo/registry": "/usr/local/cargo/registry",
+              "${{ runner.temp }}/container-cargo/git": "/usr/local/cargo/git",
+              "${{ runner.temp }}/container-cargo/target": "/app/backend/target"
+            }
+          skip-extraction: ${{ steps.cargo-cache.outputs.cache-hit }}
 
       - name: Build runtime image
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
@@ -55,212 +63,15 @@ jobs:
           target: runtime
           load: true
           tags: ${{ env.CPR_IMAGE }}
+          no-cache-filters: |
+            runtime-base
+            runtime
           cache-from: type=gha,scope=runtime-ci
           cache-to: type=gha,mode=max,scope=runtime-ci
 
-      - name: Generate Trivy SARIF
-        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+      - name: Verify runtime image
+        uses: ./.github/actions/verify-container
         with:
-          image-ref: ${{ env.CPR_IMAGE }}
-          version: v0.72.0
-          format: sarif
-          output: trivy-results.sarif
-          severity: HIGH,CRITICAL
-          vuln-type: os,library
-          scanners: vuln
-          ignore-unfixed: true
-          exit-code: '0'
-
-      - name: Upload Trivy SARIF
-        if: >-
-          ${{ hashFiles('trivy-results.sarif') != '' &&
-              (github.event_name != 'pull_request' ||
-               github.event.pull_request.head.repo.full_name == github.repository) }}
-        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
-        with:
-          sarif_file: trivy-results.sarif
-          category: runtime-container
-
-      - name: Enforce Trivy vulnerability gate
-        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
-        with:
-          image-ref: ${{ env.CPR_IMAGE }}
-          version: v0.72.0
-          format: table
-          severity: HIGH,CRITICAL
-          vuln-type: os,library
-          scanners: vuln
-          ignore-unfixed: true
-          exit-code: '1'
-
-      - name: Prepare isolated runtime
-        shell: bash
-        run: |
-          set -euo pipefail
-          umask 0077
-          # Bind roots hand off ownership to the image-specific database users.
-          # Sticky directories keep that initialization compatible with user-namespaced runners.
-          install -d -m 1777 .runtime/postgres .runtime/redis
-          mkdir -p "$DIAGNOSTICS_DIR"
-          sudo install -d -m 0770 -o "$(id -u)" -g 10001 \
-            .runtime/data .runtime/logs
-          ruby <<'RUBY'
-          path = "deploy/config.example.yaml"
-          content = File.read(path)
-          replacements = {
-            "password: &postgres_password ''" => "password: &postgres_password '#{ENV.fetch("CI_POSTGRES_PASSWORD")}'",
-            "password: &redis_password ''" => "password: &redis_password '#{ENV.fetch("CI_REDIS_PASSWORD")}'",
-            "default_password: ''" => "default_password: '#{ENV.fetch("CI_ADMIN_PASSWORD")}'",
-          }
-          replacements.each do |placeholder, configured|
-            raise "missing config placeholder: #{placeholder}" unless content.sub!(placeholder, configured)
-          end
-          File.write("deploy/config.yaml", content)
-          RUBY
-          sudo chown "$(id -u):10001" deploy/config.yaml
-          chmod 0640 deploy/config.yaml
-
-      - name: Validate Docker Compose
-        shell: bash
-        run: |
-          set -euo pipefail
-          docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml config --quiet
-
-      - name: Configure Redis host memory overcommit
-        shell: bash
-        run: |
-          set -euo pipefail
-          sudo sysctl -w vm.overcommit_memory=1
-          test "$(sysctl -n vm.overcommit_memory)" = 1
-
-      - name: Verify PostgreSQL and Redis volume persistence
-        shell: bash
-        run: |
-          set -euo pipefail
-          compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml)
-          "${compose[@]}" up -d --no-build --wait postgres redis
-          test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-            psql -At -U codex_proxy -d codex_proxy -c "SHOW TimeZone;" | tr -d '\r')" = Asia/Shanghai
-          "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-            psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
-            "CREATE TABLE cpr_ci_persistence_probe (value text PRIMARY KEY); INSERT INTO cpr_ci_persistence_probe VALUES ('persisted');"
-          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
-            redis-cli SET cpr:ci:persistence-probe persisted
-          "${compose[@]}" up -d --no-build --wait --force-recreate postgres redis
-          test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-            psql -At -U codex_proxy -d codex_proxy -c \
-            "SELECT value FROM cpr_ci_persistence_probe;")" = persisted
-          test "$("${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
-            redis-cli --raw GET cpr:ci:persistence-probe | tr -d '\r')" = persisted
-          "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-            psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
-            "DROP TABLE cpr_ci_persistence_probe;"
-          "${compose[@]}" exec -T -e REDISCLI_AUTH="$CI_REDIS_PASSWORD" redis \
-            redis-cli DEL cpr:ci:persistence-probe
-
-      - name: Start and verify application
-        shell: bash
-        run: |
-          set -euo pipefail
-          compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml)
-          "${compose[@]}" up -d --no-build --wait codex-proxy-rs
-          status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
-            "http://127.0.0.1:8080/healthz")"
-          test "$status" = 204
-          test "$("${compose[@]}" exec -T codex-proxy-rs id -u | tr -d '\r')" = 10001
-          test "$("${compose[@]}" exec -T codex-proxy-rs id -g | tr -d '\r')" = 10001
-          test "$("${compose[@]}" exec -T codex-proxy-rs date +%z | tr -d '\r')" = +0800
-          test "$("${compose[@]}" exec -T codex-proxy-rs cat /etc/timezone | tr -d '\r')" = Asia/Shanghai
-          "${compose[@]}" exec -T codex-proxy-rs sh -c \
-            'touch /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write && rm /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write'
-
-      - name: Verify clean logs and graceful shutdown
-        shell: bash
-        run: |
-          set -euo pipefail
-          compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml)
-          "${compose[@]}" stop --timeout 30 codex-proxy-rs
-          container_id="$("${compose[@]}" ps -a -q codex-proxy-rs)"
-          test -n "$container_id"
-          test "$(docker inspect --format '{{.State.ExitCode}}' "$container_id")" = 0
-          "${compose[@]}" logs --no-color --timestamps codex-proxy-rs \
-            > "$DIAGNOSTICS_DIR/application.log"
-          "${compose[@]}" logs --no-color --timestamps postgres \
-            > "$DIAGNOSTICS_DIR/postgres.log"
-          "${compose[@]}" logs --no-color --timestamps redis \
-            > "$DIAGNOSTICS_DIR/redis.log"
-          if grep --extended-regexp --ignore-case \
-            '"level"[[:space:]]*:[[:space:]]*"(warn|error|fatal|panic)"|(^|[^[:alnum:]_])panic([^[:alnum:]_]|$)' \
-            "$DIAGNOSTICS_DIR/application.log" \
-            || grep --extended-regexp --ignore-case \
-              '(^|[[:space:]])(warning|error|fatal|panic):' \
-              "$DIAGNOSTICS_DIR/postgres.log" \
-            || grep --extended-regexp --ignore-case \
-              '[0-9]+:[A-Z][[:space:]].*[[:space:]]#[[:space:]]|(^|[|[:space:]])(warning|error|fatal|panic)(:|[[:space:]])' \
-              "$DIAGNOSTICS_DIR/redis.log"; then
-            echo "container logs contain a warning or error severity" >&2
-            exit 1
-          fi
-
-      - name: Collect container diagnostics
-        if: always()
-        shell: bash
-        run: |
-          set +e
-          mkdir -p "$DIAGNOSTICS_DIR"
-          raw_dir="$(mktemp -d)"
-          compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml)
-          "${compose[@]}" config > "$raw_dir/compose-config.yaml" 2>&1
-          "${compose[@]}" ps -a > "$raw_dir/compose-ps.txt" 2>&1
-          "${compose[@]}" logs --no-color --timestamps > "$raw_dir/compose.log" 2>&1
-          mapfile -t container_ids < <("${compose[@]}" ps -a -q)
-          if [ "${#container_ids[@]}" -gt 0 ]; then
-            docker inspect "${container_ids[@]}" > "$raw_dir/docker-inspect.json" 2>&1
-          fi
-          RAW_DIR="$raw_dir" OUTPUT_DIR="$DIAGNOSTICS_DIR" ruby <<'RUBY'
-          raw_dir = ENV.fetch("RAW_DIR")
-          output_dir = ENV.fetch("OUTPUT_DIR")
-          secrets = [
-            ENV.fetch("CI_ADMIN_PASSWORD"),
-            ENV.fetch("CI_POSTGRES_PASSWORD"),
-            ENV.fetch("CI_REDIS_PASSWORD"),
-          ]
-          encoded_secrets = secrets.map do |secret|
-            secret.encode("UTF-8").bytes.map do |byte|
-              character = byte.chr
-              character.match?(/[A-Za-z0-9]/) ? character : format("%%%02X", byte)
-            end.join
-          end
-
-          Dir.children(raw_dir).each do |name|
-            content = File.binread(File.join(raw_dir, name))
-            (secrets + encoded_secrets).each do |secret|
-              content = content.gsub(secret, "<redacted>")
-            end
-            File.binwrite(File.join(output_dir, name), content)
-          end
-          RUBY
-          rm -rf "$raw_dir"
-          cp trivy-results.sarif "$DIAGNOSTICS_DIR/" 2>/dev/null || true
-
-      - name: Upload container diagnostics
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: container-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}
-          path: ${{ runner.temp }}/codex-proxy-rs-diagnostics
-          if-no-files-found: warn
-          retention-days: 7
-
-      - name: Remove isolated runtime
-        if: always()
-        shell: bash
-        run: |
-          docker compose --project-name "$COMPOSE_PROJECT_NAME" \
-            -f deploy/compose.yaml down --remove-orphans || true
-          sudo rm -rf "$GITHUB_WORKSPACE/.runtime" "$GITHUB_WORKSPACE/deploy/config.yaml"
+          image: ${{ env.CPR_IMAGE }}
+          platform: linux/amd64
+          artifact-name: container-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-amd64

.github/workflows/_quality.yml

@@ -33,6 +33,8 @@ jobs:
     timeout-minutes: 30
     env:
       CARGO_TERM_COLOR: always
+      # Rust 1.97 编译 AWS SDK 调试信息需要更大的 codegen 线程栈。
+      RUST_MIN_STACK: 16777216
       CPR_TEST_DATABASE_URL: postgres://codex_proxy:codex_proxy@127.0.0.1:5432/codex_proxy
       CPR_TEST_REDIS_URL: redis://127.0.0.1:6379
     services:

.github/workflows/agents-md-guard.yml

@@ -0,0 +1,75 @@
+name: Agent Instructions Guard
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: agents-md-guard-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # 只查询 PR 元数据，禁止检出或执行贡献分支中的代码。
+      - name: Enforce agent instructions policy
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr = context.payload.pull_request;
+            const params = { owner, repo, pull_number: pr.number };
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              ...params,
+              per_page: 100,
+            });
+            const isInstructions = path => typeof path === 'string'
+              && (path === 'AGENTS.md' || path.endsWith('/AGENTS.md'));
+
+            // 同时检查重命名前后的路径，避免通过移走规则文件绕过检查。
+            if (!files.some(file => isInstructions(file.filename) || isInstructions(file.previous_filename))) {
+              core.info('No agent instruction changes detected.');
+              return;
+            }
+
+            // 旧事件不处理后续提交，也不重复处理已关闭的 PR。
+            const { data: current } = await github.rest.pulls.get(params);
+            if (current.state !== 'open' || current.head.sha !== pr.head.sha) {
+              core.info('Pull request state has changed; skipping this event.');
+              return;
+            }
+
+            const marker = '<!-- agents-md-guard -->';
+            const body = [
+              marker,
+              '此 PR 修改了 `AGENTS.md`，已按贡献规则关闭。',
+              '',
+              'PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。',
+              '请撤销相关变更后重新打开 PR；如需调整协作规则，请先提交 Issue 说明原因和建议，由维护者处理。',
+            ].join('\n');
+
+            try {
+              const comments = await github.paginate(github.rest.issues.listComments, {
+                owner, repo, issue_number: pr.number, per_page: 100,
+              });
+              const notified = comments.some(comment => comment.user?.login === 'github-actions[bot]'
+                && comment.body?.includes(marker));
+              if (!notified) {
+                await github.rest.issues.createComment({ owner, repo, issue_number: pr.number, body });
+              }
+            } catch (error) {
+              core.warning(`Unable to post policy explanation: ${error.message}`);
+            }
+
+            await github.rest.pulls.update({ ...params, state: 'closed' });
+            core.setFailed('Pull requests must not change AGENTS.md.');

.github/workflows/ci.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'release/version.yaml'
   pull_request:
     branches:
       - main
@@ -48,6 +50,7 @@ jobs:
               - 'deploy/**'
               - '.dockerignore'
               - 'release/version.yaml'
+              - '.github/actions/**'
               - '.github/workflows/_container.yml'
               - '.github/workflows/ci.yml'
 

.github/workflows/release.yml

@@ -88,6 +88,13 @@ jobs:
           fail("Release tag #{release_tag} does not match #{version_path} tag #{expected_tag}") unless release_tag == expected_tag
           fail("#{version_path}: version #{version} is not a valid semver") unless version.match?(SEMVER)
 
+          notes_path = "release/notes.md"
+          fail("#{notes_path}: release notes are required") unless File.file?(notes_path)
+          notes = File.readlines(notes_path)
+          unless notes.first&.strip == "# #{release_tag}" && !notes.drop(1).join.strip.empty?
+            fail("#{notes_path}: expected non-empty notes starting with '# #{release_tag}'")
+          end
+
           platforms = platforms_data["platforms"]
           fail("#{platforms_path}: platforms must be a non-empty array") unless platforms.is_a?(Array) && !platforms.empty?
 
@@ -185,8 +192,9 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             backend/target
-          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
+          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}-${{ needs.release-info.outputs.git_sha }}
           restore-keys: |
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
             cargo-v2-${{ runner.os }}-${{ matrix.target }}-
 
       - name: Build binary
@@ -250,8 +258,9 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             backend/target
-          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
+          key: cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}-${{ needs.release-info.outputs.git_sha }}
           restore-keys: |
+            cargo-v2-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml') }}
             cargo-v2-${{ runner.os }}-${{ matrix.target }}-
 
       - name: Build binary
@@ -399,6 +408,7 @@ jobs:
       contents: read
       packages: write
       id-token: write
+      security-events: write
     env:
       TRIVY_QUIET: 'true'
       TRIVY_SKIP_VERSION_CHECK: 'true'
@@ -448,7 +458,7 @@ jobs:
           PY
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Login to GHCR
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
@@ -468,6 +478,9 @@ jobs:
           push: true
           build-args: |
             CPR_PREBUILT_DIR=dist/docker
+          no-cache-filters: |
+            runtime-base
+            runtime-prebuilt
           cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }}
           cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache-${{ matrix.os }}-${{ matrix.arch }},mode=min
           provenance: mode=max
@@ -479,19 +492,31 @@ jobs:
             org.opencontainers.image.source=https://github.com/zyycn/codex-proxy-rs
           tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ needs.release-info.outputs.git_sha }}-${{ matrix.arch }}
 
-      - name: Scan exact app image digest
-        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
-        env:
-          TRIVY_PLATFORM: ${{ matrix.dockerPlatform }}
+      - name: Verify exact app image digest
+        uses: ./.github/actions/verify-container
         with:
-          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build-and-push.outputs.digest }}
-          version: v0.72.0
-          format: table
-          severity: HIGH,CRITICAL
-          vuln-type: os,library
-          scanners: vuln
-          ignore-unfixed: true
-          exit-code: '1'
+          image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build-and-push.outputs.digest }}
+          platform: ${{ matrix.dockerPlatform }}
+          artifact-name: container-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.arch }}
+
+      - name: Record verified image digest
+        shell: bash
+        env:
+          IMAGE_DIGEST: ${{ steps.build-and-push.outputs.digest }}
+          IMAGE_ARCH: ${{ matrix.arch }}
+        run: |
+          set -euo pipefail
+          [[ "$IMAGE_DIGEST" =~ ^sha256:[a-f0-9]{64}$ ]]
+          mkdir -p dist/digests
+          printf '%s\n' "$IMAGE_DIGEST" > "dist/digests/linux-${IMAGE_ARCH}.txt"
+
+      - name: Upload verified image digest
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: image-digest-${{ matrix.os }}-${{ matrix.arch }}
+          path: dist/digests/*.txt
+          if-no-files-found: error
+          retention-days: 1
 
   publish:
     needs: [release-info, package-assets, build-docker-image]
@@ -515,8 +540,15 @@ jobs:
           name: release-assets
           path: dist/release
 
+      - name: Download verified image digests
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: image-digest-*
+          path: dist/digests
+          merge-multiple: true
+
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Install Cosign
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
@@ -546,7 +578,12 @@ jobs:
             platform="${platform//[[:space:]]/}"
             [ -n "${platform}" ] || continue
             arch="${platform##*/}"
-            sources+=("${image}:sha-${GIT_SHA}-${arch}")
+            digest="$(cat "dist/digests/linux-${arch}.txt")"
+            if [[ ! "$digest" =~ ^sha256:[a-f0-9]{64}$ ]]; then
+              echo "invalid verified image digest for ${platform}" >&2
+              exit 1
+            fi
+            sources+=("${image}@${digest}")
           done
 
           if [ "${#sources[@]}" -eq 0 ]; then
@@ -613,15 +650,10 @@ jobs:
 
           cosign sign --yes "${images[@]}"
 
-      - name: Publish GitHub Release
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
-        with:
-          tag_name: ${{ needs.release-info.outputs.tag }}
-          generate_release_notes: true
-          previous_tag: ${{ needs.release-info.outputs.previous_tag }}
-          prerelease: ${{ needs.release-info.outputs.prerelease == 'true' }}
-          make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
-          body: |
+      - name: Prepare release notes
+        shell: bash
+        env:
+          INSTALLATION_NOTES: |
             > [!WARNING]
             > **Upgrading across major versions?** Online upgrades across major versions are not supported. Deploy the new major fresh with a new `.runtime/` data directory, then re-import or re-authorize provider accounts and client keys. See the [upgrade notes](https://github.com/${{ github.repository }}/blob/main/deploy/README.md#镜像升级与源码构建).
 
@@ -642,6 +674,26 @@ jobs:
 
             - [GitHub Repository](https://github.com/${{ github.repository }})
             - [Installation Guide](https://github.com/${{ github.repository }}/blob/main/deploy/README.md)
+        run: |
+          python3 <<'PY'
+          import os
+          from pathlib import Path
+
+          notes = "\n".join(Path("release/notes.md").read_text().splitlines()[1:]).strip()
+          installation = os.environ["INSTALLATION_NOTES"].strip()
+          output = Path(os.environ["RUNNER_TEMP"]) / "release-notes.md"
+          output.write_text(f"{notes}\n\n{installation}\n")
+          PY
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
+        with:
+          tag_name: ${{ needs.release-info.outputs.tag }}
+          generate_release_notes: true
+          previous_tag: ${{ needs.release-info.outputs.previous_tag }}
+          prerelease: ${{ needs.release-info.outputs.prerelease == 'true' }}
+          make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
+          body_path: ${{ runner.temp }}/release-notes.md
           fail_on_unmatched_files: true
           files: |
             dist/release/*

.gitignore

@@ -33,7 +33,6 @@ Thumbs.db
 # Local tools and worktrees
 /.codegraph/
 /.codex-ws-audit/
-/.agents/
 /.reasonix/
 /.claude
 /.worktrees/

AGENTS.md

@@ -0,0 +1,47 @@
+# 项目协作约定
+
+开发和审查先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，使用其中的协作流程和审查标准。
+模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准；
+没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则。
+
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
+
+- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.
+- **Shell** (always works): `codegraph explore "<symbol names or question>"` and `codegraph node <symbol-or-file>` print the same output.
+
+If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision.
+<!-- CODEGRAPH_END -->
+
+## 工作方式
+
+- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题，以官方源码为首要参考确定或评估方案。
+- 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。
+- 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。
+- 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。
+- 审查请求默认只读。修复、提交、推送和合并按用户当前授权执行；“本地验证通过”不等于用户已经审阅批准。
+- 不读取或输出无关凭据，不把真实密钥、代理认证、账号令牌或请求转储放入提交、截图及审查报告。
+
+## Code Review Rules
+
+### 审查范围
+
+- 确认目标分支与当前变更范围，结合调用方、被调用方及已有测试审查；结论对应实际审查的提交或工作区状态。
+- 按 CONTRIBUTING.md 的维度检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称。
+- 重点核对现有架构和数据合同：共享业务事实是否重复解释，异步与并发操作是否破坏状态，权限和敏感数据是否越界，协议适配是否影响兼容性。
+- 修改既有特殊分支时先查场景和历史；放宽检查、修改测试或新增例外需要业务依据，不能仅以让检查通过为理由。
+
+### 代码与界面一致性
+
+- 对重复逻辑、冗余状态和多余抽象给出具体位置及影响；建议复用时指出已有实现，不能仅凭行数或语法相似判定质量。
+- UI 变更对照项目基础组件、主题和同类页面，检查交互、状态、响应式与可访问性。局部问题是否应在共用组件修复，按职责判断，不一律禁止局部样式。
+- 核对截图、预览和实际交互证据；未检查的状态明确列为验证缺口，不推断视觉验收已经通过。
+
+### 审查输出
+
+- 用中文先回答原问题是否成立、解决方向是否合理，依据与判断标准见 [贡献与审查](CONTRIBUTING.md#审查标准)，再报告实现问题和验证缺口。
+- 实现问题聚焦本次变更新引入或加重的、可定位的问题，包含文件位置、触发场景或规范依据、影响和最小修复方向。
+- 区分必须修复的问题、可选建议和验证缺口。个人偏好标为建议，不作为必须修复项；没有问题时不要凑数。
+- 严重程度按实际影响判断，不为绕过工具的优先级过滤而升级普通规范问题。说明审查和验证的实际覆盖范围，AI 未报告问题不等于维护者批准。

CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# 贡献与审查
+
+贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。
+
+本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。
+
+## 提交 Issue
+
+问题反馈使用仓库的 [Issue 表单](.github/ISSUE_TEMPLATE/bug_report.yml)，填写问题类型、描述、版本与环境、复现步骤和预期结果。接口问题补充平台与认证类型、模型、客户端，以及脱敏后的请求、响应和请求 ID；页面问题附相关截图或录屏。
+
+日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议与协作规则调整可直接提交 Issue，说明场景、原因和建议方案。
+
+## 问题与方案依据
+
+开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。
+
+涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。
+
+官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。
+
+反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口。
+
+## PR 流程
+
+1. **准备变更。** 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改与自查。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。
+2. **发起 PR。** 目标分支使用 `main`。说明问题成立的依据、触发场景、改动后的行为和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。界面改动提供截图、录屏或可复现的预览方式。一个 PR 围绕一个明确目标，必要重构说明关联原因。
+3. **自动检查与初审。** CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验。
+4. **修改与合并。** 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。
+
+AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求。
+
+### 项目技能
+
+仓库技能位于 `.agents/skills/`，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 `AGENTS.md` 为准。
+
+| 技能 | 用途 | 调用示例 |
+| --- | --- | --- |
+| [dev-guide](.agents/skills/dev-guide/SKILL.md) | 项目开发与文档导航 | `$dev-guide 修复当前问题` |
+| [github-pr](.agents/skills/github-pr/SKILL.md) | 创建或审查 PR | `$github-pr 创建当前分支的 PR` / `$github-pr 审查 PR #编号` |
+| [github-issue](.agents/skills/github-issue/SKILL.md) | 整理或提交 Issue | `$github-issue 提交当前问题` |
+| [release](.agents/skills/release/SKILL.md) | 准备发布说明或正式发版 | `$release 整理本次发布说明` / `$release 发布 vX.Y.Z` |
+
+审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查。
+
+### 规则文件保护
+
+PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。
+
+源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流。
+
+## 审查标准
+
+按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告。
+
+结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证。
+
+| 维度 | 检查重点 |
+| --- | --- |
+| 设计与架构 | 职责归属、依赖方向、公开接口是否合理；是否融入已有体系，有无绕过边界的旁路 |
+| 正确性与兼容性 | 正常、异常和边界输入；并发、取消、重试与副作用；是否改变既有 API、协议或数据合同 |
+| 安全与数据 | 权限、输入校验、敏感信息、状态隔离和持久化一致性；日志与诊断是否符合脱敏边界 |
+| 简洁性与复用 | 重复业务规则、冗余状态、无效代码和过早抽象；能否用更直接的实现解决当前问题 |
+| 性能与资源 | 实际数据规模下的查询、请求、内存与连接成本；资源释放、背压和异常时的生命周期 |
+| 可读性与风格 | 命名是否准确，控制流是否易懂，格式是否一致；注释解释约束与原因而非复述代码 |
+| 测试与验证 | 是否覆盖真实触发条件和结果，能否发现回归；证据是否对应本次变更，有无跳过或缺失项 |
+| 界面与交互 | 共用组件和主题、信息层级、状态反馈、响应式、键盘操作及可访问性；是否有实际页面证据 |
+| 文档与升级 | 行为、配置、API 和部署说明是否同步；数据迁移和兼容影响是否交代清楚 |
+
+审查意见区分三类：
+
+- **必须修复：** 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向。
+- **建议：** 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构。
+- **验证缺口：** 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷。
+
+复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则。
+
+## 项目约定
+
+- Rust 模块、可见性、依赖方向和测试目录按架构文档执行，使用现有 Rustfmt 与 Clippy 配置。
+- Vue 使用 TypeScript、`<script setup>` 和现有 ESLint 配置；API 请求通过已有模块及 `request` 封装，沿用逐行请求配置格式。
+- 业务数据的解析、校验和展示优先复用已有逻辑。新增抽象放在拥有该职责的模块，避免重复事实源或无实际需求的通用层。
+- 新增代码注释使用中文。提交信息使用英文 Conventional Commits，参考近期历史，按完整功能归并；确由 Codex 参与的提交保留 `Co-authored-by: Codex <noreply@openai.com>`。
+- 发布说明写入 `release/notes.md`，标题首行为目标版本的 `# vX.Y.Z`，章节标题和正文使用中文；命令、配置键、协议名等保留原文。只说明本次版本的实际变化，按影响交代升级事项。
+- PR 聚焦目标；无关格式化、重构和依赖升级单独处理。改动使现有说明失真或缺少必要信息时，按文档职责修订对应内容；变更经过留在 PR，发布说明按维护者的发布安排更新。
+
+## 界面验证
+
+开发前查找同类页面及 `components/base` 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
+
+列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。
+
+提交者在浏览器中验证受影响路径，提供前后截图、录屏或预览步骤，并标明实际覆盖的状态。按变更选择浅色/深色、窄窗口、空/加载/错误状态、大量数据及键盘操作；共用主题或基础组件变更按主题文档扩大验证范围。模拟数据与预览材料不包含真实凭据。
+
+涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。
+
+## 验证
+
+选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言。
+
+| 范围 | 现有检查 | 仍需提供的证据 |
+| --- | --- | --- |
+| Rust | Rustfmt、严格 Clippy、后端测试、架构边界检查 | 相关失败场景和集成行为 |
+| 前端 | ESLint、类型检查与构建 | 页面一致性、交互和实际数据状态 |
+| 数据库迁移 | 冻结清单校验与 PR 基线比对 | 升级行为及兼容说明 |
+| 依赖安全 | Cargo Audit、pnpm Audit | 本次变更的权限、数据与信任边界 |
+| 工作流与容器 | Actionlint、相关容器检查 | 改动涉及的运行行为 |
+
+前端从仓库根目录执行：
+
+```bash
+pnpm --dir frontend format:check
+pnpm --dir frontend build
+git diff --check
+```
+
+`build` 已包含类型检查；不维护独立前端测试代码。后端的工具链、命令与线程栈设置统一见 [修改与验收](docs/architecture.md#12-修改与验收)。
+
+依赖 PostgreSQL / Redis 的测试使用 [专用测试环境](backend/migrations/README.md#本地测试库)，未配置导致跳过时明确记录。CI 中已有对应服务和检查，见 [质量工作流](.github/workflows/_quality.yml) 与 [安全扫描](.github/workflows/security-scan.yml)。
+
+集成变更应验证实际业务路径及结果，不能只凭健康检查或探测成功认定全链路正常。协议和网络改动按需核对认证、证书、代理、流式交付及客户端结果；记录影响复现的环境条件。缺少运行条件时说明缺口，不用模拟结果代替真实集成结论。
+
+## 自动检查与合并条件
+
+[CI](.github/workflows/ci.yml) 已按变更范围调用现有质量检查。新增自动规则优先使用现有工具，要求依据明确、结果稳定、误报可控；无法可靠判定的设计与视觉问题保留审查判断，避免把具体源码写法锁成测试。
+
+AI 自动审查需要在所用工具中单独启用。其支持的检查范围和优先级过滤以工具说明为准；即使能读取 `AGENTS.md`，也不能保证所有可维护性和视觉问题都会被报告。配置参考 [Codex GitHub 审查文档](https://learn.chatgpt.com/docs/third-party/github)。
+
+要由 GitHub 强制执行合并条件，维护者需配置对应分支的必需状态检查、审阅批准和讨论解决要求，并按需要设置新提交后的重新审阅。配置前核对实际检查名称与触发范围，见 [GitHub 分支保护](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)。规则文档本身不会启用 AI 服务或更改分支设置。

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -5,192 +5,110 @@
 
 # Codex Proxy RS
 
-**基于 Rust 的多 Provider 透明 AI 网关**
+面向 Codex 的自托管多账号 AI 网关
 
 [![CI](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/zyycn/codex-proxy-rs?display_name=tag&sort=semver&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/releases)
 [![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
-[![MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/license/mit)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
 
-[快速开始](#快速开始) · [客户端接入](#客户端接入) · [运维](#运维) · [部署](deploy/README.md) · [接口](docs/api.md) · [架构](docs/architecture.md)
+[快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
 
 </div>
 
 > [!NOTE]
-> 只支持 OpenAI Responses API，不提供 `/v1/chat/completions`。
-
-## 能力
-
-| 领域     | 实现                                                                                                  |
-| -------- | ----------------------------------------------------------------------------------------------------- |
-| 协议     | OpenAI Responses JSON、SSE、WebSocket 与模型目录                                                       |
-| Provider | 固定 OpenAI、xAI 两个 Provider；各自管理 OAuth、账号、额度与模型目录                                    |
-| 路由     | Client Key 绑定 Provider、全局模型映射、会话亲和与同 Provider 安全 fallback                             |
-| 透明边界 | OpenAI 请求保留未知字段和字段顺序，SSE 与 WebSocket 原样转发业务字节；xAI 在 Provider 内做协议转换          |
-| 延续     | OpenAI native/replay continuation；xAI 使用客户端提交的完整历史                                          |
-| 账号     | 导入、OAuth、credential 刷新、主动额度刷新，以及正常响应中的被动额度/状态观测                              |
-| 管理     | Client Key、账号、模型目录、设置、观测、系统更新与 OAuth                                                 |
-| 计量     | 模型请求 Token、费用、延迟、账号与 Provider 归因，并记录响应确认的实际 `service_tier`                      |
+> 本项目提供 Responses API，不支持 `/v1/chat/completions`。接入前请确认客户端支持 Responses 协议。
 
 ## 快速开始
 
-需要 Docker Engine 与 Docker Compose Plugin。
+使用 Docker Compose 部署发布镜像 `ghcr.io/zyycn/codex-proxy-rs:latest`，同时启动 PostgreSQL 和 Redis。
+以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。已有部署请先看
+[升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置。
 
-### 1. 准备
+### 1. 下载部署文件并配置
 
 ```bash
-git clone https://github.com/zyycn/codex-proxy-rs.git
-cd codex-proxy-rs
+mkdir -p codex-proxy-rs/deploy && cd codex-proxy-rs
+
+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/compose.yaml \
+  -o deploy/compose.yaml
+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/config.example.yaml \
+  -o deploy/config.example.yaml
 
-mkdir -p .runtime/data .runtime/logs
 install -d -m 0750 .runtime/postgres .runtime/redis
-cp deploy/config.example.yaml deploy/config.yaml
-sudo chown "$(id -u):10001" deploy/config.yaml
-chmod 0640 deploy/config.yaml
+sudo install -d -m 0770 -o "$(id -u)" -g 10001 .runtime/data .runtime/logs
+sudo install -m 0640 -o "$(id -u)" -g 10001 deploy/config.example.yaml deploy/config.yaml
 ```
 
-分别生成 PostgreSQL 与 Redis 密码：
+分别生成数据库和 Redis 密码：
 
 ```bash
 openssl rand -hex 24
 openssl rand -hex 24
 ```
 
-把两个结果写入 `deploy/config.yaml`，并单独设置管理员初始密码：
+编辑 `deploy/config.yaml`，填好以下三项：
 
-| 配置                       | 约束                         |
-| -------------------------- | ---------------------------- |
-| `store.database.password`  | 48 位十六进制                 |
-| `store.redis.password`     | 48 位十六进制                 |
-| `admin.default_password`   | 至少 12 位，不能包含 `$`      |
+| 配置项 | 填写内容 |
+| --- | --- |
+| `store.database.password` | 第一个生成的 48 位十六进制密码 |
+| `store.redis.password` | 第二个生成的 48 位十六进制密码 |
+| `admin.default_password` | 管理员初始密码，至少 12 位，不能包含 `$` |
 
-PostgreSQL、Redis 容器和应用通过同一份 `config.yaml` 使用这两个基础设施密码，不需要额外
-导出环境变量。管理员密码只在首次创建管理员时生效。
-
-Linux 需要允许容器组写入运行目录：
-
-```bash
-sudo chown -R "$(id -u):10001" .runtime/data .runtime/logs
-chmod 0770 .runtime/data .runtime/logs
-```
-
-### 2. 启动
+### 2. 启动服务
 
 ```bash
 docker compose -f deploy/compose.yaml config --quiet
 docker compose -f deploy/compose.yaml pull
-docker compose -f deploy/compose.yaml up -d --no-build
+docker compose -f deploy/compose.yaml up -d --no-build --wait
 curl -i http://127.0.0.1:8080/healthz
 ```
 
-`204 No Content` 表示应用、PostgreSQL 与 Redis 均可用。管理端地址：
-`http://127.0.0.1:8080`。
+健康检查返回 `204 No Content` 后，打开 `http://127.0.0.1:8080`，
+使用 `admin@cpr.local` 和刚设置的管理员密码登录。
 
-### 3. 初始化
+默认地址只能在服务器本机访问。从其他设备使用时，需要配置
+[HTTPS 反向代理](deploy/README.md#公网访问)。
 
-1. 使用 `admin@cpr.local` 与初始密码登录。
-2. 在账号页选择对应 Provider：OpenAI 支持 OAuth、账号文件与 Agent Identity；xAI 支持 OAuth
-   和兼容账号文件导入。
-3. 按需配置客户端模型到上游模型的全局映射；未命中映射的模型名原样透传。
-4. 创建 `sk_...` Client Key，绑定 `openai` 或 `xai`，并设置速率与并发限制。
+### 3. 添加账号与客户端密钥
 
-OpenAI 账号导入和首次 OAuth 创建在 credential 提交后会立即尝试一次额度观测；额度接口临时失败不会
-回滚已提交的账号。Free、K12 等套餐共用同一套额度与状态转换逻辑，套餐字段只作为账号事实并隔离
-对应的模型目录 cache。credential 刷新、额度刷新和正常请求中的被动额度观测是三条独立链路，详见
-[账号接口](docs/api.md#5-账号)。
-
-> [!IMPORTANT]
-> xAI 使用 OAuth session，不支持把 xAI API Key 作为上游 credential。
-
-> [!NOTE]
-> `admin.default_password` 只在首次创建管理员时生效。
-
-完整部署、权限和密码轮换规则见 [deploy/README.md](deploy/README.md)。
+1. 在「账号」中添加账号，完成授权或导入。
+2. 按需建立账号分组，再创建客户端密钥并选择可用分组。**不选分组表示可使用全部账号**。
+3. 打开密钥的「使用密钥」，复制客户端配置。
 
 ## 客户端接入
 
-| 配置     | 值                                       |
-| -------- | ---------------------------------------- |
-| Base URL | `http://127.0.0.1:8080/v1`               |
-| API Key  | 管理端创建的 `sk_...`                    |
-| 鉴权     | `Authorization: Bearer <client-api-key>` |
+**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，或通过 CCSwitch 导入。
+合并到客户端配置后重启 Codex。完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)。
+
+**其他 Responses API 客户端**：填写以下信息。
+
+| 配置 | 值 |
+| --- | --- |
+| Base URL | `http://127.0.0.1:8080/v1`；远程接入使用服务器的 HTTPS 地址 |
+| API Key | 管理端创建的客户端密钥 |
+
+可用模型以该密钥查询到的模型列表为准：
 
 ```bash
 curl http://127.0.0.1:8080/v1/models \
   -H 'Authorization: Bearer <client-api-key>'
-
-curl http://127.0.0.1:8080/v1/responses \
-  -H 'Authorization: Bearer <client-api-key>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "model": "<model-id>",
-    "input": "Reply with pong.",
-    "stream": false
-  }'
 ```
 
-<details>
-<summary>API 路由</summary>
-
-| 路由                               | 用途                           |
-| ---------------------------------- | ------------------------------ |
-| `POST /v1/responses`               | JSON 响应或 SSE Responses 流    |
-| `GET /v1/responses`                | Responses WebSocket 升级        |
-| `POST /v1/responses/review`        | review 子代理请求               |
-| `GET /v1/models`                   | 当前 Client Key 可用的模型列表   |
-| `GET /v1/models/catalog`           | Codex 客户端展示用模型目录      |
-| `GET /v1/models/{model_id}/info`   | Codex 客户端展示用模型详情      |
-| `GET /v1/models/{model_id}`        | OpenAI 兼容模型详情             |
-
-所有 `/v1/*` 路由都需要客户端 API Key。
-
-</details>
-
-完整的客户端与管理端路由、鉴权和 mutation 规则见 [接口文档](docs/api.md)。
-
-## 运维
-
-```bash
-# 实例升级
-docker compose -f deploy/compose.yaml pull codex-proxy-rs
-docker compose -f deploy/compose.yaml up -d --no-build
-
-# 日志
-docker compose -f deploy/compose.yaml logs -f codex-proxy-rs
-
-# 从源码构建
-docker compose -f deploy/compose.yaml build codex-proxy-rs
-docker compose -f deploy/compose.yaml up -d
-```
-
-> [!IMPORTANT]
-> `.runtime/` 保存 PostgreSQL、Redis、日志、OpenAI 会话锚点密钥和自更新状态。删除该目录会永久清除
-> 运行状态。
-
-> [!WARNING]
-> 不支持跨大版本在线升级。升级到新的大版本时，请使用全新的 `.runtime/` 数据目录重新部署，
-> 并重新导入或重新授权 Provider 账号与客户端 Key。
-
-Compose 默认只绑定 `127.0.0.1`。公网接入应使用 HTTPS 反向代理，转发 WebSocket
-upgrade 与真实客户端 IP；不要暴露 PostgreSQL 或 Redis。
-
-## 维护与发布
-
-发布仓库版本必须从干净、已同步上游的发布分支运行：
-
-```bash
-release/publish <version>
-```
-
-脚本依赖已登录的 GitHub CLI（`gh auth login`）。它会更新 `release/version.yaml`、创建约定提交与带
-注释的 `v<version>` tag，原子推送分支和 tag，再从发布分支触发 Release 构建，使构建缓存可以跨版本
-复用。不要手工修改版本后单独打 tag。该脚本不会登录服务器，也不会改变任何运行实例；源码提交、
-仓库发版和实例升级是三个独立状态。
-
 ## 文档
 
-- [部署](deploy/README.md)
-- [客户端与管理端接口](docs/api.md)
-- [架构与数据边界](docs/architecture.md)
-- [Release](https://github.com/zyycn/codex-proxy-rs/releases)
-- [容器镜像](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
+- [客户端接入与生图](deploy/README.md#客户端配置)
+- [部署、备份与恢复](deploy/README.md)
+- [API 参考](docs/api.md)
+- [系统架构](docs/architecture.md)
+- [管理端主题](docs/theme.md)
+- [数据库迁移](backend/migrations/README.md)
+- [贡献与审查](CONTRIBUTING.md)
+
+## 社区
+
+感谢 [LINUX DO](https://linux.do) 社区提供开放、友善的技术交流平台。
+
+## 许可证
+
+本项目基于 [Apache License 2.0](LICENSE) 开源。

backend/Cargo.toml

@@ -15,7 +15,7 @@ resolver = "3"
 [workspace.package]
 version = "0.0.0"
 edition = "2024"
-license = "MIT"
+license = "Apache-2.0"
 publish = false
 rust-version = "1.97"
 
@@ -38,3 +38,7 @@ strip = "symbols"
 lto = "thin"
 codegen-units = 1
 panic = "abort"
+
+[patch.crates-io]
+# Upstream SOCKS IPv6 fix; remove once a release includes hyperium/hyper-util#302.
+hyper-util = { git = "https://github.com/hyperium/hyper-util", rev = "191b1acf0a6b18e807e4abf5a6d4a7c47979ecd6" }

backend/apps/gateway/Cargo.toml

@@ -26,8 +26,9 @@ tokio = { version = "1.52.3", default-features = false, features = ["rt-multi-th
 [dev-dependencies]
 config = { version = "0.15.23", default-features = false, features = ["yaml"] }
 serde_json = "1"
-syn = { version = "3.0.3", features = ["full"] }
+syn = { version = "3.0.3", features = ["full", "visit"] }
 tempfile = "3.27.0"
+tokio-rustls = { version = "=0.26.4", default-features = false }
 
 [lints]
 workspace = true

backend/apps/gateway/src/bootstrap.rs

@@ -27,8 +27,9 @@ impl LoadableConfig for GatewayConfig {
             return Err(ConfigError::InvalidField("schema_version"));
         }
         self.host.resolve_and_validate(source_dir)?;
+        let runtime_data_dir = self.host.runtime_data_dir().to_path_buf();
         self.store
-            .resolve_and_validate(source_dir)
+            .resolve_and_validate(&runtime_data_dir)
             .map_err(|_| ConfigError::InvalidField("store"))?;
         self.admin
             .resolve_and_validate(source_dir)
@@ -37,7 +38,7 @@ impl LoadableConfig for GatewayConfig {
             .resolve_and_validate(source_dir)
             .map_err(|_| ConfigError::InvalidField("api"))?;
         self.openai
-            .resolve_and_validate(source_dir)
+            .resolve_and_validate(&runtime_data_dir)
             .map_err(|_| ConfigError::InvalidField("openai"))?;
         self.xai
             .resolve_and_validate(source_dir)
@@ -77,7 +78,11 @@ pub async fn run() -> Result<(), BootstrapError> {
         store.admin_ports(),
         vec![openai.admin_provider(), xai.admin_provider()],
         core.snapshot_control(),
-        core.account_probe(),
+        (
+            core.account_probe(),
+            host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
+        ),
+        host.client_distribution_resolver(),
         host.system_operations(),
     )
     .await?;
@@ -85,6 +90,7 @@ pub async fn run() -> Result<(), BootstrapError> {
 
     let mut probes = store.health_probes();
     probes.extend(core.health_probes());
+    probes.push(host.logging_health_probe());
     let api = gateway_api::initialize(
         api,
         core.execution_service(),

backend/apps/gateway/src/main.rs

@@ -1,6 +1,6 @@
 use std::{env, error::Error, io};
 
-use provider_openai::transport::tls::ensure_rustls_provider;
+use provider_openai::ensure_rustls_provider;
 
 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
     ensure_rustls_provider();

backend/apps/gateway/tests/architecture.rs

@@ -1,12 +1,15 @@
 //! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验。
 
 use std::{
+    collections::{BTreeMap, BTreeSet},
     fs,
     path::{Path, PathBuf},
 };
 
+use syn::{Item, visit::Visit};
+
 /// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
-const WORKSPACE_MEMBERS: &[&str] = &[
+pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
     "apps/gateway",
     "crates/gateway-admin",
     "crates/gateway-api",
@@ -58,6 +61,82 @@ fn gateway_core_depends_on_no_http_db_redis_or_provider_crate() {
     );
 }
 
+#[test]
+fn core_value_owners_do_not_depend_on_execution_or_routing() {
+    let root = backend_root().join("crates/gateway-core/src");
+    for relative in super::rust_files(&root) {
+        let allowed: Option<&[&str]> = match relative.to_str().expect("source path") {
+            "validation.rs" => Some(&[]),
+            "identity.rs" => Some(&["validation"]),
+            "upstream.rs" => Some(&["validation"]),
+            "event.rs" => Some(&["metering", "operation", "upstream", "validation"]),
+            "account/store.rs" => Some(&["account", "error", "identity", "validation"]),
+            path if path.starts_with("policy/") => Some(&["account", "policy", "validation"]),
+            path if path.starts_with("account/") => Some(&["account", "identity", "validation"]),
+            _ => None,
+        };
+        let Some(allowed) = allowed else { continue };
+        let source = fs::read_to_string(root.join(&relative)).expect("read core source");
+        let syntax = syn::parse_file(&source).expect("parse core source");
+        let mut references = CrateReferences::default();
+        references.visit_file(&syntax);
+        for dependency in references.0 {
+            assert!(
+                allowed.contains(&dependency.as_str()),
+                "{} must not depend on crate::{dependency}",
+                relative.display()
+            );
+        }
+    }
+}
+
+#[derive(Default)]
+struct CrateReferences(BTreeSet<String>);
+
+impl<'ast> Visit<'ast> for CrateReferences {
+    fn visit_path(&mut self, path: &'ast syn::Path) {
+        let mut segments = path.segments.iter();
+        if segments
+            .next()
+            .is_some_and(|segment| segment.ident == "crate")
+            && let Some(owner) = segments.next()
+        {
+            self.0.insert(owner.ident.to_string());
+        }
+        syn::visit::visit_path(self, path);
+    }
+
+    fn visit_item_use(&mut self, item: &'ast syn::ItemUse) {
+        self.use_tree(&item.tree, false);
+    }
+}
+
+impl CrateReferences {
+    fn use_tree(&mut self, tree: &syn::UseTree, crate_root: bool) {
+        match tree {
+            syn::UseTree::Path(path) if crate_root => {
+                self.0.insert(path.ident.to_string());
+            }
+            syn::UseTree::Name(name) if crate_root => {
+                self.0.insert(name.ident.to_string());
+            }
+            syn::UseTree::Rename(rename) if crate_root => {
+                self.0.insert(rename.ident.to_string());
+            }
+            syn::UseTree::Path(path) => self.use_tree(&path.tree, path.ident == "crate"),
+            syn::UseTree::Group(group) => {
+                for item in &group.items {
+                    self.use_tree(item, crate_root);
+                }
+            }
+            syn::UseTree::Glob(_) if crate_root => {
+                self.0.insert("*".to_owned());
+            }
+            _ => {}
+        }
+    }
+}
+
 #[test]
 fn gateway_protocol_has_no_workspace_dependencies() {
     for name in dependency_names("crates/gateway-protocol") {
@@ -95,6 +174,37 @@ const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
     ("provider-xai", "crates/providers/xai"),
 ];
 
+/// Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
+    ("crates/gateway-api", &["admin", "openai"]),
+    (
+        "crates/gateway-host",
+        &[
+            "client_distribution",
+            "config",
+            "proxy_probe",
+            "serve",
+            "system_update",
+            "workers",
+        ],
+    ),
+    ("crates/gateway-store", &["backup", "postgres", "redis"]),
+    (
+        "crates/providers/openai",
+        &["config", "credential", "transport"],
+    ),
+    (
+        "crates/providers/xai",
+        &["config", "credential", "transport"],
+    ),
+];
+
+/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景。
+const ROOT_TEST_SCENARIOS: &[(&str, &[&str])] = &[
+    ("apps/gateway", &["architecture"]),
+    ("crates/gateway-api", &["architecture"]),
+];
+
 /// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表。
 const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
     ("codex-proxy-rs", "gateway-admin"),
@@ -123,6 +233,46 @@ const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
 #[test]
 fn workspace_internal_dependency_edges_match_frozen_dag() {
     let metadata = cargo_metadata_json();
+    let actual = workspace_runtime_dependency_edges(&metadata);
+    let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
+        .iter()
+        .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
+        .collect();
+    expected.sort();
+
+    assert_eq!(
+        actual, expected,
+        "workspace internal dependency edges diverged from the frozen DAG"
+    );
+}
+
+#[test]
+fn runtime_dependency_edges_exclude_dev_build_and_external_dependencies() {
+    let metadata = serde_json::json!({
+        "packages": [
+            {
+                "name": "gateway-api",
+                "dependencies": [
+                    { "name": "gateway-core", "kind": null },
+                    { "name": "gateway-store", "kind": "dev" },
+                    { "name": "gateway-host", "kind": "build" },
+                    { "name": "serde", "kind": null }
+                ]
+            },
+            {
+                "name": "external-package",
+                "dependencies": [{ "name": "gateway-core", "kind": null }]
+            }
+        ]
+    });
+
+    assert_eq!(
+        workspace_runtime_dependency_edges(&metadata),
+        vec![("gateway-api".to_owned(), "gateway-core".to_owned())]
+    );
+}
+
+fn workspace_runtime_dependency_edges(metadata: &serde_json::Value) -> Vec<(String, String)> {
     let packages = metadata["packages"]
         .as_array()
         .expect("cargo metadata packages");
@@ -140,31 +290,43 @@ fn workspace_internal_dependency_edges_match_frozen_dag() {
             if !internal_names.contains(dep_name) {
                 continue;
             }
-            let is_runtime_edge = dependency["dep_kinds"]
-                .as_array()
-                .map(|kinds| {
-                    kinds
-                        .iter()
-                        .any(|kind| kind["kind"].as_str() == Some("normal"))
-                })
-                .unwrap_or(true);
-            if is_runtime_edge {
+            if dependency.get("kind").expect("dependency kind").is_null() {
                 actual.push((name.to_owned(), dep_name.to_owned()));
             }
         }
     }
 
-    let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
-        .iter()
-        .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
-        .collect();
     actual.sort();
-    expected.sort();
+    actual
+}
 
-    assert_eq!(
-        actual, expected,
-        "workspace internal dependency edges diverged from the frozen DAG"
-    );
+#[test]
+fn adapter_public_module_surfaces_match_allowlist() {
+    for (member, allowed) in ADAPTER_PUBLIC_MODULES {
+        let root = backend_root().join(member).join("src/lib.rs");
+        let source = fs::read_to_string(&root).expect("read adapter crate root");
+        let syntax = syn::parse_file(&source).expect("parse adapter crate root");
+        let actual = syntax
+            .items
+            .iter()
+            .filter_map(|item| match item {
+                Item::Mod(module) if matches!(module.vis, syn::Visibility::Public(_)) => {
+                    Some(module.ident.to_string())
+                }
+                _ => None,
+            })
+            .collect::<BTreeSet<_>>();
+        let expected = allowed
+            .iter()
+            .map(|module| (*module).to_owned())
+            .collect::<BTreeSet<_>>();
+        assert_eq!(
+            actual,
+            expected,
+            "{} public module surface diverged from its allowlist",
+            root.display()
+        );
+    }
 }
 
 #[test]
@@ -185,7 +347,192 @@ fn production_sources_do_not_host_tests() {
     }
 }
 
-fn backend_root() -> PathBuf {
+#[test]
+fn workspace_modules_follow_conventional_file_layout() {
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        assert_module_tree(&member_root.join("src"), &["lib.rs", "main.rs"]);
+
+        let tests = member_root.join("tests");
+        if tests.is_dir() {
+            assert_module_tree(&tests, &["main.rs"]);
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ModuleLayout {
+    File,
+    Directory,
+}
+
+#[test]
+fn integration_tests_mirror_production_module_tree() {
+    for member in WORKSPACE_MEMBERS {
+        let member_root = backend_root().join(member);
+        let tests_root = member_root.join("tests");
+        if !tests_root.is_dir() {
+            continue;
+        }
+
+        let production = module_layouts(&member_root.join("src"), &["lib.rs", "main.rs"]);
+        let tests = module_layouts(&tests_root, &["main.rs"]);
+        for (module, test_layout) in tests {
+            if module == Path::new("support") {
+                continue;
+            }
+
+            if let Some(production_layout) = production.get(&module) {
+                assert_eq!(
+                    test_layout,
+                    *production_layout,
+                    "{} must mirror the production module layout for {}",
+                    tests_root.join(module.with_extension("rs")).display(),
+                    member_root.join("src").join(&module).display(),
+                );
+                continue;
+            }
+
+            let has_production_owner = module
+                .parent()
+                .into_iter()
+                .flat_map(Path::ancestors)
+                .take_while(|ancestor| !ancestor.as_os_str().is_empty())
+                .any(|ancestor| production.contains_key(ancestor));
+            assert!(
+                has_production_owner || root_test_scenario_allowed(member, &module),
+                "{} has no mirrored production module owner",
+                tests_root.join(module.with_extension("rs")).display(),
+            );
+        }
+    }
+}
+
+fn module_layouts(root: &Path, crate_roots: &[&str]) -> BTreeMap<PathBuf, ModuleLayout> {
+    super::rust_files(root)
+        .into_iter()
+        .filter(|relative| {
+            !crate_roots
+                .iter()
+                .any(|candidate| relative == Path::new(candidate))
+        })
+        .map(|relative| {
+            if relative.file_name().and_then(|value| value.to_str()) == Some("mod.rs") {
+                (
+                    relative.parent().expect("mod.rs parent").to_path_buf(),
+                    ModuleLayout::Directory,
+                )
+            } else {
+                (relative.with_extension(""), ModuleLayout::File)
+            }
+        })
+        .collect()
+}
+
+fn root_test_scenario_allowed(member: &str, module: &Path) -> bool {
+    let Some(module) = module.to_str() else {
+        return false;
+    };
+    ROOT_TEST_SCENARIOS
+        .iter()
+        .any(|(candidate, scenarios)| *candidate == member && scenarios.contains(&module))
+}
+
+fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
+    let files = super::rust_files(root);
+    for relative in &files {
+        if crate_roots
+            .iter()
+            .any(|candidate| relative == Path::new(candidate))
+        {
+            continue;
+        }
+
+        let file_name = relative
+            .file_name()
+            .and_then(|value| value.to_str())
+            .expect("Rust source file name");
+        let parent = relative.parent().expect("Rust source parent");
+        let module_name = if file_name == "mod.rs" {
+            parent
+                .file_name()
+                .and_then(|value| value.to_str())
+                .expect("mod.rs module name")
+        } else {
+            relative
+                .file_stem()
+                .and_then(|value| value.to_str())
+                .expect("Rust source module name")
+        };
+
+        if file_name != "mod.rs" {
+            assert_ne!(
+                parent.file_name().and_then(|value| value.to_str()),
+                Some(module_name),
+                "{} repeats its parent module name",
+                root.join(relative).display()
+            );
+            let child_directory = relative.with_extension("");
+            assert!(
+                !files
+                    .iter()
+                    .any(|candidate| candidate.starts_with(&child_directory)),
+                "{} mixes a leaf module with a same-name module directory",
+                root.join(relative).display()
+            );
+        }
+
+        let declaration_parents = if parent.as_os_str().is_empty()
+            || (file_name == "mod.rs"
+                && parent
+                    .parent()
+                    .is_some_and(|ancestor| ancestor.as_os_str().is_empty()))
+        {
+            crate_roots
+                .iter()
+                .map(|candidate| root.join(candidate))
+                .collect::<Vec<_>>()
+        } else {
+            let declaration_directory = if file_name == "mod.rs" {
+                parent.parent().expect("nested mod.rs parent")
+            } else {
+                parent
+            };
+            vec![root.join(declaration_directory).join("mod.rs")]
+        };
+        let declaration_count = declaration_parents
+            .iter()
+            .map(|path| external_module_declaration_count(path, module_name))
+            .sum::<usize>();
+        assert_eq!(
+            declaration_count,
+            1,
+            "{} must be declared exactly once by its parent module",
+            root.join(relative).display()
+        );
+    }
+}
+
+fn external_module_declaration_count(path: &Path, module_name: &str) -> usize {
+    if !path.is_file() {
+        return 0;
+    }
+    let source = fs::read_to_string(path).expect("read parent module source");
+    let syntax = syn::parse_file(&source).expect("parse parent module source");
+    syntax
+        .items
+        .iter()
+        .filter(|item| {
+            matches!(
+                item,
+                Item::Mod(module)
+                    if module.content.is_none() && module.ident == module_name
+            )
+        })
+        .count()
+}
+
+pub(super) fn backend_root() -> PathBuf {
     Path::new(env!("CARGO_MANIFEST_DIR"))
         .join("../..")
         .canonicalize()

backend/apps/gateway/tests/bootstrap.rs

@@ -9,6 +9,151 @@ const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
 const ADMIN_PASSWORD: &str = "test-admin-password";
 const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";
 
+#[tokio::test]
+async fn proxy_probe_should_use_provider_custom_ca_for_https_proxies() {
+    use gateway_admin::ports::proxy::ProxyProbe;
+    use gateway_core::account::OutboundProxy;
+    use gateway_host::proxy_probe::HttpProxyProbe;
+    use std::{sync::Arc, time::Duration};
+    use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+    use tokio_rustls::{
+        TlsAcceptor,
+        rustls::{
+            ServerConfig,
+            pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject as _},
+        },
+    };
+
+    const CHILD_ENV: &str = "CPR_TEST_PROXY_TLS_DIRECTORY";
+    let Ok(directory) = std::env::var(CHILD_ENV) else {
+        let directory = tempfile::tempdir().unwrap();
+        generate_proxy_test_certificates(directory.path());
+        // 使用子进程隔离环境变量，避免并行测试读取到临时 CA 配置。
+        for ca_env in ["CODEX_CA_CERTIFICATE", "SSL_CERT_FILE"] {
+            let mut child = Command::new(std::env::current_exe().unwrap());
+            child
+                .args([
+                    "--exact",
+                    "bootstrap::proxy_probe_should_use_provider_custom_ca_for_https_proxies",
+                    "--nocapture",
+                ])
+                .env(CHILD_ENV, directory.path())
+                .env_remove("CODEX_CA_CERTIFICATE")
+                .env_remove("SSL_CERT_FILE")
+                .env(ca_env, directory.path().join("ca.pem"));
+            if ca_env == "CODEX_CA_CERTIFICATE" {
+                child.env(
+                    "SSL_CERT_FILE",
+                    directory.path().join("missing-fallback.pem"),
+                );
+            }
+            let output = child.output().unwrap();
+            assert!(
+                output.status.success(),
+                "{ca_env}: {}\n{}",
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+        }
+        return;
+    };
+    provider_openai::ensure_rustls_provider();
+    let directory = std::path::Path::new(&directory);
+    let certificate = CertificateDer::from_pem_file(directory.join("server.pem")).unwrap();
+    let key = PrivateKeyDer::from_pem_file(directory.join("server.key")).unwrap();
+    let acceptor = TlsAcceptor::from(Arc::new(
+        ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(vec![certificate], key)
+            .unwrap(),
+    ));
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let proxy =
+        OutboundProxy::parse(&format!("https://{}", listener.local_addr().unwrap())).unwrap();
+    let server = tokio::spawn(async move {
+        let (socket, _) = listener.accept().await.unwrap();
+        let mut stream = acceptor.accept(socket).await.unwrap();
+        let mut request = Vec::new();
+        while !request.ends_with(b"\r\n\r\n") {
+            assert!(request.len() < 8192);
+            request.push(stream.read_u8().await.unwrap());
+        }
+        assert!(request.starts_with(b"GET http://unresolvable.invalid/ip "));
+        let body = "{\"ip\":\"203.0.113.8\"}";
+        stream.write_all(format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).as_bytes()).await.unwrap();
+        stream.shutdown().await.unwrap();
+    });
+    let probe = HttpProxyProbe::new("http://unresolvable.invalid/ip")
+        .with_client_builder(provider_openai::build_reqwest_client_with_custom_ca);
+    let result = probe.test(&proxy).await;
+    assert!(result.success, "{}", result.message);
+    assert_eq!(result.exit_ip.unwrap().to_string(), "203.0.113.8");
+    tokio::time::timeout(Duration::from_secs(5), server)
+        .await
+        .unwrap()
+        .unwrap();
+}
+
+fn generate_proxy_test_certificates(directory: &std::path::Path) {
+    let openssl = |args: &[&str]| {
+        let output = Command::new("openssl")
+            .args(args)
+            .current_dir(directory)
+            .output()
+            .unwrap();
+        assert!(
+            output.status.success(),
+            "{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    };
+    openssl(&[
+        "req",
+        "-x509",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        "ca.key",
+        "-out",
+        "ca.pem",
+        "-days",
+        "1",
+        "-subj",
+        "/CN=Proxy Test CA",
+    ]);
+    openssl(&[
+        "req",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        "server.key",
+        "-out",
+        "server.csr",
+        "-subj",
+        "/CN=localhost",
+    ]);
+    fs::write(directory.join("extensions"), "subjectAltName=IP:127.0.0.1\nbasicConstraints=critical,CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n").unwrap();
+    openssl(&[
+        "x509",
+        "-req",
+        "-in",
+        "server.csr",
+        "-CA",
+        "ca.pem",
+        "-CAkey",
+        "ca.key",
+        "-CAcreateserial",
+        "-out",
+        "server.pem",
+        "-days",
+        "1",
+        "-extfile",
+        "extensions",
+    ]);
+}
+
 #[test]
 fn config_loader_should_load_complete_terminal_example() {
     parse_config(&valid_config()).expect("terminal config example");
@@ -18,10 +163,18 @@ fn config_loader_should_load_complete_terminal_example() {
 fn config_loader_should_resolve_paths_relative_to_config_file() {
     let (config, _directory) = parse_config(&valid_config()).expect("resolved config");
     let debug = format!("{config:?}");
+    assert!(debug.contains(".runtime/data"));
     assert!(debug.contains(".runtime/logs"));
     assert!(debug.contains("frontend/dist"));
 }
 
+#[test]
+fn config_loader_should_reject_missing_runtime_data_dir() {
+    let config = valid_config().replace("  runtime_data_dir: '../.runtime/data'\n", "");
+
+    assert!(parse_config(&config).is_err());
+}
+
 #[test]
 fn config_loader_should_inject_connection_passwords_into_urls() {
     parse_config(&valid_config()).expect("Store validates password injection into both URLs");
@@ -135,7 +288,7 @@ fn config_loader_should_reject_removed_fingerprint_section() {
 
 #[test]
 fn config_loader_should_reject_invalid_codex_cli_version() {
-    assert_rejected(valid_config().replace("codex_version: '0.146.0'", "codex_version: 'latest'"));
+    assert_rejected(valid_config().replace("codex_version: '0.153.4'", "codex_version: 'latest'"));
 }
 
 #[test]
@@ -154,7 +307,7 @@ fn config_loader_should_reject_zero_server_port() {
 
 #[test]
 fn config_loader_should_reject_invalid_desktop_profile_fields() {
-    assert_rejected(valid_config().replace("desktop_build: '6119'", "desktop_build: 'build'"));
+    assert_rejected(valid_config().replace("desktop_build: '8109'", "desktop_build: 'build'"));
 }
 
 fn assert_rejected(config: String) {

backend/apps/gateway/tests/main.rs

@@ -1,6 +1,9 @@
 mod architecture;
 mod bootstrap;
 
+// 组合根是否混入业务策略由代码审查判断，行数和标识符/注释关键词不能证明职责越界。
+// 依赖 DAG、公开模块面和模块镜像继续由 architecture 检查，源码纪律由下方测试维护。
+
 use std::{
     collections::BTreeSet,
     fs,
@@ -43,58 +46,38 @@ fn cargo_library_root_is_conventional_lib() {
 }
 
 #[test]
-fn production_files_have_no_hidden_modules_or_test_hooks() {
-    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
-    for relative in ["bootstrap.rs", "lib.rs", "main.rs"] {
-        let path = root.join(relative);
-        let source = fs::read_to_string(&path).expect("read production source");
-        assert!(
-            !source.contains("include!("),
-            "{} uses include!",
-            path.display()
-        );
-        let syntax = syn::parse_file(&source).expect("parse production source");
-        for item in &syntax.items {
-            if let Item::Mod(module) = item {
-                assert!(
-                    module.content.is_none(),
-                    "{} has an inline module",
-                    path.display()
-                );
-            }
-            for attribute in item_attrs(item) {
-                assert!(
-                    !is_path_or_test_cfg(attribute),
-                    "{} has a production test/path hook",
-                    path.display(),
-                );
+fn workspace_production_files_have_no_hidden_modules_or_test_hooks() {
+    for member in architecture::WORKSPACE_MEMBERS {
+        let root = architecture::backend_root().join(member).join("src");
+        for relative in rust_files(&root) {
+            let path = root.join(relative);
+            let source = fs::read_to_string(&path).expect("read production source");
+            assert!(
+                !source.contains("include!("),
+                "{} uses include!",
+                path.display()
+            );
+            let syntax = syn::parse_file(&source).expect("parse production source");
+            for item in &syntax.items {
+                if let Item::Mod(module) = item {
+                    assert!(
+                        module.content.is_none(),
+                        "{} has an inline module",
+                        path.display()
+                    );
+                }
+                for attribute in item_attrs(item) {
+                    assert!(
+                        !is_path_or_test_cfg(attribute),
+                        "{} has a production test/path hook",
+                        path.display(),
+                    );
+                }
             }
         }
     }
 }
 
-#[test]
-fn bootstrap_owns_only_bundle_wiring() {
-    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
-    let bootstrap = fs::read_to_string(root.join("bootstrap.rs")).expect("read bootstrap");
-    for forbidden in [
-        "sqlx::",
-        "redis::",
-        "Repository",
-        "impl Provider",
-        "impl ExecutionService",
-        "tokio::spawn",
-        "access_token",
-        "refresh_token",
-    ] {
-        assert!(
-            !bootstrap.contains(forbidden),
-            "bootstrap owns `{forbidden}`"
-        );
-    }
-    assert!(bootstrap.lines().count() <= 300);
-}
-
 fn rust_files(root: &Path) -> BTreeSet<PathBuf> {
     let mut result = BTreeSet::new();
     collect_rust_files(root, root, &mut result);

backend/crates/gateway-admin/Cargo.toml

@@ -12,15 +12,18 @@ name = "main"
 path = "tests/main.rs"
 
 [dependencies]
-argon2 = "0.5.3"
+argon2 = "0.6.0"
 async-trait = "0.1.89"
 base64 = "0.23.0"
+bytes = "1.11.1"
 chrono = "0.4.45"
 futures = "0.3.32"
 gateway-core = { path = "../gateway-core" }
+heck = "0.5.0"
 hex = "0.4.3"
 rand_core = { version = "0.6.4", features = ["getrandom"] }
 serde = { version = "1.0.228", features = ["derive"] }
+serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 secrecy = { version = "0.10.3", features = ["serde"] }
 subtle = "2.6.1"
 thiserror = "2.0.18"
@@ -28,10 +31,9 @@ tracing = "0.1.44"
 uuid = { version = "1.23.3", features = ["v7"] }
 cron = "0.17"
 chrono-tz = "0.10"
-tokio = { version = "1.52", features = ["rt", "time", "macros"] }
+tokio = { version = "1.52", features = ["rt", "time", "macros", "sync"] }
 
 [dev-dependencies]
-serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 sha2 = "0.11"
 tempfile = "3"
 tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt"] }

backend/crates/gateway-admin/src/backup/policy.rs

@@ -119,11 +119,11 @@ pub struct RetentionDecision {
 
 /// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录。
 ///
-/// 规则（`docs/s3-backup-design-audit.md` §4.4）：
+/// 自动保留规则：
 /// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理。
 /// - 自动计划备份满足任一启用阈值即可进入删除。
 /// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）。
-/// - 手动备份不受自动阈值影响；无 TTL，仅由管理员手动删除。
+/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理。
 #[must_use]
 pub fn decide_retention(
     retention_days: u32,

backend/crates/gateway-admin/src/backup/task.rs

@@ -9,7 +9,7 @@ use std::time::Duration;
 use chrono::{DateTime, Utc};
 use futures::future::BoxFuture;
 use gateway_core::{
-    engine::CancellationToken,
+    lifecycle::CancellationToken,
     task::{DaemonTask, WorkerTaskError},
 };
 use tracing::{info, warn};

backend/crates/gateway-admin/src/lib.rs

@@ -6,7 +6,8 @@ use std::{fmt, path::Path, sync::Arc, time::Duration};
 
 use gateway_core::{
     engine::probe::AccountProbe,
-    routing::{ProviderKind, snapshot::SnapshotControl},
+    routing::ProviderKind,
+    runtime::SnapshotControl,
     task::{
         DaemonRestartPolicy, WorkerContribution, WorkerId, WorkerKind, WorkerRegistration,
         WorkerRunnable,
@@ -22,19 +23,22 @@ mod use_case;
 
 pub use use_case::{
     account_groups::AccountGroupService, accounts::AccountsService, auth::AuthService,
-    backup::BackupService, client_keys::ClientKeyService, observability::ObservabilityService,
-    openai::OpenAiService, settings::SettingsService, system::SystemService, xai::XaiService,
+    backup::BackupService, client_distribution::ClientDistributionService,
+    client_keys::ClientKeyService, observability::ObservabilityService, openai::OpenAiService,
+    proxies::ProxiesService, settings::SettingsService, system::SystemService, xai::XaiService,
 };
 
 use model::{AdminError, AdminErrorKind};
 use ports::{
+    client_distribution::ClientDistributionResolver,
     provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind, ProviderAdminRegistry},
     store::AdminStorePorts,
     system::SystemOperations,
 };
 use use_case::{
     account_groups::DefaultAccountGroupService, accounts::DefaultAccountsService,
-    auth::DefaultAuthService, backup::DefaultBackupService, client_keys::DefaultClientKeyService,
+    auth::DefaultAuthService, backup::DefaultBackupService,
+    client_distribution::DefaultClientDistributionService, client_keys::DefaultClientKeyService,
     observability::DefaultObservabilityService, openai::DefaultOpenAiService,
     settings::DefaultSettingsService, system::DefaultSystemService, xai::DefaultXaiService,
 };
@@ -134,9 +138,9 @@ impl fmt::Debug for AdminConfig {
 /// Admin-owned 启动配置错误；不回显任何配置值。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum AdminConfigError {
-    #[error("configuration field `{0}` is invalid")]
+    #[error("配置字段 `{0}` 不合法")]
     InvalidField(&'static str),
-    #[error("admin.default_password does not meet the initial password policy")]
+    #[error("admin.default_password 不符合初始密码策略")]
     WeakInitialPassword,
 }
 
@@ -145,10 +149,12 @@ pub enum AdminConfigError {
 /// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块。
 #[derive(Clone)]
 pub struct AdminServices {
+    proxies: Arc<dyn ProxiesService>,
     auth: Arc<dyn AuthService>,
     accounts: Arc<dyn AccountsService>,
     account_groups: Arc<dyn AccountGroupService>,
     client_keys: Arc<dyn ClientKeyService>,
+    client_distribution: Arc<dyn ClientDistributionService>,
     observability: Arc<dyn ObservabilityService>,
     settings: Arc<dyn SettingsService>,
     system: Arc<dyn SystemService>,
@@ -158,6 +164,11 @@ pub struct AdminServices {
 }
 
 impl AdminServices {
+    #[must_use]
+    pub fn proxies(&self) -> &dyn ProxiesService {
+        self.proxies.as_ref()
+    }
+
     #[must_use]
     pub fn auth(&self) -> &dyn AuthService {
         self.auth.as_ref()
@@ -178,6 +189,11 @@ impl AdminServices {
         self.client_keys.as_ref()
     }
 
+    #[must_use]
+    pub fn client_distribution(&self) -> &dyn ClientDistributionService {
+        self.client_distribution.as_ref()
+    }
+
     #[must_use]
     pub fn observability(&self) -> &dyn ObservabilityService {
         self.observability.as_ref()
@@ -237,9 +253,11 @@ pub async fn initialize(
     store: AdminStorePorts,
     providers: Vec<Arc<dyn ProviderAdmin>>,
     snapshot: Arc<dyn SnapshotControl>,
-    probe: Arc<dyn AccountProbe>,
+    probes: (Arc<dyn AccountProbe>, Arc<dyn ports::proxy::ProxyProbe>),
+    client_distribution: Arc<dyn ClientDistributionResolver>,
     system: Arc<dyn SystemOperations>,
 ) -> Result<AdminBundle, AdminError> {
+    let (probe, proxy_probe) = probes;
     config
         .resolve_and_validate(Path::new("."))
         .map_err(|error| AdminError::invalid(error.to_string()))?;
@@ -261,6 +279,7 @@ pub async fn initialize(
 
     let accounts = Arc::new(DefaultAccountsService::new(
         store.accounts(),
+        store.account_runtime(),
         registry.clone(),
         snapshot.clone(),
         probe.clone(),
@@ -278,18 +297,27 @@ pub async fn initialize(
         backup_ports.object_store(),
     );
     let services = AdminServices {
+        proxies: Arc::new(use_case::proxies::DefaultProxiesService::new(
+            store.proxies(),
+            proxy_probe,
+            snapshot.clone(),
+            registry.clone(),
+        )),
         auth,
         accounts,
         account_groups: Arc::new(DefaultAccountGroupService::new(
             store.account_groups(),
+            store.account_runtime(),
             snapshot.clone(),
         )),
         client_keys: Arc::new(DefaultClientKeyService::new(
             store.client_keys(),
             snapshot.clone(),
         )),
+        client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
         observability: Arc::new(DefaultObservabilityService::new(
             store.observability(),
+            store.accounts(),
             store.settings(),
             registry,
         )),
@@ -301,11 +329,13 @@ pub async fn initialize(
         openai: Arc::new(DefaultOpenAiService::new(
             openai,
             store.accounts(),
+            store.proxies(),
             snapshot.clone(),
         )),
         xai: Arc::new(DefaultXaiService::new(
             xai,
             store.accounts(),
+            store.proxies(),
             snapshot.clone(),
         )),
         backups,
@@ -322,9 +352,9 @@ fn backup_worker_contribution(
     task: backup::task::BackupTask,
 ) -> Result<Vec<WorkerContribution>, AdminError> {
     let id = WorkerId::try_new(WorkerKind::Backup, BACKUP_WORKER_OWNER)
-        .map_err(|_| AdminError::internal("Backup worker id is invalid"))?;
+        .map_err(|_| AdminError::internal("备份 Worker ID 不合法"))?;
     let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
-        .map_err(|_| AdminError::internal("Backup worker restart policy is invalid"))?;
+        .map_err(|_| AdminError::internal("备份 Worker 重启策略不合法"))?;
     let registration = WorkerRegistration::try_new(
         id,
         WorkerRunnable::Daemon {
@@ -332,12 +362,12 @@ fn backup_worker_contribution(
             task: Box::new(task),
         },
     )
-    .map_err(|_| AdminError::internal("Backup worker registration is invalid"))?;
+    .map_err(|_| AdminError::internal("备份 Worker 注册信息不合法"))?;
     Ok(vec![WorkerContribution::Registration(registration)])
 }
 
 fn provider_kind(value: &'static str) -> Result<ProviderKind, AdminError> {
-    ProviderKind::new(value).map_err(|_| AdminError::internal("Built-in Provider kind is invalid"))
+    ProviderKind::new(value).map_err(|_| AdminError::internal("内置 Provider 类型不合法"))
 }
 
 fn map_provider_registry_error(error: ProviderAdminError) -> AdminError {
@@ -347,8 +377,12 @@ fn map_provider_registry_error(error: ProviderAdminError) -> AdminError {
         }
         ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
         ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
-        ProviderAdminErrorKind::Unavailable => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
+        ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
+            AdminErrorKind::Unavailable
+        }
+        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
         ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
     };
-    AdminError::new(kind, "Provider registry initialization failed")
+    AdminError::new(kind, "Provider 注册表初始化失败")
 }

backend/crates/gateway-admin/src/model/account_groups.rs

@@ -3,7 +3,7 @@
 use std::collections::BTreeMap;
 
 use chrono::{DateTime, Utc};
-use gateway_core::routing::AccountGroupId;
+use gateway_core::{account::AccountStatusFacts, routing::AccountGroupId};
 
 use super::{PageSize, Revision, observability::DecimalAmount};
 
@@ -45,7 +45,17 @@ pub struct AccountGroupCapacity {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupUsage {
     pub today_usd: DecimalAmount,
-    pub total_usd: DecimalAmount,
+    /// 当前 usage retention 窗口内、按请求发生时 routing group 快照归属的累计成本。
+    pub retained_total_usd: DecimalAmount,
+}
+
+/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupMemberFact {
+    pub group_id: AccountGroupId,
+    pub account_id: String,
+    pub status: AccountStatusFacts,
+    pub total_slots: u64,
 }
 
 /// Lightweight group reference embedded in account and client-key views.

backend/crates/gateway-admin/src/model/accounts.rs

@@ -1,20 +1,32 @@
 //! 多 Provider 账号目录与连接测试的公共事实。
 
-use std::pin::Pin;
+use std::{collections::BTreeMap, pin::Pin};
 
 use chrono::{DateTime, Utc};
 use futures::Stream;
 
-use gateway_core::routing::ProviderKind;
+use gateway_core::{
+    engine::probe::AccountProbeErrorSource, error::GatewayErrorKind, routing::ProviderKind,
+    upstream::UpstreamSendState,
+};
 
 use super::{PageSize, Revision, account_groups::AccountGroupRef, observability::TimeRange};
 
-pub use gateway_core::engine::credential::{
+pub use gateway_core::account::{
     AccountConcurrencyLimit, AccountErrorReason, AccountStatus, AccountStatusFacts,
     AccountStatusProjection, AccountWeight, CredentialState, QuotaAccessState, QuotaEvidence,
     QuotaState, resolve_account_status,
 };
 
+/// 导入时统一应用的账号调度与分组设置；缺省时保留原有导入语义。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountImportSettings {
+    pub enabled: bool,
+    pub concurrency_limit: Option<AccountConcurrencyLimit>,
+    pub weight: AccountWeight,
+    pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+}
+
 /// 账号列表排序字段。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AccountSortField {
@@ -52,6 +64,14 @@ pub struct AccountListQuery {
     pub sort: Option<AccountSort>,
 }
 
+/// Admin query service 从运行态存储取得的当前账号冷却快照。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AccountRuntimeSnapshot {
+    pub rate_limited_until: BTreeMap<String, DateTime<Utc>>,
+    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零。
+    pub in_flight: Option<BTreeMap<String, u64>>,
+}
+
 /// Optional account membership filter.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AccountGroupFilter {
@@ -78,6 +98,7 @@ pub struct AccountRecord {
     pub enabled: bool,
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
+    pub outbound_proxy: Option<gateway_core::account::OutboundProxy>,
     pub credential_state: CredentialState,
     pub credential_observed_at: DateTime<Utc>,
     pub quota: QuotaState,
@@ -200,13 +221,14 @@ pub struct UpdateAccount {
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
     pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
 /// 账号更新结果。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUpdateResult {
     pub config_revision: Revision,
-    pub account_id: gateway_core::engine::credential::ProviderAccountId,
+    pub account_id: gateway_core::account::ProviderAccountId,
 }
 
 /// 一批账号可编辑事实的一次性替换命令。
@@ -217,13 +239,14 @@ pub struct BatchUpdateAccounts {
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
     pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
 /// 批量账号更新结果。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountsUpdateResult {
     pub config_revision: Revision,
-    pub account_ids: Vec<gateway_core::engine::credential::ProviderAccountId>,
+    pub account_ids: Vec<gateway_core::account::ProviderAccountId>,
 }
 
 /// 账号批量删除命令。
@@ -249,6 +272,9 @@ pub enum AccountConnectionTestEvent {
     },
     Completed,
     Failed {
+        source: AccountProbeErrorSource,
+        gateway_error_code: GatewayErrorKind,
+        send_state: Option<UpstreamSendState>,
         message: String,
         provider_error_code: Option<String>,
         provider_error_type: Option<String>,

backend/crates/gateway-admin/src/model/auth.rs

@@ -4,6 +4,12 @@ use chrono::{DateTime, Utc};
 
 use super::{MutationActor, MutationContext, Revision};
 
+/// 会话审计使用的稳定管理员标识。
+#[must_use]
+pub fn admin_session_actor_ref(admin_user_id: &str) -> String {
+    format!("admin:{admin_user_id}")
+}
+
 /// 已认证的管理主体。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AdminPrincipal {

backend/crates/gateway-admin/src/model/backup/code.rs

@@ -0,0 +1,34 @@
+//! 备份领域的稳定错误码。
+
+/// 配置或参数非法。
+pub const INVALID_CONFIG: &str = "backup.invalid_config";
+/// Cron 表达式非法。
+pub const INVALID_CRON: &str = "backup.invalid_cron";
+/// IANA 时区非法。
+pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
+/// 记录不存在。
+pub const RECORD_NOT_FOUND: &str = "backup.record_not_found";
+/// 已存在活跃任务，拒绝创建。
+pub const ACTIVE_TASK_CONFLICT: &str = "backup.active_task_conflict";
+/// 记录状态与期望不符，无法迁移。
+pub const STATE_CONFLICT: &str = "backup.state_conflict";
+/// 已有记录时禁止切换存储目标。
+pub const STORAGE_IDENTITY_LOCKED: &str = "backup.storage_identity_locked";
+/// `pg_dump` 非零退出或失败。
+pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
+/// 暂存磁盘空间不足。
+pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
+/// S3 认证失败。
+pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
+/// S3 权限拒绝。
+pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
+/// S3 上传失败。
+pub const S3_UPLOAD_FAILED: &str = "backup.s3_upload_failed";
+/// 远端对象校验失败。
+pub const REMOTE_VERIFICATION_FAILED: &str = "backup.remote_verification_failed";
+/// 任务被取消。
+pub const CANCELLED: &str = "backup.cancelled";
+/// 仓储或对象存储暂不可用。
+pub const STORE_UNAVAILABLE: &str = "backup.store_unavailable";
+/// 上游 S3 服务返回无效或失败响应。
+pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";

backend/crates/gateway-admin/src/model/backup/mod.rs

@@ -288,7 +288,7 @@ pub struct BackupRecord {
     pub error_message: Option<String>,
     pub started_at: Option<DateTime<Utc>>,
     pub completed_at: Option<DateTime<Utc>>,
-    /// 手动过期时间；创建时确定，到期自动清理。
+    /// 创建时确定的过期时间；手工和计划备份均可设置，到期自动清理。
     pub expires_at: Option<DateTime<Utc>>,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
@@ -447,40 +447,7 @@ impl BackupError {
 }
 
 /// 构造稳定错误码常量。
-pub mod code {
-    /// 配置或参数非法。
-    pub const INVALID_CONFIG: &str = "backup.invalid_config";
-    /// Cron 表达式非法。
-    pub const INVALID_CRON: &str = "backup.invalid_cron";
-    /// IANA 时区非法。
-    pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
-    /// 记录不存在。
-    pub const RECORD_NOT_FOUND: &str = "backup.record_not_found";
-    /// 已存在活跃任务，拒绝创建。
-    pub const ACTIVE_TASK_CONFLICT: &str = "backup.active_task_conflict";
-    /// 记录状态与期望不符，无法迁移。
-    pub const STATE_CONFLICT: &str = "backup.state_conflict";
-    /// 已有记录时禁止切换存储目标。
-    pub const STORAGE_IDENTITY_LOCKED: &str = "backup.storage_identity_locked";
-    /// `pg_dump` 非零退出或失败。
-    pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
-    /// 暂存磁盘空间不足。
-    pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
-    /// S3 认证失败。
-    pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
-    /// S3 权限拒绝。
-    pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
-    /// S3 上传失败。
-    pub const S3_UPLOAD_FAILED: &str = "backup.s3_upload_failed";
-    /// 远端对象校验失败。
-    pub const REMOTE_VERIFICATION_FAILED: &str = "backup.remote_verification_failed";
-    /// 任务被取消。
-    pub const CANCELLED: &str = "backup.cancelled";
-    /// 仓储或对象存储暂不可用。
-    pub const STORE_UNAVAILABLE: &str = "backup.store_unavailable";
-    /// 上游 S3 服务返回无效或失败响应。
-    pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";
-}
+pub mod code;
 
 /// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.dump`。
 ///

backend/crates/gateway-admin/src/model/client_distribution.rs

@@ -0,0 +1,58 @@
+//! 管理设置页使用的 Codex 客户端下载信息。
+
+use chrono::{DateTime, Utc};
+
+/// Windows 安装包架构。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum ClientArchitecture {
+    X64,
+    Arm64,
+}
+
+impl ClientArchitecture {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::X64 => "x64",
+            Self::Arm64 => "arm64",
+        }
+    }
+}
+
+/// 下载地址的可信来源。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientDownloadSource {
+    MicrosoftStore,
+    OfficialOpenAi,
+}
+
+impl ClientDownloadSource {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::MicrosoftStore => "microsoft_store",
+            Self::OfficialOpenAi => "official_openai",
+        }
+    }
+}
+
+/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClientDownloadPackage {
+    pub architecture: ClientArchitecture,
+    pub source: ClientDownloadSource,
+    pub version: Option<String>,
+    pub file_name: String,
+    pub size_bytes: Option<u64>,
+    pub download_url: String,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+/// Codex Desktop Windows 下载解析结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CodexDesktopWindowsDownloads {
+    pub resolved_at: DateTime<Utc>,
+    pub cached: bool,
+    pub warning: Option<String>,
+    pub packages: Vec<ClientDownloadPackage>,
+}

backend/crates/gateway-admin/src/model/client_keys.rs

@@ -5,7 +5,8 @@ use std::{fmt, num::NonZeroU16};
 use chrono::{DateTime, Utc};
 
 use gateway_core::{
-    policy::{ClientApiKeyId, RateLimits},
+    engine::budget::{ClientBudgetLimits, ClientBudgetStatus},
+    policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits},
     routing::{AccountGroupId, ProviderKind},
 };
 
@@ -93,6 +94,7 @@ pub struct ClientKeyRecord {
     pub prefix: String,
     pub enabled: bool,
     pub limits: RateLimits,
+    pub budget: ClientBudgetStatus,
     pub last_used_at: Option<DateTime<Utc>>,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
@@ -142,10 +144,12 @@ impl fmt::Debug for ClientKeySecret {
 /// API 提交的 Client Key 创建命令。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateClientKey {
+    pub custom_key: Option<PlaintextClientApiKey>,
     pub name: String,
     pub label: Option<String>,
     pub group_ids: Vec<AccountGroupId>,
     pub limits: RateLimits,
+    pub budget: ClientBudgetLimits,
 }
 
 /// 管理用例生成 ID 与明文后的持久化命令。
@@ -156,6 +160,7 @@ pub struct NewClientKey {
     pub label: Option<String>,
     pub group_ids: Vec<AccountGroupId>,
     pub limits: RateLimits,
+    pub budget: ClientBudgetLimits,
     pub plaintext: String,
 }
 
@@ -179,6 +184,8 @@ pub struct UpdateClientKey {
     pub label: Option<String>,
     pub group_ids: Vec<AccountGroupId>,
     pub limits: RateLimits,
+    pub daily_limit_usd: Option<gateway_core::metering::Decimal>,
+    pub weekly_limit_usd: Option<gateway_core::metering::Decimal>,
 }
 
 /// 修改 Client Key 启用状态。

backend/crates/gateway-admin/src/model/mod.rs

@@ -6,9 +6,13 @@ pub mod account_groups;
 pub mod accounts;
 pub mod auth;
 pub mod backup;
+pub mod client_distribution;
 pub mod client_keys;
 pub mod observability;
 pub mod provider_credentials;
+pub mod proxies;
+pub mod quota_forecast;
+pub mod quota_forecast_sampling;
 pub mod settings;
 pub mod system;
 
@@ -21,11 +25,12 @@ pub enum AdminErrorKind {
     Conflict,
     RateLimited,
     BadGateway,
+    UpstreamResultUnknown,
     Unavailable,
     Internal,
 }
 
-/// 不携带基础设施细节的管理用例错误。
+/// 不携带基础设施细节、可安全返回给管理员的管理用例错误。
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
 #[error("{message}")]
 pub struct AdminError {
@@ -47,6 +52,12 @@ impl AdminError {
         self.kind
     }
 
+    /// 返回已脱敏、可公开给管理员的文案。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        &self.message
+    }
+
     #[must_use]
     pub fn invalid(message: impl Into<String>) -> Self {
         Self::new(AdminErrorKind::Invalid, message)
@@ -72,6 +83,11 @@ impl AdminError {
         Self::new(AdminErrorKind::BadGateway, message)
     }
 
+    #[must_use]
+    pub fn upstream_result_unknown(message: impl Into<String>) -> Self {
+        Self::new(AdminErrorKind::UpstreamResultUnknown, message)
+    }
+
     #[must_use]
     pub fn unavailable(message: impl Into<String>) -> Self {
         Self::new(AdminErrorKind::Unavailable, message)

backend/crates/gateway-admin/src/model/observability.rs

@@ -1,6 +1,6 @@
 //! 用量、成本、健康与错误诊断的 UTC 语义事实。
 
-use std::{num::NonZeroU32, str::FromStr};
+use std::str::FromStr;
 
 use chrono::{DateTime, TimeDelta, Timelike as _, Utc};
 
@@ -38,29 +38,6 @@ impl TimeRange {
     }
 }
 
-/// 从一开始的观测页码。
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct PageNumber(NonZeroU32);
-
-impl PageNumber {
-    #[must_use]
-    pub const fn new(value: NonZeroU32) -> Self {
-        Self(value)
-    }
-
-    #[must_use]
-    pub const fn get(self) -> u32 {
-        self.0.get()
-    }
-}
-
-/// 观测记录的稳定键集游标。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ObservabilityCursor {
-    pub observed_at: DateTime<Utc>,
-    pub stable_id: String,
-}
-
 /// 请求结果状态。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum RequestOutcome {
@@ -146,8 +123,7 @@ pub struct UsageFilter {
 pub struct UsageQuery {
     pub range: TimeRange,
     pub filter: UsageFilter,
-    pub cursor: Option<ObservabilityCursor>,
-    pub page: PageNumber,
+    pub current_page: u32,
     pub page_size: PageSize,
 }
 
@@ -164,7 +140,6 @@ pub struct OpsErrorFilter {
     pub attempt_index: Option<u32>,
     pub response_id: Option<String>,
     pub upstream_request_id: Option<String>,
-    pub failure_kind: Option<String>,
     pub status_code: Option<u16>,
     pub search: Option<String>,
 }
@@ -174,8 +149,7 @@ pub struct OpsErrorFilter {
 pub struct OpsErrorQuery {
     pub range: TimeRange,
     pub filter: OpsErrorFilter,
-    pub cursor: Option<ObservabilityCursor>,
-    pub page: PageNumber,
+    pub current_page: u32,
     pub page_size: PageSize,
 }
 
@@ -213,11 +187,11 @@ impl DecimalAmount {
         Self::from_decimal(self.to_decimal()?.checked_div_u64(divisor)?)
     }
 
-    fn to_decimal(&self) -> Option<gateway_core::accounting::Decimal> {
+    fn to_decimal(&self) -> Option<gateway_core::metering::Decimal> {
         self.0.parse().ok()
     }
 
-    fn from_decimal(value: gateway_core::accounting::Decimal) -> Option<Self> {
+    fn from_decimal(value: gateway_core::metering::Decimal) -> Option<Self> {
         Some(Self(value.canonical()))
     }
 }
@@ -402,6 +376,16 @@ pub struct RequestMetrics {
     pub max_latency_ms: Option<u64>,
     pub latency_percentiles: LatencyPercentiles,
     pub first_token_latency_percentiles: LatencyPercentiles,
+    pub admission_decision_count: u64,
+    pub admission_decision_percentiles: LatencyPercentiles,
+    pub account_selection_wait_count: u64,
+    pub account_selection_wait_percentiles: LatencyPercentiles,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_sample_count: u64,
+    pub capacity_utilization_avg_basis_points: Option<u64>,
+    pub capacity_utilization_p95_basis_points: Option<u64>,
     pub cache_eligible_request_count: u64,
     pub cache_hit_request_count: u64,
 }
@@ -487,6 +471,8 @@ pub struct DashboardAccountUsage {
     pub name: String,
     pub email: Option<String>,
     pub plan_type: Option<String>,
+    /// Admin 按 Provider 补齐的套餐展示名称。
+    pub plan_type_display: Option<String>,
     pub request_count: u64,
     pub success_count: u64,
     pub input_tokens: Option<u64>,
@@ -507,6 +493,8 @@ pub struct DashboardAccountUsage {
     ///
     /// `None` 表示上游未提供可比较的百分比，不应伪造为零。
     pub quota_used_percent: Option<f64>,
+    /// Provider 返回的代表窗口；缺失时保留未知语义。
+    pub quota_window: Option<super::provider_credentials::ProviderQuotaWindow>,
     pub models: Vec<DashboardAccountModelUsage>,
 }
 
@@ -535,13 +523,60 @@ pub struct DashboardTotals {
 #[derive(Debug, Clone, PartialEq)]
 pub struct DashboardObservation {
     pub range: TimeRange,
-    pub requests: RequestMetrics,
-    pub attempts: AttemptMetrics,
     pub totals: DashboardTotals,
     pub provider_accounts: AccountPoolMetrics,
     pub trend: Vec<RequestMetricPoint>,
     pub account_usage: Vec<DashboardAccountUsage>,
-    pub recent_requests: Vec<UsageRecord>,
+    pub recent_requests: Vec<UsageListRecord>,
+}
+
+/// 使用记录表格的窄读模型。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UsageListRecord {
+    pub id: String,
+    pub endpoint: String,
+    pub client_transport: String,
+    pub requested_model_id: Option<String>,
+    pub provider_kind: Option<String>,
+    pub provider_account_ref: Option<String>,
+    pub provider_account_name: Option<String>,
+    pub provider_account_email: Option<String>,
+    pub provider_account_authentication_kind: Option<String>,
+    pub upstream_model_id: Option<String>,
+    pub upstream_transport: Option<String>,
+    pub service_tier: Option<String>,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+    pub cached_tokens: Option<u64>,
+    pub cache_write_tokens: Option<u64>,
+    pub reasoning_tokens: Option<u64>,
+    pub image_input_tokens: Option<u64>,
+    pub image_output_tokens: Option<u64>,
+    pub total_tokens: Option<u64>,
+    pub cost_source: String,
+    pub cost_amount: Option<DecimalAmount>,
+    pub cost_currency: Option<String>,
+    pub billing: Option<UsageBilling>,
+    pub transport_decision_wait_ms: Option<u64>,
+    pub connect_ms: Option<u64>,
+    pub headers_ms: Option<u64>,
+    pub first_event_ms: Option<u64>,
+    pub first_reasoning_ms: Option<u64>,
+    pub first_text_ms: Option<u64>,
+    pub first_token_ms: Option<u64>,
+    pub provider_processing_ms: Option<u64>,
+    pub latency_ms: Option<u64>,
+    pub admission_decision_ms: Option<u64>,
+    pub account_selection_wait_ms: Option<u64>,
+    pub capacity_used_slots: Option<u64>,
+    pub capacity_total_slots: Option<u64>,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: bool,
+    pub started_at: DateTime<Utc>,
 }
 
 /// 一次完整模型请求的公共观测记录。
@@ -557,7 +592,7 @@ pub struct UsageRecord {
     pub operation: String,
     pub endpoint: String,
     pub client_transport: String,
-    pub requested_model_id: String,
+    pub requested_model_id: Option<String>,
     pub provider_kind: Option<String>,
     pub provider_account_ref: Option<String>,
     pub provider_account_name: Option<String>,
@@ -604,6 +639,10 @@ pub struct UsageRecord {
     pub first_token_ms: Option<u64>,
     pub provider_processing_ms: Option<u64>,
     pub latency_ms: Option<u64>,
+    pub admission_decision_ms: Option<u64>,
+    pub account_selection_wait_ms: Option<u64>,
+    pub capacity_used_slots: Option<u64>,
+    pub capacity_total_slots: Option<u64>,
     pub client_ip: Option<String>,
     pub user_agent: Option<String>,
     pub reasoning_effort: Option<String>,
@@ -621,9 +660,10 @@ pub struct UsageRecord {
 /// 用量分页结果。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UsagePage {
-    pub items: Vec<UsageRecord>,
+    pub items: Vec<UsageListRecord>,
+    pub current_page: u32,
+    pub page_size: u16,
     pub total: u64,
-    pub next_cursor: Option<ObservabilityCursor>,
 }
 
 /// 请求中的一次上游尝试或运维事件。
@@ -666,6 +706,8 @@ pub struct UsageAttempt {
 /// 一条请求及其全部尝试。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UsageDetail {
+    pub trace: Option<serde_json::Value>,
+    pub related_requests: Vec<serde_json::Value>,
     pub request: UsageRecord,
     pub attempts: Vec<UsageAttempt>,
 }
@@ -708,6 +750,9 @@ pub struct DiagnosticObservation {
     pub total_tokens: u64,
     pub average_latency_ms: Option<u64>,
     pub latency_p95_ms: Option<u64>,
+    pub first_token_p95_ms: Option<u64>,
+    pub non_completion_count: u64,
+    pub retry_count: u64,
     pub cost_coverage: CostCoverage,
     pub costs: Vec<CurrencyCost>,
 }
@@ -722,6 +767,10 @@ pub struct OpsError {
     pub client_api_key_ref: Option<String>,
     pub component: String,
     pub operation: String,
+    pub protocol: Option<String>,
+    pub client_transport: Option<String>,
+    pub requested_model_id: Option<String>,
+    pub service_tier: Option<String>,
     pub endpoint: Option<String>,
     pub provider_kind: Option<String>,
     pub provider_account_ref: Option<String>,
@@ -731,6 +780,7 @@ pub struct OpsError {
     pub upstream_model_id: Option<String>,
     pub upstream_transport: Option<String>,
     pub failure_kind: String,
+    pub upstream_send_state: Option<String>,
     pub client_status_code: Option<u16>,
     pub upstream_status_code: Option<u16>,
     pub provider_error_code: Option<String>,
@@ -738,7 +788,26 @@ pub struct OpsError {
     pub upstream_request_id: Option<String>,
     pub latency_ms: Option<u64>,
     pub message: String,
-    pub occurrence_count: u32,
+    pub raw_upstream_error: Option<String>,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub request_kind: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: Option<bool>,
+    pub continuation_affinity_hash: Option<String>,
+    pub continuation_previous_response_id_hash: Option<String>,
+    pub continuation_unavailable_reason: Option<String>,
+    pub upstream_connection_id: Option<String>,
+    pub upstream_connection_exit_reason: Option<String>,
+    pub upstream_connection_age_ms: Option<u64>,
+    pub upstream_connection_idle_ms: Option<u64>,
+    pub recovery_request_id: Option<String>,
+    pub recovered_at: Option<DateTime<Utc>>,
+    pub recovery_attempt_count: u32,
+    pub recovery_retry_delay_ms: Option<u64>,
+    pub recovery_total_latency_ms: Option<u64>,
     pub occurred_at: DateTime<Utc>,
     pub stable_sort_id: String,
 }
@@ -747,8 +816,9 @@ pub struct OpsError {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OpsErrorPage {
     pub items: Vec<OpsError>,
+    pub current_page: u32,
+    pub page_size: u16,
     pub total: u64,
-    pub next_cursor: Option<ObservabilityCursor>,
 }
 
 /// 仪表盘趋势指标。
@@ -787,6 +857,9 @@ pub struct TrendSummary {
     pub average_latency_ms: Option<u64>,
     pub max_latency_ms: Option<u64>,
     pub min_latency_ms: Option<u64>,
+    pub peak_first_token_p95_ms: Option<f64>,
+    pub peak_latency_p95_ms: Option<f64>,
+    pub minimum_output_throughput_p50: Option<u64>,
     pub success_rate: Option<f64>,
     pub cache_hit_request_rate: Option<f64>,
     pub costs: Vec<CurrencyCost>,
@@ -935,6 +1008,7 @@ pub struct DashboardResult {
 /// 洞察健康时间点的语义结果。
 #[derive(Debug, Clone, PartialEq)]
 pub struct UsageInsightsHealthPoint {
+    pub total_requests: u64,
     pub bucket_start: DateTime<Utc>,
     pub success_requests: u64,
     pub failed_requests: u64,
@@ -954,6 +1028,7 @@ pub struct UsageInsightsHealth {
     pub incomplete_requests: u64,
     pub caller_error_requests: u64,
     pub success_rate: f64,
+    pub completion_rate: f64,
     pub points: Vec<UsageInsightsHealthPoint>,
 }
 
@@ -963,6 +1038,13 @@ pub struct UsageInsightsPerformancePoint {
     pub bucket_start: DateTime<Utc>,
     pub latency_percentiles: LatencyPercentiles,
     pub first_token_latency_percentiles: LatencyPercentiles,
+    pub admission_decision_percentiles: LatencyPercentiles,
+    pub account_selection_wait_percentiles: LatencyPercentiles,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization_avg_basis_points: Option<u64>,
+    pub capacity_utilization_p95_basis_points: Option<u64>,
 }
 
 /// 洞察性能汇总与可观测覆盖率。
@@ -972,6 +1054,16 @@ pub struct UsageInsightsPerformance {
     pub first_token_latency_percentiles: LatencyPercentiles,
     pub latency_coverage: f64,
     pub first_token_coverage: f64,
+    pub admission_decision_percentiles: LatencyPercentiles,
+    pub account_selection_wait_percentiles: LatencyPercentiles,
+    pub admission_decision_coverage: f64,
+    pub account_selection_wait_coverage: f64,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization_avg_basis_points: Option<u64>,
+    pub capacity_utilization_p95_basis_points: Option<u64>,
+    pub capacity_coverage: f64,
     pub points: Vec<UsageInsightsPerformancePoint>,
 }
 
@@ -985,6 +1077,8 @@ pub struct UsageInsightsCostPoint {
     pub total_tokens: u64,
     pub estimated_cost: Option<DecimalAmount>,
     pub standard_cost: Option<DecimalAmount>,
+    pub no_cache_cost: Option<DecimalAmount>,
+    pub cache_savings: Option<DecimalAmount>,
     pub cached_token_rate: f64,
     pub cache_hit_request_rate: Option<f64>,
 }
@@ -994,7 +1088,11 @@ pub struct UsageInsightsCostPoint {
 pub struct UsageInsightsCost {
     pub estimated_cost: Option<DecimalAmount>,
     pub standard_cost: Option<DecimalAmount>,
+    pub no_cache_cost: Option<DecimalAmount>,
+    pub cache_savings: Option<DecimalAmount>,
+    pub tier_premium: Option<DecimalAmount>,
     pub cost_per_request: Option<DecimalAmount>,
+    pub cost_per_successful_request: Option<DecimalAmount>,
     pub tokens_per_request: f64,
     pub cached_token_rate: f64,
     pub cache_hit_request_rate: Option<f64>,
@@ -1030,6 +1128,12 @@ pub struct DiagnosticsItem {
     pub request_share: f64,
     pub average_latency_ms: Option<u64>,
     pub latency_p95_ms: Option<u64>,
+    pub first_token_p95_ms: Option<u64>,
+    pub non_completion_count: u64,
+    pub non_completion_rate: f64,
+    pub retry_count: u64,
+    pub retry_rate: f64,
+    pub impact_score: f64,
     pub estimated_cost: Option<DecimalAmount>,
     pub attempt_count: u64,
     pub total_tokens: u64,

backend/crates/gateway-admin/src/model/provider_credentials.rs

@@ -1,17 +1,24 @@
 //! Provider 管理能力交换的中立 Command 与 Result。
 
-use std::fmt;
+use std::{fmt, pin::Pin};
 
 use async_trait::async_trait;
-use chrono::{DateTime, Utc};
+use bytes::Bytes;
+use chrono::{DateTime, NaiveDate, Utc};
+use futures::Stream;
 use gateway_core::{
-    engine::credential::{OpaqueProviderData, ProviderAccountId, ProviderAccountIdentity},
+    account::{OpaqueProviderData, ProviderAccountId, ProviderAccountIdentity},
     routing::{ProviderKind, UpstreamModelId},
 };
+use serde::Deserialize;
+use serde_json::{Map, Value};
+use uuid::Uuid;
 
 use super::{
-    AdminError, MutationActor, MutationContext, PageSize, Revision,
-    accounts::{AccountRecord, AccountSummary, AccountUsage, CredentialState},
+    AdminError, MutationActor, MutationContext, Revision,
+    accounts::{
+        AccountImportSettings, AccountRecord, AccountSummary, AccountUsage, CredentialState,
+    },
 };
 
 /// Provider-owned JSON；公共层只搬运且 Debug 不输出值。
@@ -42,56 +49,6 @@ impl fmt::Debug for ProviderDocument {
     }
 }
 
-/// Credential 列表稳定游标。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CredentialCursor {
-    pub created_at: DateTime<Utc>,
-    pub account_id: ProviderAccountId,
-}
-
-/// Provider credential 列表查询。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CredentialListQuery {
-    pub credential_state: Option<CredentialStateFilter>,
-    pub enabled: Option<bool>,
-    pub window: CredentialListWindow,
-}
-
-/// Credential 状态筛选。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum CredentialStateFilter {
-    Exact(CredentialState),
-    AnyOf(Vec<CredentialState>),
-}
-
-impl CredentialStateFilter {
-    #[must_use]
-    pub fn matches(&self, credential_state: CredentialState) -> bool {
-        match self {
-            Self::Exact(expected) => *expected == credential_state,
-            Self::AnyOf(expected) => expected.contains(&credential_state),
-        }
-    }
-}
-
-/// Credential 目录的集合窗口；完整列表与游标分页互斥。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum CredentialListWindow {
-    All,
-    Page {
-        cursor: Option<CredentialCursor>,
-        page_size: PageSize,
-    },
-}
-
-/// Provider credential 列表。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CredentialPage {
-    pub config_revision: Revision,
-    pub items: Vec<AccountRecord>,
-    pub next_cursor: Option<CredentialCursor>,
-}
-
 /// Provider credential 详情。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDetails {
@@ -101,6 +58,8 @@ pub struct CredentialDetails {
 
 /// Provider 正式文档批量导入命令。
 pub struct ImportCredentials {
+    pub outbound_proxy_id: Option<String>,
+    pub settings: Option<AccountImportSettings>,
     pub context: MutationContext,
     pub document: ProviderDocument,
 }
@@ -124,6 +83,7 @@ pub struct CredentialImportResult {
 
 /// Provider 解析导入文档时只接收不透明文档，不接触 revision 或审计上下文。
 pub struct PrepareCredentialImport {
+    pub default_outbound_proxy: Option<gateway_core::account::OutboundProxy>,
     pub document: ProviderDocument,
 }
 
@@ -139,6 +99,7 @@ impl fmt::Debug for PrepareCredentialImport {
 /// Provider 已验证、可由 Store 原子创建的一份 credential。
 #[derive(Debug, Clone, PartialEq)]
 pub struct PreparedCredentialCreate {
+    pub outbound_proxy: Option<gateway_core::account::OutboundProxy>,
     pub account_id: ProviderAccountId,
     pub provider_kind: ProviderKind,
     pub name: String,
@@ -166,6 +127,8 @@ pub struct PreparedCredentialImport {
 /// Admin 交给 Store 的导入事务命令。
 #[derive(Debug, Clone, PartialEq)]
 pub struct CredentialImportCommit {
+    pub outbound_proxy: Option<super::proxies::ImportProxyBinding>,
+    pub settings: Option<AccountImportSettings>,
     pub prepared: PreparedCredentialImport,
 }
 
@@ -244,6 +207,8 @@ pub struct PendingAuthorizationMutation {
     provider_kind: ProviderKind,
     target: AuthorizationMutationTarget,
     owner_binding: AuthorizationOwnerBinding,
+    outbound_proxy: Option<gateway_core::account::OutboundProxy>,
+    outbound_proxy_id: Option<String>,
 }
 
 impl PendingAuthorizationMutation {
@@ -257,6 +222,8 @@ impl PendingAuthorizationMutation {
             provider_kind,
             target,
             owner_binding,
+            outbound_proxy: None,
+            outbound_proxy_id: None,
         }
     }
 
@@ -274,6 +241,146 @@ impl PendingAuthorizationMutation {
     pub const fn owner_binding(&self) -> &AuthorizationOwnerBinding {
         &self.owner_binding
     }
+
+    #[must_use]
+    pub fn with_outbound_proxy(
+        mut self,
+        proxy: Option<gateway_core::account::OutboundProxy>,
+    ) -> Self {
+        self.outbound_proxy = proxy;
+        self
+    }
+
+    pub fn outbound_proxy(&self) -> Option<&gateway_core::account::OutboundProxy> {
+        self.outbound_proxy.as_ref()
+    }
+
+    #[must_use]
+    pub fn with_outbound_proxy_id(mut self, id: Option<String>) -> Self {
+        self.outbound_proxy_id = id;
+        self
+    }
+
+    pub fn outbound_proxy_id(&self) -> Option<&str> {
+        self.outbound_proxy_id.as_deref()
+    }
+}
+
+impl PendingAuthorizationMutation {
+    /// 编码 v1 中立事务字段；版本号的位置和 Provider 私有外层文档由 adapter 保持。
+    #[must_use]
+    pub fn to_storage_v1(&self) -> Map<String, Value> {
+        let target = match &self.target {
+            AuthorizationMutationTarget::Create { name } => {
+                serde_json::json!({"kind": "create", "name": name})
+            }
+            AuthorizationMutationTarget::Reauthorize { account_id } => {
+                serde_json::json!({"kind": "reauthorize", "account_id": account_id.to_string()})
+            }
+        };
+        let owner = match self.owner_binding.owner() {
+            AuthorizationOwner::AdminSession { admin_user_id } => {
+                serde_json::json!({"kind": "admin_session", "admin_user_id": admin_user_id})
+            }
+            AuthorizationOwner::AdminApiKey => serde_json::json!({"kind": "admin_api_key"}),
+            AuthorizationOwner::System => serde_json::json!({"kind": "system"}),
+        };
+        let mut document = Map::from_iter([
+            (
+                "provider_kind".to_owned(),
+                Value::String(self.provider_kind.as_str().to_owned()),
+            ),
+            ("target".to_owned(), target),
+            ("owner".to_owned(), owner),
+            (
+                "started_request_id".to_owned(),
+                Value::String(self.owner_binding.started_request_id().to_owned()),
+            ),
+        ]);
+        if let Some(proxy) = &self.outbound_proxy {
+            document.insert(
+                "outbound_proxy_url".to_owned(),
+                Value::String(proxy.expose_url().to_owned()),
+            );
+        }
+        if let Some(id) = &self.outbound_proxy_id {
+            document.insert("outbound_proxy_id".to_owned(), Value::String(id.clone()));
+        }
+        document
+    }
+
+    /// 恢复 adapter 已确认版本为 v1 的中立事务字段。
+    ///
+    /// # Errors
+    ///
+    /// 文档字段、Provider kind 或账号身份非法时返回错误，不携带原始 pending 内容。
+    pub fn from_storage_v1(value: Value) -> Result<Self, AdminError> {
+        let invalid = || AdminError::invalid("invalid pending authorization mutation");
+        let document: StoredAuthorizationMutationV1 =
+            serde_json::from_value(value).map_err(|_| invalid())?;
+        let provider_kind = ProviderKind::new(document.provider_kind).map_err(|_| invalid())?;
+        let target = match document.target {
+            StoredAuthorizationTargetV1::Create { name } => {
+                AuthorizationMutationTarget::Create { name }
+            }
+            StoredAuthorizationTargetV1::Reauthorize { account_id } => {
+                AuthorizationMutationTarget::Reauthorize {
+                    account_id: ProviderAccountId::new(account_id).map_err(|_| invalid())?,
+                }
+            }
+        };
+        let owner = match document.owner {
+            StoredAuthorizationOwnerV1::AdminSession { admin_user_id } => {
+                AuthorizationOwner::AdminSession { admin_user_id }
+            }
+            StoredAuthorizationOwnerV1::AdminApiKey => AuthorizationOwner::AdminApiKey,
+            StoredAuthorizationOwnerV1::System => AuthorizationOwner::System,
+        };
+        let proxy = document
+            .outbound_proxy_url
+            .as_deref()
+            .map(gateway_core::account::OutboundProxy::parse)
+            .transpose()
+            .map_err(|_| invalid())?;
+        Ok(Self::new(
+            provider_kind,
+            target,
+            AuthorizationOwnerBinding {
+                owner,
+                started_request_id: document.started_request_id,
+            },
+        )
+        .with_outbound_proxy(proxy)
+        .with_outbound_proxy_id(document.outbound_proxy_id))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct StoredAuthorizationMutationV1 {
+    provider_kind: String,
+    target: StoredAuthorizationTargetV1,
+    owner: StoredAuthorizationOwnerV1,
+    started_request_id: String,
+    #[serde(default)]
+    outbound_proxy_url: Option<String>,
+    #[serde(default)]
+    outbound_proxy_id: Option<String>,
+}
+
+#[derive(Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+enum StoredAuthorizationTargetV1 {
+    Create { name: String },
+    Reauthorize { account_id: String },
+}
+
+#[derive(Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+enum StoredAuthorizationOwnerV1 {
+    AdminSession { admin_user_id: String },
+    AdminApiKey,
+    System,
 }
 
 /// 启动 Provider OAuth Authorization Code 流程。
@@ -282,6 +389,7 @@ pub struct StartAuthorization {
     pub context: MutationContext,
     pub name: String,
     pub reauthorization: Option<ProviderAccountId>,
+    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
 /// OAuth 流程启动结果。
@@ -347,6 +455,7 @@ pub enum AuthorizationCredentialCommit {
 /// Admin 交给 Store 的 OAuth 原子事务命令。
 #[derive(Debug, Clone, PartialEq)]
 pub struct AuthorizationCommit {
+    pub settings: Option<AccountImportSettings>,
     pub pending: PendingAuthorizationMutation,
     pub credential: AuthorizationCredentialCommit,
 }
@@ -381,7 +490,10 @@ impl PreparedAuthorizationCommit {
         self
     }
 
-    pub(crate) fn into_commit(self) -> AuthorizationCommitSettlement {
+    pub(crate) fn into_commit(
+        self,
+        settings: Option<AccountImportSettings>,
+    ) -> AuthorizationCommitSettlement {
         let (credential, guard) = match self.credential {
             PreparedAuthorizationCredential::Create(credential) => {
                 (AuthorizationCredentialCommit::Create(credential), None)
@@ -396,6 +508,7 @@ impl PreparedAuthorizationCommit {
         };
         AuthorizationCommitSettlement {
             command: AuthorizationCommit {
+                settings,
                 pending: self.pending,
                 credential,
             },
@@ -409,7 +522,7 @@ impl PreparedAuthorizationCommit {
             credential_guard,
             authorization_guard,
             ..
-        } = self.into_commit();
+        } = self.into_commit(None);
         drop(credential_guard);
         if let Some(guard) = authorization_guard {
             guard.abort().await?;
@@ -421,6 +534,7 @@ impl PreparedAuthorizationCommit {
 /// 完成 Provider OAuth 流程。
 #[derive(Clone, PartialEq, Eq)]
 pub struct CompleteAuthorization {
+    pub settings: Option<AccountImportSettings>,
     pub context: MutationContext,
     pub flow_id: String,
     pub callback_url: String,
@@ -570,13 +684,34 @@ pub enum QuotaLocalUsageAttribution {
     Unavailable,
 }
 
+/// Provider quota bucket 中窗口的官方位置语义。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProviderQuotaWindowRole {
+    Primary,
+    Secondary,
+    Monthly,
+}
+
+impl ProviderQuotaWindowRole {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Primary => "primary",
+            Self::Secondary => "secondary",
+            Self::Monthly => "monthly",
+        }
+    }
+}
+
 /// 一个 Provider quota 窗口的公共投影。
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuotaWindow {
     pub key: String,
     pub group: String,
     pub label: String,
-    pub source: Option<String>,
+    pub limit_id: Option<String>,
+    pub limit_name: Option<String>,
+    pub role: Option<ProviderQuotaWindowRole>,
     pub local_usage_attribution: QuotaLocalUsageAttribution,
     pub window_seconds: Option<u64>,
     pub used_percent: Option<f64>,
@@ -586,6 +721,13 @@ pub struct ProviderQuotaWindow {
     pub provider_data: Option<ProviderDocument>,
 }
 
+/// 账号用量统计周期，按周优先、月次之选择；短期限流窗口不参与统计面板。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum AccountUsagePeriod {
+    Weekly,
+    Monthly,
+}
+
 /// Provider 解释 quota 所需的公共请求事实。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderQuotaRequest {
@@ -597,6 +739,8 @@ pub struct ProviderQuotaRequest {
 /// Provider 已解析的 quota 结果及其不透明差异字段。
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuota {
+    /// 上游额度响应明确提供的套餐，可用于补全账号展示。
+    pub plan_type: Option<String>,
     pub observed_at: Option<DateTime<Utc>>,
     pub refresh_token_expires_at: Option<DateTime<Utc>>,
     pub windows: Vec<ProviderQuotaWindow>,
@@ -605,61 +749,272 @@ pub struct ProviderQuota {
     pub provider_data: Option<ProviderDocument>,
 }
 
+/// 空值和 `unknown` 代表未提供套餐；新的套餐标识仍按明确值保留。
+pub(crate) fn explicit_plan_type(value: Option<&str>) -> Option<&str> {
+    value.filter(|value| {
+        let value = value.trim();
+        !value.is_empty() && !value.eq_ignore_ascii_case("unknown")
+    })
+}
+
+/// Provider 官方个人资料中的累计摘要。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderProfileStatisticsSummary {
+    pub total_text_tokens: Option<u64>,
+    pub peak_tokens: Option<u64>,
+    pub longest_task_duration_ms: Option<u64>,
+    pub current_streak_days: Option<u64>,
+    pub longest_streak_days: Option<u64>,
+}
+
+/// Provider 官方个人资料中的单日 Token bucket。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderProfileDailyUsage {
+    pub date: NaiveDate,
+    pub tokens: u64,
+}
+
+/// Provider 官方个人资料中的插件或 Skill 调用排行。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderProfileInvocation {
+    pub invocation_type: String,
+    pub plugin_id: Option<String>,
+    pub plugin_name: Option<String>,
+    pub skill_id: Option<String>,
+    pub skill_name: Option<String>,
+    pub usage_count: Option<u64>,
+}
+
+/// Provider 官方个人资料中的活动洞察。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProviderProfileActivityInsights {
+    pub fast_mode_percent: Option<f64>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_effort_percent: Option<f64>,
+    pub skills_explored: Option<u64>,
+    pub total_skills_used: Option<u64>,
+    pub total_threads: Option<u64>,
+    pub invocations: Option<Vec<ProviderProfileInvocation>>,
+}
+
+/// Provider 已解释的官方个人资料统计。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ProviderProfileStatistics {
+    pub display_name: Option<String>,
+    pub username: Option<String>,
+    pub image_url: Option<String>,
+    pub has_stats_error: bool,
+    pub summary: ProviderProfileStatisticsSummary,
+    pub daily_usage: Option<Vec<ProviderProfileDailyUsage>>,
+    pub activity_insights: ProviderProfileActivityInsights,
+}
+
+/// Provider 头像正文的中立字节流；公共层不解释 MIME，也不限制总字节数。
+pub type ProviderProfileAvatarStream =
+    Pin<Box<dyn Stream<Item = Result<Bytes, ProviderProfileAvatarStreamError>> + Send + 'static>>;
+
+/// Provider 头像流在响应开始后的通用失败，不携带上游 URL 或正文。
+#[derive(Debug, thiserror::Error)]
+#[error("provider profile avatar stream failed")]
+pub struct ProviderProfileAvatarStreamError;
+
+/// Provider 已校验并打开的官方头像响应。
+pub struct ProviderProfileAvatar {
+    pub content_type: Option<String>,
+    pub content_length: Option<u64>,
+    pub etag: Option<String>,
+    pub body: ProviderProfileAvatarStream,
+}
+
+impl fmt::Debug for ProviderProfileAvatar {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("ProviderProfileAvatar")
+            .field("content_type", &self.content_type)
+            .field("content_length", &self.content_length)
+            .field("etag", &self.etag)
+            .field("body", &"<stream>")
+            .finish()
+    }
+}
+
+/// Provider 返回的一张安全主动额度重置卡。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderResetCredit {
+    pub id: String,
+    pub status: Option<String>,
+    pub title: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub reset_type: Option<String>,
+}
+
+/// Provider 主动额度重置卡列表。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderResetCredits {
+    pub available_count: u64,
+    pub credits: Vec<ProviderResetCredit>,
+}
+
+/// 一次主动额度重置卡消费命令。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConsumeProviderResetCredit {
+    pub account_id: ProviderAccountId,
+    pub credit_id: Option<String>,
+    pub redeem_request_id: Uuid,
+}
+
+/// Provider 返回的主动额度重置卡消费结果。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderResetCreditResult {
+    pub code: String,
+    pub credit: Option<ProviderResetCredit>,
+}
+
 impl ProviderQuota {
-    /// 返回账号展开面板使用的当前额度窗口用量。
+    /// 保留账号已有的套餐子类型，仅在缺失时使用上游额度快照补全。
+    pub(crate) fn fill_missing_plan_type(&self, account_plan_type: &mut Option<String>) {
+        if explicit_plan_type(account_plan_type.as_deref()).is_none() {
+            *account_plan_type = explicit_plan_type(self.plan_type.as_deref()).map(str::to_owned);
+        }
+    }
+
+    /// 选择账号用量统计的周/月窗口，同时返回展示所需的周期事实。
     ///
-    /// 只选择具备完整时间边界且可按账号归属的窗口；优先级与 Dashboard
-    /// 代表性额度窗口一致，同一优先级保持 Provider 投影顺序。
+    /// 只使用边界完整、可归属到整个账号的窗口；周优先于月，同周期保持
+    /// Provider 投影顺序。没有符合条件的窗口时不回退到短期或历史累计。
     #[must_use]
-    pub fn representative_window_usage(&self) -> Option<&AccountUsage> {
-        self.windows
-            .iter()
-            .enumerate()
-            .filter(|(_, window)| {
-                window.local_usage_attribution == QuotaLocalUsageAttribution::AccountWide
-                    && window.window_seconds.is_some()
-                    && window.reset_at.is_some()
-                    && window.local_usage.is_some()
-            })
-            .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
-            .and_then(|(_, window)| window.local_usage.as_ref())
+    pub fn usage_window(&self) -> Option<(&ProviderQuotaWindow, AccountUsagePeriod)> {
+        self.usage_windows()
+            .filter(|(window, _)| window.local_usage.is_some())
+            .min_by_key(|(_, period)| *period)
+    }
+
+    /// 统计与预测共用窗口归属规则，避免把模型专属桶或短期限流当作账号容量。
+    pub(crate) fn usage_windows(
+        &self,
+    ) -> impl Iterator<Item = (&ProviderQuotaWindow, AccountUsagePeriod)> {
+        self.windows.iter().filter_map(|window| {
+            if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide
+                || window.reset_at.is_none()
+            {
+                return None;
+            }
+            let seconds = window.window_seconds?;
+            let period = if is_week_window(seconds) {
+                AccountUsagePeriod::Weekly
+            } else if window.group == "monthly" && seconds >= 7 * 24 * 60 * 60 {
+                AccountUsagePeriod::Monthly
+            } else {
+                return None;
+            };
+            Some((window, period))
+        })
     }
 
     /// 返回 Dashboard 使用的代表性额度比例。
     ///
-    /// 优先使用短周期窗口，再依次使用周、月和其它窗口；同一优先级取较高的已用比例。
-    /// 这里只解释跨 Provider 共享的窗口语义，绝不读取 Provider 私有 JSON。
+    /// 优先使用覆盖账号全部请求的窗口；同一归属范围内再依次使用短周期、周、月
+    /// 和其它窗口，同一优先级取较高的已用比例。这里只解释跨 Provider 共享的窗口
+    /// 语义，绝不读取 Provider 私有 JSON。
     #[must_use]
     pub fn representative_used_percent(&self) -> Option<f64> {
+        if self.limit_reached {
+            return Some(100.0);
+        }
+        self.representative_used_window()
+            .map(|(_, used_percent)| used_percent)
+    }
+
+    /// 选择 Dashboard 展示的真实窗口；没有百分比时仍保留 Provider 的滚动窗口语义。
+    #[must_use]
+    pub fn representative_window(&self) -> Option<&ProviderQuotaWindow> {
+        self.representative_used_window()
+            .map(|(index, _)| &self.windows[index])
+            .or_else(|| {
+                self.windows
+                    .iter()
+                    .enumerate()
+                    .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
+                    .map(|(_, window)| window)
+            })
+    }
+
+    /// 将已确认的账号级额度耗尽事实投影到展示窗口。
+    ///
+    /// Provider 已指出具体触顶窗口时只归一化这些窗口；否则归一化 Dashboard
+    /// 同样会选择的代表窗口，避免把多个独立额度窗口全部伪造成已用尽。
+    pub fn apply_limit_reached_display(&mut self) {
+        if !self.limit_reached {
+            return;
+        }
+        let reached_windows = self
+            .windows
+            .iter()
+            .enumerate()
+            .filter_map(|(index, window)| window.limit_reached.then_some(index))
+            .collect::<Vec<_>>();
+        if !reached_windows.is_empty() {
+            for index in reached_windows {
+                self.windows[index].used_percent = Some(100.0);
+            }
+            return;
+        }
+        let representative = self
+            .representative_used_window()
+            .map(|(index, _)| index)
+            .or_else(|| {
+                self.windows
+                    .iter()
+                    .enumerate()
+                    .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
+                    .map(|(index, _)| index)
+            });
+        if let Some(index) = representative {
+            self.windows[index].used_percent = Some(100.0);
+            self.windows[index].limit_reached = true;
+        }
+    }
+
+    fn representative_used_window(&self) -> Option<(usize, f64)> {
         self.windows
             .iter()
+            .enumerate()
             .filter_map(|window| {
+                let (index, window) = window;
                 let used_percent = window
                     .used_percent
                     .filter(|value| value.is_finite())
                     .map(|value| value.clamp(0.0, 100.0))?;
-                Some((quota_usage_priority(window), used_percent))
+                Some((index, quota_usage_priority(window), used_percent))
             })
-            .fold(None::<(u8, f64)>, |selected, candidate| match selected {
-                Some(current)
-                    if current.0 < candidate.0
-                        || (current.0 == candidate.0 && current.1 >= candidate.1) =>
-                {
+            .fold(
+                None::<(usize, (u8, u8), f64)>,
+                |selected, candidate| match selected {
                     Some(current)
-                }
-                _ => Some(candidate),
-            })
-            .map(|(_, used_percent)| used_percent)
+                        if current.1 < candidate.1
+                            || (current.1 == candidate.1 && current.2 >= candidate.2) =>
+                    {
+                        Some(current)
+                    }
+                    _ => Some(candidate),
+                },
+            )
+            .map(|(index, _, used_percent)| (index, used_percent))
     }
 }
 
-fn quota_usage_priority(window: &ProviderQuotaWindow) -> u8 {
-    match window.group.as_str() {
+fn quota_usage_priority(window: &ProviderQuotaWindow) -> (u8, u8) {
+    let attribution = match window.local_usage_attribution {
+        QuotaLocalUsageAttribution::AccountWide => 0,
+        QuotaLocalUsageAttribution::Unavailable => 1,
+    };
+    let duration = match window.group.as_str() {
         "shortTerm" if window.window_seconds.is_some_and(is_week_window) => 1,
         "shortTerm" => 0,
         "monthly" => 2,
         _ => 3,
-    }
+    };
+    (attribution, duration)
 }
 
 fn is_week_window(seconds: u64) -> bool {
@@ -716,7 +1071,9 @@ impl fmt::Debug for ProviderExport {
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryItem {
     pub account: AccountRecord,
-    pub projection: gateway_core::engine::credential::AccountStatusProjection,
+    /// Provider 提供的套餐展示名称；未识别到套餐时为空。
+    pub plan_type_display: Option<String>,
+    pub projection: gateway_core::account::AccountStatusProjection,
     pub usage: Option<super::accounts::AccountUsage>,
     pub quota: ProviderQuota,
 }

backend/crates/gateway-admin/src/model/proxies.rs

@@ -0,0 +1,105 @@
+//! 可复用的账号出口配置，以及脱敏后的连通性测试结果。
+
+use chrono::{DateTime, Utc};
+use gateway_core::account::OutboundProxy;
+
+use super::{PageSize, Revision, account_groups::AccountGroupRef};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccountProxySelection {
+    Direct,
+    Url(OutboundProxy),
+    Saved(String),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImportProxyBinding {
+    pub id: String,
+    pub proxy: OutboundProxy,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyListQuery {
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyAccountRef {
+    pub id: String,
+    pub name: String,
+    pub email: Option<String>,
+    pub provider_kind: String,
+    pub authentication_kind: String,
+    pub plan_type: Option<String>,
+    pub plan_type_display: Option<String>,
+    pub groups: Vec<AccountGroupRef>,
+    pub enabled: bool,
+}
+
+/// 按代理查询关联账号，分页与搜索均在存储层执行。
+#[derive(Debug, Clone)]
+pub struct ProxyAccountListQuery {
+    pub proxy_id: String,
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyAccountPage {
+    pub items: Vec<ProxyAccountRef>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyTestResult {
+    pub success: bool,
+    pub latency_ms: u64,
+    pub exit_ip: Option<std::net::IpAddr>,
+    pub message: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyRecord {
+    pub id: String,
+    pub name: String,
+    pub proxy: OutboundProxy,
+    pub revision: Revision,
+    pub account_count: u64,
+    pub last_test_at: Option<DateTime<Utc>>,
+    pub last_test: Option<ProxyTestResult>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyPage {
+    pub items: Vec<ProxyRecord>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+#[derive(Debug, Clone)]
+pub struct NewProxy {
+    pub name: String,
+    pub proxy: OutboundProxy,
+}
+
+#[derive(Debug, Clone)]
+pub struct UpdateProxy {
+    pub id: String,
+    pub revision: Revision,
+    pub name: String,
+    pub proxy: Option<OutboundProxy>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyMutation {
+    pub config_revision: Revision,
+    pub record: ProxyRecord,
+}

backend/crates/gateway-admin/src/model/quota_forecast.rs

@@ -0,0 +1,207 @@
+//! 账号额度的只读容量估算，不参与金额结算或账号调度。
+
+use chrono::{DateTime, Duration, Utc};
+
+use super::provider_credentials::{AccountUsagePeriod, ProviderQuota, ProviderQuotaWindow};
+use super::quota_forecast_sampling::{QuotaForecastMethod, QuotaForecastSample};
+
+const DAY_SECONDS: u64 = 86_400;
+const MIN_USED_PERCENT: f64 = 5.0;
+const LOW_SAMPLE_PERCENT: f64 = 10.0;
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountQuotaForecastReport {
+    pub account_id: String,
+    pub generated_at: DateTime<Utc>,
+    pub forecasts: [AccountQuotaForecast; 2],
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountQuotaForecast {
+    pub period: AccountUsagePeriod,
+    pub target_seconds: u64,
+    pub extrapolated: bool,
+    pub source: Option<QuotaForecastSource>,
+    pub unavailable_reason: Option<&'static str>,
+    pub low_sample: bool,
+    pub incomplete_cost: bool,
+    pub incomplete_tokens: bool,
+    pub estimated_tokens: Option<u64>,
+    pub estimated_usd: Option<f64>,
+    /// 剩余估算始终属于源窗口，不随目标周期折算。
+    pub remaining_tokens: Option<u64>,
+    pub remaining_usd: Option<f64>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuotaForecastSource {
+    pub label: String,
+    pub used_percent: Option<f64>,
+    pub observed_at: Option<DateTime<Utc>>,
+    pub reset_at: DateTime<Utc>,
+    pub tokens: Option<u64>,
+    pub usd: Option<f64>,
+}
+
+/// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算。
+/// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度。
+#[must_use]
+pub fn account_quota_forecasts(
+    quota: &ProviderQuota,
+    account_added_at: DateTime<Utc>,
+    now: DateTime<Utc>,
+    samples: &[QuotaForecastSample],
+) -> [AccountQuotaForecast; 2] {
+    [AccountUsagePeriod::Weekly, AccountUsagePeriod::Monthly].map(|period| {
+        let selected = quota
+            .usage_windows()
+            .find(|(_, source_period)| *source_period == period)
+            .or_else(|| quota.usage_windows().min_by_key(|(_, period)| *period));
+        let mut forecast = AccountQuotaForecast {
+            period,
+            target_seconds: match period {
+                AccountUsagePeriod::Weekly => 7 * DAY_SECONDS,
+                AccountUsagePeriod::Monthly => 30 * DAY_SECONDS,
+            },
+            extrapolated: false,
+            source: None,
+            unavailable_reason: Some("没有可统计的周/月额度窗口，请先刷新账号额度。"),
+            low_sample: false,
+            incomplete_cost: false,
+            incomplete_tokens: false,
+            estimated_tokens: None,
+            estimated_usd: None,
+            remaining_tokens: None,
+            remaining_usd: None,
+        };
+        if let Some((window, source_period)) = selected {
+            forecast.project(
+                window,
+                source_period,
+                quota.observed_at,
+                account_added_at,
+                now,
+                samples.iter().find(|sample| sample.key == window.key),
+            );
+        }
+        forecast
+    })
+}
+
+impl AccountQuotaForecast {
+    fn project(
+        &mut self,
+        window: &ProviderQuotaWindow,
+        source_period: AccountUsagePeriod,
+        observed_at: Option<DateTime<Utc>>,
+        account_added_at: DateTime<Utc>,
+        now: DateTime<Utc>,
+        sample: Option<&QuotaForecastSample>,
+    ) {
+        let (Some(seconds), Some(reset_at)) = (window.window_seconds, window.reset_at) else {
+            return;
+        };
+        self.extrapolated = source_period != self.period;
+        if !self.extrapolated {
+            self.target_seconds = seconds;
+        }
+        let percent = window
+            .used_percent
+            .filter(|p| p.is_finite() && (0.0..=100.0).contains(p));
+        let usage = sample.map(|sample| &sample.usage);
+        let usd = usage
+            .filter(|usage| usage.known_cost_count > 0)
+            .map(|usage| usage.usd)
+            .filter(|value| value.is_finite() && *value >= 0.0);
+        let start = i64::try_from(seconds)
+            .ok()
+            .and_then(Duration::try_seconds)
+            .and_then(|duration| reset_at.checked_sub_signed(duration));
+        self.source = Some(QuotaForecastSource {
+            label: window.label.clone(),
+            used_percent: percent,
+            observed_at,
+            reset_at,
+            tokens: usage.map(|usage| usage.tokens),
+            usd,
+        });
+        self.incomplete_cost = usage.is_none_or(|usage| {
+            usage.unavailable_cost_count > 0
+                || usage.known_cost_count == 0
+                || usage.known_cost_count != usage.request_count
+        });
+        self.incomplete_tokens = usage.is_some_and(|usage| usage.missing_token_count > 0);
+        let method = sample.map_or(QuotaForecastMethod::Cumulative, |sample| sample.method);
+        let Some(start) = start.filter(|start| *start <= now && now < reset_at) else {
+            self.unavailable_reason = Some("额度窗口已过期或边界无效，请刷新账号额度后重试。");
+            return;
+        };
+        if !observed_at.is_some_and(|observed| start <= observed && observed <= now) {
+            self.unavailable_reason = Some("缺少本周期的额度快照，请先刷新账号额度。");
+            return;
+        }
+        if sample.is_some_and(|sample| sample.discontinuous) {
+            self.unavailable_reason =
+                Some("额度观测出现回落或累计记录不连续，正在重新积累配对样本。");
+            return;
+        }
+        if account_added_at > start && method == QuotaForecastMethod::Cumulative {
+            self.unavailable_reason = Some(
+                "本周期开始时的记录不完整，正在积累至少 5 个百分点的配对观测，无需等待下次重置。",
+            );
+            return;
+        }
+        let Some(percent) = percent else {
+            self.unavailable_reason = Some("已用比例未知，请刷新额度后查看预测。");
+            return;
+        };
+        let Some(usage) = usage.filter(|usage| usage.request_count > 0) else {
+            self.unavailable_reason = Some("本周期没有网关用量记录，暂时无法预测额度。");
+            return;
+        };
+        let Some(sample) = sample.filter(|sample| {
+            sample.end_at == observed_at.unwrap_or(now)
+                && start <= sample.start_at
+                && sample.start_at <= sample.end_at
+                && sample.sampled_percent.is_finite()
+                && sample.sampled_percent >= MIN_USED_PERCENT
+                && sample.sampled_percent <= percent
+        }) else {
+            self.unavailable_reason =
+                Some("有效额度进度不足 5 个百分点或采样边界无效，请继续积累用量。");
+            return;
+        };
+        self.low_sample = sample.sampled_percent < LOW_SAMPLE_PERCENT
+            || (method == QuotaForecastMethod::Incremental && sample.block_count < 2);
+        // 预测是近似展示值；不复用为账单金额，也不把月折算当成自然月或额外余额。
+        let capacity_factor = 100.0 / sample.sampled_percent;
+        let factor = capacity_factor * self.target_seconds as f64 / seconds as f64;
+        let tokens = Some(usage.tokens).filter(|tokens| *tokens > 0 && !self.incomplete_tokens);
+        self.estimated_tokens = tokens.and_then(|value| estimate_tokens(value, factor));
+        self.estimated_usd = usd
+            .filter(|_| !self.incomplete_cost)
+            .and_then(|value| estimate(value, factor));
+        let remaining_factor = (100.0 - percent) / sample.sampled_percent;
+        self.remaining_tokens = tokens.and_then(|value| estimate_tokens(value, remaining_factor));
+        self.remaining_usd = usd
+            .filter(|_| !self.incomplete_cost)
+            .and_then(|value| estimate(value, remaining_factor));
+        self.unavailable_reason = if self.estimated_tokens.is_none() && self.estimated_usd.is_none()
+        {
+            Some("本周期缺少可用的 Token 或完整费用记录，暂时无法预测额度。")
+        } else {
+            None
+        };
+    }
+}
+
+fn estimate(value: f64, factor: f64) -> Option<f64> {
+    let estimate = value * factor;
+    (estimate.is_finite() && estimate >= 0.0).then_some(estimate)
+}
+
+fn estimate_tokens(value: u64, factor: f64) -> Option<u64> {
+    estimate(value as f64, factor)
+        .filter(|value| value.round() < u64::MAX as f64)
+        .map(|value| value.round() as u64)
+}

backend/crates/gateway-admin/src/model/quota_forecast_sampling.rs

@@ -0,0 +1,190 @@
+//! 预测专用的配对采样；不改变完整交付用量或费用账本的统计口径。
+
+use chrono::{DateTime, Utc};
+
+use super::provider_credentials::ProviderDocument;
+
+/// 限制带 Provider 文档的历史点数量；累计用量仍覆盖整个查询区间。
+pub const MAX_FORECAST_HISTORY_POINTS: usize = 128;
+const MIN_BLOCK_PERCENT: f64 = 5.0;
+const RECENT_BLOCKS: usize = 3;
+
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct QuotaForecastUsage {
+    pub request_count: u64,
+    pub tokens: u64,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_tokens: u64,
+    pub missing_token_count: u64,
+    pub known_cost_count: u64,
+    pub unavailable_cost_count: u64,
+    pub usd: f64,
+    pub excluded_request_count: u64,
+}
+
+impl QuotaForecastUsage {
+    /// 累计计数倒退表示不能配对，不用饱和减法掩盖数据断点。
+    fn difference(&self, baseline: &Self) -> Option<Self> {
+        let usd = self.usd - baseline.usd;
+        if !usd.is_finite() || usd < -1e-9 {
+            return None;
+        }
+        Some(Self {
+            request_count: self.request_count.checked_sub(baseline.request_count)?,
+            tokens: self.tokens.checked_sub(baseline.tokens)?,
+            input_tokens: self.input_tokens.checked_sub(baseline.input_tokens)?,
+            output_tokens: self.output_tokens.checked_sub(baseline.output_tokens)?,
+            cached_tokens: self.cached_tokens.checked_sub(baseline.cached_tokens)?,
+            missing_token_count: self
+                .missing_token_count
+                .checked_sub(baseline.missing_token_count)?,
+            known_cost_count: self
+                .known_cost_count
+                .checked_sub(baseline.known_cost_count)?,
+            unavailable_cost_count: self
+                .unavailable_cost_count
+                .checked_sub(baseline.unavailable_cost_count)?,
+            usd: usd.max(0.0),
+            excluded_request_count: self
+                .excluded_request_count
+                .checked_sub(baseline.excluded_request_count)?,
+        })
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastHistoryPoint {
+    pub started_at: DateTime<Utc>,
+    pub completed_at: DateTime<Utc>,
+    pub usage: QuotaForecastUsage,
+    pub provider_observation: ProviderDocument,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct QuotaForecastHistory {
+    pub points: Vec<QuotaForecastHistoryPoint>,
+    pub usage: QuotaForecastUsage,
+    pub pending_request_count: u64,
+}
+
+/// 具体 Provider 从自己的历史文档解释出的额度事实。
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuotaForecastObservation {
+    pub used_percent: f64,
+    pub reset_at: DateTime<Utc>,
+    pub plan_type: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastPoint {
+    pub observed_at: DateTime<Utc>,
+    pub used_percent: f64,
+    pub usage: QuotaForecastUsage,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum QuotaForecastMethod {
+    Cumulative,
+    Incremental,
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastSample {
+    pub key: String,
+    pub method: QuotaForecastMethod,
+    pub start_at: DateTime<Utc>,
+    pub end_at: DateTime<Utc>,
+    pub baseline_percent: f64,
+    pub sampled_percent: f64,
+    pub block_count: usize,
+    pub observation_count: usize,
+    pub pending_request_count: u64,
+    pub discontinuous: bool,
+    pub usage: QuotaForecastUsage,
+}
+
+/// 对同一额度段的累计点形成至少 5 个百分点的连续块，使用最近三个完整块及尾部。
+/// 不平均逐请求比值；重复百分比不增加块数，5/10 个百分点仅是量化噪声门槛。
+#[must_use]
+pub fn select_forecast_sample(
+    key: String,
+    start_at: DateTime<Utc>,
+    current: QuotaForecastPoint,
+    mut history: Vec<QuotaForecastPoint>,
+    pending_request_count: u64,
+) -> QuotaForecastSample {
+    history.retain(|point| {
+        start_at <= point.observed_at
+            && point.observed_at < current.observed_at
+            && point.used_percent.is_finite()
+            && (0.0..100.0).contains(&point.used_percent)
+    });
+    history.sort_by_key(|point| point.observed_at);
+    let mut sample = QuotaForecastSample {
+        key,
+        method: QuotaForecastMethod::Cumulative,
+        start_at,
+        end_at: current.observed_at,
+        baseline_percent: 0.0,
+        sampled_percent: current.used_percent,
+        block_count: 0,
+        observation_count: history.len(),
+        pending_request_count,
+        discontinuous: false,
+        usage: current.usage.clone(),
+    };
+    history.push(current);
+    let mut anchors: Vec<&QuotaForecastPoint> = Vec::new();
+    let mut high_water: Option<&QuotaForecastPoint> = None;
+    for point in &history {
+        if let Some(previous) = high_water {
+            if point.observed_at <= previous.observed_at {
+                continue;
+            }
+            if point.used_percent < previous.used_percent {
+                // 一个百分点内的回落可能是量化/并发乱序；更大的回落不能跨越。
+                if previous.used_percent - point.used_percent <= 1.0 {
+                    continue;
+                }
+                sample.discontinuous = true;
+                anchors.clear();
+            }
+        }
+        high_water = Some(point);
+        if anchors
+            .last()
+            .is_none_or(|anchor| point.used_percent - anchor.used_percent >= MIN_BLOCK_PERCENT)
+        {
+            anchors.push(point);
+        }
+    }
+    let Some(current) = history.last() else {
+        return sample;
+    };
+    if anchors.len() < 2 {
+        return sample;
+    }
+    let baseline_index = anchors.len().saturating_sub(RECENT_BLOCKS + 1);
+    let baseline = anchors[baseline_index];
+    let progress = current.used_percent - baseline.used_percent;
+    if !progress.is_finite() || progress < MIN_BLOCK_PERCENT {
+        return sample;
+    }
+    let Some(usage) = current.usage.difference(&baseline.usage) else {
+        sample.discontinuous = true;
+        return sample;
+    };
+    if usage.request_count == 0 {
+        return sample;
+    }
+    sample.method = QuotaForecastMethod::Incremental;
+    sample.start_at = baseline.observed_at;
+    sample.baseline_percent = baseline.used_percent;
+    sample.sampled_percent = progress;
+    sample.block_count = anchors.len() - baseline_index - 1;
+    sample.usage = usage;
+    // 断点后的新基线已有足够进度时，只消费新段；旧段从不参与本次估算。
+    sample.discontinuous = false;
+    sample
+}

backend/crates/gateway-admin/src/model/settings.rs

@@ -12,7 +12,7 @@ use super::Revision;
 pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;
 
 /// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
-pub use gateway_core::engine::credential::RotationStrategy;
+pub use gateway_core::account::RotationStrategy;
 
 /// 完整运行设置事实。
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -24,6 +24,8 @@ pub struct RuntimeSettings {
     pub max_concurrent_per_account: u32,
     pub request_interval_ms: u64,
     pub rotation_strategy: RotationStrategy,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
     pub usage_retention_days: u32,
     pub ops_event_retention_days: u32,
     pub audit_retention_days: u32,
@@ -39,6 +41,8 @@ pub struct ReplaceRuntimeSettings {
     pub max_concurrent_per_account: u32,
     pub request_interval_ms: u64,
     pub rotation_strategy: RotationStrategy,
+    pub min_codex_desktop_version: Option<String>,
+    pub min_codex_cli_version: Option<String>,
     pub usage_retention_days: u32,
     pub ops_event_retention_days: u32,
     pub audit_retention_days: u32,

backend/crates/gateway-admin/src/ports/backup.rs

@@ -145,7 +145,7 @@ pub trait DatabaseDumpPort: Send + Sync {
 #[derive(Debug, Clone)]
 pub struct DumpRequest {
     pub backup_id: String,
-    pub cancellation: gateway_core::engine::CancellationToken,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
 }
 
 /// 已完成并落盘的归档事实。
@@ -212,7 +212,7 @@ pub struct UploadObjectRequest {
     pub object_key: String,
     pub source: PathBuf,
     pub metadata: BackupObjectMetadata,
-    pub cancellation: gateway_core::engine::CancellationToken,
+    pub cancellation: gateway_core::lifecycle::CancellationToken,
 }
 
 /// 备份控制面所需的全部 Store 能力集合。

backend/crates/gateway-admin/src/ports/client_distribution.rs

@@ -0,0 +1,10 @@
+//! 客户端安装包解析的外部能力端口。
+
+use async_trait::async_trait;
+
+use crate::model::client_distribution::CodexDesktopWindowsDownloads;
+
+#[async_trait]
+pub trait ClientDistributionResolver: Send + Sync {
+    async fn resolve_codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}

backend/crates/gateway-admin/src/ports/mod.rs

@@ -1,6 +1,8 @@
 //! 管理用例依赖的外部能力端口。
 
 pub mod backup;
+pub mod client_distribution;
 pub mod provider;
+pub mod proxy;
 pub mod store;
 pub mod system;

backend/crates/gateway-admin/src/ports/provider.rs

@@ -4,20 +4,26 @@ use std::{collections::BTreeMap, sync::Arc};
 
 use async_trait::async_trait;
 use gateway_core::{
-    engine::credential::ProviderAccountId,
+    account::ProviderAccountId,
     operation::Operation,
     routing::{ProviderKind, UpstreamModelId},
 };
+use heck::ToUpperCamelCase;
 
 use crate::model::observability::{
     CalculatedBillingBreakdown, DashboardWireProfile, ProviderBillingInput,
 };
 use crate::model::provider_credentials::{
-    AuthorizationStarted, CompleteAuthorization, PendingAuthorizationMutation,
-    PrepareCredentialImport, PrepareCredentialRefresh, PrepareCredentialRotation,
-    PreparedAuthorizationCommit, PreparedCredentialImport, PreparedCredentialRotation,
-    ProviderExport, ProviderExportCredentialInput, ProviderModels, ProviderQuota,
-    ProviderQuotaRequest,
+    AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
+    PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
+    PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
+    PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput, ProviderModels,
+    ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+    ProviderResetCreditResult, ProviderResetCredits, explicit_plan_type,
+};
+use crate::model::{
+    provider_credentials::{ProviderDocument, ProviderQuotaWindow},
+    quota_forecast_sampling::QuotaForecastObservation,
 };
 
 /// Provider 管理失败的稳定分类。
@@ -27,27 +33,75 @@ pub enum ProviderAdminErrorKind {
     Unsupported,
     NotFound,
     Conflict,
+    /// Provider 已发起不可逆操作，但无法确认最终执行结果。
+    Ambiguous,
     Unavailable,
+    CredentialRefreshRequired,
+    BadGateway,
     Internal,
 }
 
-/// 不泄漏 OAuth material 与 Provider 响应体的管理错误。
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+/// 不携带 OAuth 请求材料的管理错误。
+///
+/// `message` 是 Provider 局部诊断，可能包含原始上游正文；通用管理用例不得自动把它作为公开文案。
+/// 只有明确拥有原始诊断合同的调用方才能读取，`Debug` 始终只记录是否存在。
+/// `public_message` 则是明确标记为可公开的静态提示，不允许携带动态上游材料。
+#[derive(Clone, PartialEq, Eq, thiserror::Error)]
 #[error("provider admin operation failed: {kind:?}")]
 pub struct ProviderAdminError {
     kind: ProviderAdminErrorKind,
+    message: Option<String>,
+    public_message: Option<&'static str>,
+}
+
+impl std::fmt::Debug for ProviderAdminError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("ProviderAdminError")
+            .field("kind", &self.kind)
+            .field("message", &self.message.as_ref().map(|_| "<redacted>"))
+            .field("public_message", &self.public_message)
+            .finish()
+    }
 }
 
 impl ProviderAdminError {
     #[must_use]
     pub const fn new(kind: ProviderAdminErrorKind) -> Self {
-        Self { kind }
+        Self {
+            kind,
+            message: None,
+            public_message: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_message(mut self, message: impl Into<String>) -> Self {
+        self.message = Some(message.into());
+        self
+    }
+
+    /// Provider 明确允许公开的静态提示；不得承载上游响应或凭据材料。
+    #[must_use]
+    pub const fn with_public_message(mut self, message: &'static str) -> Self {
+        self.public_message = Some(message);
+        self
+    }
+
+    #[must_use]
+    pub const fn public_message(&self) -> Option<&'static str> {
+        self.public_message
     }
 
     #[must_use]
     pub const fn kind(&self) -> ProviderAdminErrorKind {
         self.kind
     }
+
+    #[must_use]
+    pub fn message(&self) -> Option<&str> {
+        self.message.as_deref()
+    }
 }
 
 /// 一个具体 Provider 对管理控制面提供的解析、验证、上游交互与运行时资源回收能力。
@@ -58,6 +112,11 @@ impl ProviderAdminError {
 pub trait ProviderAdmin: Send + Sync {
     fn provider_kind(&self) -> &ProviderKind;
 
+    /// 将原始套餐值投影为展示名称；默认保留未知 Provider 的原始名称。
+    fn plan_type_display(&self, plan_type: &str) -> String {
+        plan_type.to_owned()
+    }
+
     /// 账号已经由控制面提交为不可调度状态，释放 Provider 持有的账号级运行时资源。
     ///
     /// 无账号级运行时资源的 Provider 不需要执行额外操作。该通知发生在 Store 事务
@@ -116,6 +175,47 @@ pub trait ProviderAdmin: Send + Sync {
         request: ProviderQuotaRequest,
     ) -> Result<ProviderQuota, ProviderAdminError>;
 
+    /// 历史观测的协议字段仅由具体 Provider 解释；不支持时保留累计估算。
+    fn quota_forecast_observation(
+        &self,
+        _document: &ProviderDocument,
+        _window: &ProviderQuotaWindow,
+    ) -> Option<QuotaForecastObservation> {
+        None
+    }
+
+    /// 查询 Provider 官方个人资料统计；不支持该能力的 Provider 使用默认拒绝。
+    async fn profile_statistics(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 打开 Provider 官方头像字节流；不支持该能力的 Provider 使用默认拒绝。
+    async fn profile_avatar(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 查询 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn reset_credits(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderResetCredits, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
+    /// 消费 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    async fn consume_reset_credit(
+        &self,
+        _command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
     async fn models(
         &self,
         account_id: &ProviderAccountId,
@@ -165,6 +265,37 @@ impl ProviderAdminRegistry {
             .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
     }
 
+    /// 账号目录与关联列表共用套餐补全和展示规则，已知账号套餐优先于额度快照。
+    pub(crate) fn resolve_account_plan(
+        &self,
+        provider_kind: &str,
+        plan_type: &mut Option<String>,
+        quota: Option<&ProviderQuota>,
+    ) -> Option<String> {
+        if let Some(quota) = quota {
+            quota.fill_missing_plan_type(plan_type);
+        }
+        self.plan_type_display(provider_kind, plan_type.as_deref())
+    }
+
+    /// 账号页和 Dashboard 共用的大驼峰套餐展示名称，不修改原始套餐值。
+    pub(crate) fn plan_type_display(
+        &self,
+        provider_kind: &str,
+        plan_type: Option<&str>,
+    ) -> Option<String> {
+        let plan_type = explicit_plan_type(plan_type)?.trim();
+        let provider = ProviderKind::new(provider_kind.to_owned())
+            .ok()
+            .and_then(|kind| self.providers.get(&kind));
+        let display = provider.map_or_else(
+            || plan_type.to_owned(),
+            |provider| provider.plan_type_display(plan_type),
+        );
+        // 所有 Provider 及未知套餐统一排版，保留 Plus 后缀的含义。
+        Some(display.replace('+', " Plus ").to_upper_camel_case())
+    }
+
     /// 返回所有已注册 Provider 的 Dashboard 上游身份画像。
     pub fn dashboard_wire_profiles(&self) -> Vec<DashboardWireProfile> {
         self.providers

backend/crates/gateway-admin/src/ports/proxy.rs

@@ -0,0 +1,66 @@
+use async_trait::async_trait;
+use gateway_core::account::{OutboundProxy, ProviderAccountId};
+
+use super::store::AdminStoreResult;
+use crate::model::{
+    MutationContext, Revision,
+    proxies::{
+        ImportProxyBinding, NewProxy, ProxyAccountListQuery, ProxyAccountPage, ProxyListQuery,
+        ProxyMutation, ProxyPage, ProxyRecord, ProxyTestResult, UpdateProxy,
+    },
+};
+
+#[async_trait]
+pub trait ProxyStore: Send + Sync {
+    /// 在凭据交换到提交期间保护选定代理的连接配置和测试结果。
+    async fn reserve_import(&self, id: &str) -> AdminStoreResult<ProxyImportReservation>;
+    async fn list(&self, query: ProxyListQuery) -> AdminStoreResult<ProxyPage>;
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> AdminStoreResult<ProxyAccountPage>;
+    async fn get(&self, id: &str) -> AdminStoreResult<ProxyRecord>;
+    /// 仅在账号仍绑定指定代理时解除关联，并清除账号保存的连接地址。
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &ProviderAccountId,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn create(
+        &self,
+        command: NewProxy,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation>;
+    async fn update(
+        &self,
+        command: UpdateProxy,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation>;
+    async fn delete(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn record_test(
+        &self,
+        id: &str,
+        revision: Revision,
+        result: ProxyTestResult,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyRecord>;
+}
+
+/// 离开作用域时释放保护，错误返回和请求取消也遵循相同规则。
+pub trait ProxyImportGuard: Send + Sync {}
+
+pub struct ProxyImportReservation {
+    pub binding: ImportProxyBinding,
+    pub guard: Box<dyn ProxyImportGuard>,
+}
+
+#[async_trait]
+pub trait ProxyProbe: Send + Sync {
+    async fn test(&self, proxy: &OutboundProxy) -> ProxyTestResult;
+}

backend/crates/gateway-admin/src/ports/store.rs

@@ -6,18 +6,19 @@ use std::sync::Arc;
 
 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
+use futures::stream::BoxStream;
 
 use super::backup::BackupStorePorts;
 use crate::model::{
     MutationContext, Revision,
     account_groups::{
-        AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, DeleteAccountGroup,
-        NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+        AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+        DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
     },
     accounts::{
-        AccountListQuery, AccountPage, AccountPageItem, AccountUpdateResult, AccountUsage,
-        AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
-        BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
+        AccountListQuery, AccountPage, AccountPageItem, AccountRuntimeSnapshot,
+        AccountUpdateResult, AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult,
+        AccountsUpdateResult, BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
     },
     auth::{AdminAuditEvent, AdminSession},
     client_keys::{
@@ -31,9 +32,9 @@ use crate::model::{
     },
     provider_credentials::{
         AuthorizationCommit, CredentialDetails, CredentialImportCommit, CredentialImportResult,
-        CredentialListQuery, CredentialMutationResult, CredentialPage, CredentialRotationCommit,
-        ProviderExportCredentialInput,
+        CredentialMutationResult, CredentialRotationCommit, ProviderExportCredentialInput,
     },
+    quota_forecast_sampling::QuotaForecastHistory,
     settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
 };
 
@@ -43,6 +44,7 @@ pub enum AdminStoreErrorKind {
     Invalid,
     NotFound,
     StaleRevision,
+    DuplicateName,
     Conflict,
     Unavailable,
 }
@@ -86,9 +88,17 @@ pub type AdminStoreResult<T> = Result<T, AdminStoreError>;
 /// 账号目录与公共账号写操作。
 #[async_trait]
 pub trait AccountStore: Send + Sync {
-    async fn list_accounts(&self, query: AccountListQuery) -> AdminStoreResult<AccountPage>;
+    async fn list_accounts(
+        &self,
+        query: AccountListQuery,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage>;
 
-    async fn load_account(&self, account_id: &str) -> AdminStoreResult<Option<AccountPageItem>>;
+    async fn load_account(
+        &self,
+        account_id: &str,
+        runtime: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<Option<AccountPageItem>>;
 
     async fn load_account_usage(
         &self,
@@ -101,22 +111,22 @@ pub trait AccountStore: Send + Sync {
         windows: &[AccountUsageWindowQuery],
     ) -> AdminStoreResult<Vec<AccountUsageWindowResult>>;
 
-    async fn list_credentials(
+    /// 从同一数据库语句取得截止快照的累计用量和有界历史观测。
+    async fn load_quota_forecast_history(
         &self,
-        provider_kind: &gateway_core::routing::ProviderKind,
-        query: CredentialListQuery,
-    ) -> AdminStoreResult<CredentialPage>;
+        window: &AccountUsageWindowQuery,
+    ) -> AdminStoreResult<QuotaForecastHistory>;
 
     async fn credential_details(
         &self,
         provider_kind: &gateway_core::routing::ProviderKind,
-        account_id: &gateway_core::engine::credential::ProviderAccountId,
+        account_id: &gateway_core::account::ProviderAccountId,
     ) -> AdminStoreResult<Option<CredentialDetails>>;
 
     async fn load_credentials_for_export(
         &self,
         provider_kind: &gateway_core::routing::ProviderKind,
-        account_ids: &[gateway_core::engine::credential::ProviderAccountId],
+        account_ids: &[gateway_core::account::ProviderAccountId],
     ) -> AdminStoreResult<Vec<ProviderExportCredentialInput>>;
 
     async fn commit_credential_import(
@@ -151,7 +161,7 @@ pub trait AccountStore: Send + Sync {
 
     async fn recover_account(
         &self,
-        account_id: &gateway_core::engine::credential::ProviderAccountId,
+        account_id: &gateway_core::account::ProviderAccountId,
         context: &MutationContext,
     ) -> AdminStoreResult<AccountUpdateResult>;
 
@@ -169,11 +179,22 @@ pub trait AccountStore: Send + Sync {
 
     async fn record_credential_export(
         &self,
-        account_ids: &[gateway_core::engine::credential::ProviderAccountId],
+        account_ids: &[gateway_core::account::ProviderAccountId],
         context: &MutationContext,
     ) -> AdminStoreResult<()>;
 }
 
+/// 可丢失账号运行态的管理读端口；跨存储编排由 Admin application service 拥有。
+#[async_trait]
+pub trait AccountRuntimeStore: Send + Sync {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot>;
+
+    async fn account_runtime(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<AccountRuntimeSnapshot>;
+}
+
 /// 管理员密码、会话和安全审计。
 #[async_trait]
 pub trait AuthStore: Send + Sync {
@@ -240,6 +261,11 @@ pub trait AccountGroupStore: Send + Sync {
         query: AccountGroupListQuery,
     ) -> AdminStoreResult<AccountGroupPage>;
 
+    async fn load_account_group_members(
+        &self,
+        group_ids: &[gateway_core::routing::AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>>;
+
     async fn create_account_group(
         &self,
         command: NewAccountGroup,
@@ -265,6 +291,10 @@ pub trait AccountGroupStore: Send + Sync {
     ) -> AdminStoreResult<AccountGroupMutation>;
 }
 
+/// 逐条读取的已计算费用事实；消费结束或丢弃时释放查询资源。
+pub type UsageCalculatedBillingStream<'a> =
+    BoxStream<'a, AdminStoreResult<UsageCalculatedBillingFact>>;
+
 /// 用量、趋势、诊断与运维错误的只读能力。
 #[async_trait]
 pub trait ObservabilityStore: Send + Sync {
@@ -294,12 +324,13 @@ pub trait ObservabilityStore: Send + Sync {
         filter: UsageFilter,
     ) -> AdminStoreResult<Vec<RequestMetricPoint>>;
 
-    /// 返回可由 Provider 重新校验的已计算费用事实，用于恢复标准费用趋势。
-    async fn usage_calculated_billing_facts(
+    /// 流式返回可由 Provider 重新校验的已计算费用事实，不保证顺序。
+    /// 查询及解码错误由流返回；调用方应逐条聚合，避免收集整个区间。
+    fn usage_calculated_billing_facts(
         &self,
         range: TimeRange,
         filter: UsageFilter,
-    ) -> AdminStoreResult<Vec<UsageCalculatedBillingFact>>;
+    ) -> UsageCalculatedBillingStream<'_>;
 
     async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage>;
 
@@ -346,13 +377,38 @@ pub trait SettingsStore: Send + Sync {
     ) -> AdminStoreResult<AdminApiKeyMutation>;
 }
 
+/// 账号目录、运行态与分组所需的 Store 能力集合。
+#[derive(Clone)]
+pub struct AdminAccountStorePorts {
+    accounts: Arc<dyn AccountStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
+    groups: Arc<dyn AccountGroupStore>,
+    proxies: Arc<dyn super::proxy::ProxyStore>,
+}
+
+impl AdminAccountStorePorts {
+    #[must_use]
+    pub fn new(
+        accounts: Arc<dyn AccountStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
+        groups: Arc<dyn AccountGroupStore>,
+        proxies: Arc<dyn super::proxy::ProxyStore>,
+    ) -> Self {
+        Self {
+            accounts,
+            runtime,
+            groups,
+            proxies,
+        }
+    }
+}
+
 /// 管理用例所需能力的封闭集合。
 ///
 /// 字段保持私有，每个 getter 只交出一种明确能力。该类型不提供通用拆包入口。
 #[derive(Clone)]
 pub struct AdminStorePorts {
-    accounts: Arc<dyn AccountStore>,
-    account_groups: Arc<dyn AccountGroupStore>,
+    accounts: AdminAccountStorePorts,
     auth: Arc<dyn AuthStore>,
     client_keys: Arc<dyn ClientKeyStore>,
     observability: Arc<dyn ObservabilityStore>,
@@ -363,8 +419,7 @@ pub struct AdminStorePorts {
 impl AdminStorePorts {
     #[must_use]
     pub fn new(
-        accounts: Arc<dyn AccountStore>,
-        account_groups: Arc<dyn AccountGroupStore>,
+        accounts: AdminAccountStorePorts,
         auth: Arc<dyn AuthStore>,
         client_keys: Arc<dyn ClientKeyStore>,
         observability: Arc<dyn ObservabilityStore>,
@@ -373,7 +428,6 @@ impl AdminStorePorts {
     ) -> Self {
         Self {
             accounts,
-            account_groups,
             auth,
             client_keys,
             observability,
@@ -384,12 +438,22 @@ impl AdminStorePorts {
 
     #[must_use]
     pub fn accounts(&self) -> Arc<dyn AccountStore> {
-        self.accounts.clone()
+        self.accounts.accounts.clone()
+    }
+
+    #[must_use]
+    pub fn account_runtime(&self) -> Arc<dyn AccountRuntimeStore> {
+        self.accounts.runtime.clone()
     }
 
     #[must_use]
     pub fn account_groups(&self) -> Arc<dyn AccountGroupStore> {
-        self.account_groups.clone()
+        self.accounts.groups.clone()
+    }
+
+    #[must_use]
+    pub fn proxies(&self) -> Arc<dyn super::proxy::ProxyStore> {
+        self.accounts.proxies.clone()
     }
 
     #[must_use]

backend/crates/gateway-admin/src/use_case/account_groups.rs

@@ -1,20 +1,30 @@
 //! Account group management use cases.
 
-use std::sync::Arc;
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+    time::SystemTime,
+};
 
 use async_trait::async_trait;
-use gateway_core::routing::{AccountGroupId, snapshot::SnapshotControl};
+use gateway_core::{
+    account::{AccountStatus, resolve_account_status},
+    routing::AccountGroupId,
+    runtime::SnapshotControl,
+};
 use uuid::Uuid;
 
 use crate::{
     model::{
         AdminError, MutationContext,
         account_groups::{
-            AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, CreateAccountGroup,
-            DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupListQuery,
+            AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage, AccountGroupRecord,
+            CreateAccountGroup, DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled,
+            UpdateAccountGroup,
         },
     },
-    ports::store::AccountGroupStore,
+    ports::store::{AccountGroupStore, AccountRuntimeStore},
 };
 
 use super::{map_store_error, publish_committed};
@@ -47,6 +57,7 @@ pub trait AccountGroupService: Send + Sync {
 
 pub(crate) struct DefaultAccountGroupService {
     store: Arc<dyn AccountGroupStore>,
+    runtime: Arc<dyn AccountRuntimeStore>,
     snapshot: Arc<dyn SnapshotControl>,
 }
 
@@ -54,16 +65,54 @@ impl DefaultAccountGroupService {
     #[must_use]
     pub(crate) fn new(
         store: Arc<dyn AccountGroupStore>,
+        runtime: Arc<dyn AccountRuntimeStore>,
         snapshot: Arc<dyn SnapshotControl>,
     ) -> Self {
-        Self { store, snapshot }
+        Self {
+            store,
+            runtime,
+            snapshot,
+        }
+    }
+
+    async fn enrich_records(&self, records: &mut [AccountGroupRecord]) -> Result<(), AdminError> {
+        if records.is_empty() {
+            return Ok(());
+        }
+        let group_ids = records
+            .iter()
+            .map(|record| record.id.clone())
+            .collect::<Vec<_>>();
+        let members = self
+            .store
+            .load_account_group_members(&group_ids)
+            .await
+            .map_err(|error| map_store_error(error, "account group members"))?;
+        let account_ids = members
+            .iter()
+            .map(|member| member.account_id.clone())
+            .collect::<BTreeSet<_>>()
+            .into_iter()
+            .collect::<Vec<_>>();
+        let runtime = match self.runtime.account_runtime(&account_ids).await {
+            Ok(runtime) => runtime,
+            Err(error) => {
+                tracing::warn!(error = %error, "account group runtime projection is unavailable");
+                Default::default()
+            }
+        };
+        project_group_runtime(records, &members, &runtime);
+        Ok(())
     }
 
     async fn publish(
         &self,
         result: Result<AccountGroupMutation, crate::ports::store::AdminStoreError>,
     ) -> Result<AccountGroupMutation, AdminError> {
-        let result = result.map_err(|error| map_store_error(error, "account group"))?;
+        let mut result = result.map_err(|error| map_store_error(error, "account group"))?;
+        if let Some(record) = result.record.as_mut() {
+            self.enrich_records(std::slice::from_mut(record)).await?;
+        }
         publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
         Ok(result)
     }
@@ -72,10 +121,13 @@ impl DefaultAccountGroupService {
 #[async_trait]
 impl AccountGroupService for DefaultAccountGroupService {
     async fn list(&self, query: AccountGroupListQuery) -> Result<AccountGroupPage, AdminError> {
-        self.store
+        let mut page = self
+            .store
             .list_account_groups(query)
             .await
-            .map_err(|error| map_store_error(error, "account group"))
+            .map_err(|error| map_store_error(error, "account group"))?;
+        self.enrich_records(&mut page.items).await?;
+        Ok(page)
     }
 
     async fn create(
@@ -84,7 +136,7 @@ impl AccountGroupService for DefaultAccountGroupService {
         command: CreateAccountGroup,
     ) -> Result<AccountGroupMutation, AdminError> {
         let id = AccountGroupId::new(format!("grp_{}", Uuid::now_v7().simple()))
-            .map_err(|_| AdminError::internal("Failed to create account group ID"))?;
+            .map_err(|_| AdminError::internal("创建账号组 ID 失败"))?;
         self.publish(
             self.store
                 .create_account_group(
@@ -128,3 +180,63 @@ impl AccountGroupService for DefaultAccountGroupService {
             .await
     }
 }
+
+fn project_group_runtime(
+    records: &mut [AccountGroupRecord],
+    members: &[AccountGroupMemberFact],
+    runtime: &crate::model::accounts::AccountRuntimeSnapshot,
+) {
+    let now = SystemTime::now();
+    let mut status_by_account = BTreeMap::new();
+    let mut slots_by_account = BTreeMap::new();
+    let mut accounts_by_group = BTreeMap::<&str, Vec<&str>>::new();
+    for member in members {
+        let mut status = member.status.clone();
+        status.rate_limited_until = runtime
+            .rate_limited_until
+            .get(&member.account_id)
+            .copied()
+            .map(Into::into);
+        status_by_account
+            .entry(member.account_id.as_str())
+            .or_insert_with(|| resolve_account_status(&status, now).status);
+        slots_by_account
+            .entry(member.account_id.as_str())
+            .or_insert(member.total_slots);
+        accounts_by_group
+            .entry(member.group_id.as_str())
+            .or_default()
+            .push(member.account_id.as_str());
+    }
+    for record in records {
+        let account_ids = accounts_by_group
+            .get(record.id.as_str())
+            .map_or(&[][..], Vec::as_slice);
+        let available_ids = account_ids
+            .iter()
+            .copied()
+            .filter(|account_id| status_by_account.get(account_id) == Some(&AccountStatus::Normal))
+            .collect::<Vec<_>>();
+        let total = u64::try_from(account_ids.len()).unwrap_or(u64::MAX);
+        let available = u64::try_from(available_ids.len()).unwrap_or(u64::MAX);
+        record.account_summary = AccountGroupAccountSummary {
+            available,
+            limited: total.saturating_sub(available),
+            total,
+        };
+        record.capacity = AccountGroupCapacity {
+            used_slots: if available_ids.is_empty() {
+                Some(0)
+            } else {
+                runtime.in_flight.as_ref().map(|in_flight| {
+                    available_ids.iter().fold(0_u64, |sum, account_id| {
+                        sum.saturating_add(in_flight.get(*account_id).copied().unwrap_or(0))
+                    })
+                })
+            },
+            total_slots: available_ids.iter().fold(0_u64, |sum, account_id| {
+                sum.saturating_add(slots_by_account.get(*account_id).copied().unwrap_or(0))
+            }),
+        };
+    }
+}

backend/crates/gateway-admin/src/use_case/accounts.rs

@@ -6,11 +6,10 @@ use async_trait::async_trait;
 use chrono::{Duration, Utc};
 use futures::StreamExt as _;
 use gateway_core::{
-    engine::{
-        credential::ProviderAccountId,
-        probe::{AccountProbe, AccountProbeRequest},
-    },
-    routing::{ProviderKind, UpstreamModelId, snapshot::SnapshotControl},
+    account::ProviderAccountId,
+    engine::probe::{AccountProbe, AccountProbeRequest},
+    routing::{ProviderKind, UpstreamModelId},
+    runtime::SnapshotControl,
 };
 
 use crate::{
@@ -24,11 +23,18 @@ use crate::{
         observability::TimeRange,
         provider_credentials::{
             AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
-            PrepareCredentialRefresh, ProviderModels, ProviderQuota, ProviderQuotaRequest,
-            ProviderQuotaWindow, QuotaLocalUsageAttribution,
+            ConsumeProviderResetCredit, PrepareCredentialRefresh, ProviderModels,
+            ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+            ProviderQuotaWindow, ProviderResetCreditResult, ProviderResetCredits,
+            QuotaLocalUsageAttribution,
         },
+        quota_forecast::{AccountQuotaForecastReport, account_quota_forecasts},
+        quota_forecast_sampling::{QuotaForecastPoint, select_forecast_sample},
+    },
+    ports::{
+        provider::ProviderAdminRegistry,
+        store::{AccountRuntimeStore, AccountStore},
     },
-    ports::{provider::ProviderAdminRegistry, store::AccountStore},
 };
 
 use super::{
@@ -79,6 +85,41 @@ pub trait AccountsService: Send + Sync {
         refresh: bool,
     ) -> Result<AccountDirectoryItem, AdminError>;
 
+    async fn quota_forecast(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<AccountQuotaForecastReport, AdminError>;
+
+    async fn profile_statistics(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持账号统计"))
+    }
+
+    async fn profile_avatar(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持账号头像"))
+    }
+
+    async fn reset_credits(
+        &self,
+        _context: &MutationContext,
+        _account_id: ProviderAccountId,
+    ) -> Result<ProviderResetCredits, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持重置额度"))
+    }
+
+    async fn consume_reset_credit(
+        &self,
+        _context: &MutationContext,
+        _command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持重置额度"))
+    }
+
     async fn models(
         &self,
         account_id: &ProviderAccountId,
@@ -94,36 +135,59 @@ pub trait AccountsService: Send + Sync {
 
 pub(crate) struct DefaultAccountsService {
     accounts: Arc<dyn AccountStore>,
+    account_runtime: Arc<dyn AccountRuntimeStore>,
     providers: ProviderAdminRegistry,
     snapshot: Arc<dyn SnapshotControl>,
     probe: Arc<dyn AccountProbe>,
+    reset_credit_locks:
+        Arc<futures::lock::Mutex<BTreeMap<ProviderAccountId, Arc<futures::lock::Mutex<()>>>>>,
 }
 
 impl DefaultAccountsService {
     #[must_use]
-    pub(crate) const fn new(
+    pub(crate) fn new(
         accounts: Arc<dyn AccountStore>,
+        account_runtime: Arc<dyn AccountRuntimeStore>,
         providers: ProviderAdminRegistry,
         snapshot: Arc<dyn SnapshotControl>,
         probe: Arc<dyn AccountProbe>,
     ) -> Self {
         Self {
             accounts,
+            account_runtime,
             providers,
             snapshot,
             probe,
+            reset_credit_locks: Arc::new(futures::lock::Mutex::new(BTreeMap::new())),
         }
     }
 
+    async fn reset_credit_lock(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Arc<futures::lock::Mutex<()>> {
+        let mut locks = self.reset_credit_locks.lock().await;
+        Arc::clone(
+            locks
+                .entry(account_id.clone())
+                .or_insert_with(|| Arc::new(futures::lock::Mutex::new(()))),
+        )
+    }
+
     async fn load_account(
         &self,
         account_id: &ProviderAccountId,
     ) -> Result<AccountPageItem, AdminError> {
+        let runtime = self
+            .account_runtime
+            .account_runtime(&[account_id.as_str().to_owned()])
+            .await
+            .map_err(|error| map_store_error(error, "account runtime"))?;
         self.accounts
-            .load_account(account_id.as_str())
+            .load_account(account_id.as_str(), runtime)
             .await
             .map_err(|error| map_store_error(error, "provider account"))?
-            .ok_or_else(|| AdminError::not_found("Provider account was not found"))
+            .ok_or_else(|| AdminError::not_found("Provider 账号不存在"))
     }
 
     async fn provider_for_account(
@@ -156,6 +220,7 @@ impl DefaultAccountsService {
                 quota
                     .windows
                     .iter()
+                    .filter(|window| window.local_usage.is_none())
                     .filter_map(|window| quota_usage_window(&item.account.id, window))
             })
             .collect::<Vec<_>>();
@@ -212,13 +277,25 @@ impl DefaultAccountsService {
             })
             .await
             .map_err(|error| map_provider_error(error, "provider quota"))?;
+        let mut stored = if refresh_quota {
+            self.load_account(account_id).await?
+        } else {
+            stored
+        };
         self.attach_quota_local_usage(
             std::slice::from_ref(&stored),
             std::slice::from_mut(&mut quota),
         )
         .await?;
-        let usage = quota.representative_window_usage().cloned();
+        let usage = quota
+            .usage_window()
+            .and_then(|(window, _)| window.local_usage.clone());
         Ok(AccountDirectoryItem {
+            plan_type_display: self.providers.resolve_account_plan(
+                stored.account.provider_kind.as_str(),
+                &mut stored.account.plan_type,
+                Some(&quota),
+            ),
             projection: stored.projection,
             usage,
             account: stored.account,
@@ -230,9 +307,14 @@ impl DefaultAccountsService {
 #[async_trait]
 impl AccountsService for DefaultAccountsService {
     async fn list(&self, query: AccountListQuery) -> Result<AccountDirectoryPage, AdminError> {
+        let runtime = self
+            .account_runtime
+            .active_rate_limits()
+            .await
+            .map_err(|error| map_store_error(error, "account runtime"))?;
         let page = self
             .accounts
-            .list_accounts(query)
+            .list_accounts(query, runtime)
             .await
             .map_err(|error| map_store_error(error, "account directory"))?;
         let now = Utc::now();
@@ -257,7 +339,7 @@ impl AccountsService for DefaultAccountsService {
         let mut quotas = futures::future::join_all(page.items.iter().map(|item| async {
             let account = &item.account;
             let account_id = ProviderAccountId::new(account.id.clone())
-                .map_err(|_| AdminError::invalid("Invalid provider account ID"))?;
+                .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
             // 单个账号的 quota 投影失败（Provider 未注册或 quota 读取失败）不拖垮整页：
             // 该账号降级为空额度投影，其余账号与页面状态照常返回。
             let provider = match self.providers.require(&account.provider_kind) {
@@ -299,9 +381,16 @@ impl AccountsService for DefaultAccountsService {
             .items
             .into_iter()
             .zip(quotas)
-            .map(|(item, quota)| {
-                let usage = quota.representative_window_usage().cloned();
+            .map(|(mut item, quota)| {
+                let usage = quota
+                    .usage_window()
+                    .and_then(|(window, _)| window.local_usage.clone());
                 AccountDirectoryItem {
+                    plan_type_display: self.providers.resolve_account_plan(
+                        item.account.provider_kind.as_str(),
+                        &mut item.account.plan_type,
+                        Some(&quota),
+                    ),
                     usage,
                     account: item.account,
                     projection: item.projection,
@@ -323,9 +412,7 @@ impl AccountsService for DefaultAccountsService {
         account_ids: Vec<ProviderAccountId>,
     ) -> Result<AccountExportBundle, AdminError> {
         if account_ids.is_empty() || account_ids.len() > 200 {
-            return Err(AdminError::invalid(
-                "Account export requires between 1 and 200 accounts",
-            ));
+            return Err(AdminError::invalid("账号导出数量必须在 1 到 200 之间"));
         }
         let exported_ids = account_ids.clone();
         let mut grouped = BTreeMap::<ProviderKind, Vec<ProviderAccountId>>::new();
@@ -340,7 +427,7 @@ impl AccountsService for DefaultAccountsService {
             let unique = ids.iter().collect::<std::collections::BTreeSet<_>>();
             unique.len() != ids.len()
         }) {
-            return Err(AdminError::invalid("Account export contains duplicate IDs"));
+            return Err(AdminError::invalid("账号导出列表包含重复 ID"));
         }
         let mut documents = Vec::with_capacity(grouped.len());
         for (provider_kind, ids) in grouped {
@@ -430,7 +517,7 @@ impl AccountsService for DefaultAccountsService {
         command: UpdateAccount,
     ) -> Result<AccountUpdateResult, AdminError> {
         let account_id = ProviderAccountId::new(command.account_id.clone())
-            .map_err(|_| AdminError::invalid("Invalid provider account ID"))?;
+            .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))?;
         let (_, provider) = self.provider_for_account(&account_id).await?;
         let enabled = command.enabled;
         let result = self
@@ -458,7 +545,7 @@ impl AccountsService for DefaultAccountsService {
             .iter()
             .map(|id| {
                 ProviderAccountId::new(id.clone())
-                    .map_err(|_| AdminError::invalid("Invalid provider account ID"))
+                    .map_err(|_| AdminError::invalid("Provider 账号 ID 不合法"))
             })
             .collect::<Result<Vec<_>, _>>()?;
         let mut providers = BTreeMap::<
@@ -502,6 +589,170 @@ impl AccountsService for DefaultAccountsService {
         self.load_directory_item(account_id, refresh).await
     }
 
+    async fn quota_forecast(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<AccountQuotaForecastReport, AdminError> {
+        let (stored, provider) = self.provider_for_account(account_id).await?;
+        let quota = provider
+            .quota(ProviderQuotaRequest {
+                account_id: account_id.clone(),
+                refresh: false,
+                rolling_usage: None,
+            })
+            .await
+            .map_err(|error| map_provider_error(error, "forecast quota snapshot"))?;
+        let now = Utc::now();
+        let mut samples = Vec::new();
+        for (window, _) in quota.usage_windows() {
+            let (Some(mut query), Some(observed), Some(percent)) = (
+                quota_usage_window(account_id.as_str(), window),
+                quota.observed_at,
+                window.used_percent,
+            ) else {
+                continue;
+            };
+            query.range.start = query.range.start.max(stored.account.created_at);
+            if query.range.start >= observed
+                || observed > now
+                || now >= query.range.end
+                || !percent.is_finite()
+                || !(0.0..=100.0).contains(&percent)
+            {
+                continue;
+            }
+            let reset_at = query.range.end;
+            query.range.end = observed;
+            let history = self
+                .accounts
+                .load_quota_forecast_history(&query)
+                .await
+                .map_err(|error| map_store_error(error, "forecast paired usage"))?;
+            let mut points = Vec::new();
+            let mut interrupted = false;
+            for point in history.points {
+                let Some(fact) =
+                    provider.quota_forecast_observation(&point.provider_observation, window)
+                else {
+                    continue;
+                };
+                let same_plan = quota
+                    .plan_type
+                    .as_deref()
+                    .zip(fact.plan_type.as_deref())
+                    .is_some_and(|(current, previous)| current.eq_ignore_ascii_case(previous));
+                // 仅容纳已观测到的秒级量化抖动，不用宽时间容差合并实际重置。
+                // 不匹配的段截断基线；之后的有效观测可以重新积累。
+                if !same_plan || (fact.reset_at - reset_at).abs() > Duration::seconds(2) {
+                    points.clear();
+                    interrupted = true;
+                    continue;
+                }
+                points.push(QuotaForecastPoint {
+                    observed_at: point.completed_at,
+                    used_percent: fact.used_percent,
+                    usage: point.usage,
+                });
+            }
+            let mut sample = select_forecast_sample(
+                window.key.clone(),
+                query.range.start,
+                QuotaForecastPoint {
+                    observed_at: observed,
+                    used_percent: percent,
+                    usage: history.usage,
+                },
+                points,
+                history.pending_request_count,
+            );
+            if interrupted
+                && sample.method
+                    == crate::model::quota_forecast_sampling::QuotaForecastMethod::Cumulative
+            {
+                sample.discontinuous = true;
+            }
+            samples.push(sample);
+        }
+        Ok(AccountQuotaForecastReport {
+            account_id: account_id.to_string(),
+            generated_at: now,
+            forecasts: account_quota_forecasts(&quota, stored.account.created_at, now, &samples),
+        })
+    }
+
+    async fn profile_statistics(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, AdminError> {
+        let (_, provider) = self.provider_for_account(account_id).await?;
+        provider
+            .profile_statistics(account_id)
+            .await
+            .map_err(|error| map_provider_error(error, "provider profile statistics"))
+    }
+
+    async fn profile_avatar(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<ProviderProfileAvatar, AdminError> {
+        let (_, provider) = self.provider_for_account(account_id).await?;
+        provider
+            .profile_avatar(account_id)
+            .await
+            .map_err(|error| map_provider_error(error, "provider profile avatar"))
+    }
+
+    async fn reset_credits(
+        &self,
+        context: &MutationContext,
+        account_id: ProviderAccountId,
+    ) -> Result<ProviderResetCredits, AdminError> {
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        match provider.reset_credits(&account_id).await {
+            Ok(credits) => Ok(credits),
+            Err(error)
+                if error.kind()
+                    == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired =>
+            {
+                self.refresh(context, account_id.clone()).await?;
+                let (_, provider) = self.provider_for_account(&account_id).await?;
+                provider
+                    .reset_credits(&account_id)
+                    .await
+                    .map_err(map_reset_credits_error_after_refresh)
+            }
+            Err(error) => Err(map_provider_error(error, "provider reset credits")),
+        }
+    }
+
+    async fn consume_reset_credit(
+        &self,
+        context: &MutationContext,
+        command: ConsumeProviderResetCredit,
+    ) -> Result<ProviderResetCreditResult, AdminError> {
+        let account_id = command.account_id.clone();
+        // 覆盖 credential refresh + 同键重试的完整账号级临界区，避免 401 两次调用
+        // 之间插入另一笔不可逆消费。
+        let lock = self.reset_credit_lock(&account_id).await;
+        let _guard = lock.lock().await;
+        let (_, provider) = self.provider_for_account(&account_id).await?;
+        match provider.consume_reset_credit(command.clone()).await {
+            Ok(result) => Ok(result),
+            Err(error)
+                if error.kind()
+                    == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired =>
+            {
+                self.refresh(context, account_id.clone()).await?;
+                let (_, provider) = self.provider_for_account(&account_id).await?;
+                provider
+                    .consume_reset_credit(command)
+                    .await
+                    .map_err(map_reset_credits_error_after_refresh)
+            }
+            Err(error) => Err(map_provider_error(error, "provider reset-credit consume")),
+        }
+    }
+
     async fn models(
         &self,
         account_id: &ProviderAccountId,
@@ -565,12 +816,11 @@ impl AccountsService for DefaultAccountsService {
                     let upstream_body = error
                         .upstream_response()
                         .map(|response| String::from_utf8_lossy(response.body()).into_owned());
-                    let message = upstream_body
-                        .as_deref()
-                        .filter(|body| !body.is_empty())
-                        .unwrap_or_else(|| error.client_message())
-                        .to_owned();
+                    let message = error.client_message().to_owned();
                     vec![AccountConnectionTestEvent::Failed {
+                        source: error.source(),
+                        gateway_error_code: error.kind(),
+                        send_state: error.send_state(),
                         message,
                         provider_error_code: error.client_error_code().map(ToOwned::to_owned),
                         provider_error_type: error.client_error_type().map(ToOwned::to_owned),
@@ -586,9 +836,19 @@ impl AccountsService for DefaultAccountsService {
     }
 }
 
+fn map_reset_credits_error_after_refresh(
+    error: crate::ports::provider::ProviderAdminError,
+) -> AdminError {
+    if error.kind() == crate::ports::provider::ProviderAdminErrorKind::CredentialRefreshRequired {
+        return AdminError::bad_gateway("上游服务拒绝了刷新后的凭据");
+    }
+    map_provider_error(error, "provider reset credits")
+}
+
 /// 账号目录中单个账号 quota 读取失败时使用的空额度投影。
 fn empty_quota() -> ProviderQuota {
     ProviderQuota {
+        plan_type: None,
         observed_at: None,
         refresh_token_expires_at: None,
         windows: Vec::new(),
@@ -601,14 +861,12 @@ fn quota_usage_window(
     account_id: &str,
     window: &ProviderQuotaWindow,
 ) -> Option<AccountUsageWindowQuery> {
-    if window.local_usage.is_some()
-        || window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide
-    {
+    if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide {
         return None;
     }
     let reset_at = window.reset_at?;
     let seconds = i64::try_from(window.window_seconds?).ok()?;
-    let start = reset_at.checked_sub_signed(Duration::seconds(seconds))?;
+    let start = reset_at.checked_sub_signed(Duration::try_seconds(seconds)?)?;
     let range = TimeRange::new(start, reset_at).ok()?;
     // 上游百分比以该 reset 边界定义；以当前时间回推会让本地 Token 属于另一窗口。
     Some(AccountUsageWindowQuery {

backend/crates/gateway-admin/src/use_case/auth.rs

@@ -2,7 +2,7 @@
 
 use std::sync::Arc;
 
-use argon2::{Argon2, PasswordHash, PasswordHasher, PasswordVerifier, password_hash::SaltString};
+use argon2::{Argon2, PasswordHash, PasswordHasher, PasswordVerifier};
 use async_trait::async_trait;
 use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
 use chrono::{Duration, Utc};
@@ -69,7 +69,7 @@ impl DefaultAuthService {
             id: format!("audit_{}", Uuid::now_v7().simple()),
             actor_kind: AuditActorKind::AdminSession,
             actor_admin_user_id: Some(self.default_admin_user_id.clone()),
-            actor_ref: format!("admin:{}", self.default_admin_user_id),
+            actor_ref: crate::model::auth::admin_session_actor_ref(&self.default_admin_user_id),
             request_id: None,
             action: action.to_owned(),
             entity_kind: "admin_session".to_owned(),
@@ -183,7 +183,7 @@ impl AuthService for DefaultAuthService {
         if let Some(session) = session {
             let mut event = self.auth_audit("admin.logout", Utc::now());
             event.actor_admin_user_id = Some(session.admin_user_id.clone());
-            event.actor_ref = format!("admin:{}", session.admin_user_id);
+            event.actor_ref = crate::model::auth::admin_session_actor_ref(&session.admin_user_id);
             event.entity_ref = session.admin_user_id;
             self.store
                 .append_audit_event(event)
@@ -195,16 +195,15 @@ impl AuthService for DefaultAuthService {
 }
 
 fn hash_admin_password(password: &str) -> Result<String, AdminError> {
-    let salt = SaltString::generate(&mut OsRng);
     Argon2::default()
-        .hash_password(password.as_bytes(), &salt)
+        .hash_password(password.as_bytes())
         .map(|hash| hash.to_string())
-        .map_err(|_| AdminError::internal("Failed to hash administrator password"))
+        .map_err(|_| AdminError::internal("管理员密码哈希失败"))
 }
 
 fn verify_admin_password(password: &str, encoded: &str) -> Result<bool, AdminError> {
     let hash = PasswordHash::new(encoded)
-        .map_err(|_| AdminError::internal("Stored administrator password hash is invalid"))?;
+        .map_err(|_| AdminError::internal("已保存的管理员密码哈希不合法"))?;
     Ok(Argon2::default()
         .verify_password(password.as_bytes(), &hash)
         .is_ok())

backend/crates/gateway-admin/src/use_case/backup.rs

@@ -5,7 +5,7 @@ use std::time::Duration;
 
 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::runtime::SnapshotControl;
 use secrecy::ExposeSecret as _;
 use uuid::Uuid;
 
@@ -326,7 +326,9 @@ impl DefaultBackupService {
             crate::model::MutationActor::System => AuditActorKind::System,
         };
         let actor_ref = match &context.actor {
-            crate::model::MutationActor::AdminSession { admin_user_id } => admin_user_id.clone(),
+            crate::model::MutationActor::AdminSession { admin_user_id } => {
+                crate::model::auth::admin_session_actor_ref(admin_user_id)
+            }
             crate::model::MutationActor::AdminApiKey => "admin_api_key".to_owned(),
             crate::model::MutationActor::System => "system".to_owned(),
         };
@@ -429,9 +431,7 @@ fn map_backup_error(error: BackupError) -> AdminError {
         code::ACTIVE_TASK_CONFLICT | code::STATE_CONFLICT | code::STORAGE_IDENTITY_LOCKED => {
             AdminError::conflict(error.message().to_owned())
         }
-        code::STORE_UNAVAILABLE => {
-            AdminError::new(AdminErrorKind::Unavailable, error.message().to_owned())
-        }
-        _ => AdminError::bad_gateway(error.message().to_owned()),
+        code::STORE_UNAVAILABLE => AdminError::new(AdminErrorKind::Unavailable, "备份服务暂不可用"),
+        _ => AdminError::bad_gateway("备份服务请求失败"),
     }
 }

backend/crates/gateway-admin/src/use_case/client_distribution.rs

@@ -0,0 +1,33 @@
+//! Codex 客户端下载信息用例。
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+
+use crate::{
+    model::client_distribution::CodexDesktopWindowsDownloads,
+    ports::client_distribution::ClientDistributionResolver,
+};
+
+#[async_trait]
+pub trait ClientDistributionService: Send + Sync {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads;
+}
+
+pub(crate) struct DefaultClientDistributionService {
+    resolver: Arc<dyn ClientDistributionResolver>,
+}
+
+impl DefaultClientDistributionService {
+    #[must_use]
+    pub(crate) const fn new(resolver: Arc<dyn ClientDistributionResolver>) -> Self {
+        Self { resolver }
+    }
+}
+
+#[async_trait]
+impl ClientDistributionService for DefaultClientDistributionService {
+    async fn codex_desktop_windows(&self, refresh: bool) -> CodexDesktopWindowsDownloads {
+        self.resolver.resolve_codex_desktop_windows(refresh).await
+    }
+}

backend/crates/gateway-admin/src/use_case/client_keys.rs

@@ -5,7 +5,7 @@ use std::sync::Arc;
 use async_trait::async_trait;
 use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
 use gateway_core::policy::ClientApiKeyId;
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::runtime::SnapshotControl;
 use rand_core::{OsRng, RngCore as _};
 use uuid::Uuid;
 
@@ -18,7 +18,7 @@ use crate::{
             DeleteClientKey, NewClientKey, SetClientKeyEnabled, UpdateClientKey,
         },
     },
-    ports::store::ClientKeyStore,
+    ports::store::{AdminStoreError, AdminStoreErrorKind, ClientKeyStore},
 };
 
 use super::{map_store_error, publish_committed};
@@ -77,7 +77,7 @@ impl ClientKeyService for DefaultClientKeyService {
             .reveal_client_key(id)
             .await
             .map_err(|error| map_store_error(error, "client API key"))?
-            .ok_or_else(|| AdminError::not_found("Client API key was not found"))
+            .ok_or_else(|| AdminError::not_found("Client API Key 不存在"))
     }
 
     async fn create(
@@ -86,10 +86,14 @@ impl ClientKeyService for DefaultClientKeyService {
         command: CreateClientKey,
     ) -> Result<CreatedClientKey, AdminError> {
         let id = ClientApiKeyId::new(format!("key_{}", Uuid::now_v7().simple()))
-            .map_err(|_| AdminError::internal("Failed to create Client API key ID"))?;
-        let mut bytes = [0_u8; 32];
-        OsRng.fill_bytes(&mut bytes);
-        let plaintext = format!("sk_{}", URL_SAFE_NO_PAD.encode(bytes));
+            .map_err(|_| AdminError::internal("创建 Client API Key ID 失败"))?;
+        let plaintext = if let Some(key) = command.custom_key {
+            key.expose_for_auth().to_owned()
+        } else {
+            let mut bytes = [0_u8; 32];
+            OsRng.fill_bytes(&mut bytes);
+            format!("sk_{}", URL_SAFE_NO_PAD.encode(bytes))
+        };
         let (config_revision, record) = self
             .store
             .create_client_key(
@@ -99,12 +103,13 @@ impl ClientKeyService for DefaultClientKeyService {
                     label: command.label,
                     group_ids: command.group_ids,
                     limits: command.limits,
+                    budget: command.budget,
                     plaintext: plaintext.clone(),
                 },
                 context,
             )
             .await
-            .map_err(|error| map_store_error(error, "client API key"))?;
+            .map_err(map_client_key_write_error)?;
         publish_committed(self.snapshot.as_ref(), config_revision).await?;
         Ok(CreatedClientKey {
             config_revision,
@@ -122,7 +127,7 @@ impl ClientKeyService for DefaultClientKeyService {
             .store
             .update_client_key(command, context)
             .await
-            .map_err(|error| map_store_error(error, "client API key"))?;
+            .map_err(map_client_key_write_error)?;
         publish_committed(self.snapshot.as_ref(), config_revision).await?;
         Ok(ClientKeyMutation {
             config_revision,
@@ -170,13 +175,21 @@ impl ClientKeyService for DefaultClientKeyService {
     }
 }
 
+fn map_client_key_write_error(error: AdminStoreError) -> AdminError {
+    match error.kind() {
+        AdminStoreErrorKind::DuplicateName => AdminError::conflict("名称已存在"),
+        AdminStoreErrorKind::Conflict => AdminError::conflict("API Key 已存在，请使用其他密钥"),
+        _ => map_store_error(error, "client API key"),
+    }
+}
+
 fn validate_cursor(query: &ClientKeyListQuery) -> Result<(), AdminError> {
     let Some(cursor) = &query.cursor else {
         return Ok(());
     };
     if cursor.sort != query.sort {
         return Err(AdminError::invalid(
-            "Client API key cursor sort does not match the query",
+            "Client API Key 游标排序与查询条件不一致",
         ));
     }
     let matches = matches!(
@@ -198,6 +211,6 @@ fn validate_cursor(query: &ClientKeyListQuery) -> Result<(), AdminError> {
     if matches {
         Ok(())
     } else {
-        Err(AdminError::invalid("Invalid Client API key cursor"))
+        Err(AdminError::invalid("Client API Key 游标不合法"))
     }
 }

backend/crates/gateway-admin/src/use_case/mod.rs

@@ -4,13 +4,17 @@ pub mod account_groups;
 pub mod accounts;
 pub mod auth;
 pub mod backup;
+pub mod client_distribution;
 pub mod client_keys;
 pub mod observability;
 pub mod openai;
+pub mod proxies;
 pub mod settings;
 pub mod system;
 pub mod xai;
 
+use std::sync::Arc;
+
 use crate::{
     model::{
         AdminError, AdminErrorKind, MutationContext,
@@ -20,7 +24,7 @@ use crate::{
             CredentialDetails, CredentialMutationResult, CredentialRotationCommit,
             PendingAuthorizationMutation, PreparedAuthorizationCommit,
             PreparedAuthorizationCredential, PreparedCredentialImport, PreparedCredentialRotation,
-            StartAuthorization,
+            ProviderQuotaRequest, StartAuthorization,
         },
     },
     ports::{
@@ -29,20 +33,29 @@ use crate::{
     },
 };
 use gateway_core::{
-    engine::credential::ProviderAccountId,
-    routing::{ConfigRevision, ProviderKind, snapshot::SnapshotControl},
+    account::ProviderAccountId,
+    routing::{ConfigRevision, ProviderKind},
+    runtime::SnapshotControl,
 };
 
 fn map_store_error(error: AdminStoreError, resource: &'static str) -> AdminError {
     let kind = match error.kind() {
         AdminStoreErrorKind::Invalid => AdminErrorKind::Invalid,
         AdminStoreErrorKind::NotFound => AdminErrorKind::NotFound,
-        AdminStoreErrorKind::StaleRevision | AdminStoreErrorKind::Conflict => {
-            AdminErrorKind::Conflict
-        }
+        AdminStoreErrorKind::StaleRevision
+        | AdminStoreErrorKind::DuplicateName
+        | AdminStoreErrorKind::Conflict => AdminErrorKind::Conflict,
         AdminStoreErrorKind::Unavailable => AdminErrorKind::Unavailable,
     };
-    AdminError::new(kind, format!("{resource} operation failed"))
+    tracing::warn!(resource, error_kind = ?error.kind(), "admin store operation failed");
+    let message = match kind {
+        AdminErrorKind::Invalid => "请求参数不合法",
+        AdminErrorKind::NotFound => "请求的资源不存在",
+        AdminErrorKind::Conflict => "当前资源状态冲突，请刷新后重试",
+        AdminErrorKind::Unavailable => "依赖服务暂不可用",
+        _ => "服务内部错误",
+    };
+    AdminError::new(kind, message)
 }
 
 fn map_provider_error(
@@ -56,10 +69,24 @@ fn map_provider_error(
         ProviderAdminErrorKind::Unsupported => AdminErrorKind::Invalid,
         ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
         ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
+        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
         ProviderAdminErrorKind::Unavailable => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::CredentialRefreshRequired => AdminErrorKind::Unavailable,
+        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
         ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
     };
-    AdminError::new(kind, format!("{resource} operation failed"))
+    tracing::warn!(resource, error_kind = ?error.kind(), "admin provider operation failed");
+    let message = match kind {
+        AdminErrorKind::Invalid => "Provider 请求不合法",
+        AdminErrorKind::NotFound => "Provider 资源不存在",
+        AdminErrorKind::Conflict => "Provider 资源状态冲突，请刷新后重试",
+        AdminErrorKind::BadGateway => "上游服务请求失败",
+        AdminErrorKind::UpstreamResultUnknown => "上游执行结果未知，请刷新状态后再决定是否重试",
+        AdminErrorKind::Unavailable => "Provider 服务暂不可用",
+        AdminErrorKind::Internal => "服务内部错误",
+        _ => "Provider 操作失败",
+    };
+    AdminError::new(kind, error.public_message().unwrap_or(message))
 }
 
 async fn publish_committed(
@@ -67,11 +94,48 @@ async fn publish_committed(
     revision: crate::model::Revision,
 ) -> Result<(), AdminError> {
     let revision = ConfigRevision::new(revision.get())
-        .map_err(|_| AdminError::internal("Committed configuration revision is invalid"))?;
+        .map_err(|_| AdminError::internal("已提交的配置版本不合法"))?;
     snapshot.publish_committed(revision).await;
     Ok(())
 }
 
+async fn publish_credentials_and_observe_quota(
+    provider: &Arc<dyn ProviderAdmin>,
+    snapshot: &dyn SnapshotControl,
+    revision: crate::model::Revision,
+    account_ids: &[ProviderAccountId],
+    request_id: &str,
+) -> Result<(), AdminError> {
+    provider.account_facts_changed(account_ids).await;
+    publish_committed(snapshot, revision).await?;
+
+    // 凭据已经提交；额度只是可重建的观察，不能拖住管理请求或回滚提交结果。
+    let provider = Arc::clone(provider);
+    let account_ids = account_ids.to_vec();
+    let request_id = request_id.to_owned();
+    tokio::spawn(async move {
+        for account_id in account_ids {
+            if let Err(error) = provider
+                .quota(ProviderQuotaRequest {
+                    account_id: account_id.clone(),
+                    refresh: true,
+                    rolling_usage: None,
+                })
+                .await
+            {
+                tracing::warn!(
+                    request_id,
+                    provider = %provider.provider_kind().as_str(),
+                    account_id = %account_id.as_str(),
+                    quota_error = ?error.kind(),
+                    "initial quota observation failed"
+                );
+            }
+        }
+    });
+    Ok(())
+}
+
 async fn required_credential(
     accounts: &dyn AccountStore,
     provider_kind: &ProviderKind,
@@ -82,25 +146,61 @@ async fn required_credential(
         .credential_details(provider_kind, account_id)
         .await
         .map_err(|error| map_store_error(error, resource))?
-        .ok_or_else(|| AdminError::not_found(format!("{resource} was not found")))
+        .ok_or_else(|| AdminError::not_found("Provider 凭据不存在"))
+}
+
+async fn import_proxy_binding(
+    proxies: &dyn crate::ports::proxy::ProxyStore,
+    id: Option<&str>,
+) -> Result<Option<crate::ports::proxy::ProxyImportReservation>, AdminError> {
+    let Some(id) = id else { return Ok(None) };
+    let reservation = proxies
+        .reserve_import(id)
+        .await
+        .map_err(|error| map_store_error(error, "proxy"))?;
+    Ok(Some(reservation))
 }
 
 async fn pending_authorization(
     accounts: &dyn AccountStore,
+    proxies: &dyn crate::ports::proxy::ProxyStore,
     provider_kind: &ProviderKind,
     command: &StartAuthorization,
     resource: &'static str,
 ) -> Result<PendingAuthorizationMutation, AdminError> {
+    let proxy;
+    let mut proxy_id = None;
     let target = match &command.reauthorization {
         Some(account_id) => {
-            required_credential(accounts, provider_kind, account_id, resource).await?;
+            proxy = required_credential(accounts, provider_kind, account_id, resource)
+                .await?
+                .credential
+                .outbound_proxy;
             AuthorizationMutationTarget::Reauthorize {
                 account_id: account_id.clone(),
             }
         }
-        None => AuthorizationMutationTarget::Create {
-            name: command.name.clone(),
-        },
+        None => {
+            use crate::model::proxies::AccountProxySelection;
+            proxy = match &command.outbound_proxy {
+                Some(AccountProxySelection::Url(value)) => Some(value.clone()),
+                Some(AccountProxySelection::Saved(id)) => {
+                    let record = proxies
+                        .get(id)
+                        .await
+                        .map_err(|error| map_store_error(error, "proxy"))?;
+                    if !record.last_test.is_some_and(|test| test.success) {
+                        return Err(AdminError::conflict("请先测试代理连接"));
+                    }
+                    proxy_id = Some(record.id);
+                    Some(record.proxy)
+                }
+                Some(AccountProxySelection::Direct) | None => None,
+            };
+            AuthorizationMutationTarget::Create {
+                name: command.name.clone(),
+            }
+        }
     };
     Ok(PendingAuthorizationMutation::new(
         provider_kind.clone(),
@@ -108,13 +208,15 @@ async fn pending_authorization(
         crate::model::provider_credentials::AuthorizationOwnerBinding::from_context(
             &command.context,
         ),
-    ))
+    )
+    .with_outbound_proxy(proxy)
+    .with_outbound_proxy_id(proxy_id))
 }
 
 fn validate_prepared_import(
     provider_kind: &ProviderKind,
     prepared: &PreparedCredentialImport,
-    resource: &'static str,
+    _resource: &'static str,
 ) -> Result<(), AdminError> {
     if prepared.provider_kind != *provider_kind
         || prepared
@@ -122,9 +224,7 @@ fn validate_prepared_import(
             .iter()
             .any(|credential| credential.provider_kind != *provider_kind)
     {
-        return Err(AdminError::conflict(format!(
-            "{resource} prepared facts do not match the requested Provider scope"
-        )));
+        return Err(AdminError::conflict("Provider 准备结果与请求范围不一致"));
     }
     Ok(())
 }
@@ -132,15 +232,13 @@ fn validate_prepared_import(
 fn validate_prepared_rotation(
     account: &crate::model::accounts::AccountRecord,
     prepared: &PreparedCredentialRotation,
-    resource: &'static str,
+    _resource: &'static str,
 ) -> Result<(), AdminError> {
     let facts = prepared.facts();
     if facts.account_id.as_str() != account.id.as_str()
         || facts.provider_kind != account.provider_kind
     {
-        return Err(AdminError::conflict(format!(
-            "{resource} prepared facts do not match the current credential"
-        )));
+        return Err(AdminError::conflict("Provider 准备结果与当前凭据不一致"));
     }
     Ok(())
 }
@@ -154,9 +252,7 @@ async fn validate_authorization_commit(
     if prepared.pending.provider_kind() != provider_kind
         || !prepared.pending.owner_binding().matches_context(context)
     {
-        let validation_error = AdminError::conflict(format!(
-            "{resource} pending authorization binding is invalid"
-        ));
+        let validation_error = AdminError::conflict("OAuth 授权绑定已失效，请重新发起授权");
         if let Err(error) = prepared.abort().await {
             tracing::warn!(
                 resource,
@@ -182,9 +278,7 @@ async fn validate_authorization_commit(
         _ => false,
     };
     if !matches_target {
-        let validation_error = AdminError::conflict(format!(
-            "{resource} prepared credential does not match its pending target"
-        ));
+        let validation_error = AdminError::conflict("OAuth 凭据与待提交目标不一致");
         if let Err(error) = prepared.abort().await {
             tracing::warn!(
                 resource,
@@ -201,14 +295,24 @@ async fn validate_authorization_commit(
 async fn commit_authorization(
     accounts: &dyn AccountStore,
     prepared: PreparedAuthorizationCommit,
+    settings: Option<crate::model::accounts::AccountImportSettings>,
     context: &MutationContext,
     resource: &'static str,
 ) -> Result<CredentialMutationResult, AdminError> {
+    if settings.is_some()
+        && matches!(
+            &prepared.credential,
+            PreparedAuthorizationCredential::Reauthorize(_)
+        )
+    {
+        prepared.abort().await?;
+        return Err(AdminError::invalid("重新授权不能修改账号设置"));
+    }
     let crate::model::provider_credentials::AuthorizationCommitSettlement {
         command,
         credential_guard,
         authorization_guard,
-    } = prepared.into_commit();
+    } = prepared.into_commit(settings);
     match accounts.commit_authorization(command, context).await {
         Ok(result) => {
             if let Some(guard) = credential_guard {

backend/crates/gateway-admin/src/use_case/observability.rs

@@ -1,13 +1,16 @@
 //! 观测查询、趋势、费用覆盖与健康阈值规则。
 
 use std::{
-    collections::{BTreeMap, btree_map::Entry},
+    collections::{BTreeMap, HashMap, btree_map::Entry},
+    str::FromStr,
     sync::Arc,
+    time::{Duration as StdDuration, Instant},
 };
 
 use async_trait::async_trait;
 use chrono::{DateTime, Duration, Timelike as _, Utc};
-use gateway_core::{engine::credential::ProviderAccountId, routing::ProviderKind};
+use futures::TryStreamExt;
+use gateway_core::{account::ProviderAccountId, routing::ProviderKind};
 
 use crate::{
     model::{
@@ -27,7 +30,7 @@ use crate::{
     },
     ports::{
         provider::{ProviderAdminErrorKind, ProviderAdminRegistry},
-        store::{ObservabilityStore, SettingsStore},
+        store::{AccountStore, ObservabilityStore, SettingsStore, UsageCalculatedBillingStream},
     },
 };
 
@@ -38,6 +41,58 @@ const HEALTH_TIMELINE_SLOTS: i64 = 24 * 4;
 const HEALTH_TIMELINE_MIN_SAMPLE_SIZE: u64 = 10;
 const HEALTH_TIMELINE_UNAVAILABLE_FAILURE_THRESHOLD: u64 = 3;
 const HEALTH_TIMELINE_STABLE_RELIABILITY: f64 = 99.0;
+const DASHBOARD_QUERY_BUCKET_SECONDS: i64 = 2;
+const DASHBOARD_QUERY_CACHE_RETENTION: StdDuration = StdDuration::from_secs(2);
+
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+struct DashboardQueryKey {
+    start: DateTime<Utc>,
+    end_bucket: i64,
+}
+
+impl DashboardQueryKey {
+    fn new(range: TimeRange) -> Self {
+        Self {
+            start: range.start,
+            end_bucket: range
+                .end
+                .timestamp()
+                .div_euclid(DASHBOARD_QUERY_BUCKET_SECONDS),
+        }
+    }
+}
+
+struct DashboardQueryEntry {
+    created_at: Instant,
+    result: Arc<tokio::sync::OnceCell<Result<DashboardResult, AdminError>>>,
+}
+
+#[derive(Default)]
+struct DashboardQueryCache {
+    entries: tokio::sync::Mutex<HashMap<DashboardQueryKey, DashboardQueryEntry>>,
+}
+
+impl DashboardQueryCache {
+    async fn result_cell(
+        &self,
+        key: DashboardQueryKey,
+    ) -> Arc<tokio::sync::OnceCell<Result<DashboardResult, AdminError>>> {
+        let now = Instant::now();
+        let mut entries = self.entries.lock().await;
+        entries.retain(|_, entry| {
+            now.duration_since(entry.created_at) < DASHBOARD_QUERY_CACHE_RETENTION
+        });
+        Arc::clone(
+            &entries
+                .entry(key)
+                .or_insert_with(|| DashboardQueryEntry {
+                    created_at: now,
+                    result: Arc::new(tokio::sync::OnceCell::new()),
+                })
+                .result,
+        )
+    }
+}
 
 /// API 消费的观测控制面服务。
 #[async_trait]
@@ -72,31 +127,32 @@ pub trait ObservabilityService: Send + Sync {
 
 pub(crate) struct DefaultObservabilityService {
     store: Arc<dyn ObservabilityStore>,
+    accounts: Arc<dyn AccountStore>,
     settings: Arc<dyn SettingsStore>,
     providers: ProviderAdminRegistry,
+    dashboard_queries: DashboardQueryCache,
 }
 
 impl DefaultObservabilityService {
     #[must_use]
     pub(crate) fn new(
         store: Arc<dyn ObservabilityStore>,
+        accounts: Arc<dyn AccountStore>,
         settings: Arc<dyn SettingsStore>,
         providers: ProviderAdminRegistry,
     ) -> Self {
         Self {
             store,
+            accounts,
             settings,
             providers,
+            dashboard_queries: DashboardQueryCache::default(),
         }
     }
-}
 
-#[async_trait]
-impl ObservabilityService for DefaultObservabilityService {
-    async fn dashboard_summary(
+    async fn load_dashboard_summary(
         &self,
         range: TimeRange,
-        kind: TrendKind,
     ) -> Result<DashboardResult, AdminError> {
         let observed_at = Utc::now();
         let (mut observation, settings, runtime_slots) = futures::try_join!(
@@ -105,9 +161,14 @@ impl ObservabilityService for DefaultObservabilityService {
             self.store.dashboard_runtime_slots(observed_at),
         )
         .map_err(|error| map_store_error(error, "dashboard"))?;
-        self.enrich_billing(&mut observation.recent_requests);
+        self.enrich_list_billing(&mut observation.recent_requests);
         self.enrich_dashboard_quotas(&mut observation.account_usage)
             .await;
+        for account in &mut observation.account_usage {
+            account.plan_type_display = self
+                .providers
+                .plan_type_display(&account.provider_kind, account.plan_type.as_deref());
+        }
         let today_start = china_day_start(observation.range.end);
         let yesterday_start = today_start - Duration::days(1);
         let today =
@@ -118,11 +179,18 @@ impl ObservabilityService for DefaultObservabilityService {
             observation.totals.cached_tokens,
             observation.totals.input_tokens,
         );
-        let average_first_token_latency_ms = average(
-            observation.requests.first_token_latency_sum_ms,
-            observation.requests.first_token_latency_count,
-        );
-        let trend = trend(kind, observation.trend.clone())?;
+        let (first_token_latency_sum_ms, first_token_latency_count) = observation
+            .trend
+            .iter()
+            .fold((0_u64, 0_u64), |(sum, count), point| {
+                (
+                    sum.saturating_add(point.metrics.first_token_latency_sum_ms),
+                    count.saturating_add(point.metrics.first_token_latency_count),
+                )
+            });
+        let average_first_token_latency_ms =
+            average(first_token_latency_sum_ms, first_token_latency_count);
+        let trend = trend(TrendKind::Usage, observation.trend.clone())?;
         let health_timeline = health_timeline_at(&observation.trend, Utc::now());
         let wire_profiles = self.providers.dashboard_wire_profiles();
         let max_concurrent_per_account = u64::from(settings.max_concurrent_per_account);
@@ -160,6 +228,26 @@ impl ObservabilityService for DefaultObservabilityService {
             wire_profiles,
         })
     }
+}
+
+#[async_trait]
+impl ObservabilityService for DefaultObservabilityService {
+    async fn dashboard_summary(
+        &self,
+        range: TimeRange,
+        kind: TrendKind,
+    ) -> Result<DashboardResult, AdminError> {
+        let cell = self
+            .dashboard_queries
+            .result_cell(DashboardQueryKey::new(range))
+            .await;
+        let mut result = cell
+            .get_or_init(|| self.load_dashboard_summary(range))
+            .await
+            .clone()?;
+        result.trend = trend(kind, result.observation.trend.clone())?;
+        Ok(result)
+    }
 
     async fn dashboard_trend(
         &self,
@@ -180,20 +268,20 @@ impl ObservabilityService for DefaultObservabilityService {
             .list_usage_records(query)
             .await
             .map_err(|error| map_store_error(error, "usage records"))?;
-        self.enrich_billing(&mut page.items);
+        self.enrich_list_billing(&mut page.items);
         Ok(page)
     }
 
     async fn usage_record_detail(&self, request_id: &str) -> Result<UsageDetail, AdminError> {
         if request_id.trim().is_empty() {
-            return Err(AdminError::invalid("Usage record ID is required"));
+            return Err(AdminError::invalid("用量记录 ID 不能为空"));
         }
         let mut detail = self
             .store
             .usage_record_detail(request_id)
             .await
             .map_err(|error| map_store_error(error, "usage record"))?;
-        self.enrich_billing(std::slice::from_mut(&mut detail.request));
+        self.enrich_detail_billing(std::slice::from_mut(&mut detail.request));
         Ok(detail)
     }
 
@@ -222,13 +310,21 @@ impl ObservabilityService for DefaultObservabilityService {
         range: TimeRange,
         filter: UsageFilter,
     ) -> Result<UsageInsights, AdminError> {
-        let (overview, trend, billing_facts) = futures::try_join!(
-            self.store.usage_summary(range, filter.clone()),
-            self.store.usage_trend(range, filter.clone()),
-            self.store.usage_calculated_billing_facts(range, filter),
-        )
-        .map_err(|error| map_store_error(error, "usage insights"))?;
-        let standard_costs = recover_standard_costs(&self.providers, billing_facts)?;
+        let aggregates = async {
+            futures::try_join!(
+                self.store.usage_summary(range, filter.clone()),
+                self.store.usage_trend(range, filter.clone()),
+            )
+            .map_err(|error| map_store_error(error, "usage insights"))
+        };
+        let ((overview, trend), standard_costs) = futures::try_join!(
+            aggregates,
+            recover_standard_costs(
+                &self.providers,
+                self.store
+                    .usage_calculated_billing_facts(range, filter.clone()),
+            ),
+        )?;
         build_usage_insights(overview, trend, standard_costs)
     }
 
@@ -246,26 +342,50 @@ impl ObservabilityService for DefaultObservabilityService {
         let total_requests = items.iter().fold(0_u64, |total, item| {
             total.saturating_add(item.request_count)
         });
-        Ok(DiagnosticsResult {
-            dimension,
-            items: items
-                .into_iter()
-                .map(|item| DiagnosticsItem {
+        let mut items = items
+            .into_iter()
+            .map(|item| {
+                let error_rate = rate_or_zero(item.failure_count, item.request_count);
+                let non_completion_rate =
+                    rate_or_zero(item.non_completion_count, item.request_count);
+                let retry_rate = rate_or_zero(item.retry_count, item.request_count);
+                let impact_score = diagnostic_impact_score(
+                    item.request_count,
+                    total_requests,
+                    error_rate,
+                    non_completion_rate,
+                    retry_rate,
+                    item.first_token_p95_ms,
+                );
+                DiagnosticsItem {
                     key: item.key,
                     name: item.name,
                     request_count: item.request_count,
-                    success_count: item.request_count.saturating_sub(item.failure_count),
+                    success_count: item.success_count,
                     error_count: item.failure_count,
-                    error_rate: rate_or_zero(item.failure_count, item.request_count),
+                    error_rate,
                     request_share: rate_or_zero(item.request_count, total_requests),
                     average_latency_ms: item.average_latency_ms,
                     latency_p95_ms: item.latency_p95_ms,
+                    first_token_p95_ms: item.first_token_p95_ms,
+                    non_completion_count: item.non_completion_count,
+                    non_completion_rate,
+                    retry_count: item.retry_count,
+                    retry_rate,
+                    impact_score,
                     estimated_cost: usd_cost(&item.costs),
                     attempt_count: item.attempt_count,
                     total_tokens: item.total_tokens,
-                })
-                .collect(),
-        })
+                }
+            })
+            .collect::<Vec<_>>();
+        items.sort_by(|left, right| {
+            right
+                .impact_score
+                .total_cmp(&left.impact_score)
+                .then_with(|| right.request_count.cmp(&left.request_count))
+        });
+        Ok(DiagnosticsResult { dimension, items })
     }
 
     async fn ops_errors(&self, query: OpsErrorQuery) -> Result<OpsErrorPage, AdminError> {
@@ -279,35 +399,40 @@ impl ObservabilityService for DefaultObservabilityService {
 fn build_usage_insights(
     overview: UsageOverview,
     trend: Vec<RequestMetricPoint>,
-    standard_costs: UsageStandardCosts,
+    standard_costs: UsageCostScenarios,
 ) -> Result<UsageInsights, AdminError> {
     let granularity = trend.first().map_or(
         crate::model::observability::Granularity::FifteenMinutes,
         |point| point.granularity,
     );
     if trend.iter().any(|point| point.granularity != granularity) {
-        return Err(AdminError::internal(
-            "Usage insight trend contains mixed granularities",
-        ));
+        return Err(AdminError::internal("用量洞察趋势包含不一致的时间粒度"));
     }
 
     let requests = &overview.requests;
     let failed_requests = service_failure_count(requests);
     let health_requests = requests.success_count.saturating_add(failed_requests);
     let health = UsageInsightsHealth {
-        total_requests: health_requests,
+        total_requests: requests.request_count,
         success_requests: requests.success_count,
         failed_requests,
         cancelled_requests: requests.cancelled_count,
         incomplete_requests: requests.incomplete_count,
         caller_error_requests: requests.caller_error_count,
         success_rate: rate_or_zero(requests.success_count, health_requests),
+        completion_rate: rate_or_zero(
+            requests
+                .success_count
+                .saturating_add(requests.failure_count),
+            requests.request_count,
+        ),
         points: trend
             .iter()
             .map(|point| {
                 let failed_requests = service_failure_count(&point.metrics);
                 let health_requests = point.metrics.success_count.saturating_add(failed_requests);
                 UsageInsightsHealthPoint {
+                    total_requests: point.metrics.request_count,
                     bucket_start: point.bucket_start,
                     success_requests: point.metrics.success_count,
                     failed_requests,
@@ -327,27 +452,74 @@ fn build_usage_insights(
             requests.first_token_latency_count,
             requests.request_count,
         ),
+        admission_decision_percentiles: requests.admission_decision_percentiles,
+        account_selection_wait_percentiles: requests.account_selection_wait_percentiles,
+        admission_decision_coverage: rate_or_zero(
+            requests.admission_decision_count,
+            requests.request_count,
+        ),
+        account_selection_wait_coverage: rate_or_zero(
+            requests.account_selection_wait_count,
+            requests.request_count,
+        ),
+        output_throughput_p10: requests.output_throughput_p10,
+        output_throughput_p50: requests.output_throughput_p50,
+        output_throughput_p90: requests.output_throughput_p90,
+        capacity_utilization_avg_basis_points: requests.capacity_utilization_avg_basis_points,
+        capacity_utilization_p95_basis_points: requests.capacity_utilization_p95_basis_points,
+        capacity_coverage: rate_or_zero(requests.capacity_sample_count, requests.request_count),
         points: trend
             .iter()
             .map(|point| UsageInsightsPerformancePoint {
                 bucket_start: point.bucket_start,
                 latency_percentiles: point.metrics.latency_percentiles,
                 first_token_latency_percentiles: point.metrics.first_token_latency_percentiles,
+                admission_decision_percentiles: point.metrics.admission_decision_percentiles,
+                account_selection_wait_percentiles: point
+                    .metrics
+                    .account_selection_wait_percentiles,
+                output_throughput_p10: point.metrics.output_throughput_p10,
+                output_throughput_p50: point.metrics.output_throughput_p50,
+                output_throughput_p90: point.metrics.output_throughput_p90,
+                capacity_utilization_avg_basis_points: point
+                    .metrics
+                    .capacity_utilization_avg_basis_points,
+                capacity_utilization_p95_basis_points: point
+                    .metrics
+                    .capacity_utilization_p95_basis_points,
             })
             .collect(),
     };
     let estimated_cost = usd_cost(&overview.attempts.costs);
-    let UsageStandardCosts {
-        total: standard_cost,
-        by_bucket: standard_costs_by_bucket,
+    let UsageCostScenarios {
+        standard:
+            ScenarioCosts {
+                total: standard_cost,
+                by_bucket: standard_costs_by_bucket,
+            },
+        no_cache:
+            ScenarioCosts {
+                total: no_cache_cost,
+                by_bucket: no_cache_costs_by_bucket,
+            },
     } = standard_costs;
+    let cache_savings = amount_difference(no_cache_cost.as_ref(), estimated_cost.as_ref());
+    let tier_premium = amount_difference(estimated_cost.as_ref(), standard_cost.as_ref());
+    let cost_per_request = estimated_cost
+        .as_ref()
+        .and_then(|cost| cost.checked_div_u64(requests.request_count));
+    let cost_per_successful_request = estimated_cost
+        .as_ref()
+        .and_then(|cost| cost.checked_div_u64(requests.success_count));
     let cost = UsageInsightsCost {
-        cost_per_request: estimated_cost
-            .as_ref()
-            .and_then(|cost| cost.checked_div_u64(requests.request_count)),
+        cost_per_request,
         estimated_cost,
         standard_cost,
+        no_cache_cost,
+        cache_savings,
+        tier_premium,
         tokens_per_request: rate_or_zero(requests.total_tokens, requests.request_count),
+        cost_per_successful_request,
         cached_token_rate: rate_or_zero(requests.cached_tokens, requests.input_tokens),
         cache_hit_request_rate: ratio(
             requests.cache_hit_request_count,
@@ -367,6 +539,11 @@ fn build_usage_insights(
                 total_tokens: point.metrics.total_tokens,
                 estimated_cost: usd_cost(&point.costs),
                 standard_cost: standard_costs_by_bucket.get(&point.bucket_start).cloned(),
+                no_cache_cost: no_cache_costs_by_bucket.get(&point.bucket_start).cloned(),
+                cache_savings: amount_difference(
+                    no_cache_costs_by_bucket.get(&point.bucket_start),
+                    usd_cost(&point.costs).as_ref(),
+                ),
                 cached_token_rate: rate_or_zero(
                     point.metrics.cached_tokens,
                     point.metrics.input_tokens,
@@ -391,12 +568,12 @@ fn build_usage_insights(
 }
 
 #[derive(Debug, Default)]
-struct UsageStandardCosts {
+struct ScenarioCosts {
     total: Option<DecimalAmount>,
     by_bucket: BTreeMap<DateTime<Utc>, DecimalAmount>,
 }
 
-impl UsageStandardCosts {
+impl ScenarioCosts {
     fn add(
         &mut self,
         bucket_start: DateTime<Utc>,
@@ -405,14 +582,15 @@ impl UsageStandardCosts {
         self.total = Some(match self.total.take() {
             Some(current) => current
                 .checked_add(&amount)
-                .ok_or_else(|| AdminError::internal("Usage standard cost exceeds decimal range"))?,
+                .ok_or_else(|| AdminError::internal("用量标准成本超出数值范围"))?,
             None => amount.clone(),
         });
         match self.by_bucket.entry(bucket_start) {
             Entry::Occupied(mut entry) => {
-                let sum = entry.get().checked_add(&amount).ok_or_else(|| {
-                    AdminError::internal("Usage standard cost exceeds decimal range")
-                })?;
+                let sum = entry
+                    .get()
+                    .checked_add(&amount)
+                    .ok_or_else(|| AdminError::internal("用量标准成本超出数值范围"))?;
                 entry.insert(sum);
             }
             Entry::Vacant(entry) => {
@@ -423,23 +601,33 @@ impl UsageStandardCosts {
     }
 }
 
-fn recover_standard_costs(
+#[derive(Debug, Default)]
+struct UsageCostScenarios {
+    standard: ScenarioCosts,
+    no_cache: ScenarioCosts,
+}
+
+async fn recover_standard_costs(
     providers: &ProviderAdminRegistry,
-    facts: Vec<UsageCalculatedBillingFact>,
-) -> Result<UsageStandardCosts, AdminError> {
-    let mut standard_costs = UsageStandardCosts::default();
-    for fact in facts {
-        let Ok(provider_kind) = ProviderKind::new(fact.provider_kind) else {
+    mut facts: UsageCalculatedBillingStream<'_>,
+) -> Result<UsageCostScenarios, AdminError> {
+    let mut scenarios = UsageCostScenarios::default();
+    while let Some(fact) = facts
+        .try_next()
+        .await
+        .map_err(|error| map_store_error(error, "usage billing facts"))?
+    {
+        let Ok(provider_kind) = ProviderKind::new(fact.provider_kind.clone()) else {
             continue;
         };
         let input = ProviderBillingInput {
-            upstream_model_id: fact.upstream_model_id,
-            service_tier: fact.service_tier,
+            upstream_model_id: fact.upstream_model_id.clone(),
+            service_tier: fact.service_tier.clone(),
             input_tokens: fact.input_tokens,
             output_tokens: fact.output_tokens,
             cached_tokens: fact.cached_tokens,
             cache_write_tokens: fact.cache_write_tokens,
-            total: fact.total,
+            total: fact.total.clone(),
         };
         let breakdown = match providers.calculated_billing(&provider_kind, &input) {
             Ok(breakdown) => breakdown,
@@ -456,9 +644,80 @@ fn recover_standard_costs(
         {
             continue;
         }
-        standard_costs.add(fact.bucket_start, breakdown.standard_amount.amount)?;
+        scenarios
+            .standard
+            .add(fact.bucket_start, breakdown.standard_amount.amount.clone())?;
+        if let Some(no_cache_cost) = no_cache_cost(&fact, &breakdown) {
+            scenarios.no_cache.add(fact.bucket_start, no_cache_cost)?;
+        }
     }
-    Ok(standard_costs)
+    Ok(scenarios)
+}
+
+fn no_cache_cost(
+    fact: &UsageCalculatedBillingFact,
+    breakdown: &crate::model::observability::CalculatedBillingBreakdown,
+) -> Option<DecimalAmount> {
+    let input_tokens = fact.input_tokens?;
+    let cached_tokens = fact.cached_tokens.unwrap_or_default().min(input_tokens);
+    let cache_write_tokens = fact
+        .cache_write_tokens
+        .unwrap_or_default()
+        .min(input_tokens.saturating_sub(cached_tokens));
+    let input_rate = decimal(&breakdown.input_price_per_million.amount)?;
+    let replaced_input_amount = input_rate
+        .scaled()
+        .checked_mul(u128::from(cached_tokens.saturating_add(cache_write_tokens)))?
+        .checked_div(1_000_000)?;
+    let total = decimal(&breakdown.total_amount.amount)?
+        .scaled()
+        .checked_sub(decimal(&breakdown.cache_read_amount.amount)?.scaled())?
+        .checked_sub(decimal(&breakdown.cache_write_amount.amount)?.scaled())?
+        .checked_add(replaced_input_amount)?;
+    DecimalAmount::from_str(
+        &gateway_core::metering::Decimal::from_scaled(total)
+            .ok()?
+            .canonical(),
+    )
+    .ok()
+}
+
+fn amount_difference(
+    larger: Option<&DecimalAmount>,
+    smaller: Option<&DecimalAmount>,
+) -> Option<DecimalAmount> {
+    let difference = decimal(larger?)?
+        .scaled()
+        .checked_sub(decimal(smaller?)?.scaled())?;
+    DecimalAmount::from_str(
+        &gateway_core::metering::Decimal::from_scaled(difference)
+            .ok()?
+            .canonical(),
+    )
+    .ok()
+}
+
+fn decimal(value: &DecimalAmount) -> Option<gateway_core::metering::Decimal> {
+    value.as_str().parse().ok()
+}
+
+fn diagnostic_impact_score(
+    request_count: u64,
+    total_requests: u64,
+    error_rate: f64,
+    non_completion_rate: f64,
+    retry_rate: f64,
+    first_token_p95_ms: Option<u64>,
+) -> f64 {
+    let request_share = rate_or_zero(request_count, total_requests);
+    let slow_score = first_token_p95_ms
+        .map_or(0.0, |value| value as f64 / 30_000.0)
+        .min(1.0);
+    error_rate * 0.35
+        + non_completion_rate * 0.25
+        + retry_rate.min(1.0) * 0.20
+        + request_share * 0.10
+        + slow_score * 0.10
 }
 
 fn usd_cost(costs: &[CurrencyCost]) -> Option<DecimalAmount> {
@@ -470,8 +729,31 @@ fn usd_cost(costs: &[CurrencyCost]) -> Option<DecimalAmount> {
 
 impl DefaultObservabilityService {
     async fn enrich_dashboard_quotas(&self, accounts: &mut [DashboardAccountUsage]) {
+        if accounts.is_empty() {
+            return;
+        }
+        let now = Utc::now();
+        let ids = accounts
+            .iter()
+            .map(|account| account.account_id.clone())
+            .collect::<Vec<_>>();
+        let mut rolling_usage = self
+            .accounts
+            .load_account_usage(
+                TimeRange {
+                    start: now - Duration::hours(24),
+                    end: now,
+                },
+                &ids,
+            )
+            .await
+            .unwrap_or_default()
+            .into_iter()
+            .map(|usage| (usage.account_id.clone(), usage))
+            .collect::<HashMap<_, _>>();
         let providers = self.providers.clone();
         let quota_reads = accounts.iter().map(|account| {
+            let rolling_usage = rolling_usage.remove(&account.account_id);
             let account_id = ProviderAccountId::new(account.account_id.clone()).ok();
             let provider = ProviderKind::new(account.provider_kind.clone())
                 .ok()
@@ -484,22 +766,58 @@ impl DefaultObservabilityService {
                     .quota(ProviderQuotaRequest {
                         account_id,
                         refresh: false,
-                        rolling_usage: None,
+                        rolling_usage,
                     })
                     .await
                     .ok()
-                    .and_then(|quota| quota.representative_used_percent())
             }
         });
-        let quota_used = futures::future::join_all(quota_reads).await;
-        for (account, used_percent) in accounts.iter_mut().zip(quota_used) {
-            account.quota_used_percent = used_percent;
+        let quotas = futures::future::join_all(quota_reads).await;
+        for (account, quota) in accounts.iter_mut().zip(quotas) {
+            if let Some(mut quota) = quota {
+                quota.fill_missing_plan_type(&mut account.plan_type);
+                quota.apply_limit_reached_display();
+                account.quota_used_percent = quota.representative_used_percent();
+                account.quota_window = quota.representative_window().cloned();
+            }
         }
     }
 
     /// 逐条尽力把可校验的总额升级为完整分解；单条脏数据（非法 Provider kind、
     /// 不支持的来源或费用规则失败）只保留该条已存的总额，不影响整页返回。
-    fn enrich_billing(&self, records: &mut [crate::model::observability::UsageRecord]) {
+    fn enrich_list_billing(&self, records: &mut [crate::model::observability::UsageListRecord]) {
+        for record in records {
+            let Some(UsageBilling::Total { source, total }) = record.billing.as_ref() else {
+                continue;
+            };
+            if !matches!(source.as_str(), "calculated" | "provider_reported") {
+                continue;
+            }
+            let (Some(provider), Some(upstream_model_id)) = (
+                record.provider_kind.as_deref(),
+                record.upstream_model_id.as_ref(),
+            ) else {
+                continue;
+            };
+            let Ok(provider_kind) = ProviderKind::new(provider.to_owned()) else {
+                continue;
+            };
+            let input = ProviderBillingInput {
+                upstream_model_id: upstream_model_id.clone(),
+                service_tier: record.service_tier.clone(),
+                input_tokens: record.input_tokens,
+                output_tokens: record.output_tokens,
+                cached_tokens: record.cached_tokens,
+                cache_write_tokens: record.cache_write_tokens,
+                total: total.clone(),
+            };
+            if let Ok(Some(breakdown)) = self.providers.calculated_billing(&provider_kind, &input) {
+                record.billing = Some(UsageBilling::Calculated(Box::new(breakdown)));
+            }
+        }
+    }
+
+    fn enrich_detail_billing(&self, records: &mut [crate::model::observability::UsageRecord]) {
         for record in records {
             let Some(UsageBilling::Total { source, total }) = record.billing.as_ref() else {
                 continue;
@@ -612,9 +930,9 @@ fn trend(kind: TrendKind, points: Vec<RequestMetricPoint>) -> Result<Trend, Admi
             .saturating_add(point.cost_coverage.not_billable_count);
         for cost in &point.costs {
             if let Some(amount) = costs.get_mut(&cost.currency) {
-                *amount = amount.checked_add(&cost.amount).ok_or_else(|| {
-                    AdminError::internal("Cost aggregation exceeded numeric bounds")
-                })?;
+                *amount = amount
+                    .checked_add(&cost.amount)
+                    .ok_or_else(|| AdminError::internal("成本聚合结果超出数值范围"))?;
             } else {
                 costs.insert(cost.currency.clone(), cost.amount.clone());
             }
@@ -630,6 +948,20 @@ fn trend(kind: TrendKind, points: Vec<RequestMetricPoint>) -> Result<Trend, Admi
         metrics.cache_hit_request_count,
         metrics.cache_eligible_request_count,
     );
+    let peak_first_token_p95_ms = points
+        .iter()
+        .filter_map(|point| point.metrics.first_token_latency_percentiles.p95_ms)
+        .map(|value| value.as_f64())
+        .reduce(f64::max);
+    let peak_latency_p95_ms = points
+        .iter()
+        .filter_map(|point| point.metrics.latency_percentiles.p95_ms)
+        .map(|value| value.as_f64())
+        .reduce(f64::max);
+    let minimum_output_throughput_p50 = points
+        .iter()
+        .filter_map(|point| point.metrics.output_throughput_p50)
+        .min();
     Ok(Trend {
         kind,
         points: points.into_iter().map(trend_point).collect(),
@@ -643,6 +975,9 @@ fn trend(kind: TrendKind, points: Vec<RequestMetricPoint>) -> Result<Trend, Admi
             average_latency_ms,
             max_latency_ms: metrics.max_latency_ms,
             min_latency_ms: metrics.min_latency_ms,
+            peak_first_token_p95_ms,
+            peak_latency_p95_ms,
+            minimum_output_throughput_p50,
             success_rate,
             cache_hit_request_rate,
             costs: costs

backend/crates/gateway-admin/src/use_case/openai.rs

@@ -3,17 +3,16 @@
 use std::sync::Arc;
 
 use async_trait::async_trait;
-use gateway_core::{engine::credential::ProviderAccountId, routing::snapshot::SnapshotControl};
+use gateway_core::runtime::SnapshotControl;
 
 use crate::{
     model::{
         AdminError,
         provider_credentials::{
             AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
-            CredentialDeletionResult, CredentialDetails, CredentialImportCommit,
-            CredentialImportResult, CredentialListQuery, CredentialMutationResult, CredentialPage,
-            ImportCredentials, PrepareCredentialImport, PrepareCredentialRotation,
-            ProviderQuotaRequest, RotateCredential, StartAuthorization,
+            CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
+            CredentialMutationResult, ImportCredentials, PrepareCredentialImport,
+            PrepareCredentialRotation, RotateCredential, StartAuthorization,
         },
     },
     ports::{provider::ProviderAdmin, store::AccountStore},
@@ -21,18 +20,14 @@ use crate::{
 
 use super::{
     commit_authorization, commit_credential_rotation, delete_credentials, map_provider_error,
-    map_store_error, pending_authorization, publish_committed, required_credential,
-    validate_authorization_commit, validate_prepared_import, validate_prepared_rotation,
+    map_store_error, pending_authorization, publish_committed,
+    publish_credentials_and_observe_quota, required_credential, validate_authorization_commit,
+    validate_prepared_import, validate_prepared_rotation,
 };
 
 /// OpenAI 固定管理路由消费的服务。
 #[async_trait]
 pub trait OpenAiService: Send + Sync {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError>;
-    async fn details(
-        &self,
-        account_id: &ProviderAccountId,
-    ) -> Result<CredentialDetails, AdminError>;
     async fn import_document(
         &self,
         command: ImportCredentials,
@@ -58,6 +53,7 @@ pub trait OpenAiService: Send + Sync {
 pub(crate) struct DefaultOpenAiService {
     provider: Arc<dyn ProviderAdmin>,
     accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
     snapshot: Arc<dyn SnapshotControl>,
 }
 
@@ -66,71 +62,39 @@ impl DefaultOpenAiService {
     pub(crate) fn new(
         provider: Arc<dyn ProviderAdmin>,
         accounts: Arc<dyn AccountStore>,
+        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
         snapshot: Arc<dyn SnapshotControl>,
     ) -> Self {
         Self {
             provider,
             accounts,
+            proxies,
             snapshot,
         }
     }
-
-    fn observe_initial_quotas(&self, account_ids: &[ProviderAccountId], request_id: &str) {
-        let provider = Arc::clone(&self.provider);
-        let account_ids = account_ids.to_vec();
-        let request_id = request_id.to_owned();
-        tokio::spawn(async move {
-            for account_id in account_ids {
-                if let Err(error) = provider
-                    .quota(ProviderQuotaRequest {
-                        account_id: account_id.clone(),
-                        refresh: true,
-                        rolling_usage: None,
-                    })
-                    .await
-                {
-                    tracing::warn!(
-                        request_id,
-                        account_id = %account_id.as_str(),
-                        quota_error = ?error.kind(),
-                        "OpenAI initial quota observation failed"
-                    );
-                }
-            }
-        });
-    }
 }
 
 #[async_trait]
 impl OpenAiService for DefaultOpenAiService {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError> {
-        self.accounts
-            .list_credentials(self.provider.provider_kind(), query)
-            .await
-            .map_err(|error| map_store_error(error, "OpenAI credential"))
-    }
-
-    async fn details(
-        &self,
-        account_id: &ProviderAccountId,
-    ) -> Result<CredentialDetails, AdminError> {
-        required_credential(
-            self.accounts.as_ref(),
-            self.provider.provider_kind(),
-            account_id,
-            "OpenAI credential",
-        )
-        .await
-    }
-
     async fn import_document(
         &self,
         command: ImportCredentials,
     ) -> Result<CredentialImportResult, AdminError> {
         let context = command.context;
+        let proxy_reservation = super::import_proxy_binding(
+            self.proxies.as_ref(),
+            command.outbound_proxy_id.as_deref(),
+        )
+        .await?;
+        let outbound_proxy = proxy_reservation
+            .as_ref()
+            .map(|reservation| reservation.binding.clone());
         let prepared = self
             .provider
             .prepare_import(PrepareCredentialImport {
+                default_outbound_proxy: outbound_proxy
+                    .as_ref()
+                    .map(|binding| binding.proxy.clone()),
                 document: command.document,
             })
             .await
@@ -142,15 +106,25 @@ impl OpenAiService for DefaultOpenAiService {
         )?;
         let result = self
             .accounts
-            .commit_credential_import(CredentialImportCommit { prepared }, &context)
+            .commit_credential_import(
+                CredentialImportCommit {
+                    outbound_proxy,
+                    prepared,
+                    settings: command.settings,
+                },
+                &context,
+            )
             .await
             .map_err(|error| map_store_error(error, "OpenAI credential import"))?;
-        self.provider
-            .account_facts_changed(&result.credential_ids)
-            .await;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        // 导入完成后立即做一次观察；失败不回滚已经提交的 credential。
-        self.observe_initial_quotas(&result.credential_ids, &context.request_id);
+        drop(proxy_reservation);
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            &result.credential_ids,
+            &context.request_id,
+        )
+        .await?;
         Ok(result)
     }
 
@@ -160,6 +134,7 @@ impl OpenAiService for DefaultOpenAiService {
     ) -> Result<AuthorizationStarted, AdminError> {
         let pending = pending_authorization(
             self.accounts.as_ref(),
+            self.proxies.as_ref(),
             self.provider.provider_kind(),
             &command,
             "OpenAI credential",
@@ -173,9 +148,10 @@ impl OpenAiService for DefaultOpenAiService {
 
     async fn complete_authorization(
         &self,
-        command: CompleteAuthorization,
+        mut command: CompleteAuthorization,
     ) -> Result<CredentialMutationResult, AdminError> {
         let context = command.context.clone();
+        let settings = command.settings.take();
         let prepared = self
             .provider
             .complete_authorization(command)
@@ -191,18 +167,19 @@ impl OpenAiService for DefaultOpenAiService {
         let result = commit_authorization(
             self.accounts.as_ref(),
             prepared,
+            settings,
             &context,
             "OpenAI authorization",
         )
         .await?;
-        self.provider
-            .account_facts_changed(std::slice::from_ref(&result.account_id))
-            .await;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        self.observe_initial_quotas(
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
             std::slice::from_ref(&result.account_id),
             &context.request_id,
-        );
+        )
+        .await?;
         Ok(result)
     }
 

backend/crates/gateway-admin/src/use_case/proxies.rs

@@ -0,0 +1,261 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use futures::{StreamExt, stream};
+use gateway_core::{
+    account::{OutboundProxy, ProviderAccountId},
+    routing::ProviderKind,
+    runtime::SnapshotControl,
+};
+use tokio::sync::Semaphore;
+
+use super::{map_store_error, publish_committed};
+use crate::{
+    model::{
+        AdminError, AdminErrorKind, MutationContext, Revision,
+        provider_credentials::{ProviderQuotaRequest, explicit_plan_type},
+        proxies::*,
+    },
+    ports::{
+        provider::ProviderAdminRegistry,
+        proxy::{ProxyProbe, ProxyStore},
+        store::AdminStoreErrorKind,
+    },
+};
+
+#[async_trait]
+pub trait ProxiesService: Send + Sync {
+    async fn list(&self, query: ProxyListQuery) -> Result<ProxyPage, AdminError>;
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> Result<ProxyAccountPage, AdminError>;
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &str,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError>;
+    async fn create(
+        &self,
+        command: NewProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError>;
+    async fn update(
+        &self,
+        command: UpdateProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError>;
+    async fn delete(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError>;
+    async fn test(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<ProxyRecord, AdminError>;
+    /// 探测未保存的连接地址，不写入代理记录或修改账号绑定。
+    async fn probe(&self, proxy: &OutboundProxy) -> Result<ProxyTestResult, AdminError>;
+}
+
+pub(crate) struct DefaultProxiesService {
+    store: Arc<dyn ProxyStore>,
+    probe: Arc<dyn ProxyProbe>,
+    snapshot: Arc<dyn SnapshotControl>,
+    providers: ProviderAdminRegistry,
+    test_slots: Semaphore,
+}
+
+impl DefaultProxiesService {
+    pub(crate) fn new(
+        store: Arc<dyn ProxyStore>,
+        probe: Arc<dyn ProxyProbe>,
+        snapshot: Arc<dyn SnapshotControl>,
+        providers: ProviderAdminRegistry,
+    ) -> Self {
+        Self {
+            store,
+            probe,
+            snapshot,
+            providers,
+            test_slots: Semaphore::new(4),
+        }
+    }
+}
+
+#[async_trait]
+impl ProxiesService for DefaultProxiesService {
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &str,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        if proxy_id.is_empty() || proxy_id.len() > 128 || proxy_id.chars().any(char::is_control) {
+            return Err(AdminError::invalid("代理 ID 不合法"));
+        }
+        let account_id = ProviderAccountId::new(account_id.to_owned())
+            .map_err(|_| AdminError::invalid("账号 ID 不合法"))?;
+        let revision = self
+            .store
+            .remove_account(proxy_id, &account_id, context)
+            .await
+            .map_err(|error| {
+                if error.kind() == AdminStoreErrorKind::Conflict {
+                    AdminError::conflict("账号的代理绑定已变化，请刷新后重试")
+                } else {
+                    map_store_error(error, "proxy account")
+                }
+            })?;
+        publish_committed(self.snapshot.as_ref(), revision).await?;
+        Ok(revision)
+    }
+
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> Result<ProxyAccountPage, AdminError> {
+        if query.proxy_id.is_empty()
+            || query.proxy_id.len() > 128
+            || query.proxy_id.chars().any(char::is_control)
+            || query.page == 0
+            || query.search.len() > 256
+            || query.search.chars().any(char::is_control)
+        {
+            return Err(AdminError::invalid("关联账号查询参数不合法"));
+        }
+        let mut page = self
+            .store
+            .list_accounts(query)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        page.items = stream::iter(page.items)
+            .map(|mut account| async {
+                // 与账号目录一致，缺失套餐时读取已有额度快照；限制并发且不触发上游刷新。
+                let mut cached_quota = None;
+                if explicit_plan_type(account.plan_type.as_deref()).is_none()
+                    && let Ok(kind) = ProviderKind::new(account.provider_kind.clone())
+                    && let Ok(provider) = self.providers.require(&kind)
+                    && let Ok(account_id) = ProviderAccountId::new(account.id.clone())
+                    && let Ok(quota) = provider
+                        .quota(ProviderQuotaRequest {
+                            account_id,
+                            refresh: false,
+                            rolling_usage: None,
+                        })
+                        .await
+                {
+                    cached_quota = Some(quota);
+                }
+                account.plan_type_display = self.providers.resolve_account_plan(
+                    &account.provider_kind,
+                    &mut account.plan_type,
+                    cached_quota.as_ref(),
+                );
+                account
+            })
+            .buffered(8)
+            .collect()
+            .await;
+        Ok(page)
+    }
+
+    async fn list(&self, query: ProxyListQuery) -> Result<ProxyPage, AdminError> {
+        if query.page == 0 || query.search.len() > 256 || query.search.chars().any(char::is_control)
+        {
+            return Err(AdminError::invalid("代理查询参数不合法"));
+        }
+        self.store
+            .list(query)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))
+    }
+
+    async fn create(
+        &self,
+        mut command: NewProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError> {
+        command.name = validate_name(&command.name)?;
+        let result = self
+            .store
+            .create(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn update(
+        &self,
+        mut command: UpdateProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError> {
+        command.name = validate_name(&command.name)?;
+        let result = self
+            .store
+            .update(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn delete(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        let result = self
+            .store
+            .delete(id, revision, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        publish_committed(self.snapshot.as_ref(), result).await?;
+        Ok(result)
+    }
+
+    async fn probe(&self, proxy: &OutboundProxy) -> Result<ProxyTestResult, AdminError> {
+        let _permit = self.test_slots.try_acquire().map_err(|_| {
+            AdminError::new(AdminErrorKind::RateLimited, "代理测试繁忙，请稍后重试")
+        })?;
+        Ok(self.probe.test(proxy).await)
+    }
+
+    async fn test(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<ProxyRecord, AdminError> {
+        let _permit = self.test_slots.try_acquire().map_err(|_| {
+            AdminError::new(AdminErrorKind::RateLimited, "代理测试繁忙，请稍后重试")
+        })?;
+        let record = self
+            .store
+            .get(id)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        if record.revision != revision {
+            return Err(AdminError::conflict("代理已被修改，请刷新后重新测试"));
+        }
+        let result = self.probe.test(&record.proxy).await;
+        self.store
+            .record_test(id, revision, result, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))
+    }
+}
+
+fn validate_name(value: &str) -> Result<String, AdminError> {
+    let value = value.trim();
+    if value.is_empty() || value.chars().count() > 100 || value.chars().any(char::is_control) {
+        return Err(AdminError::invalid("代理名称需要 1 至 100 个字符"));
+    }
+    Ok(value.to_owned())
+}

backend/crates/gateway-admin/src/use_case/settings.rs

@@ -3,7 +3,8 @@
 use std::sync::Arc;
 
 use async_trait::async_trait;
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::policy::CodexClientVersion;
+use gateway_core::runtime::SnapshotControl;
 use rand_core::{OsRng, RngCore as _};
 
 use crate::{
@@ -119,10 +120,16 @@ fn validate_settings(command: &ReplaceRuntimeSettings) -> Result<(), AdminError>
         && command.usage_retention_days >= 31
         && command.ops_event_retention_days > 0
         && command.audit_retention_days > 0
+        && valid_client_version(command.min_codex_desktop_version.as_deref())
+        && valid_client_version(command.min_codex_cli_version.as_deref())
         && i64::try_from(command.request_interval_ms).is_ok();
     if valid {
         Ok(())
     } else {
-        Err(AdminError::invalid("Runtime settings violate constraints"))
+        Err(AdminError::invalid("运行时设置不满足约束"))
     }
 }
+
+fn valid_client_version(value: Option<&str>) -> bool {
+    value.is_none_or(|value| CodexClientVersion::parse(value).is_ok())
+}

backend/crates/gateway-admin/src/use_case/system.rs

@@ -94,5 +94,12 @@ fn map_system_error(error: SystemOperationError) -> AdminError {
         SystemOperationErrorKind::Upstream => AdminErrorKind::BadGateway,
         SystemOperationErrorKind::Internal => AdminErrorKind::Internal,
     };
-    AdminError::new(kind, error.message())
+    let message = match kind {
+        AdminErrorKind::Invalid => "系统操作请求不合法",
+        AdminErrorKind::Conflict => "系统当前状态不允许执行该操作",
+        AdminErrorKind::BadGateway => "系统更新服务请求失败",
+        AdminErrorKind::Internal => "系统操作失败",
+        _ => "系统操作失败",
+    };
+    AdminError::new(kind, message)
 }

backend/crates/gateway-admin/src/use_case/xai.rs

@@ -3,7 +3,7 @@
 use std::sync::Arc;
 
 use async_trait::async_trait;
-use gateway_core::routing::snapshot::SnapshotControl;
+use gateway_core::runtime::SnapshotControl;
 
 use crate::{
     model::{
@@ -11,8 +11,8 @@ use crate::{
         provider_credentials::{
             AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
             CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
-            CredentialListQuery, CredentialMutationResult, CredentialPage, ImportCredentials,
-            PrepareCredentialImport, ProviderQuotaRequest, StartAuthorization,
+            CredentialMutationResult, ImportCredentials, PrepareCredentialImport,
+            StartAuthorization,
         },
     },
     ports::{provider::ProviderAdmin, store::AccountStore},
@@ -20,14 +20,13 @@ use crate::{
 
 use super::{
     commit_authorization, delete_credentials, map_provider_error, map_store_error,
-    pending_authorization, publish_committed, validate_authorization_commit,
-    validate_prepared_import,
+    pending_authorization, publish_committed, publish_credentials_and_observe_quota,
+    validate_authorization_commit, validate_prepared_import,
 };
 
 /// xAI 固定管理路由消费的服务。
 #[async_trait]
 pub trait XaiService: Send + Sync {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError>;
     async fn import_document(
         &self,
         command: ImportCredentials,
@@ -49,6 +48,7 @@ pub trait XaiService: Send + Sync {
 pub(crate) struct DefaultXaiService {
     provider: Arc<dyn ProviderAdmin>,
     accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
     snapshot: Arc<dyn SnapshotControl>,
 }
 
@@ -57,11 +57,13 @@ impl DefaultXaiService {
     pub(crate) fn new(
         provider: Arc<dyn ProviderAdmin>,
         accounts: Arc<dyn AccountStore>,
+        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
         snapshot: Arc<dyn SnapshotControl>,
     ) -> Self {
         Self {
             provider,
             accounts,
+            proxies,
             snapshot,
         }
     }
@@ -69,21 +71,25 @@ impl DefaultXaiService {
 
 #[async_trait]
 impl XaiService for DefaultXaiService {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError> {
-        self.accounts
-            .list_credentials(self.provider.provider_kind(), query)
-            .await
-            .map_err(|error| map_store_error(error, "xAI credential"))
-    }
-
     async fn import_document(
         &self,
         command: ImportCredentials,
     ) -> Result<CredentialImportResult, AdminError> {
         let context = command.context;
+        let proxy_reservation = super::import_proxy_binding(
+            self.proxies.as_ref(),
+            command.outbound_proxy_id.as_deref(),
+        )
+        .await?;
+        let outbound_proxy = proxy_reservation
+            .as_ref()
+            .map(|reservation| reservation.binding.clone());
         let prepared = self
             .provider
             .prepare_import(PrepareCredentialImport {
+                default_outbound_proxy: outbound_proxy
+                    .as_ref()
+                    .map(|binding| binding.proxy.clone()),
                 document: command.document,
             })
             .await
@@ -95,21 +101,25 @@ impl XaiService for DefaultXaiService {
         )?;
         let result = self
             .accounts
-            .commit_credential_import(CredentialImportCommit { prepared }, &context)
+            .commit_credential_import(
+                CredentialImportCommit {
+                    outbound_proxy,
+                    prepared,
+                    settings: command.settings,
+                },
+                &context,
+            )
             .await
             .map_err(|error| map_store_error(error, "xAI credential import"))?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        // 导入已经提交，额度属于可重建观察事实；单个账号查询失败由周期任务重试。
-        for account_id in &result.credential_ids {
-            let _ = self
-                .provider
-                .quota(ProviderQuotaRequest {
-                    account_id: account_id.clone(),
-                    refresh: true,
-                    rolling_usage: None,
-                })
-                .await;
-        }
+        drop(proxy_reservation);
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            &result.credential_ids,
+            &context.request_id,
+        )
+        .await?;
         Ok(result)
     }
 
@@ -119,6 +129,7 @@ impl XaiService for DefaultXaiService {
     ) -> Result<AuthorizationStarted, AdminError> {
         let pending = pending_authorization(
             self.accounts.as_ref(),
+            self.proxies.as_ref(),
             self.provider.provider_kind(),
             &command,
             "xAI credential",
@@ -132,9 +143,10 @@ impl XaiService for DefaultXaiService {
 
     async fn complete_authorization(
         &self,
-        command: CompleteAuthorization,
+        mut command: CompleteAuthorization,
     ) -> Result<CredentialMutationResult, AdminError> {
         let context = command.context.clone();
+        let settings = command.settings.take();
         let prepared = self
             .provider
             .complete_authorization(command)
@@ -150,11 +162,19 @@ impl XaiService for DefaultXaiService {
         let result = commit_authorization(
             self.accounts.as_ref(),
             prepared,
+            settings,
             &context,
             "xAI authorization",
         )
         .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            std::slice::from_ref(&result.account_id),
+            &context.request_id,
+        )
+        .await?;
         Ok(result)
     }
 

backend/crates/gateway-admin/tests/backup/task.rs

@@ -10,7 +10,7 @@ use gateway_admin::{
     },
     ports::backup::{BackupRepository, DatabaseDumpPort, DumpRequest},
 };
-use gateway_core::engine::CancellationToken;
+use gateway_core::lifecycle::CancellationToken;
 
 use super::support::{
     DUMP_CONTENT, FakeBackupRepository, FakeDumpPort, FakeObjectStore, backup_id,

backend/crates/gateway-admin/tests/main.rs

@@ -1,11 +1,12 @@
 use std::str::FromStr as _;
 
 use chrono::{TimeDelta, Utc};
-use gateway_core::engine::credential::OpaqueProviderData;
+use gateway_core::account::OpaqueProviderData;
 
 use gateway_admin::{
     model::{
         PageSize, Revision,
+        accounts::AccountUsage,
         auth::LoginCommand,
         client_keys::ClientKeyPageSize,
         observability::{DecimalAmount, RequestOutcome, TimeRange},
@@ -120,6 +121,7 @@ fn provider_document_debug_should_not_expose_opaque_material() {
 #[test]
 fn representative_quota_should_prefer_short_window_and_highest_usage() {
     let quota = ProviderQuota {
+        plan_type: None,
         observed_at: None,
         refresh_token_expires_at: None,
         windows: vec![
@@ -135,6 +137,119 @@ fn representative_quota_should_prefer_short_window_and_highest_usage() {
     assert_eq!(quota.representative_used_percent(), Some(45.0));
 }
 
+#[test]
+fn representative_quota_should_prefer_account_wide_window_over_model_specific_window() {
+    let mut model_specific = quota_window("shortTerm", Some(18_000), Some(64.0));
+    model_specific.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable;
+    let quota = ProviderQuota {
+        plan_type: None,
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![
+            model_specific,
+            quota_window("shortTerm", Some(604_800), Some(5.0)),
+        ],
+        limit_reached: false,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_used_percent(), Some(5.0));
+}
+
+#[test]
+fn usage_window_should_not_use_daily_rolling_usage_for_weekly_statistics() {
+    let usage = AccountUsage {
+        account_id: "acct_xai".to_owned(),
+        request_count: 5,
+        success_count: 5,
+        input_tokens: Some(100),
+        output_tokens: Some(20),
+        cached_tokens: Some(80),
+        cache_write_tokens: Some(0),
+        reasoning_tokens: Some(0),
+        image_input_tokens: Some(0),
+        image_output_tokens: Some(0),
+        image_request_count: 0,
+        image_request_failed_count: 0,
+        total_tokens: Some(120),
+        cost_coverage: Default::default(),
+        costs: Vec::new(),
+        last_used_at: Some(Utc::now()),
+        request_buckets: Vec::new(),
+        models: Vec::new(),
+    };
+    let quota = ProviderQuota {
+        plan_type: None,
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![ProviderQuotaWindow {
+            key: "free-rolling-24h".to_owned(),
+            group: "shortTerm".to_owned(),
+            label: "日限额".to_owned(),
+            limit_id: None,
+            limit_name: None,
+            role: None,
+            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+            window_seconds: Some(86_400),
+            used_percent: None,
+            reset_at: None,
+            limit_reached: false,
+            local_usage: Some(usage),
+            provider_data: None,
+        }],
+        limit_reached: false,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.usage_window(), None);
+}
+
+#[test]
+fn exhausted_quota_should_project_full_usage_to_only_the_representative_window() {
+    let mut quota = ProviderQuota {
+        plan_type: None,
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![
+            quota_window("monthly", Some(2_592_000), Some(99.0)),
+            quota_window("shortTerm", Some(604_800), Some(80.0)),
+            quota_window("shortTerm", Some(18_000), Some(30.0)),
+            quota_window("shortTerm", Some(14_400), Some(95.0)),
+        ],
+        limit_reached: true,
+        provider_data: None,
+    };
+
+    assert_eq!(quota.representative_used_percent(), Some(100.0));
+    quota.apply_limit_reached_display();
+
+    assert_eq!(quota.windows[0].used_percent, Some(99.0));
+    assert_eq!(quota.windows[1].used_percent, Some(80.0));
+    assert_eq!(quota.windows[2].used_percent, Some(30.0));
+    assert_eq!(quota.windows[3].used_percent, Some(100.0));
+    assert!(quota.windows[3].limit_reached);
+}
+
+#[test]
+fn exhausted_quota_should_preserve_the_provider_identified_reached_window() {
+    let mut reached = quota_window("monthly", Some(2_592_000), Some(98.0));
+    reached.limit_reached = true;
+    let mut quota = ProviderQuota {
+        plan_type: None,
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: vec![reached, quota_window("shortTerm", Some(18_000), Some(95.0))],
+        limit_reached: true,
+        provider_data: None,
+    };
+
+    quota.apply_limit_reached_display();
+
+    assert_eq!(quota.windows[0].used_percent, Some(100.0));
+    assert_eq!(quota.windows[1].used_percent, Some(95.0));
+    assert!(!quota.windows[1].limit_reached);
+}
+
 fn quota_window(
     group: &str,
     window_seconds: Option<u64>,
@@ -144,7 +259,9 @@ fn quota_window(
         key: group.to_owned(),
         group: group.to_owned(),
         label: group.to_owned(),
-        source: None,
+        limit_id: None,
+        limit_name: None,
+        role: None,
         local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
         window_seconds,
         used_percent,

backend/crates/gateway-admin/tests/model/backup/mod.rs

@@ -1,4 +1,4 @@
-//! 备份领域模型（model/backup.rs）的纯逻辑测试。
+//! 备份领域模型（model/backup）的纯逻辑测试。
 
 use chrono::{TimeZone as _, Utc};
 use secrecy::SecretString;

backend/crates/gateway-admin/tests/model/mod.rs

@@ -1,3 +1,6 @@
 //! 模型模块测试：镜像 src/model/ 中带逻辑的模块。
 
 mod backup;
+mod provider_credentials;
+mod quota_forecast;
+mod quota_forecast_sampling;

backend/crates/gateway-admin/tests/model/provider_credentials.rs

@@ -0,0 +1,272 @@
+use gateway_admin::model::provider_credentials::{
+    AccountUsagePeriod, AuthorizationMutationTarget, AuthorizationOwnerBinding,
+    PendingAuthorizationMutation, ProviderQuota, ProviderQuotaWindow, ProviderQuotaWindowRole,
+    QuotaLocalUsageAttribution,
+};
+use gateway_admin::model::{MutationActor, MutationContext};
+use gateway_core::account::ProviderAccountId;
+use gateway_core::routing::ProviderKind;
+use serde_json::{Value, json};
+
+#[test]
+fn usage_window_should_prefer_weekly_without_changing_dashboard_selection() {
+    let quota = usage_quota(vec![
+        usage_window("short", "shortTerm", 18_000),
+        usage_window("month", "monthly", 30 * 86_400),
+        usage_window("week", "shortTerm", 7 * 86_400),
+    ]);
+
+    assert_eq!(
+        selected_usage_window(&quota),
+        Some(("week", AccountUsagePeriod::Weekly))
+    );
+    assert_eq!(
+        quota
+            .representative_window()
+            .map(|window| window.key.as_str()),
+        Some("short")
+    );
+}
+
+#[test]
+fn usage_window_should_use_monthly_when_weekly_is_unavailable() {
+    let mut model_week = usage_window("model-week", "shortTerm", 7 * 86_400);
+    model_week.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable;
+    let mut incomplete_week = usage_window("incomplete-week", "shortTerm", 7 * 86_400);
+    incomplete_week.reset_at = None;
+    let mut unknown_usage = usage_window("unknown-week", "shortTerm", 7 * 86_400);
+    unknown_usage.local_usage = None;
+    let quota = usage_quota(vec![
+        model_week,
+        incomplete_week,
+        unknown_usage,
+        usage_window("month", "monthly", 30 * 86_400),
+    ]);
+
+    assert_eq!(
+        selected_usage_window(&quota),
+        Some(("month", AccountUsagePeriod::Monthly))
+    );
+}
+
+#[test]
+fn usage_window_should_not_fallback_to_short_daily_or_incomplete_windows() {
+    let mut missing_duration = usage_window("unknown-month", "monthly", 30 * 86_400);
+    missing_duration.window_seconds = None;
+    let quota = usage_quota(vec![
+        usage_window("short", "shortTerm", 18_000),
+        usage_window("day", "shortTerm", 86_400),
+        usage_window("invalid-month", "monthly", 86_400),
+        missing_duration,
+    ]);
+
+    assert_eq!(quota.usage_window(), None);
+}
+
+#[test]
+fn usage_window_should_preserve_provider_order_for_equal_periods() {
+    let quota = usage_quota(vec![
+        usage_window("first-week", "shortTerm", 7 * 86_400),
+        usage_window("second-week", "shortTerm", 7 * 86_400),
+    ]);
+
+    assert_eq!(
+        selected_usage_window(&quota),
+        Some(("first-week", AccountUsagePeriod::Weekly))
+    );
+}
+
+fn selected_usage_window(quota: &ProviderQuota) -> Option<(&str, AccountUsagePeriod)> {
+    quota
+        .usage_window()
+        .map(|(window, period)| (window.key.as_str(), period))
+}
+
+fn usage_quota(windows: Vec<ProviderQuotaWindow>) -> ProviderQuota {
+    ProviderQuota {
+        plan_type: None,
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows,
+        limit_reached: false,
+        provider_data: None,
+    }
+}
+
+fn usage_window(key: &str, group: &str, seconds: u64) -> ProviderQuotaWindow {
+    ProviderQuotaWindow {
+        key: key.to_owned(),
+        group: group.to_owned(),
+        label: key.to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: None,
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(seconds),
+        used_percent: Some(50.0),
+        reset_at: Some(chrono::Utc::now()),
+        limit_reached: false,
+        local_usage: Some(gateway_admin::model::accounts::AccountUsage {
+            account_id: "acct_test".to_owned(),
+            request_count: 0,
+            success_count: 0,
+            input_tokens: None,
+            output_tokens: None,
+            cached_tokens: None,
+            cache_write_tokens: None,
+            reasoning_tokens: None,
+            image_input_tokens: None,
+            image_output_tokens: None,
+            image_request_count: 0,
+            image_request_failed_count: 0,
+            total_tokens: None,
+            cost_coverage: Default::default(),
+            costs: Vec::new(),
+            last_used_at: None,
+            request_buckets: Vec::new(),
+            models: Vec::new(),
+        }),
+        provider_data: None,
+    }
+}
+
+#[test]
+fn dashboard_quota_should_preserve_unknown_and_actual_window_facts() {
+    let mut quota = ProviderQuota {
+        plan_type: None,
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows: Vec::new(),
+        limit_reached: false,
+        provider_data: None,
+    };
+    assert!(quota.representative_window().is_none());
+    assert!(quota.representative_used_percent().is_none());
+
+    let rolling = ProviderQuotaWindow {
+        key: "provider_rolling".to_owned(),
+        group: "requests".to_owned(),
+        label: "Provider rolling window".to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: Some(ProviderQuotaWindowRole::Primary),
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(86_400),
+        used_percent: None,
+        reset_at: None,
+        limit_reached: false,
+        local_usage: None,
+        provider_data: None,
+    };
+    quota.windows.push(rolling.clone());
+    assert_eq!(quota.representative_window(), Some(&rolling));
+    assert!(quota.representative_used_percent().is_none());
+
+    quota.windows[0].used_percent = Some(99.6);
+    quota.apply_limit_reached_display();
+    let actual = quota.representative_window().expect("actual window");
+    assert_eq!(actual.used_percent, Some(99.6));
+    assert!(
+        !actual.limit_reached,
+        "display rounding cannot exhaust quota"
+    );
+    assert_eq!(actual.window_seconds, Some(86_400));
+    assert_eq!(actual.reset_at, None);
+
+    quota.windows.insert(
+        0,
+        ProviderQuotaWindow {
+            key: "model_specific".to_owned(),
+            used_percent: Some(100.0),
+            local_usage_attribution: QuotaLocalUsageAttribution::Unavailable,
+            ..rolling
+        },
+    );
+    assert_eq!(
+        quota
+            .representative_window()
+            .map(|window| window.key.as_str()),
+        Some("provider_rolling")
+    );
+}
+
+#[test]
+fn pending_mutation_v1_should_round_trip_all_targets_and_owners() {
+    for provider in ["openai", "xai"] {
+        for target in [
+            AuthorizationMutationTarget::Create {
+                name: "account".to_owned(),
+            },
+            AuthorizationMutationTarget::Reauthorize {
+                account_id: ProviderAccountId::new("acct_1").expect("account id"),
+            },
+        ] {
+            for actor in [
+                MutationActor::AdminSession {
+                    admin_user_id: "admin-1".to_owned(),
+                },
+                MutationActor::AdminApiKey,
+                MutationActor::System,
+            ] {
+                let expected = PendingAuthorizationMutation::new(
+                    ProviderKind::new(provider).expect("provider"),
+                    target.clone(),
+                    AuthorizationOwnerBinding::from_context(&MutationContext {
+                        actor,
+                        request_id: "request-1".to_owned(),
+                    }),
+                );
+                assert_eq!(
+                    PendingAuthorizationMutation::from_storage_v1(Value::Object(
+                        expected.to_storage_v1()
+                    )),
+                    Ok(expected.clone()),
+                );
+                let with_proxy = expected
+                    .with_outbound_proxy(Some(
+                        gateway_core::account::OutboundProxy::parse(
+                            "http://user:secret@proxy.example:8080",
+                        )
+                        .unwrap(),
+                    ))
+                    .with_outbound_proxy_id(Some("proxy_saved".to_owned()));
+                assert_eq!(
+                    PendingAuthorizationMutation::from_storage_v1(Value::Object(
+                        with_proxy.to_storage_v1()
+                    )),
+                    Ok(with_proxy)
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn pending_mutation_v1_should_keep_existing_storage_fields_and_reject_invalid_documents() {
+    let legacy = json!({
+        "provider_kind": "openai",
+        "target": { "kind": "reauthorize", "account_id": "acct_1" },
+        "owner": { "kind": "admin_session", "admin_user_id": "admin-1" },
+        "started_request_id": "request-1"
+    });
+    let restored =
+        PendingAuthorizationMutation::from_storage_v1(legacy.clone()).expect("v1 document");
+    assert_eq!(Value::Object(restored.to_storage_v1()), legacy);
+    for (pointer, invalid) in [
+        ("/provider_kind", json!("")),
+        ("/target/account_id", json!("")),
+        ("/target/kind", json!("other")),
+        ("/owner/kind", json!("other")),
+        ("/started_request_id", json!(null)),
+    ] {
+        let mut document = legacy.clone();
+        *document.pointer_mut(pointer).expect("field") = invalid;
+        assert!(
+            PendingAuthorizationMutation::from_storage_v1(document).is_err(),
+            "{pointer}"
+        );
+    }
+    let mut document = legacy;
+    document["schema_version"] = json!(2);
+    assert!(PendingAuthorizationMutation::from_storage_v1(document).is_err());
+}

backend/crates/gateway-admin/tests/model/quota_forecast.rs

@@ -0,0 +1,323 @@
+use chrono::{DateTime, Duration, Utc};
+use gateway_admin::model::{
+    accounts::{AccountCost, AccountUsage},
+    observability::CostCoverage,
+    provider_credentials::{ProviderQuota, ProviderQuotaWindow, QuotaLocalUsageAttribution},
+    quota_forecast::{AccountQuotaForecast, account_quota_forecasts},
+    quota_forecast_sampling::{QuotaForecastMethod, QuotaForecastSample, QuotaForecastUsage},
+};
+
+fn now() -> DateTime<Utc> {
+    "2026-09-12T00:00:00Z".parse().unwrap()
+}
+
+fn window(key: &str, days: u64) -> ProviderQuotaWindow {
+    ProviderQuotaWindow {
+        key: key.to_owned(),
+        group: if days > 7 { "monthly" } else { "shortTerm" }.to_owned(),
+        label: key.to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: None,
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(days * 86_400),
+        used_percent: Some(20.0),
+        reset_at: Some(now() + Duration::days(1)),
+        limit_reached: false,
+        local_usage: Some(AccountUsage {
+            account_id: "acct_forecast".to_owned(),
+            request_count: 10,
+            success_count: 10,
+            input_tokens: Some(900),
+            output_tokens: Some(100),
+            cached_tokens: Some(800),
+            cache_write_tokens: None,
+            reasoning_tokens: None,
+            image_input_tokens: None,
+            image_output_tokens: None,
+            image_request_count: 0,
+            image_request_failed_count: 0,
+            total_tokens: Some(1_000),
+            cost_coverage: CostCoverage {
+                calculated_count: 10,
+                ..Default::default()
+            },
+            costs: vec![AccountCost {
+                currency: "USD".to_owned(),
+                amount: "2".parse().unwrap(),
+            }],
+            last_used_at: Some(now()),
+            request_buckets: Vec::new(),
+            models: Vec::new(),
+        }),
+        provider_data: None,
+    }
+}
+
+fn quota(windows: Vec<ProviderQuotaWindow>) -> ProviderQuota {
+    ProviderQuota {
+        plan_type: None,
+        observed_at: Some(now()),
+        refresh_token_expires_at: None,
+        windows,
+        limit_reached: false,
+        provider_data: None,
+    }
+}
+
+fn forecast(quota: &ProviderQuota) -> [AccountQuotaForecast; 2] {
+    account_quota_forecasts(quota, now() - Duration::days(60), now(), &samples(quota))
+}
+
+fn samples(quota: &ProviderQuota) -> Vec<QuotaForecastSample> {
+    quota
+        .windows
+        .iter()
+        .filter_map(|window| {
+            let usage = window.local_usage.as_ref()?;
+            let usd = usage.costs.iter().find(|cost| cost.currency == "USD");
+            Some(QuotaForecastSample {
+                key: window.key.clone(),
+                method: QuotaForecastMethod::Cumulative,
+                start_at: window.reset_at?.checked_sub_signed(Duration::try_seconds(
+                    i64::try_from(window.window_seconds?).ok()?,
+                )?)?,
+                end_at: quota.observed_at.unwrap_or(now()),
+                baseline_percent: 0.0,
+                sampled_percent: window.used_percent.unwrap_or(0.0),
+                block_count: 0,
+                observation_count: 0,
+                pending_request_count: 0,
+                discontinuous: false,
+                usage: QuotaForecastUsage {
+                    request_count: usage.request_count,
+                    tokens: usage.total_tokens.unwrap_or(0),
+                    input_tokens: usage.input_tokens.unwrap_or(0),
+                    output_tokens: usage.output_tokens.unwrap_or(0),
+                    cached_tokens: usage.cached_tokens.unwrap_or(0),
+                    missing_token_count: u64::from(usage.total_tokens.is_none()),
+                    known_cost_count: if usd.is_some() {
+                        usage.cost_coverage.known_count()
+                    } else {
+                        0
+                    },
+                    unavailable_cost_count: usage.cost_coverage.partial_count
+                        + usage.cost_coverage.unavailable_count,
+                    usd: usd.map_or(0.0, |cost| cost.amount.as_str().parse().unwrap()),
+                    excluded_request_count: 0,
+                },
+            })
+        })
+        .collect()
+}
+
+#[test]
+fn forecasts_use_actual_periods_and_do_not_extrapolate_remaining_capacity() {
+    let [week, month] = forecast(&quota(vec![window("week", 7)]));
+    assert_eq!(week.estimated_tokens, Some(5_000));
+    assert_eq!(week.estimated_usd, Some(10.0));
+    assert_eq!(week.remaining_tokens, Some(4_000));
+    assert_eq!(week.remaining_usd, Some(8.0));
+    assert!(!week.extrapolated);
+    assert!(month.extrapolated);
+    assert_eq!(month.estimated_tokens, Some(21_429));
+    assert!((month.estimated_usd.unwrap() - 10.0 * 30.0 / 7.0).abs() < 1e-10);
+    assert_eq!(month.remaining_tokens, week.remaining_tokens);
+    assert_eq!(month.remaining_usd, week.remaining_usd);
+}
+
+#[test]
+fn corresponding_actual_window_takes_priority_and_retains_its_duration() {
+    let [week, month] = forecast(&quota(vec![window("month", 31), window("week", 7)]));
+    assert_eq!(week.source.unwrap().label, "week");
+    assert_eq!(month.source.unwrap().label, "month");
+    assert!(!month.extrapolated);
+    assert_eq!(month.target_seconds, 31 * 86_400);
+    assert_eq!(month.estimated_tokens, Some(5_000));
+    let [week, _] = forecast(&quota(vec![window("month", 31)]));
+    assert!(week.extrapolated);
+    assert_eq!(week.estimated_tokens, Some(1_129));
+}
+
+#[test]
+fn short_or_model_specific_windows_are_not_account_capacity() {
+    let mut model = window("model", 7);
+    model.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable;
+    for item in forecast(&quota(vec![window("day", 1), model])) {
+        assert!(item.source.is_none());
+        assert!(item.unavailable_reason.is_some());
+        assert!(item.estimated_tokens.is_none());
+    }
+}
+
+#[test]
+fn invalid_or_tiny_percentages_cannot_produce_estimates() {
+    for percent in [
+        None,
+        Some(f64::NAN),
+        Some(f64::INFINITY),
+        Some(-1.0),
+        Some(101.0),
+        Some(0.0),
+        Some(0.5),
+        Some(1.0),
+        Some(4.9),
+    ] {
+        let mut sample = window("week", 7);
+        sample.used_percent = percent;
+        let [week, _] = forecast(&quota(vec![sample]));
+        assert!(week.unavailable_reason.is_some(), "{percent:?}");
+        assert!(week.estimated_tokens.is_none());
+        assert!(week.estimated_usd.is_none());
+    }
+}
+
+#[test]
+fn low_samples_warn_and_exhaustion_uses_raw_not_display_percentages() {
+    let mut sample = window("week", 7);
+    sample.used_percent = Some(5.0);
+    sample.limit_reached = true;
+    let mut source = quota(vec![sample]);
+    source.limit_reached = true;
+    let [week, _] = forecast(&source);
+    assert!(week.low_sample);
+    assert_eq!(week.estimated_tokens, Some(20_000));
+    source.windows[0].used_percent = Some(100.0);
+    let [week, _] = forecast(&source);
+    assert!(!week.low_sample);
+    assert_eq!(week.remaining_tokens, Some(0));
+    assert_eq!(week.remaining_usd, Some(0.0));
+}
+
+#[test]
+fn stale_future_or_missing_snapshots_do_not_predict() {
+    for observed in [
+        None,
+        Some(now() - Duration::days(8)),
+        Some(now() + Duration::seconds(1)),
+    ] {
+        let mut source = quota(vec![window("week", 7)]);
+        source.observed_at = observed;
+        assert!(forecast(&source)[0].unavailable_reason.is_some());
+    }
+    let mut sample = window("week", 7);
+    sample.reset_at = Some(now());
+    assert!(
+        forecast(&quota(vec![sample]))[0]
+            .unavailable_reason
+            .is_some()
+    );
+}
+
+#[test]
+fn partial_account_history_or_missing_usage_keep_diagnostics_without_estimates() {
+    let source = quota(vec![window("week", 7)]);
+    let [week, _] =
+        account_quota_forecasts(&source, now() - Duration::days(1), now(), &samples(&source));
+    assert!(week.unavailable_reason.unwrap().contains("记录不完整"));
+    assert!(week.estimated_tokens.is_none());
+    let mut sample = window("week", 7);
+    sample.local_usage = None;
+    let [week, _] = forecast(&quota(vec![sample]));
+    assert!(week.source.is_some());
+    assert!(
+        week.unavailable_reason
+            .unwrap()
+            .contains("没有网关用量记录")
+    );
+}
+
+#[test]
+fn incremental_sample_supports_mid_cycle_accounts_and_remaining_uses_current_percent() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    sample.method = QuotaForecastMethod::Incremental;
+    sample.start_at = now() - Duration::hours(6);
+    sample.baseline_percent = 10.0;
+    sample.sampled_percent = 10.0;
+    sample.block_count = 2;
+    let [week, month] =
+        account_quota_forecasts(&source, now() - Duration::days(1), now(), &[sample]);
+    assert_eq!(week.estimated_tokens, Some(10_000));
+    assert_eq!(week.remaining_tokens, Some(8_000));
+    assert_eq!(month.remaining_tokens, Some(8_000));
+    assert!(week.unavailable_reason.is_none());
+    assert!(!week.low_sample);
+}
+
+#[test]
+fn missing_tokens_suppress_token_estimates_without_discarding_complete_costs() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    sample.usage.missing_token_count = 1;
+    let [week, _] = account_quota_forecasts(&source, now() - Duration::days(60), now(), &[sample]);
+    assert!(week.incomplete_tokens);
+    assert_eq!(week.estimated_tokens, None);
+    assert_eq!(week.remaining_tokens, None);
+    assert_eq!(week.estimated_usd, Some(10.0));
+    assert_eq!(week.source.unwrap().tokens, Some(1_000));
+}
+
+#[test]
+fn discontinuous_samples_never_fall_back_to_cumulative_predictions() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    sample.discontinuous = true;
+    let [week, _] = account_quota_forecasts(&source, now() - Duration::days(60), now(), &[sample]);
+    assert!(week.unavailable_reason.unwrap().contains("不连续"));
+    assert!(week.estimated_tokens.is_none());
+}
+
+#[test]
+fn partial_or_unknown_costs_suppress_only_money_estimates() {
+    for coverage in [
+        CostCoverage {
+            calculated_count: 9,
+            partial_count: 1,
+            ..Default::default()
+        },
+        CostCoverage {
+            calculated_count: 9,
+            unavailable_count: 1,
+            ..Default::default()
+        },
+        CostCoverage::default(),
+    ] {
+        let mut sample = window("week", 7);
+        sample.local_usage.as_mut().unwrap().cost_coverage = coverage;
+        let [week, _] = forecast(&quota(vec![sample]));
+        assert!(week.incomplete_cost);
+        assert!(week.unavailable_reason.is_none());
+        assert!(week.estimated_usd.is_none());
+        assert!(week.remaining_usd.is_none());
+        assert_eq!(week.estimated_tokens, Some(5_000));
+    }
+}
+
+#[test]
+fn zero_known_cost_is_valid_but_missing_usd_is_not_invented() {
+    let mut sample = window("week", 7);
+    sample.local_usage.as_mut().unwrap().costs[0].amount = "0".parse().unwrap();
+    assert_eq!(
+        forecast(&quota(vec![sample.clone()]))[0].estimated_usd,
+        Some(0.0)
+    );
+    sample.local_usage.as_mut().unwrap().costs[0].currency = "EUR".to_owned();
+    assert_eq!(forecast(&quota(vec![sample]))[0].estimated_usd, None);
+}
+
+#[test]
+fn oversized_window_or_estimate_is_unavailable_without_panics_or_saturation() {
+    let mut sample = window("month", 30);
+    sample.window_seconds = Some(i64::MAX as u64);
+    assert!(
+        forecast(&quota(vec![sample]))[1]
+            .unavailable_reason
+            .is_some()
+    );
+    let mut sample = window("week", 7);
+    sample.local_usage.as_mut().unwrap().total_tokens = Some(u64::MAX);
+    let [week, _] = forecast(&quota(vec![sample]));
+    assert!(week.estimated_tokens.is_none());
+    assert_eq!(week.estimated_usd, Some(10.0));
+}

backend/crates/gateway-admin/tests/model/quota_forecast_sampling.rs

@@ -0,0 +1,124 @@
+use chrono::{DateTime, Duration, Utc};
+use gateway_admin::model::quota_forecast_sampling::{
+    QuotaForecastMethod, QuotaForecastPoint, QuotaForecastSample, QuotaForecastUsage,
+    select_forecast_sample,
+};
+
+fn time(minutes: i64) -> DateTime<Utc> {
+    "2026-09-12T00:00:00Z".parse::<DateTime<Utc>>().unwrap() + Duration::minutes(minutes)
+}
+
+fn point(minute: i64, percent: f64, tokens: u64) -> QuotaForecastPoint {
+    QuotaForecastPoint {
+        observed_at: time(minute),
+        used_percent: percent,
+        usage: QuotaForecastUsage {
+            request_count: minute as u64,
+            tokens,
+            input_tokens: tokens,
+            known_cost_count: minute as u64,
+            usd: tokens as f64 / 1_000.0,
+            ..Default::default()
+        },
+    }
+}
+
+fn select(points: Vec<QuotaForecastPoint>, current: QuotaForecastPoint) -> QuotaForecastSample {
+    select_forecast_sample("week".to_owned(), time(0), current, points, 2)
+}
+
+#[test]
+fn repeated_readings_do_not_make_independent_blocks_or_shift_the_baseline() {
+    let points = (1..100)
+        .map(|minute| point(minute, 20.0, minute as u64 * 100))
+        .collect();
+    let sample = select(points, point(100, 25.0, 10_000));
+    assert_eq!(sample.method, QuotaForecastMethod::Incremental);
+    assert_eq!(sample.block_count, 1);
+    assert_eq!(sample.start_at, time(1));
+    assert_eq!(sample.sampled_percent, 5.0);
+    assert_eq!(sample.usage.tokens, 9_900);
+    assert_eq!(sample.pending_request_count, 2);
+}
+
+#[test]
+fn recent_blocks_and_tail_replace_old_workload_without_averaging_individual_ratios() {
+    let points = vec![
+        point(1, 0.0, 0),
+        point(2, 5.0, 100),
+        point(3, 10.0, 200),
+        point(4, 15.0, 400),
+        point(5, 20.0, 600),
+        point(6, 25.0, 800),
+    ];
+    let sample = select(points, point(7, 27.0, 900));
+    assert_eq!(sample.baseline_percent, 10.0);
+    assert_eq!(sample.sampled_percent, 17.0);
+    assert_eq!(sample.usage.tokens, 700);
+    assert_eq!(sample.block_count, 3);
+}
+
+#[test]
+fn snapshot_at_a_block_boundary_keeps_only_three_recent_blocks() {
+    let points = (0..6)
+        .map(|i| point(i + 1, i as f64 * 5.0, i as u64 * 100))
+        .collect();
+    let sample = select(points, point(7, 30.0, 600));
+    assert_eq!(sample.baseline_percent, 15.0);
+    assert_eq!(sample.sampled_percent, 15.0);
+    assert_eq!(sample.usage.tokens, 300);
+}
+
+#[test]
+fn large_percentage_reversal_restarts_sampling_without_crossing_old_consumption() {
+    let sample = select(
+        vec![point(1, 40.0, 100), point(2, 50.0, 200), point(3, 1.0, 210)],
+        point(4, 8.0, 280),
+    );
+    assert_eq!(sample.baseline_percent, 1.0);
+    assert_eq!(sample.usage.tokens, 70);
+    assert_eq!(sample.sampled_percent, 7.0);
+    assert!(!sample.discontinuous);
+    let waiting = select(
+        vec![point(1, 40.0, 100), point(2, 50.0, 200)],
+        point(3, 2.0, 210),
+    );
+    assert!(waiting.discontinuous);
+}
+
+#[test]
+fn one_point_reversal_is_skipped_without_counting_an_extra_block() {
+    let sample = select(
+        vec![
+            point(1, 10.0, 100),
+            point(2, 15.0, 200),
+            point(3, 14.0, 210),
+        ],
+        point(4, 20.0, 300),
+    );
+    assert_eq!(sample.block_count, 2);
+    assert_eq!(sample.usage.tokens, 200);
+    assert!(!sample.discontinuous);
+}
+
+#[test]
+fn missing_token_and_cost_counts_are_local_to_the_selected_interval() {
+    let mut baseline = point(1, 30.0, 1_000);
+    baseline.usage.missing_token_count = 2;
+    baseline.usage.unavailable_cost_count = 3;
+    let mut end = point(3, 40.0, 2_000);
+    end.usage.missing_token_count = 2;
+    end.usage.unavailable_cost_count = 4;
+    let sample = select(vec![baseline], end);
+    assert_eq!(sample.usage.missing_token_count, 0);
+    assert_eq!(sample.usage.unavailable_cost_count, 1);
+}
+
+#[test]
+fn counter_regressions_fail_closed_and_future_points_are_not_used() {
+    let invalid = select(vec![point(1, 10.0, 1_000)], point(2, 20.0, 500));
+    assert!(invalid.discontinuous);
+    let future = select(vec![point(10, 1.0, 1)], point(2, 20.0, 500));
+    assert_eq!(future.method, QuotaForecastMethod::Cumulative);
+    assert_eq!(future.observation_count, 0);
+}

backend/crates/gateway-admin/tests/use_case/account_groups.rs

@@ -0,0 +1,236 @@
+use std::{
+    collections::BTreeMap,
+    str::FromStr as _,
+    sync::{Arc, Mutex},
+};
+
+use async_trait::async_trait;
+use chrono::{Duration, Utc};
+use gateway_admin::{
+    model::{
+        MutationContext, PageSize, Revision,
+        account_groups::{
+            AccountGroupAccountSummary, AccountGroupCapacity, AccountGroupColor,
+            AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+            AccountGroupRecord, AccountGroupUsage, DeleteAccountGroup, NewAccountGroup,
+            SetAccountGroupEnabled, UpdateAccountGroup,
+        },
+        accounts::AccountRuntimeSnapshot,
+        observability::DecimalAmount,
+    },
+    ports::store::{
+        AccountGroupStore, AccountRuntimeStore, AdminStoreError, AdminStoreErrorKind,
+        AdminStoreResult,
+    },
+};
+use gateway_core::{
+    account::{AccountStatusFacts, CredentialState, QuotaState},
+    routing::AccountGroupId,
+};
+
+use super::AdminHarness;
+
+const GROUP_ID: &str = "grp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+#[tokio::test]
+async fn group_query_service_enriches_only_current_page_members_with_runtime_facts() {
+    let groups = Arc::new(FakeGroupStore::default());
+    let runtime = Arc::new(FakeRuntimeStore::default());
+    let service = AdminHarness::new()
+        .account_groups(groups.clone())
+        .account_runtime(runtime.clone())
+        .build()
+        .await;
+
+    let page = service
+        .account_groups()
+        .list(AccountGroupListQuery {
+            page: 1,
+            page_size: PageSize::new(20).expect("page size"),
+            search: None,
+            enabled: None,
+        })
+        .await
+        .expect("list projected account groups");
+
+    assert_eq!(
+        groups
+            .requested_groups
+            .lock()
+            .expect("requested groups")
+            .as_slice(),
+        [GROUP_ID]
+    );
+    assert_eq!(
+        runtime
+            .requested_accounts
+            .lock()
+            .expect("requested accounts")
+            .as_slice(),
+        ["acct_available", "acct_limited"]
+    );
+    let group = &page.items[0];
+    assert_eq!(
+        group.account_summary,
+        AccountGroupAccountSummary {
+            available: 1,
+            limited: 1,
+            total: 2,
+        }
+    );
+    assert_eq!(
+        group.capacity,
+        AccountGroupCapacity {
+            used_slots: Some(2),
+            total_slots: 4,
+        }
+    );
+}
+
+#[derive(Default)]
+struct FakeGroupStore {
+    requested_groups: Mutex<Vec<String>>,
+}
+
+#[async_trait]
+impl AccountGroupStore for FakeGroupStore {
+    async fn list_account_groups(
+        &self,
+        query: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupPage> {
+        Ok(AccountGroupPage {
+            config_revision: Revision::new(1).expect("revision"),
+            items: vec![group_record()],
+            total: 1,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+
+    async fn load_account_group_members(
+        &self,
+        group_ids: &[AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>> {
+        *self.requested_groups.lock().expect("requested groups") = group_ids
+            .iter()
+            .map(|group_id| group_id.as_str().to_owned())
+            .collect();
+        Ok(vec![member("acct_available", 4), member("acct_limited", 3)])
+    }
+
+    async fn create_account_group(
+        &self,
+        _: NewAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn update_account_group(
+        &self,
+        _: UpdateAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn set_account_group_enabled(
+        &self,
+        _: SetAccountGroupEnabled,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+
+    async fn delete_account_group(
+        &self,
+        _: DeleteAccountGroup,
+        _: &MutationContext,
+    ) -> AdminStoreResult<AccountGroupMutation> {
+        Err(unused())
+    }
+}
+
+#[derive(Default)]
+struct FakeRuntimeStore {
+    requested_accounts: Mutex<Vec<String>>,
+}
+
+#[async_trait]
+impl AccountRuntimeStore for FakeRuntimeStore {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+
+    async fn account_runtime(
+        &self,
+        account_ids: &[String],
+    ) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        *self.requested_accounts.lock().expect("requested accounts") = account_ids.to_vec();
+        Ok(AccountRuntimeSnapshot {
+            rate_limited_until: BTreeMap::from([(
+                "acct_limited".to_owned(),
+                Utc::now() + Duration::minutes(5),
+            )]),
+            in_flight: Some(BTreeMap::from([("acct_available".to_owned(), 2)])),
+        })
+    }
+}
+
+fn group_record() -> AccountGroupRecord {
+    let now = Utc::now();
+    AccountGroupRecord {
+        id: group_id(),
+        name: "Primary".to_owned(),
+        description: None,
+        color: AccountGroupColor::parse("#2563EBFF").expect("color"),
+        enabled: true,
+        member_count: 2,
+        provider_counts: BTreeMap::from([("openai".to_owned(), 2)]),
+        client_key_count: 1,
+        account_summary: AccountGroupAccountSummary {
+            available: 0,
+            limited: 0,
+            total: 0,
+        },
+        capacity: AccountGroupCapacity {
+            used_slots: None,
+            total_slots: 0,
+        },
+        usage: AccountGroupUsage {
+            today_usd: DecimalAmount::from_str("1").expect("today usage"),
+            retained_total_usd: DecimalAmount::from_str("3").expect("retained usage"),
+        },
+        created_at: now,
+        updated_at: now,
+    }
+}
+
+fn member(account_id: &str, total_slots: u64) -> AccountGroupMemberFact {
+    AccountGroupMemberFact {
+        group_id: group_id(),
+        account_id: account_id.to_owned(),
+        status: AccountStatusFacts {
+            enabled: true,
+            credential_state: CredentialState::Ready,
+            access_token_expires_at: None,
+            quota: QuotaState::default(),
+            rate_limited_until: None,
+            last_error_reason: None,
+            last_error_message: None,
+        },
+        total_slots,
+    }
+}
+
+fn group_id() -> AccountGroupId {
+    AccountGroupId::new(GROUP_ID).expect("group ID")
+}
+
+fn unused() -> AdminStoreError {
+    AdminStoreError::new(
+        AdminStoreErrorKind::Unavailable,
+        "account group",
+        "unused test operation",
+    )
+}

backend/crates/gateway-admin/tests/use_case/client_keys.rs

@@ -1,22 +1,31 @@
+use std::sync::{Arc, Mutex};
+
 use async_trait::async_trait;
-use gateway_core::policy::ClientApiKeyId;
+use chrono::Utc;
+use gateway_core::policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits};
 
 use gateway_admin::{
     model::{
-        AdminErrorKind, MutationContext, Revision,
+        AdminErrorKind, MutationActor, MutationContext, Revision,
         client_keys::{
             ClientKeyCursor, ClientKeyCursorValue, ClientKeyListQuery, ClientKeyPage,
             ClientKeyPageSize, ClientKeyRecord, ClientKeySecret, ClientKeySort, ClientKeySortField,
-            DeleteClientKey, NewClientKey, SetClientKeyEnabled, SortDirection, UpdateClientKey,
+            CreateClientKey, DeleteClientKey, NewClientKey, SetClientKeyEnabled, SortDirection,
+            UpdateClientKey,
         },
     },
     ports::store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult, ClientKeyStore},
 };
 
-struct UnusedClientKeyStore;
+#[derive(Default)]
+struct TestClientKeyStore {
+    plaintexts: Mutex<Vec<String>>,
+    create_error: Option<AdminStoreErrorKind>,
+    update_error: Option<AdminStoreErrorKind>,
+}
 
 #[async_trait]
-impl ClientKeyStore for UnusedClientKeyStore {
+impl ClientKeyStore for TestClientKeyStore {
     async fn list_client_keys(&self, query: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
         assert_eq!(query.page_size.get(), u16::MAX);
         Ok(ClientKeyPage {
@@ -36,10 +45,32 @@ impl ClientKeyStore for UnusedClientKeyStore {
 
     async fn create_client_key(
         &self,
-        _: NewClientKey,
+        key: NewClientKey,
         _: &MutationContext,
     ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
-        Err(unused())
+        if let Some(kind) = self.create_error {
+            return Err(AdminStoreError::new(
+                kind,
+                "client key",
+                "test create failure",
+            ));
+        }
+        self.plaintexts.lock().unwrap().push(key.plaintext);
+        let record = ClientKeyRecord {
+            id: key.id,
+            name: key.name,
+            label: key.label,
+            groups: Vec::new(),
+            provider_kinds: Vec::new(),
+            prefix: String::new(),
+            enabled: true,
+            limits: key.limits,
+            budget: Default::default(),
+            last_used_at: None,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        };
+        Ok((Revision::new(2).unwrap(), record))
     }
 
     async fn update_client_key(
@@ -47,6 +78,13 @@ impl ClientKeyStore for UnusedClientKeyStore {
         _: UpdateClientKey,
         _: &MutationContext,
     ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        if let Some(kind) = self.update_error {
+            return Err(AdminStoreError::new(
+                kind,
+                "client key",
+                "test update failure",
+            ));
+        }
         Err(unused())
     }
 
@@ -70,7 +108,7 @@ impl ClientKeyStore for UnusedClientKeyStore {
 #[tokio::test]
 async fn client_key_cursor_should_reject_value_that_does_not_match_sort() {
     let services = super::AdminHarness::new()
-        .client_keys(std::sync::Arc::new(UnusedClientKeyStore))
+        .client_keys(Arc::new(TestClientKeyStore::default()))
         .build()
         .await;
     let sort = ClientKeySort {
@@ -98,7 +136,7 @@ async fn client_key_cursor_should_reject_value_that_does_not_match_sort() {
 #[tokio::test]
 async fn client_key_list_should_forward_the_full_nonzero_u16_page_size() {
     let services = super::AdminHarness::new()
-        .client_keys(std::sync::Arc::new(UnusedClientKeyStore))
+        .client_keys(Arc::new(TestClientKeyStore::default()))
         .build()
         .await;
     let page = services
@@ -118,6 +156,105 @@ async fn client_key_list_should_forward_the_full_nonzero_u16_page_size() {
     assert_eq!(page.total, 0);
 }
 
+#[tokio::test]
+async fn create_preserves_migrated_keys_and_keeps_default_generation() {
+    let store = Arc::new(TestClientKeyStore::default());
+    let services = super::AdminHarness::new()
+        .client_keys(store.clone())
+        .build()
+        .await;
+    for value in [Some("q".to_owned()), Some("legacy+/=:!".repeat(1024)), None] {
+        let created = services
+            .client_keys()
+            .create(&mutation_context(), create_command(value.as_deref()))
+            .await
+            .unwrap();
+        let plaintext = created.secret.expose_for_response();
+        assert_eq!(store.plaintexts.lock().unwrap().last().unwrap(), plaintext);
+        if let Some(value) = value {
+            assert_eq!(plaintext, value);
+        } else {
+            assert!(plaintext.starts_with("sk_"));
+            assert_eq!(plaintext.len(), 46);
+        }
+    }
+}
+
+#[tokio::test]
+async fn duplicate_keys_return_actionable_conflicts_without_disclosing_the_key() {
+    let services = super::AdminHarness::new()
+        .client_keys(Arc::new(TestClientKeyStore {
+            create_error: Some(AdminStoreErrorKind::Conflict),
+            ..Default::default()
+        }))
+        .build()
+        .await;
+    let key = "legacy-duplicate-must-stay-private";
+    let error = services
+        .client_keys()
+        .create(&mutation_context(), create_command(Some(key)))
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert_eq!(error.message(), "API Key 已存在，请使用其他密钥");
+    assert!(!format!("{error:?}").contains(key));
+}
+
+#[tokio::test]
+async fn duplicate_names_report_the_same_actionable_conflict_on_create_and_update() {
+    let services = super::AdminHarness::new()
+        .client_keys(Arc::new(TestClientKeyStore {
+            create_error: Some(AdminStoreErrorKind::DuplicateName),
+            update_error: Some(AdminStoreErrorKind::DuplicateName),
+            ..Default::default()
+        }))
+        .build()
+        .await;
+    let created = services
+        .client_keys()
+        .create(&mutation_context(), create_command(None))
+        .await
+        .unwrap_err();
+    let updated = services
+        .client_keys()
+        .update(
+            &mutation_context(),
+            UpdateClientKey {
+                id: ClientApiKeyId::new("key_existing").unwrap(),
+                name: "Migration".to_owned(),
+                label: None,
+                group_ids: Vec::new(),
+                limits: RateLimits::unlimited(),
+                daily_limit_usd: None,
+                weekly_limit_usd: None,
+            },
+        )
+        .await
+        .unwrap_err();
+    for error in [created, updated] {
+        assert_eq!(error.kind(), AdminErrorKind::Conflict);
+        assert_eq!(error.message(), "名称已存在");
+    }
+}
+
+fn create_command(key: Option<&str>) -> CreateClientKey {
+    CreateClientKey {
+        custom_key: key.map(|value| PlaintextClientApiKey::new(value).unwrap()),
+        name: "Migration".to_owned(),
+        label: None,
+        group_ids: Vec::new(),
+        limits: RateLimits::unlimited(),
+        budget: Default::default(),
+    }
+}
+
+fn mutation_context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "custom-key-test".to_owned(),
+    }
+}
+
 fn unused() -> AdminStoreError {
     AdminStoreError::new(
         AdminStoreErrorKind::Unavailable,

backend/crates/gateway-admin/tests/use_case/mod.rs

@@ -1,9 +1,11 @@
+mod account_groups;
 mod accounts;
 mod auth;
 mod backup;
 mod client_keys;
 mod observability;
 mod openai;
+mod proxies;
 mod settings;
 mod system;
 mod xai;
@@ -21,15 +23,16 @@ use gateway_admin::{
     model::{
         MutationContext, Revision,
         account_groups::{
-            AccountGroupListQuery, AccountGroupMutation, AccountGroupPage, DeleteAccountGroup,
-            NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
+            AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation, AccountGroupPage,
+            DeleteAccountGroup, NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
         },
         accounts::{
-            AccountListQuery, AccountPage, AccountUpdateResult, AccountUsage,
-            AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
+            AccountListQuery, AccountPage, AccountRuntimeSnapshot, AccountUpdateResult,
+            AccountUsage, AccountUsageWindowQuery, AccountUsageWindowResult, AccountsUpdateResult,
             BatchUpdateAccounts, DeleteAccounts, UpdateAccount,
         },
         auth::{AdminAuditEvent, AdminSession},
+        client_distribution::CodexDesktopWindowsDownloads,
         client_keys::{
             ClientKeyListQuery, ClientKeyPage, ClientKeyRecord, ClientKeySecret, DeleteClientKey,
             NewClientKey, SetClientKeyEnabled, UpdateClientKey,
@@ -42,22 +45,23 @@ use gateway_admin::{
         },
         provider_credentials::{
             AuthorizationCommit, AuthorizationStarted, CompleteAuthorization, CredentialDetails,
-            CredentialImportCommit, CredentialImportResult, CredentialListQuery,
-            CredentialMutationResult, CredentialPage, CredentialRotationCommit,
-            PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
-            PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
-            PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput,
-            ProviderModels, ProviderQuota,
+            CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
+            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
+            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
+            PreparedCredentialImport, PreparedCredentialRotation, ProviderExport,
+            ProviderExportCredentialInput, ProviderModels, ProviderQuota,
         },
         settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
         system::{SystemOperationAccepted, SystemUpdateDetail, SystemUpdateStatus, SystemVersion},
     },
     ports::{
         backup::BackupStorePorts,
+        client_distribution::ClientDistributionResolver,
         provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind},
         store::{
-            AccountGroupStore, AccountStore, AdminStoreError, AdminStoreErrorKind, AdminStorePorts,
-            AdminStoreResult, AuthStore, ClientKeyStore, ObservabilityStore, SettingsStore,
+            AccountGroupStore, AccountRuntimeStore, AccountStore, AdminAccountStorePorts,
+            AdminStoreError, AdminStoreErrorKind, AdminStorePorts, AdminStoreResult, AuthStore,
+            ClientKeyStore, ObservabilityStore, SettingsStore,
         },
         system::{
             SystemOperationError, SystemOperationErrorKind, SystemOperations,
@@ -66,19 +70,21 @@ use gateway_admin::{
     },
 };
 use gateway_core::{
-    engine::{
-        credential::ProviderAccountId,
-        probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
-    },
+    account::ProviderAccountId,
+    engine::probe::{AccountProbe, AccountProbeError, AccountProbeRequest, AccountProbeResult},
     error::{GatewayError, GatewayErrorKind},
     policy::ClientApiKeyId,
-    routing::{ConfigRevision, ProviderKind, snapshot::SnapshotControl},
+    routing::{ConfigRevision, ProviderKind},
+    runtime::SnapshotControl,
 };
 
 pub(super) struct AdminHarness {
     default_password: String,
     session_ttl_minutes: u64,
     accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn gateway_admin::ports::proxy::ProxyStore>,
+    account_runtime: Arc<dyn AccountRuntimeStore>,
+    account_groups: Arc<dyn AccountGroupStore>,
     auth: Arc<dyn AuthStore>,
     client_keys: Arc<dyn ClientKeyStore>,
     observability: Arc<dyn ObservabilityStore>,
@@ -96,6 +102,9 @@ impl AdminHarness {
             default_password: "strong-test-password".to_owned(),
             session_ttl_minutes: 60,
             accounts: unavailable.clone(),
+            proxies: Arc::new(proxies::TestProxies::default()),
+            account_runtime: unavailable.clone(),
+            account_groups: Arc::new(UnavailableAccountGroupStore),
             auth: Arc::new(BootstrapAuthStore::default()),
             client_keys: unavailable.clone(),
             observability: unavailable.clone(),
@@ -125,6 +134,16 @@ impl AdminHarness {
         self
     }
 
+    pub(super) fn account_runtime(mut self, store: Arc<dyn AccountRuntimeStore>) -> Self {
+        self.account_runtime = store;
+        self
+    }
+
+    pub(super) fn account_groups(mut self, store: Arc<dyn AccountGroupStore>) -> Self {
+        self.account_groups = store;
+        self
+    }
+
     pub(super) fn auth(mut self, store: Arc<dyn AuthStore>) -> Self {
         self.auth = store;
         self
@@ -162,6 +181,14 @@ impl AdminHarness {
         self
     }
 
+    pub(super) fn proxies(
+        mut self,
+        proxies: Arc<dyn gateway_admin::ports::proxy::ProxyStore>,
+    ) -> Self {
+        self.proxies = proxies;
+        self
+    }
+
     pub(super) fn system(mut self, system: Arc<dyn SystemOperations>) -> Self {
         self.system = system;
         self
@@ -175,8 +202,12 @@ impl AdminHarness {
                 default_password: InitialAdminPassword::new(self.default_password),
             },
             AdminStorePorts::new(
-                self.accounts,
-                Arc::new(UnavailableAccountGroupStore),
+                AdminAccountStorePorts::new(
+                    self.accounts,
+                    self.account_runtime,
+                    self.account_groups,
+                    self.proxies,
+                ),
                 self.auth,
                 self.client_keys,
                 self.observability,
@@ -185,7 +216,8 @@ impl AdminHarness {
             ),
             self.providers,
             Arc::new(NoopSnapshot),
-            self.probe,
+            (self.probe, Arc::new(proxies::TestProxies::default())),
+            Arc::new(NoopClientDistribution),
             self.system,
         )
         .await
@@ -194,6 +226,20 @@ impl AdminHarness {
     }
 }
 
+struct NoopClientDistribution;
+
+#[async_trait]
+impl ClientDistributionResolver for NoopClientDistribution {
+    async fn resolve_codex_desktop_windows(&self, _: bool) -> CodexDesktopWindowsDownloads {
+        CodexDesktopWindowsDownloads {
+            resolved_at: Utc::now(),
+            cached: false,
+            warning: None,
+            packages: Vec::new(),
+        }
+    }
+}
+
 #[derive(Default)]
 struct BootstrapAuthStore {
     password_hash: Mutex<Option<String>>,
@@ -252,6 +298,13 @@ impl AccountGroupStore for UnavailableAccountGroupStore {
         Err(unavailable("account groups"))
     }
 
+    async fn load_account_group_members(
+        &self,
+        _: &[gateway_core::routing::AccountGroupId],
+    ) -> AdminStoreResult<Vec<AccountGroupMemberFact>> {
+        Err(unavailable("account group members"))
+    }
+
     async fn create_account_group(
         &self,
         _: NewAccountGroup,
@@ -287,13 +340,18 @@ impl AccountGroupStore for UnavailableAccountGroupStore {
 
 #[async_trait]
 impl AccountStore for UnavailableStore {
-    async fn list_accounts(&self, _: AccountListQuery) -> AdminStoreResult<AccountPage> {
+    async fn list_accounts(
+        &self,
+        _: AccountListQuery,
+        _: AccountRuntimeSnapshot,
+    ) -> AdminStoreResult<AccountPage> {
         Err(unavailable("accounts"))
     }
 
     async fn load_account(
         &self,
         _: &str,
+        _: AccountRuntimeSnapshot,
     ) -> AdminStoreResult<Option<gateway_admin::model::accounts::AccountPageItem>> {
         Err(unavailable("account"))
     }
@@ -313,12 +371,11 @@ impl AccountStore for UnavailableStore {
         Err(unavailable("account quota window usage"))
     }
 
-    async fn list_credentials(
+    async fn load_quota_forecast_history(
         &self,
-        _: &ProviderKind,
-        _: CredentialListQuery,
-    ) -> AdminStoreResult<CredentialPage> {
-        Err(unavailable("credentials"))
+        _: &AccountUsageWindowQuery,
+    ) -> AdminStoreResult<gateway_admin::model::quota_forecast_sampling::QuotaForecastHistory> {
+        Err(unavailable("quota forecast history"))
     }
 
     async fn credential_details(
@@ -410,6 +467,17 @@ impl AccountStore for UnavailableStore {
     }
 }
 
+#[async_trait]
+impl AccountRuntimeStore for UnavailableStore {
+    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+
+    async fn account_runtime(&self, _: &[String]) -> AdminStoreResult<AccountRuntimeSnapshot> {
+        Ok(AccountRuntimeSnapshot::default())
+    }
+}
+
 #[async_trait]
 impl ClientKeyStore for UnavailableStore {
     async fn list_client_keys(&self, _: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
@@ -478,13 +546,14 @@ impl ObservabilityStore for UnavailableStore {
         Err(unavailable("usage trend"))
     }
 
-    async fn usage_calculated_billing_facts(
+    fn usage_calculated_billing_facts(
         &self,
         _: TimeRange,
         _: UsageFilter,
-    ) -> AdminStoreResult<Vec<gateway_admin::model::observability::UsageCalculatedBillingFact>>
-    {
-        Err(unavailable("usage billing facts"))
+    ) -> gateway_admin::ports::store::UsageCalculatedBillingStream<'_> {
+        Box::pin(futures::stream::once(async {
+            Err(unavailable("usage billing facts"))
+        }))
     }
 
     async fn list_usage_records(&self, _: UsageQuery) -> AdminStoreResult<UsagePage> {

backend/crates/gateway-admin/tests/use_case/observability.rs

@@ -1,7 +1,10 @@
 use std::{
-    num::NonZeroU32,
     str::FromStr as _,
-    sync::{Arc, Mutex},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, AtomicUsize, Ordering},
+    },
+    time::Duration as StdDuration,
 };
 
 use async_trait::async_trait;
@@ -14,10 +17,10 @@ use gateway_admin::{
         observability::{
             AccountPoolMetrics, AttemptMetrics, CostCoverage, CurrencyCost, DashboardObservation,
             DashboardRuntimeSlots, DiagnosticDimension, DiagnosticObservation, Granularity,
-            HealthStatus, OpsErrorPage, OpsErrorQuery, PageNumber, RequestMetricPoint,
-            RequestMetrics, RequestOutcome, TimeRange, TrendKind, UsageBilling,
-            UsageCalculatedBillingFact, UsageDetail, UsageFilter, UsageOverview, UsagePage,
-            UsageQuery, UsageRecord, china_day_start,
+            HealthStatus, LatencyPercentiles, OpsErrorPage, OpsErrorQuery, PercentileMilliseconds,
+            RequestMetricPoint, RequestMetrics, TimeRange, TrendKind, UsageBilling,
+            UsageCalculatedBillingFact, UsageDetail, UsageFilter, UsageListRecord, UsageOverview,
+            UsagePage, UsageQuery, china_day_start,
         },
         settings::{
             AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RotationStrategy,
@@ -105,6 +108,40 @@ async fn health_timeline_should_keep_exactly_china_day_quarter_hour_slots() {
     }));
 }
 
+#[tokio::test]
+async fn dashboard_summary_should_derive_first_token_average_from_trend() {
+    let now = Utc::now();
+    let current_slot = quarter_hour_start(now);
+    let store = Arc::new(FixtureObservabilityStore::new(observation_range(now)));
+    store.replace_trend(vec![
+        health_metric_point(
+            current_slot - Duration::minutes(15),
+            RequestMetrics {
+                first_token_latency_sum_ms: 120,
+                first_token_latency_count: 2,
+                ..RequestMetrics::default()
+            },
+        ),
+        health_metric_point(
+            current_slot,
+            RequestMetrics {
+                first_token_latency_sum_ms: 180,
+                first_token_latency_count: 1,
+                ..RequestMetrics::default()
+            },
+        ),
+    ]);
+    let services = observability_services(store).await;
+
+    let summary = services
+        .observability()
+        .dashboard_summary(observation_range(now), TrendKind::Usage)
+        .await
+        .expect("dashboard summary");
+
+    assert_eq!(summary.average_first_token_latency_ms, Some(100));
+}
+
 #[tokio::test]
 async fn health_timeline_should_match_legacy_status_precedence_and_thresholds() {
     let now = Utc::now();
@@ -160,11 +197,15 @@ async fn health_timeline_should_match_legacy_status_precedence_and_thresholds()
         ),
     ];
 
-    for (metrics, expected_status, expected_reliability) in fixtures {
+    for (index, (metrics, expected_status, expected_reliability)) in
+        fixtures.into_iter().enumerate()
+    {
         store.replace_trend(vec![health_metric_point(current_slot, metrics)]);
+        let range_end =
+            now + Duration::seconds(i64::try_from(index).expect("fixture index fits i64") * 2);
         let timeline = services
             .observability()
-            .dashboard_summary(observation_range(now), TrendKind::Usage)
+            .dashboard_summary(observation_range(range_end), TrendKind::Usage)
             .await
             .expect("dashboard summary")
             .health_timeline;
@@ -220,6 +261,53 @@ async fn dashboard_summary_should_share_one_current_observation_time_across_runt
     assert!(summary_observed_at.is_some_and(|value| value > historical_end));
 }
 
+#[tokio::test]
+async fn dashboard_summary_should_coalesce_concurrent_requests_in_one_short_window() {
+    let end_bucket = Utc::now().timestamp().div_euclid(2) * 2;
+    let first_end = DateTime::from_timestamp(end_bucket, 100_000_000).expect("first end");
+    let second_end = DateTime::from_timestamp(end_bucket, 900_000_000).expect("second end");
+    let first_range = TimeRange::new(china_day_start(first_end), first_end).expect("first range");
+    let second_range =
+        TimeRange::new(china_day_start(second_end), second_end).expect("second range");
+    let store = Arc::new(FixtureObservabilityStore::new(first_range));
+    store.set_dashboard_delay(StdDuration::from_millis(20));
+    let services = observability_services(store.clone()).await;
+    let observability = services.observability();
+
+    let (first, second) = tokio::join!(
+        observability.dashboard_summary(first_range, TrendKind::Usage),
+        observability.dashboard_summary(second_range, TrendKind::Errors),
+    );
+
+    first.expect("first dashboard summary");
+    second.expect("second dashboard summary");
+    assert_eq!(store.dashboard_summary_calls(), 1);
+}
+
+#[tokio::test]
+async fn dashboard_summary_should_reload_after_the_short_window_changes() {
+    let end_bucket = Utc::now().timestamp().div_euclid(2) * 2;
+    let first_end = DateTime::from_timestamp(end_bucket, 100_000_000).expect("first end");
+    let second_end = first_end + Duration::seconds(2);
+    let first_range = TimeRange::new(china_day_start(first_end), first_end).expect("first range");
+    let second_range =
+        TimeRange::new(china_day_start(second_end), second_end).expect("second range");
+    let store = Arc::new(FixtureObservabilityStore::new(first_range));
+    let services = observability_services(store.clone()).await;
+    let observability = services.observability();
+
+    observability
+        .dashboard_summary(first_range, TrendKind::Usage)
+        .await
+        .expect("first dashboard summary");
+    observability
+        .dashboard_summary(second_range, TrendKind::Usage)
+        .await
+        .expect("second dashboard summary");
+
+    assert_eq!(store.dashboard_summary_calls(), 2);
+}
+
 #[tokio::test]
 async fn observability_services_should_calculate_usage_insights_and_diagnostic_shares() {
     let now = Utc::now();
@@ -234,6 +322,24 @@ async fn observability_services_should_calculate_usage_insights_and_diagnostic_s
         output_tokens: 200,
         total_tokens: 1_000,
         latency_count: 5,
+        admission_decision_count: 10,
+        admission_decision_percentiles: LatencyPercentiles {
+            p50_ms: Some(PercentileMilliseconds::new(2.0).expect("admission P50")),
+            p95_ms: Some(PercentileMilliseconds::new(5.0).expect("admission P95")),
+            p99_ms: Some(PercentileMilliseconds::new(8.0).expect("admission P99")),
+        },
+        account_selection_wait_count: 8,
+        account_selection_wait_percentiles: LatencyPercentiles {
+            p50_ms: Some(PercentileMilliseconds::new(10.0).expect("selection P50")),
+            p95_ms: Some(PercentileMilliseconds::new(40.0).expect("selection P95")),
+            p99_ms: Some(PercentileMilliseconds::new(70.0).expect("selection P99")),
+        },
+        output_throughput_p10: Some(40),
+        output_throughput_p50: Some(50),
+        output_throughput_p90: Some(60),
+        capacity_sample_count: 8,
+        capacity_utilization_avg_basis_points: Some(6_500),
+        capacity_utilization_p95_basis_points: Some(8_000),
         ..RequestMetrics::default()
     };
     store.replace_overview(UsageOverview {
@@ -294,10 +400,16 @@ async fn observability_services_should_calculate_usage_insights_and_diagnostic_s
         .await
         .expect("usage diagnostics");
 
-    assert_eq!(insights.health.total_requests, 8);
+    assert_eq!(insights.health.total_requests, 10);
     assert_eq!(insights.health.failed_requests, 2);
+    assert_eq!(insights.health.success_rate, 0.75);
+    assert_eq!(insights.health.completion_rate, 1.0);
     assert_eq!(insights.granularity, Granularity::FifteenMinutes);
     assert_eq!(insights.performance.latency_coverage, 0.5);
+    assert_eq!(insights.performance.admission_decision_coverage, 1.0);
+    assert_eq!(insights.performance.account_selection_wait_coverage, 0.8);
+    assert_eq!(insights.performance.capacity_coverage, 0.8);
+    assert_eq!(insights.performance.output_throughput_p50, Some(50));
     assert_eq!(insights.cost.tokens_per_request, 100.0);
     assert_eq!(
         insights
@@ -337,8 +449,25 @@ async fn observability_services_should_calculate_usage_insights_and_diagnostic_s
             .map(gateway_admin::model::observability::DecimalAmount::as_str),
         Some("1")
     );
+    assert_eq!(
+        insights
+            .cost
+            .no_cache_cost
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("1.25")
+    );
+    assert_eq!(
+        insights
+            .cost
+            .tier_premium
+            .as_ref()
+            .map(gateway_admin::model::observability::DecimalAmount::as_str),
+        Some("0.25")
+    );
     assert_eq!(diagnostics.items[0].request_share, 0.75);
     assert_eq!(diagnostics.items[1].request_share, 0.25);
+    assert!((diagnostics.items[0].impact_score - 0.075).abs() < 1e-9);
 }
 
 #[tokio::test]
@@ -408,15 +537,48 @@ async fn usage_records_should_enrich_provider_reported_totals_when_pricing_match
     ));
 }
 
+#[tokio::test]
+async fn usage_insights_should_reject_partial_costs_when_billing_stream_fails() {
+    let now = Utc::now();
+    let range = observation_range(now);
+    let store = Arc::new(FixtureObservabilityStore::new(range));
+    store.replace_calculated_billing_facts(vec![UsageCalculatedBillingFact {
+        bucket_start: quarter_hour_start(now),
+        provider_kind: "openai".to_owned(),
+        upstream_model_id: "gpt-5.5".to_owned(),
+        service_tier: None,
+        input_tokens: Some(800),
+        output_tokens: Some(200),
+        cached_tokens: Some(0),
+        cache_write_tokens: Some(0),
+        total: CurrencyCost {
+            currency: "USD".to_owned(),
+            amount: "1.25".parse().expect("cost"),
+        },
+    }]);
+    store.billing_stream_fails.store(true, Ordering::SeqCst);
+    let services = observability_services_with_calculated_billing(store).await;
+    assert!(
+        services
+            .observability()
+            .usage_insights(range, UsageFilter::default())
+            .await
+            .is_err()
+    );
+}
+
 struct FixtureObservabilityStore {
     trend: Mutex<Vec<RequestMetricPoint>>,
     overview: Mutex<UsageOverview>,
     calculated_billing_facts: Mutex<Vec<UsageCalculatedBillingFact>>,
+    billing_stream_fails: AtomicBool,
     diagnostics: Mutex<Vec<DiagnosticObservation>>,
     runtime_slots: Mutex<Option<DashboardRuntimeSlots>>,
     summary_observed_at: Mutex<Option<DateTime<Utc>>>,
     slots_observed_at: Mutex<Option<DateTime<Utc>>>,
-    usage_records: Mutex<Vec<UsageRecord>>,
+    usage_records: Mutex<Vec<UsageListRecord>>,
+    dashboard_delay: Mutex<StdDuration>,
+    dashboard_summary_calls: AtomicUsize,
 }
 
 impl FixtureObservabilityStore {
@@ -430,14 +592,25 @@ impl FixtureObservabilityStore {
                 providers: Vec::new(),
             }),
             calculated_billing_facts: Mutex::new(Vec::new()),
+            billing_stream_fails: AtomicBool::new(false),
             diagnostics: Mutex::new(Vec::new()),
             runtime_slots: Mutex::new(None),
             summary_observed_at: Mutex::new(None),
             slots_observed_at: Mutex::new(None),
             usage_records: Mutex::new(Vec::new()),
+            dashboard_delay: Mutex::new(StdDuration::ZERO),
+            dashboard_summary_calls: AtomicUsize::new(0),
         }
     }
 
+    fn set_dashboard_delay(&self, delay: StdDuration) {
+        *self.dashboard_delay.lock().expect("dashboard delay") = delay;
+    }
+
+    fn dashboard_summary_calls(&self) -> usize {
+        self.dashboard_summary_calls.load(Ordering::Relaxed)
+    }
+
     fn replace_trend(&self, trend: Vec<RequestMetricPoint>) {
         *self.trend.lock().expect("trend") = trend;
     }
@@ -471,7 +644,7 @@ impl FixtureObservabilityStore {
         )
     }
 
-    fn replace_usage_records(&self, records: Vec<UsageRecord>) {
+    fn replace_usage_records(&self, records: Vec<UsageListRecord>) {
         *self.usage_records.lock().expect("usage records") = records;
     }
 }
@@ -483,14 +656,17 @@ impl ObservabilityStore for FixtureObservabilityStore {
         range: TimeRange,
         observed_at: DateTime<Utc>,
     ) -> AdminStoreResult<DashboardObservation> {
+        self.dashboard_summary_calls.fetch_add(1, Ordering::Relaxed);
         *self
             .summary_observed_at
             .lock()
             .expect("summary observed at") = Some(observed_at);
+        let dashboard_delay = *self.dashboard_delay.lock().expect("dashboard delay");
+        if !dashboard_delay.is_zero() {
+            tokio::time::sleep(dashboard_delay).await;
+        }
         Ok(DashboardObservation {
             range,
-            requests: RequestMetrics::default(),
-            attempts: AttemptMetrics::default(),
             totals: Default::default(),
             provider_accounts: AccountPoolMetrics::default(),
             trend: self.trend.lock().expect("trend").clone(),
@@ -519,25 +695,33 @@ impl ObservabilityStore for FixtureObservabilityStore {
         Ok(self.trend.lock().expect("trend").clone())
     }
 
-    async fn usage_calculated_billing_facts(
+    fn usage_calculated_billing_facts(
         &self,
         _: TimeRange,
         _: UsageFilter,
-    ) -> AdminStoreResult<Vec<UsageCalculatedBillingFact>> {
-        Ok(self
+    ) -> gateway_admin::ports::store::UsageCalculatedBillingStream<'_> {
+        let facts = self
             .calculated_billing_facts
             .lock()
             .expect("calculated billing facts")
-            .clone())
+            .clone();
+        let error = self
+            .billing_stream_fails
+            .load(Ordering::SeqCst)
+            .then(|| Err(super::unavailable("billing stream failed")));
+        Box::pin(futures::stream::iter(
+            facts.into_iter().map(Ok).chain(error),
+        ))
     }
 
-    async fn list_usage_records(&self, _: UsageQuery) -> AdminStoreResult<UsagePage> {
+    async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage> {
         let items = self.usage_records.lock().expect("usage records").clone();
         let total = u64::try_from(items.len()).unwrap_or(u64::MAX);
         Ok(UsagePage {
             items,
+            current_page: query.current_page,
+            page_size: query.page_size.get(),
             total,
-            next_cursor: None,
         })
     }
 
@@ -576,6 +760,8 @@ impl SettingsStore for FixtureSettingsStore {
             max_concurrent_per_account: 1,
             request_interval_ms: 0,
             rotation_strategy: RotationStrategy::Smart,
+            min_codex_desktop_version: None,
+            min_codex_cli_version: None,
             usage_retention_days: 31,
             ops_event_retention_days: 30,
             audit_retention_days: 30,
@@ -639,8 +825,7 @@ fn usage_query(now: DateTime<Utc>) -> UsageQuery {
     UsageQuery {
         range: observation_range(now),
         filter: UsageFilter::default(),
-        cursor: None,
-        page: PageNumber::new(NonZeroU32::new(1).expect("page number")),
+        current_page: 1,
         page_size: PageSize::new(50).expect("page size"),
     }
 }
@@ -650,19 +835,12 @@ fn total_record(
     provider_kind: Option<&str>,
     source: &str,
     now: DateTime<Utc>,
-) -> UsageRecord {
-    UsageRecord {
+) -> UsageListRecord {
+    UsageListRecord {
         id: id.to_owned(),
-        client_api_key_ref: "key_billing".to_owned(),
-        config_revision: 1,
-        routing_scope: "all".to_owned(),
-        routing_group_refs: Vec::new(),
-        routing_group_names_snapshot: Vec::new(),
-        protocol: "openai".to_owned(),
-        operation: "generate".to_owned(),
         endpoint: "/v1/responses".to_owned(),
         client_transport: "http_sse".to_owned(),
-        requested_model_id: "gpt-5.5".to_owned(),
+        requested_model_id: Some("gpt-5.5".to_owned()),
         provider_kind: provider_kind.map(str::to_owned),
         provider_account_ref: None,
         provider_account_name: None,
@@ -670,23 +848,7 @@ fn total_record(
         provider_account_authentication_kind: None,
         upstream_model_id: Some("gpt-5.5".to_owned()),
         upstream_transport: None,
-        http_version: None,
-        websocket_pool: None,
         service_tier: None,
-        provider_metadata_json: None,
-        attempt_count: 1,
-        upstream_send_state: "sent".to_owned(),
-        downstream_committed_at: None,
-        outcome: RequestOutcome::Succeeded,
-        client_status_code: Some(200),
-        upstream_status_code: Some(200),
-        client_response_id: None,
-        upstream_request_id: None,
-        upstream_response_id: None,
-        error_kind: None,
-        provider_error_code: None,
-        error_message: None,
-        retry_after_ms: None,
         input_tokens: Some(800),
         output_tokens: Some(200),
         cached_tokens: Some(0),
@@ -715,18 +877,17 @@ fn total_record(
         first_token_ms: None,
         provider_processing_ms: None,
         latency_ms: Some(100),
+        admission_decision_ms: None,
+        account_selection_wait_ms: None,
+        capacity_used_slots: None,
+        capacity_total_slots: None,
         client_ip: None,
         user_agent: None,
         reasoning_effort: None,
         reasoning_preset: None,
-        request_kind: None,
         subagent_kind: None,
         compact: false,
-        image_generation_requested: false,
-        image_generation_succeeded: None,
         started_at: now,
-        deadline_at: now,
-        completed_at: Some(now),
     }
 }
 
@@ -742,6 +903,9 @@ fn health_metric_point(bucket_start: DateTime<Utc>, metrics: RequestMetrics) ->
 
 fn diagnostic(name: &str, request_count: u64) -> DiagnosticObservation {
     DiagnosticObservation {
+        first_token_p95_ms: None,
+        non_completion_count: 0,
+        retry_count: 0,
         key: name.to_owned(),
         name: name.to_owned(),
         request_count,

backend/crates/gateway-admin/tests/use_case/openai.rs

@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use gateway_core::engine::credential::ProviderAccountId;
+use gateway_core::account::ProviderAccountId;
 
 use gateway_admin::{
     AdminServices,
@@ -50,13 +50,15 @@ async fn openai_import_should_prepare_before_atomic_store_commit() {
     services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: Some(super::accounts::import_settings()),
             context: context("import-openai"),
             document: document(),
         })
         .await
         .expect("import credential");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         recorded(&events),
@@ -75,9 +77,52 @@ async fn openai_import_should_prepare_before_atomic_store_commit() {
             rolling_usage: None,
         }]
     );
+    assert_eq!(
+        store.import_settings(),
+        [Some(super::accounts::import_settings())]
+    );
     assert_eq!(store.audit_requests(), ["import-openai"]);
 }
 
+#[tokio::test]
+async fn openai_import_should_expose_only_explicit_public_errors_without_committing() {
+    use gateway_admin::model::AdminErrorKind;
+
+    for (provider_kind, admin_kind) in [
+        (ProviderAdminErrorKind::Invalid, AdminErrorKind::Invalid),
+        (
+            ProviderAdminErrorKind::Unavailable,
+            AdminErrorKind::Unavailable,
+        ),
+        (
+            ProviderAdminErrorKind::BadGateway,
+            AdminErrorKind::BadGateway,
+        ),
+    ] {
+        let events = events();
+        let provider = FakeProviderAdmin::new("openai", events.clone());
+        provider
+            .fail_next_with_public_message(provider_kind, "Codex PAT 验证失败，请检查令牌后重试");
+        let store = FakeAccountStore::new("openai", events.clone());
+        let services = service(provider, store.clone()).await;
+        let error = services
+            .openai()
+            .import_document(ImportCredentials {
+                outbound_proxy_id: None,
+                settings: None,
+                context: context("import-openai-pat-failure"),
+                document: document(),
+            })
+            .await
+            .expect_err("validation must fail before committing accounts");
+        assert_eq!(error.kind(), admin_kind);
+        assert_eq!(error.to_string(), "Codex PAT 验证失败，请检查令牌后重试");
+        assert!(!format!("{error:?}").contains("secret token"));
+        assert_eq!(recorded(&events), ["provider.prepare_import"]);
+        assert!(store.audit_requests().is_empty());
+    }
+}
+
 #[tokio::test]
 async fn openai_import_should_refresh_quota_for_every_imported_account() {
     let events = events();
@@ -89,13 +134,15 @@ async fn openai_import_should_refresh_quota_for_every_imported_account() {
     let result = services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
             context: context("import-openai-batch"),
             document: document(),
         })
         .await
         .expect("import credentials");
 
-    await_quota_requests(&provider, 2).await;
+    provider.wait_for_quota_requests(2).await;
 
     assert_eq!(
         result.credential_ids,
@@ -132,13 +179,15 @@ async fn openai_import_should_remain_successful_when_quota_refresh_fails() {
     let result = services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
             context: context("import-openai-quota-failure"),
             document: document(),
         })
         .await
         .expect("committed import remains successful");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         result.credential_ids,
@@ -157,6 +206,7 @@ async fn openai_authorization_create_should_observe_initial_quota() {
     services
         .openai()
         .start_authorization(StartAuthorization {
+            outbound_proxy: None,
             context: context("oauth-start-openai-create"),
             name: "new OpenAI credential".to_owned(),
             reauthorization: None,
@@ -166,6 +216,7 @@ async fn openai_authorization_create_should_observe_initial_quota() {
     services
         .openai()
         .complete_authorization(CompleteAuthorization {
+            settings: Some(super::accounts::import_settings()),
             context: context("oauth-start-openai-create"),
             flow_id: "flow-test".to_owned(),
             callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
@@ -173,7 +224,7 @@ async fn openai_authorization_create_should_observe_initial_quota() {
         .await
         .expect("complete authorization");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         recorded(&events),
@@ -193,6 +244,10 @@ async fn openai_authorization_create_should_observe_initial_quota() {
             rolling_usage: None,
         }]
     );
+    assert_eq!(
+        store.import_settings(),
+        [Some(super::accounts::import_settings())]
+    );
     assert_eq!(store.audit_requests(), ["oauth-start-openai-create"]);
 }
 
@@ -207,6 +262,7 @@ async fn openai_authorization_create_should_remain_successful_when_initial_quota
     services
         .openai()
         .start_authorization(StartAuthorization {
+            outbound_proxy: None,
             context: context("oauth-start-openai-quota-failure"),
             name: "new OpenAI credential".to_owned(),
             reauthorization: None,
@@ -216,6 +272,7 @@ async fn openai_authorization_create_should_remain_successful_when_initial_quota
     let result = services
         .openai()
         .complete_authorization(CompleteAuthorization {
+            settings: None,
             context: context("oauth-start-openai-quota-failure"),
             flow_id: "flow-test".to_owned(),
             callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
@@ -223,7 +280,7 @@ async fn openai_authorization_create_should_remain_successful_when_initial_quota
         .await
         .expect("quota observation must not fail authorization");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(result.account_id.as_str(), "acct_prepared");
     assert_eq!(provider.quota_requests().len(), 1);
@@ -238,6 +295,7 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
     store.fail_next_commit();
     let services = service(provider.clone(), store).await;
     let command = || CompleteAuthorization {
+        settings: None,
         context: context("oauth-store-retry"),
         flow_id: "flow-test".to_owned(),
         callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
@@ -246,6 +304,7 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
     services
         .openai()
         .start_authorization(StartAuthorization {
+            outbound_proxy: None,
             context: context("oauth-store-retry"),
             name: "new OpenAI credential".to_owned(),
             reauthorization: None,
@@ -263,7 +322,7 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
         .await
         .expect("released claim must permit retry");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         recorded(&events),
@@ -293,6 +352,8 @@ async fn openai_import_provider_error_should_not_touch_store_transaction() {
     services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
             context: context("import-openai-error"),
             document: document(),
         })
@@ -311,6 +372,7 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
     services
         .openai()
         .start_authorization(StartAuthorization {
+            outbound_proxy: None,
             context: context("oauth-start-openai"),
             name: "reauthorize".to_owned(),
             reauthorization: Some(ProviderAccountId::new("acct_test").expect("account ID")),
@@ -336,6 +398,7 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
     let result = services
         .openai()
         .complete_authorization(CompleteAuthorization {
+            settings: None,
             context: context("oauth-complete-openai"),
             flow_id: "flow-test".to_owned(),
             callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
@@ -343,7 +406,7 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
         .await
         .expect("complete reauthorization");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(result.credential_revision, Some(revision(3)));
 
@@ -371,19 +434,40 @@ async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>)
         .await
 }
 
-async fn await_quota_requests(provider: &FakeProviderAdmin, expected: usize) {
-    for _ in 0..100 {
-        if provider.quota_requests().len() == expected {
-            return;
-        }
-        tokio::task::yield_now().await;
-    }
-    assert_eq!(provider.quota_requests().len(), expected);
-}
-
 fn deletion(account_id: &str) -> CredentialDeletion {
     CredentialDeletion {
         context: context("request-openai"),
         account_ids: vec![ProviderAccountId::new(account_id).expect("account ID")],
     }
 }
+
+#[tokio::test]
+async fn reauthorization_with_import_settings_releases_claim_without_committing() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = service(provider, store.clone()).await;
+    services
+        .openai()
+        .start_authorization(StartAuthorization {
+            outbound_proxy: None,
+            context: context("reauthorization-settings"),
+            name: "existing account".to_owned(),
+            reauthorization: Some(ProviderAccountId::new("acct_test").expect("account ID")),
+        })
+        .await
+        .expect("start reauthorization");
+    let error = services
+        .openai()
+        .complete_authorization(CompleteAuthorization {
+            settings: Some(super::accounts::import_settings()),
+            context: context("reauthorization-settings"),
+            flow_id: "flow-test".to_owned(),
+            callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+        })
+        .await
+        .expect_err("reauthorization must preserve settings");
+    assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::Invalid);
+    assert!(!recorded(&events).contains(&"store.commit_authorization"));
+    assert!(store.import_settings().is_empty());
+}

backend/crates/gateway-admin/tests/use_case/proxies.rs

@@ -0,0 +1,227 @@
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{MutationContext, Revision, proxies::*},
+    ports::{
+        proxy::{ProxyProbe, ProxyStore},
+        store::AdminStoreResult,
+    },
+};
+use gateway_core::account::{OutboundProxy, ProviderAccountId};
+
+#[derive(Default)]
+pub(super) struct TestProxies {
+    pub events: Option<super::accounts::EventLog>,
+    pub accounts: Option<Vec<ProxyAccountRef>>,
+}
+
+struct ImportGuard(super::accounts::EventLog);
+
+impl gateway_admin::ports::proxy::ProxyImportGuard for ImportGuard {}
+
+impl Drop for ImportGuard {
+    fn drop(&mut self) {
+        self.0.lock().unwrap().push("proxy.release");
+    }
+}
+
+#[async_trait]
+impl ProxyStore for TestProxies {
+    async fn remove_account(
+        &self,
+        _: &str,
+        _: &ProviderAccountId,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(super::unavailable("proxy"))
+    }
+
+    async fn reserve_import(
+        &self,
+        id: &str,
+    ) -> AdminStoreResult<gateway_admin::ports::proxy::ProxyImportReservation> {
+        let events = self
+            .events
+            .as_ref()
+            .ok_or_else(|| super::unavailable("proxy"))?;
+        events.lock().unwrap().push("proxy.reserve");
+        Ok(gateway_admin::ports::proxy::ProxyImportReservation {
+            binding: ImportProxyBinding {
+                id: id.to_owned(),
+                proxy: OutboundProxy::parse("http://127.0.0.1:8080").unwrap(),
+            },
+            guard: Box::new(ImportGuard(events.clone())),
+        })
+    }
+    async fn list(&self, _: ProxyListQuery) -> AdminStoreResult<ProxyPage> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> AdminStoreResult<ProxyAccountPage> {
+        let items = self
+            .accounts
+            .clone()
+            .ok_or_else(|| super::unavailable("proxy"))?;
+        Ok(ProxyAccountPage {
+            total: items.len() as u64,
+            items,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+    async fn get(&self, _: &str) -> AdminStoreResult<ProxyRecord> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn create(&self, _: NewProxy, _: &MutationContext) -> AdminStoreResult<ProxyMutation> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn update(&self, _: UpdateProxy, _: &MutationContext) -> AdminStoreResult<ProxyMutation> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn delete(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn record_test(
+        &self,
+        _: &str,
+        _: Revision,
+        _: ProxyTestResult,
+        _: &MutationContext,
+    ) -> AdminStoreResult<ProxyRecord> {
+        Err(super::unavailable("proxy"))
+    }
+}
+
+#[async_trait]
+impl ProxyProbe for TestProxies {
+    async fn test(&self, _: &OutboundProxy) -> ProxyTestResult {
+        panic!("unexpected proxy probe")
+    }
+}
+
+#[tokio::test]
+async fn linked_accounts_share_plan_resolution_and_only_read_cached_quota() {
+    use super::accounts::{FakeProviderAdmin, events};
+    use gateway_admin::model::{PageSize, provider_credentials::ProviderQuota};
+    use std::sync::Arc;
+
+    for (stored, cached, expected) in [
+        (None, Some("free"), Some("free")),
+        (Some("unknown"), Some("free"), Some("free")),
+        (Some("plus"), Some("free"), Some("plus")),
+        (None, None, None),
+    ] {
+        let provider = FakeProviderAdmin::new("openai", events());
+        provider.set_quota(ProviderQuota {
+            plan_type: cached.map(str::to_owned),
+            observed_at: None,
+            refresh_token_expires_at: None,
+            windows: vec![],
+            limit_reached: false,
+            provider_data: None,
+        });
+        let services = super::AdminHarness::new()
+            .provider(provider.clone())
+            .proxies(Arc::new(TestProxies {
+                accounts: Some(vec![ProxyAccountRef {
+                    id: "acct_plan".to_owned(),
+                    name: "套餐测试".to_owned(),
+                    email: None,
+                    provider_kind: "openai".to_owned(),
+                    authentication_kind: "oauth".to_owned(),
+                    plan_type: stored.map(str::to_owned),
+                    plan_type_display: None,
+                    groups: vec![],
+                    enabled: true,
+                }]),
+                ..Default::default()
+            }))
+            .build()
+            .await;
+        let result = services
+            .proxies()
+            .list_accounts(ProxyAccountListQuery {
+                proxy_id: "proxy_plan".to_owned(),
+                page: 1,
+                page_size: PageSize::new(20).unwrap(),
+                search: String::new(),
+            })
+            .await
+            .unwrap();
+        assert_eq!(result.items[0].plan_type.as_deref(), expected);
+        assert_eq!(
+            result.items[0].plan_type_display.as_deref(),
+            match expected {
+                Some("free") => Some("OpenaiDisplayFree"),
+                Some("plus") => Some("OpenaiDisplayPlus"),
+                _ => None,
+            }
+        );
+        let requests = provider.quota_requests();
+        assert_eq!(requests.len(), usize::from(stored != Some("plus")));
+        assert!(requests.iter().all(|request| !request.refresh));
+    }
+}
+
+#[tokio::test]
+async fn credential_import_keeps_proxy_reserved_until_commit_and_releases_on_errors() {
+    use super::accounts::{
+        FakeAccountStore, FakeProviderAdmin, context, document, events, recorded,
+    };
+    use gateway_admin::model::provider_credentials::ImportCredentials;
+    use gateway_admin::ports::provider::ProviderAdminErrorKind;
+    use std::sync::Arc;
+
+    for kind in ["openai", "xai"] {
+        for failure in [None, Some("prepare"), Some("commit")] {
+            let events = events();
+            let provider = FakeProviderAdmin::new(kind, events.clone());
+            let store = FakeAccountStore::new(kind, events.clone());
+            if failure == Some("prepare") {
+                provider.fail_next(ProviderAdminErrorKind::Unavailable);
+            }
+            if failure == Some("commit") {
+                store.fail_next_commit();
+            }
+            let services = super::AdminHarness::new()
+                .provider(provider)
+                .accounts(store)
+                .proxies(Arc::new(TestProxies {
+                    events: Some(events.clone()),
+                    ..Default::default()
+                }))
+                .build()
+                .await;
+            let command = ImportCredentials {
+                outbound_proxy_id: Some("proxy_import".to_owned()),
+                settings: None,
+                context: context("reserved-import"),
+                document: document(),
+            };
+            let result = if kind == "openai" {
+                services.openai().import_document(command).await
+            } else {
+                services.xai().import_document(command).await
+            };
+            assert_eq!(result.is_err(), failure.is_some());
+            let events = recorded(&events);
+            let expected = if failure == Some("prepare") {
+                vec!["proxy.reserve", "provider.prepare_import", "proxy.release"]
+            } else {
+                vec![
+                    "proxy.reserve",
+                    "provider.prepare_import",
+                    "store.commit_import",
+                    "proxy.release",
+                ]
+            };
+            assert_eq!(&events[..expected.len()], expected);
+        }
+    }
+}

backend/crates/gateway-admin/tests/use_case/settings.rs

@@ -67,6 +67,8 @@ async fn settings_should_reject_zero_refresh_margin_before_store_call() {
                 max_concurrent_per_account: 1,
                 request_interval_ms: 0,
                 rotation_strategy: RotationStrategy::Smart,
+                min_codex_desktop_version: None,
+                min_codex_cli_version: None,
                 usage_retention_days: 31,
                 ops_event_retention_days: 30,
                 audit_retention_days: 30,

backend/crates/gateway-admin/tests/use_case/xai.rs

@@ -1,10 +1,12 @@
 use std::sync::Arc;
 
-use gateway_core::engine::credential::ProviderAccountId;
+use gateway_core::account::ProviderAccountId;
 
 use gateway_admin::{
     AdminServices,
-    model::provider_credentials::{ImportCredentials, ProviderQuotaRequest},
+    model::provider_credentials::{
+        CompleteAuthorization, ImportCredentials, ProviderQuotaRequest, StartAuthorization,
+    },
     ports::provider::ProviderAdminErrorKind,
 };
 
@@ -20,17 +22,21 @@ async fn xai_import_should_prepare_before_atomic_store_commit() {
     services
         .xai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: Some(super::accounts::import_settings()),
             context: context("import-xai"),
             document: document(),
         })
         .await
         .expect("import xAI credential");
 
+    provider.wait_for_quota_requests(1).await;
     assert_eq!(
         recorded(&events),
         [
             "provider.prepare_import",
             "store.commit_import",
+            "provider.account_facts_changed",
             "provider.quota"
         ]
     );
@@ -42,6 +48,10 @@ async fn xai_import_should_prepare_before_atomic_store_commit() {
             rolling_usage: None,
         }]
     );
+    assert_eq!(
+        store.import_settings(),
+        [Some(super::accounts::import_settings())]
+    );
     assert_eq!(store.audit_requests(), ["import-xai"]);
 }
 
@@ -56,12 +66,15 @@ async fn xai_import_should_refresh_quota_for_every_imported_account() {
     services
         .xai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
             context: context("import-xai-batch"),
             document: document(),
         })
         .await
         .expect("import credentials");
 
+    provider.wait_for_quota_requests(2).await;
     assert_eq!(
         provider.quota_requests(),
         [
@@ -90,16 +103,128 @@ async fn xai_import_should_remain_successful_when_quota_refresh_fails() {
     let result = services
         .xai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
             context: context("import-xai-quota-failure"),
             document: document(),
         })
         .await
         .expect("committed import remains successful");
 
+    provider.wait_for_quota_requests(1).await;
     assert_eq!(result.credential_ids.len(), 1);
     assert_eq!(provider.quota_requests().len(), 1);
 }
 
+#[tokio::test]
+async fn xai_authorization_should_observe_quota_without_affecting_commit() {
+    for quota_failure in [None, Some(ProviderAdminErrorKind::Unavailable)] {
+        let events = events();
+        let provider = FakeProviderAdmin::new("xai", events.clone());
+        if let Some(kind) = quota_failure {
+            provider.fail_next_quota(kind);
+        }
+        let store = FakeAccountStore::new("xai", events.clone());
+        let services = service(provider.clone(), store.clone()).await;
+        services
+            .xai()
+            .start_authorization(StartAuthorization {
+                outbound_proxy: None,
+                context: context("oauth-xai-create"),
+                name: "new xAI credential".to_owned(),
+                reauthorization: None,
+            })
+            .await
+            .expect("start authorization");
+        let result = services
+            .xai()
+            .complete_authorization(CompleteAuthorization {
+                settings: None,
+                context: context("oauth-xai-create"),
+                flow_id: "flow-test".to_owned(),
+                callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+            })
+            .await
+            .expect("quota observation must not fail authorization");
+
+        provider.wait_for_quota_requests(1).await;
+        assert_eq!(
+            recorded(&events),
+            [
+                "provider.start_authorization",
+                "provider.complete_authorization",
+                "store.commit_authorization",
+                "provider.account_facts_changed",
+                "provider.quota",
+            ]
+        );
+        assert_eq!(
+            provider.quota_requests(),
+            [ProviderQuotaRequest {
+                account_id: result.account_id,
+                refresh: true,
+                rolling_usage: None,
+            }]
+        );
+        assert_eq!(store.audit_requests(), ["oauth-xai-create"]);
+    }
+}
+
+#[tokio::test]
+async fn credential_import_should_return_while_initial_quota_is_pending() {
+    for kind in ["openai", "xai"] {
+        let events = events();
+        let provider = FakeProviderAdmin::new(kind, events.clone());
+        let quota_release = provider.pause_next_quota();
+        let store = FakeAccountStore::new(kind, events);
+        let services = service(provider.clone(), store).await;
+        let command = ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
+            context: context("import-slow-quota"),
+            document: document(),
+        };
+        let result = tokio::time::timeout(std::time::Duration::from_secs(5), async {
+            match kind {
+                "openai" => services.openai().import_document(command).await,
+                _ => services.xai().import_document(command).await,
+            }
+        })
+        .await
+        .expect("committed import must not wait for quota")
+        .expect("import credentials");
+        provider.wait_for_quota_requests(1).await;
+        assert_eq!(result.credential_ids.len(), 1);
+        quota_release.send(()).expect("finish quota observation");
+    }
+}
+
+#[tokio::test]
+async fn xai_import_store_failure_should_not_observe_quota_or_invalidate_provider_facts() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("xai", events.clone());
+    let store = FakeAccountStore::new("xai", events.clone());
+    store.fail_next_commit();
+    let services = service(provider.clone(), store).await;
+
+    services
+        .xai()
+        .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
+            context: context("import-xai-store-failure"),
+            document: document(),
+        })
+        .await
+        .expect_err("store commit fails");
+
+    assert_eq!(
+        recorded(&events),
+        ["provider.prepare_import", "store.commit_import"]
+    );
+    assert!(provider.quota_requests().is_empty());
+}
+
 async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>) -> AdminServices {
     super::AdminHarness::new()
         .provider(provider)

backend/crates/gateway-api/Cargo.toml

@@ -2,7 +2,7 @@
 name = "gateway-api"
 version = "0.1.0"
 edition = "2024"
-license = "MIT"
+license = "Apache-2.0"
 publish = false
 rust-version = "1.97"
 autotests = false
@@ -16,6 +16,7 @@ axum = { version = "0.8.9", default-features = false, features = ["json", "query
 base64 = "0.23.0"
 bytes = "1.11.1"
 chrono = { version = "0.4.45", features = ["serde"] }
+flate2 = "1.1.9"
 futures = "0.3.32"
 gateway-admin = { path = "../gateway-admin" }
 gateway-core = { path = "../gateway-core" }
@@ -24,16 +25,17 @@ secrecy = "0.10"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
 thiserror = "2.0.18"
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "time"] }
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "sync", "time"] }
 tower-http = { version = "0.7.0", features = ["cors", "fs", "request-id", "timeout", "trace"] }
 tracing = "0.1.44"
 url = "2.5.8"
 uuid = { version = "1.23.3", features = ["v7"] }
+zstd = "=0.13.3"
 
 [dev-dependencies]
 async-trait = "0.1.89"
 axum = { version = "0.8.9", default-features = false, features = ["http1", "tokio"] }
-tokio = { version = "1.52.3", default-features = false, features = ["macros", "net", "rt-multi-thread"] }
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "net", "rt-multi-thread", "test-util"] }
 tokio-tungstenite = "0.29.0"
 tower = { version = "0.5.3", features = ["util"] }
 

backend/crates/gateway-api/src/admin/account_groups.rs

@@ -3,8 +3,8 @@
 use std::collections::BTreeMap;
 
 use axum::{
-    Json, Router,
-    extract::{Query, State},
+    Router,
+    extract::State,
     http::StatusCode,
     response::IntoResponse,
     routing::{get, post},
@@ -22,8 +22,8 @@ use gateway_core::routing::AccountGroupId;
 use serde::{Deserialize, Serialize};
 
 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, PageMeta,
-    WireValidationError, wire::map_admin_service_error,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    PageMeta, WireValidationError, wire::map_admin_service_error,
 };
 
 const DEFAULT_PAGE_SIZE: u32 = 50;
@@ -127,7 +127,7 @@ struct AccountGroupCapacityView {
 #[serde(rename_all = "camelCase")]
 struct AccountGroupUsageView {
     today_usd: String,
-    total_usd: String,
+    retained_total_usd: String,
 }
 
 impl From<AccountGroupRecord> for AccountGroupView {
@@ -168,7 +168,7 @@ fn capacity_view(capacity: AccountGroupCapacity) -> AccountGroupCapacityView {
 fn usage_view(usage: AccountGroupUsage) -> AccountGroupUsageView {
     AccountGroupUsageView {
         today_usd: usage.today_usd.to_string(),
-        total_usd: usage.total_usd.to_string(),
+        retained_total_usd: usage.retained_total_usd.to_string(),
     }
 }
 
@@ -235,7 +235,7 @@ where
 async fn list<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<ListAccountGroupsQuery>,
+    AdminQuery(query): AdminQuery<ListAccountGroupsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -255,7 +255,7 @@ where
 async fn create<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<CreateAccountGroupRequest>,
+    AdminJson(request): AdminJson<CreateAccountGroupRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -281,7 +281,7 @@ where
 async fn update<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<UpdateAccountGroupRequest>,
+    AdminJson(request): AdminJson<UpdateAccountGroupRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -308,7 +308,7 @@ where
 async fn enable<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<AccountGroupIdRequest>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -319,7 +319,7 @@ where
 async fn disable<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<AccountGroupIdRequest>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -355,7 +355,7 @@ where
 async fn delete<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<AccountGroupIdRequest>,
+    AdminJson(request): AdminJson<AccountGroupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -387,12 +387,11 @@ fn mutation_response(
 }
 
 fn group_id(value: String) -> Result<AccountGroupId, AdminError> {
-    AccountGroupId::new(value).map_err(|_| AdminError::bad_request("Invalid account group ID"))
+    AccountGroupId::new(value).map_err(|_| AdminError::bad_request("账号组 ID 不合法"))
 }
 
 fn group_color(value: &str) -> Result<AccountGroupColor, AdminError> {
-    AccountGroupColor::parse(value)
-        .ok_or_else(|| AdminError::bad_request("Invalid account group color"))
+    AccountGroupColor::parse(value).ok_or_else(|| AdminError::bad_request("账号组颜色不合法"))
 }
 
 fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), AdminError> {
@@ -403,15 +402,15 @@ fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), Ad
         || description
             .is_some_and(|value| value.len() > 4096 || value.chars().any(char::is_control))
     {
-        return Err(AdminError::bad_request("Invalid account group request"));
+        return Err(AdminError::bad_request("账号组请求不合法"));
     }
     Ok(())
 }
 
 fn map_wire_error(_: WireValidationError) -> AdminError {
-    AdminError::bad_request("Invalid account group query")
+    AdminError::bad_request("账号组查询参数不合法")
 }
 
 fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Account group repository unavailable")
+    map_admin_service_error(error)
 }

backend/crates/gateway-api/src/admin/accounts/credentials.rs

@@ -0,0 +1,552 @@
+//! Provider-owned 凭据请求、命令转换与敏感材料校验。
+
+use super::*;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum AccountProvider {
+    OpenAi,
+    Xai,
+}
+
+impl AccountProvider {
+    fn parse(value: &str) -> Result<Self, WireValidationError> {
+        match value.trim() {
+            "openai" => Ok(Self::OpenAi),
+            "xai" => Ok(Self::Xai),
+            _ => Err(WireValidationError::new("provider")),
+        }
+    }
+}
+
+/// 导入统一设置，复用编辑账号的调度和分组约束。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountImportSettingsRequest {
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_required_nullable")]
+    pub concurrency_limit: Option<u64>,
+    pub weight: u64,
+    pub group_ids: Vec<String>,
+}
+
+impl AccountImportSettingsRequest {
+    fn validate(&self) -> Result<(), WireValidationError> {
+        parse_concurrency_limit(self.concurrency_limit)?;
+        parse_account_weight(self.weight)?;
+        validate_wire_group_ids(&self.group_ids)?;
+        Ok(())
+    }
+
+    fn into_settings(
+        self,
+    ) -> Result<gateway_admin::model::accounts::AccountImportSettings, WireValidationError> {
+        Ok(gateway_admin::model::accounts::AccountImportSettings {
+            enabled: self.enabled,
+            concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
+            weight: parse_account_weight(self.weight)?,
+            group_ids: validate_wire_group_ids(&self.group_ids)?,
+        })
+    }
+}
+
+/// Provider-owned 账号导入请求；公共 API 不解释 `data` 内部字段。
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountImportRequest {
+    pub outbound_proxy_id: Option<String>,
+    pub settings: Option<AccountImportSettingsRequest>,
+    pub provider: String,
+    pub data: Value,
+}
+
+impl AccountImportRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if let Some(id) = &self.outbound_proxy_id {
+            require_wire_id(id, "outboundProxyId")?;
+        }
+        if let Some(settings) = &self.settings {
+            settings.validate()?;
+        }
+        AccountProvider::parse(&self.provider)?;
+        if !self.data.is_object()
+            || serde_json::to_vec(&self.data)
+                .map_or(true, |encoded| encoded.len() > MAX_IMPORT_DATA_BYTES)
+        {
+            return Err(WireValidationError::new("data"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, ImportCredentials), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            ImportCredentials {
+                outbound_proxy_id: self.outbound_proxy_id,
+                settings: self
+                    .settings
+                    .map(AccountImportSettingsRequest::into_settings)
+                    .transpose()?,
+                context,
+                document: provider_document(self.data, "data")?,
+            },
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct StartAccountAuthorizationRequest {
+    pub outbound_proxy_id: Option<String>,
+    pub provider: String,
+    pub name: String,
+    pub account_id: Option<String>,
+    pub outbound_proxy_url: Option<super::wire::AccountProxyUpdate>,
+}
+
+impl StartAccountAuthorizationRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        require_text(&self.name, MAX_NAME_BYTES, "name")?;
+        if let Some(account_id) = self.account_id.as_deref() {
+            require_account_id(account_id, "accountId")?;
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, StartAuthorization), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        let reauthorization = self
+            .account_id
+            .map(ProviderAccountId::new)
+            .transpose()
+            .map_err(|_| WireValidationError::new("accountId"))?;
+        Ok((
+            provider,
+            StartAuthorization {
+                context,
+                name: self.name,
+                reauthorization,
+                outbound_proxy: super::wire::proxy_selection(
+                    self.outbound_proxy_id,
+                    self.outbound_proxy_url,
+                )?,
+            },
+        ))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct CompleteAccountAuthorizationRequest {
+    pub settings: Option<AccountImportSettingsRequest>,
+    pub provider: String,
+    pub flow_id: String,
+    pub callback_url: String,
+}
+
+impl CompleteAccountAuthorizationRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if let Some(settings) = &self.settings {
+            settings.validate()?;
+        }
+        let provider = AccountProvider::parse(&self.provider)?;
+        match provider {
+            AccountProvider::OpenAi => {
+                if !URL_SAFE_NO_PAD
+                    .decode(&self.flow_id)
+                    .is_ok_and(|decoded| decoded.len() == 32)
+                {
+                    return Err(WireValidationError::new("flowId"));
+                }
+            }
+            AccountProvider::Xai => require_wire_id(&self.flow_id, "flowId")?,
+        }
+        require_text(&self.callback_url, MAX_CALLBACK_URL_BYTES, "callbackUrl")
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, CompleteAuthorization), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            CompleteAuthorization {
+                settings: self
+                    .settings
+                    .map(AccountImportSettingsRequest::into_settings)
+                    .transpose()?,
+                context,
+                flow_id: self.flow_id,
+                callback_url: self.callback_url,
+            },
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct UpdateAccountRequest {
+    pub outbound_proxy_id: Option<String>,
+    pub outbound_proxy_url: Option<super::wire::AccountProxyUpdate>,
+    pub account_id: String,
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_required_nullable")]
+    pub concurrency_limit: Option<u64>,
+    pub weight: u64,
+    pub group_ids: Vec<String>,
+}
+
+impl UpdateAccountRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        parse_concurrency_limit(self.concurrency_limit)?;
+        parse_account_weight(self.weight)?;
+        validate_wire_group_ids(&self.group_ids)?;
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<UpdateAccount, WireValidationError> {
+        self.validate()?;
+        Ok(UpdateAccount {
+            outbound_proxy: super::wire::proxy_selection(
+                self.outbound_proxy_id,
+                self.outbound_proxy_url,
+            )?,
+            account_id: self.account_id,
+            enabled: self.enabled,
+            concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
+            weight: parse_account_weight(self.weight)?,
+            group_ids: validate_wire_group_ids(&self.group_ids)?,
+        })
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UpdatedAccountData {
+    pub account_id: String,
+    pub config_revision: u64,
+}
+
+impl From<AccountUpdateResult> for UpdatedAccountData {
+    fn from(result: AccountUpdateResult) -> Self {
+        Self {
+            account_id: result.account_id.to_string(),
+            config_revision: result.config_revision.get(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountDeletionRequest {
+    pub provider: String,
+    pub account_ids: Vec<String>,
+}
+
+impl AccountDeletionRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        AccountProvider::parse(&self.provider)?;
+        if self.account_ids.is_empty() || self.account_ids.len() > MAX_ACCOUNT_DELETE_BATCH {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        let mut unique = BTreeSet::new();
+        for account_id in &self.account_ids {
+            require_account_id(account_id, "accountIds")?;
+            if !unique.insert(account_id.as_str()) {
+                return Err(WireValidationError::new("accountIds"));
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<(AccountProvider, CredentialDeletion), WireValidationError> {
+        self.validate()?;
+        let provider = AccountProvider::parse(&self.provider)?;
+        Ok((
+            provider,
+            CredentialDeletion {
+                context,
+                account_ids: self
+                    .account_ids
+                    .into_iter()
+                    .map(ProviderAccountId::new)
+                    .collect::<Result<Vec<_>, _>>()
+                    .map_err(|_| WireValidationError::new("accountIds"))?,
+            },
+        ))
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct RotateAccountRequest {
+    pub provider: String,
+    pub account_id: String,
+    pub access_token: String,
+    pub refresh_token: Option<String>,
+    pub id_token: Option<String>,
+}
+
+impl RotateAccountRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if AccountProvider::parse(&self.provider)? != AccountProvider::OpenAi {
+            return Err(WireValidationError::new("provider"));
+        }
+        require_account_id(&self.account_id, "accountId")?;
+        validate_oauth_material(
+            &self.access_token,
+            self.refresh_token.as_deref(),
+            self.id_token.as_deref(),
+        )
+    }
+
+    pub(super) fn into_command(
+        self,
+        context: gateway_admin::model::MutationContext,
+    ) -> Result<RotateCredential, WireValidationError> {
+        self.validate()?;
+        let mut material = Map::new();
+        material.insert("access_token".to_owned(), Value::String(self.access_token));
+        material.insert(
+            "refresh_token".to_owned(),
+            self.refresh_token.map_or(Value::Null, Value::String),
+        );
+        material.insert(
+            "id_token".to_owned(),
+            self.id_token.map_or(Value::Null, Value::String),
+        );
+        Ok(RotateCredential {
+            mutation: CredentialMutation {
+                context,
+                account_id: ProviderAccountId::new(self.account_id)
+                    .map_err(|_| WireValidationError::new("accountId"))?,
+            },
+            provider_material: ProviderDocument::new(OpaqueProviderData::new(material)),
+        })
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountImportData {
+    pub imported_count: usize,
+    pub account_ids: Vec<String>,
+}
+
+impl AccountImportData {
+    pub fn from_result(result: CredentialImportResult) -> Self {
+        let account_ids = result
+            .credential_ids
+            .into_iter()
+            .map(|account_id| account_id.to_string())
+            .collect::<Vec<_>>();
+        Self {
+            imported_count: account_ids.len(),
+            account_ids,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountAuthorizationData {
+    pub flow_id: String,
+    pub authorization_url: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+impl From<AuthorizationStarted> for AccountAuthorizationData {
+    fn from(started: AuthorizationStarted) -> Self {
+        Self {
+            flow_id: started.flow_id,
+            authorization_url: started.authorization_url,
+            expires_at: started.expires_at,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountMutationData {
+    pub account_id: String,
+}
+
+impl From<CredentialMutationResult> for AccountMutationData {
+    fn from(result: CredentialMutationResult) -> Self {
+        Self {
+            account_id: result.account_id.to_string(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountDeletionData {
+    pub deleted_count: usize,
+    pub account_ids: Vec<String>,
+}
+
+impl From<CredentialDeletionResult> for AccountDeletionData {
+    fn from(result: CredentialDeletionResult) -> Self {
+        let account_ids = result
+            .account_ids
+            .into_iter()
+            .map(|account_id| account_id.to_string())
+            .collect::<Vec<_>>();
+        Self {
+            deleted_count: account_ids.len(),
+            account_ids,
+        }
+    }
+}
+
+pub(super) fn require_account_id(
+    value: &str,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.trim().is_empty()
+        || value.len() > 128
+        || value.chars().any(char::is_control)
+        || !value.starts_with("acct_")
+    {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+pub(super) fn parse_concurrency_limit(
+    value: Option<u64>,
+) -> Result<Option<AccountConcurrencyLimit>, WireValidationError> {
+    value
+        .map(|value| {
+            u32::try_from(value)
+                .ok()
+                .and_then(AccountConcurrencyLimit::new)
+                .ok_or_else(|| WireValidationError::new("concurrencyLimit"))
+        })
+        .transpose()
+}
+
+pub(super) fn deserialize_required_nullable<'de, D>(
+    deserializer: D,
+) -> Result<Option<u64>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    Option::<u64>::deserialize(deserializer)
+}
+
+pub(super) fn parse_account_weight(value: u64) -> Result<AccountWeight, WireValidationError> {
+    u16::try_from(value)
+        .ok()
+        .and_then(AccountWeight::new)
+        .ok_or_else(|| WireValidationError::new("weight"))
+}
+
+pub(super) fn validate_wire_group_ids(
+    values: &[String],
+) -> Result<Vec<AccountGroupId>, WireValidationError> {
+    if values.len() > MAX_ACCOUNT_GROUP_BATCH
+        || values.iter().collect::<BTreeSet<_>>().len() != values.len()
+    {
+        return Err(WireValidationError::new("groupIds"));
+    }
+    values
+        .iter()
+        .cloned()
+        .map(|value| AccountGroupId::new(value).map_err(|_| WireValidationError::new("groupIds")))
+        .collect()
+}
+
+fn provider_document(
+    value: Value,
+    field: &'static str,
+) -> Result<ProviderDocument, WireValidationError> {
+    match value {
+        Value::Object(document) => Ok(ProviderDocument::new(OpaqueProviderData::new(document))),
+        _ => Err(WireValidationError::new(field)),
+    }
+}
+
+fn require_wire_id(value: &str, field: &'static str) -> Result<(), WireValidationError> {
+    require_text(value, MAX_ID_BYTES, field)?;
+    if value.starts_with("__")
+        || !value
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.' | b':'))
+    {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn require_text(
+    value: &str,
+    max_bytes: usize,
+    field: &'static str,
+) -> Result<(), WireValidationError> {
+    if value.trim().is_empty() || value.len() > max_bytes || value.chars().any(char::is_control) {
+        return Err(WireValidationError::new(field));
+    }
+    Ok(())
+}
+
+fn validate_oauth_material(
+    access_token: &str,
+    refresh_token: Option<&str>,
+    id_token: Option<&str>,
+) -> Result<(), WireValidationError> {
+    if access_token.len() > MAX_ACCESS_TOKEN_BYTES
+        || !valid_visible_ascii(access_token)
+        || !valid_compact_jwt_shape(access_token)
+    {
+        return Err(WireValidationError::new("accessToken"));
+    }
+    if refresh_token.is_some_and(|token| {
+        token.len() > MAX_REFRESH_TOKEN_BYTES
+            || !valid_visible_ascii(token)
+            || token == access_token
+    }) {
+        return Err(WireValidationError::new("refreshToken"));
+    }
+    if id_token.is_some_and(|token| {
+        token.len() > MAX_ID_TOKEN_BYTES
+            || !valid_visible_ascii(token)
+            || !valid_compact_jwt_shape(token)
+    }) {
+        return Err(WireValidationError::new("idToken"));
+    }
+    Ok(())
+}
+
+fn valid_compact_jwt_shape(value: &str) -> bool {
+    let mut segments = value.split('.');
+    matches!(
+        (segments.next(), segments.next(), segments.next(), segments.next()),
+        (Some(header), Some(payload), Some(signature), None)
+            if !header.is_empty() && !payload.is_empty() && !signature.is_empty()
+    )
+}
+
+fn valid_visible_ascii(value: &str) -> bool {
+    !value.is_empty() && value.bytes().all(|byte| (0x21..=0x7e).contains(&byte))
+}
+
+pub(super) fn provider_document_value(document: ProviderDocument) -> Value {
+    Value::Object(document.into_provider_data().into_inner())
+}

backend/crates/gateway-api/src/admin/accounts/handlers.rs

@@ -0,0 +1,598 @@
+//! 账号管理路由与 HTTP handler 编排。
+
+use super::*;
+
+/// 构造统一账号管理路由。
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/accounts", get(list_accounts::<S>))
+        .route("/api/admin/accounts/detail", get(account_detail::<S>))
+        .route("/api/admin/accounts/export", get(export_accounts::<S>))
+        .route("/api/admin/accounts/import", post(import_accounts::<S>))
+        .route("/api/admin/accounts/refresh", post(refresh_account::<S>))
+        .route("/api/admin/accounts/recover", post(recover_account::<S>))
+        .route("/api/admin/accounts/rotate", post(rotate_account::<S>))
+        .route("/api/admin/accounts/update", post(update_account::<S>))
+        .route("/api/admin/accounts/delete", post(delete_accounts::<S>))
+        .route(
+            "/api/admin/accounts/batch-update",
+            post(batch_update_accounts::<S>),
+        )
+        .route("/api/admin/accounts/quota", get(account_quota::<S>))
+        .route(
+            "/api/admin/accounts/quota-forecast",
+            get(account_quota_forecast::<S>),
+        )
+        .route(
+            "/api/admin/accounts/profile-statistics",
+            get(account_profile_statistics::<S>),
+        )
+        .route(
+            "/api/admin/accounts/profile-avatar",
+            get(account_profile_avatar::<S>),
+        )
+        .route(
+            "/api/admin/accounts/reset-credits",
+            get(account_reset_credits::<S>).post(consume_account_reset_credit::<S>),
+        )
+        .route(
+            "/api/admin/accounts/quota/refresh",
+            post(refresh_account_quota::<S>),
+        )
+        .route("/api/admin/accounts/models", get(account_models::<S>))
+        .route(
+            "/api/admin/accounts/models/refresh",
+            post(refresh_account_models::<S>),
+        )
+        .route(
+            "/api/admin/accounts/connection-test",
+            get(test_account_connection::<S>),
+        )
+        .route(
+            "/api/admin/accounts/oauth/start",
+            post(start_account_authorization::<S>),
+        )
+        .route(
+            "/api/admin/accounts/oauth/complete",
+            post(complete_account_authorization::<S>),
+        )
+}
+
+async fn batch_update_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<BatchUpdateAccountsRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .batch_update(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(BatchUpdatedAccountsData::from(result)),
+    ))
+}
+
+async fn list_accounts<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ListQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = query.validate().map_err(map_wire_error)?;
+    let page = command.page;
+    let page_size = command.page_size.get();
+    let result = state
+        .admin_services()
+        .accounts()
+        .list(command)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_page_data(result, page, page_size, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_detail<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn export_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountExportQuery>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let ids = query.into_ids().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .export(&auth.context().mutation_context(), ids)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountExportData::from_result(result);
+    let mut response = AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)).into_response();
+    response
+        .headers_mut()
+        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
+    Ok(response)
+}
+
+async fn import_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountImportRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .import_document(command)
+                .await
+        }
+        AccountProvider::Xai => state.admin_services().xai().import_document(command).await,
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountImportData::from_result(result)),
+    ))
+}
+
+async fn start_account_authorization<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<StartAccountAuthorizationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .start_authorization(command)
+                .await
+        }
+        AccountProvider::Xai => {
+            state
+                .admin_services()
+                .xai()
+                .start_authorization(command)
+                .await
+        }
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountAuthorizationData::from(result)),
+    ))
+}
+
+async fn complete_account_authorization<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<CompleteAccountAuthorizationRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => {
+            state
+                .admin_services()
+                .openai()
+                .complete_authorization(command)
+                .await
+        }
+        AccountProvider::Xai => {
+            state
+                .admin_services()
+                .xai()
+                .complete_authorization(command)
+                .await
+        }
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(AccountMutationData::from(result)),
+    ))
+}
+
+async fn rotate_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RotateAccountRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .openai()
+        .rotate(command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountMutationData::from(result)),
+    ))
+}
+
+async fn update_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateAccountRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .update(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(UpdatedAccountData::from(result)),
+    ))
+}
+
+async fn delete_accounts<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountDeletionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (provider, command) = request
+        .into_command(auth.context().mutation_context())
+        .map_err(map_wire_error)?;
+    let result = match provider {
+        AccountProvider::OpenAi => state.admin_services().openai().delete(command).await,
+        AccountProvider::Xai => state.admin_services().xai().delete(command).await,
+    }
+    .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountDeletionData::from(result)),
+    ))
+}
+
+async fn refresh_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountRefreshRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .refresh(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_refresh_data(result, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn recover_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .recover(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_refresh_data(result, Utc::now());
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_quota<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_quota_forecast<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota_forecast(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountQuotaForecastData::from(result)),
+    ))
+}
+
+async fn account_profile_statistics<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .profile_statistics(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountProfileStatisticsData::from(result)),
+    ))
+}
+
+async fn account_profile_avatar<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountProfileAvatarQuery>,
+) -> Result<Response, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let avatar = state
+        .admin_services()
+        .accounts()
+        .profile_avatar(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(profile_avatar_response(avatar))
+}
+
+/// 将 Provider 头像流投影为受保护的同源 HTTP 响应。
+#[must_use]
+pub fn profile_avatar_response(avatar: ProviderProfileAvatar) -> Response {
+    let ProviderProfileAvatar {
+        content_type,
+        content_length,
+        etag,
+        body,
+    } = avatar;
+    let mut response = Response::new(Body::from_stream(body));
+    *response.status_mut() = StatusCode::OK;
+    let headers = response.headers_mut();
+    headers.insert(
+        header::CONTENT_TYPE,
+        content_type
+            .and_then(|value| HeaderValue::from_str(&value).ok())
+            .unwrap_or_else(|| HeaderValue::from_static("application/octet-stream")),
+    );
+    if let Some(value) =
+        content_length.and_then(|length| HeaderValue::from_str(&length.to_string()).ok())
+    {
+        headers.insert(header::CONTENT_LENGTH, value);
+    }
+    if let Some(value) = etag.and_then(|value| HeaderValue::from_str(&value).ok()) {
+        headers.insert(header::ETAG, value);
+    }
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("private, max-age=3600"),
+    );
+    headers.insert(
+        HeaderName::from_static("x-content-type-options"),
+        HeaderValue::from_static("nosniff"),
+    );
+    headers.insert(
+        HeaderName::from_static("cross-origin-resource-policy"),
+        HeaderValue::from_static("same-origin"),
+    );
+    headers.insert(
+        HeaderName::from_static("content-security-policy"),
+        HeaderValue::from_static("sandbox; default-src 'none'"),
+    );
+    response
+}
+
+async fn refresh_account_quota<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .quota(&account_id, true)
+        .await
+        .map_err(map_service_error)?;
+    let data = AccountQuotaData {
+        account: account_view(result, Utc::now()),
+    };
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn account_reset_credits<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .reset_credits(&auth.context().mutation_context(), account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountResetCreditsData::from(result)),
+    ))
+}
+
+async fn consume_account_reset_credit<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountResetCreditConsumeRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let command = request.into_command().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .consume_reset_credit(&auth.context().mutation_context(), command)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountResetCreditResultData::from(result)),
+    ))
+}
+
+async fn account_models<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .models(&account_id, false)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_models_data(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn refresh_account_models<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<AccountActionRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = request.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .models(&account_id, true)
+        .await
+        .map_err(map_service_error)?;
+    let data = account_models_data(result);
+    Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
+}
+
+async fn test_account_connection<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountTestQuery>,
+) -> Result<Sse<impl Stream<Item = Result<Event, Infallible>>>, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let (account_id, upstream_model) = query.into_command().map_err(map_wire_error)?;
+    let stream = state
+        .admin_services()
+        .accounts()
+        .test_connection(account_id, upstream_model)
+        .await
+        .map_err(map_service_error)?
+        .map(|event| {
+            let event = AccountConnectionTestEvent::from(event);
+            let data = serde_json::to_string(&event.data).unwrap_or_else(|_| "{}".to_owned());
+            Ok(Event::default().data(data))
+        });
+    Ok(Sse::new(stream).keep_alive(KeepAlive::default()))
+}

backend/crates/gateway-api/src/admin/accounts/mod.rs

@@ -0,0 +1,81 @@
+//! 管理端账号目录的 HTTP 合同、凭据动作、路由处理与安全响应投影。
+
+use std::{collections::BTreeSet, convert::Infallible, fmt};
+
+use axum::{
+    Router,
+    body::Body,
+    extract::State,
+    http::{HeaderName, HeaderValue, StatusCode, header},
+    response::{
+        IntoResponse, Response,
+        sse::{Event, KeepAlive, Sse},
+    },
+    routing::{get, post},
+};
+use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
+use chrono::{DateTime, FixedOffset, Utc};
+use futures::{Stream, StreamExt as _};
+use gateway_admin::model::{
+    AdminError as AdminServiceError, PageSize,
+    accounts::{
+        AccountConcurrencyLimit, AccountConnectionTestEvent as DomainConnectionTestEvent,
+        AccountCost, AccountGroupFilter, AccountListQuery, AccountModelUsage, AccountSort,
+        AccountSortField, AccountStatus as DomainAccountStatus, AccountUpdateResult, AccountUsage,
+        AccountWeight, AccountsUpdateResult, BatchUpdateAccounts, SortDirection, UpdateAccount,
+    },
+    provider_credentials::{
+        AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
+        AccountUsagePeriod, AuthorizationStarted, CompleteAuthorization,
+        ConsumeProviderResetCredit, CredentialDeletion, CredentialDeletionResult,
+        CredentialImportResult, CredentialMutation, CredentialMutationResult, ImportCredentials,
+        ProviderDocument, ProviderModels, ProviderProfileActivityInsights, ProviderProfileAvatar,
+        ProviderProfileDailyUsage, ProviderProfileInvocation, ProviderProfileStatistics,
+        ProviderProfileStatisticsSummary, ProviderQuota, ProviderQuotaWindow, ProviderResetCredit,
+        ProviderResetCreditResult, ProviderResetCredits, RotateCredential, StartAuthorization,
+    },
+};
+use gateway_core::{
+    account::{OpaqueProviderData, ProviderAccountId},
+    routing::{AccountGroupId, ProviderKind, UpstreamModelId},
+};
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::{Map, Value};
+use uuid::{Uuid, Version};
+
+use super::presenter::{format_compact_number, format_decimal_currency, format_number};
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    PageMeta, WireValidationError,
+};
+
+const DEFAULT_PAGE_SIZE: u32 = 50;
+const MAX_PAGE_SIZE: u32 = 200;
+const MAX_SEARCH_BYTES: usize = 256;
+const MAX_ID_BYTES: usize = 256;
+const MAX_NAME_BYTES: usize = 512;
+const MAX_IMPORT_DATA_BYTES: usize = 64 * 1024 * 1024;
+const MAX_ACCESS_TOKEN_BYTES: usize = 16 * 1024;
+const MAX_REFRESH_TOKEN_BYTES: usize = 64 * 1024;
+const MAX_ID_TOKEN_BYTES: usize = 16 * 1024;
+const MAX_CALLBACK_URL_BYTES: usize = 64 * 1024;
+const MAX_ACCOUNT_DELETE_BATCH: usize = 200;
+const MAX_ACCOUNT_GROUP_BATCH: usize = 1000;
+const MAX_AVATAR_VERSION_BYTES: usize = 32;
+
+mod credentials;
+mod handlers;
+mod presenter;
+mod wire;
+
+pub use credentials::*;
+pub use handlers::{profile_avatar_response, router};
+pub(super) use presenter::quota_window_view;
+pub use wire::*;
+
+use credentials::{
+    AccountProvider, deserialize_required_nullable, parse_account_weight, parse_concurrency_limit,
+    provider_document_value, require_account_id, validate_wire_group_ids,
+};
+use presenter::*;
+use wire::BatchUpdatedAccountsData;

backend/crates/gateway-api/src/admin/accounts/presenter.rs

@@ -0,0 +1,491 @@
+//! Admin 领域结果到安全 HTTP wire 的展示投影。
+
+use super::*;
+use gateway_admin::model::quota_forecast::{AccountQuotaForecast, AccountQuotaForecastReport};
+
+pub(super) fn account_page_data(
+    result: AccountDirectoryPage,
+    page: u32,
+    page_size: u16,
+    now: DateTime<Utc>,
+) -> AccountPageData {
+    let total_pages = if result.total == 0 {
+        0
+    } else {
+        u32::try_from(result.total.div_ceil(u64::from(page_size))).unwrap_or(u32::MAX)
+    };
+    AccountPageData {
+        items: result
+            .items
+            .into_iter()
+            .map(|item| account_view(item, now))
+            .collect(),
+        page: PageMeta::new(page, u32::from(page_size), result.total, total_pages),
+        summary: AccountSummaryView {
+            total: result.summary.total,
+            normal: result.summary.normal,
+            quota_exhausted: result.summary.quota_exhausted,
+            rate_limited: result.summary.rate_limited,
+            disabled: result.summary.disabled,
+            error: result.summary.error,
+        },
+    }
+}
+
+pub(super) fn account_refresh_data(
+    result: AccountRefreshResult,
+    now: DateTime<Utc>,
+) -> AccountRefreshData {
+    AccountRefreshData {
+        account: account_view(result.account, now),
+    }
+}
+
+pub(super) fn account_models_data(result: ProviderModels) -> AccountModelsData {
+    AccountModelsData {
+        models: result
+            .models
+            .into_iter()
+            .map(|model| {
+                let id = model.id.to_string();
+                AccountModelView {
+                    label: id.clone(),
+                    id,
+                }
+            })
+            .collect(),
+    }
+}
+
+pub(super) fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> AccountView {
+    let AccountDirectoryItem {
+        account,
+        plan_type_display,
+        projection,
+        usage,
+        quota,
+    } = item;
+    let status = projection.status.as_str().to_owned();
+    let rate_limited_until = projection.rate_limited_until.map(DateTime::<Utc>::from);
+    let expires_at = account.access_token_expires_at.as_ref().map(china_rfc3339);
+    let added_at = china_rfc3339(&account.created_at);
+    let updated_at = china_rfc3339(&account.updated_at);
+    let usage_period = quota.usage_window().map(|(_, period)| period);
+    let (quota, refresh_token_expires_at) = account_quota_view(quota, rate_limited_until, now);
+    AccountView {
+        id: account.id.clone(),
+        name: account.name,
+        provider: account.provider_kind.to_string(),
+        groups: account
+            .groups
+            .into_iter()
+            .map(|group| AccountGroupRefView {
+                id: group.id.to_string(),
+                name: group.name,
+                color: group.color.as_str().to_owned(),
+                enabled: group.enabled,
+            })
+            .collect(),
+        resource_ref: account.id,
+        email: account.email,
+        account_id: account.upstream_account_id,
+        user_id: account.upstream_user_id,
+        label: None,
+        plan_type: account.plan_type,
+        plan_type_display: plan_type_display.unwrap_or_else(|| "未知套餐".to_owned()),
+        authentication_kind: account.authentication_kind,
+        has_refresh_token: account.has_refresh_token,
+        status,
+        error_reason: projection
+            .error_reason
+            .map(|reason| reason.as_str().to_owned()),
+        error_message: projection.error_message,
+        enabled: account.enabled,
+        concurrency_limit: account.concurrency_limit.map(|limit| limit.get()),
+        weight: account.weight.get(),
+        outbound_proxy_endpoint: account
+            .outbound_proxy
+            .as_ref()
+            .map(|proxy| proxy.endpoint()),
+        access_token_expires_at: expires_at,
+        access_token_expires_at_display: account
+            .access_token_expires_at
+            .as_ref()
+            .map(china_datetime),
+        refresh_token_expires_at,
+        next_refresh_at: account.next_refresh_at.map(|value| china_rfc3339(&value)),
+        added_at,
+        added_at_display: china_datetime(&account.created_at),
+        updated_at,
+        updated_at_display: china_datetime(&account.updated_at),
+        quota,
+        usage: account_usage_view(usage, usage_period, now),
+    }
+}
+
+impl From<AccountQuotaForecastReport> for AccountQuotaForecastData {
+    fn from(report: AccountQuotaForecastReport) -> Self {
+        Self {
+            account_id: report.account_id,
+            generated_at: china_rfc3339(&report.generated_at),
+            forecasts: report
+                .forecasts
+                .into_iter()
+                .map(quota_forecast_view)
+                .collect(),
+        }
+    }
+}
+
+fn quota_forecast_view(forecast: AccountQuotaForecast) -> AccountQuotaForecastView {
+    AccountQuotaForecastView {
+        period: match forecast.period {
+            AccountUsagePeriod::Weekly => "weekly",
+            AccountUsagePeriod::Monthly => "monthly",
+        },
+        target_days: forecast.target_seconds as f64 / 86_400.0,
+        extrapolated: forecast.extrapolated,
+        source: forecast.source.map(|source| QuotaForecastSourceView {
+            label: source.label,
+            used_percent: source.used_percent,
+            used_percent_display: source
+                .used_percent
+                .map_or_else(|| "—".to_owned(), |value| format!("{value:.1}%")),
+            observed_at: source.observed_at.map(|value| china_rfc3339(&value)),
+            observed_at_display: source
+                .observed_at
+                .map_or_else(|| "—".to_owned(), |value| china_datetime(&value)),
+            reset_at: china_rfc3339(&source.reset_at),
+            tokens_display: display_optional_tokens(source.tokens),
+            usd_display: forecast_usd_display(source.usd),
+        }),
+        unavailable_reason: forecast.unavailable_reason,
+        low_sample: forecast.low_sample,
+        incomplete_cost: forecast.incomplete_cost,
+        incomplete_tokens: forecast.incomplete_tokens,
+        estimated_tokens: forecast.estimated_tokens,
+        estimated_tokens_display: display_optional_tokens(forecast.estimated_tokens),
+        estimated_usd: forecast.estimated_usd,
+        estimated_usd_display: forecast_usd_display(forecast.estimated_usd),
+        remaining_tokens: forecast.remaining_tokens,
+        remaining_tokens_display: display_optional_tokens(forecast.remaining_tokens),
+        remaining_usd: forecast.remaining_usd,
+        remaining_usd_display: forecast_usd_display(forecast.remaining_usd),
+    }
+}
+
+fn forecast_usd_display(value: Option<f64>) -> String {
+    value.map_or_else(
+        || "—".to_owned(),
+        |value| format_decimal_currency(&format!("{value:.10}"), "USD"),
+    )
+}
+
+pub(super) fn account_quota_view(
+    mut quota: ProviderQuota,
+    rate_limited_until: Option<DateTime<Utc>>,
+    now: DateTime<Utc>,
+) -> (AccountQuotaView, Option<String>) {
+    quota.apply_limit_reached_display();
+    let refresh_token_expires_at = quota
+        .refresh_token_expires_at
+        .map(|value| china_rfc3339(&value));
+    let refreshed_at_display = quota
+        .observed_at
+        .map_or_else(|| "—".to_owned(), |value| relative_time(value, now));
+    let windows = quota.windows.into_iter().map(quota_window_view).collect();
+    let rate_limited_until = rate_limited_until.map(|until| china_datetime(&until));
+    (
+        AccountQuotaView {
+            refreshed_at_display,
+            limit_reached: quota.limit_reached,
+            rate_limited_until,
+            windows,
+        },
+        refresh_token_expires_at,
+    )
+}
+
+pub(crate) fn quota_window_view(window: ProviderQuotaWindow) -> AccountQuotaWindowView {
+    let ProviderQuotaWindow {
+        key,
+        group,
+        label,
+        limit_id,
+        limit_name,
+        role,
+        local_usage_attribution: _,
+        window_seconds,
+        used_percent,
+        reset_at,
+        limit_reached,
+        local_usage,
+        provider_data: _,
+    } = window;
+    let label_display = limit_name
+        .as_ref()
+        .map_or_else(|| label.clone(), |name| format!("{name} · {label}"));
+    AccountQuotaWindowView {
+        label_display,
+        window_label_display: label,
+        key,
+        group,
+        limit_id,
+        limit_name,
+        role: role.map(|value| value.as_str().to_owned()),
+        window_seconds,
+        used_percent,
+        used_percent_display: used_percent
+            .map_or_else(|| "—".to_owned(), |value| format!("{value:.1}%")),
+        limit_reached,
+        local_usage: local_usage.as_ref().map(quota_local_usage),
+        reset_at_display: reset_at.map_or_else(|| "—".to_owned(), |value| china_datetime(&value)),
+    }
+}
+
+pub(super) fn quota_local_usage(usage: &AccountUsage) -> Value {
+    let total_tokens = usage.total_tokens.unwrap_or_default();
+    serde_json::json!({
+        "requestCount": usage.request_count,
+        "requestCountDisplay": format_number(usage.request_count),
+        "inputTokens": usage.input_tokens.unwrap_or_default(),
+        "inputTokensDisplay": display_optional_tokens(usage.input_tokens),
+        "outputTokens": usage.output_tokens.unwrap_or_default(),
+        "outputTokensDisplay": display_optional_tokens(usage.output_tokens),
+        "cachedTokens": usage.cached_tokens.unwrap_or_default(),
+        "cachedTokensDisplay": display_optional_tokens(usage.cached_tokens),
+        "imageInputTokens": usage.image_input_tokens.unwrap_or_default(),
+        "imageInputTokensDisplay": display_optional_tokens(usage.image_input_tokens),
+        "imageOutputTokens": usage.image_output_tokens.unwrap_or_default(),
+        "imageOutputTokensDisplay": display_optional_tokens(usage.image_output_tokens),
+        "imageRequestCount": usage.image_request_count,
+        "imageRequestFailedCount": usage.image_request_failed_count,
+        "totalTokens": total_tokens,
+        "totalTokensDisplay": format_compact_number(total_tokens),
+        "requestBuckets": usage.request_buckets.iter().map(|bucket| serde_json::json!({
+            "bucketStart": bucket.bucket_start,
+            "requestCount": bucket.request_count,
+        })).collect::<Vec<_>>(),
+    })
+}
+
+pub(super) fn account_usage_view(
+    usage: Option<AccountUsage>,
+    period: Option<AccountUsagePeriod>,
+    now: DateTime<Utc>,
+) -> AccountUsageView {
+    let Some(usage) = usage else {
+        return empty_account_usage();
+    };
+    let known_count = usage
+        .cost_coverage
+        .provider_reported_count
+        .saturating_add(usage.cost_coverage.calculated_count);
+    let cost_estimate_status = if known_count == 0 {
+        "unknown"
+    } else if usage.cost_coverage.unavailable_count > 0 {
+        "partial"
+    } else {
+        "known"
+    };
+    AccountUsageView {
+        window_label_display: match period {
+            Some(AccountUsagePeriod::Weekly) => "周额度窗口",
+            Some(AccountUsagePeriod::Monthly) => "月额度窗口",
+            None => "周/月额度窗口",
+        }
+        .to_owned(),
+        request_count: Some(usage.request_count),
+        request_count_display: format_number(usage.request_count),
+        input_tokens: usage.input_tokens,
+        input_tokens_display: display_optional_tokens(usage.input_tokens),
+        output_tokens: usage.output_tokens,
+        output_tokens_display: display_optional_tokens(usage.output_tokens),
+        cached_tokens: usage.cached_tokens,
+        cached_tokens_display: display_optional_tokens(usage.cached_tokens),
+        reasoning_tokens: usage.reasoning_tokens,
+        reasoning_tokens_display: display_optional_tokens(usage.reasoning_tokens),
+        image_input_tokens: usage.image_input_tokens,
+        image_input_tokens_display: display_optional_tokens(usage.image_input_tokens),
+        image_output_tokens: usage.image_output_tokens,
+        image_output_tokens_display: display_optional_tokens(usage.image_output_tokens),
+        image_request_count: Some(usage.image_request_count),
+        image_request_count_display: format_number(usage.image_request_count),
+        image_request_failed_count: Some(usage.image_request_failed_count),
+        image_request_failed_count_display: format_number(usage.image_request_failed_count),
+        total_tokens: usage.total_tokens,
+        total_tokens_display: display_optional_tokens(usage.total_tokens),
+        created_tokens: usage.cache_write_tokens,
+        created_tokens_display: display_optional_tokens(usage.cache_write_tokens),
+        read_tokens: usage.cached_tokens,
+        read_tokens_display: display_optional_tokens(usage.cached_tokens),
+        last_used_at: usage.last_used_at.map(|value| china_rfc3339(&value)),
+        last_used_at_display: usage
+            .last_used_at
+            .map_or_else(|| "—".to_owned(), |value| relative_time(value, now)),
+        cost_estimate_status: cost_estimate_status.to_owned(),
+        known_cost_count: Some(known_count),
+        partial_cost_count: Some(u64::from(cost_estimate_status == "partial")),
+        unknown_cost_count: Some(usage.cost_coverage.unavailable_count),
+        costs: usage.costs.iter().map(account_currency_cost_view).collect(),
+        models: usage
+            .models
+            .into_iter()
+            .map(|model| account_model_usage_view(model, now))
+            .collect(),
+    }
+}
+
+pub(super) fn account_model_usage_view(
+    usage: AccountModelUsage,
+    now: DateTime<Utc>,
+) -> ModelUsageView {
+    let known_count = usage
+        .cost_coverage
+        .provider_reported_count
+        .saturating_add(usage.cost_coverage.calculated_count);
+    let cost_estimate_status = if known_count == 0 {
+        "unknown"
+    } else if usage.cost_coverage.unavailable_count > 0 {
+        "partial"
+    } else {
+        "known"
+    };
+    let usd = usage
+        .costs
+        .iter()
+        .find(|cost| cost.currency.eq_ignore_ascii_case("USD"));
+    ModelUsageView {
+        model: usage.model,
+        request_count: usage.request_count,
+        request_count_display: format_number(usage.request_count),
+        success_rate: (usage.request_count > 0)
+            .then(|| usage.success_count as f64 * 100.0 / usage.request_count as f64),
+        success_rate_display: if usage.request_count == 0 {
+            "—".to_owned()
+        } else {
+            format!(
+                "{:.1}%",
+                usage.success_count as f64 * 100.0 / usage.request_count as f64
+            )
+        },
+        input_tokens: usage.input_tokens,
+        input_tokens_display: display_optional_tokens(usage.input_tokens),
+        output_tokens: usage.output_tokens,
+        output_tokens_display: display_optional_tokens(usage.output_tokens),
+        cached_tokens: usage.cached_tokens,
+        cached_tokens_display: display_optional_tokens(usage.cached_tokens),
+        image_input_tokens: usage.image_input_tokens,
+        image_input_tokens_display: display_optional_tokens(usage.image_input_tokens),
+        image_output_tokens: usage.image_output_tokens,
+        image_output_tokens_display: display_optional_tokens(usage.image_output_tokens),
+        image_request_count: usage.image_request_count,
+        image_request_count_display: format_number(usage.image_request_count),
+        image_request_failed_count: usage.image_request_failed_count,
+        image_request_failed_count_display: format_number(usage.image_request_failed_count),
+        total_tokens: usage.total_tokens,
+        total_tokens_display: display_optional_tokens(usage.total_tokens),
+        billing_amount_usd: usd.map(|cost| cost.amount.as_str().to_owned()),
+        billing_amount_usd_display: usd.map_or_else(
+            || "—".to_owned(),
+            |cost| format_decimal_currency(cost.amount.as_str(), "USD"),
+        ),
+        cost_estimate_status: cost_estimate_status.to_owned(),
+        known_cost_count: known_count,
+        partial_cost_count: u64::from(cost_estimate_status == "partial"),
+        unknown_cost_count: usage.cost_coverage.unavailable_count,
+        costs: usage.costs.iter().map(account_currency_cost_view).collect(),
+        last_used_at: china_rfc3339(&usage.last_used_at),
+        last_used_at_display: relative_time(usage.last_used_at, now),
+    }
+}
+
+pub(super) fn account_currency_cost_view(cost: &AccountCost) -> CurrencyCostView {
+    CurrencyCostView {
+        currency: cost.currency.clone(),
+        estimated_amount: cost.amount.as_str().to_owned(),
+        estimated_amount_display: format_decimal_currency(cost.amount.as_str(), &cost.currency),
+    }
+}
+
+pub(super) fn display_optional_tokens(value: Option<u64>) -> String {
+    value.map_or_else(|| "—".to_owned(), format_compact_number)
+}
+
+pub(super) fn empty_account_usage() -> AccountUsageView {
+    AccountUsageView {
+        window_label_display: "周/月额度窗口".to_owned(),
+        request_count: None,
+        request_count_display: "—".to_owned(),
+        input_tokens: None,
+        input_tokens_display: "—".to_owned(),
+        output_tokens: None,
+        output_tokens_display: "—".to_owned(),
+        cached_tokens: None,
+        cached_tokens_display: "—".to_owned(),
+        reasoning_tokens: None,
+        reasoning_tokens_display: "—".to_owned(),
+        image_input_tokens: None,
+        image_input_tokens_display: "—".to_owned(),
+        image_output_tokens: None,
+        image_output_tokens_display: "—".to_owned(),
+        image_request_count: None,
+        image_request_count_display: "—".to_owned(),
+        image_request_failed_count: None,
+        image_request_failed_count_display: "—".to_owned(),
+        total_tokens: None,
+        total_tokens_display: "—".to_owned(),
+        created_tokens: None,
+        created_tokens_display: "—".to_owned(),
+        read_tokens: None,
+        read_tokens_display: "—".to_owned(),
+        last_used_at: None,
+        last_used_at_display: "—".to_owned(),
+        cost_estimate_status: "unavailable".to_owned(),
+        known_cost_count: None,
+        partial_cost_count: None,
+        unknown_cost_count: None,
+        costs: Vec::new(),
+        models: Vec::new(),
+    }
+}
+
+pub(super) fn relative_time(value: DateTime<Utc>, now: DateTime<Utc>) -> String {
+    let elapsed = now.signed_duration_since(value);
+    if elapsed.num_seconds() < 0 {
+        return china_datetime(&value);
+    }
+    if elapsed.num_seconds() < 60 {
+        return "刚刚".to_owned();
+    }
+    if elapsed.num_minutes() < 60 {
+        return format!("{} 分钟前", elapsed.num_minutes());
+    }
+    if elapsed.num_hours() < 24 {
+        return format!("{} 小时前", elapsed.num_hours());
+    }
+    format!("{} 天前", elapsed.num_days())
+}
+
+pub(super) fn china_offset() -> FixedOffset {
+    FixedOffset::east_opt(8 * 60 * 60).expect("UTC+8 is a valid fixed offset")
+}
+
+pub(super) fn china_rfc3339(value: &DateTime<Utc>) -> String {
+    value.with_timezone(&china_offset()).to_rfc3339()
+}
+
+pub(super) fn china_datetime(value: &DateTime<Utc>) -> String {
+    value
+        .with_timezone(&china_offset())
+        .format("%Y-%m-%d %H:%M:%S")
+        .to_string()
+}
+
+pub(super) fn map_wire_error(error: WireValidationError) -> AdminError {
+    AdminError::bad_request(format!("{} 字段不合法", error.field()))
+}
+
+pub(super) fn map_service_error(error: AdminServiceError) -> AdminError {
+    super::super::wire::map_admin_service_error(error)
+}

backend/crates/gateway-api/src/admin/accounts/wire.rs

@@ -0,0 +1,932 @@
+//! 账号管理请求、响应与查询 wire contract。
+
+use super::*;
+
+#[derive(Debug, Clone)]
+pub struct AccountProxyUpdate(pub Option<gateway_core::account::OutboundProxy>);
+
+impl<'de> Deserialize<'de> for AccountProxyUpdate {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = String::deserialize(deserializer)?;
+        if value.is_empty() {
+            return Ok(Self(None));
+        }
+        gateway_core::account::OutboundProxy::parse(&value)
+            .map(|proxy| Self(Some(proxy)))
+            .map_err(serde::de::Error::custom)
+    }
+}
+
+pub(super) fn proxy_selection(
+    id: Option<String>,
+    url: Option<AccountProxyUpdate>,
+) -> Result<Option<gateway_admin::model::proxies::AccountProxySelection>, WireValidationError> {
+    use gateway_admin::model::proxies::AccountProxySelection;
+    match (id, url) {
+        (Some(_), Some(_)) => Err(WireValidationError::new("outboundProxyId")),
+        (Some(id), None) if id.is_empty() => Ok(Some(AccountProxySelection::Direct)),
+        (Some(id), None) => {
+            if id.len() > 128
+                || !id
+                    .bytes()
+                    .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'))
+            {
+                return Err(WireValidationError::new("outboundProxyId"));
+            }
+            Ok(Some(AccountProxySelection::Saved(id)))
+        }
+        (None, Some(value)) => Ok(Some(
+            value
+                .0
+                .map_or(AccountProxySelection::Direct, AccountProxySelection::Url),
+        )),
+        (None, None) => Ok(None),
+    }
+}
+
+/// 账号列表查询参数。
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct ListQuery {
+    pub page: Option<u32>,
+    pub page_size: Option<u32>,
+    pub provider: Option<String>,
+    pub group_id: Option<String>,
+    pub search: Option<String>,
+    pub status: Option<String>,
+    pub sort_by: Option<String>,
+    pub sort_direction: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct BatchUpdateAccountsRequest {
+    pub outbound_proxy_id: Option<String>,
+    pub outbound_proxy_url: Option<AccountProxyUpdate>,
+    pub account_ids: Vec<String>,
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_required_nullable")]
+    pub concurrency_limit: Option<u64>,
+    pub weight: u64,
+    pub group_ids: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct BatchUpdatedAccountsData {
+    account_ids: Vec<String>,
+    config_revision: u64,
+}
+
+impl From<AccountsUpdateResult> for BatchUpdatedAccountsData {
+    fn from(result: AccountsUpdateResult) -> Self {
+        Self {
+            account_ids: result
+                .account_ids
+                .into_iter()
+                .map(|id| id.to_string())
+                .collect(),
+            config_revision: result.config_revision.get(),
+        }
+    }
+}
+
+impl BatchUpdateAccountsRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        if self.account_ids.is_empty()
+            || self.account_ids.len() > MAX_ACCOUNT_GROUP_BATCH
+            || self
+                .account_ids
+                .iter()
+                .any(|id| require_account_id(id, "accountIds").is_err())
+            || self.account_ids.iter().collect::<BTreeSet<_>>().len() != self.account_ids.len()
+        {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        validate_wire_group_ids(&self.group_ids)?;
+        parse_concurrency_limit(self.concurrency_limit)?;
+        parse_account_weight(self.weight)?;
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<BatchUpdateAccounts, WireValidationError> {
+        self.validate()?;
+        Ok(BatchUpdateAccounts {
+            outbound_proxy: proxy_selection(self.outbound_proxy_id, self.outbound_proxy_url)?,
+            account_ids: self.account_ids,
+            enabled: self.enabled,
+            concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
+            weight: parse_account_weight(self.weight)?,
+            group_ids: validate_wire_group_ids(&self.group_ids)?,
+        })
+    }
+}
+
+impl ListQuery {
+    /// 解析并校验全部 wire 字段，生成 Admin 查询命令。
+    pub fn validate(self) -> Result<AccountListQuery, WireValidationError> {
+        let page = self.page.unwrap_or(1);
+        if page == 0 {
+            return Err(WireValidationError::new("page"));
+        }
+        let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
+        if page_size == 0 || page_size > MAX_PAGE_SIZE {
+            return Err(WireValidationError::new("pageSize"));
+        }
+        let provider_kind = parse_provider(self.provider.as_deref().unwrap_or("all"))?;
+        let group_filter = match self.group_id.as_deref().map(str::trim) {
+            None | Some("") => None,
+            Some("ungrouped") => Some(AccountGroupFilter::Ungrouped),
+            Some(value) => Some(AccountGroupFilter::Group(
+                AccountGroupId::new(value.to_owned())
+                    .map_err(|_| WireValidationError::new("groupId"))?,
+            )),
+        };
+        let search = self
+            .search
+            .map(|value| value.trim().to_owned())
+            .filter(|value| !value.is_empty());
+        if search.as_deref().is_some_and(|value| {
+            value.len() > MAX_SEARCH_BYTES || value.chars().any(char::is_control)
+        }) {
+            return Err(WireValidationError::new("search"));
+        }
+        let status = match self.status.as_deref().map(str::trim) {
+            None | Some("") => None,
+            Some(value) => Some(
+                DomainAccountStatus::parse(&value.to_ascii_lowercase())
+                    .ok_or_else(|| WireValidationError::new("status"))?,
+            ),
+        };
+        let sort = match (self.sort_by.as_deref(), self.sort_direction.as_deref()) {
+            (None, None) => None,
+            (Some(field), Some(direction)) => Some(AccountSort {
+                field: parse_sort_field(field).ok_or_else(|| WireValidationError::new("sortBy"))?,
+                direction: parse_sort_direction(direction)
+                    .ok_or_else(|| WireValidationError::new("sortDirection"))?,
+            }),
+            _ => return Err(WireValidationError::new("sort")),
+        };
+        Ok(AccountListQuery {
+            page,
+            page_size: PageSize::new(
+                u16::try_from(page_size).map_err(|_| WireValidationError::new("pageSize"))?,
+            )
+            .map_err(|_| WireValidationError::new("pageSize"))?,
+            provider_kind,
+            group_filter,
+            search,
+            status,
+            sort,
+        })
+    }
+}
+
+fn parse_provider(value: &str) -> Result<Option<ProviderKind>, WireValidationError> {
+    let value = value.trim();
+    if value.is_empty() || value.eq_ignore_ascii_case("all") {
+        return Ok(None);
+    }
+    ProviderKind::new(value.to_owned())
+        .map(Some)
+        .map_err(|_| WireValidationError::new("provider"))
+}
+
+fn parse_sort_field(value: &str) -> Option<AccountSortField> {
+    match value.trim() {
+        "email" => Some(AccountSortField::Email),
+        "status" => Some(AccountSortField::Status),
+        "planType" => Some(AccountSortField::PlanType),
+        "usage" => Some(AccountSortField::Usage),
+        "lastUsedAt" => Some(AccountSortField::LastUsedAt),
+        "expiresAt" => Some(AccountSortField::ExpiresAt),
+        _ => None,
+    }
+}
+
+fn parse_sort_direction(value: &str) -> Option<SortDirection> {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "asc" => Some(SortDirection::Asc),
+        "desc" => Some(SortDirection::Desc),
+        _ => None,
+    }
+}
+
+/// 账号列表响应数据。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountPageData {
+    pub items: Vec<AccountView>,
+    pub page: PageMeta,
+    pub summary: AccountSummaryView,
+}
+
+/// 账号概览计数。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountSummaryView {
+    pub total: u64,
+    pub normal: u64,
+    pub quota_exhausted: u64,
+    pub rate_limited: u64,
+    pub disabled: u64,
+    pub error: u64,
+}
+
+/// 一条安全账号视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountView {
+    pub outbound_proxy_endpoint: Option<String>,
+    pub id: String,
+    pub name: String,
+    pub provider: String,
+    pub groups: Vec<AccountGroupRefView>,
+    pub resource_ref: String,
+    pub email: Option<String>,
+    pub account_id: Option<String>,
+    pub user_id: Option<String>,
+    pub label: Option<String>,
+    pub plan_type: Option<String>,
+    /// 后端生成的套餐展示名称；缺失套餐时为“未知套餐”。
+    pub plan_type_display: String,
+    pub authentication_kind: String,
+    pub has_refresh_token: bool,
+    pub status: String,
+    /// `status == "error"` 时的具体原因；其余状态为 `null`。
+    pub error_reason: Option<String>,
+    /// 最近一次失败的上游错误描述；仅错误状态存在。
+    pub error_message: Option<String>,
+    pub enabled: bool,
+    pub concurrency_limit: Option<u32>,
+    pub weight: u16,
+    pub access_token_expires_at: Option<String>,
+    pub access_token_expires_at_display: Option<String>,
+    pub refresh_token_expires_at: Option<String>,
+    pub next_refresh_at: Option<String>,
+    pub added_at: String,
+    pub added_at_display: String,
+    pub updated_at: String,
+    pub updated_at_display: String,
+    pub quota: AccountQuotaView,
+    pub usage: AccountUsageView,
+}
+
+/// 容量估算仅供管理端展示；金额不是订阅账单或可消费余额。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaForecastData {
+    pub account_id: String,
+    pub generated_at: String,
+    pub forecasts: Vec<AccountQuotaForecastView>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaForecastView {
+    pub period: &'static str,
+    pub target_days: f64,
+    pub extrapolated: bool,
+    pub source: Option<QuotaForecastSourceView>,
+    pub unavailable_reason: Option<&'static str>,
+    pub low_sample: bool,
+    pub incomplete_cost: bool,
+    pub incomplete_tokens: bool,
+    pub estimated_tokens: Option<u64>,
+    pub estimated_tokens_display: String,
+    pub estimated_usd: Option<f64>,
+    pub estimated_usd_display: String,
+    pub remaining_tokens: Option<u64>,
+    pub remaining_tokens_display: String,
+    pub remaining_usd: Option<f64>,
+    pub remaining_usd_display: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct QuotaForecastSourceView {
+    pub label: String,
+    pub used_percent: Option<f64>,
+    pub used_percent_display: String,
+    pub observed_at: Option<String>,
+    pub observed_at_display: String,
+    pub reset_at: String,
+    pub tokens_display: String,
+    pub usd_display: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountGroupRefView {
+    pub id: String,
+    pub name: String,
+    pub color: String,
+    pub enabled: bool,
+}
+
+/// Provider quota 安全视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaView {
+    pub refreshed_at_display: String,
+    pub limit_reached: bool,
+    /// 429 临时限流（Redis 冷却）到期时间展示；非限流中为 `null`。
+    pub rate_limited_until: Option<String>,
+    pub windows: Vec<AccountQuotaWindowView>,
+}
+
+/// 一个 quota 时间窗口。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaWindowView {
+    pub key: String,
+    pub group: String,
+    pub limit_id: Option<String>,
+    pub limit_name: Option<String>,
+    pub role: Option<String>,
+    pub window_seconds: Option<u64>,
+    pub label_display: String,
+    pub window_label_display: String,
+    pub used_percent: Option<f64>,
+    pub used_percent_display: String,
+    pub limit_reached: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub local_usage: Option<serde_json::Value>,
+    pub reset_at_display: String,
+}
+
+/// 账号观测用量。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountUsageView {
+    pub window_label_display: String,
+    pub request_count: Option<u64>,
+    pub request_count_display: String,
+    pub input_tokens: Option<u64>,
+    pub input_tokens_display: String,
+    pub output_tokens: Option<u64>,
+    pub output_tokens_display: String,
+    pub cached_tokens: Option<u64>,
+    pub cached_tokens_display: String,
+    pub reasoning_tokens: Option<u64>,
+    pub reasoning_tokens_display: String,
+    pub image_input_tokens: Option<u64>,
+    pub image_input_tokens_display: String,
+    pub image_output_tokens: Option<u64>,
+    pub image_output_tokens_display: String,
+    pub image_request_count: Option<u64>,
+    pub image_request_count_display: String,
+    pub image_request_failed_count: Option<u64>,
+    pub image_request_failed_count_display: String,
+    pub total_tokens: Option<u64>,
+    pub total_tokens_display: String,
+    pub created_tokens: Option<u64>,
+    pub created_tokens_display: String,
+    pub read_tokens: Option<u64>,
+    pub read_tokens_display: String,
+    pub last_used_at: Option<String>,
+    pub last_used_at_display: String,
+    pub cost_estimate_status: String,
+    pub known_cost_count: Option<u64>,
+    pub partial_cost_count: Option<u64>,
+    pub unknown_cost_count: Option<u64>,
+    pub costs: Vec<CurrencyCostView>,
+    pub models: Vec<ModelUsageView>,
+}
+
+/// 凭据在单个上游模型上的观测用量。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ModelUsageView {
+    pub model: String,
+    pub request_count: u64,
+    pub request_count_display: String,
+    pub success_rate: Option<f64>,
+    pub success_rate_display: String,
+    pub input_tokens: Option<u64>,
+    pub input_tokens_display: String,
+    pub output_tokens: Option<u64>,
+    pub output_tokens_display: String,
+    pub cached_tokens: Option<u64>,
+    pub cached_tokens_display: String,
+    pub image_input_tokens: Option<u64>,
+    pub image_input_tokens_display: String,
+    pub image_output_tokens: Option<u64>,
+    pub image_output_tokens_display: String,
+    pub image_request_count: u64,
+    pub image_request_count_display: String,
+    pub image_request_failed_count: u64,
+    pub image_request_failed_count_display: String,
+    pub total_tokens: Option<u64>,
+    pub total_tokens_display: String,
+    pub billing_amount_usd: Option<String>,
+    pub billing_amount_usd_display: String,
+    pub cost_estimate_status: String,
+    pub known_cost_count: u64,
+    pub partial_cost_count: u64,
+    pub unknown_cost_count: u64,
+    pub costs: Vec<CurrencyCostView>,
+    pub last_used_at: String,
+    pub last_used_at_display: String,
+}
+
+/// 单一货币的可查询成本。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CurrencyCostView {
+    pub currency: String,
+    pub estimated_amount: String,
+    pub estimated_amount_display: String,
+}
+
+/// 账号详情类 GET 的固定 ID query。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountIdQuery {
+    pub account_id: String,
+}
+
+impl AccountIdQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 头像 GET 的固定 query；`version` 只参与浏览器缓存键，不进入上游请求。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountProfileAvatarQuery {
+    pub account_id: String,
+    pub version: Option<String>,
+}
+
+impl AccountProfileAvatarQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.version.as_deref().is_some_and(|version| {
+            version.is_empty()
+                || version.len() > MAX_AVATAR_VERSION_BYTES
+                || !version.bytes().all(|byte| byte.is_ascii_alphanumeric())
+        }) {
+            return Err(WireValidationError::new("version"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 敏感导出的固定 query；IDs 使用逗号分隔，禁止隐式导出全部账号。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountExportQuery {
+    pub account_ids: String,
+    pub confirm: String,
+}
+
+impl AccountExportQuery {
+    pub fn into_ids(self) -> Result<Vec<ProviderAccountId>, WireValidationError> {
+        if self.confirm != "export_sensitive_accounts" {
+            return Err(WireValidationError::new("confirm"));
+        }
+        let ids = self
+            .account_ids
+            .split(',')
+            .map(str::trim)
+            .filter(|id| !id.is_empty())
+            .map(ToOwned::to_owned)
+            .collect::<Vec<_>>();
+        if ids.is_empty()
+            || ids.len() > 200
+            || ids
+                .iter()
+                .any(|id| require_account_id(id, "accountIds").is_err())
+        {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        let unique = ids.iter().collect::<BTreeSet<_>>();
+        if unique.len() != ids.len() {
+            return Err(WireValidationError::new("accountIds"));
+        }
+        ids.into_iter()
+            .map(|id| {
+                ProviderAccountId::new(id).map_err(|_| WireValidationError::new("accountIds"))
+            })
+            .collect()
+    }
+}
+
+/// 账号运行期动作。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountActionRequest {
+    pub account_id: String,
+}
+
+impl AccountActionRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_id(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 主动额度重置卡消费请求。幂等键由 UI 生成并在不确定重试时复用，与官方一致。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountResetCreditConsumeRequest {
+    pub account_id: String,
+    #[serde(default)]
+    pub credit_id: Option<String>,
+    pub redeem_request_id: String,
+}
+
+impl AccountResetCreditConsumeRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.credit_id.as_deref().is_some_and(|value| {
+            let value = value.trim();
+            value.is_empty() || value.len() > 512 || value.chars().any(char::is_control)
+        }) {
+            return Err(WireValidationError::new("creditId"));
+        }
+        let value = self.redeem_request_id.trim();
+        let redeem_request_id =
+            Uuid::parse_str(value).map_err(|_| WireValidationError::new("redeemRequestId"))?;
+        if redeem_request_id.get_version() != Some(Version::Random)
+            || redeem_request_id.hyphenated().to_string() != value
+        {
+            return Err(WireValidationError::new("redeemRequestId"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(self) -> Result<ConsumeProviderResetCredit, WireValidationError> {
+        self.validate()?;
+        Ok(ConsumeProviderResetCredit {
+            account_id: ProviderAccountId::new(self.account_id)
+                .map_err(|_| WireValidationError::new("accountId"))?,
+            credit_id: self.credit_id.map(|value| value.trim().to_owned()),
+            redeem_request_id: Uuid::parse_str(&self.redeem_request_id)
+                .map_err(|_| WireValidationError::new("redeemRequestId"))?,
+        })
+    }
+}
+
+/// 手工 OAuth 刷新会变更持久 credential。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountRefreshRequest {
+    pub account_id: String,
+}
+
+impl AccountRefreshRequest {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")
+    }
+
+    pub(super) fn into_command(self) -> Result<ProviderAccountId, WireValidationError> {
+        self.validate()?;
+        ProviderAccountId::new(self.account_id).map_err(|_| WireValidationError::new("accountId"))
+    }
+}
+
+/// 连接测试 query；测试仍经唯一 Core/Provider 模型请求路径执行。
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct AccountTestQuery {
+    pub account_id: String,
+    pub model_id: String,
+}
+
+impl AccountTestQuery {
+    pub fn validate(&self) -> Result<(), WireValidationError> {
+        require_account_id(&self.account_id, "accountId")?;
+        if self.model_id.trim().is_empty() || self.model_id.chars().any(char::is_control) {
+            return Err(WireValidationError::new("modelId"));
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_command(
+        self,
+    ) -> Result<(ProviderAccountId, UpstreamModelId), WireValidationError> {
+        self.validate()?;
+        Ok((
+            ProviderAccountId::new(self.account_id)
+                .map_err(|_| WireValidationError::new("accountId"))?,
+            UpstreamModelId::new(self.model_id).map_err(|_| WireValidationError::new("modelId"))?,
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountModelView {
+    pub id: String,
+    pub label: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountModelsData {
+    pub models: Vec<AccountModelView>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountRefreshData {
+    pub account: AccountView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountQuotaData {
+    pub account: AccountView,
+}
+
+/// Provider 官方个人资料统计响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileStatisticsData {
+    pub display_name: Option<String>,
+    pub username: Option<String>,
+    pub image_url: Option<String>,
+    pub has_stats_error: bool,
+    pub summary: AccountProfileStatisticsSummaryView,
+    pub daily_usage: Option<Vec<AccountProfileDailyUsageView>>,
+    pub activity_insights: AccountProfileActivityInsightsView,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileStatisticsSummaryView {
+    pub total_text_tokens: Option<u64>,
+    pub peak_tokens: Option<u64>,
+    pub longest_task_duration_ms: Option<u64>,
+    pub current_streak_days: Option<u64>,
+    pub longest_streak_days: Option<u64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileDailyUsageView {
+    pub date: String,
+    pub tokens: u64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileActivityInsightsView {
+    pub fast_mode_percent: Option<f64>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_effort_percent: Option<f64>,
+    pub skills_explored: Option<u64>,
+    pub total_skills_used: Option<u64>,
+    pub total_threads: Option<u64>,
+    pub invocations: Option<Vec<AccountProfileInvocationView>>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountProfileInvocationView {
+    #[serde(rename = "type")]
+    pub invocation_type: String,
+    pub plugin_id: Option<String>,
+    pub plugin_name: Option<String>,
+    pub skill_id: Option<String>,
+    pub skill_name: Option<String>,
+    pub usage_count: Option<u64>,
+}
+
+impl From<ProviderProfileStatistics> for AccountProfileStatisticsData {
+    fn from(statistics: ProviderProfileStatistics) -> Self {
+        Self {
+            display_name: statistics.display_name,
+            username: statistics.username,
+            image_url: statistics.image_url,
+            has_stats_error: statistics.has_stats_error,
+            summary: profile_statistics_summary_view(statistics.summary),
+            daily_usage: statistics
+                .daily_usage
+                .map(|daily| daily.into_iter().map(profile_daily_usage_view).collect()),
+            activity_insights: profile_activity_insights_view(statistics.activity_insights),
+        }
+    }
+}
+
+const fn profile_statistics_summary_view(
+    summary: ProviderProfileStatisticsSummary,
+) -> AccountProfileStatisticsSummaryView {
+    AccountProfileStatisticsSummaryView {
+        total_text_tokens: summary.total_text_tokens,
+        peak_tokens: summary.peak_tokens,
+        longest_task_duration_ms: summary.longest_task_duration_ms,
+        current_streak_days: summary.current_streak_days,
+        longest_streak_days: summary.longest_streak_days,
+    }
+}
+
+fn profile_daily_usage_view(daily: ProviderProfileDailyUsage) -> AccountProfileDailyUsageView {
+    AccountProfileDailyUsageView {
+        date: daily.date.to_string(),
+        tokens: daily.tokens,
+    }
+}
+
+fn profile_activity_insights_view(
+    insights: ProviderProfileActivityInsights,
+) -> AccountProfileActivityInsightsView {
+    AccountProfileActivityInsightsView {
+        fast_mode_percent: insights.fast_mode_percent,
+        reasoning_effort: insights.reasoning_effort,
+        reasoning_effort_percent: insights.reasoning_effort_percent,
+        skills_explored: insights.skills_explored,
+        total_skills_used: insights.total_skills_used,
+        total_threads: insights.total_threads,
+        invocations: insights.invocations.map(|invocations| {
+            invocations
+                .into_iter()
+                .map(profile_invocation_view)
+                .collect()
+        }),
+    }
+}
+
+fn profile_invocation_view(invocation: ProviderProfileInvocation) -> AccountProfileInvocationView {
+    AccountProfileInvocationView {
+        invocation_type: invocation.invocation_type,
+        plugin_id: invocation.plugin_id,
+        plugin_name: invocation.plugin_name,
+        skill_id: invocation.skill_id,
+        skill_name: invocation.skill_name,
+        usage_count: invocation.usage_count,
+    }
+}
+
+/// 主动额度重置卡列表响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditsData {
+    pub available_count: u64,
+    pub credits: Vec<AccountResetCreditView>,
+}
+
+/// 一张安全主动额度重置卡视图。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditView {
+    pub id: String,
+    pub status: Option<String>,
+    pub title: Option<String>,
+    pub expires_at: Option<String>,
+    pub reset_type: Option<String>,
+}
+
+/// 主动额度重置卡消费响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountResetCreditResultData {
+    pub code: String,
+    pub credit: Option<AccountResetCreditView>,
+}
+
+impl From<ProviderResetCredit> for AccountResetCreditView {
+    fn from(credit: ProviderResetCredit) -> Self {
+        Self {
+            id: credit.id,
+            status: credit.status,
+            title: credit.title,
+            expires_at: credit.expires_at.map(|value| value.to_rfc3339()),
+            reset_type: credit.reset_type,
+        }
+    }
+}
+
+impl From<ProviderResetCredits> for AccountResetCreditsData {
+    fn from(credits: ProviderResetCredits) -> Self {
+        Self {
+            available_count: credits.available_count,
+            credits: credits
+                .credits
+                .into_iter()
+                .map(AccountResetCreditView::from)
+                .collect(),
+        }
+    }
+}
+
+impl From<ProviderResetCreditResult> for AccountResetCreditResultData {
+    fn from(result: ProviderResetCreditResult) -> Self {
+        Self {
+            code: result.code,
+            credit: result.credit.map(AccountResetCreditView::from),
+        }
+    }
+}
+
+/// Provider-owned 明文导出文档；Debug 永远不输出内部 JSON。
+#[derive(Serialize)]
+#[serde(transparent)]
+pub struct AccountExportData(Value);
+
+impl AccountExportData {
+    #[must_use]
+    pub const fn new(value: Value) -> Self {
+        Self(value)
+    }
+
+    pub(super) fn from_result(bundle: AccountExportBundle) -> Self {
+        let documents = bundle
+            .documents
+            .into_iter()
+            .map(|document| {
+                serde_json::json!({
+                    "provider": document.provider_kind.to_string(),
+                    "document": provider_document_value(document.document),
+                })
+            })
+            .collect::<Vec<_>>();
+        Self::new(serde_json::json!({
+            "exportedAt": bundle.exported_at.to_rfc3339(),
+            "documents": documents,
+        }))
+    }
+}
+
+impl fmt::Debug for AccountExportData {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("AccountExportData(<redacted>)")
+    }
+}
+
+pub struct AccountConnectionTestEvent {
+    pub data: Value,
+}
+
+impl From<DomainConnectionTestEvent> for AccountConnectionTestEvent {
+    fn from(event: DomainConnectionTestEvent) -> Self {
+        let data = match event {
+            DomainConnectionTestEvent::Started { model } => serde_json::json!({
+                "type": "test_start",
+                "model": model,
+                "text": "正在连接上游 Responses"
+            }),
+            DomainConnectionTestEvent::Request {
+                model,
+                input_text,
+                stream,
+                store,
+            } => serde_json::json!({
+                "type": "request",
+                "payload": {
+                    "model": model,
+                    "input": [{
+                        "role": "user",
+                        "content": [{ "type": "input_text", "text": input_text }]
+                    }],
+                    "stream": stream,
+                    "store": store
+                }
+            }),
+            DomainConnectionTestEvent::Content { text } => {
+                serde_json::json!({ "type": "content", "text": text })
+            }
+            DomainConnectionTestEvent::Completed => serde_json::json!({
+                "type": "test_complete",
+                "success": true
+            }),
+            DomainConnectionTestEvent::Failed {
+                source,
+                gateway_error_code,
+                send_state,
+                message,
+                provider_error_code,
+                provider_error_type,
+                upstream_status,
+                upstream_content_type,
+                upstream_body,
+            } => serde_json::json!({
+                "type": "error",
+                "source": source.as_str(),
+                "gatewayErrorCode": gateway_error_code.as_str(),
+                "sendState": send_state.map(gateway_core::upstream::UpstreamSendState::as_str),
+                "error": message,
+                "providerErrorCode": provider_error_code,
+                "providerErrorType": provider_error_type,
+                "upstreamStatus": upstream_status,
+                "upstreamContentType": upstream_content_type,
+                "upstreamBody": upstream_body
+            }),
+        };
+        Self { data }
+    }
+}

backend/crates/gateway-api/src/admin/auth.rs

@@ -3,9 +3,13 @@
 use std::fmt;
 
 use axum::{
-    Json, Router,
+    Router,
     extract::{FromRequestParts, State},
-    http::{HeaderMap, HeaderValue, StatusCode, header::SET_COOKIE, request::Parts},
+    http::{
+        HeaderMap, HeaderValue, StatusCode,
+        header::{ORIGIN, SET_COOKIE},
+        request::Parts,
+    },
     response::{IntoResponse, Response},
     routing::{get, post},
 };
@@ -15,18 +19,37 @@ use gateway_admin::{
 };
 use serde::{Deserialize, Serialize};
 use tower_http::request_id::RequestId;
+use url::Url;
 
-use super::{AdminEnvelope, AdminError, AdminResponse};
+use super::{AdminEnvelope, AdminError, AdminJson, AdminResponse};
 
 const REQUEST_ID_HEADER: &str = "x-request-id";
 const ADMIN_SESSION_COOKIE: &str = "cpr_admin_session";
-const ADMIN_SESSION_COOKIE_ATTRS: &str = "Path=/; Secure; HttpOnly; SameSite=Lax";
 
 /// 所有管理 HTTP 模块从 state 消费同一个认证用例端口。
 pub trait AdminSessionState {
     fn admin_services(&self) -> &AdminServices;
 }
 
+fn admin_session_cookie_attrs(headers: &HeaderMap) -> &'static str {
+    // 同源管理端的 POST 由浏览器携带 Origin，HTTPS 反代回源 HTTP 不改变它。
+    // 只对明确的 HTTP 来源放宽；缺失、opaque 或非法来源继续使用 Secure。
+    let http_origin = headers.get_all(ORIGIN).iter().count() == 1
+        && headers
+            .get(ORIGIN)
+            .and_then(|value| value.to_str().ok())
+            .is_some_and(|origin| {
+                Url::parse(origin).is_ok_and(|url| {
+                    url.scheme() == "http" && url.origin().ascii_serialization() == origin
+                })
+            });
+    if http_origin {
+        "Path=/; HttpOnly; SameSite=Lax"
+    } else {
+        "Path=/; Secure; HttpOnly; SameSite=Lax"
+    }
+}
+
 /// 已通过管理员会话或部署级管理 API Key 鉴权的请求。
 pub struct AdminAuth {
     context: AdminRequestContext,
@@ -37,11 +60,6 @@ impl AdminAuth {
     pub const fn context(&self) -> &AdminRequestContext {
         &self.context
     }
-
-    #[must_use]
-    pub fn into_context(self) -> AdminRequestContext {
-        self.context
-    }
 }
 
 impl<S> FromRequestParts<S> for AdminAuth
@@ -52,8 +70,7 @@ where
 
     async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
         let principal = require_admin_auth(state, &parts.headers).await?;
-        let request_id = admin_request_id(parts)
-            .ok_or_else(|| AdminError::internal("Missing admin request context"))?;
+        let request_id = admin_request_id(parts).ok_or_else(AdminError::internal)?;
         Ok(Self {
             context: AdminRequestContext {
                 principal,
@@ -90,7 +107,7 @@ where
     {
         Ok(Some(admin_user_id)) => Ok(admin_user_id),
         Ok(None) => Err(AdminError::admin_session_required()),
-        Err(_) => Err(AdminError::internal("Failed to validate admin session")),
+        Err(_) => Err(AdminError::internal()),
     }
 }
 
@@ -107,7 +124,7 @@ where
         {
             Ok(true) => Ok(AdminPrincipal::ApiKey),
             Ok(false) => Err(AdminError::invalid_admin_api_key()),
-            Err(_) => Err(AdminError::internal("Failed to validate admin API key")),
+            Err(_) => Err(AdminError::internal()),
         };
     }
 
@@ -209,7 +226,8 @@ where
 
 async fn login<S>(
     State(state): State<S>,
-    Json(payload): Json<AdminLoginRequest>,
+    headers: HeaderMap,
+    AdminJson(payload): AdminJson<AdminLoginRequest>,
 ) -> Result<Response, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -227,13 +245,13 @@ where
     )
     .into_response();
     let cookie = format!(
-        "{ADMIN_SESSION_COOKIE}={}; {ADMIN_SESSION_COOKIE_ATTRS}",
-        session.session_id
+        "{ADMIN_SESSION_COOKIE}={}; {}",
+        session.session_id,
+        admin_session_cookie_attrs(&headers)
     );
     response.headers_mut().insert(
         SET_COOKIE,
-        HeaderValue::from_str(&cookie)
-            .map_err(|_| AdminError::internal("Failed to create admin session cookie"))?,
+        HeaderValue::from_str(&cookie).map_err(|_| AdminError::internal())?,
     );
     Ok(response)
 }
@@ -250,7 +268,7 @@ where
         .auth()
         .validate_session(admin_session_cookie(&headers).as_deref())
         .await
-        .map_err(|_| AdminError::internal("Failed to validate admin session"))?;
+        .map_err(|_| AdminError::internal())?;
     Ok(AdminResponse::new(
         StatusCode::OK,
         AdminEnvelope::ok(AdminSessionStatusData::new(authenticated)),
@@ -267,11 +285,13 @@ where
     let mut response =
         AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(AdminLogoutData::new()))
             .into_response();
-    let cookie = format!("{ADMIN_SESSION_COOKIE}=; {ADMIN_SESSION_COOKIE_ATTRS}; Max-Age=0");
+    let cookie = format!(
+        "{ADMIN_SESSION_COOKIE}=; {}; Max-Age=0",
+        admin_session_cookie_attrs(&headers)
+    );
     response.headers_mut().insert(
         SET_COOKIE,
-        HeaderValue::from_str(&cookie)
-            .map_err(|_| AdminError::internal("Failed to clear admin session cookie"))?,
+        HeaderValue::from_str(&cookie).map_err(|_| AdminError::internal())?,
     );
     Ok(response)
 }
@@ -287,6 +307,6 @@ fn admin_session_cookie(headers: &HeaderMap) -> Option<String> {
 fn map_login_error(error: LoginError) -> AdminError {
     match error {
         LoginError::InvalidCredentials => AdminError::invalid_admin_credentials(),
-        LoginError::Unavailable => AdminError::internal("Failed to create admin session"),
+        LoginError::Unavailable => AdminError::internal(),
     }
 }

backend/crates/gateway-api/src/admin/backups.rs

@@ -3,8 +3,8 @@
 //! 路径统一位于 `/api/admin/settings/backups/*`，内部由独立 `BackupService` 承担业务。
 
 use axum::{
-    Json, Router,
-    extract::{Query, State},
+    Router,
+    extract::State,
     http::StatusCode,
     response::IntoResponse,
     routing::{get, post},
@@ -18,8 +18,8 @@ use secrecy::{ExposeSecret as _, SecretString};
 use serde::{Deserialize, Serialize};
 
 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminPageData, AdminResponse, AdminSessionState,
-    PageMeta, wire::map_admin_service_error,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminPageData, AdminQuery, AdminResponse,
+    AdminSessionState, PageMeta, wire::map_admin_service_error,
 };
 
 /// 备份设置视图；`secretAccessKey` 返回已保存的明文凭据，由前端掩码显示。
@@ -256,7 +256,7 @@ where
 async fn update_backup_storage<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<UpdateBackupStorageRequest>,
+    AdminJson(request): AdminJson<UpdateBackupStorageRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -304,7 +304,7 @@ where
 async fn update_backup_schedule<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<UpdateBackupScheduleRequest>,
+    AdminJson(request): AdminJson<UpdateBackupScheduleRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -331,28 +331,28 @@ where
 async fn backup_records<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<BackupRecordsQuery>,
+    AdminQuery(query): AdminQuery<BackupRecordsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
 {
     let page_size = gateway_admin::model::PageSize::new(query.page_size.unwrap_or(20))
-        .map_err(|_| AdminError::bad_request("Invalid pageSize"))?;
+        .map_err(|_| AdminError::bad_request("pageSize 不合法"))?;
     let page = query.page.unwrap_or(1);
     if page == 0 {
-        return Err(AdminError::bad_request("Invalid page"));
+        return Err(AdminError::bad_request("page 不合法"));
     }
     let status = match query.status.as_deref() {
         None => None,
         Some(value) => BackupStatus::parse(value)
             .map(Some)
-            .ok_or_else(|| AdminError::bad_request("Invalid status"))?,
+            .ok_or_else(|| AdminError::bad_request("status 不合法"))?,
     };
     let trigger = match query.trigger.as_deref() {
         None => None,
         Some(value) => BackupTriggerKind::parse(value)
             .map(Some)
-            .ok_or_else(|| AdminError::bad_request("Invalid trigger"))?,
+            .ok_or_else(|| AdminError::bad_request("trigger 不合法"))?,
     };
     let domain_query = gateway_admin::model::backup::BackupRecordListQuery {
         page,
@@ -386,7 +386,7 @@ where
 async fn create_backup<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    body: Option<Json<CreateBackupRequest>>,
+    body: Option<AdminJson<CreateBackupRequest>>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -417,7 +417,7 @@ pub struct CreateBackupRequest {
 async fn download_backup_url<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<BackupIdRequest>,
+    AdminJson(request): AdminJson<BackupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -437,7 +437,7 @@ where
 async fn delete_backup<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(request): Json<BackupIdRequest>,
+    AdminJson(request): AdminJson<BackupIdRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -455,5 +455,5 @@ where
 }
 
 fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Backup service unavailable")
+    map_admin_service_error(error)
 }

backend/crates/gateway-api/src/admin/client_keys.rs

@@ -11,28 +11,39 @@ use gateway_admin::model::client_keys::{
     CreatedClientKey, DeleteClientKey, SetClientKeyEnabled, SortDirection, UpdateClientKey,
 };
 use gateway_core::{
-    policy::{ClientApiKeyId, RateLimits},
+    engine::budget::ClientBudgetLimits,
+    metering::Decimal,
+    policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits},
     routing::AccountGroupId,
 };
 use serde::{Deserialize, Serialize};
 
 use axum::{
-    Json, Router,
-    extract::{Query, State},
+    Router,
+    extract::State,
     http::{HeaderValue, StatusCode, header::CACHE_CONTROL},
     response::{IntoResponse, Response},
     routing::{get, post},
 };
 
 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, WireValidationError,
-    wire::map_admin_service_error,
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    WireValidationError, wire::map_admin_service_error,
 };
 
 const MAX_CURSOR_BYTES: usize = 512;
 const MAX_SEARCH_BYTES: usize = 256;
 const DEFAULT_PAGE_SIZE: u16 = 50;
 
+fn parse_budget(
+    value: Option<String>,
+    field: &'static str,
+) -> Result<Option<Decimal>, WireValidationError> {
+    value
+        .map(|value| value.parse().map_err(|_| WireValidationError::new(field)))
+        .transpose()
+}
+
 /// Client Key 列表查询。
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
@@ -59,9 +70,7 @@ impl ListClientKeysQuery {
         }
         let search = self.search.map(|search| search.trim().to_owned());
         if search.as_deref().is_some_and(|search| {
-            search.len() > MAX_SEARCH_BYTES
-                || search.chars().any(char::is_control)
-                || contains_client_key_material(search)
+            search.len() > MAX_SEARCH_BYTES || search.chars().any(char::is_control)
         }) {
             return Err(WireValidationError::new("search"));
         }
@@ -132,14 +141,27 @@ impl ClientKeySort {
 }
 
 /// 创建 Client Key 请求。
-#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[derive(Clone, PartialEq, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct CreateClientKeyRequest {
+    custom_key: Option<String>,
     name: String,
     label: Option<String>,
     group_ids: Vec<String>,
     max_concurrency: u64,
     requests_per_minute: u64,
+    daily_limit_usd: Option<String>,
+    weekly_limit_usd: Option<String>,
+}
+
+impl fmt::Debug for CreateClientKeyRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CreateClientKeyRequest")
+            .field("name", &self.name)
+            .field("custom_key", &"[REDACTED]")
+            .finish_non_exhaustive()
+    }
 }
 
 impl CreateClientKeyRequest {
@@ -151,9 +173,20 @@ impl CreateClientKeyRequest {
         validate_limit(self.max_concurrency, "maxConcurrency")?;
         validate_limit(self.requests_per_minute, "requestsPerMinute")?;
         Ok(CreateClientKey {
+            custom_key: self
+                .custom_key
+                .filter(|key| !key.is_empty())
+                .map(PlaintextClientApiKey::new)
+                .transpose()
+                .map_err(|_| WireValidationError::new("customKey"))?,
             name: self.name,
             label: self.label,
             group_ids,
+            budget: ClientBudgetLimits {
+                daily_usd: parse_budget(self.daily_limit_usd, "dailyLimitUsd")?.unwrap_or_default(),
+                weekly_usd: parse_budget(self.weekly_limit_usd, "weeklyLimitUsd")?
+                    .unwrap_or_default(),
+            },
             limits: RateLimits {
                 max_concurrency: self.max_concurrency,
                 requests_per_minute: self.requests_per_minute,
@@ -172,6 +205,8 @@ pub struct UpdateClientKeyRequest {
     group_ids: Vec<String>,
     max_concurrency: u64,
     requests_per_minute: u64,
+    daily_limit_usd: Option<String>,
+    weekly_limit_usd: Option<String>,
 }
 
 impl UpdateClientKeyRequest {
@@ -188,6 +223,8 @@ impl UpdateClientKeyRequest {
             name: self.name,
             label: self.label,
             group_ids,
+            daily_limit_usd: parse_budget(self.daily_limit_usd, "dailyLimitUsd")?,
+            weekly_limit_usd: parse_budget(self.weekly_limit_usd, "weeklyLimitUsd")?,
             limits: RateLimits {
                 max_concurrency: self.max_concurrency,
                 requests_per_minute: self.requests_per_minute,
@@ -247,6 +284,12 @@ pub struct ClientKeyView {
     enabled: bool,
     max_concurrency: u64,
     requests_per_minute: u64,
+    daily_limit_usd: String,
+    weekly_limit_usd: String,
+    daily_used_usd: String,
+    weekly_used_usd: String,
+    daily_resets_at: Option<DateTime<Utc>>,
+    weekly_resets_at: Option<DateTime<Utc>>,
     created_at: DateTime<Utc>,
     updated_at: DateTime<Utc>,
     last_used_at: Option<DateTime<Utc>>,
@@ -292,6 +335,12 @@ impl From<ClientKeyRecord> for ClientKeyView {
             enabled: record.enabled,
             max_concurrency: record.limits.max_concurrency,
             requests_per_minute: record.limits.requests_per_minute,
+            daily_limit_usd: record.budget.limits.daily_usd.canonical(),
+            weekly_limit_usd: record.budget.limits.weekly_usd.canonical(),
+            daily_used_usd: record.budget.daily_used_usd.canonical(),
+            weekly_used_usd: record.budget.weekly_used_usd.canonical(),
+            daily_resets_at: record.budget.daily_resets_at.map(DateTime::from),
+            weekly_resets_at: record.budget.weekly_resets_at.map(DateTime::from),
             created_at: record.created_at,
             updated_at: record.updated_at,
             last_used_at: record.last_used_at,
@@ -627,15 +676,6 @@ fn validate_optional_text(
     Ok(())
 }
 
-fn contains_client_key_material(value: &str) -> bool {
-    value.as_bytes().windows(46).any(|window| {
-        &window[..3] == b"sk_"
-            && window[3..]
-                .iter()
-                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
-    })
-}
-
 /// 构造固定 GET/POST 且 ID 仅位于 query/body 的 Client API Key 路由。
 pub fn router<S>() -> Router<S>
 where
@@ -669,7 +709,7 @@ where
 async fn list_client_keys<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<ListClientKeysQuery>,
+    AdminQuery(query): AdminQuery<ListClientKeysQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -680,15 +720,14 @@ where
         .list(query.into_command().map_err(map_wire_error)?)
         .await
         .map_err(map_service_error)?;
-    let data = ClientKeyListData::try_from(result)
-        .map_err(|_| AdminError::internal("Failed to encode client key cursor"))?;
+    let data = ClientKeyListData::try_from(result).map_err(|_| AdminError::internal())?;
     Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }
 
 async fn create_client_key<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(payload): Json<CreateClientKeyRequest>,
+    AdminJson(payload): AdminJson<CreateClientKeyRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -709,7 +748,7 @@ where
 async fn reveal_client_key<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<ClientKeyIdQuery>,
+    AdminQuery(query): AdminQuery<ClientKeyIdQuery>,
 ) -> Result<Response, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -735,7 +774,7 @@ where
 async fn update_client_key<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(payload): Json<UpdateClientKeyRequest>,
+    AdminJson(payload): AdminJson<UpdateClientKeyRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -753,7 +792,7 @@ where
 async fn disable_client_key<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(payload): Json<ClientKeyMutationRequest>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -774,7 +813,7 @@ where
 async fn enable_client_key<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(payload): Json<ClientKeyMutationRequest>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -795,7 +834,7 @@ where
 async fn delete_client_key<S>(
     auth: AdminAuth,
     State(state): State<S>,
-    Json(payload): Json<ClientKeyMutationRequest>,
+    AdminJson(payload): AdminJson<ClientKeyMutationRequest>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -822,13 +861,14 @@ fn mutation_response(
 
 fn map_wire_error(error: WireValidationError) -> AdminError {
     match error.field() {
-        "cursor" => AdminError::bad_request("Invalid client key cursor"),
-        "clientKeyRevealNotFound" => AdminError::not_found("Client API key was not found"),
-        "clientKeyMutationNotFound" => AdminError::not_found("client API key was not found"),
-        _ => AdminError::bad_request("Invalid client API key request"),
+        "cursor" => AdminError::bad_request("Client API Key 游标不合法"),
+        "clientKeyRevealNotFound" | "clientKeyMutationNotFound" => {
+            AdminError::not_found("Client API Key 不存在")
+        }
+        _ => AdminError::bad_request("Client API Key 请求不合法"),
     }
 }
 
 fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Configuration repository unavailable")
+    map_admin_service_error(error)
 }

backend/crates/gateway-api/src/admin/extract.rs

@@ -0,0 +1,87 @@
+//! 管理端 JSON 与 Query extractor 的稳定 rejection 映射。
+
+use axum::{
+    Json,
+    extract::{
+        FromRequest, FromRequestParts, OptionalFromRequest, Query, Request,
+        rejection::{JsonRejection, QueryRejection},
+    },
+    http::{StatusCode, request::Parts},
+};
+use serde::de::DeserializeOwned;
+
+use super::AdminError;
+
+/// 将 Axum JSON rejection 收口为管理端错误信封。
+pub struct AdminJson<T>(pub T);
+
+impl<T, S> FromRequest<S> for AdminJson<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request(request: Request, state: &S) -> Result<Self, Self::Rejection> {
+        <Json<T> as FromRequest<S>>::from_request(request, state)
+            .await
+            .map(|Json(value)| Self(value))
+            .map_err(map_json_rejection)
+    }
+}
+
+impl<T, S> OptionalFromRequest<S> for AdminJson<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request(request: Request, state: &S) -> Result<Option<Self>, Self::Rejection> {
+        <Json<T> as OptionalFromRequest<S>>::from_request(request, state)
+            .await
+            .map(|value| value.map(|Json(value)| Self(value)))
+            .map_err(map_json_rejection)
+    }
+}
+
+/// 将 Axum Query rejection 收口为管理端错误信封。
+pub struct AdminQuery<T>(pub T);
+
+impl<T, S> FromRequestParts<S> for AdminQuery<T>
+where
+    T: DeserializeOwned,
+    S: Send + Sync,
+{
+    type Rejection = AdminError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        Query::<T>::from_request_parts(parts, state)
+            .await
+            .map(|Query(value)| Self(value))
+            .map_err(map_query_rejection)
+    }
+}
+
+fn map_json_rejection(rejection: JsonRejection) -> AdminError {
+    let status = rejection.status();
+    match rejection {
+        JsonRejection::JsonSyntaxError(_) => AdminError::malformed_json(),
+        JsonRejection::JsonDataError(_) => {
+            AdminError::invalid_request(StatusCode::UNPROCESSABLE_ENTITY, "请求字段不合法")
+        }
+        JsonRejection::MissingJsonContentType(_) => AdminError::invalid_request(
+            StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            "请求必须使用 application/json",
+        ),
+        JsonRejection::BytesRejection(_) if status == StatusCode::PAYLOAD_TOO_LARGE => {
+            AdminError::invalid_request(status, "请求体过大")
+        }
+        JsonRejection::BytesRejection(_) => AdminError::internal(),
+        _ => AdminError::invalid_request(status, "请求体不合法"),
+    }
+}
+
+fn map_query_rejection(_: QueryRejection) -> AdminError {
+    AdminError::bad_request("请求参数不合法")
+}

backend/crates/gateway-api/src/admin/mod.rs

@@ -5,6 +5,7 @@ use axum::{
     http::{HeaderValue, header},
     middleware,
     response::Response,
+    routing::any,
 };
 
 pub mod account_groups;
@@ -12,13 +13,16 @@ pub mod accounts;
 pub mod auth;
 pub mod backups;
 pub mod client_keys;
+mod extract;
 pub mod observability;
 pub mod presenter;
+pub mod proxies;
 pub mod settings;
 pub mod system;
 pub mod wire;
 
 pub use auth::{AdminAuth, AdminSessionState};
+pub use extract::{AdminJson, AdminQuery};
 pub use wire::{
     ADMIN_OK_CODE, ADMIN_OK_MESSAGE, AdminEnvelope, AdminError, AdminErrorBody, AdminErrorCode,
     AdminPageData, AdminResponse, PageMeta, WireValidationError,
@@ -31,6 +35,7 @@ where
 {
     Router::new()
         .merge(account_groups::router::<S>())
+        .merge(proxies::router::<S>())
         .merge(accounts::router::<S>())
         .merge(auth::router::<S>())
         .merge(backups::router::<S>())
@@ -38,12 +43,24 @@ where
         .merge(observability::router::<S>())
         .merge(settings::router::<S>())
         .merge(system::router::<S>())
+        .method_not_allowed_fallback(method_not_allowed)
+        .route("/api/admin", any(admin_not_found))
+        .route("/api/admin/{*path}", any(admin_not_found))
         .layer(middleware::map_response(no_store))
 }
 
+async fn method_not_allowed() -> AdminError {
+    AdminError::method_not_allowed()
+}
+
+async fn admin_not_found() -> AdminError {
+    AdminError::admin_route_not_found()
+}
+
 async fn no_store(mut response: Response) -> Response {
     response
         .headers_mut()
-        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
+        .entry(header::CACHE_CONTROL)
+        .or_insert(HeaderValue::from_static("no-store"));
     response
 }

backend/crates/gateway-api/src/admin/observability/mod.rs

@@ -1,15 +1,8 @@
 //! Dashboard、用量与诊断查询的 wire 映射和固定路由。
 
-use std::{collections::BTreeMap, num::NonZeroU32};
+use std::collections::BTreeMap;
 
-use axum::{
-    Router,
-    extract::{Query, State},
-    http::StatusCode,
-    response::IntoResponse,
-    routing::get,
-};
-use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use axum::{Router, extract::State, http::StatusCode, response::IntoResponse, routing::get};
 use chrono::{DateTime, Duration, Utc};
 use gateway_admin::model::{PageSize as DomainPageSize, observability as domain};
 use serde::{Deserialize, Serialize};
@@ -17,7 +10,7 @@ use serde_json::Value;
 
 use super::presenter::{format_compact_number, format_decimal_currency, format_number};
 use super::{
-    AdminAuth, AdminEnvelope, AdminError, AdminResponse, AdminSessionState, PageMeta,
+    AdminAuth, AdminEnvelope, AdminError, AdminQuery, AdminResponse, AdminSessionState,
     WireValidationError, wire::map_admin_service_error,
 };
 

backend/crates/gateway-api/src/admin/observability/presenter.rs

@@ -17,6 +17,21 @@ pub(crate) fn display_duration(value: Option<u64>) -> String {
     }
 }
 
+fn display_duration_f64(value: Option<f64>) -> String {
+    let Some(value) = value.filter(|value| value.is_finite() && *value >= 0.0) else {
+        return "—".to_owned();
+    };
+    if value < 1_000.0 {
+        format!("{value:.0} ms")
+    } else if value < 60_000.0 {
+        format!("{:.2} s", value / 1_000.0)
+    } else if value < 3_600_000.0 {
+        format!("{:.1} min", value / 60_000.0)
+    } else {
+        format!("{:.1} h", value / 3_600_000.0)
+    }
+}
+
 pub(crate) fn display_rate(value: f64) -> String {
     if value.is_finite() {
         format!("{:.1}%", value * 100.0)
@@ -25,6 +40,10 @@ pub(crate) fn display_rate(value: f64) -> String {
     }
 }
 
+fn basis_points_rate(value: u64) -> f64 {
+    value as f64 / 10_000.0
+}
+
 pub(crate) fn china_datetime(value: &DateTime<Utc>) -> String {
     (*value + Duration::hours(8))
         .format("%Y-%m-%d %H:%M:%S")
@@ -127,6 +146,43 @@ pub(crate) fn token_details(record: &domain::UsageRecord) -> TokenDetailsView {
     }
 }
 
+pub(crate) fn usage_list_token_details(record: &domain::UsageListRecord) -> TokenDetailsView {
+    TokenDetailsView {
+        input_tokens: record.input_tokens,
+        output_tokens: record.output_tokens,
+        cached_tokens: record.cached_tokens,
+        cache_write_tokens: record.cache_write_tokens,
+        reasoning_tokens: record.reasoning_tokens,
+        image_input_tokens: record.image_input_tokens,
+        image_output_tokens: record.image_output_tokens,
+        total_tokens: record.total_tokens,
+        input_tokens_display: record
+            .input_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        output_tokens_display: record
+            .output_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        cached_tokens_display: record
+            .cached_tokens
+            .map_or_else(|| "-".to_owned(), format_compact_number),
+        cache_write_tokens_display: record
+            .cache_write_tokens
+            .map_or_else(|| "-".to_owned(), format_compact_number),
+        reasoning_tokens_display: record
+            .reasoning_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        image_input_tokens_display: record
+            .image_input_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        image_output_tokens_display: record
+            .image_output_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+        total_tokens_display: record
+            .total_tokens
+            .map_or_else(|| "-".to_owned(), format_number),
+    }
+}
+
 pub(crate) fn format_money(cost: &domain::CurrencyCost) -> String {
     format_decimal_currency(cost.amount.as_str(), &cost.currency)
 }
@@ -142,20 +198,32 @@ pub(crate) fn format_service_tier(service_tier: Option<&str>) -> String {
     match service_tier {
         Some("priority" | "fast") => "Fast".to_owned(),
         Some("flex") => "Flex".to_owned(),
-        Some("default") | None => "Default".to_owned(),
-        Some(other) => other.to_owned(),
+        Some("default" | "standard") | None => "Standard".to_owned(),
+        Some(other) => capitalize_first(other),
     }
 }
 
+fn capitalize_first(value: &str) -> String {
+    let mut chars = value.chars();
+    chars
+        .next()
+        .map(|first| first.to_uppercase().chain(chars).collect())
+        .unwrap_or_default()
+}
+
 pub(crate) fn billing_view(billing: Option<&domain::UsageBilling>) -> Option<BillingView> {
     match billing? {
-        domain::UsageBilling::Total { total, .. } => Some(BillingView {
+        domain::UsageBilling::Total { source, total } => Some(BillingView {
             input_amount_display: "—".to_owned(),
             output_amount_display: "—".to_owned(),
             cache_read_amount_display: "—".to_owned(),
             cache_write_amount_display: "—".to_owned(),
             standard_amount_display: "—".to_owned(),
-            total_amount_display: format_money(total),
+            total_amount_display: if source == "calculated" {
+                format!("≈ {}", format_money(total))
+            } else {
+                format_money(total)
+            },
             input_price_display: "—".to_owned(),
             output_price_display: "—".to_owned(),
             cache_read_price_display: "—".to_owned(),
@@ -180,6 +248,57 @@ pub(crate) fn billing_view(billing: Option<&domain::UsageBilling>) -> Option<Bil
     }
 }
 
+pub(crate) fn usage_list_record_view(record: domain::UsageListRecord) -> UsageListRecordView {
+    let token_details = usage_list_token_details(&record);
+    let billing = billing_view(record.billing.as_ref());
+    let created_at_display = china_datetime(&record.started_at);
+    let model = record
+        .upstream_model_id
+        .clone()
+        .or_else(|| record.requested_model_id.clone());
+    UsageListRecordView {
+        id: record.id,
+        provider: record.provider_kind,
+        authentication_kind: record.provider_account_authentication_kind,
+        account_id: record.provider_account_ref,
+        account_email: record.provider_account_email,
+        account_name: record.provider_account_name,
+        route: record.endpoint,
+        model,
+        requested_model: record.requested_model_id,
+        upstream_model: record.upstream_model_id,
+        service_tier: record.service_tier,
+        client_transport: record.client_transport,
+        upstream_transport: record.upstream_transport,
+        reasoning_effort: record.reasoning_effort,
+        reasoning_preset: record.reasoning_preset,
+        subagent_kind: record.subagent_kind,
+        compact: record.compact,
+        token_details,
+        billing,
+        latency_details: UsageLatencyDetailsView {
+            admission_decision_ms: record.admission_decision_ms,
+            account_selection_wait_ms: record.account_selection_wait_ms,
+            capacity_used_slots: record.capacity_used_slots,
+            capacity_total_slots: record.capacity_total_slots,
+            transport_decision_wait_ms: record.transport_decision_wait_ms,
+            ws_connect_ms: record.connect_ms,
+            upstream_headers_ms: record.headers_ms,
+            first_event_ms: record.first_event_ms,
+            first_reasoning_ms: record.first_reasoning_ms,
+            first_text_ms: record.first_text_ms,
+            first_token_ms: record.first_token_ms,
+            openai_processing_ms: record.provider_processing_ms,
+        },
+        first_token_latency_ms: record.first_token_ms,
+        latency_ms: record.latency_ms,
+        created_at: record.started_at,
+        created_at_display,
+        client_ip: record.client_ip,
+        user_agent: record.user_agent,
+    }
+}
+
 pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView {
     let tokens = token_details(&record);
     let billing = billing_view(record.billing.as_ref());
@@ -222,11 +341,7 @@ pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView
     let model = record
         .upstream_model_id
         .clone()
-        .unwrap_or_else(|| record.requested_model_id.clone());
-    let transport = record
-        .upstream_transport
-        .clone()
-        .or_else(|| Some(record.client_transport.clone()));
+        .or_else(|| record.requested_model_id.clone());
     let metadata = provider_metadata_fields(record.provider_metadata_json.as_deref());
     UsageRecordView {
         id: record.id.clone(),
@@ -243,11 +358,12 @@ pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView
         account_name: record.provider_account_name,
         route: record.endpoint,
         model,
-        requested_model: Some(record.requested_model_id),
+        requested_model: record.requested_model_id,
         upstream_model: record.upstream_model_id,
         service_tier: record.service_tier,
         status_code,
-        transport,
+        client_transport: record.client_transport,
+        upstream_transport: record.upstream_transport,
         protocol: record.protocol.clone(),
         http_version: record.http_version.clone(),
         client_status_code: record.client_status_code.map(i64::from),
@@ -259,6 +375,10 @@ pub(crate) fn usage_record_view(record: domain::UsageRecord) -> UsageRecordView
         image_generation_requested: record.image_generation_requested,
         image_generation_succeeded: record.image_generation_succeeded,
         latency_details: UsageLatencyDetailsView {
+            admission_decision_ms: record.admission_decision_ms,
+            account_selection_wait_ms: record.account_selection_wait_ms,
+            capacity_used_slots: record.capacity_used_slots,
+            capacity_total_slots: record.capacity_total_slots,
             transport_decision_wait_ms: record.transport_decision_wait_ms,
             ws_connect_ms: record.connect_ms,
             upstream_headers_ms: record.headers_ms,
@@ -318,6 +438,8 @@ pub(crate) fn provider_metadata_fields(value: Option<&str>) -> BTreeMap<String,
         "requestKind",
         "subagentKind",
         "transport",
+        "clientTransport",
+        "upstreamTransport",
         "httpVersion",
         "clientStatusCode",
         "upstreamStatusCode",
@@ -351,9 +473,7 @@ pub(crate) fn usage_attempt_view(attempt: domain::UsageAttempt) -> UsageAttemptV
         provider: attempt
             .provider_kind
             .unwrap_or_else(|| "unknown".to_owned()),
-        model: attempt
-            .upstream_model_id
-            .unwrap_or_else(|| "unknown".to_owned()),
+        model: attempt.upstream_model_id,
         transport: attempt
             .upstream_transport
             .unwrap_or_else(|| "unknown".to_owned()),
@@ -389,6 +509,8 @@ pub(crate) fn usage_attempt_view(attempt: domain::UsageAttempt) -> UsageAttemptV
 
 pub(crate) fn usage_detail_view(detail: domain::UsageDetail) -> UsageRecordDetailView {
     UsageRecordDetailView {
+        trace: detail.trace,
+        related_requests: detail.related_requests,
         request: usage_record_view(detail.request),
         attempts: detail
             .attempts
@@ -399,31 +521,13 @@ pub(crate) fn usage_detail_view(detail: domain::UsageDetail) -> UsageRecordDetai
     }
 }
 
-pub(crate) fn page_meta(page: u32, page_size: u16, total: u64) -> PageMeta {
-    let page_size_u64 = u64::from(page_size);
-    let total_pages = total.saturating_add(page_size_u64 - 1) / page_size_u64;
-    PageMeta::new(
-        page,
-        u32::from(page_size),
-        total,
-        u32::try_from(total_pages).unwrap_or(u32::MAX),
-    )
-}
-
-pub(crate) fn usage_page_view(
-    page: domain::UsagePage,
-    page_number: u32,
-    page_size: u16,
-) -> Result<PageData<UsageRecordView>, WireValidationError> {
-    Ok(PageData {
-        items: page.items.into_iter().map(usage_record_view).collect(),
-        page: page_meta(page_number, page_size, page.total),
-        next_cursor: page
-            .next_cursor
-            .as_ref()
-            .map(encode_observability_cursor)
-            .transpose()?,
-    })
+pub(crate) fn usage_page_view(page: domain::UsagePage) -> PageData<UsageListRecordView> {
+    PageData {
+        items: page.items.into_iter().map(usage_list_record_view).collect(),
+        current_page: page.current_page,
+        page_size: page.page_size,
+        total: page.total,
+    }
 }
 
 pub(crate) fn ops_error_view(error: domain::OpsError) -> OpsErrorView {
@@ -433,50 +537,77 @@ pub(crate) fn ops_error_view(error: domain::OpsError) -> OpsErrorView {
         .or(error.provider_account_name.as_ref())
         .or(error.provider_account_ref.as_ref())
         .cloned();
+    let model = error
+        .upstream_model_id
+        .clone()
+        .or_else(|| error.requested_model_id.clone());
     OpsErrorView {
         id: error.event_id,
         request_id: error.request_id,
         client_api_key_id: error.client_api_key_ref,
         kind: error.component.clone(),
+        operation: error.operation,
+        protocol: error.protocol,
+        client_transport: error.client_transport,
         provider: error.provider_kind,
         authentication_kind: error.provider_account_authentication_kind,
         account_id: error.provider_account_ref,
+        account_name: error.provider_account_name,
+        account_email: error.provider_account_email,
         route: error.endpoint.unwrap_or_else(|| "—".to_owned()),
-        model: error.upstream_model_id,
+        model,
+        requested_model: error.requested_model_id,
+        upstream_model: error.upstream_model_id,
+        service_tier: error.service_tier,
         client_status_code: error.client_status_code.map(i64::from),
         upstream_status_code: error.upstream_status_code.map(i64::from),
         transport: error.upstream_transport,
         attempt_index: error.attempt_index,
         failure_class: error.failure_kind,
+        upstream_send_state: error.upstream_send_state,
+        provider_error_code: error.provider_error_code,
         response_id: error.client_response_id,
         upstream_request_id: error.upstream_request_id,
         latency_ms: error.latency_ms,
+        client_ip: error.client_ip,
+        user_agent: error.user_agent,
+        reasoning_effort: error.reasoning_effort,
+        reasoning_preset: error.reasoning_preset,
+        request_kind: error.request_kind,
+        subagent_kind: error.subagent_kind,
+        compact: error.compact,
         message: error.message,
+        raw_upstream_error: error.raw_upstream_error,
         metadata: OpsErrorMetadataView {
             source: error.source,
             component: error.component,
             attempt_id: None,
             account_label,
+            continuation_affinity_hash: error.continuation_affinity_hash,
+            continuation_previous_response_id_hash: error.continuation_previous_response_id_hash,
+            continuation_unavailable_reason: error.continuation_unavailable_reason,
+            upstream_connection_id: error.upstream_connection_id,
+            upstream_connection_exit_reason: error.upstream_connection_exit_reason,
+            upstream_connection_age_ms: error.upstream_connection_age_ms,
+            upstream_connection_idle_ms: error.upstream_connection_idle_ms,
+            recovery_request_id: error.recovery_request_id,
+            recovered_at: error.recovered_at,
+            recovery_attempt_count: error.recovery_attempt_count,
+            recovery_retry_delay_ms: error.recovery_retry_delay_ms,
+            recovery_total_latency_ms: error.recovery_total_latency_ms,
         },
         created_at: error.occurred_at,
         created_at_display: china_datetime(&error.occurred_at),
     }
 }
 
-pub(crate) fn ops_page_view(
-    page: domain::OpsErrorPage,
-    page_number: u32,
-    page_size: u16,
-) -> Result<PageData<OpsErrorView>, WireValidationError> {
-    Ok(PageData {
+pub(crate) fn ops_page_view(page: domain::OpsErrorPage) -> PageData<OpsErrorView> {
+    PageData {
         items: page.items.into_iter().map(ops_error_view).collect(),
-        page: page_meta(page_number, page_size, page.total),
-        next_cursor: page
-            .next_cursor
-            .as_ref()
-            .map(encode_observability_cursor)
-            .transpose()?,
-    })
+        current_page: page.current_page,
+        page_size: page.page_size,
+        total: page.total,
+    }
 }
 
 pub(crate) fn trend_point_view(point: domain::TrendPoint) -> TrendPointView {
@@ -508,6 +639,36 @@ pub(crate) fn trend_point_view(point: domain::TrendPoint) -> TrendPointView {
         success_rate: success_rate_value
             .map_or_else(|| "—".to_owned(), |value| format!("{value:.1}%")),
         success_rate_value,
+        first_token_p50_ms: point
+            .metrics
+            .first_token_latency_percentiles
+            .p50_ms
+            .map(|value| value.as_f64()),
+        first_token_p95_ms: point
+            .metrics
+            .first_token_latency_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        latency_p95_ms: point
+            .metrics
+            .latency_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        output_throughput_p50: point.metrics.output_throughput_p50,
+        admission_decision_p95_ms: point
+            .metrics
+            .admission_decision_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        account_selection_wait_p95_ms: point
+            .metrics
+            .account_selection_wait_percentiles
+            .p95_ms
+            .map(|value| value.as_f64()),
+        capacity_utilization: point
+            .metrics
+            .capacity_utilization_p95_basis_points
+            .map(basis_points_rate),
     }
 }
 
@@ -535,18 +696,20 @@ pub(crate) fn trend_summary_view(
         ],
         TrendKind::Latency => vec![
             TrendSummaryView {
-                label: "平均".to_owned(),
-                value: display_duration(summary.average_latency_ms),
+                label: "首字 P95".to_owned(),
+                value: display_duration_f64(summary.peak_first_token_p95_ms),
                 ratio: None,
             },
             TrendSummaryView {
-                label: "最高".to_owned(),
-                value: display_duration(summary.max_latency_ms),
+                label: "总耗时 P95".to_owned(),
+                value: display_duration_f64(summary.peak_latency_p95_ms),
                 ratio: None,
             },
             TrendSummaryView {
-                label: "最低".to_owned(),
-                value: display_duration(summary.min_latency_ms),
+                label: "吞吐 P50".to_owned(),
+                value: summary
+                    .minimum_output_throughput_p50
+                    .map_or_else(|| "—".to_owned(), |value| format!("{value} tok/s")),
                 ratio: None,
             },
         ],
@@ -706,6 +869,28 @@ pub(crate) fn dashboard_view(
     } = observation;
     let mut account_usage_views = Vec::with_capacity(account_usage.len());
     for credential in account_usage {
+        let local_requests = credential
+            .quota_window
+            .as_ref()
+            .filter(|window| window.used_percent.is_none())
+            .and_then(|window| window.local_usage.as_ref())
+            .map(|usage| usage.request_count);
+        let (metric_label, metric_value) = match local_requests {
+            Some(count) => (
+                "次数".to_owned(),
+                if count > 0 {
+                    format_compact_number(count)
+                } else {
+                    "—".to_owned()
+                },
+            ),
+            None => (
+                "今日 Token".to_owned(),
+                credential
+                    .total_tokens
+                    .map_or_else(|| "—".to_owned(), format_compact_number),
+            ),
+        };
         account_usage_views.push(DashboardAccountUsageView {
             id: credential.account_id.clone(),
             provider: credential.provider_kind.clone(),
@@ -715,6 +900,10 @@ pub(crate) fn dashboard_view(
                 .clone()
                 .unwrap_or_else(|| credential.name.clone()),
             plan_type: credential.plan_type.clone(),
+            plan_type_display: credential
+                .plan_type_display
+                .clone()
+                .unwrap_or_else(|| "未知套餐".to_owned()),
             tokens: credential
                 .total_tokens
                 .map_or_else(|| "—".to_owned(), format_compact_number),
@@ -728,24 +917,27 @@ pub(crate) fn dashboard_view(
                 })
                 .collect(),
             quota_used_percent: credential.quota_used_percent,
+            usage_window: credential
+                .quota_window
+                .map(crate::admin::accounts::quota_window_view),
+            metric_label,
+            metric_value,
             last_used: relative_time(credential.last_used_at, range.end),
         });
     }
+    let unavailable_accounts = provider_accounts
+        .total
+        .saturating_sub(provider_accounts.normal);
+
     DashboardDataView {
         cards: DashboardCardsView {
             credentials: DashboardCredentialsCardView {
-                total: format_compact_number(provider_accounts.total),
+                total: provider_accounts.total.to_string(),
                 total_value: provider_accounts.total,
-                available: format_compact_number(provider_accounts.normal),
+                available: provider_accounts.normal.to_string(),
                 available_value: provider_accounts.normal,
-                unavailable: format_compact_number(
-                    provider_accounts
-                        .total
-                        .saturating_sub(provider_accounts.normal),
-                ),
-                unavailable_value: provider_accounts
-                    .total
-                    .saturating_sub(provider_accounts.normal),
+                unavailable: unavailable_accounts.to_string(),
+                unavailable_value: unavailable_accounts,
             },
             traffic: DashboardTrafficCardView {
                 today_requests: format_compact_number(today.request_count),
@@ -775,7 +967,10 @@ pub(crate) fn dashboard_view(
         health_timeline: health_timeline_view(health_timeline),
         wire_profiles: wire_profiles.into_iter().map(wire_profile_view).collect(),
         account_usage: account_usage_views,
-        usage_records: recent_requests.into_iter().map(usage_record_view).collect(),
+        usage_records: recent_requests
+            .into_iter()
+            .map(usage_list_record_view)
+            .collect(),
         pool_summary: DashboardPoolSummaryView {
             total: provider_accounts.total,
             normal: provider_accounts.normal,
@@ -817,6 +1012,7 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
         .map(|point| OverviewHealthPointView {
             bucket: point.bucket_start,
             label: china_label(point.bucket_start, "%m-%d %H:%M"),
+            total_requests: point.total_requests,
             success_requests: point.success_requests,
             failed_requests: point.failed_requests,
             cancelled_requests: point.cancelled_requests,
@@ -847,6 +1043,31 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
                 .first_token_latency_percentiles
                 .p99_ms
                 .map(|value| value.as_f64()),
+            admission_decision_p50_ms: point
+                .admission_decision_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            admission_decision_p95_ms: point
+                .admission_decision_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p50_ms: point
+                .account_selection_wait_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p95_ms: point
+                .account_selection_wait_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            output_throughput_p10: point.output_throughput_p10,
+            output_throughput_p50: point.output_throughput_p50,
+            output_throughput_p90: point.output_throughput_p90,
+            capacity_utilization: point
+                .capacity_utilization_avg_basis_points
+                .map(basis_points_rate),
+            capacity_utilization_p95: point
+                .capacity_utilization_p95_basis_points
+                .map(basis_points_rate),
         })
         .collect();
     let cost_points = insights
@@ -862,6 +1083,8 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
             total_tokens: point.total_tokens,
             estimated_cost: point.estimated_cost.as_ref().map(ToString::to_string),
             standard_cost: point.standard_cost.as_ref().map(ToString::to_string),
+            no_cache_cost: point.no_cache_cost.as_ref().map(ToString::to_string),
+            cache_savings: point.cache_savings.as_ref().map(ToString::to_string),
             cached_token_rate: point.cached_token_rate,
             cache_hit_request_rate: point.cache_hit_request_rate,
         })
@@ -876,6 +1099,7 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
             incomplete_requests: insights.health.incomplete_requests,
             caller_error_requests: insights.health.caller_error_requests,
             success_rate: insights.health.success_rate,
+            completion_rate: insights.health.completion_rate,
             request_change_rate: None,
             success_rate_change: None,
             points: health_points,
@@ -911,8 +1135,42 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
                 .first_token_latency_percentiles
                 .p99_ms
                 .map(|value| value.as_f64()),
+            admission_decision_p50_ms: insights
+                .performance
+                .admission_decision_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            admission_decision_p95_ms: insights
+                .performance
+                .admission_decision_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p50_ms: insights
+                .performance
+                .account_selection_wait_percentiles
+                .p50_ms
+                .map(|value| value.as_f64()),
+            account_selection_wait_p95_ms: insights
+                .performance
+                .account_selection_wait_percentiles
+                .p95_ms
+                .map(|value| value.as_f64()),
+            output_throughput_p10: insights.performance.output_throughput_p10,
+            output_throughput_p50: insights.performance.output_throughput_p50,
+            output_throughput_p90: insights.performance.output_throughput_p90,
+            capacity_utilization: insights
+                .performance
+                .capacity_utilization_avg_basis_points
+                .map(basis_points_rate),
+            capacity_utilization_p95: insights
+                .performance
+                .capacity_utilization_p95_basis_points
+                .map(basis_points_rate),
             latency_coverage: insights.performance.latency_coverage,
             first_token_coverage: insights.performance.first_token_coverage,
+            admission_decision_coverage: insights.performance.admission_decision_coverage,
+            account_selection_wait_coverage: insights.performance.account_selection_wait_coverage,
+            capacity_coverage: insights.performance.capacity_coverage,
             points: performance_points,
         },
         cost: OverviewCostView {
@@ -926,11 +1184,27 @@ pub(crate) fn usage_insights_view(insights: domain::UsageInsights) -> UsageInsig
                 .standard_cost
                 .as_ref()
                 .map(ToString::to_string),
+            no_cache_cost: insights
+                .cost
+                .no_cache_cost
+                .as_ref()
+                .map(ToString::to_string),
+            cache_savings: insights
+                .cost
+                .cache_savings
+                .as_ref()
+                .map(ToString::to_string),
+            tier_premium: insights.cost.tier_premium.as_ref().map(ToString::to_string),
             cost_per_request: insights
                 .cost
                 .cost_per_request
                 .as_ref()
                 .map(ToString::to_string),
+            cost_per_successful_request: insights
+                .cost
+                .cost_per_successful_request
+                .as_ref()
+                .map(ToString::to_string),
             tokens_per_request: insights.cost.tokens_per_request,
             cached_token_rate: insights.cost.cached_token_rate,
             cache_hit_request_rate: insights.cost.cache_hit_request_rate,
@@ -988,6 +1262,12 @@ pub(crate) fn diagnostics_view(
                 request_share: item.request_share,
                 average_latency_ms: item.average_latency_ms,
                 latency_p95_ms: item.latency_p95_ms,
+                first_token_p95_ms: item.first_token_p95_ms,
+                non_completion_count: item.non_completion_count,
+                non_completion_rate: item.non_completion_rate,
+                retry_count: item.retry_count,
+                retry_rate: item.retry_rate,
+                impact_score: item.impact_score,
                 estimated_cost: item.estimated_cost.as_ref().map(ToString::to_string),
                 attempt_count: item.attempt_count,
                 total_tokens: item.total_tokens,
@@ -997,21 +1277,21 @@ pub(crate) fn diagnostics_view(
 }
 
 pub(crate) fn map_wire_error(error: WireValidationError) -> AdminError {
+    if error.field() == "timeRange" {
+        return AdminError::invalid_time_range();
+    }
     let message = match error.field() {
-        "timeRange" => "Invalid time range",
-        "statusCode" => "Status code must be between 100 and 599",
-        "attemptIndex" => "Attempt index is out of range",
-        "kind" => "Invalid dashboard trend kind",
-        "dimension" => "Invalid diagnostics dimension",
-        "outcome" => "Invalid Observability query",
-        "id" => "Usage record ID is required",
-        "page" | "pageSize" => "Invalid Observability query",
-        "cursor" => "Invalid observability cursor",
-        _ => "Invalid observability query",
+        "statusCode" => "statusCode 必须在 100 到 599 之间",
+        "attemptIndex" => "attemptIndex 超出有效范围",
+        "kind" => "Dashboard 趋势类型不合法",
+        "dimension" => "诊断维度不合法",
+        "id" => "用量记录 ID 不能为空",
+        "cursor" => "观测数据游标不合法",
+        _ => "观测查询参数不合法",
     };
     AdminError::bad_request(message)
 }
 
 pub(crate) fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
-    map_admin_service_error(error, "Observability repository unavailable")
+    map_admin_service_error(error)
 }

backend/crates/gateway-api/src/admin/observability/query.rs

@@ -2,14 +2,10 @@
 
 use super::*;
 
-use base64::Engine as _;
-
 /// 观测列表默认页大小。
 pub const DEFAULT_PAGE_SIZE: u16 = 50;
 /// 观测列表允许的最大页大小。
 pub const MAX_PAGE_SIZE: u16 = 100;
-/// 游标编码在 HTTP 层解码前允许的最大长度。
-pub const MAX_CURSOR_BYTES: usize = 1024;
 
 /// Dashboard 查询参数。
 #[derive(Clone, Default, Deserialize)]
@@ -31,9 +27,8 @@ impl DashboardQuery {
 #[derive(Clone, Default, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct UsageQuery {
-    pub page: Option<u32>,
+    pub current_page: Option<u32>,
     pub page_size: Option<u16>,
-    pub cursor: Option<String>,
     pub kind: Option<String>,
     pub outcome: Option<String>,
     pub client_api_key_id: Option<String>,
@@ -53,22 +48,17 @@ pub struct UsageQuery {
 }
 
 impl UsageQuery {
-    /// 校验分页字段，不改变仓储层的分页 owner。
-    pub fn validate_page(&self) -> Result<(u32, u16), WireValidationError> {
-        let page = self.page.unwrap_or(1);
-        if page == 0 {
-            return Err(WireValidationError::new("page"));
+    /// 校验 Element Plus 风格的页码分页字段。
+    pub fn validate_pagination(&self) -> Result<(u32, u16), WireValidationError> {
+        let current_page = self.current_page.unwrap_or(1);
+        if current_page == 0 {
+            return Err(WireValidationError::new("currentPage"));
         }
         let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
         if page_size == 0 || page_size > MAX_PAGE_SIZE {
             return Err(WireValidationError::new("pageSize"));
         }
-        Ok((page, page_size))
-    }
-
-    /// 校验游标的 wire 边界；编码和排序语义由应用层负责。
-    pub fn validate_cursor(&self) -> Result<(), WireValidationError> {
-        validate_cursor(self.cursor.as_deref())
+        Ok((current_page, page_size))
     }
 }
 
@@ -110,22 +100,19 @@ impl DiagnosticsQuery {
 #[derive(Clone, Default, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct OpsQuery {
-    pub page: Option<u32>,
+    pub current_page: Option<u32>,
     pub page_size: Option<u16>,
-    pub cursor: Option<String>,
     pub kind: Option<String>,
     pub client_api_key_id: Option<String>,
     pub provider: Option<String>,
     pub request_id: Option<String>,
     pub account_id: Option<String>,
-    pub route: Option<String>,
     pub model: Option<String>,
     pub status_code: Option<i64>,
     pub client_status_code: Option<i64>,
     pub upstream_status_code: Option<i64>,
     pub transport: Option<String>,
     pub attempt_index: Option<i64>,
-    pub failure_class: Option<String>,
     pub response_id: Option<String>,
     pub upstream_request_id: Option<String>,
     pub search: Option<String>,
@@ -134,22 +121,17 @@ pub struct OpsQuery {
 }
 
 impl OpsQuery {
-    /// 校验分页字段。
-    pub fn validate_page(&self) -> Result<(u32, u16), WireValidationError> {
-        let page = self.page.unwrap_or(1);
-        if page == 0 {
-            return Err(WireValidationError::new("page"));
+    /// 校验 Element Plus 风格的页码分页字段。
+    pub fn validate_pagination(&self) -> Result<(u32, u16), WireValidationError> {
+        let current_page = self.current_page.unwrap_or(1);
+        if current_page == 0 {
+            return Err(WireValidationError::new("currentPage"));
         }
         let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
         if page_size == 0 || page_size > MAX_PAGE_SIZE {
             return Err(WireValidationError::new("pageSize"));
         }
-        Ok((page, page_size))
-    }
-
-    /// 校验游标的 wire 边界。
-    pub fn validate_cursor(&self) -> Result<(), WireValidationError> {
-        validate_cursor(self.cursor.as_deref())
+        Ok((current_page, page_size))
     }
 }
 
@@ -258,13 +240,6 @@ pub(crate) fn require_text(value: &str, field: &'static str) -> Result<(), WireV
     }
 }
 
-pub(crate) fn validate_cursor(value: Option<&str>) -> Result<(), WireValidationError> {
-    if value.is_some_and(|value| value.is_empty() || value.len() > MAX_CURSOR_BYTES) {
-        return Err(WireValidationError::new("cursor"));
-    }
-    Ok(())
-}
-
 pub(crate) fn trimmed(value: Option<&str>) -> Option<&str> {
     value.map(str::trim).filter(|value| !value.is_empty())
 }
@@ -345,37 +320,20 @@ pub(crate) fn usage_filter(query: &UsageQuery) -> Result<domain::UsageFilter, Wi
     })
 }
 
-pub(crate) fn usage_command(
-    query: &UsageQuery,
-) -> Result<(domain::UsageQuery, u32, u16), WireValidationError> {
-    let (page, page_size) = query.validate_page()?;
-    query.validate_cursor()?;
-    let page_number = NonZeroU32::new(page)
-        .map(domain::PageNumber::new)
-        .ok_or_else(|| WireValidationError::new("page"))?;
+pub(crate) fn usage_command(query: &UsageQuery) -> Result<domain::UsageQuery, WireValidationError> {
+    let (current_page, page_size) = query.validate_pagination()?;
     let page_size_value =
         DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
-    Ok((
-        domain::UsageQuery {
-            range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
-            filter: usage_filter(query)?,
-            cursor: decode_observability_cursor(query.cursor.as_deref())?,
-            page: page_number,
-            page_size: page_size_value,
-        },
-        page,
-        page_size,
-    ))
+    Ok(domain::UsageQuery {
+        range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
+        filter: usage_filter(query)?,
+        current_page,
+        page_size: page_size_value,
+    })
 }
 
-pub(crate) fn ops_command(
-    query: &OpsQuery,
-) -> Result<(domain::OpsErrorQuery, u32, u16), WireValidationError> {
-    let (page, page_size) = query.validate_page()?;
-    query.validate_cursor()?;
-    let page_number = NonZeroU32::new(page)
-        .map(domain::PageNumber::new)
-        .ok_or_else(|| WireValidationError::new("page"))?;
+pub(crate) fn ops_command(query: &OpsQuery) -> Result<domain::OpsErrorQuery, WireValidationError> {
+    let (current_page, page_size) = query.validate_pagination()?;
     let page_size_value =
         DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
     let status_code = parse_status(
@@ -384,66 +342,25 @@ pub(crate) fn ops_command(
             .or(query.client_status_code)
             .or(query.status_code),
     )?;
-    Ok((
-        domain::OpsErrorQuery {
-            range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
-            filter: domain::OpsErrorFilter {
-                client_api_key_ref: non_empty(query.client_api_key_id.clone()),
-                request_id: non_empty(query.request_id.clone()),
-                provider_kind: non_empty(query.provider.clone()),
-                provider_account_ref: non_empty(query.account_id.clone()),
-                operation: non_empty(query.route.clone()).or_else(|| non_empty(query.kind.clone())),
-                model: non_empty(query.model.clone()),
-                transport: non_empty(query.transport.clone()),
-                attempt_index: parse_attempt_index(query.attempt_index)?,
-                response_id: non_empty(query.response_id.clone()),
-                upstream_request_id: non_empty(query.upstream_request_id.clone()),
-                failure_kind: non_empty(query.failure_class.clone()),
-                status_code,
-                search: non_empty(query.search.clone()),
-            },
-            cursor: decode_observability_cursor(query.cursor.as_deref())?,
-            page: page_number,
-            page_size: page_size_value,
+    Ok(domain::OpsErrorQuery {
+        range: usage_range(query.start_time.as_deref(), query.end_time.as_deref())?,
+        filter: domain::OpsErrorFilter {
+            client_api_key_ref: non_empty(query.client_api_key_id.clone()),
+            request_id: non_empty(query.request_id.clone()),
+            provider_kind: non_empty(query.provider.clone()),
+            provider_account_ref: non_empty(query.account_id.clone()),
+            operation: non_empty(query.kind.clone()),
+            model: non_empty(query.model.clone()),
+            transport: non_empty(query.transport.clone()),
+            attempt_index: parse_attempt_index(query.attempt_index)?,
+            response_id: non_empty(query.response_id.clone()),
+            upstream_request_id: non_empty(query.upstream_request_id.clone()),
+            status_code,
+            search: non_empty(query.search.clone()),
         },
-        page,
-        page_size,
-    ))
-}
-
-pub(crate) fn decode_observability_cursor(
-    value: Option<&str>,
-) -> Result<Option<domain::ObservabilityCursor>, WireValidationError> {
-    value
-        .map(|encoded| {
-            if encoded.is_empty() || encoded.len() > MAX_CURSOR_BYTES {
-                return Err(WireValidationError::new("cursor"));
-            }
-            let bytes = URL_SAFE_NO_PAD
-                .decode(encoded)
-                .map_err(|_| WireValidationError::new("cursor"))?;
-            let wire: CursorWire =
-                serde_json::from_slice(&bytes).map_err(|_| WireValidationError::new("cursor"))?;
-            if wire.stable_id.trim().is_empty() {
-                return Err(WireValidationError::new("cursor"));
-            }
-            Ok(domain::ObservabilityCursor {
-                observed_at: wire.observed_at,
-                stable_id: wire.stable_id,
-            })
-        })
-        .transpose()
-}
-
-pub(crate) fn encode_observability_cursor(
-    cursor: &domain::ObservabilityCursor,
-) -> Result<String, WireValidationError> {
-    let bytes = serde_json::to_vec(&CursorWire {
-        observed_at: cursor.observed_at,
-        stable_id: cursor.stable_id.clone(),
+        current_page,
+        page_size: page_size_value,
     })
-    .map_err(|_| WireValidationError::new("cursor"))?;
-    Ok(URL_SAFE_NO_PAD.encode(bytes))
 }
 
 pub(crate) fn non_empty(value: Option<String>) -> Option<String> {

backend/crates/gateway-api/src/admin/observability/routes.rs

@@ -32,7 +32,7 @@ where
 pub(crate) async fn dashboard_summary<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<DashboardQuery>,
+    AdminQuery(query): AdminQuery<DashboardQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -56,7 +56,7 @@ where
 pub(crate) async fn dashboard_trend<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<DashboardQuery>,
+    AdminQuery(query): AdminQuery<DashboardQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -79,27 +79,26 @@ where
 pub(crate) async fn usage_records<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<UsageQuery>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
 {
-    let (command, page, page_size) = usage_command(&query).map_err(map_wire_error)?;
+    let command = usage_command(&query).map_err(map_wire_error)?;
     let result = state
         .admin_services()
         .observability()
         .usage_records(command)
         .await
         .map_err(map_service_error)?;
-    let data = usage_page_view(result, page, page_size)
-        .map_err(|_| AdminError::internal("Failed to encode observability cursor"))?;
+    let data = usage_page_view(result);
     Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }
 
 pub(crate) async fn usage_record_detail<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<DetailQuery>,
+    AdminQuery(query): AdminQuery<DetailQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -120,7 +119,7 @@ where
 pub(crate) async fn usage_records_summary<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<UsageQuery>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -143,7 +142,7 @@ where
 pub(crate) async fn usage_insights_overview<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<UsageQuery>,
+    AdminQuery(query): AdminQuery<UsageQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -166,7 +165,7 @@ where
 pub(crate) async fn usage_insights_diagnostics<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<DiagnosticsQuery>,
+    AdminQuery(query): AdminQuery<DiagnosticsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
@@ -196,19 +195,18 @@ where
 pub(crate) async fn ops_errors<S>(
     _auth: AdminAuth,
     State(state): State<S>,
-    Query(query): Query<OpsQuery>,
+    AdminQuery(query): AdminQuery<OpsQuery>,
 ) -> Result<impl IntoResponse, AdminError>
 where
     S: AdminSessionState + Send + Sync,
 {
-    let (command, page, page_size) = ops_command(&query).map_err(map_wire_error)?;
+    let command = ops_command(&query).map_err(map_wire_error)?;
     let result = state
         .admin_services()
         .observability()
         .ops_errors(command)
         .await
         .map_err(map_service_error)?;
-    let data = ops_page_view(result, page, page_size)
-        .map_err(|_| AdminError::internal("Failed to encode observability cursor"))?;
+    let data = ops_page_view(result);
     Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }

backend/crates/gateway-api/src/admin/observability/wire.rs

@@ -2,21 +2,14 @@
 
 use super::*;
 
-/// 观测列表游标的稳定 wire 形状。
-#[derive(Clone, Serialize, serde::Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-pub struct CursorWire {
-    pub observed_at: DateTime<Utc>,
-    pub stable_id: String,
-}
-
 /// 观测列表响应数据。
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PageData<T> {
     pub items: Vec<T>,
-    pub page: PageMeta,
-    pub next_cursor: Option<String>,
+    pub current_page: u32,
+    pub page_size: u16,
+    pub total: u64,
 }
 
 /// Token 详情展示。
@@ -77,7 +70,39 @@ pub struct BillingView {
     pub multiplier_display: String,
 }
 
-/// 单条逻辑请求展示。
+/// 使用记录表格的窄展示。
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UsageListRecordView {
+    pub id: String,
+    pub provider: Option<String>,
+    pub authentication_kind: Option<String>,
+    pub account_id: Option<String>,
+    pub account_email: Option<String>,
+    pub account_name: Option<String>,
+    pub route: String,
+    pub model: Option<String>,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
+    pub client_transport: String,
+    pub upstream_transport: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: bool,
+    pub token_details: TokenDetailsView,
+    pub billing: Option<BillingView>,
+    pub latency_details: UsageLatencyDetailsView,
+    pub first_token_latency_ms: Option<u64>,
+    pub latency_ms: Option<u64>,
+    pub created_at: DateTime<Utc>,
+    pub created_at_display: String,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+}
+
+/// 单条逻辑请求详情展示。
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UsageRecordView {
@@ -94,12 +119,13 @@ pub struct UsageRecordView {
     pub account_email: Option<String>,
     pub account_name: Option<String>,
     pub route: String,
-    pub model: String,
+    pub model: Option<String>,
     pub requested_model: Option<String>,
     pub upstream_model: Option<String>,
     pub service_tier: Option<String>,
     pub status_code: Option<i64>,
-    pub transport: Option<String>,
+    pub client_transport: String,
+    pub upstream_transport: Option<String>,
     pub protocol: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub http_version: Option<String>,
@@ -157,6 +183,14 @@ pub struct WebSocketPoolMetadataView {
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UsageLatencyDetailsView {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub admission_decision_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub account_selection_wait_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub capacity_used_slots: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub capacity_total_slots: Option<u64>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub transport_decision_wait_ms: Option<u64>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -183,7 +217,7 @@ pub struct UsageAttemptView {
     pub attempt_index: u32,
     pub trigger: String,
     pub provider: String,
-    pub model: String,
+    pub model: Option<String>,
     pub transport: String,
     pub send_state: String,
     pub outcome: String,
@@ -213,6 +247,8 @@ pub struct UsageAttemptView {
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct UsageRecordDetailView {
+    pub trace: Option<serde_json::Value>,
+    pub related_requests: Vec<serde_json::Value>,
     #[serde(flatten)]
     pub request: UsageRecordView,
     pub attempts: Vec<UsageAttemptView>,
@@ -256,6 +292,13 @@ pub struct TrendPointView {
     pub min_latency_value: Option<u64>,
     pub success_rate: String,
     pub success_rate_value: Option<f64>,
+    pub first_token_p50_ms: Option<f64>,
+    pub first_token_p95_ms: Option<f64>,
+    pub latency_p95_ms: Option<f64>,
+    pub output_throughput_p50: Option<u64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub capacity_utilization: Option<f64>,
 }
 
 /// Dashboard 趋势摘要。
@@ -330,10 +373,14 @@ pub struct DashboardAccountUsageView {
     pub authentication_kind: String,
     pub email: String,
     pub plan_type: Option<String>,
+    pub plan_type_display: String,
     pub tokens: String,
     pub request_count: u64,
     pub request_buckets: Vec<DashboardAccountRequestBucketView>,
     pub quota_used_percent: Option<f64>,
+    pub usage_window: Option<crate::admin::accounts::AccountQuotaWindowView>,
+    pub metric_label: String,
+    pub metric_value: String,
     pub last_used: String,
 }
 
@@ -510,7 +557,7 @@ pub struct DashboardDataView {
     pub health_timeline: HealthTimelineView,
     pub wire_profiles: Vec<DashboardWireProfileView>,
     pub account_usage: Vec<DashboardAccountUsageView>,
-    pub usage_records: Vec<UsageRecordView>,
+    pub usage_records: Vec<UsageListRecordView>,
     pub pool_summary: DashboardPoolSummaryView,
     pub capacity_info: DashboardCapacityInfoView,
     pub rotation_strategy: String,
@@ -537,6 +584,7 @@ pub struct UsageSummaryView {
 pub struct OverviewHealthPointView {
     pub bucket: DateTime<Utc>,
     pub label: String,
+    pub total_requests: u64,
     pub success_requests: u64,
     pub failed_requests: u64,
     pub cancelled_requests: u64,
@@ -556,6 +604,7 @@ pub struct OverviewHealthView {
     pub incomplete_requests: u64,
     pub caller_error_requests: u64,
     pub success_rate: f64,
+    pub completion_rate: f64,
     pub request_change_rate: Option<f64>,
     pub success_rate_change: Option<f64>,
     pub points: Vec<OverviewHealthPointView>,
@@ -573,6 +622,15 @@ pub struct OverviewPerformancePointView {
     pub first_token_p50_ms: Option<f64>,
     pub first_token_p95_ms: Option<f64>,
     pub first_token_p99_ms: Option<f64>,
+    pub admission_decision_p50_ms: Option<f64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p50_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization: Option<f64>,
+    pub capacity_utilization_p95: Option<f64>,
 }
 
 /// 洞察性能摘要。
@@ -585,8 +643,20 @@ pub struct OverviewPerformanceView {
     pub first_token_p50_ms: Option<f64>,
     pub first_token_p95_ms: Option<f64>,
     pub first_token_p99_ms: Option<f64>,
+    pub admission_decision_p50_ms: Option<f64>,
+    pub admission_decision_p95_ms: Option<f64>,
+    pub account_selection_wait_p50_ms: Option<f64>,
+    pub account_selection_wait_p95_ms: Option<f64>,
+    pub output_throughput_p10: Option<u64>,
+    pub output_throughput_p50: Option<u64>,
+    pub output_throughput_p90: Option<u64>,
+    pub capacity_utilization: Option<f64>,
+    pub capacity_utilization_p95: Option<f64>,
     pub latency_coverage: f64,
     pub first_token_coverage: f64,
+    pub admission_decision_coverage: f64,
+    pub account_selection_wait_coverage: f64,
+    pub capacity_coverage: f64,
     pub points: Vec<OverviewPerformancePointView>,
 }
 
@@ -602,6 +672,8 @@ pub struct OverviewCostPointView {
     pub total_tokens: u64,
     pub estimated_cost: Option<String>,
     pub standard_cost: Option<String>,
+    pub no_cache_cost: Option<String>,
+    pub cache_savings: Option<String>,
     pub cached_token_rate: f64,
     pub cache_hit_request_rate: Option<f64>,
 }
@@ -612,7 +684,11 @@ pub struct OverviewCostPointView {
 pub struct OverviewCostView {
     pub estimated_cost: Option<String>,
     pub standard_cost: Option<String>,
+    pub no_cache_cost: Option<String>,
+    pub cache_savings: Option<String>,
+    pub tier_premium: Option<String>,
     pub cost_per_request: Option<String>,
+    pub cost_per_successful_request: Option<String>,
     pub tokens_per_request: f64,
     pub cached_token_rate: f64,
     pub cache_hit_request_rate: Option<f64>,
@@ -661,6 +737,12 @@ pub struct DiagnosticItemView {
     pub request_share: f64,
     pub average_latency_ms: Option<u64>,
     pub latency_p95_ms: Option<u64>,
+    pub first_token_p95_ms: Option<u64>,
+    pub non_completion_count: u64,
+    pub non_completion_rate: f64,
+    pub retry_count: u64,
+    pub retry_rate: f64,
+    pub impact_score: f64,
     pub estimated_cost: Option<String>,
     pub attempt_count: u64,
     pub total_tokens: u64,
@@ -682,20 +764,39 @@ pub struct OpsErrorView {
     pub request_id: Option<String>,
     pub client_api_key_id: Option<String>,
     pub kind: String,
+    pub operation: String,
+    pub protocol: Option<String>,
+    pub client_transport: Option<String>,
     pub provider: Option<String>,
     pub authentication_kind: Option<String>,
     pub account_id: Option<String>,
+    pub account_name: Option<String>,
+    pub account_email: Option<String>,
     pub route: String,
     pub model: Option<String>,
+    pub requested_model: Option<String>,
+    pub upstream_model: Option<String>,
+    pub service_tier: Option<String>,
     pub client_status_code: Option<i64>,
     pub upstream_status_code: Option<i64>,
     pub transport: Option<String>,
     pub attempt_index: Option<u32>,
     pub failure_class: String,
+    pub upstream_send_state: Option<String>,
+    pub provider_error_code: Option<String>,
     pub response_id: Option<String>,
     pub upstream_request_id: Option<String>,
     pub latency_ms: Option<u64>,
+    pub client_ip: Option<String>,
+    pub user_agent: Option<String>,
+    pub reasoning_effort: Option<String>,
+    pub reasoning_preset: Option<String>,
+    pub request_kind: Option<String>,
+    pub subagent_kind: Option<String>,
+    pub compact: Option<bool>,
     pub message: String,
+    /// 上游错误正文或 WebSocket close/error frame 原文；不做脱敏。
+    pub raw_upstream_error: Option<String>,
     pub metadata: OpsErrorMetadataView,
     pub created_at: DateTime<Utc>,
     pub created_at_display: String,
@@ -709,4 +810,16 @@ pub struct OpsErrorMetadataView {
     pub component: String,
     pub attempt_id: Option<String>,
     pub account_label: Option<String>,
+    pub continuation_affinity_hash: Option<String>,
+    pub continuation_previous_response_id_hash: Option<String>,
+    pub continuation_unavailable_reason: Option<String>,
+    pub upstream_connection_id: Option<String>,
+    pub upstream_connection_exit_reason: Option<String>,
+    pub upstream_connection_age_ms: Option<u64>,
+    pub upstream_connection_idle_ms: Option<u64>,
+    pub recovery_request_id: Option<String>,
+    pub recovered_at: Option<DateTime<Utc>>,
+    pub recovery_attempt_count: u32,
+    pub recovery_retry_delay_ms: Option<u64>,
+    pub recovery_total_latency_ms: Option<u64>,
 }

backend/crates/gateway-api/src/admin/presenter.rs

@@ -1,9 +1,9 @@
 //! Admin API 的展示层辅助：数值格式化。
 //!
-//! 按 docs/project-redundancy-boundary-audit.md BE-02 的目标，display 字段最终
-//! 迁移到前端；过渡期统一由本模块提供，避免 accounts/observability 各自维护。
+//! 当前 wire 仍保留 display 字段；统一由本模块提供，避免 accounts/observability
+//! 各自维护格式化规则。
 
-use gateway_core::accounting::Decimal;
+use gateway_core::metering::Decimal;
 
 /// 千分位格式化。
 #[must_use]