befly 3.76.0 → 3.76.2

package/scripts/syncDb/apply.js

@@ -0,0 +1,87 @@
+import { SQL } from "bun";
+
+function createExecutor(client) {
+    return {
+        execute: async function (statement, params = []) {
+            const startedAt = Date.now();
+            const data = params.length > 0 ? await client.unsafe(statement, params) : await client.unsafe(statement);
+            return { data: data, sql: { sql: statement, params: params, duration: Date.now() - startedAt } };
+        }
+    };
+}
+
+export function createSyncDbClient(mysqlConfig) {
+    const sql = new SQL({
+        adapter: "mysql",
+        hostname: mysqlConfig.hostname,
+        port: mysqlConfig.port,
+        database: mysqlConfig.database,
+        username: mysqlConfig.username,
+        password: mysqlConfig.password,
+        max: 1,
+        bigint: true,
+        connectionTimeout: mysqlConfig.connectionTimeout
+    });
+
+    return {
+        ...createExecutor(sql),
+        close: async function () {
+            await sql.close();
+        },
+        reserve: async function () {
+            const connection = await sql.reserve();
+            return {
+                ...createExecutor(connection),
+                release: function () {
+                    connection.release();
+                }
+            };
+        }
+    };
+}
+
+function getLockName(database) {
+    const name = `befly:syncDb:${database}`;
+    if (name.length <= 64) return name;
+    const hash = new Bun.CryptoHasher("sha256").update(name).digest("hex").slice(0, 32);
+    return `befly:syncDb:${hash}`;
+}
+
+export async function applySchemaPlan(client, context) {
+    const connection = await client.reserve();
+    const lockName = getLockName(context.database);
+    let locked = false;
+    const results = [];
+    try {
+        const lockResult = await connection.execute("SELECT GET_LOCK(?, 0) AS acquired", [lockName]);
+        if (Number(lockResult.data?.[0]?.acquired) !== 1) throw new Error(`无法获取数据库同步锁：${lockName}`);
+        locked = true;
+        await connection.execute("SET SESSION lock_wait_timeout = 10");
+
+        const verified = await context.verify(connection);
+        if (verified.planHash !== context.plan.planHash) throw new Error("数据库结构或预检结果已变化，请重新预览后再执行");
+
+        for (const operation of verified.operations.filter((item) => item.preflight?.blocked !== true)) {
+            const startedAt = Date.now();
+            process.stdout.write(`[syncDb] 执行 ${operation.id}\n`);
+            try {
+                await connection.execute(operation.sql);
+                results.push({ id: operation.id, status: "success", duration: Date.now() - startedAt, error: "" });
+            } catch (error) {
+                results.push({ id: operation.id, status: "failed", duration: Date.now() - startedAt, error: String(error?.message || error) });
+                error.syncDbResults = results;
+                throw error;
+            }
+        }
+        return results;
+    } finally {
+        if (locked) {
+            try {
+                await connection.execute("SELECT RELEASE_LOCK(?) AS released", [lockName]);
+            } catch {
+                // 连接关闭时 MySQL 会自动释放命名锁
+            }
+        }
+        connection.release();
+    }
+}

package/scripts/syncDb/ddl.js

@@ -0,0 +1,43 @@
+function quoteIdentifier(value) {
+    if (!/^[a-z][a-z0-9_]*$/.test(value)) throw new TypeError(`无效数据库标识符 ${value}`);
+    return `\`${value}\``;
+}
+
+function quoteString(value) {
+    return `'${String(value).replaceAll("\\", "\\\\").replaceAll("'", "''")}'`;
+}
+
+function formatDefault(column) {
+    if (!column.default.hasDefault) return "";
+    return ` DEFAULT ${typeof column.default.value === "number" ? String(column.default.value) : quoteString(column.default.value)}`;
+}
+
+export function columnSql(column) {
+    const type = column.fieldType === "integer" ? "BIGINT" : column.fieldType === "number" ? `DECIMAL(${column.precision}, ${column.scale})` : column.fieldType === "varchar" ? `VARCHAR(${column.maxValue})` : "MEDIUMTEXT";
+    return `${quoteIdentifier(column.dbName)} ${type} ${column.nullable ? "NULL" : "NOT NULL"}${formatDefault(column)}${column.autoIncrement ? " AUTO_INCREMENT" : ""} COMMENT ${quoteString(column.name)}`;
+}
+
+function indexSql(index) {
+    const fields = index.fields.map(quoteIdentifier).join(", ");
+    return `${index.type === "unique" ? "UNIQUE " : ""}KEY ${quoteIdentifier(index.name)} (${fields})`;
+}
+
+export function createTableSql(table) {
+    const columns = Object.values(table.columns).map(columnSql);
+    const primary = `PRIMARY KEY (${quoteIdentifier(table.primary)})`;
+    const indexes = Object.values(table.indexes).map(indexSql);
+    return `CREATE TABLE ${quoteIdentifier(table.dbName)} (\n    ${[...columns, primary, ...indexes].join(",\n    ")}\n) ENGINE=InnoDB DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci COMMENT=${quoteString(table.name)}`;
+}
+
+export function operationSql(operation) {
+    const table = quoteIdentifier(operation.table);
+    if (operation.kind === "createTable") return createTableSql(operation.after);
+    if (operation.kind === "alterTableComment") return `ALTER TABLE ${table} COMMENT=${quoteString(operation.after)}`;
+    if (operation.kind === "alterTableCollation") return `ALTER TABLE ${table} CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci`;
+    if (operation.kind === "addColumn") return `ALTER TABLE ${table} ADD COLUMN ${columnSql(operation.after)}`;
+    if (operation.kind === "alterColumn") return `ALTER TABLE ${table} MODIFY COLUMN ${columnSql(operation.after)}`;
+    if (operation.kind === "addIndex") return `ALTER TABLE ${table} ADD ${indexSql(operation.after)}`;
+    if (operation.kind === "replaceIndex") return `ALTER TABLE ${table} DROP INDEX ${quoteIdentifier(operation.object)}, ADD ${indexSql(operation.after)}`;
+    if (operation.kind === "dropIndex") return `ALTER TABLE ${table} DROP INDEX ${quoteIdentifier(operation.object)}`;
+    throw new TypeError(`不支持的 syncDb operation ${operation.kind}`);
+}

package/scripts/syncDb/index.js

@@ -1,43 +1,188 @@
-import { join, resolve } from "node:path";
-
-import { Connect } from "#befly/lib/connect.js";
-import { Logger } from "#befly/lib/logger.js";
+import { checkTable } from "#befly/checks/table.js";
+import { Logger } from "#befly/libs/logger/index.js";
 import { createError } from "#befly/utils/error.js";
+import { isPlainObject } from "#befly/utils/is.js";
+import { scanTables } from "#befly/utils/scanSources.js";
+
+import { applySchemaPlan, createSyncDbClient } from "./apply.js";
+import { buildTargetDatabaseModel } from "./model.js";
+import { buildSchemaPlan } from "./plan.js";
+import { runPreflight } from "./preflight.js";
+import { printPreflightFailures, printSyncPlan, writeSyncArchive } from "./report.js";
+import { readDatabaseSnapshot } from "./snapshot.js";
+
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+
+function nowText() {
+    const date = new Date();
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
 
-import { prepareSyncDbBaseContext } from "./context.js";
-import { applySyncDbDiff } from "./diff.js";
-import { printSyncDbDiffSummary, printSyncDbProcessLog, writeSyncDbReport } from "./report.js";
+async function buildPlan(mysql, targetTables, singleTable) {
+    const snapshot = await readDatabaseSnapshot(mysql);
+    const plan = buildSchemaPlan(targetTables, snapshot.tables, { singleTable: singleTable });
+    await runPreflight(mysql, plan);
+    return { mysqlVersion: snapshot.mysqlVersion, plan: plan };
+}
+
+export async function syncDb(mysqlConfig, options = {}) {
+    const apply = options.apply === true;
+    const list = options.list === true;
+    const tableName = options.tableName || "";
+    const startedAt = nowText();
+    let client;
+    let targetTables;
+    let archivePath = "";
+    let context = {
+        apply: apply,
+        tableName: tableName,
+        hostname: mysqlConfig?.hostname,
+        port: mysqlConfig?.port,
+        username: mysqlConfig?.username,
+        database: mysqlConfig?.database || "",
+        mysqlVersion: "",
+        plan: { operations: [], notices: [], blocked: [], counts: { createTable: 0, safe: 0, warning: 0, destructive: 0, notice: 0, blocked: 0 }, planHash: "" },
+        startedAt: startedAt,
+        finishedAt: "",
+        status: "running",
+        results: [],
+        remainingPlan: null
+    };
 
-export async function syncDb(mysqlConfig) {
-    const reportPath = resolve(join(process.cwd(), "db.sync.md"));
     try {
-        printSyncDbProcessLog("开始执行应用");
-        const { diff, groupedDbColumns, tablesDir, existingTableMap } = await prepareSyncDbBaseContext(mysqlConfig);
-        const writtenReportPath = await writeSyncDbReport(reportPath, diff, groupedDbColumns, existingTableMap);
-        printSyncDbDiffSummary(diff);
-        const applyResult = await applySyncDbDiff(diff, tablesDir, existingTableMap);
-        const hasDiff = diff.missingTables.length > 0 || applyResult.appendedFieldCount > 0 || diff.extraTables.length > 0 || applyResult.removedFieldCount > 0;
+        if (!isPlainObject(mysqlConfig)) throw new TypeError("syncDb 缺少 mysql 配置");
+        process.stdout.write("[syncDb] 数据库连接\n");
+        process.stdout.write(`[syncDb] 地址：${mysqlConfig.hostname}\n`);
+        process.stdout.write(`[syncDb] 端口：${mysqlConfig.port}\n`);
+        process.stdout.write(`[syncDb] 用户名：${mysqlConfig.username}\n`);
+        process.stdout.write(`[syncDb] 数据库名：${mysqlConfig.database}\n\n`);
+        if (apply) archivePath = await writeSyncArchive(context);
+        const tables = await scanTables({ beflyMode: mysqlConfig.beflyMode });
+        const tableErrors = await checkTable(tables);
+        if (tableErrors.length > 0) throw createError("Tables 定义校验失败", { code: "policy", subsystem: "scripts", operation: "syncDb", errors: tableErrors });
+
+        targetTables = buildTargetDatabaseModel(tables, tableName);
+        client = createSyncDbClient(mysqlConfig);
+        const built = await buildPlan(client, targetTables, Boolean(tableName));
+        context = {
+            ...context,
+            hostname: mysqlConfig.hostname,
+            port: mysqlConfig.port,
+            username: mysqlConfig.username,
+            database: mysqlConfig.database,
+            mysqlVersion: built.mysqlVersion,
+            plan: built.plan,
+            startedAt: startedAt,
+            finishedAt: nowText(),
+            status: apply ? "ready" : built.plan.blocked.length > 0 ? "blocked" : built.plan.operations.length > 0 ? "preview" : "no-change",
+            results: [],
+            remainingPlan: built.plan
+        };
+
+        if (list) {
+            const rows = printPreflightFailures(context.plan);
+            return {
+                status: "list",
+                database: context.database,
+                mysqlVersion: context.mysqlVersion,
+                operationCount: context.plan.operations.length,
+                blockedCount: context.plan.blocked.length,
+                preflightFailureCount: rows.length,
+                noticeCount: context.plan.notices.length,
+                planHash: context.plan.planHash,
+                archivePath: ""
+            };
+        }
+        printSyncPlan(context);
+        if (!apply) {
+            return {
+                status: context.status,
+                database: context.database,
+                mysqlVersion: context.mysqlVersion,
+                operationCount: context.plan.operations.length,
+                blockedCount: context.plan.blocked.length,
+                noticeCount: context.plan.notices.length,
+                planHash: context.plan.planHash,
+                archivePath: ""
+            };
+        }
+
+        archivePath = await writeSyncArchive(context, archivePath);
+        process.stdout.write(`[syncDb] 同步存档：${archivePath}\n`);
+        const executableOperations = context.plan.operations.filter((operation) => operation.preflight?.blocked !== true);
+        if (executableOperations.length === 0) {
+            const finalBuilt = await buildPlan(client, targetTables, Boolean(tableName));
+            context.remainingPlan = finalBuilt.plan;
+            context.mysqlVersion = finalBuilt.mysqlVersion;
+            context.status = finalBuilt.plan.blocked.length > 0 ? "blocked" : "no-change";
+            context.finishedAt = nowText();
+            await writeSyncArchive(context, archivePath);
+            process.stdout.write("\n[syncDb] 剩余未同步内容\n");
+            printSyncPlan({ ...context, apply: false, plan: finalBuilt.plan });
+            return {
+                status: context.status,
+                database: context.database,
+                mysqlVersion: context.mysqlVersion,
+                operationCount: context.plan.operations.length,
+                appliedCount: 0,
+                blockedCount: finalBuilt.plan.blocked.length,
+                noticeCount: finalBuilt.plan.notices.length,
+                remainingOperationCount: finalBuilt.plan.operations.length,
+                planHash: context.plan.planHash,
+                archivePath: archivePath
+            };
+        }
 
-        printSyncDbProcessLog(
-            `应用完成，缺少表数量=${diff.missingTables.length}，缺少字段数量=${applyResult.appendedFieldCount}，多余表数量=${diff.extraTables.length}，多余字段数量=${diff.extraFieldCount}，新建表定义文件数量=${applyResult.createdTableFileCount}，补充字段数量=${applyResult.appendedFieldCount}，删除字段数量=${applyResult.removedFieldCount}`
-        );
+        context.results = await applySchemaPlan(client, {
+            database: mysqlConfig.database,
+            plan: context.plan,
+            verify: async (connection) => (await buildPlan(connection, targetTables, Boolean(tableName))).plan
+        });
+        const finalBuilt = await buildPlan(client, targetTables, Boolean(tableName));
+        context.remainingPlan = finalBuilt.plan;
+        context.mysqlVersion = finalBuilt.mysqlVersion;
+        context.status = finalBuilt.plan.operations.length === 0 && finalBuilt.plan.blocked.length === 0 ? "applied" : "partial";
+        context.finishedAt = nowText();
+        await writeSyncArchive(context, archivePath);
+        process.stdout.write("\n[syncDb] 剩余未同步内容\n");
+        printSyncPlan({ ...context, apply: false, plan: finalBuilt.plan });
 
         return {
-            mode: "apply",
-            createdTableFileCount: applyResult.createdTableFileCount,
-            appendedFieldCount: applyResult.appendedFieldCount,
-            removedFieldCount: applyResult.removedFieldCount,
-            missingTableCount: diff.missingTables.length,
-            missingFieldCount: applyResult.appendedFieldCount,
-            extraTableCount: diff.extraTables.length,
-            extraFieldCount: diff.extraFieldCount,
-            hasDiff: hasDiff,
-            reportPath: writtenReportPath
+            status: context.status,
+            database: context.database,
+            mysqlVersion: context.mysqlVersion,
+            operationCount: context.plan.operations.length,
+            appliedCount: context.results.length,
+            blockedCount: finalBuilt.plan.blocked.length,
+            noticeCount: finalBuilt.plan.notices.length,
+            remainingOperationCount: finalBuilt.plan.operations.length,
+            planHash: context.plan.planHash,
+            archivePath: archivePath
         };
     } catch (error) {
-        throw createError("执行表定义同步失败", { cause: error, code: "runtime", subsystem: "scripts", operation: "syncDb" });
+        if (context && Array.isArray(error?.syncDbResults)) context.results = error.syncDbResults;
+        if (apply) {
+            context.status = context.results?.some((result) => result.status === "success") ? "partial" : context.plan?.blocked.length > 0 ? "blocked" : "failed";
+            context.finishedAt = nowText();
+            context.error = String(error?.message || error);
+            if (client && targetTables && context.results?.length > 0) {
+                try {
+                    context.remainingPlan = (await buildPlan(client, targetTables, Boolean(tableName))).plan;
+                } catch {
+                    // 保留原始执行错误，存档沿用执行前计划
+                }
+            }
+            try {
+                archivePath = await writeSyncArchive(context, archivePath);
+            } catch (archiveError) {
+                throw createError("同步失败且无法写入同步存档", { cause: archiveError, code: "runtime", subsystem: "scripts", operation: "syncDb" });
+            }
+        }
+        throw createError("执行数据库结构同步失败", { cause: error, code: "runtime", subsystem: "scripts", operation: "syncDb" });
     } finally {
-        await Connect.disconnect();
+        await client?.close();
         await Logger.flush();
     }
 }

package/scripts/syncDb/model.js

@@ -0,0 +1,60 @@
+import { snakeCase } from "#befly/utils/util.js";
+
+function normalizeDefault(value) {
+    return value === undefined ? { hasDefault: false, value: undefined } : { hasDefault: true, value: value };
+}
+
+function buildColumn(fieldName, field) {
+    return {
+        codeName: fieldName,
+        dbName: snakeCase(fieldName),
+        name: field.name,
+        detail: field.detail,
+        fieldType: field.fieldType,
+        nullable: field.fieldNullable,
+        default: normalizeDefault(field.fieldDefault),
+        maxValue: field.maxValue,
+        precision: field.precision,
+        scale: field.scale,
+        primary: field.primary === true,
+        autoIncrement: field.autoIncrement === true,
+        unsigned: false
+    };
+}
+
+export function buildTargetDatabaseModel(tables, tableName) {
+    let selectedTables = Object.values(tables);
+    if (tableName) {
+        selectedTables = selectedTables.filter((table) => table.codeName === tableName || table.fileName === tableName);
+        if (selectedTables.length === 0) throw new TypeError(`找不到 Table 定义：${tableName}`);
+    }
+
+    return Object.fromEntries(
+        selectedTables
+            .toSorted((left, right) => snakeCase(left.codeName).localeCompare(snakeCase(right.codeName)))
+            .map((table) => [
+                snakeCase(table.codeName),
+                {
+                    codeName: table.codeName,
+                    fileName: table.fileName,
+                    dbName: snakeCase(table.codeName),
+                    name: table.name,
+                    primary: snakeCase(table.primary),
+                    engine: "INNODB",
+                    charset: "utf8mb4",
+                    collation: "utf8mb4_0900_ai_ci",
+                    columns: Object.fromEntries(Object.entries(table.fields).map(([fieldName, field]) => [snakeCase(fieldName), buildColumn(fieldName, field)])),
+                    indexes: Object.fromEntries(
+                        Object.entries(table.indexes).map(([indexName, index]) => [
+                            indexName,
+                            {
+                                name: indexName,
+                                type: index.type,
+                                fields: index.fields.map((fieldName) => snakeCase(fieldName))
+                            }
+                        ])
+                    )
+                }
+            ])
+    );
+}

package/scripts/syncDb/plan.js

@@ -0,0 +1,160 @@
+import { operationSql } from "./ddl.js";
+
+function sameDefault(left, right) {
+    if (left.hasDefault !== right.hasDefault) return false;
+    if (!left.hasDefault) return true;
+    if (typeof left.value === "number" || typeof right.value === "number") return Number(left.value) === Number(right.value);
+    return String(left.value) === String(right.value);
+}
+
+function sameIndex(left, right) {
+    return left.type === right.type && left.fields.length === right.fields.length && left.fields.every((field, index) => field === right.fields[index]);
+}
+
+function targetDbType(fieldType) {
+    return { integer: "bigint", number: "decimal", varchar: "varchar", text: "mediumtext" }[fieldType];
+}
+
+function compatibleFieldType(target, actual) {
+    const sources = {
+        integer: new Set(["integer", "tinyint", "smallint", "mediumint", "int"]),
+        number: new Set(["number"]),
+        varchar: new Set(["varchar", "char"]),
+        text: new Set(["text", "tinytext", "longtext", "json", "varchar", "char"])
+    };
+    return sources[target]?.has(actual) === true;
+}
+
+function columnChanges(target, actual) {
+    const changes = [];
+    for (const property of ["fieldType", "maxValue", "precision", "scale", "nullable", "name", "unsigned"]) {
+        if (target[property] !== actual[property]) changes.push({ property: property, before: actual[property], after: target[property] });
+    }
+    if (!sameDefault(target.default, actual.default)) changes.push({ property: "default", before: actual.default, after: target.default });
+    return changes;
+}
+
+function columnRisk(target, actual, changes) {
+    if (target.fieldType === "varchar" && target.maxValue < actual.maxValue) return "warning";
+    if (target.fieldType === "number" && (target.precision < actual.precision || target.scale < actual.scale)) return "warning";
+    if (actual.nullable && !target.nullable) return "warning";
+    return changes.every((change) => change.property === "name") ? "safe" : "warning";
+}
+
+function addOperation(plan, operation) {
+    operation.id = `${operation.kind}:${operation.table}${operation.object ? `.${operation.object}` : ""}`;
+    operation.sql = operationSql(operation);
+    plan.operations.push(operation);
+}
+
+function addBlocked(plan, blocked) {
+    blocked.id = `${blocked.kind}:${blocked.table}${blocked.object ? `.${blocked.object}` : ""}`;
+    plan.blocked.push(blocked);
+}
+
+function addNotice(plan, notice) {
+    notice.id = `${notice.kind}:${notice.table}${notice.object ? `.${notice.object}` : ""}`;
+    plan.notices.push(notice);
+}
+
+export function updatePlanHash(plan) {
+    const payload = {
+        operations: plan.operations.map(({ id, kind, risk, table, object, before, after, changes, preflight, sql }) => ({ id: id, kind: kind, risk: risk, table: table, object: object, before: before, after: after, changes: changes, preflight: preflight, sql: sql })),
+        blocked: plan.blocked,
+        notices: plan.notices
+    };
+    plan.planHash = new Bun.CryptoHasher("sha256").update(JSON.stringify(payload)).digest("hex");
+    return plan;
+}
+
+export function buildSchemaPlan(targetTables, actualTables, { singleTable = false } = {}) {
+    const plan = { operations: [], notices: [], blocked: [], counts: {} };
+
+    for (const target of Object.values(targetTables)) {
+        const actual = actualTables[target.dbName];
+        if (!actual) {
+            addOperation(plan, { kind: "createTable", risk: "safe", table: target.dbName, before: null, after: target, changes: [] });
+            continue;
+        }
+
+        if (actual.engine !== target.engine) addBlocked(plan, { kind: "tableEngine", table: target.dbName, before: actual.engine, after: target.engine, reason: "不自动转换表引擎" });
+        if (actual.charset !== target.charset) addBlocked(plan, { kind: "tableCharset", table: target.dbName, before: actual.charset, after: target.charset, reason: "不自动执行跨字符集转换" });
+        else if (actual.collation !== target.collation) addOperation(plan, { kind: "alterTableCollation", risk: "warning", table: target.dbName, before: actual.collation, after: target.collation, changes: [{ property: "collation", before: actual.collation, after: target.collation }] });
+        if (actual.name !== target.name) addOperation(plan, { kind: "alterTableComment", risk: "safe", table: target.dbName, before: actual.name, after: target.name, changes: [{ property: "name", before: actual.name, after: target.name }] });
+
+        if (actual.primary !== target.primary) addBlocked(plan, { kind: "tablePrimary", table: target.dbName, before: actual.primary, after: target.primary, reason: "不自动修改主键" });
+        const targetPrimary = target.columns[target.primary];
+        const actualPrimary = actual.columns[target.primary];
+        if (actual.primary === target.primary && actualPrimary && actualPrimary.autoIncrement !== targetPrimary.autoIncrement)
+            addBlocked(plan, { kind: "tableAutoIncrement", table: target.dbName, object: target.primary, before: actualPrimary.autoIncrement, after: targetPrimary.autoIncrement, reason: "不自动修改主键自增属性" });
+
+        for (const targetColumn of Object.values(target.columns)) {
+            const actualColumn = actual.columns[targetColumn.dbName];
+            if (!actualColumn) {
+                addOperation(plan, { kind: "addColumn", risk: targetColumn.nullable || targetColumn.default.hasDefault ? "safe" : "warning", table: target.dbName, object: targetColumn.dbName, before: null, after: targetColumn, changes: [] });
+                continue;
+            }
+            const sourceType = actualColumn.dbType || targetDbType(actualColumn.fieldType) || actualColumn.fieldType;
+            const sourceDisplayType = actualColumn.dbType || actualColumn.fieldType;
+            const sourceFieldType = sourceType === "bigint" ? "integer" : sourceType === "decimal" || sourceType === "numeric" ? "number" : sourceType === "mediumtext" ? "text" : sourceType;
+            if (!compatibleFieldType(targetColumn.fieldType, sourceFieldType)) {
+                addBlocked(plan, { kind: "columnType", table: target.dbName, object: targetColumn.dbName, before: sourceDisplayType, after: targetColumn.fieldType, target: targetColumn, reason: "不允许自动执行不兼容字段类型转换" });
+                continue;
+            }
+            const physicalTypeChanged = sourceType !== targetDbType(targetColumn.fieldType);
+            if (targetColumn.fieldType === "text" && physicalTypeChanged && Object.values(actual.indexes).some((index) => index.fields.includes(targetColumn.dbName))) {
+                addBlocked(plan, { kind: "columnIndexedText", table: target.dbName, object: targetColumn.dbName, before: sourceDisplayType, after: targetColumn.fieldType, target: targetColumn, reason: "索引字段不能直接转换为 MEDIUMTEXT" });
+                continue;
+            }
+            if (targetColumn.primary !== actualColumn.primary || targetColumn.autoIncrement !== actualColumn.autoIncrement) continue;
+            const changes = columnChanges(targetColumn, actualColumn).filter((change) => change.property !== "fieldType");
+            if (physicalTypeChanged) changes.unshift({ property: "fieldType", before: sourceDisplayType, after: targetColumn.fieldType });
+            if (changes.length > 0) addOperation(plan, { kind: "alterColumn", risk: columnRisk(targetColumn, actualColumn, changes), table: target.dbName, object: targetColumn.dbName, before: actualColumn, after: targetColumn, changes: changes });
+        }
+
+        for (const actualColumn of Object.values(actual.columns)) {
+            if (!target.columns[actualColumn.dbName]) addNotice(plan, { kind: "unmanagedColumn", table: target.dbName, object: actualColumn.dbName, message: "字段仅存在于 MySQL，按只增不减规则保留" });
+        }
+
+        for (const targetIndex of Object.values(target.indexes)) {
+            const actualIndex = actual.indexes[targetIndex.name];
+            if (!actualIndex) addOperation(plan, { kind: "addIndex", risk: targetIndex.type === "unique" ? "warning" : "safe", table: target.dbName, object: targetIndex.name, before: null, after: targetIndex, changes: [] });
+            else if (!actualIndex.supported || !sameIndex(targetIndex, actualIndex))
+                addOperation(plan, {
+                    kind: "replaceIndex",
+                    risk: "warning",
+                    table: target.dbName,
+                    object: targetIndex.name,
+                    before: actualIndex,
+                    after: targetIndex,
+                    changes: [
+                        { property: "type", before: actualIndex.type, after: targetIndex.type },
+                        { property: "fields", before: actualIndex.fields, after: targetIndex.fields }
+                    ]
+                });
+        }
+        for (const actualIndex of Object.values(actual.indexes)) {
+            if (!target.indexes[actualIndex.name]) addOperation(plan, { kind: "dropIndex", risk: "destructive", table: target.dbName, object: actualIndex.name, before: actualIndex, after: null, changes: [] });
+        }
+    }
+
+    if (!singleTable) {
+        for (const actual of Object.values(actualTables)) {
+            if (!targetTables[actual.dbName]) addNotice(plan, { kind: "unmanagedTable", table: actual.dbName, message: "表仅存在于 MySQL，保留且不受同步管理" });
+        }
+    }
+
+    plan.operations.sort((left, right) => {
+        const order = { createTable: 10, alterTableComment: 20, alterTableCollation: 30, addColumn: 40, alterColumn: 50, addIndex: 60, replaceIndex: 70, dropIndex: 80 };
+        return order[left.kind] - order[right.kind] || left.table.localeCompare(right.table) || String(left.object || "").localeCompare(String(right.object || ""));
+    });
+    plan.counts = {
+        createTable: plan.operations.filter((item) => item.kind === "createTable").length,
+        safe: plan.operations.filter((item) => item.risk === "safe").length,
+        warning: plan.operations.filter((item) => item.risk === "warning").length,
+        destructive: plan.operations.filter((item) => item.risk === "destructive").length,
+        notice: plan.notices.length,
+        blocked: plan.blocked.length
+    };
+    return updatePlanHash(plan);
+}