lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
master
nex/openspec/specs/provider-management/spec.md
lanyuanxiaoyao 56ecc73d1b docs: 整合 openspec 规范，合并配置和前端相关独立 spec 
将 cli-config、config-priority、env-config 合并入 config-management；
将 tdesign-integration、recharts-integration、frontend-config-ui、
frontend-testing、stats-dashboard 合并入新的 frontend/spec.md；
清理其余 spec 中的冗余标记，补充缺失场景。
2026-04-20 19:55:56 +08:00

4.4 KiB
Raw Permalink Blame History

Provider Management

Purpose

管理 AI 供应商的完整生命周期，包括创建、查询、更新、删除供应商配置，通过分层架构（Handler -> Service -> Repository）处理业务逻辑和数据访问。

Requirements

Requirement: 创建供应商配置

网关 SHALL 允许通过管理 API 创建新的供应商配置。

Scenario: 使用有效数据创建供应商

  • WHEN 向 /api/providers 发送 POST 请求，携带有效的供应商数据（id, name, api_key, base_url, protocol）
  • THEN 网关 SHALL 在数据库中创建新的供应商记录
  • THEN 网关 SHALL 返回创建的供应商，状态码为 201
  • THEN 供应商 SHALL 默认启用
  • THEN protocol 字段 SHALL 默认为 "openai"

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 指示缺少哪些字段

变更说明： handler 通过 ProviderService 调用，数据访问通过 ProviderRepository。API 接口保持不变。

Requirement: 列出所有供应商

网关 SHALL 允许获取所有供应商配置。

Scenario: 成功列出供应商

  • WHEN 向 /api/providers 发送 GET 请求
  • THEN 网关 SHALL 返回所有供应商的列表
  • THEN 每个供应商 SHALL 包含 id, name, api_key（已掩码）, base_url, protocol, enabled, created_at, updated_at
  • THEN api_key SHALL 被掩码（仅显示最后 4 个字符）

变更说明： 数据访问从 config 包迁移到 ProviderRepository。API 接口保持不变。

Requirement: 获取特定供应商

网关 SHALL 允许通过 ID 获取特定供应商。

Scenario: 获取存在的供应商

  • WHEN 向 /api/providers/:id 发送 GET 请求，携带有效的供应商 ID
  • THEN 网关 SHALL 返回供应商详情
  • THEN SHALL 包含 protocol 字段
  • THEN api_key SHALL 被掩码

Scenario: 获取不存在的供应商

  • WHEN 向 /api/providers/:id 发送 GET 请求，携带不存在的 ID
  • THEN 网关 SHALL 返回错误，状态码为 404 (Not Found)

变更说明： 通过 ProviderService 和 ProviderRepository 实现。API 接口保持不变。

Requirement: 更新供应商配置

网关 SHALL 允许更新现有供应商配置。

Scenario: 使用有效数据更新供应商

  • WHEN 向 /api/providers/:id 发送 PUT 请求，携带有效的供应商数据
  • THEN 网关 SHALL 更新数据库中的供应商记录
  • THEN 网关 SHALL 返回更新后的供应商
  • THEN 更新 SHALL 支持修改 protocol 字段

变更说明： 通过 ProviderService 和 ProviderRepository 实现。API 接口保持不变。

Requirement: 删除供应商配置

网关 SHALL 允许删除供应商配置。

Scenario: 删除存在的供应商

  • WHEN 向 /api/providers/:id 发送 DELETE 请求，携带有效的供应商 ID
  • THEN 网关 SHALL 删除供应商记录
  • THEN 网关 SHALL 删除所有关联的模型（CASCADE）
  • THEN 网关 SHALL 返回状态码 204 (No Content)

变更说明： 通过 ProviderService 和 ProviderRepository 实现。API 接口保持不变。

Requirement: 使用 service 层处理业务逻辑

Handler SHALL 通过 ProviderService 处理业务逻辑。

Scenario: 调用 service 方法

  • WHEN handler 收到请求
  • THEN SHALL 调用对应的 ProviderService 方法（Create、Get、List、Update、Delete）
  • THEN SHALL 使用 domain.Provider 类型

Scenario: 错误处理

  • WHEN service 返回错误
  • THEN SHALL 转换为 HTTP 错误响应
  • THEN SHALL 使用结构化错误处理

Requirement: 使用 repository 层访问数据

Service SHALL 通过 ProviderRepository 访问数据。

Scenario: 调用 repository 方法

  • WHEN service 处理业务逻辑
  • THEN SHALL 调用对应的 ProviderRepository 方法
  • THEN SHALL 使用 domain.Provider 类型

Scenario: 数据验证

  • WHEN 创建或更新供应商
  • THEN SHALL 在 service 层验证业务规则
  • THEN SHALL 在 repository 层执行数据库操作
View Git Blame Copy Permalink