easyai-ai-gateway/docs/design.md

EasyAI AI 网关中台设计文档

1. 建设目标

将现有 easyai-server-main / easyai-integration-api 中与 integration-platform 强相关的能力拆分为一个独立项目：

• 独立运行：后端 Go、复用 Agent memory 的 PostgreSQL 18（easyai-pgvector）、前端 React + TSX。
• 前端 UI：使用 shadcn-ui + Tailwind CSS + Radix UI + lucide-react，保持控制台形态与 EasyAI 运维后台一致。
• 独立部署：HTTP API、任务执行器、任务事件持久化与进度回调均由本服务承载；接入 EasyAI 主站时，业务前端实时推送继续复用 server-main 现有 WebSocket 网关。
• 身份双模式：支持 Gateway 本地账号注册登录，也支持沿用 easyai-server-main 的 JWT claim、角色权限和 OpenAPI sk-* 校验方式。
• 能力对接：作为 Chat、生图、生视频等模型能力网关，供 easyai-server-main 和前端直接调用。
• 渐进迁移：新服务稳定后，再让 server-main 的 OpenaiService / IntegrationPlatformService 切为远程调用门面。

2. 迁移边界

2.1 迁入 AI Gateway

能力	新服务职责
平台管理	平台 CRUD、启停、优先级、凭证配置、可用性检测、默认折扣系数
基准模型库	维护全量 provider、基准模型、模型能力、图像/视频/文本能力标签、基准定价和默认限流模板
模型管理	平台模型、模型类型、能力标签、上下文窗口、计费配置；支持从基准模型继承、按折扣继承或自由覆盖
模型路由	复用现有 assignClientsByModelName 的平台过滤、并发负载、优先级、队列等待语义
生成任务	Chat、图片生成、图片编辑、视频生成、语音、Embedding 等任务入口
队列执行	按平台/模型/方法维度做并发控制、等待队列、超时、重试；队列状态必须持久化，服务异常重启后可恢复
测试模式	支持 simulation / dry-run，不向真实平台提交任务，仍完整走路由、队列、限流、重试、进度、结果归一流程
计费预估	在任务创建前或前端配置面提供 estimated billing，且必须使用与真实路由一致的有效模型价格
任务结果	保存任务请求、状态、结果摘要、billings，向主服务发送结算事件
推送	承接任务级进度事件，提供类似原 RxJS Observable 的中间过程返回能力；业务实时进度通过配置回调地址回调 server-main 内部任务进度接口，再由主服务复用原 WebSocket 网关推给业务前端

2.2 接入 server-main 时仍保留在 server-main

能力	原因
用户、组织、租户、角色	EasyAI 主站模式下仍是主账号体系；Gateway 保存同步副本和策略快照
余额、资源包、扣费流水	需要复用现有账单锁、组织扣费、消费记录
API Key 创建与撤销	接入模式下 sk-* 生命周期属于主服务用户体系；独立模式由 Gateway 本地 API Key 模块承接
文件上传	复用 server-main 已开放的文件上传接口，OSS/COS/S3 密钥和上传实现继续只落在主服务
业务 WebSocket 网关	现有前端已经订阅主服务 WebSocket 通道，Gateway 通过任务进度回调接入，不直接替换业务推送链路
对话、绘图历史、工作流历史	与产品域模型绑定，Gateway 只返回任务结果和结算载荷

3. 总体架构

flowchart LR
  subgraph client [调用方]
    FE[React / easyai-main-web]
    MAIN[easyai-server-main]
    OPENAPI[OpenAPI Client]
  end

  subgraph gw [API Gateway / Ingress]
    HTTP[HTTP Routes]
    PUSH[SSE / WebSocket Routes]
  end

  subgraph aigw [EasyAI AI Gateway]
    API[Go HTTP API]
    AUTH[Auth Middleware]
    ROUTER[Model Router]
    QUEUE[Queue + Runtime]
    CALLBACK[Task Progress Callback]
    VENDOR[Vendor Clients]
    ADMIN[React Admin Console]
  end

  subgraph data [Data]
    PG[(Agent memory PostgreSQL<br/>easyai-pgvector)]
    REDIS[(Redis later)]
  end

  subgraph servermain [server-main]
    USER[User / Org]
    APIKEY[API Key Verify]
    WSGW[WebSocket Gateway]
    BILL[Billing + Ledger]
    FILES[Open File Upload]
  end

  FE --> HTTP --> API
  FE <-->|business progress ws| WSGW
  ADMIN --> PUSH
  OPENAPI --> HTTP --> API
  MAIN -->|internal HTTP| API
  ADMIN --> API
  API --> AUTH
  AUTH -->|JWT local verify| API
  AUTH -->|sk-* delegate| APIKEY
  API --> ROUTER --> QUEUE --> VENDOR
  API --> PG
  QUEUE --> PG
  QUEUE --> CALLBACK -->|POST task progress callback to server-main| WSGW
  QUEUE -->|settlement event| BILL
  API -->|POST /v1/files/upload| FILES

4. Monorepo 方案

本脚手架采用 Nx + pnpm + go.work：

• Nx 负责任务编排、缓存、前后端统一命令：dev、build、test、migrate。
• go.work 管理 Go 模块，避免把 Go 项目硬塞进 Node 包管理。
• pnpm-workspace.yaml 管理 React 前端与 TypeScript contracts。
• 前端控制台使用 shadcn-ui 作为组件体系，配套 Tailwind CSS、Radix UI primitive、lucide-react 图标和 class-variance-authority 管理组件变体。

选择这个组合的原因：

• 与 EasyAI 现有 Nx 使用习惯接近，便于团队统一命令。
• Go 后端保持 Go 原生模块边界，后续可以拆 apps/worker、libs/go/*。
• 前端仍可复用 React 生态和 TSX 风格，contracts 可给前端、SDK、BFF 共用。
• shadcn-ui 代码是可拷贝进仓库的 TSX 组件，不绑定运行时 UI 框架，适合后续沉淀平台管理、队列监控、模型计费配置等复杂表单。

4.1 前端 UI 约束

• 基础组件统一从 apps/web/src/components/ui/* 引入，不直接散落自定义 button/input/table 样式。
• 首期需要引入并固化：Button、Input、Textarea、Select、Switch、Checkbox、Tabs、Dialog、Sheet、Table、Badge、Alert、Toast/Sonner、Tooltip、Progress、DropdownMenu、Form。
• 图标统一使用 lucide-react，按钮类动作优先用语义图标加 tooltip。
• 控制台不是营销页，布局以高密度管理视图为主：平台列表、模型配置、队列监控、任务详情、客户端运行状态、限流配置、重试策略。
• 主题 token 以 CSS variables 管理，后续可与 EasyAI 全局后台色板对齐。

5. 授权设计

5.1 身份模式与 JWT 用户授权

Gateway 支持三种身份模式：

• standalone：Gateway 本地账号注册登录，签发 Gateway JWT。
• server-main：只接受 server-main JWT / OpenAPI sk-* 校验结果，用户与租户从主服务同步。
• hybrid：同时接受 Gateway 本地账号和 server-main 身份，按 source 区分。

接入 server-main 时兼容主服务 JWT：

• secret：读取 CONFIG_JWT_SECRET，默认值与现有 jwtConstants.secret 保持一致。
• token 有效期：由 server-main 签发控制，当前 access token 为 600s，refresh token 为 7d。
• claim 兼容：
  • sub：用户 ID
  • username
  • role
  • tenantId
  • gatewayTenantId
  • tenantKey
  • source
  • gatewayUserId
  • userGroupId / userGroupKey / userGroupKeys
  • sso_id
  • API Key 场景扩展：apiKeyId、apiKeySecret、apiKeyName

Gateway 本地登录首期只签发短期 access token，不做 refresh token；接入 server-main 的刷新仍走主服务。

5.1.1 本地账号注册登录

首期普通账号只做用户名/邮箱 + 密码：

Method	Path	Permission	说明
POST	/api/v1/auth/register	public	注册 Gateway 本地账号，创建或加入租户，返回 access token
POST	/api/v1/auth/login	public	本地账号登录，返回 access token

注册字段：

• username / email：至少一个必填。
• password：至少 8 位，落库为 bcrypt hash。
• tenantKey / tenantName：可选；未传时创建个人租户。

安全边界：

• 普通注册首期只给 user 角色。
• 允许注册时填写已有 tenantKey 只是脚手架行为；正式上线前需要租户邀请、域名校验或管理员审批。
• server-main 模式可关闭本地注册登录，只保留外部 token 入口。

5.2 权限等级

权限枚举与 server-main 保持一致：

Permission	用途
public	健康检查、公开模型列表等
basic	普通用户任务创建、任务查询
creat	创作者级能力
power	平台配置、模型配置、计费配置
manager	超级管理与危险操作

角色映射与 server-main 一致：user、creator、operator、manager、admin。

5.3 OpenAPI API Key

对于 Authorization: Bearer sk-* 或 x-comfy-api-key：

1. Gateway 不直接持有 API Key hash。
2. Gateway 调用 server-main 的内部校验接口。
3. server-main 返回标准用户 claim。
4. Gateway 将 claim 放入请求上下文，后续任务、结算事件都带 apiKeyId / apiKeyName。

建议在 server-main 增加内部接口：

POST /internal/platform/auth/verify-api-key
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
Content-Type: application/json

{ "apiKey": "sk-..." }

5.4 内部服务授权

server-main 调 Gateway 内部接口时使用服务令牌：

Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
X-EasyAI-Actor: easyai-server-main

内部令牌只用于服务间调用，不替代用户上下文。用户发起的任务仍应透传用户 JWT 或 API Key claim。

6. 接口规范与兼容路由

6.1 兼容优先原则

AI Gateway 的外部接口必须以“兼容现有 EasyAI 路由、请求 DTO、响应结构、错误码、流式语义”为第一目标，不能要求前端或 server-main 因拆分服务而大面积改调用路径。

• 管理面兼容：沿用原 integration-platform、integration/platform-api、integration-platform/snapshots 路由。
• 站内生成接口兼容：沿用原 OpenaiController 根路径接口，例如 /chat/completions、/images/generations。
• OpenAPI 兼容：沿用 /v1/* 路由，例如 /v1/chat/completions、/v1/images/generations，API Key 语义与原来一致。
• 新增接口隔离：/api/v1/* 只用于 Gateway 自身控制台、调试、内部 SDK 或新能力，不作为迁移期替代原路由。
• 响应包装：对原来返回 ResOp 的管理接口继续返回同形态；对 OpenAI-compatible 接口保持原 JSON / stream chunk 结构；对任务类接口保持原 taskId、status、url、billings 等字段语义。
• 路径匹配顺序：迁移 integration-platform 时必须保留静态路径优先于 :id / :action/:id 的规则，避免 models/list/enabled、dynamic-priority/:id、scene-script/:id/partial 被动态路由误吞。

6.2 平台管理兼容路由

Method	Path	Permission	说明
POST	/integration-platform	power	创建平台
POST	/integration-platform/preset	power	创建预置平台
GET	/integration-platform	power	平台列表
GET	/integration-platform/list/ops-compact	power	运维精简列表
GET	/integration-platform/queue-stats	power	队列统计
POST	/integration-platform/clear-queue/:platformId	power	清理平台队列
POST	/integration-platform/find-by-ids	power	按 ID 批量查平台
POST	/integration-platform/find-by-model	basic	按模型查候选平台
GET	/integration-platform/models/list/enabled	basic	启用模型列表
GET	/integration-platform/models/list/all	power	全量模型列表
PATCH	/integration-platform/dynamic-priority/:id	power	动态优先级
DELETE	/integration-platform/dynamic-priority/:id	power	删除动态优先级
POST	/integration-platform/disable/:id	power	禁用平台
POST	/integration-platform/enable-model/:id	power	启用平台模型
PATCH	/integration-platform/scene-script/:id/partial	power	局部更新场景脚本
PATCH	/integration-platform/:action/:id	power	兼容启停等 action
PATCH	/integration-platform/:id	power	更新平台
DELETE	/integration-platform/:id	manager	删除平台
GET	/integration-platform/models/:type	basic	按类型查模型
GET	/integration-platform/models/strict/:type	basic	按类型严格查模型
POST	/integration-platform/models/estimatedBilling	basic	预估扣费
POST	/integration-platform/models/estimatedBilling/:workflowId	basic	工作流预估扣费
POST	/integration-platform/resetException/:id	power	重置异常状态
POST	/integration-platform/:id/copy	power	复制平台
GET	/integration-platform/:id	power	平台详情

兼容表中的旧权限用于保持原接口语义；在新 Gateway 第一阶段，所有写入 provider / platform 凭证、启停平台、删除平台、复制平台的接口都要额外要求全局管理员，即 manager/admin 角色。

6.3 平台 API 配置兼容路由

Method	Path	Permission	说明
POST	/integration/platform-api	power	创建 API 配置
GET	/integration/platform-api	power	API 配置列表
GET	/integration/platform-api/:id	power	API 配置详情
PATCH	/integration/platform-api/:id	power	更新 API 配置
DELETE	/integration/platform-api/:id	manager	删除 API 配置
POST	/integration/platform-api/execute	power	调试执行
GET	/integration-platform/snapshots/platform/:platformId	power	平台快照

6.4 站内生成兼容路由

Method	Path	说明
GET	/models/list	站内模型列表
POST	/chat/completions	站内 Chat
POST	/chat/completions/cancel/:requestId	取消 Chat
POST	/chat/structured-output	结构化输出
POST	/images/generations	生图
POST	/images/edits	图片编辑
POST	/video/generations	生视频
POST	/embeddings	Embeddings
GET	/embeddings/models	Embedding 模型
GET	/ai/result/:taskId	任务结果

6.5 OpenAPI 兼容路由

Method	Path	说明
POST	/v1/chat/completions	OpenAI-compatible Chat
POST	/v1/chat/completions/cancel/:requestId	取消 Chat
POST	/v1/images/generations	生图
POST	/v1/images/edits	图片编辑
POST	/v1/video/generations	生视频
GET	/v1/ai/result/:taskId	任务结果
GET	/v1/ai/cancel/:taskId	取消任务
POST	/v1/embeddings	Embeddings
GET	/v1/embeddings/models	Embedding 模型
GET	/v1/models	OpenAI-compatible 模型列表
GET	/v1/models/list	EasyAI 模型列表

/v1/balance、/v1/files/upload、/v1/creatToken、/v1/removeToken 与用户余额、文件、API Key 生命周期强绑定，默认仍由 server-main 保留；若网关暴露同路径，只能做兼容代理或调用 server-main 内部接口。

6.6 Gateway 新增接口

Method	Path	Permission	说明
POST	/api/v1/auth/register	public	Gateway 本地账号注册，invitationCode 可选
POST	/api/v1/auth/login	public	Gateway 本地账号登录
GET	/api/v1/me	basic	网关当前身份调试
GET	/api/v1/catalog/providers	power	基准 provider 列表
GET	/api/v1/catalog/base-models	power	基准模型库列表
GET	/api/v1/catalog/base-models/:id	power	基准模型详情
GET	/api/v1/tenants	power	网关租户列表，支持本地租户和 server-main 同步租户
GET	/api/v1/tenants/:id	power	租户详情、来源、策略和同步状态
POST	/api/v1/tenants/sync	power	从 server-main 拉取或接收租户同步
GET	/api/v1/tenant-invitations	power	本地租户邀请码列表
POST	/api/v1/tenant-invitations	power	创建本地注册邀请码
GET	/api/v1/users	power	网关用户列表，支持本地用户和 server-main 同步用户
GET	/api/v1/users/:id	power	用户详情、来源、角色、用户组和同步状态
POST	/api/v1/users/sync	power	从 server-main 拉取或接收用户同步
GET	/api/v1/user-groups	power	用户组策略列表
GET	/api/v1/user-groups/:id	power	用户组详情、成员与策略
POST	/api/v1/user-groups/:id/sync	power	同步用户组策略到 server-main
GET	/api/v1/wallet/accounts	basic	独立模式本地余额账户
GET	/api/v1/wallet/transactions	basic	独立模式本地余额流水
GET	/api/v1/recharge/orders	basic	独立模式充值订单
POST	/api/v1/recharge/orders	basic	独立模式创建充值订单
GET	/api/v1/api-keys	basic	独立模式 API Key 列表
POST	/api/v1/api-keys	basic	独立模式创建 API Key
PATCH	/api/v1/api-keys/:id/disable	basic	禁用本地 API Key
POST	/api/v1/pricing/estimate	basic	使用 effective pricing resolver 做价格预估
GET	/api/v1/pricing/rules	power	定价规则列表
GET	/api/v1/tasks/:taskId	basic	Gateway 任务详情
GET	/api/v1/tasks/:taskId/events	basic	SSE 任务进度
GET	/api/v1/runtime/clients	power	客户端运行状态
GET	/api/v1/runtime/queues	power	队列与限流状态
GET	/api/v1/runtime/rate-limit-windows	power	TPM/RPM 当前窗口与并发 lease 状态
POST	/api/v1/runtime/tasks/:taskId/replay	power	重放任务事件
POST	/api/v1/runtime/tasks/:taskId/callbacks/replay	power	重放任务进度回调 outbox

6.7 内部接口

Method	Path	调用方	说明
POST	/internal/v1/settlements	Gateway worker	回调主服务结算失败时补偿
POST	${TASK_PROGRESS_CALLBACK_URL}	Gateway worker	任务进度回调到 server-main 内部任务进度接口，实际路径由配置决定
POST	/internal/platform/tenants/sync	server-main	同步租户增量、禁用状态和租户策略到 Gateway
POST	/internal/platform/users/sync	server-main	同步用户增量、禁用状态、角色和用户组关系到 Gateway
POST	/internal/platform/user-groups/sync	server-main	同步用户组、折扣和限流策略到 Gateway
POST	/internal/v1/task-callbacks	server-main	迁移期主服务回写历史或任务绑定

7. 数据模型

数据模型按“基准模型库 -> 平台实例 -> 平台模型覆盖 -> 任务运行态”分层：

• 基准模型库保存 provider、canonical model、能力 schema、默认能力、基准价格、默认限流模板，是所有平台模型的 fallback。
• 创建平台时可以设置 default_discount_factor，平台模型默认按“基准价格 x 折扣系数”计算；没有任何平台侧配置时，能力和价格都 follow 基准模型。
• 平台模型可以覆盖能力、定价和限流。覆盖只作用于该平台模型，不能反向污染基准模型库。
• 租户是隔离域：独立模式下 Gateway 管理 gateway_tenants；接入模式下同步 server-main 租户/组织，任务、用户、平台可见性、限流与计费策略都需要带租户上下文。
• 用户是身份域：独立部署时 Gateway 自己维护 gateway_users、登录、API Key、余额、充值订单和钱包流水；接入 server-main 时 Gateway 保存用户同步副本和策略快照，认证、余额、充值、订单仍可由 server-main 作为事实源。
• 用户组是策略作用域：不同用户组可以绑定充值折扣、模型计费折扣、TPM/RPM/并发、队列优先级、API Key 配额等策略。独立模式由 Gateway 完整执行；server-main 模式下充值和余额执行归主服务，Gateway 执行模型调用侧策略。
• estimated billing、真实任务 billings、控制台价格预览必须走同一个 effective pricing resolver。

7.0 身份运行模式

Gateway 需要支持三种身份运行模式，默认配置为 IDENTITY_MODE=hybrid：

模式	配置	用户事实源	API Key / 登录	用户组策略	适用场景
Standalone	IDENTITY_MODE=standalone	Gateway gateway_users	Gateway 本地用户、密码/SSO、API Key	Gateway 维护并执行充值折扣、调用折扣、限流和并发	独立商业化或单独部署
Server-main gateway	IDENTITY_MODE=server-main	server-main	JWT 复用主服务 secret，sk-* 调用主服务校验	server-main 与 Gateway 同步；主服务执行充值/余额，Gateway 执行调用折扣和限流	EasyAI 主站拆分后的 AI 网关
Hybrid	IDENTITY_MODE=hybrid	Gateway + server-main	两种方式并存，按 source 区分	按 source + group_key 合并，冲突以更高优先级策略为准	迁移灰度或私有化集成

本地注册规则：

• 普通注册默认开放，invitationCode 可选；不填邀请码时创建或复用 tenantKey 对应的 Gateway 本地租户，未填 tenantKey 时生成个人租户。
• 填写邀请码时必须命中 gateway_tenant_invitations 的有效记录，注册用户加入邀请码指定租户，并可绑定邀请码指定用户组。
• 平台凭证、provider 凭证和全局模型配置暂时只允许全局管理员维护；租户侧先只做模型使用、用量查看和策略展示。

身份解析流程：

1. 从 JWT / API Key / 内部调用 token 解析出外部身份。
2. 根据 source + external_user_id 在 gateway_users 找到或创建同步副本。
3. 按用户、租户、API Key、组织命中 gateway_user_group_memberships。
4. 根据用户组优先级和策略合并规则得到 effective policy。
5. 创建任务时把 gateway_user_id、user_source、user_group_id、user_group_key、user_group_policy_snapshot 写入 gateway_tasks，后续重试和结算不受同步变更影响。

7.0.1 多租户模型

多租户支持不能只停留在 claim 的 tenantId 字符串，Gateway 需要有自己的租户表和执行上下文：

• gateway_tenants 保存租户事实或同步副本，使用 source + external_tenant_id 幂等同步。
• gateway_users.gateway_tenant_id 关联 Gateway 租户，tenant_id / tenant_key 保留与 server-main 兼容的外部标识。
• gateway_tasks 固化 gateway_tenant_id、tenant_id、tenant_key，确保任务恢复、重试、结算和审计不受后续租户变更影响。
• integration_platforms.visibility_scope 区分 global、tenant、private，租户专属平台只能被对应租户路由到。
• 限流、定价、用户组和 quota 都可以以租户作为 scope；同一请求会同时命中 global、tenant、user_group、user、api_key 等策略。
• 控制台数据查询默认按当前用户租户过滤；power/manager 可跨租户查看和管理。

7.1 integration_platforms

保存平台实例与凭证：

• provider：平台类型，如 openai、runninghub、jimeng。
• name：运营可识别名称。
• base_url
• auth_type
• credentials：加密后的凭证 JSON，后续应接入 KMS。
• config：限流、超时、重试、平台私有配置。
• visibility_scope：global、tenant、private，用于多租户平台可见性。
• tenant_id / tenant_key：租户专属平台的归属。
• default_discount_factor：平台默认折扣系数，基于基准模型价计算平台有效价。
• priority
• status

7.2 platform_models

保存平台模型配置：

• platform_id
• base_model_id：关联基准模型库，未配置能力/价格时 follow 基准模型。
• model_name
• model_type：chat、image、video、audio 等。
• capabilities：平台模型有效能力，来自基准模型能力与平台覆盖合并。
• pricing_mode：inherit、inherit_discount、custom。
• discount_factor：模型级折扣，未设置时使用平台默认折扣。
• billing_config：平台模型有效计费配置，来自基准价、折扣和自定义覆盖。
• enabled

7.3 gateway_tasks

保存任务请求与状态：

• kind：chat.completions、images.generations、videos.generations
• user_id：请求 claim 中的用户 ID，独立模式为 Gateway 用户 ID，接入模式为 server-main 用户 ID。
• gateway_user_id：Gateway 本地用户表 ID，用于关联同步副本和审计。
• user_source：gateway、server-main、sync。
• tenant_id
• user_group_id / user_group_key
• user_group_policy_snapshot：任务创建时解析出的用户组策略快照，用于审计和重试稳定性。
• model
• request
• status：queued、running、succeeded、failed、cancelled
• queue_key：限流队列 key，例如 ${platformKey}-${model} 或 ${provider}-${methodName}
• priority
• idempotency_key
• remote_task_id
• remote_task_payload
• run_mode：production、simulation
• simulation_profile
• simulation_seed
• locked_by
• locked_at
• heartbeat_at
• next_run_at
• result
• billings
• error

7.4 gateway_task_attempts

保存每一次客户端尝试，支持“上一个客户端失败，下一个客户端重试”的完整审计：

• task_id
• attempt_no
• platform_id
• client_id
• model_id
• status：submitted、polling、succeeded、failed、skipped
• retryable
• error_code
• error_message
• remote_task_id
• simulated
• request_snapshot
• response_snapshot
• started_at
• finished_at

7.5 gateway_task_events

保存任务执行过程中的事件，用于控制台 SSE / WebSocket 重放、进度回调 outbox 投递与服务重启后的进度恢复：

• task_id
• seq：单任务内递增序号
• event_type：queue_status、node_status、progress、partial_result、completed、failed
• status
• progress
• message
• payload
• created_at

客户端断线重连时可通过 Last-Event-ID 或 afterSeq 回放事件。

7.5.1 gateway_task_callback_outbox

保存投递给 server-main 内部任务进度接口的回调。Gateway 产生事件后先写 gateway_task_events，再写 callback outbox，由独立 worker 按配置的 TASK_PROGRESS_CALLBACK_URL 投递，失败后可重试。

• task_id
• event_id / seq：与 gateway_task_events 对应，用于幂等与顺序控制。
• callback_url：当前使用的回调地址快照，避免配置变化影响已排队事件。
• payload：回调给 server-main 的标准事件载荷。
• status：pending、delivering、delivered、failed、skipped
• attempts
• next_attempt_at
• last_error
• delivered_at

7.6 runtime_client_states

保存平台客户端的运行时状态：

• client_id
• platform_id
• provider
• method_name
• queue_key
• running_count
• waiting_count
• limiter_ratio
• cooldown_until
• last_assigned_at
• last_error
• updated_at

该表用于恢复与观测；实时并发计数仍可通过事务锁、SKIP LOCKED、Redis token bucket 或内存计数加 PG 校验组合实现，但 PG 是最终事实源。

7.7 gateway_upload_assets

保存网关任务引用的上传资产：

• task_id
• source：server-main-open-upload、remote-url、multipart、simulation
• server_main_file_id：主服务返回的文件 ID。
• object_key
• url
• content_type
• size
• checksum
• metadata

7.8 settlement_outbox

保存结算事件 outbox：

• task_id
• event_type
• payload
• status
• attempts
• next_attempt_at

结算事件必须按 eventId / taskId 幂等，不能因为 Gateway 重启、HTTP 回调失败或 MQ 抖动重复扣费。

7.9 表结构草案

以下为首期 PostgreSQL 表结构草案。字段类型以后续 migration 为准，但语义和索引边界应保持稳定。

7.9.1 model_catalog_providers

字段	类型	约束	说明
id	uuid	PK	基准 provider ID
provider_key	text	unique, not null	稳定 provider key，如 openai、runninghub、jimeng
display_name	text	not null	展示名称
provider_type	text	not null	openai_compatible、workflow_app、video_vendor、audio_vendor
capability_schema	jsonb	not null, default {}	provider 支持的能力字段定义
default_rate_limit_policy	jsonb	not null, default {}	provider 默认 TPM/RPM/并发模板
status	text	not null	active、deprecated、hidden
metadata	jsonb	not null, default {}	文档链接、logo、排序等
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• uniq_model_catalog_provider_key(provider_key)
• idx_model_catalog_provider_status(status)

7.9.2 base_model_catalog

保存全量基准模型。这个表不代表某个平台已经开通该模型，而是标准模型与价格来源。

字段	类型	约束	说明
id	uuid	PK	基准模型 ID
provider_id	uuid	FK	所属基准 provider
provider_key	text	not null	冗余 provider key，方便查询
canonical_model_key	text	unique, not null	Gateway 内部标准模型 key
provider_model_name	text	not null	供应商原始模型名
model_type	text	not null	chat、image、video、audio、embedding、music、digital_human、model_3d
display_name	text	not null	展示名称
capabilities	jsonb	not null, default {}	上下文、多模态、参考图/视频/音频、尺寸、时长、质量等基准能力
base_billing_config	jsonb	not null, default {}	基准计费配置
default_rate_limit_policy	jsonb	not null, default {}	默认 TPM/RPM/并发限制模板
pricing_version	int	not null, default 1	基准价格版本
status	text	not null	active、deprecated、hidden
metadata	jsonb	not null, default {}	供应商文档、排序、标签
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• uniq_base_model_catalog_key(canonical_model_key)
• idx_base_model_catalog_provider(provider_key, model_type, status)
• idx_base_model_catalog_capabilities 使用 GIN(capabilities)

7.9.3 model_pricing_rules

保存基准模型和平台模型的可版本化价格规则。平台模型没有自定义规则时，使用 base_model_catalog.base_billing_config 并应用折扣。

字段	类型	约束	说明
id	uuid	PK	价格规则 ID
scope_type	text	not null	base_model、platform、platform_model
scope_id	uuid	nullable	对应基准模型、平台或平台模型 ID
resource_type	text	not null	text_input、text_output、image、video、audio、music、digital_human、model
unit	text	not null	1k_tokens、image、5s、second、character_1k、item
base_price	numeric	not null	基准单价，单位使用 EasyAI resource / credit
currency	text	not null, default resource	resource、credit、cny、usd
base_weight	jsonb	not null, default {}	固定权重，如默认倍率
dynamic_weight	jsonb	not null, default {}	分辨率、质量、时长、有无音频等动态权重
effective_from	timestamptz	nullable	生效开始
effective_to	timestamptz	nullable	生效结束
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• idx_model_pricing_scope(scope_type, scope_id, resource_type)
• idx_model_pricing_effective(effective_from, effective_to)

7.9.4 gateway_tenants

保存 Gateway 可识别的租户。独立模式下它是租户事实表；接入 server-main 时它是租户/组织同步副本。

字段	类型	约束	说明
id	uuid	PK	Gateway 租户 ID
tenant_key	text	unique, not null	Gateway 内稳定租户 key
source	text	not null	gateway、server-main、sync
external_tenant_id	text	nullable	外部租户/组织 ID
name	text	not null	租户名称
description	text	nullable	说明
default_user_group_id	uuid	FK nullable	默认用户组
plan_key	text	nullable	套餐或商业计划 key
billing_profile	jsonb	not null, default {}	独立模式账务资料或接入模式同步摘要
rate_limit_policy	jsonb	not null, default {}	租户级 TPM/RPM/并发/队列策略
auth_policy	jsonb	not null, default {}	注册、邀请、SSO、域名限制等认证策略
metadata	jsonb	not null, default {}	同步、运营、展示扩展信息
status	text	not null	active、disabled、locked、deleted
synced_at	timestamptz	nullable	最近同步时间
source_updated_at	timestamptz	nullable	外部源更新时间
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间
deleted_at	timestamptz	nullable	软删除时间

索引：

• uniq_gateway_tenants_tenant_key(tenant_key)
• uniq_gateway_tenants_source_external(source, external_tenant_id)
• idx_gateway_tenants_status(status, created_at)

7.9.5 gateway_users

保存 Gateway 可识别的用户。独立模式下它是用户事实表，并与本地 API Key、钱包、充值订单形成闭环；接入 server-main 时它是用户同步副本和策略执行缓存，不迁入主服务余额、订单、充值流水。

字段	类型	约束	说明
id	uuid	PK	Gateway 用户 ID
user_key	text	unique, not null	Gateway 内稳定用户 key
source	text	not null	gateway、server-main、sync
external_user_id	text	nullable	外部用户 ID，server-main 模式为主服务用户 ID
username	text	not null	登录名或同步用户名
display_name	text	nullable	展示名
email	text	nullable	邮箱
phone	text	nullable	手机号
avatar_url	text	nullable	头像
password_hash	text	nullable	仅独立模式使用，接入主服务时为空
gateway_tenant_id	uuid	FK nullable	Gateway 租户 ID
tenant_id	text	nullable	外部租户 ID 或兼容 claim
tenant_key	text	nullable	Gateway 租户 key
default_user_group_id	uuid	FK nullable	默认用户组
roles	jsonb	not null, default []	user、creator、operator、admin 等角色
auth_profile	jsonb	not null, default {}	SSO、MFA、API Key 策略等认证资料
metadata	jsonb	not null, default {}	同步、运营、展示扩展信息
status	text	not null	active、disabled、locked、deleted
last_login_at	timestamptz	nullable	最近登录时间
synced_at	timestamptz	nullable	最近同步时间
source_updated_at	timestamptz	nullable	外部源更新时间
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间
deleted_at	timestamptz	nullable	软删除时间

索引：

• uniq_gateway_users_user_key(user_key)
• uniq_gateway_users_source_external(source, external_user_id)
• idx_gateway_users_status(status, created_at)
• idx_gateway_users_tenant(tenant_id, tenant_key, status)

同步规则：

• source='gateway'：用户由 Gateway 创建和禁用，可独立使用；充值、余额、API Key 由 Gateway 本地模块承接。
• source='server-main'：用户由主服务同步，Gateway 只保存执行模型调用所需字段；禁用、角色、用户组变更以主服务事件或同步任务为准。
• 同一个外部用户以 source + external_user_id 幂等 upsert，避免用户名变更造成重复用户。
• 用户被禁用后，新任务拒绝进入队列；已运行任务按任务策略快照继续或按管理员策略取消。

7.9.6 gateway_user_groups

保存用户组及其策略。用户组可以由 Gateway 管理，也可以从 server-main 同步；独立模式下 Gateway 执行全部策略，接入模式下充值和余额仍以 server-main 为事实源。

字段	类型	约束	说明
id	uuid	PK	用户组 ID
group_key	text	unique, not null	稳定用户组 key，如 free、pro、enterprise
name	text	not null	展示名称
description	text	nullable	说明
source	text	not null	gateway、server-main、sync
priority	int	not null, default 100	多组命中时优先级，越小越优先
recharge_discount_policy	jsonb	not null, default {}	充值折扣/赠送资源策略；独立模式由 Gateway 执行，接入模式由 server-main 执行
billing_discount_policy	jsonb	not null, default {}	模型调用计费折扣策略，用于 estimated billing 和 billings
rate_limit_policy	jsonb	not null, default {}	用户组 TPM/RPM/并发/队列策略
quota_policy	jsonb	not null, default {}	日/月额度、API Key 额度、最大任务数
metadata	jsonb	not null, default {}	展示、运营、同步元数据
status	text	not null	active、disabled
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

示例：

{
  "recharge_discount_policy": {
    "type": "tiered_bonus",
    "tiers": [
      { "minAmount": 100, "bonusRatio": 0.05 },
      { "minAmount": 1000, "bonusRatio": 0.12 }
    ]
  },
  "billing_discount_policy": {
    "defaultDiscountFactor": 0.9,
    "modelTypeDiscounts": { "chat": 0.85, "image": 0.95 }
  },
  "rate_limit_policy": {
    "rules": [
      { "metric": "rpm", "limit": 1200, "windowSeconds": 60 },
      { "metric": "tpm_total", "limit": 300000, "windowSeconds": 60 },
      { "metric": "concurrent", "limit": 50, "leaseTtlSeconds": 900 }
    ]
  }
}

7.9.7 gateway_user_group_memberships

保存用户组成员关系。一个用户、租户或 API Key 可命中多个组，运行时按组优先级和策略合并规则解析有效策略。

字段	类型	约束	说明
id	uuid	PK	成员关系 ID
group_id	uuid	FK	用户组 ID
principal_type	text	not null	user、tenant、api_key、organization
principal_id	text	not null	对应 Gateway 用户 ID、server-main 外部用户 ID、租户 ID、API Key ID 或组织 ID
source	text	not null	gateway、server-main、sync
priority	int	not null, default 100	关系级优先级
effective_from	timestamptz	nullable	生效开始
effective_to	timestamptz	nullable	生效结束
status	text	not null	active、disabled
metadata	jsonb	not null, default {}	同步和运营元数据
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• uniq_user_group_membership(group_id, principal_type, principal_id)
• idx_user_group_membership_principal(principal_type, principal_id, status)
• idx_user_group_membership_effective(effective_from, effective_to)

成员解析规则：

• 独立模式优先使用 principal_type='user' + gateway_users.id。
• 接入 server-main 时可使用 principal_type='user' + external_user_id，并通过 gateway_users.source='server-main' 反查同步副本。
• 多个组同时命中时，先按 gateway_user_group_memberships.priority，再按 gateway_user_groups.priority 合并策略。

7.9.8 gateway_tenant_invitations

本地注册邀请码。邀请码不是普通注册的必填项，但填写后必须可校验，并决定用户加入哪个租户和用户组。

字段	类型	约束	说明
id	uuid	PK	邀请 ID
tenant_id	uuid	FK	加入的 Gateway 租户
invite_code	text	unique, not null	注册邀请码
role	text	not null, default user	注册后角色，默认普通用户
user_group_id	uuid	FK nullable	注册后默认用户组
max_uses	int	nullable	最大使用次数
used_count	int	not null	已使用次数
expires_at	timestamptz	nullable	过期时间
status	text	not null	active、disabled
metadata	jsonb	not null	渠道、备注、审批信息

7.9.9 gateway_api_keys

独立模式本地 API Key 表。server-main 接入模式下，sk-* 仍调用主服务校验；Gateway 只记录执行快照和策略。

字段	类型	约束	说明
id	uuid	PK	API Key ID
gateway_tenant_id / gateway_user_id	uuid	FK	所属租户与用户
key_prefix	text	not null	展示和快速定位前缀
key_hash	text	unique, not null	secret hash，不保存明文
name	text	not null	用户命名
scopes	jsonb	not null	可调用能力范围
user_group_id	uuid	nullable	API Key 级策略组
rate_limit_policy / quota_policy	jsonb	not null	Key 级限流和额度覆盖
status	text	not null	active、disabled、revoked
expires_at / last_used_at	timestamptz	nullable	过期与最近使用

7.9.10 gateway_wallet_accounts

独立模式本地钱包账户。Phase 1 先支持资源余额闭环，后续可扩展人民币、美元或企业额度。

字段	类型	约束	说明
id	uuid	PK	钱包账户 ID
gateway_tenant_id / gateway_user_id	uuid	FK	所属租户与用户
currency	text	not null	resource、credit、cny、usd
balance	numeric	not null	可用余额
frozen_balance	numeric	not null	冻结余额
total_recharged	numeric	not null	累计充值
total_spent	numeric	not null	累计消费
status	text	not null	active、frozen、disabled

7.9.11 gateway_wallet_transactions

独立模式钱包流水。任务扣费、充值到账、退款、人工调整都必须写流水，并使用 idempotency_key 防重。

字段	类型	约束	说明
id	uuid	PK	流水 ID
account_id	uuid	FK	钱包账户
direction	text	not null	credit、debit、freeze、unfreeze
transaction_type	text	not null	recharge、billing、refund、adjustment
amount	numeric	not null	金额
balance_before / balance_after	numeric	not null	变动前后余额
idempotency_key	text	nullable	幂等 key
reference_type / reference_id	text	nullable	关联任务、订单或人工工单

7.9.12 gateway_recharge_orders

独立模式充值订单。第一阶段先闭合订单、折扣、入账和流水；支付渠道可以从手工确认开始，再接真实支付。

字段	类型	约束	说明
id	uuid	PK	充值订单 ID
gateway_tenant_id / gateway_user_id	uuid	FK	所属租户与用户
amount	numeric	not null	入账基础额度
bonus_amount	numeric	not null	用户组充值折扣或赠送额度
payable_amount	numeric	not null	实际应付
currency	text	not null	币种或资源类型
channel	text	not null	manual、wechat、alipay、stripe
status	text	not null	created、pending、paid、closed、failed
external_order_id	text	nullable	第三方支付订单
idempotency_key	text	nullable	创建订单幂等 key
paid_at	timestamptz	nullable	支付完成时间

7.9.13 integration_platforms

字段	类型	约束	说明
id	uuid	PK	平台实例 ID
provider	text	not null	平台类型，如 openai、runninghub、jimeng
platform_key	text	unique, not null	稳定平台 key，用于队列和客户端注册
name	text	not null	展示名称
base_url	text	nullable	平台 API 地址
auth_type	text	not null	bearer、api_key、basic、custom
credentials	jsonb	not null, default {}	加密后的凭证 JSON
config	jsonb	not null, default {}	超时、重试、限流、平台私有配置
visibility_scope	text	not null, default global	global、tenant、private
tenant_id	text	nullable	租户外部 ID 或兼容 claim
tenant_key	text	nullable	Gateway 租户 key
default_pricing_mode	text	not null, default inherit_discount	平台默认价格模式：inherit、inherit_discount、custom
default_discount_factor	numeric	not null, default 1	平台默认折扣系数，创建平台时可统一基于基准模型打折
retry_policy	jsonb	not null, default {}	平台级重试策略
rate_limit_policy	jsonb	not null, default {}	平台级限流策略
priority	int	not null, default 100	静态优先级，越小越优先
dynamic_priority	int	nullable	动态优先级覆盖
status	text	not null	enabled、disabled、exception
disabled_reason	text	nullable	禁用原因
cooldown_until	timestamptz	nullable	熔断/冷却到期时间
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间
deleted_at	timestamptz	nullable	软删除

索引：

• idx_integration_platforms_provider_status(provider, status)
• idx_integration_platforms_status_priority(status, priority, dynamic_priority)
• idx_integration_platforms_cooldown(cooldown_until)
• idx_integration_platforms_tenant_scope(visibility_scope, tenant_id, tenant_key, status)

7.9.14 platform_models

字段	类型	约束	说明
id	uuid	PK	模型配置 ID
platform_id	uuid	FK	所属平台
base_model_id	uuid	FK nullable	关联基准模型；为空时表示纯自定义模型
model_name	text	not null	请求使用的模型名
model_alias	text	nullable	对外展示/兼容别名
model_type	text	not null	chat、image、video、audio、embedding
display_name	text	not null	展示名称
capability_override	jsonb	not null, default {}	相对基准模型的能力覆盖
capabilities	jsonb	not null, default {}	解析后的有效能力，用于路由和前端展示
pricing_mode	text	not null, default inherit_discount	inherit、inherit_discount、custom
discount_factor	numeric	nullable	模型级折扣，空值时继承平台默认折扣
billing_config_override	jsonb	not null, default {}	自定义计费覆盖
billing_config	jsonb	not null, default {}	解析后的有效计费配置，用于 estimated billing 和真实 billings
permission_config	jsonb	not null, default {}	平台维度权限过滤配置
retry_policy	jsonb	not null, default {}	模型级重试策略
rate_limit_policy	jsonb	not null, default {}	模型级限流策略
enabled	boolean	not null, default true	是否启用
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引与约束：

• uniq_platform_model_type(platform_id, model_name, model_type)
• idx_platform_models_base(base_model_id)
• idx_platform_models_lookup(model_type, model_name, enabled)
• idx_platform_models_alias(model_alias)
• idx_platform_models_capabilities 使用 GIN(capabilities)

7.9.15 gateway_tasks

字段	类型	约束	说明
id	uuid	PK	Gateway 任务 ID
external_task_id	text	nullable	与 server-main / 前端兼容的外部任务 ID
kind	text	not null	chat.completions、images.generations 等
run_mode	text	not null	production、simulation
user_id	text	not null	请求 claim 中的用户 ID
gateway_user_id	uuid	nullable	Gateway 用户表 ID
user_source	text	not null, default gateway	gateway、server-main、sync
gateway_tenant_id	uuid	nullable	Gateway 租户 ID
tenant_id	text	nullable	外部租户 ID 或兼容 claim
tenant_key	text	nullable	Gateway 租户 key
api_key_id	text	nullable	OpenAPI Key ID
user_group_id	uuid	nullable	命中的用户组 ID
user_group_key	text	nullable	命中的用户组 key
user_group_policy_snapshot	jsonb	not null, default {}	用户组策略快照
model	text	not null	请求模型
model_type	text	nullable	模型类型
request	jsonb	not null	原始请求快照
normalized_request	jsonb	not null, default {}	参数处理后的请求
status	text	not null	queued、leased、running、polling、succeeded、failed_retryable、failed_final、cancelled
queue_key	text	not null	队列与限流 key
priority	int	not null, default 100	任务优先级
idempotency_key	text	nullable	幂等 key
remote_task_id	text	nullable	供应商任务 ID
remote_task_payload	jsonb	nullable	供应商任务载荷
simulation_profile	jsonb	nullable	模拟配置
simulation_seed	text	nullable	模拟种子
locked_by	text	nullable	worker ID
locked_at	timestamptz	nullable	租约时间
heartbeat_at	timestamptz	nullable	worker 心跳
next_run_at	timestamptz	not null	下次可运行时间
attempt_count	int	not null, default 0	已尝试次数
max_attempts	int	not null, default 1	最大尝试次数
result	jsonb	nullable	归一化结果
billings	jsonb	nullable	计费结果
error_code	text	nullable	错误码
error_message	text	nullable	错误信息
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间
finished_at	timestamptz	nullable	完成时间

索引：

• idx_gateway_tasks_queue(status, next_run_at, priority, created_at)
• idx_gateway_tasks_lease(status, heartbeat_at)
• idx_gateway_tasks_user_created(user_id, created_at desc)
• idx_gateway_tasks_external(external_task_id)
• uniq_gateway_tasks_idempotency(user_id, idempotency_key) where idempotency_key is not null

7.9.16 gateway_task_attempts

字段	类型	约束	说明
id	uuid	PK	attempt ID
task_id	uuid	FK	所属任务
attempt_no	int	not null	第几次尝试
platform_id	uuid	nullable	尝试平台
platform_model_id	uuid	nullable	尝试模型配置
client_id	text	nullable	客户端实例 ID
queue_key	text	not null	限流 key
status	text	not null	submitted、polling、succeeded、failed、skipped
retryable	boolean	not null, default false	是否可重试
simulated	boolean	not null, default false	是否模拟
remote_task_id	text	nullable	供应商任务 ID
request_snapshot	jsonb	not null, default {}	本次请求快照
response_snapshot	jsonb	nullable	本次响应快照
error_code	text	nullable	错误码
error_message	text	nullable	错误信息
started_at	timestamptz	not null	开始时间
finished_at	timestamptz	nullable	结束时间

索引：

• uniq_gateway_attempt_no(task_id, attempt_no)
• idx_gateway_attempts_task(task_id)
• idx_gateway_attempts_client(client_id, started_at desc)

7.9.17 gateway_task_events

字段	类型	约束	说明
id	uuid	PK	事件 ID
task_id	uuid	FK	所属任务
seq	bigint	not null	单任务递增序号
event_type	text	not null	queue_status、progress、partial_result、completed、failed
status	text	nullable	任务状态
phase	text	nullable	routing、queued、submit、polling、upload
progress	numeric	nullable	0 到 1
message	text	nullable	展示消息
payload	jsonb	not null, default {}	事件载荷
simulated	boolean	not null, default false	是否模拟
created_at	timestamptz	not null	创建时间

索引：

• uniq_gateway_events_seq(task_id, seq)
• idx_gateway_events_task_created(task_id, created_at)

7.9.18 gateway_task_callback_outbox

字段	类型	约束	说明
id	uuid	PK	回调 outbox ID
task_id	uuid	FK	任务 ID
event_id	uuid	FK nullable	对应 gateway_task_events.id
seq	bigint	not null	单任务事件序号
callback_url	text	not null	投递地址快照，来自 TASK_PROGRESS_CALLBACK_URL
payload	jsonb	not null	回调载荷
status	text	not null	pending、delivering、delivered、failed、skipped
attempts	int	not null, default 0	已投递次数
next_attempt_at	timestamptz	not null	下次投递时间
last_error	text	nullable	最近错误
delivered_at	timestamptz	nullable	投递成功时间
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• uniq_task_callback_seq(task_id, seq, callback_url)
• idx_task_callback_outbox_pending(status, next_attempt_at)
• idx_task_callback_outbox_task(task_id, seq)

7.9.19 runtime_client_states

字段	类型	约束	说明
client_id	text	PK	客户端实例 ID
platform_id	uuid	nullable	所属平台
provider	text	not null	provider
method_name	text	not null	方法名
queue_key	text	not null	队列 key
running_count	int	not null, default 0	当前运行数
waiting_count	int	not null, default 0	当前等待数
limiter_ratio	numeric	not null, default 0	负载比
cooldown_until	timestamptz	nullable	冷却截止
last_assigned_at	timestamptz	nullable	上次分配时间
last_error	text	nullable	最近错误
updated_at	timestamptz	not null	更新时间

索引：

• idx_runtime_client_queue(queue_key, cooldown_until)
• idx_runtime_client_platform(platform_id)

7.9.20 gateway_upload_assets

字段	类型	约束	说明
id	uuid	PK	资产 ID
task_id	uuid	FK nullable	关联任务
source	text	not null	固定为 server-main-open-upload 或 remote-url / simulation
server_main_file_id	text	nullable	主服务返回的 file id
url	text	not null	主服务返回 URL
object_key	text	nullable	主服务返回对象 key
content_type	text	nullable	MIME
size	bigint	nullable	文件大小
checksum	text	nullable	校验和
metadata	jsonb	not null, default {}	上传响应与业务元数据
created_at	timestamptz	not null	创建时间

索引：

• idx_gateway_upload_task(task_id)
• idx_gateway_upload_file(server_main_file_id)

7.9.21 gateway_retry_policies

字段	类型	约束	说明
id	uuid	PK	策略 ID
scope_type	text	not null	global、provider、platform、model、method
scope_key	text	not null	作用域 key
enabled	boolean	not null	是否启用重试
policy	jsonb	not null	重试策略 JSON
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

约束：

• uniq_retry_policy_scope(scope_type, scope_key)

7.9.22 gateway_rate_limit_policies

字段	类型	约束	说明
id	uuid	PK	策略 ID
scope_type	text	not null	global、provider、platform、client、base_model、platform_model、method、tenant、user_group、user、api_key
scope_key	text	not null	作用域 key
policy	jsonb	not null	TPM、RPM、并发、队列长度、冷却策略
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

约束：

• uniq_rate_limit_policy_scope(scope_type, scope_key)

示例：

{
  "rules": [
    { "metric": "tpm_total", "limit": 90000, "windowSeconds": 60, "consume": "reserve_then_reconcile" },
    { "metric": "rpm", "limit": 600, "windowSeconds": 60, "consume": "fixed_window" },
    { "metric": "concurrent", "limit": 20, "leaseTtlSeconds": 900 },
    { "metric": "queue_size", "limit": 1000 }
  ]
}

7.9.23 gateway_rate_limit_counters

保存一分钟窗口内的 TPM/RPM 使用量。Redis 可做加速，但 PG counter 是重启恢复和审计的事实源。

字段	类型	约束	说明
scope_type	text	not null	限流作用域
scope_key	text	not null	作用域 key
metric	text	not null	tpm_total、tpm_input、tpm_output、rpm
window_start	timestamptz	not null	分钟窗口开始时间
limit_value	numeric	not null	当前窗口限制
used_value	numeric	not null, default 0	已确认消耗
reserved_value	numeric	not null, default 0	已预占但待回填消耗
reset_at	timestamptz	not null	窗口结束时间
updated_at	timestamptz	not null	更新时间

约束：

• pk_rate_limit_counter(scope_type, scope_key, metric, window_start)

7.9.24 gateway_concurrency_leases

保存并发请求租约，服务异常重启后可释放过期并发。

字段	类型	约束	说明
id	uuid	PK	并发租约 ID
task_id	uuid	FK	任务 ID
attempt_id	uuid	FK nullable	attempt ID
scope_type	text	not null	限流作用域
scope_key	text	not null	作用域 key
lease_value	numeric	not null, default 1	占用并发数
acquired_at	timestamptz	not null	获取时间
expires_at	timestamptz	not null	过期时间
released_at	timestamptz	nullable	释放时间

索引：

• idx_concurrency_leases_active(scope_type, scope_key, released_at, expires_at)
• idx_concurrency_leases_task(task_id)

8. 模型路由、限流与失败切换

迁移时不要做简单的 first-match。路由器需要复用现有语义：

1. 先按模型名、模型类型、平台启用状态筛候选。
2. 保留平台维度权限过滤，同名模型不能跨平台混用。
3. 按平台优先级排序。
4. 结合并发是否已满、limiter ratio、等待队列、lastAssignedAt 做负载均衡。
5. 对 app-style provider，例如 RunningHub 模板类能力，使用 provider + methodName 的队列 key。

一期脚手架只预留接口，迁移实现时把 IntegrationModelFactory.assignClientsByModelName 与 assignClientsByProviderMethod 的行为写成 Go 版单元测试再实现。

8.1 限流维度

限流策略需要支持以下维度组合：

• 全局：global
• Provider 级：provider_key
• 平台级：platform_id
• 客户端级：client_id
• 基准模型级：base_model_id / canonical_model_key
• 平台模型级：platform_model_id / model_name / model_type
• 方法级：method_name，例如 runAIApp$
• 租户/用户级：gateway_tenant_id / tenant_id / tenant_key / user_id
• 用户组级：user_group_id / user_group_key
• OpenAPI Key 级：api_key_id

同一请求可能命中多个策略，默认以最严格策略为准；如后续需要不同优先级，可在 policy 中增加 mergeStrategy。

8.1.1 一分钟窗口核心指标

限流必须把 TPM、RPM、并发作为一等指标，而不是只看 running count：

指标	含义	适用能力	执行方式
tpm_total	一分钟内输入 + 输出 token 总数	Chat、Responses、Embedding、可 token 化文本任务	提交前按 prompt / max_tokens 预估并预占，完成后用实际 token 回填
tpm_input	一分钟内输入 token 数	Chat、Responses、Embedding	提交前按 tokenizer 或近似估算预占
tpm_output	一分钟内输出 token 数	Chat、Responses	stream 场景可按 chunk 增量累计，完成后 reconcile
rpm	一分钟内请求数	所有同步/异步模型提交	任务 attempt 提交前扣减；失败切换的新 attempt 也算一次 provider 请求
concurrent	同时运行或轮询中的请求数	所有 provider client	通过 gateway_concurrency_leases 获取租约，完成、失败、取消或过期释放
queue_size	等待队列长度	所有队列	超过后按策略返回兼容错误或降级到 simulation / fallback

TPM 的预占策略：

• 文本任务：优先使用模型 tokenizer；没有 tokenizer 时用字符数估算，并把估算方式写入 event payload。
• Chat stream：提交前按 input_tokens + max_tokens 预占，stream 中可累计输出 token，完成后用 usage 精确回填。
• 未提供 max_tokens 的请求：使用模型默认输出上限或策略中的 defaultOutputReserveTokens。
• 失败且未提交到供应商：释放预占 token；已提交但失败的 attempt 按供应商是否计费决定保留或部分释放。
• 生图/生视频通常不计 TPM，但如果 provider 对多模态 token 有限制，可在 capabilities.tokenPolicy 中启用对应估算器。

RPM 和并发的边界：

• RPM 以“向 provider 发起一次 submit / sync request”为计数点；排队但未提交不消耗 RPM。
• 失败切换到下一个客户端时，新客户端 attempt 会重新消耗该客户端、平台、provider 维度的 RPM。
• 并发租约从 submit 前获取，到同步响应完成、异步任务进入可安全释放阶段或任务终态时释放；长轮询 provider 可拆成 submit_concurrent 与 poll_concurrent 两类 scope。
• 服务重启后扫描过期 lease，结合 gateway_tasks.heartbeat_at 判断释放或续租，避免并发永久泄漏。

除核心指标外，还保留每日/月度配额、错误冷却、余额不足拦截等策略，但这些属于调度前置校验，不替代 TPM/RPM/并发。

8.2 候选客户端选择

候选客户端排序规则必须可测试、可复现：

1. 过滤禁用平台、禁用模型、不可用凭证、权限不满足的客户端。
2. 过滤与请求能力不匹配的客户端，例如不支持视频参考、音频参考、多图输入时不能作为候选。
3. 根据指定平台 / 指定客户端优先收窄候选。
4. 按 priority、是否满载、limiter_ratio、等待队列长度、last_assigned_at、轻微 jitter 排序。
5. 选中客户端后在同一事务内写入 last_assigned_at 和任务锁，避免并发请求都抢到同一个客户端。

8.3 失败切换与重试策略

一个模型请求进来，如果多个客户端满足要求，必须具备“上一个客户端失败，下一个客户端重试”的能力，且可配置是否允许：

{
  "retry": {
    "enabled": true,
    "failoverClients": true,
    "maxAttempts": 3,
    "maxSameClientAttempts": 1,
    "backoff": { "type": "exponential", "baseMs": 500, "maxMs": 5000 },
    "retryableStatusCodes": [408, 409, 429, 500, 502, 503, 504],
    "retryableErrorCodes": ["timeout", "rate_limit", "temporary_unavailable"],
    "nonRetryableErrorCodes": ["invalid_request", "insufficient_quota", "content_policy"],
    "retryOnSubmitUnknown": false
  }
}

策略可挂在全局、provider、platform、model、method 四层，优先级为：请求显式配置 > 模型配置 > 平台配置 > provider 默认 > 全局默认。

重试要求：

• 每次尝试都写入 gateway_task_attempts，包括跳过原因和失败分类。
• 已明确提交成功但轮询失败的任务，优先继续轮询原 remote_task_id，不能盲目重复提交造成供应商侧重复任务。
• 提交状态未知时，根据 retryOnSubmitUnknown 决定是否切换客户端；默认保守处理，标记为 unknown 并进入人工/补偿检查。
• 非重试错误直接终止任务，不再切换客户端。
• 重试产生的新客户端必须仍满足同一请求的能力、权限和计费要求。

9. 基准模型库与定价体系

定价不直接散落在平台模型里。Gateway 先有一个基准模型库，基准模型库存所有 provider、模型、能力、默认限流模板和基准价格；平台创建和平台模型配置都基于这个库继承或覆盖。

9.1 基准模型库内容

每个基准模型至少包含：

• provider：如 openai、runninghub、jimeng。
• canonical model key：Gateway 内部稳定模型 key。
• provider model name：供应商真实请求模型名。
• model type：chat、image、video、audio、embedding、music、digital_human、model_3d。
• capabilities：上下文窗口、stream、多模态输入、参考图、参考视频、参考音频、支持尺寸、质量、时长、有无音频、最大 batch 等。
• base billing config：文本、图像、视频、音频等不同能力的基准价格。
• default rate limit policy：provider 或模型默认 TPM/RPM/并发模板。

9.2 平台价格继承与覆盖

创建平台时有三种方式：

模式	配置	说明
inherit	不填价格	完全 follow 基准模型价格和能力
inherit_discount	default_discount_factor 或模型级 discount_factor	有效价 = 基准价 x 折扣系数；能力默认 follow 基准模型，可局部覆盖
custom	billing_config_override / capability_override	平台模型完全自定义价格或能力，未覆盖字段仍从基准模型补齐

有效配置解析顺序：

1. 平台模型 capability_override / billing_config_override。
2. 平台模型 discount_factor。
3. 平台 default_discount_factor。
4. 用户组 billing_discount_policy，用于用户组级模型调用折扣。
5. 基准模型 capabilities / base_billing_config。

如果没有配置平台模型价格，必须 follow 基准模型；不能出现空价格导致预估扣费为 0 的隐式行为。

接入 server-main 时，充值折扣不在 Gateway 内直接变更余额。Gateway 只保存 recharge_discount_policy 并与主服务同步；充值订单、资源包发放、余额流水仍由 server-main 作为事实源执行。独立模式下，充值、余额、订单和钱包流水由 Gateway 本地账务模块闭环。

9.3 各能力计价模型

文本类：

• 按 1k_tokens 计价。
• 输入和输出分开计价：text_input、text_output。
• 如果模型只配置总价，可 fallback 到 text_total，但 resolver 对外仍展开成输入/输出明细。
• 预估时用输入 token + 输出 token 预估值；最终结算用 provider usage 或 Gateway tokenizer 回填。

图像类：

• 基础单位为 image。
• 动态权重至少支持：分辨率、质量、张数、编辑/生成模式。
• 分辨率示例：512x512、1024x1024、1K、2K、4K、8K。
• 质量示例：standard、hd、high、ultra。
• 公式示例：count * basePrice * resolutionWeight * qualityWeight * modeWeight。

视频类：

• 基础单位建议为 5s 或 second，与原 provider 配置保持可映射。
• 动态权重至少支持：时长、分辨率、是否包含音频、是否使用参考视频、是否指定声音/音色、生成数量。
• 分辨率示例：480p、720p、1080p、2160p。
• 公式示例：count * ceil(durationSeconds / unitSeconds) * basePrice * resolutionWeight * audioWeight * referenceWeight。

音频、音乐、数字人、3D 模型：

• TTS / audio 可按 character_1k 或秒计费。
• 音乐可按首数、时长、模型权重计费。
• 数字人可按时长、分辨率、音频驱动方式计费。
• 3D / model 类按任务数、模型复杂度或 provider 返回的计费单位映射。

9.4 estimated billing 一致性

/integration-platform/models/estimatedBilling、/integration-platform/models/estimatedBilling/:workflowId 和真实任务结算必须使用同一个 resolver：

request -> normalize params -> resolve effective platform model
-> resolve effective capabilities -> resolve effective pricing
-> estimate billing -> route / submit -> final billing reconcile

要求：

• 预估扣费不能只按模型名查第一条，必须使用真实候选平台过滤、权限过滤和优先级排序后的有效平台模型。
• 同名模型跨平台时，平台权限和平台模型价格都不能串。
• 测试模式使用同样的预估逻辑，但 billings 标记 simulated=true。
• 基准模型价格变更时，平台模型可选择自动 follow 最新版本或 pin 到指定 pricing_version，避免历史价格被静默改变。

10. Base Client 与 Provider 实现架构

Gateway 需要保留类似原 BaseModelClient 的整体架构：公共基类定义通用生命周期，不同 provider/client 只实现平台差异。这样才能把参数预处理、限流、日志、进度、重试、计费和结果归一放在同一层处理。

10.1 Client 接口

Go 侧建议抽象为：

type ModelClient interface {
  Provider() string
  MethodName() string
  BuildParams(ctx context.Context, task TaskContext) (VendorRequest, error)
  SubmitTask(ctx context.Context, request VendorRequest) (RemoteTask, error)
  PollResult(ctx context.Context, remote RemoteTask) (PollResult, error)
  NormalizeResult(ctx context.Context, result PollResult) (NormalizedResult, error)
  EstimateBilling(ctx context.Context, task TaskContext) ([]BillingItem, error)
  Cancel(ctx context.Context, remote RemoteTask) error
}

10.2 Base Client 公共职责

BaseClient / BaseModelClient 负责：

• 调用参数处理链：尺寸、画幅、时长、多模态内容过滤、默认值填充。
• 校验模型能力：图片参考、视频参考、音频参考、文件输入、stream 支持等。
• 发出进度事件：构建参数、排队、提交、轮询、下载、上传、完成。
• 执行通用 timeout、backoff、错误分类、重试和 failover 策略。
• 统一记录 gateway_task_attempts、gateway_task_events、运行指标。
• 统一提取 billings 与 result，交给 outbox 做结算事件。
• 统一处理文件资产：已上传文件引用、远程 URL 转存、provider 临时 URL 拉取后调用 server-main /v1/files/upload。

10.3 Provider Client 实现职责

具体 client 只负责供应商协议：

• OpenAI-compatible：同步/stream chat、responses、image generation。
• Gemini：Chat、多模态图片输入、生图、图像编辑优先进入第一阶段迁移。
• RunningHub：模板类 app 提交、轮询、结果提取，队列 key 使用 ${provider}-${methodName}。
• Jimeng / Vidu / Kling / Hunyuan Video：视频任务提交与轮询。
• Suno / Speech / Digital Human：各自的提交和结果归一。
• SimulationClient：用于测试模式和 dry-run，完整模拟提交、轮询、进度、失败、结果，不参与真实生产候选。
• MockTest：用于 provider contract 回归和 loopback，不能和生产路由混在同一个职责里；应由独立 registry / loopback service 管理。

每个 provider 至少需要：

• contract test：固定输入输出 DTO。
• retry classification test：哪些错误可重试、哪些不可重试。
• progress event snapshot：确保前端进度面板兼容。
• billing snapshot：确保预估扣费和最终 billings 语义一致。

11. 队列持久化、恢复与限流执行

11.1 持久化队列原则

队列必须以 PostgreSQL 为事实源，Redis / 内存只作为加速和通知层。服务异常重启后，任务状态必须可从 PG 恢复。

任务生命周期：

created -> queued -> leased -> running -> polling -> succeeded
                                  |           |
                                  |           -> failed_retryable -> queued
                                  -> failed_final / cancelled

核心规则：

• 入队时写 gateway_tasks，状态为 queued，并写初始 gateway_task_events。
• worker 获取任务时使用事务、FOR UPDATE SKIP LOCKED 或 advisory lock，写入 locked_by、locked_at、heartbeat_at。
• worker 运行中定期刷新 heartbeat_at。
• 服务启动时扫描 running/polling/leased 且 heartbeat 超时的任务。
• 有 remote_task_id 的任务优先进入 reconciliation poller，继续取回供应商结果。
• 没有 remote_task_id 的任务按 retry 策略回到 queued 或进入 failed_final。
• 结算 outbox 独立重试，任务成功不等于结算成功。

11.2 恢复策略

重启前状态	恢复动作
queued	保持队列，等待 worker 重新租约
leased 但无 heartbeat	释放锁，回到 queued
running 且无 remote_task_id	视为提交前失败，按 retry 策略重试
running/polling 且有 remote_task_id	进入 poller 继续取回结果
succeeded 但 settlement pending	outbox 继续补偿
failed_retryable 且未超最大次数	按 next_run_at 回队列
failed_final/cancelled	不自动恢复

11.3 限流执行

worker 租约任务前必须先拿到限流令牌：

• TPM 令牌：按 gateway_rate_limit_counters 的一分钟窗口预占 token，完成后 reconcile 实际 token。
• RPM 令牌：提交 provider 前扣减一分钟窗口请求数，失败切换的新 attempt 重新评估。
• 并发令牌：按 queue_key / client_id / method_name / platform_model_id 维度写 gateway_concurrency_leases。
• 排队令牌：超过 max_waiting 后直接返回兼容错误。
• 冷却令牌：客户端错误达到阈值后设置 cooldown_until。

如果 worker 拿不到令牌，任务保持 queued 并更新 next_run_at，不能占用 worker 长时间空等。

12. 进度流与 RxJS-like 中间结果

原系统里很多 provider 使用 RxJS Observable 在中间过程返回进度。Go 侧需要提供等价语义：

type ProgressPublisher interface {
  Publish(ctx context.Context, event ProgressEvent) error
  Subscribe(ctx context.Context, taskID string, afterSeq int64) (<-chan ProgressEvent, error)
}

12.1 ProgressEvent 结构

{
  "taskId": "uuid",
  "seq": 12,
  "event": "progress",
  "status": "running",
  "phase": "polling",
  "progress": 0.42,
  "message": "Generating video frames",
  "payload": {},
  "createdAt": "2026-05-09T12:00:00Z"
}

12.2 推送通道

• 业务实时进度主通道：Gateway 按 TASK_PROGRESS_CALLBACK_URL 回调 server-main，由 server-main 复用原 WebSocket 网关推送给业务前端。
• 控制台 SSE：GET /api/v1/tasks/:taskId/events，支持 Last-Event-ID 回放，用于 Gateway 控制台、调试和故障诊断。
• Gateway WebSocket：用于网关控制台高频队列监控、运行态监控；不替代业务前端现有 WebSocket 通道。
• OpenAI stream：/chat/completions、/v1/chat/completions、/responses 需要保持原 stream chunk 格式。

任务进度回调示例：

POST ${TASK_PROGRESS_CALLBACK_URL}
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
Content-Type: application/json
Idempotency-Key: ${taskId}:${seq}
X-EasyAI-Event-Type: task.progress

{
  "eventId": "uuid",
  "taskId": "uuid",
  "externalTaskId": "server-main-task-id",
  "userId": "user-id",
  "tenantId": "tenant-id",
  "apiKeyId": "optional",
  "kind": "images.generations",
  "model": "gpt-image-1",
  "seq": 12,
  "event": "progress",
  "status": "running",
  "phase": "polling",
  "progress": 0.42,
  "message": "Generating video frames",
  "payload": {},
  "createdAt": "2026-05-09T12:00:00Z"
}

server-main 收到后不重新执行任务，只做三件事：

1. 按 Idempotency-Key 或 taskId + seq 幂等落库/去重。
2. 根据 externalTaskId、taskId、userId、tenantId 找到原业务会话或任务频道。
3. 通过原 WebSocket 网关推送给业务前端，保持前端订阅协议不大改。

12.3 进度持久化要求

• 所有对用户可见的状态变化都必须先写 gateway_task_events，再写 gateway_task_callback_outbox，最后广播/投递。
• 客户端断线后能从 seq 或 Last-Event-ID 补齐。
• 任务恢复后必须先重放最近状态，再继续发布新进度。
• 完成态事件必须包含足够的结果摘要，前端无需额外轮询才能更新卡片状态。
• 回调投递失败不能阻塞任务执行，但必须进入 outbox 重试，并在控制台显示滞留状态。
• 同一任务的回调按 seq 保序投递；允许不同任务并发投递。

13. 测试模式与全链路模拟

AI Gateway 需要内置测试模式，目标是在不触达真实供应商、不真实扣费、不调用主服务生产上传接口的前提下，把请求完整跑过路由、候选客户端选择、队列、限流、失败切换、进度流、结果归一、任务恢复等核心链路。

13.1 启用方式

支持三种启用粒度：

粒度	配置	说明
全局	`AI_GATEWAY_RUN_MODE=production	simulation`
请求级	X-EasyAI-Test-Mode: simulation 或 body test_mode=true	仅对单次请求模拟，默认只允许 power/manager 或内部服务使用
平台/模型级	platform.config.testMode、model.config.testMode	指定平台、模型在测试环境永远走模拟

安全要求：

• 生产环境默认禁止普通用户请求级 test mode；需要显式开启 ALLOW_REQUEST_TEST_MODE=true。
• OpenAPI sk-* 默认不能打开 test mode，除非 API Key 或租户配置允许。
• 进入 simulation 后必须在 task、attempt、event、response 中标记 simulated=true，避免和真实任务混淆。

13.2 模拟链路

测试模式仍走完整执行链：

HTTP route -> auth -> route compatibility adapter -> model router
-> persistent queue -> rate limiter -> SimulationClient
-> progress events -> normalized result -> dry-run billing -> task completed

不会执行的动作：

• 不调用真实 provider 的 submit / poll / cancel API。
• 不生成真实供应商订单或任务。
• 不向 server-main 发真实扣费结算事件。
• 不调用 server-main 的生产文件上传，除非显式使用测试环境上传接口。
• 不消耗真实平台并发额度。

仍会执行的动作：

• 真实鉴权。
• 真实路由和候选客户端排序。
• 真实队列持久化、锁、heartbeat、恢复。
• 真实限流令牌计算。
• 真实进度事件持久化和推送。
• 真实任务记录、attempt 记录、dry-run outbox 记录。

13.3 Simulation Profile

SimulationClient 根据 simulation_profile 生成确定性行为：

{
  "simulation_profile": {
    "latencyMs": [300, 800, 1200],
    "progressSteps": [0.1, 0.35, 0.7, 1],
    "resultKind": "image",
    "resultCount": 2,
    "failures": [
      { "attempt": 1, "errorCode": "timeout", "retryable": true },
      { "attempt": 2, "errorCode": "rate_limit", "retryable": true }
    ],
    "seed": "task-id-or-custom-seed"
  }
}

用途：

• 模拟成功：返回固定格式图片、视频、音频、文本或 embedding 结果。
• 模拟失败：按 attempt 注入可重试 / 不可重试错误。
• 模拟慢任务：验证进度、断线重连、任务恢复。
• 模拟限流：验证排队、等待上限、cooldown。
• 模拟未知提交态：验证 retryOnSubmitUnknown 和人工补偿路径。

13.4 失败切换测试

测试模式必须能验证“上一个客户端失败，下一个客户端重试”：

1. router 仍按真实规则选出多个候选客户端。
2. SimulationClient 为第一个候选返回 retryable error。
3. runtime 写入 failed attempt。
4. retry policy 判断可切换。
5. router 排除已失败且不可复用的 client，选下一个候选。
6. 第二个候选成功后，任务以 succeeded 完成，并记录完整 attempts。

禁用重试时，同样的失败应直接进入 failed_final，不能切换客户端。

13.5 Dry-run 计费与结算

• EstimateBilling 仍使用真实计费配置计算，结果标记 simulated=true。
• settlement_outbox 可写入 dry_run 事件，但默认状态为 skipped，不触发主服务扣费。
• 若需要联调主服务结算接口，只能调用 server-main 的 dry-run settlement endpoint，不能复用真实扣费 endpoint。

13.6 模拟结果资产

测试模式下的文件结果有三种来源：

• 内置静态占位 URL，例如 /static/simulation/image.png。
• data URL / inline metadata，仅用于接口契约测试。
• 测试文件上传接口：只有显式启用 AI_GATEWAY_SIMULATION_UPLOAD=true 时才允许调用 server-main 测试环境上传接口；默认使用内置静态占位资产。

结果必须带：

{
  "simulated": true,
  "assetSource": "simulation",
  "provider": "simulation"
}

13.7 观测与审计

控制台需要能筛选 run_mode=simulation 的任务，展示：

• 使用的 simulation profile。
• 每次 attempt 的模拟错误和重试决策。
• 生成的 progress events。
• dry-run billing。
• 是否触发了恢复流程。

14. server-main 对接方式

14.1 短期：server-main 仍保留入口

server-main 对外接口不变：

• /chat/completions
• /images/generations
• /video/generations
• /v1/chat/completions
• /v1/images/generations
• /v1/video/generations

内部 OpenaiService 变成薄门面：

sequenceDiagram
  participant FE as Frontend
  participant MAIN as server-main
  participant GW as AI Gateway
  participant V as Vendor

  FE->>MAIN: POST /images/generations
  MAIN->>MAIN: create history / task id
  MAIN->>GW: POST /api/v1/images/generations
  GW->>V: submit task
  GW-->>MAIN: POST task progress callback
  MAIN-->>FE: WebSocket task progress
  V-->>GW: result
  GW-->>MAIN: POST task completed callback
  MAIN-->>FE: WebSocket task completed
  GW-->>MAIN: settlement event with billings
  MAIN->>MAIN: billing + history update
  GW-->>MAIN: task result
  MAIN-->>FE: response

14.2 实时任务进度回调

AI Gateway 不直接替换原业务前端的 WebSocket 订阅方式。Gateway 在配置中指定任务进度回调地址：

TASK_PROGRESS_CALLBACK_URL=http://easyai-server-main:3000/internal/platform/task-progress-callbacks
TASK_PROGRESS_CALLBACK_ENABLED=true
TASK_PROGRESS_CALLBACK_TIMEOUT_MS=5000
TASK_PROGRESS_CALLBACK_MAX_ATTEMPTS=10

运行时要求：

• BaseClient / runtime 每产生一个进度事件，先写 gateway_task_events，再写 gateway_task_callback_outbox。
• callback worker 使用 SERVER_MAIN_INTERNAL_TOKEN 调用 TASK_PROGRESS_CALLBACK_URL。
• server-main 收到事件后进入主服务内部推送流程，再由原 WebSocket 网关推送给业务前端。
• Gateway 控制台仍可通过 SSE 读 gateway_task_events，用于运维诊断，不影响业务前端推送通道。
• 如果 server-main 短暂不可用，Gateway 按 outbox 重试；超过最大次数后标记 failed，控制台可手动 replay。

14.3 中期：前端直接打 Gateway

前端配置 VITE_GATEWAY_API_BASE_URL，生成类请求直接走网关路由到 AI Gateway。server-main 只处理登录、刷新、余额、历史、开放文件上传、扣费。

即使生成请求改为前端直连 Gateway，业务实时进度默认仍回调 server-main 内部任务进度接口，除非某个新业务明确迁移到 Gateway 自身的事件通道。

14.4 结算事件

Gateway 任务成功后向 server-main 发送结算事件：

{
  "eventId": "uuid",
  "taskId": "uuid",
  "userId": "user-id",
  "tenantId": "tenant-id",
  "apiKeyId": "optional",
  "kind": "images.generations",
  "model": "gpt-image-1",
  "billings": [
    {
      "resourceType": "image",
      "amount": 1,
      "unit": "item",
      "cost": 100
    }
  ],
  "resultRef": {
    "url": "https://..."
  }
}

要求：

• server-main 以 eventId / taskId 做幂等。
• Gateway 保留 outbox 或重试表，避免结算事件丢失。
• 扣费失败时任务结果仍可先保存，但前端展示需要明确异常状态。

15. 文件上传

文件上传策略收敛为：AI Gateway 不维护自己的 OSS/COS/S3 配置，不做预签名，不直接写对象存储；所有需要上传或转存的文件，统一调用 server-main 已开放的文件上传接口。这样可以复用主服务现有 OSS 配置、权限、文件记录、MIME 推断和后续审计。

15.1 ServerMainUploadClient 抽象

type ServerMainUploadClient interface {
  UploadMultipart(ctx context.Context, input UploadMultipartInput) (UploadedAsset, error)
  UploadFromURL(ctx context.Context, input UploadFromURLInput) (UploadedAsset, error)
  ResolveAsset(ctx context.Context, ref AssetRef) (ResolvedAsset, error)
}

15.2 调用接口

默认调用 server-main 的开放上传接口：

Method	Path	说明
POST	/v1/files/upload	OpenAPI 兼容 multipart 文件上传

调用要求：

• 用户请求：透传用户 JWT 或 OpenAPI sk-*，保持与原主服务上传权限一致。
• Gateway 内部上传：使用服务令牌加原始用户上下文头，例如 X-EasyAI-User-Id、X-EasyAI-Tenant-Id、X-EasyAI-Task-Id，具体以 server-main 内部约定为准。
• 上传返回值以主服务响应为准，Gateway 只做字段归一并写入 gateway_upload_assets。
• 测试模式默认不调用上传接口，除非显式启用测试上传。

15.3 上传场景

场景	处理方式
前端已经通过主服务上传	请求中携带主服务返回的 URL / file id，Gateway 只校验和记录
Gateway 需要转存远程 URL	Gateway 下载远程内容，作为 multipart 调 /v1/files/upload 上传到主服务
Provider 返回临时 URL	Gateway 拉取结果，再调 /v1/files/upload 转存，最终结果使用主服务 URL
OpenAPI multipart 上传	继续由 server-main 的 /v1/files/upload 承接；Gateway 不新增并行上传入口
base64 小文件	Gateway 解码为 multipart，再调用 /v1/files/upload

15.4 安全与可靠性

• 限制最大文件大小、content-type、扩展名。
• 远程 URL 下载必须禁止内网地址、metadata 地址、超长重定向链。
• 上传到 server-main 时带 Idempotency-Key，避免重启或 retry 造成重复文件记录。
• gateway_upload_assets 记录主服务返回的 file id、URL、object key、checksum、响应快照。
• 如果上传失败，任务按 provider retry 策略判断是否可重试；上传失败本身也要写 attempt/event。
• Gateway 不保存长期文件密钥，不暴露 OSS 配置页面。

16. 前端页面设计

前端使用 React + TypeScript + TSX + shadcn-ui，定位不是单纯后台控制台，而是“AI 能力门户 + 用户工作台 + 管理工作台 + API 文档中心”。页面根据 IDENTITY_MODE 切换身份来源：独立模式走 Gateway 本地登录 / API Key；接入 server-main 时走主服务 JWT / OpenAPI Key 授权。普通用户只能进入模型、用户工作台和 API 文档，管理员额外进入管理工作台。

16.1 一级导航

一级模块	路由	默认权限	定位
登录	/login、/register	public	Gateway 本地账号登录注册、外部 token 入口
首页	/	public/basic	服务入口、模型能力概览、用量摘要、最近任务、快捷入口
模型	/models	public/basic	可用模型浏览、能力筛选、价格/限流展示、模型调用入口
用户工作台	/workspace	basic	个人中心、余额充值、API Key、任务记录
管理工作台	/admin	power/manager	用户与用户组、全局模型配置、平台管理、队列限流、结算与系统设置
API 文档	/docs	public/basic	开放接口文档、鉴权说明、示例代码、在线调用测试

16.2 登录与注册

首期登录页先提供普通账号能力和可选邀请码注册，后续再接 SSO、验证码、MFA：

页面	路由	权限	说明
登录	/login	public	用户名/邮箱 + 密码登录 Gateway 本地账号
注册	/register	public	创建 Gateway 本地账号；可填写租户 key / 租户名称 / 邀请码，邀请码不是必填
外部 Token 入口	/login?mode=external	public	粘贴 server-main access token，用于接入模式和开发调试

登录成功后统一获得 Gateway 可校验的 access token；本地账号 token 中包含 source=gateway、gatewayUserId、gatewayTenantId、tenantKey。外部 token 保留 source=server-main 或主服务返回的 claim。

16.3 首页

首页不是营销页，首屏应直接提供可操作入口和运行状态。

页面	路由	权限	说明
首页总览	/	public/basic	推荐模型、最近任务、余额摘要、API Key 状态、服务公告
能力概览	/capabilities	public/basic	Chat、生图、生视频、音频、Embedding 等能力入口
服务状态	/status	public/basic	网关健康、模型可用性、平台异常公告、限流提示

首页组件：

• HeroStatusBand：显示 Gateway 健康、可用模型数、今日任务数、当前余额。
• QuickStartActions：Chat 调用、生图调用、生视频调用、创建 API Key、查看 API 文档。
• ModelCapabilityGrid：按文本、图像、视频、音频、Embedding 展示可用能力。
• RecentTasks：最近任务状态、进度、失败原因和重试入口。
• UsageSnapshot：本月调用量、token、图片/视频任务、费用趋势。

16.4 模型

模型页面面向普通用户和管理员，但展示内容按权限裁剪。

页面	路由	权限	说明
模型广场	/models	public/basic	按能力、provider、价格、上下文、多模态筛选模型
模型详情	/models/:modelKey	public/basic	能力、价格、限流、参数 schema、示例请求、在线试用
模型价格	/models/:modelKey/pricing	basic	文本输入/输出、图像分辨率/质量、视频时长/分辨率等价格
模型调用测试	/models/:modelKey/playground	basic	选择 API Key 或 JWT，在线测试 Chat/生图/生视频

模型页能力：

• 筛选：模型类型、provider、是否支持 stream、多模态、参考图/视频/音频、上下文窗口、价格区间。
• 展示：有效模型价、TPM/RPM/并发限制、是否支持测试模式、常见错误码。
• 管理员视角：展示平台模型来源、基准模型映射、平台折扣、能力覆盖和实际候选平台。

16.5 用户工作台

用户工作台关注“我能用什么、用了多少、怎么调用、历史任务在哪里”。

页面	路由	权限	说明
个人中心总览	/workspace/overview	basic	账号信息、身份来源、角色、用户组、余额、API Key 数、最近任务、用量摘要
余额与充值	/workspace/billing	basic	余额、资源包、充值入口、消费记录、用户组充值折扣、发票/订单状态
API Key 管理	/workspace/api-keys	basic	API Key 列表、创建、禁用、重置、权限范围、最近调用
任务记录	/workspace/tasks	basic	Chat/生图/生视频等任务列表，按状态、模型、时间筛选
任务详情	/workspace/tasks/:id	basic	请求、进度事件、结果、计费、上传资产、失败原因

边界：

• 独立模式下，用户资料、API Key、余额、充值订单和钱包流水由 Gateway 本地模块闭环；接入 server-main 时，余额、充值、订单、API Key 生命周期仍归 server-main，Gateway 前端可以通过 server-main API 或兼容代理展示。
• 用户组影响充值折扣、调用折扣和并发/限流；工作台需要展示当前用户命中的用户组、折扣说明、TPM/RPM/并发限制。
• 任务记录以 Gateway 任务为执行事实源，但业务历史最终仍可由 server-main 汇总。
• API Key 创建时必须显示一次性 secret，后续只展示 key 名称、前缀、权限和最近使用时间。

16.6 管理工作台

管理工作台只对 power/manager 开放，负责全局模型、平台、限流、重试、运行态和系统集成。当前阶段平台凭证和 provider 凭证仅允许全局管理员配置，租户管理员暂不拥有自助配置入口。

页面	路由	权限	说明
管理总览	/admin	power	服务健康、任务吞吐、成功率、队列积压、异常平台、回调 outbox
租户管理	/admin/tenants	power	本地租户、同步租户、租户策略、状态和用量隔离
用户管理	/admin/users	power	本地用户、同步用户、角色、状态、同步差异和用户组命中
用户组管理	/admin/user-groups	power	用户组、成员关系、充值折扣、调用折扣、并发/限流策略
全局模型配置	/admin/models/global	power	基准模型库、能力 schema、基准定价、默认限流模板
基准 Provider	/admin/catalog/providers	power	provider 列表、协议类型、能力 schema、启停状态
基准模型详情	/admin/catalog/base-models/:id	power	能力、价格版本、默认 TPM/RPM/并发、引用平台模型
定价规则	/admin/pricing/rules	power	文本/图像/视频/音频价格、动态权重、版本生效时间
平台管理	/admin/platforms	power	平台 CRUD、启停、优先级、凭证状态、复制、异常重置
平台详情	/admin/platforms/:id	power	基础信息、凭证、模型、折扣、限流、重试、运行态、快照
平台模型	/admin/platform-models	power	平台模型列表、基准映射、能力覆盖、价格覆盖、权限过滤
API 配置	/admin/platform-apis	power	兼容原 integration/platform-api 的 CRUD 与执行测试
队列监控	/admin/runtime/queues	power	queue key、等待数、运行数、租约、恢复状态
客户端运行态	/admin/runtime/clients	power	running、waiting、limiter ratio、cooldown、last error
限流策略	/admin/policies/rate-limit	power	TPM、RPM、并发、队列长度、冷却策略
重试策略	/admin/policies/retry	power	global/provider/platform/model/method 重试策略
任务审计	/admin/tasks	power	全量任务、attempt、失败切换、用户/模型/平台筛选
上传记录	/admin/uploads	power	主服务上传记录映射、任务关联、失败重试
结算 outbox	/admin/settlements	manager	结算事件、重试、跳过、幂等 key
回调 outbox	/admin/callbacks	power	任务进度回调状态、失败原因、手动 replay
测试模式	/admin/simulation	power	simulation profile、失败注入、慢任务、dry-run billing
系统设置	/admin/settings	manager	server-main 地址、内部令牌、运行模式、安全开关

关键管理页面：

• 全局模型配置：维护 model_catalog_providers、base_model_catalog、model_pricing_rules，支持导入旧项目配置。
• 租户管理：维护 gateway_tenants，支持本地租户 CRUD、从 server-main 增量同步、禁用状态同步、租户策略和用量隔离审计。
• 用户管理：维护 gateway_users，支持本地用户 CRUD、从 server-main 增量同步、禁用状态同步、角色同步和同步差异审计。
• 用户组管理：维护 gateway_user_groups、gateway_user_group_memberships，支持从 server-main 同步成员关系；独立模式执行全部策略，接入模式下充值折扣由 server-main 执行，Gateway 执行调用折扣和并发/限流。
• 平台管理：创建平台时选择基准 provider，配置默认折扣系数；平台模型可 follow 基准、按折扣继承或自定义覆盖。
• 队列与限流：展示 TPM/RPM 窗口、预占值、并发 lease、cooldown、next run。
• 回调 outbox：展示 Gateway 到进度回调目标的投递结果，支持按 task replay。

16.7 API 文档与在线调用测试

API 文档面向开发者，需要能完成从鉴权到真实调用的闭环。

页面	路由	权限	说明
文档首页	/docs	public/basic	快速开始、鉴权方式、模型列表、错误码、限流说明
鉴权	/docs/auth	public/basic	JWT、OpenAPI sk-*、Header、权限范围、API Key 安全
Chat	/docs/api/chat	public/basic	/v1/chat/completions、stream、工具调用、示例代码
Responses	/docs/api/responses	public/basic	/v1/responses 请求、取消、结构化输出
图片	/docs/api/images	public/basic	/v1/images/generations、/v1/images/edits、文件输入
视频	/docs/api/videos	public/basic	/v1/video/generations、进度查询、结果取回
音频/语音	/docs/api/audio	public/basic	speech、music、digital human 等接口
Embeddings	/docs/api/embeddings	public/basic	embedding 模型、批量输入、维度说明
文件上传	/docs/api/files	public/basic	说明仍调用 server-main /v1/files/upload
任务结果	/docs/api/tasks	public/basic	/v1/ai/result/:taskId、取消、状态、回调语义
错误码	/docs/errors	public/basic	兼容错误结构、retryable 分类、限流错误
在线调试	/docs/playground	basic	选择模型、API Key、请求模板，执行在线调用测试

在线调试器：

• 左侧选择接口类型：Chat、Responses、生图、图像编辑、生视频、Embedding、语音。
• 中间为参数表单 + JSON editor 双模式，表单字段来自模型能力 schema。
• 右侧展示 curl、JavaScript、Python 示例代码和实时响应。
• 支持 stream 结果面板、任务进度时间线、结果预览、usage / billings。
• 支持测试模式开关；开启后标记 simulation，不触达真实 provider、不真实扣费。
• 调试前展示当前 API Key 的权限、余额、TPM/RPM/并发限制。

16.8 前端模块目录

apps/web/src/
  app/
    routes.tsx
    providers.tsx
  components/
    ui/                 # shadcn-ui generated components
    layout/
    data-table/
    json-viewer/
    status-badge/
  features/
    auth/
      login/
      register/
    home/
    models/
    workspace/
      overview/
      billing/
      api-keys/
      tasks/
    admin/
      dashboard/
      catalog/
      tenants/
      users/
      user-groups/
      pricing/
      platforms/
      platform-apis/
      runtime/
      policies/
      tasks/
      callbacks/
      uploads/
      settlements/
      simulation/
      settings/
    docs/
      api-reference/
      playground/
  lib/
    api-client.ts
    auth.ts
    format.ts
    query-keys.ts
  contracts/
    dto.ts              # 或从 packages/contracts 引入

16.9 前端数据流

• 使用 @tanstack/react-query 管理列表、详情、轮询和 mutation。
• 表格使用 @tanstack/react-table，配合 shadcn Table。
• 表单使用 react-hook-form + zod，校验策略与后端 DTO 对齐。
• 用户工作台在独立模式下调用 Gateway 本地身份/账务模块；接入 server-main 时余额、充值、API Key 生命周期优先调用 server-main API，Gateway 展示执行侧任务、模型能力、用户同步状态和用户组执行策略。
• Gateway 控制台事件统一封装为 useTaskEvents(taskId)；业务前端实时进度仍由原 WebSocket 网关推送。
• 所有 destructive action 使用 shadcn Dialog 二次确认。
• 页面级权限由路由 loader 或 wrapper 判断，不在每个按钮里重复散落判断。

17. 迁移计划

Phase 0：脚手架与契约

• 建立 monorepo、Go API、React 控制台、PG migration。
• 前端接入 shadcn-ui，建立基础组件目录和主题 token。
• PG 目标版本为 PostgreSQL 18；复用 Agent memory 的 easyai-pgvector 实例，但使用独立数据库 easyai_ai_gateway，避免与 easyai_memory 的记忆表混库。
• 容器网络内默认连接串为 postgresql://easyai:easyai2025@easyai-pgvector:5432/easyai_ai_gateway?schema=public；宿主机直跑时必须改成宿主机可访问的 host/port，例如 localhost 或实际映射端口。
• 如果只提供 MEMORY_DATABASE_URL，Go 侧只借用其中的 host/user/password，并按 AI_GATEWAY_DATABASE_NAME 替换数据库名；同时会把 Prisma 风格的 schema=public 转成 PostgreSQL search_path 参数。
• 建立 JWT / API Key 授权中间件骨架和 standalone / server-main / hybrid 身份模式配置，默认 hybrid。
• 固化 API、事件、数据库设计。
• 建立 simulation / dry-run 模式配置与安全开关，默认禁止生产环境普通用户随意开启。
• 建立基准 provider、基准模型库、价格规则、用户、用户组策略、邀请码、本地 API Key、钱包、充值订单和 TPM/RPM/并发限流表结构。

Phase 1：模型库 + 首批生成能力

第一阶段只做可落地的核心闭环：模型库、大模型对话、生图、图像编辑。Client 只迁移 OpenAI 和 Gemini 两个，视频和其他 provider 后移。

• 导入 OpenAI、Gemini 的基准 provider、基准模型、能力 schema、默认限流模板，形成首批 base_model_catalog。
• 建立全局模型配置：模型类型、上下文、多模态能力、图片输入/输出能力、stream 支持、价格规则。
• 平台创建支持选择基准模型、设置默认折扣系数；平台模型支持 follow 基准模型、折扣继承和自定义覆盖。
• 建立 gateway_users 同步副本和 gateway_user_groups 策略解析，支持本地用户与 server-main 用户在同一套策略链路里命中不同折扣和限流。
• 建立本地账号闭环：普通注册可选邀请码，独立模式支持本地 API Key、余额、充值订单和钱包流水。
• 迁移大模型对话路由：/chat/completions、/v1/chat/completions，并为 /responses / /v1/responses 保留兼容契约。
• 迁移生图和图像编辑路由：/images/generations、/v1/images/generations、/images/edits、/v1/images/edits。
• 建立 OpenAI Chat / Image Client 与 Gemini Chat / Image Client 的 Base Client 实现和 contract test。
• 支持文本输入/输出 token 计费，图像按分辨率、质量、数量、生成/编辑模式计费。
• 实现调用 server-main 开放上传接口的 ServerMainUploadClient，覆盖参考图、mask、provider 临时 URL 转存、base64 小文件上传。
• 实现 SimulationClient，支持 Chat、生图、图像编辑的成功、失败、慢任务、限流、未知提交态等 profile。

Phase 2：路由、队列与稳定性补强

• 迁移 IntegrationModelFactory.assignClientsByModelName 行为。
• 建立 Base Client 生命周期：构建参数、提交任务、轮询结果、归一化结果、估算计费、取消任务。
• 实现客户端失败切换策略：上一个客户端失败后按配置切到下一个候选客户端。
• 补队列持久化、TPM/RPM/并发限流、重启恢复、重试、超时、任务事件。
• 实现任务进度 callback outbox，将 Gateway 进度回调给实时推送通道；同时保留 Gateway 控制台 SSE / WebSocket 和 OpenAI stream。
• 为 OpenAI、Gemini 增加 retry classification test、billing snapshot、progress event snapshot。

Phase 3：server-main 切薄门面与灰度

• OpenaiService 内部先将 Chat、生图、图像编辑切到 Gateway HTTP SDK。
• 结算事件接入 server-main 扣费链路。
• 前端逐步改 Gateway API Base URL。
• 开启 shadow / dry-run，比对旧实现和 Gateway 的候选模型、预估扣费、参数预处理结果。

Phase 4：视频与更多 provider

• 在 Phase 1 稳定后再迁移生视频、音频、Embedding、音乐、数字人等能力。
• 迁移 RunningHub、Jimeng、Vidu、Kling、Hunyuan Video、Suno 等 provider。
• 对 app-style provider 补 assignClientsByProviderMethod 和 provider + methodName 队列 key。
• 每个 provider 增加 contract test、retry classification test、billing snapshot。

Phase 5：server-main 清理旧实现

• 删除或冻结 server-main 中重复的 runtime client。
• 保留必要 BFF、历史、账单、文件上传能力。

18. 验收标准

• pnpm nx run api:migrate 可在 Agent memory PostgreSQL 中初始化 AI Gateway 表。
• pnpm nx run api:test 通过。
• pnpm nx run web:build 通过。
• 控制台使用 shadcn-ui 组件，不出现散落的独立 UI 体系。
• 使用 server-main 签发的 JWT 能访问 /api/v1/me。
• OpenAPI sk-* 能委托 server-main 校验并获得用户 claim。
• 原 integration-platform、站内生成、/v1/* 核心路由可用，DTO 与响应结构兼容。
• 基准 provider、基准模型库、基准价格和默认限流模板可在控制台维护。
• 用户、用户组、成员关系、充值折扣、调用折扣、TPM/RPM/并发策略可在管理工作台维护；独立模式可本地闭环，接入模式下充值执行仍以 server-main 为事实源。
• 接入 server-main 时，用户、角色、禁用状态和用户组成员关系支持增量同步；任务保存用户和用户组策略快照。
• 平台创建可设置默认折扣系数；平台模型未配置时 follow 基准模型，配置折扣时按基准价折扣计算，自定义覆盖时覆盖价格和能力。
• 文本定价支持输入/输出 token 分开计费；图像定价支持分辨率和质量权重；视频定价支持时长、分辨率、有无音频等权重。
• estimated billing 与真实任务 billings 使用同一个 effective pricing resolver，不能出现预估和真实路由价格来源不一致。
• 队列任务在服务异常重启后可恢复：已提交供应商的任务继续 poll，未提交任务重新排队。
• 限流策略覆盖 TPM、RPM、并发，并支持平台、客户端、基准模型、平台模型、方法、租户、用户组、用户、API Key 维度。
• TPM/RPM 一分钟窗口和并发 lease 在服务重启后可恢复或释放，不产生永久占用。
• 多客户端候选下，一个客户端可重试失败后按策略切换下一个客户端；禁用重试时必须直接失败。
• Base Client 架构覆盖构建参数、提交任务、取回结果、归一化结果、计费估算、取消任务。
• 任务中间进度可通过 SSE / WebSocket / stream 返回，并支持断线重放。
• 业务前端实时进度通过 TASK_PROGRESS_CALLBACK_URL 回调到 server-main 内部任务进度接口，再由主服务复用原 WebSocket 网关推送；callback outbox 支持失败重试和手动 replay。
• 文件上传统一调用 server-main 开放上传接口，Gateway 不维护自己的 OSS 配置。
• 测试模式下不会向真实平台提交任务、不会真实扣费、不会调用主服务生产上传接口，但会完整经过路由、队列、限流、重试、进度和结果归一。
• 测试模式支持 profile 注入可重试错误，能验证客户端失败切换；禁用重试时能验证直接失败。
• Phase 1 至少完成 Chat / 生图 / 图像编辑各一个 provider 的端到端任务；生视频放到 Phase 4 后续迁移。
• 结算事件在 server-main 幂等扣费。
• 同名模型跨平台权限过滤与旧逻辑一致。

19. 本轮设计复核结论与已确认决策

本轮复核后已修正：

• 身份边界：不再写成“用户/租户只能留在 server-main”，改为 standalone、server-main、hybrid 三种模式。
• 多租户：补 gateway_tenants，并把用户、任务、平台可见性、限流和策略解析都接入租户上下文。
• 登录注册：补 Gateway 本地账号注册登录接口和前端登录页规划。
• 进度回调：统一表述为回调 server-main 内部任务进度接口，不直接回调 ws-gateway。
• Phase 1 范围：继续限定为模型库、Chat、生图、图像编辑、OpenAI 和 Gemini；视频迁移放到后续阶段。

已确认决策：

1. 默认身份模式就是 hybrid，用于同时支持本地账号和 server-main token / API Key。
2. 普通注册支持填写邀请码，但邀请码不是必填项；填写后按邀请码加入指定租户和用户组。
3. 先做本地闭环：独立模式下本地 API Key、余额、充值订单和钱包流水由 Gateway 承接。
4. 当前阶段仅允许全局管理员配置 provider / platform 凭证和全局模型，不开放租户管理员自助配置凭证。