# 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 上传配置和实际文件落库。
- 对话与绘图历史最终落库。