lanyuanxiaoyao
395887667d
实现统一模型 ID 格式 (provider_id/model_name)，支持跨协议模型标识和 Smart Passthrough。 核心变更： - 新增 pkg/modelid 包：解析、格式化、校验统一模型 ID - 数据库迁移：models 表使用 UUID 主键 + UNIQUE(provider_id, model_name) 约束 - Repository 层：FindByProviderAndModelName、ListEnabled 方法 - Service 层：联合唯一校验、provider ID 字符集校验 - Conversion 层：ExtractModelName、RewriteRequestModelName/RewriteResponseModelName 方法 - Handler 层：统一模型 ID 路由、Smart Passthrough、Models API 本地聚合 - 新增 error-responses、unified-model-id 规范 测试覆盖： - 单元测试：modelid、conversion、handler、service、repository - 集成测试：统一模型 ID 路由、Smart Passthrough 保真性、跨协议转换 - 迁移测试：UUID 主键、UNIQUE 约束、级联删除 OpenSpec： - 归档 unified-model-id 变更到 archive/2026-04-21-unified-model-id - 同步 11 个 delta specs 到 main specs - 新增 error-responses、unified-model-id 规范文件
154 lines
4.3 KiB
Markdown
154 lines
4.3 KiB
Markdown
# Database Migration
|
||
|
||
## Purpose
|
||
|
||
使用 goose 管理数据库迁移，支持自动执行、回滚和版本化管理。
|
||
|
||
### Requirement: 使用 goose 迁移工具
|
||
|
||
系统 SHALL 使用 goose 管理数据库迁移。
|
||
|
||
#### Scenario: goose 安装
|
||
|
||
- **WHEN** 开发环境设置
|
||
- **THEN** SHALL 安装 goose CLI 工具
|
||
- **THEN** SHALL 支持通过 CLI 执行迁移
|
||
|
||
#### Scenario: 迁移文件格式
|
||
|
||
- **WHEN** 创建迁移文件
|
||
- **THEN** SHALL 使用 SQL 格式（.sql 文件）
|
||
- **THEN** SHALL 包含 -- +goose Up 和 -- +goose Down 注释
|
||
- **THEN** SHALL 支持事务性迁移
|
||
|
||
### Requirement: 创建初始迁移
|
||
|
||
系统 SHALL 创建初始 schema 迁移。
|
||
|
||
#### Scenario: 初始迁移文件
|
||
|
||
- **WHEN** 创建初始迁移
|
||
- **THEN** SHALL 创建单个初始迁移文件（如 `20260421000001_initial_schema.sql`）
|
||
- **THEN** SHALL 包含 providers、models、usage_stats 表的创建语句
|
||
- **THEN** SHALL 包含外键约束
|
||
- **THEN** SHALL 包含索引创建语句
|
||
|
||
#### Scenario: Up 迁移
|
||
|
||
- **WHEN** 执行 up 迁移
|
||
- **THEN** SHALL 创建所有表
|
||
- **THEN** SHALL 创建索引
|
||
- **THEN** SHALL 创建外键约束
|
||
|
||
#### Scenario: Down 迁移
|
||
|
||
- **WHEN** 执行 down 迁移
|
||
- **THEN** SHALL 删除所有表和索引
|
||
- **THEN** SHALL 按正确顺序删除（避免外键约束错误）
|
||
|
||
### Requirement: models 表 schema 变更
|
||
|
||
系统 SHALL 在初始迁移脚本中直接创建新的 models 表结构（服务未上线，无需考虑数据迁移，迁移脚本已合并为单个初始迁移文件）。
|
||
|
||
#### Scenario: 初始迁移 models 表结构
|
||
|
||
- **WHEN** 执行迁移
|
||
- **THEN** SHALL CREATE models 表，包含字段：id（TEXT PRIMARY KEY，存储 UUID 字符串）、provider_id（TEXT NOT NULL）、model_name（TEXT NOT NULL）、enabled（INTEGER DEFAULT 1）、created_at（DATETIME）
|
||
- **THEN** SHALL 存在 UNIQUE(provider_id, model_name) 约束
|
||
- **THEN** SHALL 存在 FOREIGN KEY (provider_id) REFERENCES providers(id) ON DELETE CASCADE
|
||
|
||
### Requirement: 迁移命令集成
|
||
|
||
迁移 SHALL 集成到 Makefile。
|
||
|
||
#### Scenario: 迁移 up 命令
|
||
|
||
- **WHEN** 执行 `make migrate-up`
|
||
- **THEN** SHALL 执行所有待执行的迁移
|
||
- **THEN** SHALL 显示迁移进度
|
||
|
||
#### Scenario: 迁移 down 命令
|
||
|
||
- **WHEN** 执行 `make migrate-down`
|
||
- **THEN** SHALL 回滚最后一个迁移
|
||
- **THEN** SHALL 显示回滚进度
|
||
|
||
#### Scenario: 迁移状态命令
|
||
|
||
- **WHEN** 执行 `make migrate-status`
|
||
- **THEN** SHALL 显示当前迁移状态
|
||
- **THEN** SHALL 显示已执行和待执行的迁移
|
||
|
||
#### Scenario: 创建迁移命令
|
||
|
||
- **WHEN** 执行 `make migrate-create name=<name>`
|
||
- **THEN** SHALL 创建新的迁移文件模板
|
||
- **THEN** SHALL 使用递增的版本号
|
||
|
||
### Requirement: 应用启动时迁移
|
||
|
||
应用 SHALL 在启动时执行迁移。
|
||
|
||
#### Scenario: 自动迁移
|
||
|
||
- **WHEN** 应用启动
|
||
- **THEN** SHALL 自动执行待执行的迁移
|
||
- **THEN** SHALL 在迁移失败时拒绝启动
|
||
- **THEN** SHALL 记录迁移日志
|
||
|
||
#### Scenario: 迁移版本检查
|
||
|
||
- **WHEN** 应用启动
|
||
- **THEN** SHALL 检查数据库迁移版本
|
||
- **THEN** SHALL 在版本不匹配时执行迁移
|
||
|
||
### Requirement: 连接池配置
|
||
|
||
系统 SHALL 配置数据库连接池。
|
||
|
||
#### Scenario: 连接池参数
|
||
|
||
- **WHEN** 初始化数据库连接
|
||
- **THEN** SHALL 设置 MaxIdleConns（默认 10）
|
||
- **THEN** SHALL 设置 MaxOpenConns（默认 100）
|
||
- **THEN** SHALL 设置 ConnMaxLifetime（默认 1h）
|
||
|
||
#### Scenario: 连接池监控
|
||
|
||
- **WHEN** 应用运行
|
||
- **THEN** SHALL 定期记录连接池状态（可选）
|
||
- **THEN** SHALL 监控连接池使用情况
|
||
|
||
### Requirement: 迁移回滚支持
|
||
|
||
系统 SHALL 支持迁移回滚。
|
||
|
||
#### Scenario: 回滚到指定版本
|
||
|
||
- **WHEN** 执行 `goose down-to <version>`
|
||
- **THEN** SHALL 回滚到指定版本
|
||
- **THEN** SHALL 按顺序执行 down 迁移
|
||
|
||
#### Scenario: 完全回滚
|
||
|
||
- **WHEN** 执行 `goose reset`
|
||
- **THEN** SHALL 回滚所有迁移
|
||
- **THEN** SHALL 清空数据库
|
||
|
||
### Requirement: 迁移文件管理
|
||
|
||
迁移文件 SHALL 版本化管理。
|
||
|
||
#### Scenario: 迁移文件命名
|
||
|
||
- **WHEN** 创建迁移文件
|
||
- **THEN** SHALL 使用格式 `<version>_<name>.sql`
|
||
- **THEN** SHALL 版本号递增
|
||
- **THEN** SHALL 名称使用 snake_case
|
||
|
||
#### Scenario: 迁移文件存储
|
||
|
||
- **WHEN** 创建迁移文件
|
||
- **THEN** SHALL 存储在 migrations/ 目录
|
||
- **THEN** SHALL 提交到版本控制系统
|