lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
b92974716f621909b26d94623da601bba1afa2b8
nex/openspec/specs/database-migration/spec.md
lanyuanxiaoyao f18904af1e feat: 实现分层架构，包含 domain、service、repository 和 pkg 层 
- 新增 domain 层：model、provider、route、stats 实体
- 新增 service 层：models、providers、routing、stats 业务逻辑
- 新增 repository 层：models、providers、stats 数据访问
- 新增 pkg 工具包：errors、logger、validator
- 新增中间件：CORS、logging、recovery、request ID
- 新增数据库迁移：初始 schema 和索引
- 新增单元测试和集成测试
- 新增规范文档：config-management、database-migration、error-handling、layered-architecture、middleware-system、request-validation、structured-logging、test-coverage
- 移除 config 子包和 model_router（已迁移至分层架构）
2026-04-16 00:47:20 +08:00

3.9 KiB
Raw Blame History

Database Migration

ADDED Requirements

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 创建 001_initial_schema.sql
  • THEN SHALL 包含 providers、models、usage_stats 表的创建语句
  • THEN SHALL 包含外键约束

Scenario: Up 迁移

  • WHEN 执行 up 迁移
  • THEN SHALL 创建所有表
  • THEN SHALL 创建索引
  • THEN SHALL 创建外键约束

Scenario: Down 迁移

  • WHEN 执行 down 迁移
  • THEN SHALL 删除所有表
  • THEN SHALL 按正确顺序删除（避免外键约束错误）

Requirement: 添加索引迁移

系统 SHALL 创建索引迁移。

Scenario: 索引迁移文件

  • WHEN 创建索引迁移
  • THEN SHALL 创建 002_add_indexes.sql
  • THEN SHALL 为常用查询字段添加索引

Scenario: 索引定义

  • WHEN 添加索引
  • THEN SHALL 为 models(provider_id) 添加索引
  • THEN SHALL 为 models(model_name) 添加索引
  • THEN SHALL 为 usage_stats(provider_id, model_name, date) 添加复合索引

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 提交到版本控制系统
View Git Blame Copy Permalink