Initial project scaffold

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/migration-plan.md

@@ -0,0 +1,49 @@
+# 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。

docs/server-main-integration.md

@@ -0,0 +1,87 @@
+# server-main 对接清单
+
+## 1. 需要在 server-main 增加的内部接口
+
+### 1.1 API Key 校验
+
+```http
+POST /internal/platform/auth/verify-api-key
+Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
+Content-Type: application/json
+
+{ "apiKey": "sk-..." }
+```
+
+返回：
+
+```json
+{
+  "sub": "user-id",
+  "username": "demo",
+  "role": ["user"],
+  "tenantId": null,
+  "apiKeyId": "key-id",
+  "apiKeySecret": "sk-...",
+  "apiKeyName": "production-key"
+}
+```
+
+### 1.2 文件上传
+
+```http
+POST /v1/files/upload
+Authorization: Bearer ${USER_JWT_OR_SK}
+Content-Type: multipart/form-data
+
+file=@result.png
+```
+
+AI Gateway 不维护独立 OSS 配置，也不向 `server-main` 申请预签名。需要上传本地中间产物、provider 临时 URL 转存、base64 解码结果时，统一组装 multipart 请求调用主服务开放上传接口，并记录主服务返回的 file id / URL / object key。
+
+### 1.3 结算事件
+
+```http
+POST /internal/platform/settlements
+Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
+Content-Type: application/json
+Idempotency-Key: ${eventId}
+```
+
+结算事件中的 `billings` 由 AI Gateway 根据基准模型库、平台折扣、平台模型覆盖后的 effective pricing 计算。`server-main` 仍负责余额、资源包、账单锁和消费流水，不重新推导模型价格，只按幂等事件扣费。
+
+## 2. server-main OpenaiService 薄门面
+
+保留现有对内方法签名，内部新增 `AiGatewayClient`：
+
+- `createChatCompletion`
+- `generateImage`
+- `editImage`
+- `generateVideo`
+- `createEmbedding`
+- `estimateBilling`
+
+切流开关：
+
+```env
+AI_GATEWAY_ENABLED=true
+AI_GATEWAY_BASE_URL=http://easyai-ai-gateway:8088
+AI_GATEWAY_INTERNAL_TOKEN=change-me
+```
+
+## 3. 迁移期双写与比对
+
+高风险接口可短期 shadow：
+
+1. 主路径仍走旧实现。
+2. 异步把同一请求投递到 Gateway dry-run。
+3. 比对候选平台、TPM/RPM/并发限流决策、预估扣费、参数预处理结果。
+4. 结果稳定后切主路径。
+
+## 4. 不迁移项
+
+- `refresh_token` 签发和刷新。
+- 用户余额查询。
+- 用户 API Key 的创建、撤销、列表。
+- 账单锁、扣费流水。
+- OSS/COS/S3 上传配置和实际文件落库。
+- 对话与绘图历史最终落库。