befly 3.21.1 → 3.22.0

package/scripts/syncDb/context.js

@@ -8,52 +8,30 @@ import { importDefault } from "../../utils/importDefault.js";
 import { isNonEmptyString, isPlainObject } from "../../utils/is.js";
 import { camelCase } from "../../utils/util.js";
 import { buildSyncDbDiff, groupSyncDbColumns } from "./diff.js";
-import { querySyncDbColumns } from "./query.js";
 import { printSyncDbProcessLog } from "./report.js";
 
-async function loadSyncDbTableDefs(tablesDir) {
-    const tableMap = new Map();
-
-    const glob = new Bun.Glob("*.json");
-    const files = await glob.scan({
-        cwd: tablesDir,
-        onlyFiles: true,
-        absolute: true,
-        followSymlinks: true
-    });
-
-    for await (const filePath of files) {
-        const fileName = basename(filePath, ".json");
-        const tableKey = String(camelCase(fileName)).toLowerCase();
-        if (fileName.startsWith("_")) {
-            continue;
-        }
-
-        const loaded = await importDefault(filePath, {});
-        if (!isPlainObject(loaded)) {
-            Logger.warn("tables 定义文件不是对象，已按空对象处理", {
-                filePath: filePath
-            });
-            tableMap.set(tableKey, {
-                filePath: filePath,
-                tableDef: {}
-            });
-            continue;
-        }
-
-        tableMap.set(tableKey, {
-            filePath: filePath,
-            tableDef: loaded
-        });
-    }
-
-    return tableMap;
-}
+const SYNC_DB_COLUMNS_SQL = `
+SELECT
+    c.TABLE_NAME AS tableName,
+    t.TABLE_COMMENT AS tableComment,
+    c.COLUMN_NAME AS columnName,
+    c.DATA_TYPE AS dataType,
+    c.COLUMN_TYPE AS columnType,
+    c.CHARACTER_MAXIMUM_LENGTH AS charLength,
+    c.COLUMN_COMMENT AS columnComment,
+    c.ORDINAL_POSITION AS ordinalPosition
+FROM information_schema.COLUMNS AS c
+LEFT JOIN information_schema.TABLES AS t
+    ON t.TABLE_SCHEMA = c.TABLE_SCHEMA
+    AND t.TABLE_NAME = c.TABLE_NAME
+WHERE c.TABLE_SCHEMA = DATABASE()
+ORDER BY c.TABLE_NAME ASC, c.ORDINAL_POSITION ASC
+`;
 
 export async function prepareSyncDbBaseContext(mysqlConfig) {
     const tablesDir = resolve(join(process.cwd(), "tables"));
     await mkdir(tablesDir, { recursive: true });
-    printSyncDbProcessLog(`tables目录=${tablesDir}`);
+    printSyncDbProcessLog(`表定义目录=${tablesDir}`);
 
     if (!isPlainObject(mysqlConfig)) {
         throw new Error("syncDb 缺少 mysql 配置", {
@@ -64,8 +42,8 @@ export async function prepareSyncDbBaseContext(mysqlConfig) {
         });
     }
 
-    printSyncDbProcessLog(`beflyMode=${mysqlConfig.beflyMode === "manual" ? "manual" : "auto"}`);
-    printSyncDbProcessLog(`连接 MySQL，database=${mysqlConfig.database}`);
+    printSyncDbProcessLog(`同步模式=${mysqlConfig.beflyMode === "manual" ? "手动" : "自动"}`);
+    printSyncDbProcessLog(`连接 MySQL，数据库名=${mysqlConfig.database}`);
     await Connect.connectMysql(mysqlConfig);
     const mysql = new DbHelper({
         redis: null,
@@ -75,8 +53,10 @@ export async function prepareSyncDbBaseContext(mysqlConfig) {
     });
 
     printSyncDbProcessLog("开始读取数据库字段信息");
-    const dbColumns = await querySyncDbColumns(mysql);
-    printSyncDbProcessLog(`数据库字段读取完成，columnCount=${dbColumns.length}`);
+    const queryRes = await mysql.execute(SYNC_DB_COLUMNS_SQL);
+    const dbColumns = Array.isArray(queryRes.data) ? queryRes.data : [];
+    printSyncDbProcessLog(`数据库字段读取完成，字段数量=${dbColumns.length}`);
+
     const skippedBeflyTables = new Set();
     for (const row of dbColumns) {
         const tableName = String(row?.tableName || "");
@@ -93,10 +73,45 @@ export async function prepareSyncDbBaseContext(mysqlConfig) {
     }
 
     const groupedDbColumns = groupSyncDbColumns(dbColumns);
-    const existingTableMap = await loadSyncDbTableDefs(tablesDir);
+    const existingTableMap = new Map();
+    const glob = new Bun.Glob("*.json");
+    const files = await glob.scan({
+        cwd: tablesDir,
+        onlyFiles: true,
+        absolute: true,
+        followSymlinks: true
+    });
+
+    for await (const filePath of files) {
+        const tableFileName = basename(filePath, ".json");
+        if (tableFileName.startsWith("_")) {
+            continue;
+        }
+
+        const tableKey = String(camelCase(tableFileName)).toLowerCase();
+        const loaded = await importDefault(filePath, {});
+        if (!isPlainObject(loaded)) {
+            Logger.warn("tables 定义文件不是对象，已按空对象处理", {
+                filePath: filePath
+            });
+            existingTableMap.set(tableKey, {
+                tableFileName: tableFileName,
+                filePath: filePath,
+                tableDef: {}
+            });
+            continue;
+        }
+
+        existingTableMap.set(tableKey, {
+            tableFileName: tableFileName,
+            filePath: filePath,
+            tableDef: loaded
+        });
+    }
+
     const diff = buildSyncDbDiff(groupedDbColumns, existingTableMap, mysqlConfig.beflyMode);
-    printSyncDbProcessLog(`tables定义文件数量=${existingTableMap.size}`);
-    printSyncDbProcessLog(`差异扫描完成，missingTableCount=${diff.missingTables.length}，missingFieldCount=${Object.values(diff.missingFieldsByTable).reduce((sum, item) => sum + item.fields.length, 0)}`);
+    printSyncDbProcessLog(`表定义文件数量=${existingTableMap.size}`);
+    printSyncDbProcessLog(`差异扫描完成，缺少表数量=${diff.missingTables.length}，缺少字段数量=${diff.missingFieldCount}，多余表数量=${diff.extraTables.length}，多余字段数量=${diff.extraFieldCount}`);
 
     return {
         diff: diff,

package/scripts/syncDb/diff.js

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 
 import { isNonEmptyString, isPlainObject } from "../../utils/is.js";
-import { camelCase } from "../../utils/util.js";
+import { camelCase, snakeCase } from "../../utils/util.js";
 import { printSyncDbProcessLog } from "./report.js";
 import { toSyncDbFieldDef } from "./transform.js";
 
@@ -16,6 +16,25 @@ function shouldSkipSyncDbColumn(columnMeta, beflyMode) {
     return SYNC_DB_MANAGED_FIELD_NAMES.has(columnName);
 }
 
+function shouldSkipSyncDbFieldName(fieldName, beflyMode) {
+    if (beflyMode !== "manual") {
+        return false;
+    }
+
+    return SYNC_DB_MANAGED_FIELD_NAMES.has(snakeCase(String(fieldName || "")));
+}
+
+function sortSyncDbObjectKeys(source) {
+    const entries = Object.entries(source).sort(([left], [right]) => left.localeCompare(right));
+    const output = {};
+
+    for (const [key, value] of entries) {
+        output[key] = value;
+    }
+
+    return output;
+}
+
 export function groupSyncDbColumns(rows) {
     const grouped = new Map();
 
@@ -50,11 +69,18 @@ export function groupSyncDbColumns(rows) {
 
 export function buildSyncDbDiff(groupedDbColumns, existingTableMap, beflyMode = "auto") {
     const missingTables = [];
+    const extraTables = [];
     const missingFieldsByTable = {};
+    const extraFieldsByTable = {};
+    const groupedDbTableKeySet = new Set();
+    let missingFieldCount = 0;
+    let extraFieldCount = 0;
 
     for (const [tableName, columns] of groupedDbColumns.entries()) {
         const tableFileName = camelCase(tableName);
-        const existing = existingTableMap.get(String(tableFileName).toLowerCase());
+        const tableKey = String(tableFileName).toLowerCase();
+        groupedDbTableKeySet.add(tableKey);
+        const existing = existingTableMap.get(tableKey);
         const filteredColumns = columns.filter((columnMeta) => !shouldSkipSyncDbColumn(columnMeta, beflyMode));
 
         if (!existing) {
@@ -72,8 +98,10 @@ export function buildSyncDbDiff(groupedDbColumns, existingTableMap, beflyMode =
 
         const existingFields = isPlainObject(existing.tableDef) ? existing.tableDef : {};
         const missingFields = [];
+        const dbFieldNameSet = new Set();
         for (const columnMeta of filteredColumns) {
             const fieldInfo = toSyncDbFieldDef(columnMeta);
+            dbFieldNameSet.add(fieldInfo.fieldName);
             if (Object.hasOwn(existingFields, fieldInfo.fieldName)) {
                 continue;
             }
@@ -91,18 +119,61 @@ export function buildSyncDbDiff(groupedDbColumns, existingTableMap, beflyMode =
         }
 
         if (missingFields.length > 0) {
+            missingFieldCount = missingFieldCount + missingFields.length;
             missingFieldsByTable[tableFileName] = {
                 tableName: tableName,
-                tableFileName: tableFileName,
+                tableFileName: existing.tableFileName || tableFileName,
                 filePath: existing.filePath,
                 fields: missingFields
             };
         }
+
+        const extraFields = [];
+        for (const fieldName of Object.keys(existingFields)) {
+            if (shouldSkipSyncDbFieldName(fieldName, beflyMode)) {
+                continue;
+            }
+            if (dbFieldNameSet.has(fieldName)) {
+                continue;
+            }
+
+            extraFields.push({
+                tableName: tableName,
+                tableFileName: tableFileName,
+                fieldName: fieldName,
+                fieldDef: existingFields[fieldName]
+            });
+        }
+
+        if (extraFields.length > 0) {
+            extraFieldCount = extraFieldCount + extraFields.length;
+            extraFieldsByTable[tableFileName] = {
+                tableName: tableName,
+                tableFileName: existing.tableFileName || tableFileName,
+                filePath: existing.filePath,
+                fields: extraFields
+            };
+        }
+    }
+
+    for (const [tableKey, existing] of existingTableMap.entries()) {
+        if (groupedDbTableKeySet.has(tableKey)) {
+            continue;
+        }
+
+        extraTables.push({
+            tableFileName: existing.tableFileName || camelCase(tableKey),
+            filePath: existing.filePath
+        });
     }
 
     return {
         missingTables: missingTables,
-        missingFieldsByTable: missingFieldsByTable
+        extraTables: extraTables,
+        missingFieldsByTable: missingFieldsByTable,
+        extraFieldsByTable: extraFieldsByTable,
+        missingFieldCount: missingFieldCount,
+        extraFieldCount: extraFieldCount
     };
 }
 
@@ -118,7 +189,7 @@ export async function applySyncDbDiff(diff, tablesDir, existingTableMap) {
         }
 
         const filePath = join(tablesDir, `${missingTable.tableFileName}.json`);
-        await Bun.write(filePath, `${JSON.stringify(tableDef, null, 4)}\n`);
+        await Bun.write(filePath, `${JSON.stringify(sortSyncDbObjectKeys(tableDef), null, 4)}\n`);
         createdTableFileCount = createdTableFileCount + 1;
         printSyncDbProcessLog(`已生成表映射 ${filePath}`);
     }
@@ -133,8 +204,8 @@ export async function applySyncDbDiff(diff, tablesDir, existingTableMap) {
             appendedFieldCount = appendedFieldCount + 1;
         }
 
-        await Bun.write(targetFilePath, `${JSON.stringify(currentTableDef, null, 4)}\n`);
-        printSyncDbProcessLog(`已补充字段映射 ${targetFilePath}，fieldCount=${tableInfo.fields.length}`);
+        await Bun.write(targetFilePath, `${JSON.stringify(sortSyncDbObjectKeys(currentTableDef), null, 4)}\n`);
+        printSyncDbProcessLog(`已补充字段映射 ${targetFilePath}，补充字段数量=${tableInfo.fields.length}`);
     }
 
     return {
@@ -142,11 +213,3 @@ export async function applySyncDbDiff(diff, tablesDir, existingTableMap) {
         appendedFieldCount: appendedFieldCount
     };
 }
-
-export function countSyncDbMissingFields(diff) {
-    let missingFieldCount = 0;
-    for (const item of Object.values(diff.missingFieldsByTable)) {
-        missingFieldCount = missingFieldCount + item.fields.length;
-    }
-    return missingFieldCount;
-}

package/scripts/syncDb/index.js

@@ -1,55 +1,23 @@
-import { mkdir } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 
 import { Connect } from "../../lib/connect.js";
 import { Logger } from "../../lib/logger.js";
-import { applySyncDbDiff, countSyncDbMissingFields } from "./diff.js";
+import { applySyncDbDiff } from "./diff.js";
 import { prepareSyncDbBaseContext } from "./context.js";
-import { printSyncDbDiffSummary, printSyncDbProcessLog, writeSyncDbCheckReport } from "./report.js";
-
-export async function syncDbCheck(mysqlConfig) {
-    try {
-        printSyncDbProcessLog("开始执行 check");
-        const reportPath = resolve(join(process.cwd(), "db.check.md"));
-        await mkdir(dirname(reportPath), { recursive: true });
-        await Bun.write(reportPath, "");
-
-        const { diff, groupedDbColumns, existingTableMap } = await prepareSyncDbBaseContext(mysqlConfig);
-        const missingFieldCount = countSyncDbMissingFields(diff);
-        const writtenReportPath = await writeSyncDbCheckReport(reportPath, diff, groupedDbColumns, existingTableMap);
-        printSyncDbDiffSummary("check", diff);
-        printSyncDbProcessLog(`check完成，missingTableCount=${diff.missingTables.length}，missingFieldCount=${missingFieldCount}`);
-
-        return {
-            mode: "check",
-            createdTableFileCount: 0,
-            appendedFieldCount: 0,
-            missingTableCount: diff.missingTables.length,
-            missingFieldCount: missingFieldCount,
-            hasDiff: diff.missingTables.length > 0 || missingFieldCount > 0,
-            reportPath: writtenReportPath
-        };
-    } catch (error) {
-        throw new Error("执行表定义同步失败", {
-            cause: error,
-            code: "runtime",
-            subsystem: "scripts",
-            operation: "syncDb"
-        });
-    } finally {
-        await Connect.disconnect();
-        await Logger.flush();
-    }
-}
+import { printSyncDbDiffSummary, printSyncDbProcessLog, writeSyncDbReport } from "./report.js";
 
 export async function syncDbApply(mysqlConfig) {
+    const reportPath = resolve(join(process.cwd(), "db.sync.md"));
     try {
-        printSyncDbProcessLog("开始执行 apply");
-        const { diff, tablesDir, existingTableMap } = await prepareSyncDbBaseContext(mysqlConfig);
-        printSyncDbDiffSummary("check", diff);
+        printSyncDbProcessLog("开始执行应用");
+        const { diff, groupedDbColumns, tablesDir, existingTableMap } = await prepareSyncDbBaseContext(mysqlConfig);
+        const extraFieldCount = diff.extraFieldCount;
+        const writtenReportPath = await writeSyncDbReport(reportPath, diff, groupedDbColumns, existingTableMap);
+        printSyncDbDiffSummary(diff);
         const applyResult = await applySyncDbDiff(diff, tablesDir, existingTableMap);
-        printSyncDbDiffSummary("apply", diff);
-        printSyncDbProcessLog(`apply完成，createdTableFileCount=${applyResult.createdTableFileCount}，appendedFieldCount=${applyResult.appendedFieldCount}`);
+        const hasDiff = diff.missingTables.length > 0 || applyResult.appendedFieldCount > 0 || diff.extraTables.length > 0 || extraFieldCount > 0;
+
+        printSyncDbProcessLog(`应用完成，缺少表数量=${diff.missingTables.length}，缺少字段数量=${applyResult.appendedFieldCount}，多余表数量=${diff.extraTables.length}，多余字段数量=${extraFieldCount}，新建表定义文件数量=${applyResult.createdTableFileCount}，补充字段数量=${applyResult.appendedFieldCount}`);
 
         return {
             mode: "apply",
@@ -57,8 +25,10 @@ export async function syncDbApply(mysqlConfig) {
             appendedFieldCount: applyResult.appendedFieldCount,
             missingTableCount: diff.missingTables.length,
             missingFieldCount: applyResult.appendedFieldCount,
-            hasDiff: diff.missingTables.length > 0 || applyResult.appendedFieldCount > 0,
-            reportPath: ""
+            extraTableCount: diff.extraTables.length,
+            extraFieldCount: extraFieldCount,
+            hasDiff: hasDiff,
+            reportPath: writtenReportPath
         };
     } catch (error) {
         throw new Error("执行表定义同步失败", {

package/scripts/syncDb/report.js

@@ -4,25 +4,44 @@ import { dirname } from "node:path";
 import { Logger } from "../../lib/logger.js";
 import { isNonEmptyString } from "../../utils/is.js";
 import { camelCase } from "../../utils/util.js";
-import { countSyncDbMissingFields } from "./diff.js";
 import { toSyncDbFieldDef } from "./transform.js";
 
 export function printSyncDbProcessLog(message) {
     process.stdout.write(`[syncDb] ${message}\n`);
 }
 
-export function printSyncDbDiffSummary(mode, diff) {
+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 = countSyncDbMissingFields(diff);
+    const missingFieldCount = resolveSyncDbFieldCount(diff.missingFieldsByTable, diff.missingFieldCount);
+    const extraFieldGroups = Object.values(diff.extraFieldsByTable);
+    const extraFieldCount = resolveSyncDbFieldCount(diff.extraFieldsByTable, diff.extraFieldCount);
 
-    Logger.info("DB 与项目根目录 tables 差异检查完成", {
-        mode: mode,
+    Logger.info("数据库与项目根目录表定义差异检查完成", {
         missingTableCount: diff.missingTables.length,
         missingFieldCount: missingFieldCount,
-        missingTables: tableNames
+        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)
+        });
+    }
+
+    for (const item of diff.extraTables) {
+        Logger.info("发现多余表", {
+            tableFileName: item.tableFileName,
+            filePath: item.filePath
+        });
+    }
+
     for (const item of missingFieldGroups) {
         Logger.info("发现缺失字段", {
             tableName: item.tableName,
@@ -30,6 +49,14 @@ export function printSyncDbDiffSummary(mode, diff) {
             fieldNames: item.fields.map((field) => field.fieldName)
         });
     }
+
+    for (const item of extraFieldGroups) {
+        Logger.info("发现多余字段", {
+            tableName: item.tableName,
+            tableFileName: item.tableFileName,
+            fieldNames: item.fields.map((field) => field.fieldName)
+        });
+    }
 }
 
 function escapeSyncDbMdCell(value) {
@@ -47,144 +74,116 @@ function formatSyncDbValue(value) {
     return String(value);
 }
 
-function buildSyncDbCheckRows(diff) {
-    const rows = [];
-
-    for (const missingTable of diff.missingTables) {
-        for (const columnMeta of missingTable.columns) {
-            const fieldInfo = toSyncDbFieldDef(columnMeta);
-            rows.push({
-                diffType: "缺少表",
-                tableName: missingTable.tableName,
-                tableFileName: `${missingTable.tableFileName}.json`,
-                dbColumnName: columnMeta.columnName,
-                fieldName: fieldInfo.fieldName,
-                dbDataType: columnMeta.dataType,
-                dbColumnType: columnMeta.columnType,
-                dbCharLength: columnMeta.charLength,
-                fieldInput: fieldInfo.fieldDef.input,
-                fieldMax: fieldInfo.fieldDef.max,
-                fieldDisplayName: fieldInfo.fieldDef.name
-            });
-        }
+function resolveSyncDbFieldCount(groups, fieldCount) {
+    if (Number.isInteger(fieldCount) && fieldCount >= 0) {
+        return fieldCount;
     }
 
-    for (const tableInfo of Object.values(diff.missingFieldsByTable)) {
-        for (const fieldItem of tableInfo.fields) {
-            rows.push({
-                diffType: "缺少字段",
-                tableName: tableInfo.tableName,
-                tableFileName: `${tableInfo.tableFileName}.json`,
-                dbColumnName: fieldItem.dbColumnName,
-                fieldName: fieldItem.fieldName,
-                dbDataType: fieldItem.dbDataType,
-                dbColumnType: fieldItem.dbColumnType,
-                dbCharLength: fieldItem.dbCharLength,
-                fieldInput: fieldItem.fieldDef.input,
-                fieldMax: fieldItem.fieldDef.max,
-                fieldDisplayName: fieldItem.fieldDef.name
-            });
-        }
+    let resolvedFieldCount = 0;
+    for (const item of Object.values(groups || {})) {
+        resolvedFieldCount = resolvedFieldCount + item.fields.length;
     }
 
-    return rows;
+    return resolvedFieldCount;
 }
 
-function groupSyncDbDiffRowsByTable(rows) {
-    const grouped = new Map();
-
-    for (const row of rows) {
-        const tableName = String(row.tableName || "-");
-        const tableFileName = String(row.tableFileName || "-");
-        const groupKey = `${tableName}@@${tableFileName}`;
-        if (!grouped.has(groupKey)) {
-            grouped.set(groupKey, {
-                tableName: tableName,
-                tableFileName: tableFileName,
-                rows: []
-            });
-        }
-
-        grouped.get(groupKey).rows.push(row);
-    }
-
-    return Array.from(grouped.values());
+function appendSyncDbMarkdownRow(lines, values) {
+    lines.push(`| ${values.map((item) => escapeSyncDbMdCell(formatSyncDbValue(item))).join(" | ")} |`);
 }
 
-function buildSyncDbAllTableRows(groupedDbColumns, existingTableMap) {
-    const rows = [];
-
-    for (const [tableName, columns] of groupedDbColumns.entries()) {
-        const hasTableDef = existingTableMap.has(String(camelCase(tableName)).toLowerCase()) ? "是" : "否";
-        const tableComment = isNonEmptyString(columns[0]?.tableComment) ? String(columns[0].tableComment).trim() : "-";
-        rows.push({
-            tableName: tableName,
-            tableComment: tableComment,
-            columnCount: columns.length,
-            hasTableDef: hasTableDef
-        });
+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);
     }
-
-    return rows;
+    lines.push("");
 }
 
-function buildSyncDbCheckMarkdown(diff, groupedDbColumns, existingTableMap) {
-    const allTableRows = buildSyncDbAllTableRows(groupedDbColumns, existingTableMap);
-    const rows = buildSyncDbCheckRows(diff);
-    const diffGroups = groupSyncDbDiffRowsByTable(rows);
-    const missingFieldCount = countSyncDbMissingFields(diff);
+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("# DB 与项目根目录 tables 差异报告");
+    lines.push("# 数据库与项目根目录表定义差异报告");
     lines.push("");
     lines.push(`- 生成时间戳: ${String(Date.now())}`);
-    lines.push(`- 扫描数据库表数量: ${String(allTableRows.length)}`);
+    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("| 数据库表 | 表说明 | 列数量 | tables中是否存在 |\n|---|---|---:|---|");
+    lines.push("| 数据库表 | 表说明 | 列数量 | 表定义中是否存在 |\n|---|---|---:|---|");
 
-    if (allTableRows.length === 0) {
+    if (groupedDbColumns.size === 0) {
         lines.push("| - | - | - | 未扫描到可对比表（可能全部被过滤） |");
     } else {
-        for (const row of allTableRows) {
-            lines.push(`| ${escapeSyncDbMdCell(formatSyncDbValue(row.tableName))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.tableComment))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.columnCount))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.hasTableDef))} |`);
+        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 (rows.length === 0) {
+    if (!hasDiff) {
         lines.push("- 未发现差异");
         lines.push("");
         return lines.join("\n");
     }
 
-    for (const group of diffGroups) {
-        lines.push(`### ${escapeSyncDbMdCell(formatSyncDbValue(group.tableName))}（${escapeSyncDbMdCell(formatSyncDbValue(group.tableFileName))}）`);
-        lines.push("");
-        lines.push("| 差异类型 | 数据库字段名 | 字段标识 | 字段名称 | 字段类型 | 列类型 | 字符串长度 | 推断input | 推断max |");
-        lines.push("|---|---|---|---|---|---|---:|---|---:|");
-        for (const row of group.rows) {
-            lines.push(`| ${escapeSyncDbMdCell(formatSyncDbValue(row.diffType))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.dbColumnName))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.fieldName))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.fieldDisplayName))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.dbDataType))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.dbColumnType))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.dbCharLength))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.fieldInput))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.fieldMax))} |`);
+    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]);
         }
-        lines.push("");
+        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]]);
+    }
+
+    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);
     }
 
     lines.push("");
     return lines.join("\n");
 }
 
-export async function writeSyncDbCheckReport(reportPath, diff, groupedDbColumns, existingTableMap) {
+export async function writeSyncDbReport(reportPath, diff, groupedDbColumns, existingTableMap) {
     if (!isNonEmptyString(reportPath)) {
         return "";
     }
 
     await mkdir(dirname(reportPath), { recursive: true });
-    const markdown = buildSyncDbCheckMarkdown(diff, groupedDbColumns, existingTableMap);
+    const markdown = buildSyncDbReportMarkdown(diff, groupedDbColumns, existingTableMap);
     await Bun.write(reportPath, markdown);
     printSyncDbProcessLog(`差异报告已写入 ${reportPath}`);
     Logger.info("差异报告写入完成", {