lanyuanxiaoyao
f18904af1e
- 新增 domain 层：model、provider、route、stats 实体 - 新增 service 层：models、providers、routing、stats 业务逻辑 - 新增 repository 层：models、providers、stats 数据访问 - 新增 pkg 工具包：errors、logger、validator - 新增中间件：CORS、logging、recovery、request ID - 新增数据库迁移：初始 schema 和索引 - 新增单元测试和集成测试 - 新增规范文档：config-management、database-migration、error-handling、layered-architecture、middleware-system、request-validation、structured-logging、test-coverage - 移除 config 子包和 model_router（已迁移至分层架构）
99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# OpenAI Protocol Proxy
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: 支持 OpenAI Chat Completions API 端点
|
||
|
||
网关 SHALL 提供 OpenAI Chat Completions API 端点 `POST /v1/chat/completions` 供外部应用调用。
|
||
|
||
#### Scenario: 成功的非流式请求
|
||
|
||
- **WHEN** 应用发送 POST 请求到 `/v1/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
|
||
- **THEN** 网关 SHALL 将请求转发到配置的供应商
|
||
- **THEN** 网关 SHALL 将供应商的响应以 OpenAI 格式返回给应用
|
||
|
||
#### Scenario: 成功的流式请求
|
||
|
||
- **WHEN** 应用发送 POST 请求到 `/v1/chat/completions`，携带 `stream: true`
|
||
- **THEN** 网关 SHALL 将请求转发到配置的供应商
|
||
- **THEN** 网关 SHALL 使用 SSE 格式将响应流式返回给应用
|
||
- **THEN** 网关 SHALL 在流完成时发送 `data: [DONE]`
|
||
|
||
**变更说明：** handler 通过 service 层调用，而非直接调用 config 和 provider 包。API 接口保持不变。
|
||
|
||
### Requirement: 根据模型名称路由请求
|
||
|
||
网关 SHALL 根据请求中的 `model` 字段将请求路由到相应的供应商。
|
||
|
||
#### Scenario: 有效模型路由
|
||
|
||
- **WHEN** 请求包含存在于配置模型中的 `model` 字段
|
||
- **AND** 该模型已启用
|
||
- **THEN** 网关 SHALL 将请求路由到该模型关联的供应商
|
||
|
||
#### Scenario: 模型未找到
|
||
|
||
- **WHEN** 请求包含不存在于配置模型中的 `model` 字段
|
||
- **THEN** 网关 SHALL 返回带有适当错误消息的错误响应
|
||
|
||
#### Scenario: 模型已禁用
|
||
|
||
- **WHEN** 请求包含已禁用模型的 `model` 字段
|
||
- **THEN** 网关 SHALL 返回错误响应，指示模型不可用
|
||
|
||
**变更说明：** 路由逻辑从 router 包迁移到 RoutingService，通过 service 层调用。API 接口保持不变。
|
||
|
||
### Requirement: 对 OpenAI 兼容供应商透明代理
|
||
|
||
网关 SHALL 对 OpenAI 兼容供应商的请求和响应进行透明转发，不做修改。
|
||
|
||
#### Scenario: 请求转发
|
||
|
||
- **WHEN** 网关收到 OpenAI 协议请求
|
||
- **AND** 目标供应商是 OpenAI 兼容的
|
||
- **THEN** 网关 SHALL 将请求体原样转发给供应商
|
||
- **THEN** 网关 SHALL 在 Authorization 头中设置供应商的 API Key
|
||
- **THEN** 网关 SHALL 使用供应商的 base URL
|
||
|
||
#### Scenario: 响应转发
|
||
|
||
- **WHEN** 供应商返回响应
|
||
- **THEN** 网关 SHALL 将响应体原样返回给应用
|
||
- **THEN** 网关 SHALL 保留所有响应头和状态码
|
||
|
||
**变更说明：** provider client 通过接口注入到 handler，便于测试和替换实现。API 接口保持不变。
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 使用 service 层处理请求
|
||
|
||
Handler SHALL 通过 service 层处理业务逻辑。
|
||
|
||
#### Scenario: 调用 routing service
|
||
|
||
- **WHEN** handler 收到请求
|
||
- **THEN** SHALL 调用 RoutingService.Route() 获取路由结果
|
||
- **THEN** SHALL 使用路由结果中的供应商信息
|
||
|
||
#### Scenario: 调用 stats service
|
||
|
||
- **WHEN** 请求成功完成
|
||
- **THEN** SHALL 调用 StatsService.Record() 记录统计
|
||
- **THEN** SHALL 异步记录统计（不阻塞响应）
|
||
|
||
### Requirement: 使用结构化错误处理
|
||
|
||
Handler SHALL 使用结构化错误处理。
|
||
|
||
#### Scenario: 路由错误处理
|
||
|
||
- **WHEN** RoutingService 返回错误
|
||
- **THEN** SHALL 转换为对应的 AppError
|
||
- **THEN** SHALL 返回统一的错误响应
|
||
|
||
#### Scenario: 供应商错误处理
|
||
|
||
- **WHEN** ProviderClient 返回错误
|
||
- **THEN** SHALL 包装为 AppError
|
||
- **THEN** SHALL 包含请求上下文信息
|