Initial project scaffold

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-09 14:36:35 +08:00
commit 6323e70e49
39 changed files with 8664 additions and 0 deletions
@@ -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 上传配置和实际文件落库。
+- 对话与绘图历史最终落库。