lanyuanxiaoyao
915b004924
实现支持 OpenAI 和 Anthropic 双协议的统一大模型 API 网关 MVP 版本，包含： - OpenAI 和 Anthropic 协议代理 - 供应商和模型管理 - 用量统计 - 前端配置界面
152 lines
4.9 KiB
Markdown
152 lines
4.9 KiB
Markdown
# 供应商管理
|
||
|
||
## Purpose
|
||
|
||
TBD - 提供供应商配置的管理功能（创建、查询、更新、删除）
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 创建供应商配置
|
||
|
||
网关 SHALL 允许通过管理 API 创建新的供应商配置。
|
||
|
||
#### Scenario: 使用有效数据创建供应商
|
||
|
||
- **WHEN** 向 `/api/providers` 发送 POST 请求，携带有效的供应商数据（id, name, api_key, base_url）
|
||
- **THEN** 网关 SHALL 在数据库中创建新的供应商记录
|
||
- **THEN** 网关 SHALL 返回创建的供应商，状态码为 201
|
||
- **THEN** 供应商 SHALL 默认启用
|
||
|
||
#### Scenario: 使用重复 ID 创建供应商
|
||
|
||
- **WHEN** 向 `/api/providers` 发送 POST 请求，携带已存在的 ID
|
||
- **THEN** 网关 SHALL 返回错误，状态码为 409 (Conflict)
|
||
|
||
#### Scenario: 创建供应商时缺少必需字段
|
||
|
||
- **WHEN** 向 `/api/providers` 发送 POST 请求，缺少必需字段（id, name, api_key 或 base_url）
|
||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||
- **THEN** 错误 SHALL 指示缺少哪些字段
|
||
|
||
### Requirement: 列出所有供应商
|
||
|
||
网关 SHALL 允许获取所有供应商配置。
|
||
|
||
#### Scenario: 成功列出供应商
|
||
|
||
- **WHEN** 向 `/api/providers` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 返回所有供应商的列表
|
||
- **THEN** 每个供应商 SHALL 包含 id, name, api_key（已掩码）, base_url, enabled, created_at, updated_at
|
||
- **THEN** api_key SHALL 被掩码（仅显示最后 4 个字符）
|
||
|
||
#### Scenario: 列出供应商时为空
|
||
|
||
- **WHEN** 向 `/api/providers` 发送 GET 请求，且不存在供应商
|
||
- **THEN** 网关 SHALL 返回空列表
|
||
|
||
### Requirement: 获取特定供应商
|
||
|
||
网关 SHALL 允许通过 ID 获取特定供应商。
|
||
|
||
#### Scenario: 获取存在的供应商
|
||
|
||
- **WHEN** 向 `/api/providers/:id` 发送 GET 请求，携带有效的供应商 ID
|
||
- **THEN** 网关 SHALL 返回供应商详情
|
||
- **THEN** api_key SHALL 被掩码
|
||
|
||
#### Scenario: 获取不存在的供应商
|
||
|
||
- **WHEN** 向 `/api/providers/:id` 发送 GET 请求，携带不存在的 ID
|
||
- **THEN** 网关 SHALL 返回错误，状态码为 404 (Not Found)
|
||
|
||
### Requirement: 更新供应商配置
|
||
|
||
网关 SHALL 允许更新现有供应商配置。
|
||
|
||
#### Scenario: 使用有效数据更新供应商
|
||
|
||
- **WHEN** 向 `/api/providers/:id` 发送 PUT 请求，携带有效的供应商数据
|
||
- **THEN** 网关 SHALL 更新数据库中的供应商记录
|
||
- **THEN** 网关 SHALL 返回更新后的供应商
|
||
- **THEN** updated_at 时间戳 SHALL 被更新
|
||
|
||
#### Scenario: 更新不存在的供应商
|
||
|
||
- **WHEN** 向 `/api/providers/:id` 发送 PUT 请求，携带不存在的 ID
|
||
- **THEN** 网关 SHALL 返回错误，状态码为 404 (Not Found)
|
||
|
||
#### Scenario: 部分更新
|
||
|
||
- **WHEN** 向 `/api/providers/:id` 发送 PUT 请求，仅包含部分字段
|
||
- **THEN** 网关 SHALL 仅更新提供的字段
|
||
- **THEN** 网关 SHALL 保留未更改的字段
|
||
|
||
### Requirement: 删除供应商配置
|
||
|
||
网关 SHALL 允许删除供应商配置。
|
||
|
||
#### Scenario: 删除存在的供应商
|
||
|
||
- **WHEN** 向 `/api/providers/:id` 发送 DELETE 请求，携带有效的供应商 ID
|
||
- **THEN** 网关 SHALL 删除供应商记录
|
||
- **THEN** 网关 SHALL 删除所有关联的模型（CASCADE）
|
||
- **THEN** 网关 SHALL 返回状态码 204 (No Content)
|
||
|
||
#### Scenario: 删除不存在的供应商
|
||
|
||
- **WHEN** 向 `/api/providers/:id` 发送 DELETE 请求，携带不存在的 ID
|
||
- **THEN** 网关 SHALL 返回错误，状态码为 404 (Not Found)
|
||
|
||
### Requirement: 启用和禁用供应商
|
||
|
||
网关 SHALL 支持启用和禁用供应商。
|
||
|
||
#### Scenario: 禁用供应商
|
||
|
||
- **WHEN** 供应商的 `enabled` 字段设置为 false
|
||
- **THEN** 网关 SHALL 不向该供应商路由请求
|
||
- **THEN** 供应商 SHALL 保留在数据库中
|
||
|
||
#### Scenario: 启用供应商
|
||
|
||
- **WHEN** 已禁用供应商的 `enabled` 字段设置为 true
|
||
- **THEN** 网关 SHALL 恢复向该供应商路由请求
|
||
|
||
### Requirement: 验证供应商配置
|
||
|
||
网关 SHALL 验证供应商配置数据。
|
||
|
||
#### Scenario: 验证 base_url 格式
|
||
|
||
- **WHEN** 创建或更新供应商时使用无效的 base_url 格式
|
||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||
|
||
#### Scenario: 验证必需字段
|
||
|
||
- **WHEN** 创建或更新供应商
|
||
- **THEN** 网关 SHALL 验证 id, name, api_key 和 base_url 存在且非空
|
||
|
||
### Requirement: 安全存储供应商配置
|
||
|
||
网关 SHALL 安全存储供应商 API Key。
|
||
|
||
#### Scenario: 存储 API Key
|
||
|
||
- **WHEN** 创建或更新供应商时携带 API Key
|
||
- **THEN** 网关 SHALL 将 API Key 存储在数据库中
|
||
|
||
#### Scenario: 在响应中掩码 API Key
|
||
|
||
- **WHEN** 在 API 响应中返回供应商数据
|
||
- **THEN** API Key SHALL 被掩码（仅显示最后 4 个字符）
|
||
|
||
### Requirement: 仅支持 OpenAI 兼容供应商
|
||
|
||
网关 SHALL 在 MVP 中仅支持 OpenAI 兼容供应商。
|
||
|
||
#### Scenario: 供应商类型验证
|
||
|
||
- **WHEN** 创建供应商
|
||
- **THEN** 供应商类型 SHALL 隐式设置为 "openai-compatible"
|
||
- **THEN** MVP 中 SHALL 不支持其他供应商类型
|