调整迁移的逻辑

docs/migration.md

@@ -13,7 +13,101 @@
 - 自动创建迁移记录表
 - 事务支持，确保迁移的原子性
 
-## 使用方法
+## 🚀 最简单的使用方式（黑盒模式，推荐）
+
+这是最简单的迁移方式，内部自动处理配置加载、数据库连接、迁移执行等所有细节。
+
+### 方式一：使用独立迁移工具（推荐）
+
+1. **复制迁移工具模板到你的项目**：
+
+```bash
+mkdir -p cmd/migrate
+cp /path/to/go-common/templates/migrate/main.go cmd/migrate/
+```
+
+2. **创建迁移文件**：
+
+```bash
+mkdir -p migrations
+# 或使用其他目录，如 scripts/sql
+```
+
+创建 `migrations/01_init_schema.sql`：
+
+```sql
+CREATE TABLE users (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    username VARCHAR(255) NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+3. **编译和使用**：
+
+```bash
+# 编译
+go build -o bin/migrate cmd/migrate/main.go
+
+# 使用（最简单，使用默认配置和默认迁移目录）
+./bin/migrate up
+
+# 指定配置文件
+./bin/migrate up -config config.json
+
+# 指定配置和迁移目录
+./bin/migrate up -config config.json -dir scripts/sql
+
+# 查看状态
+./bin/migrate status
+
+# 回滚
+./bin/migrate down
+```
+
+**特点**：
+- ✅ 零配置：使用默认值即可运行
+- ✅ 自动查找配置：支持环境变量、默认路径
+- ✅ 自动处理：配置加载、数据库连接、迁移执行全自动
+
+### 方式二：在代码中直接调用（简单场景）
+
+```go
+import "git.toowon.com/jimmy/go-common/migration"
+
+// 最简单：使用默认配置和默认迁移目录
+err := migration.RunMigrationsFromConfigWithCommand("", "", "up")
+
+// 指定配置文件，使用默认迁移目录
+err := migration.RunMigrationsFromConfigWithCommand("config.json", "", "up")
+
+// 指定配置和迁移目录
+err := migration.RunMigrationsFromConfigWithCommand("config.json", "scripts/sql", "up")
+
+// 查看状态
+err := migration.RunMigrationsFromConfigWithCommand("config.json", "migrations", "status")
+```
+
+**参数说明**：
+- `configFile`: 配置文件路径，空字符串时自动查找（config.json, ../config.json）或使用环境变量 DATABASE_URL
+- `migrationsDir`: 迁移文件目录，空字符串时使用默认值 "migrations"
+- `command`: 命令，支持 "up", "down", "status"
+
+### 方式三：使用Factory（如果项目已使用Factory）
+
+```go
+import "git.toowon.com/jimmy/go-common/factory"
+
+fac, _ := factory.NewFactoryFromFile("config.json")
+// 使用默认目录 "migrations"
+err := fac.RunMigrations()
+// 或指定目录
+err := fac.RunMigrations("scripts/sql")
+```
+
+---
+
+## 详细使用方法（高级功能）
 
 ### 1. 创建迁移器
 
@@ -86,14 +180,16 @@ migrations := []migration.Migration{
 migrator.AddMigrations(migrations...)
 ```
 
-#### 方式三：从文件加载迁移
+#### 方式三：从文件加载迁移（推荐）
 
 ```go
-// 文件命名格式: {version}_{description}.sql 或 {version}_{description}.up.sql
-// 例如: 20240101000001_create_users_table.up.sql
-// 对应的回滚文件: 20240101000001_create_users_table.down.sql
+// 支持的文件命名格式：
+//   1. 数字前缀: 01_init_schema.sql
+//   2. 时间戳: 20240101000001_create_users.sql
+//   3. 带.up后缀: 20240101000001_create_users.up.sql
+//   对应的回滚文件: 20240101000001_create_users.down.sql
 
-migrations, err := migration.LoadMigrationsFromFiles("./migrations", "*.up.sql")
+migrations, err := migration.LoadMigrationsFromFiles("./migrations", "*.sql")
 if err != nil {
     log.Fatal(err)
 }
@@ -101,6 +197,12 @@ if err != nil {
 migrator.AddMigrations(migrations...)
 ```
 
+**新特性：**
+- ✅ 支持数字前缀命名（如 `01_init_schema.sql`）
+- ✅ 自动分割多行 SQL 语句
+- ✅ 自动处理注释（单行 `--` 和多行 `/* */`）
+- ✅ 记录执行时间（毫秒）
+
 ### 3. 执行迁移
 
 ```go
@@ -289,15 +391,31 @@ type MigrationStatus struct {
 
 **参数：**
 - `dir`: 迁移文件目录
-- `pattern`: 文件匹配模式，如 "*.up.sql"
+- `pattern`: 文件匹配模式，如 "*.sql" 或 "*.up.sql"
 
 **返回：** 迁移列表和错误信息
 
-**文件命名格式：** `{version}_{description}.up.sql`
+**支持的文件命名格式：**
 
-**示例：**
-- `20240101000001_create_users_table.up.sql` - 升级文件
-- `20240101000001_create_users_table.down.sql` - 回滚文件（可选）
+1. **数字前缀格式**（新支持）：
+   - `01_init_schema.sql`
+   - `02_init_data.sql`
+   - `03_add_log_schema.sql`
+
+2. **时间戳格式**（现有）：
+   - `20240101000001_create_users.sql`
+   - `20240101000002_add_index.sql`
+
+3. **带.up后缀格式**（现有）：
+   - `20240101000001_create_users.up.sql` - 升级文件
+   - `20240101000001_create_users.down.sql` - 回滚文件（可选）
+
+**新特性：**
+- ✅ 自动识别文件命名格式（数字前缀或时间戳）
+- ✅ 自动分割多行 SQL 语句（按分号分割）
+- ✅ 自动处理注释（单行 `--` 和多行 `/* */`）
+- ✅ 自动跳过空行和空白字符
+- ✅ 支持一个文件包含多个 SQL 语句
 
 #### GenerateVersion() string