befly 3.76.1 → 3.76.2

package/scripts/syncDb/preflight.js

@@ -0,0 +1,98 @@
+import { updatePlanHash } from "./plan.js";
+
+function quoteIdentifier(value) {
+    if (!/^[a-z][a-z0-9_]*$/.test(value)) throw new TypeError(`无效数据库标识符 ${value}`);
+    return `\`${value}\``;
+}
+
+async function countNull(mysql, operation) {
+    const result = await mysql.execute(`SELECT COUNT(*) AS count FROM ${quoteIdentifier(operation.table)} WHERE ${quoteIdentifier(operation.object)} IS NULL`);
+    return Number(result.data?.[0]?.count || 0);
+}
+
+async function maxLength(mysql, operation) {
+    const result = await mysql.execute(`SELECT MAX(CHAR_LENGTH(${quoteIdentifier(operation.object)})) AS maxLength FROM ${quoteIdentifier(operation.table)}`);
+    return Number(result.data?.[0]?.maxLength || 0);
+}
+
+async function rowCount(mysql, operation) {
+    const result = await mysql.execute(`SELECT COUNT(*) AS count FROM ${quoteIdentifier(operation.table)}`);
+    return Number(result.data?.[0]?.count || 0);
+}
+
+async function invalidDecimalCount(mysql, operation) {
+    const integerDigits = operation.after.precision - operation.after.scale;
+    const limit = 10 ** integerDigits;
+    const field = quoteIdentifier(operation.object);
+    const result = await mysql.execute(`SELECT COUNT(*) AS count FROM ${quoteIdentifier(operation.table)} WHERE ABS(${field}) >= ? OR ${field} <> ROUND(${field}, ?)`, [limit, operation.after.scale]);
+    return Number(result.data?.[0]?.count || 0);
+}
+
+async function outOfSignedBigintCount(mysql, operation) {
+    const result = await mysql.execute(`SELECT COUNT(*) AS count FROM ${quoteIdentifier(operation.table)} WHERE ${quoteIdentifier(operation.object)} > 9223372036854775807`);
+    return Number(result.data?.[0]?.count || 0);
+}
+
+async function oversizedMediumTextCount(mysql, operation) {
+    const result = await mysql.execute(`SELECT COUNT(*) AS count FROM ${quoteIdentifier(operation.table)} WHERE OCTET_LENGTH(${quoteIdentifier(operation.object)}) > 16777215`);
+    return Number(result.data?.[0]?.count || 0);
+}
+
+async function duplicateGroups(mysql, operation) {
+    const fields = operation.after.fields.map(quoteIdentifier);
+    const conditions = fields.map((field) => `${field} IS NOT NULL`).join(" AND ");
+    const result = await mysql.execute(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${quoteIdentifier(operation.table)} WHERE ${conditions} GROUP BY ${fields.join(", ")} HAVING COUNT(*) > 1) AS duplicate_groups`);
+    return Number(result.data?.[0]?.count || 0);
+}
+
+export async function runPreflight(mysql, plan) {
+    for (const operation of plan.operations) {
+        operation.preflight = null;
+        const checks = [];
+        if (operation.kind === "addColumn" && !operation.after.nullable && !operation.after.default.hasDefault) {
+            const count = await rowCount(mysql, operation);
+            checks.push({ type: "rowCount", count: count, blocked: count > 0, message: count > 0 ? `表中已有 ${count} 行，不能直接新增非空无默认值字段` : "表为空，可新增非空字段" });
+        }
+        if (operation.kind === "alterColumn" && operation.before.nullable && !operation.after.nullable) {
+            const count = await countNull(mysql, operation);
+            checks.push({ type: "nullCount", count: count, blocked: count > 0, message: count > 0 ? `存在 ${count} 行 NULL` : "不存在 NULL" });
+        }
+        if (operation.kind === "alterColumn" && operation.after.fieldType === "varchar" && ["varchar", "char"].includes(operation.before.fieldType) && operation.after.maxValue < operation.before.maxValue) {
+            const length = await maxLength(mysql, operation);
+            checks.push({ type: "maxLength", maxLength: length, blocked: length > operation.after.maxValue, message: `当前最大长度 ${length}，目标长度 ${operation.after.maxValue}` });
+        }
+        if (operation.kind === "alterColumn" && operation.after.fieldType === "number" && operation.before.fieldType === "number" && (operation.after.precision < operation.before.precision || operation.after.scale < operation.before.scale)) {
+            const count = await invalidDecimalCount(mysql, operation);
+            checks.push({ type: "decimalRange", count: count, blocked: count > 0, message: count > 0 ? `存在 ${count} 行无法容纳到 DECIMAL(${operation.after.precision}, ${operation.after.scale})` : "现有数值均可容纳" });
+        }
+        if (operation.kind === "alterColumn" && operation.after.fieldType === "integer" && (operation.before.dbType || operation.before.fieldType) === "bigint" && operation.before.unsigned && !operation.after.unsigned) {
+            const count = await outOfSignedBigintCount(mysql, operation);
+            checks.push({ type: "signedBigintRange", count: count, blocked: count > 0, message: count > 0 ? `存在 ${count} 行超过 BIGINT SIGNED 最大值` : "现有整数均可转为 BIGINT SIGNED" });
+        }
+        if (operation.kind === "alterColumn" && operation.after.fieldType === "text" && ["json", "longtext"].includes(operation.before.dbType || operation.before.fieldType)) {
+            const count = await oversizedMediumTextCount(mysql, operation);
+            checks.push({ type: "mediumTextSize", count: count, blocked: count > 0, message: count > 0 ? `存在 ${count} 行超过 MEDIUMTEXT 最大容量` : "现有内容均可转为 MEDIUMTEXT" });
+        }
+        if ((operation.kind === "addIndex" || operation.kind === "replaceIndex") && operation.after.type === "unique") {
+            const count = await duplicateGroups(mysql, operation);
+            checks.push({ type: "duplicateGroups", count: count, blocked: count > 0, message: count > 0 ? `存在 ${count} 组重复值` : "不存在重复值" });
+        }
+        if (operation.kind === "dropIndex") checks.push({ type: "dropIndex", blocked: false, message: "索引未在 Tables 中声明，将被删除" });
+        if (checks.length > 0) operation.preflight = { type: checks.length === 1 ? checks[0].type : "multiple", blocked: checks.some((check) => check.blocked), message: checks.map((check) => check.message).join("；"), checks: checks };
+
+        if (operation.preflight?.blocked) {
+            plan.blocked.push({
+                id: `preflight:${operation.table}.${operation.object}`,
+                kind: "preflight",
+                table: operation.table,
+                object: operation.object,
+                before: operation.before,
+                after: operation.after,
+                reason: operation.preflight.message
+            });
+        }
+    }
+
+    plan.counts.blocked = plan.blocked.length;
+    return updatePlanHash(plan);
+}

package/scripts/syncDb/report.js

@@ -1,195 +1,210 @@
 import { mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
+import { join, resolve } from "node:path";
 
-import { Logger } from "#befly/lib/logger.js";
-import { isNonEmptyString } from "#befly/utils/is.js";
-import { camelCase } from "#befly/utils/util.js";
-
-import { toSyncDbFieldDef } from "./transform.js";
+function formatValue(value) {
+    if (value === "") return '""';
+    if (value === null || value === undefined) return "无";
+    if (value && typeof value === "object") {
+        if (Object.hasOwn(value, "hasDefault")) return value.hasDefault ? formatValue(value.value) : "无";
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
 
-export function printSyncDbProcessLog(message) {
-    process.stdout.write(`[syncDb] ${message}\n`);
+const operationNames = {
+    createTable: "创建表",
+    alterTableComment: "修改表注释",
+    alterTableCollation: "修改排序规则",
+    addColumn: "新增字段",
+    alterColumn: "修改字段",
+    addIndex: "新增索引",
+    replaceIndex: "替换索引",
+    dropIndex: "删除索引"
+};
+
+const operationColors = {
+    createTable: "cyan",
+    alterTableComment: "limegreen",
+    alterTableCollation: "yellow",
+    addColumn: "limegreen",
+    alterColumn: "yellow",
+    addIndex: "limegreen",
+    replaceIndex: "yellow",
+    dropIndex: "red"
+};
+
+function colorText(text, color, enabled) {
+    if (!enabled) return text;
+    const ansi = Bun.color(color, "ansi");
+    return ansi ? `${ansi}${text}\x1b[0m` : text;
 }
 
-export function printSyncDbDiffSummary(diff) {
-    const tableNames = diff.missingTables.map((item) => item.tableName);
-    const extraTableFileNames = diff.extraTables.map((item) => item.tableFileName);
-    const missingFieldGroups = Object.values(diff.missingFieldsByTable);
-    const missingFieldCount = resolveSyncDbFieldCount(diff.missingFieldsByTable, diff.missingFieldCount);
-    const extraFieldGroups = Object.values(diff.extraFieldsByTable);
-    const extraFieldCount = resolveSyncDbFieldCount(diff.extraFieldsByTable, diff.extraFieldCount);
-
-    Logger.info("数据库与项目根目录表定义差异检查完成", {
-        missingTableCount: diff.missingTables.length,
-        missingFieldCount: missingFieldCount,
-        extraTableCount: diff.extraTables.length,
-        extraFieldCount: extraFieldCount,
-        missingTables: tableNames,
-        extraTables: extraTableFileNames
-    });
-
-    for (const item of diff.missingTables) {
-        Logger.info("发现缺失表", {
-            tableName: item.tableName,
-            tableFileName: item.tableFileName,
-            columnNames: item.columns.map((column) => column.columnName)
-        });
-    }
+function targetFieldTypeText(field) {
+    if (!field || typeof field !== "object") return "-";
+    return field.fieldType === "integer" ? "BIGINT" : field.fieldType === "number" ? `DECIMAL(${field.precision},${field.scale})` : field.fieldType === "varchar" ? `VARCHAR(${field.maxValue})` : field.fieldType === "text" ? "MEDIUMTEXT" : "-";
+}
 
-    for (const item of diff.extraTables) {
-        Logger.info("发现多余表", {
-            tableFileName: item.tableFileName,
-            filePath: item.filePath
-        });
-    }
+function fieldTypeText(operation) {
+    if (!["addColumn", "alterColumn"].includes(operation.kind)) return "-";
+    return targetFieldTypeText(operation.after);
+}
 
-    for (const item of missingFieldGroups) {
-        Logger.info("发现缺失字段", {
-            tableName: item.tableName,
-            tableFileName: item.tableFileName,
-            fieldNames: item.fields.map((field) => field.fieldName)
-        });
-    }
+function preflightResult(operation, colors) {
+    return colorText(operation.preflight?.blocked ? "否" : "是", operation.preflight?.blocked ? "red" : "limegreen", colors);
+}
 
-    for (const item of extraFieldGroups) {
-        Logger.info("发现多余字段", {
-            tableName: item.tableName,
-            tableFileName: item.tableFileName,
-            fieldNames: item.fields.map((field) => field.fieldName)
+function buildSyncRows(plan, colors) {
+    const createdTables = new Set(plan.operations.filter((operation) => operation.kind === "createTable").map((operation) => operation.table));
+    const riskNames = { safe: "安全", warning: "警告", destructive: "破坏性" };
+    const riskColors = { safe: "limegreen", warning: "yellow", destructive: "red" };
+    const rows = plan.operations
+        .filter((operation) => operation.preflight?.blocked !== true && (operation.kind === "createTable" || !createdTables.has(operation.table)))
+        .map((operation) => ({
+            类型: colorText(operationNames[operation.kind], operationColors[operation.kind], colors),
+            风险: colorText(riskNames[operation.risk], riskColors[operation.risk], colors),
+            表: operation.table,
+            对象: operation.object || "-",
+            字段类型: fieldTypeText(operation),
+            变更: archiveChangeText(operation),
+            预检结果: preflightResult(operation, colors)
+        }));
+    for (const notice of plan.notices.filter((item) => !createdTables.has(item.table))) rows.push({ 类型: colorText("保留", "deepskyblue", colors), 风险: "-", 表: notice.table, 对象: notice.object || "-", 字段类型: "-", 变更: notice.message, 预检结果: "-" });
+    for (const blocked of plan.blocked.filter((item) => !createdTables.has(item.table))) {
+        const change = blocked.before !== undefined || blocked.after !== undefined ? `${formatValue(blocked.before)} -> ${formatValue(blocked.after)}` : blocked.reason;
+        rows.push({
+            类型: colorText("禁止同步", "orangered", colors),
+            风险: colorText("阻塞", "orangered", colors),
+            表: blocked.table,
+            对象: blocked.object || "-",
+            字段类型: targetFieldTypeText(blocked.target || blocked.after),
+            变更: change,
+            预检结果: blocked.kind === "preflight" ? colorText("否", "red", colors) : "-"
         });
     }
+    return rows;
 }
 
-function escapeSyncDbMdCell(value) {
-    const text = String(value ?? "");
-    return text.replaceAll("|", "\\|").replaceAll("\n", "<br>");
-}
-
-function formatSyncDbValue(value) {
-    if (value === null || value === undefined) {
-        return "-";
-    }
-    if (value === "") {
-        return "-";
+const preflightNames = {
+    rowCount: "表数据行数",
+    nullCount: "NULL 数据",
+    maxLength: "字符长度",
+    decimalRange: "数值范围",
+    signedBigintRange: "BIGINT 范围",
+    mediumTextSize: "文本容量",
+    duplicateGroups: "唯一索引重复值",
+    dropIndex: "删除索引"
+};
+
+export function printPreflightFailures(plan) {
+    const rows = [];
+    for (const operation of plan.operations.filter((item) => item.preflight?.blocked)) {
+        const checks = operation.preflight.checks?.filter((check) => check.blocked) || [operation.preflight];
+        for (const check of checks) {
+            rows.push({
+                表: operation.table,
+                对象: operation.object || "-",
+                类型: operationNames[operation.kind],
+                检查项: preflightNames[check.type] || check.type,
+                详情: check.message
+            });
+        }
     }
-    return String(value);
+    process.stdout.write(`[syncDb] 预检未通过：${rows.length} 项\n`);
+    if (rows.length > 0) process.stdout.write(Bun.inspect.table(rows));
+    return rows;
 }
 
-function resolveSyncDbFieldCount(groups, fieldCount) {
-    if (Number.isInteger(fieldCount) && fieldCount >= 0) {
-        return fieldCount;
-    }
+export function printSyncPlan(context) {
+    const { plan } = context;
+    process.stdout.write(`[syncDb] 模式：${context.apply ? "执行" : "预览"}\n`);
+    process.stdout.write(`[syncDb] 范围：${context.tableName || "全部表"}\n`);
+    process.stdout.write(`[syncDb] 数据库：${context.database}，MySQL ${context.mysqlVersion}\n`);
+    const executableCount = plan.operations.filter((operation) => operation.preflight?.blocked !== true).length;
+    process.stdout.write(`[syncDb] 计划：可执行=${executableCount}，blocked=${plan.blocked.length}，保留提示=${plan.notices.length}\n`);
 
-    let resolvedFieldCount = 0;
-    for (const item of Object.values(groups || {})) {
-        resolvedFieldCount = resolvedFieldCount + item.fields.length;
+    const rows = buildSyncRows(plan, true);
+    if (rows.length > 0) {
+        process.stdout.write("\n[syncDb] 同步明细\n");
+        process.stdout.write(Bun.inspect.table(rows));
     }
 
-    return resolvedFieldCount;
+    if (!context.apply && executableCount > 0) process.stdout.write(`\n[syncDb] 预览完成。执行可同步内容：bun run syncDb${context.tableName ? ` ${context.tableName}` : ""} --yes\n`);
 }
 
-function appendSyncDbMarkdownRow(lines, values) {
-    lines.push(`| ${values.map((item) => escapeSyncDbMdCell(formatSyncDbValue(item))).join(" | ")} |`);
+function escapeTableValue(value) {
+    return String(value ?? "")
+        .replaceAll("|", "\\|")
+        .replaceAll("\n", "<br>");
 }
 
-function appendSyncDbDiffGroup(lines, tableName, tableFileName, rows) {
-    lines.push(`### ${escapeSyncDbMdCell(formatSyncDbValue(tableName))}（${escapeSyncDbMdCell(formatSyncDbValue(tableFileName))}）`);
-    lines.push("");
-    lines.push("| 差异类型 | 数据库字段名 | 字段标识 | 字段名称 | 字段类型 | 列类型 | 字符串长度 | 推断input | 推断max |");
-    lines.push("|---|---|---|---|---|---|---:|---|---:|");
-    for (const row of rows) {
-        appendSyncDbMarkdownRow(lines, row);
-    }
-    lines.push("");
+function archiveChangeText(operation) {
+    if (operation.kind === "createTable") return "创建全新表";
+    if (operation.kind === "addColumn") return `新增字段：${operation.after.dbName}，类型=${operation.after.fieldType}，NULL=${operation.after.nullable ? "是" : "否"}，默认值=${formatValue(operation.after.default)}`;
+    if (operation.kind === "addIndex") return `新增${operation.after.type === "unique" ? "唯一" : "普通"}索引：${operation.after.fields.join(", ")}`;
+    if (operation.kind === "replaceIndex") return `${formatValue(operation.before)} -> ${formatValue(operation.after)}`;
+    if (operation.kind === "dropIndex") return `删除未在 Tables 中声明的索引：${operation.object}`;
+    return operation.changes.map((change) => `${change.property}: ${formatValue(change.before)} -> ${formatValue(change.after)}`).join("；");
 }
 
-function buildSyncDbReportMarkdown(diff, groupedDbColumns, existingTableMap) {
-    const missingFieldCount = resolveSyncDbFieldCount(diff.missingFieldsByTable, diff.missingFieldCount);
-    const extraFieldCount = resolveSyncDbFieldCount(diff.extraFieldsByTable, diff.extraFieldCount);
-    const hasDiff = diff.missingTables.length > 0 || missingFieldCount > 0 || diff.extraTables.length > 0 || extraFieldCount > 0;
-
-    const lines = [];
-    lines.push("# 数据库与项目根目录表定义差异报告");
-    lines.push("");
-    lines.push(`- 生成时间戳: ${String(Date.now())}`);
-    lines.push(`- 扫描数据库表数量: ${String(groupedDbColumns.size)}`);
-    lines.push(`- 缺少表数量: ${String(diff.missingTables.length)}`);
-    lines.push(`- 缺少字段数量: ${String(missingFieldCount)}`);
-    lines.push(`- 多余表数量: ${String(diff.extraTables.length)}`);
-    lines.push(`- 多余字段数量: ${String(extraFieldCount)}`);
-    if (diff.missingTables.length > 0) {
-        lines.push(`- 缺少表列表: ${diff.missingTables.map((item) => item.tableName).join(", ")}`);
-    }
-    if (diff.extraTables.length > 0) {
-        lines.push(`- 多余表列表: ${diff.extraTables.map((item) => item.tableFileName).join(", ")}`);
-    }
-    lines.push("");
-    lines.push("## 全部数据库表信息");
-    lines.push("");
-    lines.push("| 数据库表 | 表说明 | 列数量 | 表定义中是否存在 |\n|---|---|---:|---|");
-
-    if (groupedDbColumns.size === 0) {
-        lines.push("| - | - | - | 未扫描到可对比表（可能全部被过滤） |");
-    } else {
-        for (const [tableName, columns] of groupedDbColumns.entries()) {
-            appendSyncDbMarkdownRow(lines, [tableName, isNonEmptyString(columns[0]?.tableComment) ? String(columns[0].tableComment).trim() : "-", columns.length, existingTableMap.has(String(camelCase(tableName)).toLowerCase()) ? "是" : "否"]);
-        }
-    }
-
-    lines.push("");
-    lines.push("## 全部差异信息");
-    lines.push("");
-    if (!hasDiff) {
-        lines.push("- 未发现差异");
+function renderArchive(context) {
+    const lines = [
+        "# MySQL 表结构同步存档",
+        "",
+        "## 基本信息",
+        "",
+        "| 项目 | 内容 |",
+        "|---|---|",
+        `| 开始时间 | ${escapeTableValue(context.startedAt)} |`,
+        `| 完成时间 | ${escapeTableValue(context.finishedAt)} |`,
+        `| 同步范围 | ${escapeTableValue(context.tableName || "全部表")} |`,
+        `| 数据库地址 | ${escapeTableValue(context.hostname)} |`,
+        `| 端口 | ${escapeTableValue(context.port)} |`,
+        `| 用户名 | ${escapeTableValue(context.username)} |`,
+        `| 数据库名 | ${escapeTableValue(context.database)} |`,
+        `| MySQL | ${escapeTableValue(context.mysqlVersion)} |`,
+        "| 字符集 | utf8mb4 |",
+        "| 排序规则 | utf8mb4_0900_ai_ci |",
+        `| 状态 | ${escapeTableValue(context.status)} |`,
+        `| Plan Hash | ${escapeTableValue(context.plan.planHash)} |`,
+        ""
+    ];
+
+    const rows = buildSyncRows(context.plan, false);
+    if (rows.length > 0) {
+        lines.push("## 同步明细", "", "| 类型 | 风险 | 表 | 对象 | 字段类型 | 变更 | 预检结果 |", "|---|---|---|---|---|---|---|");
+        for (const row of rows) lines.push(`| ${escapeTableValue(row.类型)} | ${escapeTableValue(row.风险)} | ${escapeTableValue(row.表)} | ${escapeTableValue(row.对象)} | ${escapeTableValue(row.字段类型)} | ${escapeTableValue(row.变更)} | ${escapeTableValue(row.预检结果)} |`);
         lines.push("");
-        return lines.join("\n");
     }
 
-    for (const missingTable of diff.missingTables) {
-        const groupRows = [];
-        for (const columnMeta of missingTable.columns) {
-            const fieldInfo = toSyncDbFieldDef(columnMeta);
-            groupRows.push(["缺少表", columnMeta.columnName, fieldInfo.fieldName, fieldInfo.fieldDef.name, columnMeta.dataType, columnMeta.columnType, columnMeta.charLength, fieldInfo.fieldDef.input, fieldInfo.fieldDef.max]);
-        }
-        appendSyncDbDiffGroup(lines, missingTable.tableName, `${missingTable.tableFileName}.json`, groupRows);
-    }
-
-    for (const tableInfo of Object.values(diff.missingFieldsByTable)) {
-        const groupRows = [];
-        for (const fieldItem of tableInfo.fields) {
-            groupRows.push(["缺少字段", fieldItem.dbColumnName, fieldItem.fieldName, fieldItem.fieldDef.name, fieldItem.dbDataType, fieldItem.dbColumnType, fieldItem.dbCharLength, fieldItem.fieldDef.input, fieldItem.fieldDef.max]);
-        }
-        appendSyncDbDiffGroup(lines, tableInfo.tableName, `${tableInfo.tableFileName}.json`, groupRows);
-    }
-
-    for (const extraTable of diff.extraTables) {
-        appendSyncDbDiffGroup(lines, "-", `${extraTable.tableFileName}.json`, [["多余表", "-", "-", extraTable.filePath || "-", "-", "-", null, "-", null]]);
-    }
+    lines.push(
+        "## 最终验证",
+        "",
+        "| 项目 | 数量 |",
+        "|---|---:|",
+        `| 已执行 | ${(context.results || []).filter((result) => result.status === "success").length} |`,
+        `| 剩余可执行差异 | ${context.remainingPlan?.operations.length ?? context.plan.operations.length} |`,
+        `| 剩余阻塞差异 | ${context.remainingPlan?.blocked.length ?? context.plan.blocked.length} |`,
+        ""
+    );
+    if (context.error) lines.push("## 错误", "", escapeTableValue(context.error), "");
+    return `${lines.join("\n")}\n`;
+}
 
-    for (const tableInfo of Object.values(diff.extraFieldsByTable)) {
-        const groupRows = [];
-        for (const fieldItem of tableInfo.fields) {
-            groupRows.push(["多余字段", "-", fieldItem.fieldName, fieldItem.fieldDef?.name, "-", "-", null, fieldItem.fieldDef?.input, fieldItem.fieldDef?.max]);
-        }
-        appendSyncDbDiffGroup(lines, tableInfo.tableName, `${tableInfo.tableFileName}.json`, groupRows);
-    }
+function pad(value, length = 2) {
+    return String(value).padStart(length, "0");
+}
 
-    lines.push("");
-    return lines.join("\n");
+function archiveFileName(date) {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}_${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}-${pad(date.getMilliseconds(), 3)}.md`;
 }
 
-export async function writeSyncDbReport(reportPath, diff, groupedDbColumns, existingTableMap) {
-    if (!isNonEmptyString(reportPath)) {
-        return "";
+export async function writeSyncArchive(context, filePath = "") {
+    let targetPath = filePath;
+    if (!targetPath) {
+        const directory = resolve(process.cwd(), ".temp", "syncDb");
+        await mkdir(directory, { recursive: true });
+        targetPath = join(directory, archiveFileName(new Date()));
     }
-
-    await mkdir(dirname(reportPath), { recursive: true });
-    const markdown = buildSyncDbReportMarkdown(diff, groupedDbColumns, existingTableMap);
-    await Bun.write(reportPath, markdown);
-    printSyncDbProcessLog(`差异报告已写入 ${reportPath}`);
-    Logger.info("差异报告写入完成", {
-        reportPath: reportPath
-    });
-
-    return reportPath;
+    await Bun.write(targetPath, renderArchive(context));
+    return targetPath;
 }

package/scripts/syncDb/snapshot.js

@@ -0,0 +1,118 @@
+const VERSION_SQL = "SELECT VERSION() AS version, @@version_comment AS versionComment";
+const TABLES_SQL = `
+SELECT TABLE_NAME AS tableName, ENGINE AS engine, TABLE_COLLATION AS tableCollation, TABLE_COMMENT AS tableComment
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
+ORDER BY TABLE_NAME`;
+const COLUMNS_SQL = `
+SELECT TABLE_NAME AS tableName, COLUMN_NAME AS columnName, ORDINAL_POSITION AS ordinalPosition,
+    DATA_TYPE AS dataType, COLUMN_TYPE AS columnType, CHARACTER_MAXIMUM_LENGTH AS charLength,
+    NUMERIC_PRECISION AS numericPrecision, NUMERIC_SCALE AS numericScale, IS_NULLABLE AS isNullable,
+    COLUMN_DEFAULT AS columnDefault, EXTRA AS extra, COLUMN_KEY AS columnKey, COLUMN_COMMENT AS columnComment
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = DATABASE()
+ORDER BY TABLE_NAME, ORDINAL_POSITION`;
+const INDEXES_SQL = `
+SELECT TABLE_NAME AS tableName, INDEX_NAME AS indexName, NON_UNIQUE AS nonUnique,
+    SEQ_IN_INDEX AS seqInIndex, COLUMN_NAME AS columnName, SUB_PART AS subPart,
+    INDEX_TYPE AS indexType, IS_VISIBLE AS isVisible
+FROM information_schema.STATISTICS
+WHERE TABLE_SCHEMA = DATABASE()
+ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX`;
+
+export function assertMysql80(version, versionComment = "") {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version));
+    const text = `${version} ${versionComment}`.toLowerCase();
+    const supported = match && Number(match[1]) >= 8;
+    if (!supported || /(mariadb|tidb|oceanbase)/.test(text)) throw new TypeError(`仅支持 Oracle MySQL 8.0 及以上版本，当前版本 ${version}`);
+    return `${match[1]}.${match[2]}.${match[3]}`;
+}
+
+function normalizeDefault(value) {
+    if (value === null || value === undefined) return { hasDefault: false, value: undefined };
+    return { hasDefault: true, value: value };
+}
+
+function getFieldType(row) {
+    if (row.dataType === "bigint") return "integer";
+    if (row.dataType === "decimal") return "number";
+    if (row.dataType === "varchar") return "varchar";
+    if (row.dataType === "mediumtext") return "text";
+    return row.dataType;
+}
+
+export function buildDatabaseSnapshot(tableRows, columnRows, indexRows) {
+    const tables = Object.fromEntries(
+        tableRows.map((row) => [
+            row.tableName,
+            {
+                dbName: row.tableName,
+                name: row.tableComment || "",
+                engine: String(row.engine || "").toUpperCase(),
+                charset: String(row.tableCollation || "")
+                    .split("_")
+                    .slice(0, 1)
+                    .join("_"),
+                collation: row.tableCollation || "",
+                columns: {},
+                indexes: {},
+                primary: null
+            }
+        ])
+    );
+
+    for (const row of columnRows) {
+        const table = tables[row.tableName];
+        if (!table) continue;
+        const fieldType = getFieldType(row);
+        const nullable = row.isNullable === "YES";
+        const column = {
+            dbName: row.columnName,
+            name: row.columnComment || "",
+            fieldType: fieldType,
+            dbType: row.dataType,
+            nullable: nullable,
+            default: normalizeDefault(row.columnDefault),
+            maxValue: ["varchar", "char"].includes(fieldType) && row.charLength !== null ? Number(row.charLength) : undefined,
+            precision: fieldType === "number" && row.numericPrecision !== null ? Number(row.numericPrecision) : undefined,
+            scale: fieldType === "number" && row.numericScale !== null ? Number(row.numericScale) : undefined,
+            primary: row.columnKey === "PRI",
+            autoIncrement: String(row.extra || "")
+                .toLowerCase()
+                .includes("auto_increment"),
+            unsigned: /\bunsigned\b/i.test(String(row.columnType || ""))
+        };
+        table.columns[row.columnName] = column;
+        if (column.primary) table.primary = table.primary ? "__multiple__" : row.columnName;
+    }
+
+    const groupedIndexes = new Map();
+    for (const row of indexRows) {
+        if (row.indexName === "PRIMARY") continue;
+        const key = `${row.tableName}\0${row.indexName}`;
+        if (!groupedIndexes.has(key)) groupedIndexes.set(key, []);
+        groupedIndexes.get(key).push(row);
+    }
+    for (const rows of groupedIndexes.values()) {
+        const first = rows[0];
+        if (!tables[first.tableName]) continue;
+        tables[first.tableName].indexes[first.indexName] = {
+            name: first.indexName,
+            type: Number(first.nonUnique) === 0 ? "unique" : "index",
+            fields: rows.toSorted((left, right) => Number(left.seqInIndex) - Number(right.seqInIndex)).map((row) => row.columnName),
+            supported: rows.every((row) => row.columnName && row.subPart === null && String(row.indexType).toUpperCase() === "BTREE" && String(row.isVisible).toUpperCase() === "YES")
+        };
+    }
+    return tables;
+}
+
+export async function readDatabaseSnapshot(mysql) {
+    const versionRows = (await mysql.execute(VERSION_SQL)).data;
+    const versionRow = versionRows[0] || {};
+    const mysqlVersion = assertMysql80(versionRow.version, versionRow.versionComment);
+    const [tableResult, columnResult, indexResult] = await Promise.all([mysql.execute(TABLES_SQL), mysql.execute(COLUMNS_SQL), mysql.execute(INDEXES_SQL)]);
+    return {
+        mysqlVersion: mysqlVersion,
+        tables: buildDatabaseSnapshot(tableResult.data || [], columnResult.data || [], indexResult.data || [])
+    };
+}