nex/openspec/specs/mysql-driver/spec.md

MySQL Driver

Purpose

支持 MySQL 作为可选数据库后端，通过配置选择 sqlite 或 mysql 驱动，提供 MySQL 连接管理、初始化和方言迁移文件。

Requirements

Requirement: MySQL 数据库驱动支持

系统 SHALL 支持通过配置项 database.driver 选择 sqlite 或 mysql 数据库驱动，默认值为 sqlite。

Scenario: 默认使用 SQLite 驱动

• WHEN 配置中未指定 database.driver
• THEN SHALL 使用 sqlite 作为数据库驱动
• THEN SHALL 行为与现有逻辑完全一致

Scenario: 配置 MySQL 驱动

• WHEN 配置 database.driver 设置为 mysql
• THEN SHALL 使用 MySQL 驱动连接远程数据库
• THEN SHALL 使用 gorm.io/driver/mysql 打开连接
• THEN SHALL 构建 DSN 格式为 {user}:{password}@tcp({host}:{port})/{dbname}?charset=utf8mb4&parseTime=true&loc=Local

Scenario: driver 值不合法

• WHEN 配置 database.driver 不是 sqlite 或 mysql
• THEN SHALL 配置验证失败，拒绝启动

Requirement: MySQL 连接配置

系统 SHALL 在 DatabaseConfig 中支持 MySQL 连接参数。

Scenario: MySQL 连接参数字段

• WHEN database.driver 为 mysql
• THEN SHALL 读取 host（MySQL 主机地址，必填）
• THEN SHALL 读取 port（MySQL 端口，默认 3306）
• THEN SHALL 读取 user（MySQL 用户名，必填）
• THEN SHALL 读取 password（MySQL 密码，选填）
• THEN SHALL 读取 dbname（数据库名，必填）

Scenario: SQLite 模式忽略 MySQL 参数

• WHEN database.driver 为 sqlite
• THEN SHALL 忽略 MySQL 相关配置字段（host/port/user/password/dbname）
• THEN SHALL 仅使用 path 字段作为数据库文件路径

Scenario: MySQL 模式忽略 SQLite 参数

• WHEN database.driver 为 mysql
• THEN SHALL 忽略 path 字段

Requirement: 数据库初始化公共包

系统 SHALL 提供 internal/database 公共包，封装数据库初始化、迁移执行和连接关闭逻辑，供 cmd/server 和 cmd/desktop 共同调用。

Scenario: 公共包 Init 函数

• WHEN 调用 database.Init(cfg, logger)
• THEN SHALL 根据 cfg.Driver 选择对应的 GORM 驱动打开连接
• THEN SHALL 执行对应方言的 goose 迁移
• THEN SHALL 配置连接池参数
• THEN SHALL 在 driver=sqlite 时执行 PRAGMA journal_mode=WAL
• THEN SHALL 在 driver=mysql 时跳过 SQLite 专有 PRAGMA
• THEN SHALL 返回 *gorm.DB 实例

Scenario: 公共包 Close 函数

• WHEN 调用 database.Close(db)
• THEN SHALL 获取底层 sql.DB 并关闭连接

Scenario: 迁移目录选择

• WHEN 执行迁移
• THEN SHALL 在 driver=sqlite 时使用 migrations/sqlite/ 目录，goose dialect 为 sqlite3
• THEN SHALL 在 driver=mysql 时使用 migrations/mysql/ 目录，goose dialect 为 mysql

Requirement: MySQL 方言迁移文件

系统 SHALL 提供 MySQL 方言的初始迁移文件 migrations/mysql/20260421000001_initial_schema.sql。

Scenario: providers 表

• WHEN 执行 MySQL 初始迁移
• THEN SHALL 创建 providers 表，字段：id VARCHAR(36) PRIMARY KEY、name VARCHAR(255) NOT NULL、api_key VARCHAR(255) NOT NULL、base_url VARCHAR(255) NOT NULL、protocol VARCHAR(50) DEFAULT 'openai'、enabled BOOLEAN DEFAULT TRUE、created_at DATETIME(3)、updated_at DATETIME(3)

Scenario: models 表

• WHEN 执行 MySQL 初始迁移
• THEN SHALL 创建 models 表，字段：id VARCHAR(36) PRIMARY KEY、provider_id VARCHAR(36) NOT NULL、model_name VARCHAR(255) NOT NULL、enabled BOOLEAN DEFAULT TRUE、created_at DATETIME(3)
• THEN SHALL 创建 UNIQUE(provider_id, model_name) 约束
• THEN SHALL 创建 FOREIGN KEY (provider_id) REFERENCES providers(id) ON DELETE CASCADE 约束
• THEN SHALL 创建 idx_models_provider_id 和 idx_models_model_name 索引

Scenario: usage_stats 表

• WHEN 执行 MySQL 初始迁移
• THEN SHALL 创建 usage_stats 表，字段：id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY、provider_id VARCHAR(36) NOT NULL、model_name VARCHAR(255) NOT NULL、request_count INT DEFAULT 0、date DATE NOT NULL
• THEN SHALL 创建 UNIQUE(provider_id, model_name, date) 约束
• THEN SHALL 创建 idx_usage_stats_provider_model_date 复合索引

Scenario: Down 迁移

• WHEN 执行 MySQL down 迁移
• THEN SHALL 按正确顺序删除索引和表（usage_stats → models → providers）