# 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_tenant_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。