lanyuanxiaoyao
bc1ee612d9
- 新增 ConversionEngine 核心引擎，支持 OpenAI 和 Anthropic 协议转换 - 添加 stream decoder/encoder 实现 - 更新 provider client 支持新引擎 - 补充单元测试和集成测试 - 更新 specs 文档
143 lines
4.8 KiB
Markdown
143 lines
4.8 KiB
Markdown
# Layered Architecture
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 实现三层架构
|
||
|
||
系统 SHALL 实现 handler → service → repository 三层架构，并在 handler 和 provider 之间新增 conversion 层。
|
||
|
||
#### Scenario: Handler 层职责
|
||
|
||
- **WHEN** 处理 HTTP 请求
|
||
- **THEN** handler 层 SHALL 仅负责 HTTP 请求解析、URL 路由和响应写入
|
||
- **THEN** handler 层 SHALL 调用 ConversionEngine 处理协议转换
|
||
- **THEN** handler 层 SHALL 调用 service 层处理业务逻辑
|
||
- **THEN** handler 层 SHALL NOT 直接访问数据库或执行协议转换逻辑
|
||
|
||
#### Scenario: Conversion 层职责
|
||
|
||
- **WHEN** 处理协议转换
|
||
- **THEN** conversion 层 SHALL 包含 Canonical Model 定义
|
||
- **THEN** conversion 层 SHALL 包含各协议的 ProtocolAdapter 实现
|
||
- **THEN** conversion 层 SHALL 包含 ConversionEngine 门面
|
||
- **THEN** conversion 层 SHALL NOT 依赖 handler 或 service 层
|
||
|
||
#### Scenario: Service 层职责
|
||
|
||
- **WHEN** 处理业务逻辑
|
||
- **THEN** service 层 SHALL 包含业务规则和验证
|
||
- **THEN** service 层 SHALL 调用 repository 层访问数据
|
||
- **THEN** service 层 SHALL NOT 包含协议转换逻辑
|
||
|
||
#### Scenario: Repository 层职责
|
||
|
||
- **WHEN** 访问数据
|
||
- **THEN** repository 层 SHALL 仅负责数据访问
|
||
- **THEN** repository 层 SHALL 封装数据库操作
|
||
- **THEN** repository 层 SHALL NOT 包含业务逻辑或协议转换逻辑
|
||
|
||
### Requirement: 定义核心接口
|
||
|
||
系统 SHALL 定义清晰的接口边界。
|
||
|
||
#### Scenario: Service 接口定义
|
||
|
||
- **WHEN** 定义 service 接口
|
||
- **THEN** SHALL 定义 ProviderService、ModelService、RoutingService、StatsService 接口
|
||
- **THEN** SHALL 定义清晰的业务方法签名
|
||
- **THEN** SHALL 使用 domain 类型作为参数和返回值
|
||
|
||
#### Scenario: Repository 接口定义
|
||
|
||
- **WHEN** 定义 repository 接口
|
||
- **THEN** SHALL 定义 ProviderRepository、ModelRepository、StatsRepository 接口
|
||
- **THEN** SHALL 定义清晰的数据访问方法签名
|
||
- **THEN** SHALL 使用 domain 类型作为参数和返回值
|
||
|
||
#### Scenario: Provider Client 接口定义
|
||
|
||
- **WHEN** 定义 provider client 接口
|
||
- **THEN** SHALL 定义 ProviderClient 接口
|
||
- **THEN** SHALL 包含 Send（非流式）和 SendStream（流式）方法
|
||
- **THEN** SHALL 接受 HTTPRequestSpec 作为参数，不绑定特定协议
|
||
- **THEN** SHALL 支持接口 Mock
|
||
|
||
#### Scenario: Conversion 层接口定义
|
||
|
||
- **WHEN** 定义 conversion 层接口
|
||
- **THEN** SHALL 定义 ProtocolAdapter、StreamDecoder、StreamEncoder、StreamConverter、ConversionMiddleware 接口
|
||
- **THEN** SHALL 定义 AdapterRegistry 用于 Adapter 注册和查询
|
||
- **THEN** SHALL 定义 ConversionEngine 作为统一门面
|
||
|
||
### Requirement: 实现依赖注入
|
||
|
||
系统 SHALL 使用手动依赖注入。
|
||
|
||
#### Scenario: Repository 注入
|
||
|
||
- **WHEN** 初始化 service
|
||
- **THEN** SHALL 通过构造函数注入 repository 依赖
|
||
- **THEN** SHALL 使用接口类型而非具体类型
|
||
|
||
#### Scenario: Service 注入
|
||
|
||
- **WHEN** 初始化 handler
|
||
- **THEN** SHALL 通过构造函数注入 service 依赖、ConversionEngine、ProviderClient
|
||
- **THEN** SHALL 使用接口类型而非具体类型
|
||
|
||
#### Scenario: Conversion 组装
|
||
|
||
- **WHEN** 应用启动
|
||
- **THEN** SHALL 创建 AdapterRegistry 并注册所有 ProtocolAdapter
|
||
- **THEN** SHALL 创建 ConversionEngine（注入 registry 和 middleware chain）
|
||
- **THEN** SHALL 将 ConversionEngine 注入到 ProxyHandler
|
||
|
||
#### Scenario: 主函数组装
|
||
|
||
- **WHEN** 应用启动
|
||
- **THEN** main.go SHALL 按顺序构造所有依赖
|
||
- **THEN** SHALL 先构造基础设施（logger、database）
|
||
- **THEN** SHALL 再构造 repository、service
|
||
- **THEN** SHALL 再构造 conversion 层（registry → engine）
|
||
- **THEN** SHALL 最后构造 handler
|
||
|
||
### Requirement: 定义 Domain 模型
|
||
|
||
系统 SHALL 定义独立的 domain 模型。
|
||
|
||
#### Scenario: Domain 模型定义
|
||
|
||
- **WHEN** 定义领域模型
|
||
- **THEN** SHALL 在 internal/domain/ 包中定义
|
||
- **THEN** SHALL 包含 Provider、Model、UsageStats 等模型
|
||
- **THEN** Provider SHALL 包含 Protocol 字段
|
||
- **THEN** SHALL 与数据库模型分离
|
||
|
||
#### Scenario: Domain 模型使用
|
||
|
||
- **WHEN** service 和 repository 处理数据
|
||
- **THEN** SHALL 使用 domain 模型
|
||
- **THEN** SHALL NOT 使用数据库模型（GORM 模型）
|
||
|
||
### Requirement: 提高可测试性
|
||
|
||
架构 SHALL 提高代码可测试性。
|
||
|
||
#### Scenario: Service 层测试
|
||
|
||
- **WHEN** 测试 service 层
|
||
- **THEN** SHALL 能够 Mock repository 依赖
|
||
- **THEN** SHALL 能够独立测试业务逻辑
|
||
|
||
#### Scenario: Handler 层测试
|
||
|
||
- **WHEN** 测试 handler 层
|
||
- **THEN** SHALL 能够 Mock service 依赖
|
||
- **THEN** SHALL 能够独立测试 HTTP 处理逻辑
|
||
|
||
#### Scenario: Repository 层测试
|
||
|
||
- **WHEN** 测试 repository 层
|
||
- **THEN** SHALL 使用测试数据库
|
||
- **THEN** SHALL 能够独立测试数据访问逻辑
|