nex/openspec/changes/unified-model-id/specs/model-management/spec.md

MODIFIED Requirements

Requirement: 创建模型配置

网关 SHALL 允许为供应商创建新的模型配置。

Scenario: 使用有效数据创建模型

• WHEN 向 /api/models 发送 POST 请求，携带有效的模型数据（provider_id, model_name），不提供 id 字段
• THEN 网关 SHALL 自动生成 UUID 作为模型 id
• THEN 网关 SHALL 在数据库中创建新的模型记录
• THEN 网关 SHALL 返回创建的模型，状态码为 201
• THEN 模型 SHALL 默认启用
• THEN 返回的模型 SHALL 包含 unified_id 字段，值为 {provider_id}/{model_name}

Scenario: 使用不存在的供应商创建模型

• WHEN 向 /api/models 发送 POST 请求，携带不存在的 provider_id
• THEN 网关 SHALL 返回错误，状态码为 400 (Bad Request)
• THEN 错误 SHALL 指示供应商不存在

Scenario: 创建重复模型

• WHEN 向 /api/models 发送 POST 请求，携带已存在的 provider_id + model_name 组合
• THEN 网关 SHALL 返回错误，状态码为 409 (Conflict)
• THEN 错误 SHALL 指示该供应商下已存在相同模型

Requirement: 列出所有模型

网关 SHALL 允许获取所有模型配置。

Scenario: 成功列出模型

• WHEN 向 /api/models 发送 GET 请求
• THEN 网关 SHALL 返回所有模型的列表
• THEN 每个模型 SHALL 包含 id, provider_id, model_name, unified_id, enabled, created_at

变更说明： 响应新增 unified_id 字段，移除旧语义的 id 自定义输入。

Requirement: 按供应商列出模型

网关 SHALL 允许获取特定供应商的模型。

Scenario: 列出存在供应商的模型

• WHEN 向 /api/models?provider_id=<provider_id> 发送 GET 请求
• THEN 网关 SHALL 返回指定供应商的模型列表
• THEN 每个模型 SHALL 包含 unified_id 字段

Requirement: 更新模型配置

网关 SHALL 允许更新现有模型配置。

Scenario: 使用有效数据更新模型

• WHEN 向 /api/models/:id 发送 PUT 请求，携带有效的模型数据
• THEN 网关 SHALL 更新数据库中的模型记录
• THEN 网关 SHALL 返回更新后的模型
• THEN 返回的模型 SHALL 包含更新后的 unified_id

Scenario: 更新模型为重复组合

• WHEN 向 /api/models/:id 发送 PUT 请求，更新 provider_id 或 model_name 导致与已有记录重复
• THEN 网关 SHALL 返回错误，状态码为 409 (Conflict)

Requirement: 删除模型配置

网关 SHALL 允许删除模型配置。

Scenario: 删除存在的模型

• WHEN 向 /api/models/:id 发送 DELETE 请求，携带有效的模型 ID
• THEN 网关 SHALL 删除模型记录
• THEN 网关 SHALL 返回状态码 204 (No Content)

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

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

Scenario: 调用 service 方法

• WHEN handler 收到请求
• THEN SHALL 调用对应的 ModelService 方法（Create、Get、List、Update、Delete）
• THEN SHALL 使用 domain.Model 类型
• THEN Create 时 SHALL 调用 uuid.New() 生成 id

Scenario: 供应商验证和唯一性校验

• WHEN 创建或更新模型
• THEN SHALL 在 service 层验证供应商存在
• THEN SHALL 在 service 层验证 provider_id + model_name 联合唯一

Requirement: 使用 repository 层访问数据

Service SHALL 通过 ModelRepository 访问数据。

Scenario: 联合查询

• WHEN service 需要按 provider 和 model_name 查询模型
• THEN SHALL 调用 FindByProviderAndModelName(providerID, modelName) 方法

Scenario: 查询所有启用模型

• WHEN proxy handler 需要聚合模型列表
• THEN SHALL 调用 ListEnabled() 方法，返回所有 enabled 的模型（关联 enabled 的供应商）