sub2api/openspec/changes/codex-manifest-pinned-accounts/design.md

## Context

动机见 proposal.md。与方案相关的现状：

- Codex Model Manifest 入口是 `OpenAIGatewayHandler.CodexModels`：先尝试用账号模型映射本地生成；否则循环 `SelectAccountForModelWithExclusions` 选账号、`FetchCodexModelsManifest` 拉取、`CompleteAPIKeyCodexModelsManifestForClient` 补全、`MergeGroupConfiguredCodexModels` 做分组过滤与 ETag。
- `FetchCodexModelsManifest` 对 API Key 账号走 `fetchCachedAPIKeyCodexModelsManifest`（30 秒新鲜、5 分钟乐观、单飞后台刷新），对 OAuth 账号直接请求上游且带 agent identity 任务恢复逻辑，不缓存。
- 分组配置落地链路：ent schema → SQL 迁移 → `service.Group` → `group_repo` 创建与更新 setter → `api_key_repo` 分组字段投影与 `groupEntityToService` → 认证快照 `api_key_auth_cache.go` 结构体及 impl 两处映射 → 管理端 DTO / mapper → `admin_group.go` 创建与更新 → 分组复制。`models_list_config` 是完整样板。
- 前端 `GroupsView.vue` 已有 7000 行；模型路由的账号选择用「标签 + 搜索输入 + 下拉」内联实现，`Select.vue` 仅支持单选。`components/admin/group/` 下已有抽出的表单片段组件（如 `ReasoningEffortPolicyFields.vue`）。
- 后端管理端账号列表接口支持 `platform`、`group`、`search` 过滤。

## Goals / Non-Goals

**Goals:**
- 固定账号模式的运行时逻辑放在 service 层，handler 只做分支与错误映射。
- 合并逻辑是纯函数，可独立单测。
- 缓存策略只有一套实现，OAuth 与 API Key 账号共用；固定账号模式不引入第二层分组级缓存。
- 新字段在所有分组加载路径上都可见，特别是认证快照与 API Key 投影。

**Non-Goals:**
- 不改动调度器逻辑与普通请求的账号选择。
- 不为账号解绑或删除增加对该配置的级联清理，运行时容忍失效 ID。
- 固定账号关闭时保留本地生成 manifest 的路径；开启时以指定账号上游发现为先，映射在发现后应用。
- 创建分组对话框不提供该配置。

## Decisions

### D1：配置以单个 JSONB 列存储
`groups.codex_models_manifest_config`，领域类型 `domain.GroupCodexModelsManifestConfig{Enabled bool; AccountIDs []int64; FallbackToScheduler bool}`，JSON 键为 `enabled`、`account_ids`、`fallback_to_scheduler`。
- 备选：三个独立列。否决：三个字段语义耦合，JSON 保证原子写入，且与 `models_list_config` 一致。
- 迁移文件 `234_group_codex_models_manifest_config.sql`：`ADD COLUMN IF NOT EXISTS ... JSONB NOT NULL DEFAULT '{}'::jsonb`。ent schema 使用 `field.JSON(...).Default(domain.GroupCodexModelsManifestConfig{})`。

### D2：校验放在 admin service，创建路径拒绝开启
- 新文件 `group_codex_models_manifest.go` 提供 `normalizeCodexModelsManifestConfig`（平台非 openai 归零；去重保序；`enabled=false` 时保留列表便于再次启用）与 `validateCodexModelsManifestConfig(ctx, groupID, cfg)`（`enabled=true` 时：非空、≤10、全部属于 `accountRepo.ListByGroup(groupID)` 且平台 openai）。
- 创建路径：`enabled=true` 直接 400。原因：账号绑定发生在分组创建之后，创建时无法校验成员关系；前端也不展示。
- 备选：校验放 handler。否决：需要访问账号仓储，且创建与更新两条路径共用，service 是唯一收口。

### D3：运行时入口与回退策略
- handler 在本地生成分支之前判断 `group.Platform == openai && cfg.Enabled`，调用 `gatewayService.FetchPinnedCodexModelsManifest(ctx, group, clientVersion)`。
- 返回值：`(*OpenAIModelsResponse, *Account, error)`，`*Account` 为配置顺序中第一个成功账号，用于 `setOpsSelectedAccount`。
- 「无可用账号」以哨兵错误 `ErrNoPinnedCodexModelsAccounts` 表示；「全部失败」返回最后一个上游错误。handler 根据 `FallbackToScheduler` 决定：true 时跌入现有调度器循环；false 时无可用账号返回 503、全部失败按 `infraerrors.Code(err)` 返回。
- 可用性判定：`IsActive() && Schedulable && !(AutoPauseOnExpired && 已过期)`。刻意不使用 `IsSchedulable()`，因为它包含限流、过载与临时不可调度窗口。
- 账号来源：`accountRepo.ListByGroup(group.ID)`（active 成员），按配置顺序筛选并跳过缺失 ID。
- 备选：复用 `BuildGroupConfiguredCodexModelsManifest` 已加载的账号列表以省一次查询。否决：那两个列表是可调度集合，会漏掉限流中的账号；一次按分组的查询成本可接受。

### D4：并发拉取与纯函数合并
- 用 `sync.WaitGroup` 对每个可用账号并发执行：`FetchCodexModelsManifest(ctx, acc, clientVersion, "")` → API Key 账号再 `CompleteAPIKeyCodexModelsManifestForClient`。结果写入按配置顺序索引的切片，失败记录到同下标的错误切片；各账号独立完成，不因单账号失败取消其他请求。
- Codex 合并函数 `mergeCodexModelsManifestBodies(bodies [][]byte) ([]byte, error)`：以第一个 body 的顶层信封为基底，`models` 按 slug 并集，先出现者优先；slug 为空或解析失败的条目按出现顺序保留一次。输出后设置 `ETag = codexModelsManifestBodyETag(body)`，再交给 `MergeGroupConfiguredCodexModels` 做分组过滤与 304 判断。
- 部分失败：`slog.Warn` 带 group_id 与失败账号 ID 列表。
- 实现放在新文件 `openai_codex_models_pinned.go`，避免继续膨胀 2300 行的主文件。

### D5：缓存统一并调整时效
- 将 `fetchCachedAPIKeyCodexModelsManifest` 泛化为 `fetchCachedOpenAIModels(ctx, request, fetch, ifNoneMatch)`，`fetch func(ctx, ifNoneMatch) (*CodexModelsManifest, error)` 由调用方提供：API Key 路径传 `fetchCodexModelsManifestUpstream`；OAuth 路径传一个包含 agent identity 任务恢复逻辑的闭包。`handleCodexModelsManifestAccountAuthError` 在 OAuth 闭包返回错误时照旧调用。
- 常量：`openAIModelsCacheTTL` 30s → 60s；`openAIModelsCacheStaleTTL` 保持 5 分钟；超过 5 分钟 `get` 删除条目返回 miss，调用方同步等待单飞结果，这与「超期强制等待上游刷新」一致，无需新状态。
- 缓存键已包含 Authorization 与 Version 头，令牌刷新自然失效旧条目；`client_version` 不同的客户端各占一个条目。
- 缓存键不含分组信息，多个分组共用同一账号时共享同一条目，新鲜期内零上游请求，乐观期与超期刷新均按键单飞，同一时刻一个账号只发一次上游请求；分组级处理（并集合并、自定义列表过滤、别名合并）都在缓存体的克隆上进行，不写回缓存。
- `openAIModelsCacheMaxEntries` 64 → 512。OAuth 路径接入后条目数为「账号数 × 客户端版本数」，64 条在大规模部署下会被淘汰导致额外上游请求；单条清单通常几十 KB，最坏情况内存占用为几十 MB 量级。
- 后台刷新使用 `context.Background()` 加上游 15 秒超时，与现状一致。
- 备选：为固定账号模式增加分组级合并结果缓存。否决：账号级缓存命中后合并只是内存操作，再加一层会引入两套时效与失效问题。

### D6：前端拆出独立组件
- 新组件 `components/admin/group/CodexManifestAccountsField.vue`：props 为 `groupId`、`modelValue`（`{enabled, account_ids, fallback_to_scheduler}`）与已选账号名称映射；内部实现开关、标签列表、带防抖的搜索输入与下拉、回退子开关。搜索调用 `adminAPI.accounts.list(1, 20, {search, platform: 'openai', group: String(groupId)})`。
- `GroupsView.vue` 只在编辑对话框 OpenAI 区块挂载组件，打开编辑时用 `adminAPI.accounts.getById` 解析已存 ID 的名称，失败则显示 `#<id>`。提交时开关打开且列表为空则 toast 报错并阻止。
- 备选：在 GroupsView 内联复制模型路由的搜索状态。否决：会再引入一套按 key 索引的搜索状态，文件已过大。

## Risks / Trade-offs

- [固定账号模式下每次缓存超期会向 N 个账号并发请求] → 账号数上限 10；账号级缓存 1 分钟新鲜期把稳态请求量压到低于现状。
- [限流中的账号被强制用于拉取 manifest 可能加重其 429] → 这是需求明确要求的行为；manifest 请求不占并发槽，且被缓存吸收；失败时按部分合并处理。
- [部分账号失败导致模型列表短暂缺项] → 记录警告日志；下一次超期刷新恢复。用户已确认接受。
- [OAuth manifest 首次接入缓存，乐观期内令牌已被撤销仍会返回旧内容最多 4 分钟] → manifest 非敏感数据，且撤销后的下一次刷新会失败并按现有 401 处理流程处理账号。
- [配置引用的账号被解绑或删除后成为脏 ID] → 运行时跳过；编辑对话框显示 `#<id>` 提示管理员清理；全部失效时按回退配置处理。
- [认证快照漏投影新字段会让开关静默失效] → 仓库已有投影对账集成测试，任务中包含更新该测试。

## Migration Plan

1. 部署包含迁移 234 的后端版本；迁移幂等，默认值 `{}` 反序列化为关闭状态，存量分组行为不变。
2. 缓存时效变化随部署即时生效，无需数据迁移。
3. 回滚：回退代码即可，列保留无副作用；如需彻底清理可手工 `DROP COLUMN`。

### D7：普通模型列表共用固定账号来源

- `GatewayHandler.Models` 在 OpenAI 分组开启固定账号时调用 `FetchPinnedOpenAIModelsList`；普通 `/models` 别名共用该入口。
- 共享原有配置、固定账号成员筛选、并发收集与部分失败规则；标准列表失败且允许回退时用现有 OpenAI 调度器选账，再调用普通目录获取。无账号为 503，全部上游失败保留上游错误语义，不以静态默认列表掩盖失败。
- API Key 使用标准模型 URL，不添加 Codex `client_version` 或身份请求头；从管理端抽出 API Key 请求构造。OAuth 复用 `FetchCodexModelsManifest` 和规范客户端版本，保留凭据引用、Agent Identity 恢复、401 状态处理。
- 响应/缓存元数据类型泛化为 `OpenAIModelsResponse`；抽出原始 HTTP 响应获取，Codex 专用转换/元数据补全仅在 manifest 路径执行。两种请求使用同一缓存实现，以响应格式、完整 URL、账号、凭据、代理和请求头区分条目；相同 OAuth 请求共享条目。
- 标准列表保留上游 `id`、`created`、`owned_by` 等字段。OAuth slug 转成标准条目；无创建时间采用 0。有效空数组是成功结果，缺失或错误的数组结构是上游错误。

### D8：固定账号目录的映射与过滤

- 每个成功账号先基于它的原始目录做公开名称投影，随后按配置顺序取并集。透传或无映射账号保留上游具体 ID；有映射账号仅暴露映射目标存在于该账号目录的具体公开名称。
- 具体映射键以及分组选择的具体名称可作为别名候选；通配映射可匹配上游/分组提供的具体候选，但通配规则本身不作为模型 ID 返回。复用 `ResolveMappedModel` 的匹配优先级。
- Codex 别名继承对应上游条目的能力元数据；固定账号开启时不再注入其他分组账号的本地别名。固定账号回退选出的账号也应用相同投影。
- 分组列表过滤最后执行，遵守配置顺序；过滤后为空返回 200 空数组，不使用静态默认模型。最终响应体计算 ETag 并处理 304。
- 前端文案说明该配置覆盖普通模型列表和 Codex Model Manifest。持久化配置名称和结构不变。

### D9：扩展验证

新增路由/handler 与 service 测试覆盖普通两条路由、固定账号优先、原始媒体和未知模型、映射与通配别名、部分/全部失败及调度器回退、凭据/请求协议隔离、OAuth 缓存复用、三段缓存时效、分组过滤隔离与空目录、最终 ETag。运行受影响 Go 测试（含 race）、完整 unit 检查及前端类型/组件检查。