easyai-ai-gateway/docs/migration-plan.md

integration-platform 迁移实施计划

Phase 0：脚手架与基础契约

• 在 Agent memory 的 PostgreSQL 18 easyai-pgvector 实例上建立独立数据库 easyai_ai_gateway 和 AI Gateway 表，不直接使用 easyai_memory 记忆库。正式 EasyAI compose 默认账号为 easyai / easyai2025。
• 完成 Go API、React 前端、Nx/go.work/pnpm monorepo、基础 migration。
• 完成本地账号注册登录、可选邀请码、JWT / API Key 授权验证骨架，并将默认身份模式设为 hybrid。
• 固化兼容路由、任务事件、队列、定价、限流、回调 outbox 的基础设计。
• React 前端先具备登录页、首页、模型、用户工作台、管理工作台、API 文档的页面骨架。

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

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

1.1 模型库

• 建立 model_catalog_providers、base_model_catalog、model_pricing_rules 的首批数据。
• 建立 gateway_tenants、gateway_users、gateway_user_groups、gateway_invitations 和用户组策略，支持独立租户/用户、可选邀请码注册关系记录、server-main 同步租户/用户、不同用户组的充值折扣、调用折扣和并发/限流策略。
• 建立独立模式本地闭环表：gateway_api_keys、gateway_wallet_accounts、gateway_wallet_transactions、gateway_recharge_orders。
• 导入 OpenAI、Gemini 的基准 provider、基准模型、能力 schema、默认限流模板。
• 支持全局模型配置：模型类型、上下文、多模态能力、图片输入/输出能力、stream 支持、价格规则。
• 支持平台模型 follow 基准模型、平台折扣、模型级自定义价格和能力覆盖。
• 管理工作台可查看和编辑基准模型、平台模型、定价规则、默认限流。

1.2 大模型对话

• 迁移兼容路由：
  • /chat/completions
  • /v1/chat/completions
  • /responses / /v1/responses 可先保留契约，按 OpenAI/Gemini Chat 能力逐步补齐。
• 支持同步响应和 stream 响应。
• 支持文本、多模态图片输入的参数归一与能力校验。
• 支持 TPM/RPM/并发限流、失败切换、任务事件、usage / billings 回填。
• 先完成 OpenAI Chat Client 和 Gemini Chat Client 的 contract test。

1.3 生图与图像编辑

• 迁移兼容路由：
  • /images/generations
  • /v1/images/generations
  • /images/edits
  • /v1/images/edits
• 支持 prompt、参考图、mask / edit 输入、尺寸、质量、数量等参数归一。
• 文件输入与结果转存统一调用 server-main /v1/files/upload。
• 支持图像价格预估：分辨率、质量、数量、生成/编辑模式权重。
• 先完成 OpenAI Image Client 和 Gemini Image Client 的 contract test。

1.4 第一阶段验收

• 模型库中能维护 OpenAI、Gemini 的基准模型、能力和价格。
• 管理员能配置平台、平台模型、折扣、限流和重试策略。
• 管理员能配置租户、用户、用户组、成员关系、充值折扣、调用折扣、TPM/RPM/并发策略。
• 普通用户能在模型页看到可用 Chat / 生图 / 图像编辑模型。
• API 文档能在线测试 Chat、生图、图像编辑。
• OpenAI 与 Gemini 的 Chat、生图、图像编辑至少各跑通一个端到端用例。
• estimated billing 与真实 billings 使用同一个 effective pricing resolver。
• 测试模式可模拟 Chat、生图、图像编辑的成功、可重试失败、不可重试失败。
• 任务进度写入 gateway_task_events 和 callback outbox，失败可重试和 replay。

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

• 从旧代码抽取以下行为测试：
  • 同名模型平台权限过滤。
  • assignClientsByModelName 候选排序。
  • estimated billing 使用真实候选集。
• 建立 TPM/RPM/并发限流 fixtures，覆盖预占、释放、失败切换重新计数。
• Go 侧实现 router，并用 fixtures 对齐旧行为。
• 补齐持久化队列、任务租约、heartbeat、重启恢复、attempt 审计。
• 补齐租户、用户和用户组策略解析：source + externalTenantId 租户同步、source + externalUserId 用户同步、多组命中、优先级、策略合并、任务策略快照。
• 补齐 callback outbox、settlement outbox 的重试、死信和手动 replay。

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

• server-main 的 Chat、生图、图像编辑入口内部切到 Gateway HTTP SDK。
• 开启 shadow / dry-run，比对旧实现和 Gateway 的候选模型、预估扣费、参数预处理结果。
• 前端逐步增加 VITE_GATEWAY_API_BASE_URL，灰度切流核心接口。
• 观察任务成功率、平均排队时间、限流命中、扣费一致性、回调 outbox 滞留。

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 中重复的 runtime client。
• 保留必要 BFF、用户历史、账单、文件上传能力。
• 将旧 integration-platform 配置迁移脚本和回滚脚本固化。

风险控制

• 第一阶段不做视频和大量 provider，避免迁移面过宽。
• 不做 first-match 回退，所有候选选择都要有行为测试。
• 接入 server-main 模式下 API Key 不在 Gateway 落库；独立模式的本地 API Key、余额、充值订单和钱包流水在 Gateway 闭环。
• OSS 密钥不进入 Gateway；文件统一调用 server-main 开放上传接口。
• 租户、用户和用户组可由 Gateway 管理或从 server-main 同步；接入模式下充值执行、余额流水仍以 server-main 为事实源。
• 平台凭证和 provider 凭证当前阶段只允许全局管理员配置，不开放租户管理员自助维护。
• 业务前端实时进度仍走现有 WebSocket 网关；Gateway 只负责事件与回调 outbox。
• 平台模型没有自定义价格时必须 follow 基准模型，不能隐式按 0 计费。
• estimated billing 与真实结算必须使用同一个 effective pricing resolver。
• 结算事件必须幂等和可重试。
• 任务推送与余额/历史推送拆分，避免重新耦合回 server-main。