engine

type MigrateState struct {
	ID         int64      `gorm:"column:id;primaryKey;autoIncrement"                      json:"id"`
	Migration  string     `gorm:"column:migration;not null;uniqueIndex:uk_migration_step" json:"migration"`   // 迁移标识，如 "v1.6.0-chapter-id-refactor"
	Step       string     `gorm:"column:step;not null;uniqueIndex:uk_migration_step"      json:"step"`        // 迁移内 step 标识（语义化 key，如 "1-crossref-data"）
	Status     string     `gorm:"column:status;not null;index"                            json:"status"`      // "running" | "done" | "failed"（未开始无行）
	StartedAt  *time.Time `gorm:"column:started_at"                                       json:"started_at"`  // 本 step 开始时间，nullable
	FinishedAt *time.Time `gorm:"column:finished_at"                                      json:"finished_at"` // 本 step 完成时间，nullable
	Error      string     `gorm:"column:error"                                            json:"error"`       // failed 时的错误信息
	CreatedAt  time.Time  `gorm:"column:created_at;autoCreateTime"                        json:"created_at"`
	UpdatedAt  time.Time  `gorm:"column:updated_at;autoUpdateTime"                        json:"updated_at"`
}

type Migration struct {
	Name        string // 迁移标识，如 "v1.6.0-chapter-id-refactor"，写入 migrate_state.migration
	Description string // 迁移目的简述（本次迁移为了什么、主要做什么），打印进日志便于排查
	Destructive bool   // 是否破坏性迁移（删列/rename/数据重写等）：true 时 migrate.Run 会在执行前自动备份全量数据

	// NeedsMigration 仅在既有数据库缺少本 migration 的 migrate_state 时调用，识别
	// 是否仍处于该 migration 的旧 schema。应返回 error 拒绝无法安全识别的混合 schema。
	NeedsMigration  func(db *gorm.DB) (bool, error)
	PreSchemaSteps  []Step // 当前 model AutoMigrate 前执行，例如历史字段改名
	PostSchemaSteps []Step // 当前 model AutoMigrate 后执行，例如数据重写、文件迁移、删旧列
}

type Plan struct {
	Migration Migration
	Action    PlanAction
}

type PlanAction uint8

type Step interface {
	Key() string                             // 步骤标识（迁移内序数 N-描述，如 "1-crossref-data"）
	Run(db *gorm.DB, log *slog.Logger) error // 业务逻辑，幂等可重入
}