docs: 暂存本次变更的设计文档

openspec/changes/refactor-conversion-engine/specs/openai-protocol-proxy/spec.md

@@ -0,0 +1,99 @@
+## MODIFIED Requirements
+
+### Requirement: 支持 OpenAI Chat Completions API 端点
+
+网关 SHALL 提供 OpenAI Chat Completions API 端点供外部应用调用。
+
+#### Scenario: 成功的非流式请求
+
+- **WHEN** 应用发送 POST 请求到 `/openai/v1/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
+- **THEN** 网关 SHALL 通过 ConversionEngine 转换请求
+- **THEN** 网关 SHALL 将转换后的请求转发到配置的供应商
+- **THEN** 网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用
+
+#### Scenario: 成功的流式请求
+
+- **WHEN** 应用发送 POST 请求到 `/openai/v1/chat/completions`，携带 `stream: true`
+- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter
+- **THEN** 网关 SHALL 使用 SSE 格式将转换后的响应流式返回给应用
+- **THEN** 网关 SHALL 在流完成时发送 `data: [DONE]`
+
+#### Scenario: 同协议透传（OpenAI → OpenAI Provider）
+
+- **WHEN** 客户端使用 OpenAI 协议且目标供应商也是 OpenAI 协议
+- **THEN** 网关 SHALL 跳过 Canonical 转换，仅重建认证 Header 后原样转发
+- **THEN** 请求和响应 Body SHALL 保持原样
+
+### Requirement: 根据模型名称路由请求
+
+网关 SHALL 根据请求中的 `model` 字段将请求路由到相应的供应商。
+
+#### Scenario: 有效模型路由
+
+- **WHEN** 请求包含存在于配置模型中的 `model` 字段
+- **AND** 该模型已启用
+- **THEN** 网关 SHALL 将请求路由到该模型关联的供应商
+- **THEN** 网关 SHALL 从供应商的 `protocol` 字段获取 providerProtocol
+
+#### Scenario: 模型未找到
+
+- **WHEN** 请求包含不存在于配置模型中的 `model` 字段
+- **THEN** 网关 SHALL 使用 OpenAI 格式返回错误响应
+
+#### Scenario: 模型已禁用
+
+- **WHEN** 请求包含已禁用模型的 `model` 字段
+- **THEN** 网关 SHALL 使用 OpenAI 格式返回错误响应
+
+### Requirement: 对 OpenAI 兼容供应商透明代理
+
+网关 SHALL 对 OpenAI 兼容供应商的请求和响应通过 ConversionEngine 进行转换处理。
+
+#### Scenario: 跨协议请求转发
+
+- **WHEN** 网关收到 OpenAI 协议请求且目标供应商使用不同协议
+- **THEN** 网关 SHALL 通过 ConversionEngine 将请求转换为目标协议格式
+- **THEN** 网关 SHALL 使用目标协议的 Adapter 构建 URL 和 Header
+
+#### Scenario: 扩展层接口代理
+
+- **WHEN** 网关收到 `/openai/v1/models` 等 GET 请求
+- **THEN** 网关 SHALL 通过 ConversionEngine 转换扩展层接口的响应格式
+
+### Requirement: 使用 service 层处理请求
+
+Handler SHALL 通过 service 层处理业务逻辑。
+
+#### Scenario: 调用 routing service
+
+- **WHEN** ProxyHandler 收到请求
+- **THEN** SHALL 调用 RoutingService.Route() 获取路由结果
+- **THEN** SHALL 从路由结果获取 Provider（含 protocol 字段）
+
+#### Scenario: 调用 stats service
+
+- **WHEN** 请求成功完成
+- **THEN** SHALL 调用 StatsService.Record() 记录统计
+- **THEN** SHALL 异步记录统计（不阻塞响应）
+
+### Requirement: 使用结构化错误处理
+
+ProxyHandler SHALL 使用 ConversionError 和协议对应的 encodeError 处理错误。
+
+#### Scenario: 转换错误
+
+- **WHEN** ConversionEngine 返回 ConversionError
+- **THEN** SHALL 使用 clientProtocol 的 Adapter.encodeError 编码错误响应
+- **THEN** SHALL 使用 OpenAI 错误格式（`{error: {message, type, code}}`）
+
+#### Scenario: 路由错误处理
+
+- **WHEN** RoutingService 返回错误
+- **THEN** SHALL 转换为 ConversionError
+- **THEN** SHALL 使用 OpenAI 错误格式返回
+
+#### Scenario: 供应商错误处理
+
+- **WHEN** ProviderClient 返回错误
+- **THEN** SHALL 包装为 ConversionError
+- **THEN** SHALL 使用 OpenAI 错误格式返回