test: 后端测试从 SQLite 全面切换到 MySQL，与生产环境对齐

测试库不再使用 SQLite 内存库，改为每个测试包独立的 MySQL 库，表结构由 backend/migrations 的真实迁移建立。基础设施 - 新增 internal/database/testdb.go：NewTestDB() 保持原签名（28 处调用零改动），内部连接 MySQL 测试库，首次调用重建库并执行全部真实迁移，之后每次调用清空全表 - 库名 = 测试库基础名 + 包目录名，同包共享、跨包隔离，使 go test ./... 可并发执行（共用一库时各包会互相 DROP/CREATE 导致 database exists） - 新增 NewDryRunDB()：MySQL 方言 + DryRun，供断言 SQL 形态的 5 处测试使用 - 新增 AutoMigrateIfMissing()：只对不存在的表 AutoMigrate，避免改动迁移定义的索引与约束 - 新增 scripts/prepare-test-db.sh：建库与通配授权，可重复执行 - 33 处 sqlite.Open 全部替换，26 个测试文件改用 MySQL - 删除 46 处手写 SQLite 方言 DDL（AUTOINCREMENT / INTEGER PRIMARY KEY / TEXT），表统一由真实迁移建立 - go.mod 移除 gorm.io/driver/sqlite 与 mattn/go-sqlite3 - 删除生产代码里 distribution/repository.go 的 sqlite 方言分支（strftime）对齐环境后暴露并修复的真实问题 - DATE(col) 在 MySQL 返回 DATE 类型，使 Date string 字段变成 RFC3339 时间串，大盘日期会带出时间部分；28 处改为 DATE_FORMAT(col, '%Y-%m-%d') - 系统自动创建分销结算批次时 created_by 写入 0，违反指向 admin_users 的外键，生产会直接插入失败；改为写 NULL（新增 adminRef helper） - MySQL DATETIME 仅到秒，静默截断 Go 侧写入的时间，导致租用时长计算与结算时点回读比对偏差； rental_orders 的 9 个业务时间列提到 DATETIME(6) - 测试数据补齐严格模式要求的 NOT NULL 列、修正超出列长的取值、补齐外键父记录迁移 - 000065 的 ALTER TABLE rental_orders 一并完成业务时间列精度调整， feature 侧不再单开迁移文件脚本与文档 - check.sh / check-backend-coverage.sh 去掉 -p 1 串行与 SQLite 相关注释 - 更新 docs/Repository层测试补充总结.md 的测试运行说明
2026-09-10 14:34:01 +08:00
parent 2b8c74a0f1
commit cbd5412315
72 changed files with 933 additions and 1002 deletions
@@ -0,0 +1,251 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strings"
+	"sync"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// DefaultTestDSN 指向本地 Docker 开发环境的 MySQL 测试库。
+// 可通过 HFB_TEST_DSN 覆盖，库名必须包含 test 或 e2e。
+const DefaultTestDSN = "hfb:secret@tcp(127.0.0.1:13306)/hfb_sys_test?charset=utf8mb4&parseTime=True&loc=Local"
+
+var (
+	testPrepareOnce sync.Once
+	testConn        *gorm.DB
+	testPrepareErr  error
+)
+
+// NewTestDB 返回指向 MySQL 测试库的干净连接。
+//
+// 首次调用会重建测试库并执行 backend/migrations 下的真实迁移，
+// 因此测试用的表结构与生产完全一致；之后每次调用清空全部表，
+// 使每个测试都从空库开始。
+func NewTestDB() *gorm.DB {
+	db, err := sharedTestDB()
+	if err != nil {
+		panic(fmt.Sprintf("初始化 MySQL 测试库失败: %v", err))
+	}
+	if err := truncateAllTables(db); err != nil {
+		panic(fmt.Sprintf("清空 MySQL 测试库失败: %v", err))
+	}
+	return db
+}
+
+func sharedTestDB() (*gorm.DB, error) {
+	testPrepareOnce.Do(func() {
+		testConn, testPrepareErr = openTestDatabase()
+	})
+	return testConn, testPrepareErr
+}
+
+// NewDryRunDB 返回 MySQL 方言的 DryRun 连接：只生成 SQL 不执行，也无需数据库运行。
+// 用于断言查询语句形态的测试。
+func NewDryRunDB() *gorm.DB {
+	db, err := gorm.Open(mysql.New(mysql.Config{
+		DSN:                       DefaultTestDSN,
+		SkipInitializeWithVersion: true,
+	}), &gorm.Config{
+		DryRun:               true,
+		DisableAutomaticPing: true,
+		Logger:               logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		panic(fmt.Sprintf("初始化 MySQL DryRun 连接失败: %v", err))
+	}
+	return db
+}
+
+// AutoMigrateIfMissing 只对尚不存在的表执行 AutoMigrate。
+//
+// 测试库的表结构由 migrations 建立，直接 AutoMigrate 会去改迁移定义的
+// 索引与约束（例如 DROP 掉被外键依赖的唯一索引），因此已存在的表一律跳过，
+// 仅保留给测试专用的临时表使用。
+func AutoMigrateIfMissing(db *gorm.DB, models ...any) error {
+	for _, target := range models {
+		if db.Migrator().HasTable(target) {
+			continue
+		}
+		if err := db.AutoMigrate(target); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func openTestDatabase() (*gorm.DB, error) {
+	dsn := strings.TrimSpace(os.Getenv("HFB_TEST_DSN"))
+	if dsn == "" {
+		dsn = DefaultTestDSN
+	}
+	cfg, err := mysqldriver.ParseDSN(dsn)
+	if err != nil {
+		return nil, fmt.Errorf("解析测试库 DSN 失败: %w", err)
+	}
+	// 每个测试包使用独立库，避免 go test ./... 并发时互相重建同一个库。
+	cfg.DBName = cfg.DBName + "_" + packageSuffix()
+	if err := assertTestDatabaseName(cfg.DBName); err != nil {
+		return nil, err
+	}
+
+	// 重建空库，保证表结构只来自 migrations。
+	serverCfg := cfg.Clone()
+	serverCfg.DBName = ""
+	serverCfg.MultiStatements = false
+	serverDB, err := sql.Open("mysql", serverCfg.FormatDSN())
+	if err != nil {
+		return nil, fmt.Errorf("连接 MySQL 服务失败: %w", err)
+	}
+	defer func() { _ = serverDB.Close() }()
+	if _, err := serverDB.Exec("DROP DATABASE IF EXISTS `" + cfg.DBName + "`"); err != nil {
+		return nil, fmt.Errorf("删除测试库失败: %w", err)
+	}
+	if _, err := serverDB.Exec("CREATE DATABASE `" + cfg.DBName + "` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"); err != nil {
+		return nil, fmt.Errorf("创建测试库失败: %w", err)
+	}
+
+	cfg.ParseTime = true
+	cfg.MultiStatements = true
+	sqlDB, err := sql.Open("mysql", cfg.FormatDSN())
+	if err != nil {
+		return nil, fmt.Errorf("连接测试库失败: %w", err)
+	}
+	if err := applyMigrations(sqlDB); err != nil {
+		_ = sqlDB.Close()
+		return nil, err
+	}
+	gormDB, err := gorm.Open(mysql.New(mysql.Config{Conn: sqlDB}), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		_ = sqlDB.Close()
+		return nil, fmt.Errorf("打开 gorm 连接失败: %w", err)
+	}
+	return gormDB, nil
+}
+
+// assertTestDatabaseName 拒绝重置非测试库，避免误删生产数据。
+func assertTestDatabaseName(name string) error {
+	if name == "" {
+		return errors.New("测试库 DSN 必须包含数据库名")
+	}
+	if !regexp.MustCompile(`^[A-Za-z0-9_]+$`).MatchString(name) {
+		return fmt.Errorf("测试库名只允许字母、数字、下划线: %q", name)
+	}
+	if len(name) > 64 {
+		return fmt.Errorf("测试库名超过 MySQL 上限 64 字符: %q", name)
+	}
+	lower := strings.ToLower(name)
+	if !strings.Contains(lower, "test") && !strings.Contains(lower, "e2e") {
+		return fmt.Errorf("拒绝重置非测试库 %q，库名需包含 test 或 e2e", name)
+	}
+	return nil
+}
+
+// packageSuffix 用当前测试进程的工作目录名（即被测包目录）作为库名后缀。
+// go test 会把工作目录设为包的源目录，因此同包共享一个库、不同包互相隔离。
+func packageSuffix() string {
+	wd, err := os.Getwd()
+	if err != nil {
+		return "unknown"
+	}
+	suffix := regexp.MustCompile(`[^A-Za-z0-9_]`).ReplaceAllString(filepath.Base(wd), "_")
+	if suffix == "" {
+		return "unknown"
+	}
+	return suffix
+}
+
+func migrationDir() (string, error) {
+	_, currentFile, _, ok := runtime.Caller(0)
+	if !ok {
+		return "", errors.New("无法定位 database 包路径")
+	}
+	return filepath.Join(filepath.Dir(currentFile), "..", "..", "migrations"), nil
+}
+
+func applyMigrations(db *sql.DB) error {
+	dir, err := migrationDir()
+	if err != nil {
+		return err
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return fmt.Errorf("读取迁移目录失败: %w", err)
+	}
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".sql") {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+		if err != nil {
+			return fmt.Errorf("读取迁移 %s 失败: %w", entry.Name(), err)
+		}
+		if _, err := db.Exec(gooseUpSQL(string(raw))); err != nil {
+			return fmt.Errorf("执行迁移 %s 失败: %w", entry.Name(), err)
+		}
+	}
+	return nil
+}
+
+// gooseUpSQL 截取 goose 迁移文件的 Up 段，Down 段与 goose 指令行原样保留，
+// 后者在 MySQL 中属于注释，不影响执行。
+func gooseUpSQL(raw string) string {
+	if i := strings.Index(raw, "-- +goose Up"); i >= 0 {
+		raw = raw[i+len("-- +goose Up"):]
+	}
+	if i := strings.Index(raw, "-- +goose Down"); i >= 0 {
+		raw = raw[:i]
+	}
+	return raw
+}
+
+// truncateAllTables 清空测试库中的全部基础表，使每个测试从空库开始。
+func truncateAllTables(db *gorm.DB) error {
+	var tables []string
+	if err := db.Raw(
+		"SELECT table_name FROM information_schema.tables " +
+			"WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'",
+	).Scan(&tables).Error; err != nil {
+		return err
+	}
+	if len(tables) == 0 {
+		return nil
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return err
+	}
+	ctx := context.Background()
+	// 固定单连接，保证 FOREIGN_KEY_CHECKS 的会话变量对后续 TRUNCATE 生效。
+	conn, err := sqlDB.Conn(ctx)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = conn.Close() }()
+
+	if _, err := conn.ExecContext(ctx, "SET FOREIGN_KEY_CHECKS = 0"); err != nil {
+		return err
+	}
+	defer func() { _, _ = conn.ExecContext(ctx, "SET FOREIGN_KEY_CHECKS = 1") }()
+
+	for _, table := range tables {
+		if _, err := conn.ExecContext(ctx, "TRUNCATE TABLE `"+table+"`"); err != nil {
+			return fmt.Errorf("清空表 %s 失败: %w", table, err)
+		}
+	}
+	return nil
+}