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

integration-platform 迁移实施计划

第 1 周：基础设施

• 在 Agent memory 的 easyai-pgvector 实例上建立独立数据库 easyai_ai_gateway 和 AI Gateway 表，不直接使用 easyai_memory 记忆库。正式 EasyAI compose 默认账号为 easyai / easyai2025。
• 完成 JWT / API Key 授权验证。
• 完成基准 provider、基准模型库、平台与模型管理 API。
• 完成基准定价、平台默认折扣、平台模型覆盖的 schema。
• React 控制台接入平台、基准模型、TPM/RPM 限流窗口列表。

第 2 周：路由行为复刻

• 从旧代码抽取以下行为测试：
  • 同名模型平台权限过滤。
  • assignClientsByModelName 候选排序。
  • assignClientsByProviderMethod provider-level 负载均衡。
  • estimated billing 使用真实候选集。
• 建立 TPM/RPM/并发限流 fixtures，覆盖预占、释放、失败切换重新计数。
• Go 侧实现 router，并用 fixtures 对齐旧行为。

第 3 周：核心 provider

• 先迁 OpenAI-compatible / Universal。
• 再迁生图、生视频主 provider。
• 每个 provider 建 contract test。

第 4 周：任务链路

• 实现队列、任务状态、SSE 进度。
• 实现 TPM/RPM 一分钟窗口计数和并发 lease 恢复。
• 打通 Chat、生图、生视频端到端。
• 生成结算事件，接入 server-main 幂等扣费。

第 5 周：切流

• server-main OpenaiService 加 Gateway client。
• 开启 shadow / dry-run 比对。
• 前端增加 VITE_GATEWAY_API_BASE_URL。
• 灰度切流，观察任务成功率、平均排队、扣费一致性。

风险控制

• 不做 first-match 回退，所有候选选择都要有行为测试。
• API Key 不在 Gateway 落库。
• OSS 密钥不进入 Gateway；文件统一调用 server-main 开放上传接口。
• 平台模型没有自定义价格时必须 follow 基准模型，不能隐式按 0 计费。
• estimated billing 与真实结算必须使用同一个 effective pricing resolver。
• 结算事件必须幂等和可重试。
• 任务推送与余额/历史推送拆分，避免重新耦合回 server-main。