nex/openspec/changes/unified-model-id/tasks.md

1. 数据库迁移

• 1.1 新增迁移脚本：DROP 旧 models 表 + CREATE 新 models 表（id UUID PK, provider_id, model_name, enabled, created_at），UNIQUE(provider_id, model_name)
• 1.2 更新 config/models.go：Model 结构体适配（id 改为 UUID 自动生成，model_name 保持不变）
• 1.3 编写迁移脚本测试

2. 统一模型 ID 工具包

• 2.1 新增 pkg/modelid/model_id.go：实现 ParseUnifiedModelID、FormatUnifiedModelID、ValidateProviderID、IsValidUnifiedModelID
• 2.2 新增 pkg/modelid/model_id_test.go：覆盖标准格式、含斜杠 model_name、空字符串、非法字符等边界情况

3. Domain 层适配

• 3.1 修改 domain/model.go：Model 结构体字段适配，新增 UnifiedModelID() 方法
• 3.2 修改 domain/route.go：RouteResult 适配新字段

4. Repository 层适配

• 4.1 修改 repository/model_repo.go：接口变更 — GetByModelName 改为 FindByProviderAndModelName，新增 ListEnabled
• 4.2 修改 repository/model_repo_impl.go：实现 FindByProviderAndModelName（WHERE provider_id=? AND model_name=?）、ListEnabled（JOIN providers WHERE enabled）
• 4.3 编写 repository 层测试

5. Service 层适配

• 5.1 修改 service/routing_service.go：Route 接口改为 RouteByModelName(providerID, modelName string)
• 5.2 修改 service/routing_service_impl.go：调用 FindByProviderAndModelName 替代 GetByModelName
• 5.3 修改 service/model_service.go：Create 生成 UUID、新增联合唯一校验方法
• 5.4 修改 service/model_service_impl.go：实现联合唯一校验、UUID 生成
• 5.5 修改 service/provider_service_impl.go：Create 时调用 ValidateProviderID 校验 ID 字符集
• 5.6 编写 service 层测试

6. Conversion 层适配

• 6.1 修改 conversion/adapter.go：ProtocolAdapter 接口新增 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName 四个方法
• 6.2 修改 conversion/engine.go：ConvertHttpResponse 新增 modelOverride 参数（跨协议场景），各 convert*ResponseBody 中覆写 canonical Model；CreateStreamConverter 新增 modelOverride 参数
• 6.3 修改 conversion/openai/adapter.go：实现 ExtractUnifiedModelID、ExtractModelName（按 ifaceType 提取 model）、RewriteRequestModelName 和 RewriteResponseModelName（json.RawMessage 最小化改写，按 ifaceType 定位 model 字段，请求/响应独立实现），修改 isModelInfoPath 允许 suffix 含 "/"
• 6.4 修改 conversion/anthropic/adapter.go：实现 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName，修改 isModelInfoPath 允许 suffix 含 "/"
• 6.5 编写 conversion 层测试：ExtractUnifiedModelID、ExtractModelName 各 ifaceType、RewriteRequestModelName/RewriteResponseModelName 保真性（含未知参数不丢失）、isModelInfoPath 含斜杠路径、modelOverride 覆写

7. Handler 层改造

• 7.1 修改 handler/proxy_handler.go：HandleProxy 按接口类型分发 — Models/ModelInfo 本地聚合；Chat/Embed/Rerank 用 adapter.ExtractModelName 提取统一 ID 路由，同协议走 Smart Passthrough（adapter.RewriteRequestModelName 改写请求、adapter.RewriteResponseModelName 改写响应），跨协议走全量转换（modelOverride）；删除 forwardPassthrough 和硬编码的 extractModelName
• 7.2 修改 handler/model_handler.go：请求体字段适配（移除 id 输入、保留 provider_id 和 model_name），响应新增 unified_id，Create 使用 UUID
• 7.3 修改 handler/provider_handler.go：CreateProvider 校验 ID 字符集
• 7.4 编写 handler 层测试：统一模型 ID 路由、同协议 Smart Passthrough 保真性、跨协议 modelOverride、Models 聚合、ModelInfo 查询、流式场景 model 覆写、provider ID 校验

8. 路由注册适配

• 8.1 修改 cmd/server/main.go：setupRoutes 适配 handler 签名变更，传递新增依赖

9. 文档更新

• 9.1 按需更新 README.md：同步 models 表结构、API 接口字段、统一模型 ID 格式、Smart Passthrough 策略等变更说明