befly 3.16.11 → 3.17.0

package/befly.js

@@ -10505,6 +10505,13 @@ var parse5 = function(p) {
   };
 };
 // configs/constConfig.js
+var STRING_KIND_TYPES = ["char", "varchar", "enum", "tinytext", "text", "mediumtext", "longtext"];
+var TEXT_KIND_TYPES = ["tinytext", "text", "mediumtext", "longtext"];
+var INT_KIND_TYPES = ["tinyint", "smallint", "mediumint", "int", "bigint"];
+var DECIMAL_KIND_TYPES = ["decimal"];
+var FLOAT_KIND_TYPES = ["float", "double"];
+var JSON_KIND_TYPES = ["json"];
+var ENUM_KIND_TYPES = ["enum"];
 var RUN_MODE_VALUES = ["development", "production"];
 var DB_ID_MODE_VALUES = ["timeId", "autoId"];
 
@@ -10542,6 +10549,18 @@ function isNullable(value, extraValues = []) {
   }
   return false;
 }
+function isMinLengthString(value, minLength) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  if (!Number.isFinite(minLength)) {
+    return false;
+  }
+  if (minLength <= 0) {
+    return true;
+  }
+  return value.trim().length >= minLength;
+}
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
@@ -10782,6 +10801,22 @@ function sanitizeLogObject(obj, options) {
 }
 
 // utils/util.js
+function canConvertToNumber(value) {
+  const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+  const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
+  if (value > maxSafe || value < minSafe) {
+    return null;
+  }
+  const asNumber = Number(value);
+  if (!Number.isSafeInteger(asNumber)) {
+    return null;
+  }
+  const text = String(asNumber);
+  if (text.includes("e") || text.includes("E")) {
+    return null;
+  }
+  return asNumber;
+}
 function getTypeTag(value) {
   if (value === null)
     return "null";
@@ -10814,6 +10849,67 @@ function normalizePositiveInt(value, fallback, min, max) {
     return max;
   return v;
 }
+function toWordParts(input) {
+  const normalized = String(input).replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[^a-zA-Z0-9]+/g, " ").trim();
+  if (normalized.length === 0) {
+    return [];
+  }
+  return normalized.split(/\s+/).filter((p) => p.length > 0);
+}
+function upperFirst(s) {
+  if (s.length === 0) {
+    return s;
+  }
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function camelCase(input) {
+  const parts = toWordParts(input);
+  if (parts.length === 0) {
+    return "";
+  }
+  const firstPart = parts[0];
+  if (!firstPart) {
+    return "";
+  }
+  const first = firstPart.toLowerCase();
+  const rest = parts.slice(1).map((p) => upperFirst(p.toLowerCase()));
+  return [first].concat(rest).join("");
+}
+function normalizeToWords(input) {
+  return String(input).replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[^a-zA-Z0-9]+/g, " ").trim();
+}
+function snakeCase(input) {
+  const normalized = normalizeToWords(input);
+  if (normalized.length === 0) {
+    return "";
+  }
+  return normalized.split(/\s+/).filter((p) => p.length > 0).map((p) => p.toLowerCase()).join("_");
+}
+var keysToCamel = (obj) => {
+  if (!obj || !isPlainObject2(obj))
+    return obj;
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const camelKey = camelCase(key);
+    result[camelKey] = value;
+  }
+  return result;
+};
+var keysToSnake = (obj) => {
+  if (!obj || !isPlainObject2(obj))
+    return obj;
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const snakeKey = snakeCase(key);
+    result[snakeKey] = value;
+  }
+  return result;
+};
+var arrayKeysToCamel = (arr) => {
+  if (!arr || !Array.isArray(arr))
+    return arr;
+  return arr.map((item) => keysToCamel(item));
+};
 function genShortId() {
   const timePart = Date.now().toString(36);
   let rand = "";
@@ -10825,6 +10921,7 @@ function genShortId() {
 
 // lib/logger.js
 var INITIAL_CWD = process.cwd();
+var RUNTIME_LOG_DIR = nodePathResolve(INITIAL_CWD, "logs");
 var BUILTIN_SENSITIVE_KEYS = ["*password*", "pass", "pwd", "*token*", "access_token", "refresh_token", "accessToken", "refreshToken", "authorization", "cookie", "set-cookie", "*secret*", "apiKey", "api_key", "privateKey", "private_key"];
 var sanitizeOptions = {
   maxStringLen: 200,
@@ -10851,7 +10948,7 @@ var appFileSink = null;
 var errorFileSink = null;
 var config2 = {
   debug: 0,
-  dir: "./logs",
+  dir: RUNTIME_LOG_DIR,
   maxSize: 20,
   runtimeEnv: "production"
 };
@@ -11010,7 +11107,7 @@ class LogFileSink {
   getFilePath(date3, index) {
     const suffix = index > 0 ? `.${index}` : "";
     const filename = this.prefix === "app" ? `${date3}${suffix}.log` : `${this.prefix}.${date3}${suffix}.log`;
-    return nodePathJoin(resolveLogDir(), filename);
+    return nodePathJoin(RUNTIME_LOG_DIR, filename);
   }
   async ensureStreamReady(nextChunkBytes) {
     const date3 = formatYmdHms(Reflect.construct(Date, []), "date");
@@ -11084,21 +11181,13 @@ async function shutdown() {
     errorFileSink = null;
   }
 }
-function resolveLogDir() {
-  const rawDir = config2.dir || "./logs";
-  if (nodePathIsAbsolute(rawDir)) {
-    return rawDir;
-  }
-  return nodePathResolve(INITIAL_CWD, rawDir);
-}
 function ensureLogDirExists() {
-  const dir = resolveLogDir();
   try {
-    if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
+    if (!existsSync(RUNTIME_LOG_DIR)) {
+      mkdirSync(RUNTIME_LOG_DIR, { recursive: true });
     }
   } catch (error48) {
-    throw new Error(`\u521B\u5EFA logs \u76EE\u5F55\u5931\u8D25: ${dir}. ${error48?.message || error48}`, {
+    throw new Error(`\u521B\u5EFA logs \u76EE\u5F55\u5931\u8D25: ${RUNTIME_LOG_DIR}. ${error48?.message || error48}`, {
       cause: error48,
       code: "runtime"
     });
@@ -11108,10 +11197,11 @@ function configure(cfg) {
   shutdown();
   config2 = Object.assign({
     debug: 0,
-    dir: "./logs",
+    dir: RUNTIME_LOG_DIR,
     maxSize: 20,
     runtimeEnv: "production"
   }, cfg);
+  config2.dir = RUNTIME_LOG_DIR;
   if (cfg && !isString(cfg.runtimeEnv) && isString(cfg.runMode)) {
     config2.runtimeEnv = cfg.runMode;
   }
@@ -12322,217 +12412,3735 @@ async function syncMenu(ctx, menus) {
   }
 }
 
-// utils/calcPerfTime.js
-var calcPerfTime = (startTime, endTime = Bun.nanoseconds()) => {
-  const elapsedMs = (endTime - startTime) / 1e6;
-  if (elapsedMs < 1000) {
-    return `${elapsedMs.toFixed(2)} \u6BEB\u79D2`;
-  } else {
-    const elapsedSeconds = elapsedMs / 1000;
-    return `${elapsedSeconds.toFixed(2)} \u79D2`;
-  }
-};
+// scripts/syncDb/index.js
+import { mkdir as mkdir3 } from "fs/promises";
+import { dirname as dirname3, join as join4, resolve as resolve3 } from "path";
 
-// utils/scanFiles.js
-import { existsSync as existsSync2 } from "fs";
+// scripts/syncDb/diff.js
+import { join as join2 } from "path";
 
-// utils/importDefault.js
-import { isAbsolute as isAbsolute2 } from "path";
-import { pathToFileURL } from "url";
-function isWindowsAbsPath(file) {
-  return /^[a-zA-Z]:[\\/]/.test(file);
-}
-function toFileImportUrl(file) {
-  if (isAbsolute2(file) || isWindowsAbsPath(file)) {
-    return pathToFileURL(file).href;
+// scripts/syncDb/transform.js
+function resolveSyncDbEnumInput(columnType) {
+  const matched = /^enum\((.*)\)$/.exec(columnType);
+  if (!matched || !matched[1]) {
+    return "";
   }
-  return file;
-}
-async function importDefault(file, defaultValue) {
-  try {
-    const isJson = file.endsWith(".json");
-    const mod = isJson ? await import(toFileImportUrl(file), { with: { type: "json" } }) : await import(file);
-    const value = mod?.default;
-    if (isNullable(value)) {
-      return defaultValue;
-    }
-    const expectedType = getTypeTag(defaultValue);
-    const actualType = getTypeTag(value);
-    if (expectedType !== actualType) {
-      Logger.warn("importDefault \u5BFC\u5165\u7C7B\u578B\u4E0E\u9ED8\u8BA4\u503C\u4E0D\u4E00\u81F4\uFF0C\u5DF2\u56DE\u9000\u5230\u9ED8\u8BA4\u503C", { file, expectedType, actualType });
-      return defaultValue;
-    }
-    return value;
-  } catch (err) {
-    Logger.warn("importDefault \u5BFC\u5165\u5931\u8D25\uFF0C\u5DF2\u56DE\u9000\u5230\u9ED8\u8BA4\u503C", { err, file });
-    return defaultValue;
+  const values = [];
+  const enumValueRegexp = /'((?:[^'\\]|\\.)*)'/g;
+  let execResult = enumValueRegexp.exec(matched[1]);
+  while (execResult) {
+    const decodedValue = String(execResult[1]).replaceAll("\\'", "'");
+    values.push(decodedValue);
+    execResult = enumValueRegexp.exec(matched[1]);
+  }
+  if (values.length === 0) {
+    return "";
   }
+  return values.join("|");
 }
-
-// utils/scanFiles.js
-async function scanFiles(dir, source, type, pattern) {
-  try {
-    const glob = new Bun.Glob(pattern);
-    if (!existsSync2(dir))
-      return [];
-    const results = [];
-    const files = await glob.scan({
-      cwd: dir,
-      onlyFiles: true,
-      absolute: true,
-      followSymlinks: true
-    });
-    for await (const file of files) {
-      const filePath = normalize(file);
-      const parsedFile = parse5(filePath);
-      const fileName = parsedFile.name;
-      const parsedRelativePath = parse5(relative(dir, filePath));
-      const relativePath = parsedRelativePath.dir ? join(parsedRelativePath.dir, parsedRelativePath.name) : parsedRelativePath.name;
-      if (relativePath.split("/").some((part) => part.startsWith("_")))
-        continue;
-      const content = await importDefault(filePath, {});
-      const contentObj = isPlainObject2(content) ? content : {};
-      const base = {
-        source,
-        type,
-        filePath,
-        relativePath,
-        fileName,
-        apiPath: `/api/${source}/${relativePath}`
-      };
-      if (type === "table") {
-        base["fieldsDef"] = contentObj;
-      }
-      if (type === "api") {
-        base["name"] = "";
-      }
-      if (type !== "table") {
-        for (const [key, value] of Object.entries(contentObj)) {
-          if (base[key])
-            continue;
-          base[key] = value;
-        }
-      }
-      results.push(base);
+function resolveSyncDbInputByColumn(columnMeta) {
+  const dataType = String(columnMeta.dataType || "").toLowerCase();
+  const columnType = String(columnMeta.columnType || "").toLowerCase();
+  if (ENUM_KIND_TYPES.includes(dataType)) {
+    const enumInput = resolveSyncDbEnumInput(columnType);
+    if (isNonEmptyString(enumInput)) {
+      return enumInput;
     }
-    return results;
-  } catch (error48) {
-    throw new Error(`\u626B\u63CF\u5931\u8D25: source=${source} type=${type} dir=${dir} pattern=${pattern}`, {
-      cause: error48,
-      code: "runtime"
-    });
+    return "string";
   }
-}
-
-// utils/scanSources.js
-var scanSources = async () => {
-  const apis = [];
-  const plugins = [];
-  const hooks = [];
-  const tables = [];
-  const allCoreTables = await scanFiles(coreTableDir, "core", "table", "*.json");
-  for (const item of allCoreTables) {
-    tables.push(item);
+  if (JSON_KIND_TYPES.includes(dataType)) {
+    return "json";
   }
-  const allAppTables = await scanFiles(appTableDir, "app", "table", "*.json");
-  for (const item of allAppTables) {
-    tables.push(item);
+  if (INT_KIND_TYPES.includes(dataType)) {
+    return "integer";
   }
-  const allCorePlugins = await scanFiles(corePluginDir, "core", "plugin", "*.js");
-  for (const item of allCorePlugins) {
-    plugins.push(item);
+  if (DECIMAL_KIND_TYPES.includes(dataType) || FLOAT_KIND_TYPES.includes(dataType)) {
+    return "number";
   }
-  const allAppPlugins = await scanFiles(appPluginDir, "app", "plugin", "*.js");
-  for (const item of allAppPlugins) {
-    plugins.push(item);
+  if (STRING_KIND_TYPES.includes(dataType) || TEXT_KIND_TYPES.includes(dataType)) {
+    if (dataType === "char") {
+      return "char";
+    }
+    return "string";
   }
-  const allCoreHooks = await scanFiles(coreHookDir, "core", "hook", "*.js");
-  for (const item of allCoreHooks) {
-    hooks.push(item);
+  if (dataType.includes("date") || dataType.includes("time") || dataType === "year") {
+    return "string";
   }
-  const allAppHooks = await scanFiles(appHookDir, "app", "hook", "*.js");
-  for (const item of allAppHooks) {
-    hooks.push(item);
+  if (dataType === "bit" || dataType === "boolean") {
+    return "integer";
   }
-  const allCoreApis = await scanFiles(coreApiDir, "core", "api", "**/*.js");
-  for (const item of allCoreApis) {
-    apis.push(item);
+  return "string";
+}
+function resolveSyncDbMaxByColumn(columnMeta) {
+  const dataType = String(columnMeta.dataType || "").toLowerCase();
+  if (!(STRING_KIND_TYPES.includes(dataType) || TEXT_KIND_TYPES.includes(dataType))) {
+    return null;
   }
-  const allAppApis = await scanFiles(appApiDir, "app", "api", "**/*.js");
-  for (const item of allAppApis) {
-    apis.push(item);
+  if (!isNumber(columnMeta.charLength)) {
+    return null;
+  }
+  if (!Number.isFinite(columnMeta.charLength)) {
+    return null;
+  }
+  if (columnMeta.charLength <= 0 || columnMeta.charLength > Number.MAX_SAFE_INTEGER) {
+    return null;
+  }
+  return Math.floor(columnMeta.charLength);
+}
+function toSyncDbFieldDef(columnMeta) {
+  const fieldName = camelCase(String(columnMeta.columnName || ""));
+  const fieldDisplayName = isNonEmptyString(columnMeta.columnComment) ? String(columnMeta.columnComment).trim() : fieldName;
+  const fieldInput = resolveSyncDbInputByColumn(columnMeta);
+  const fieldMax = resolveSyncDbMaxByColumn(columnMeta);
+  const fieldDef = {
+    name: fieldDisplayName,
+    input: fieldInput
+  };
+  if (isNumber(fieldMax)) {
+    fieldDef.max = fieldMax;
   }
   return {
-    hooks,
-    plugins,
-    apis,
-    tables
+    fieldName,
+    fieldDef
   };
-};
-
-// utils/deepMerge.js
-function clone2(value) {
-  return structuredClone(value);
 }
-function concat(targetArr, sourceArr, cloneTargetItems) {
-  const nextArr = [];
-  if (cloneTargetItems) {
-    for (const item of targetArr) {
-      nextArr.push(clone2(item));
+
+// scripts/syncDb/diff.js
+function groupSyncDbColumns(rows) {
+  const grouped = new Map;
+  for (const row of rows) {
+    const tableName = String(row.tableName || "");
+    if (!isNonEmptyString(tableName)) {
+      continue;
     }
-  } else {
-    for (const item of targetArr) {
-      nextArr.push(item);
+    if (tableName.toLowerCase().startsWith("befly_")) {
+      continue;
     }
+    if (!grouped.has(tableName)) {
+      grouped.set(tableName, []);
+    }
+    const tableColumns = grouped.get(tableName);
+    tableColumns.push({
+      tableName,
+      tableComment: row.tableComment,
+      columnName: row.columnName,
+      dataType: row.dataType,
+      columnType: row.columnType,
+      charLength: row.charLength,
+      columnComment: row.columnComment,
+      ordinalPosition: row.ordinalPosition
+    });
   }
-  for (const item of sourceArr) {
-    nextArr.push(clone2(item));
-  }
-  return nextArr;
-}
-function mergeValue(baseValue, incomingValue) {
-  if (Array.isArray(baseValue) && Array.isArray(incomingValue)) {
-    return concat(baseValue, incomingValue, false);
-  }
-  if (isPlainObject2(baseValue) && isPlainObject2(incomingValue)) {
-    mergeInto(baseValue, incomingValue);
-    return baseValue;
-  }
-  return clone2(incomingValue);
+  return grouped;
 }
-function mergeInto(base, incoming) {
-  for (const key of Object.keys(incoming)) {
-    const incomingValue = incoming[key];
-    if (incomingValue === undefined) {
+function buildSyncDbDiff(groupedDbColumns, existingTableMap) {
+  const missingTables = [];
+  const missingFieldsByTable = {};
+  for (const [tableName, columns] of groupedDbColumns.entries()) {
+    const tableFileName = camelCase(tableName);
+    const existing = existingTableMap.get(String(tableFileName).toLowerCase());
+    if (!existing) {
+      missingTables.push({
+        tableName,
+        tableFileName,
+        columns
+      });
       continue;
     }
-    base[key] = mergeValue(base[key], incomingValue);
+    const existingFields = isPlainObject2(existing.tableDef) ? existing.tableDef : {};
+    const missingFields = [];
+    for (const columnMeta of columns) {
+      const fieldInfo = toSyncDbFieldDef(columnMeta);
+      if (Object.prototype.hasOwnProperty.call(existingFields, fieldInfo.fieldName)) {
+        continue;
+      }
+      missingFields.push({
+        tableName,
+        tableFileName,
+        dbColumnName: columnMeta.columnName,
+        dbDataType: columnMeta.dataType,
+        dbColumnType: columnMeta.columnType,
+        dbCharLength: columnMeta.charLength,
+        fieldName: fieldInfo.fieldName,
+        fieldDef: fieldInfo.fieldDef
+      });
+    }
+    if (missingFields.length > 0) {
+      missingFieldsByTable[tableFileName] = {
+        tableName,
+        tableFileName,
+        filePath: existing.filePath,
+        fields: missingFields
+      };
+    }
   }
-  return base;
+  return {
+    missingTables,
+    missingFieldsByTable
+  };
 }
-function deepMerge(source, target) {
-  if (Array.isArray(source) && Array.isArray(target)) {
-    const base = clone2(source);
-    const incoming = clone2(target);
-    return concat(base, incoming, false);
+async function applySyncDbDiff(diff, tablesDir, existingTableMap) {
+  let createdTableFileCount = 0;
+  let appendedFieldCount = 0;
+  for (const missingTable of diff.missingTables) {
+    const tableDef = {};
+    for (const columnMeta of missingTable.columns) {
+      const fieldInfo = toSyncDbFieldDef(columnMeta);
+      tableDef[fieldInfo.fieldName] = fieldInfo.fieldDef;
+    }
+    const filePath = join2(tablesDir, `${missingTable.tableFileName}.json`);
+    await Bun.write(filePath, `${JSON.stringify(tableDef, null, 4)}
+`);
+    createdTableFileCount = createdTableFileCount + 1;
   }
-  if (isPlainObject2(source) && isPlainObject2(target)) {
-    const base = clone2(source);
-    const incoming = clone2(target);
-    return mergeInto(base, incoming);
+  for (const [tableFileName, tableInfo] of Object.entries(diff.missingFieldsByTable)) {
+    const existing = existingTableMap.get(String(tableFileName).toLowerCase());
+    const targetFilePath = existing?.filePath || join2(tablesDir, `${tableFileName}.json`);
+    const currentTableDef = isPlainObject2(existing?.tableDef) ? existing.tableDef : {};
+    for (const fieldItem of tableInfo.fields) {
+      currentTableDef[fieldItem.fieldName] = fieldItem.fieldDef;
+      appendedFieldCount = appendedFieldCount + 1;
+    }
+    await Bun.write(targetFilePath, `${JSON.stringify(currentTableDef, null, 4)}
+`);
   }
-  throw new Error("deepMerge: source/target \u5FC5\u987B\u540C\u4E3A\u6570\u7EC4\u6216\u540C\u4E3A\u666E\u901A\u5BF9\u8C61", {
-    cause: null,
-    code: "validation",
-    subsystem: "utils",
-    operation: "deepMerge"
-  });
+  return {
+    createdTableFileCount,
+    appendedFieldCount
+  };
+}
+function countSyncDbMissingFields(diff) {
+  let missingFieldCount = 0;
+  for (const item of Object.values(diff.missingFieldsByTable)) {
+    missingFieldCount = missingFieldCount + item.fields.length;
+  }
+  return missingFieldCount;
 }
 
-// utils/sortModules.js
-function sortModules(items) {
-  const result = [];
-  const visited = new Set;
+// scripts/syncDb/context.js
+import { mkdir } from "fs/promises";
+import { basename as basename2, resolve as resolve2, join as join3 } from "path";
+
+// utils/fieldClear.js
+function isObject2(val) {
+  return val !== null && typeof val === "object" && !Array.isArray(val);
+}
+function isArray(val) {
+  return Array.isArray(val);
+}
+function fieldClear(data, options = {}) {
+  const { pickKeys, omitKeys, keepValues, excludeValues, keepMap } = options;
+  const filterObj = (obj) => {
+    let result = {};
+    let keys = Object.keys(obj);
+    if (pickKeys && pickKeys.length) {
+      keys = keys.filter((k) => pickKeys.includes(k));
+    }
+    if (omitKeys && omitKeys.length) {
+      keys = keys.filter((k) => !omitKeys.includes(k));
+    }
+    for (const key of keys) {
+      const value = obj[key];
+      if (keepMap && key in keepMap) {
+        if (Object.is(keepMap[key], value)) {
+          result[key] = value;
+          continue;
+        }
+      }
+      if (keepValues && keepValues.length && !keepValues.includes(value)) {
+        continue;
+      }
+      if (excludeValues && excludeValues.length && excludeValues.includes(value)) {
+        continue;
+      }
+      result[key] = value;
+    }
+    return result;
+  };
+  if (isArray(data)) {
+    return data.map((item) => isObject2(item) ? filterObj(item) : item).filter((item) => {
+      if (isObject2(item)) {
+        return Object.keys(item).length > 0;
+      }
+      return true;
+    });
+  }
+  if (isObject2(data)) {
+    return filterObj(data);
+  }
+  return data;
+}
+
+// lib/sqlBuilder/check.js
+class SqlCheck {
+  static assertNoUndefinedParam(value, label) {
+    if (value === undefined) {
+      throw new Error(`${label} \u4E0D\u80FD\u4E3A undefined`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+  static startsWithQuote(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith("`") || trimmed.startsWith('"');
+  }
+  static isQuotedIdentPaired(value) {
+    const trimmed = value.trim();
+    if (!isMinLengthString(trimmed, 2)) {
+      return false;
+    }
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if (first === "`" && last === "`") {
+      return true;
+    }
+    if (first === '"' && last === '"') {
+      return true;
+    }
+    return false;
+  }
+  static assertPairedQuotedIdentIfStartsWithQuote(value, label) {
+    if (SqlCheck.startsWithQuote(value) && !SqlCheck.isQuotedIdentPaired(value)) {
+      throw new Error(`${label} \u5F15\u7528\u4E0D\u5B8C\u6574\uFF0C\u8BF7\u4F7F\u7528\u6210\u5BF9\u7684 \`...\` \u6216 "..." (value: ${value})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+  static assertSafeIdentifierPart(part, kind) {
+    if (!SqlCheck.SAFE_IDENTIFIER_RE.test(part)) {
+      throw new Error(`\u65E0\u6548\u7684 ${kind} \u6807\u8BC6\u7B26: ${part}`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+  static assertSafeAlias(aliasPart) {
+    if (SqlCheck.isQuotedIdentPaired(aliasPart)) {
+      return;
+    }
+    if (!SqlCheck.SAFE_IDENTIFIER_RE.test(aliasPart)) {
+      throw new Error(`\u65E0\u6548\u7684\u5B57\u6BB5\u522B\u540D: ${aliasPart}`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+  static assertNoExprField(field) {
+    if (!isNonEmptyString(field)) {
+      return;
+    }
+    const trimmed = field.trim();
+    if (trimmed.includes("(") || trimmed.includes(")")) {
+      throw new Error(`\u5B57\u6BB5\u5305\u542B\u51FD\u6570/\u8868\u8FBE\u5F0F\uFF0C\u8BF7\u4F7F\u7528 selectRaw/whereRaw (field: ${trimmed})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+  static assertBatchInsertRowsConsistent(rows, options) {
+    if (!Array.isArray(rows)) {
+      throw new Error("\u6279\u91CF\u63D2\u5165 rows \u5FC5\u987B\u662F\u6570\u7EC4", {
+        cause: null,
+        code: "validation"
+      });
+    }
+    if (rows.length === 0) {
+      throw new Error(`\u63D2\u5165\u6570\u636E\u4E0D\u80FD\u4E3A\u7A7A (table: ${options.table})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const first = rows[0];
+    if (!first || typeof first !== "object" || Array.isArray(first)) {
+      throw new Error(`\u6279\u91CF\u63D2\u5165\u7684\u6BCF\u4E00\u884C\u5FC5\u987B\u662F\u5BF9\u8C61 (table: ${options.table}, rowIndex: 0)`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const fields = Object.keys(first);
+    if (fields.length === 0) {
+      throw new Error(`\u63D2\u5165\u6570\u636E\u5FC5\u987B\u81F3\u5C11\u6709\u4E00\u4E2A\u5B57\u6BB5 (table: ${options.table})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const fieldSet = new Set(fields);
+    for (let i = 0;i < rows.length; i++) {
+      const row = rows[i];
+      if (!row || typeof row !== "object" || Array.isArray(row)) {
+        throw new Error(`\u6279\u91CF\u63D2\u5165\u7684\u6BCF\u4E00\u884C\u5FC5\u987B\u662F\u5BF9\u8C61 (table: ${options.table}, rowIndex: ${i})`, {
+          cause: null,
+          code: "validation"
+        });
+      }
+      const rowKeys = Object.keys(row);
+      if (rowKeys.length !== fields.length) {
+        throw new Error(`\u6279\u91CF\u63D2\u5165\u6BCF\u884C\u5B57\u6BB5\u5FC5\u987B\u4E00\u81F4 (table: ${options.table}, rowIndex: ${i})`, {
+          cause: null,
+          code: "validation"
+        });
+      }
+      for (const key of rowKeys) {
+        if (!fieldSet.has(key)) {
+          throw new Error(`\u6279\u91CF\u63D2\u5165\u6BCF\u884C\u5B57\u6BB5\u5FC5\u987B\u4E00\u81F4 (table: ${options.table}, rowIndex: ${i}, extraField: ${key})`, {
+            cause: null,
+            code: "validation"
+          });
+        }
+      }
+      for (const field of fields) {
+        if (!(field in row)) {
+          throw new Error(`\u6279\u91CF\u63D2\u5165\u7F3A\u5C11\u5B57\u6BB5 (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+            cause: null,
+            code: "validation"
+          });
+        }
+        SqlCheck.assertNoUndefinedParam(row[field], `\u6279\u91CF\u63D2\u5165\u5B57\u6BB5\u503C (table: ${options.table}, rowIndex: ${i}, field: ${field})`);
+      }
+    }
+    return fields;
+  }
+}
+SqlCheck.SAFE_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+// lib/sqlBuilder/errors.js
+var SqlErrors = {
+  QUOTE_IDENT_NEED_STRING: (identifier) => `quoteIdent \u9700\u8981\u5B57\u7B26\u4E32\u7C7B\u578B\u6807\u8BC6\u7B26 (identifier: ${String(identifier)})`,
+  IDENT_EMPTY: "SQL \u6807\u8BC6\u7B26\u4E0D\u80FD\u4E3A\u7A7A",
+  FIELD_EXPR_NOT_ALLOWED: (field) => `\u5B57\u6BB5\u5305\u542B\u51FD\u6570/\u8868\u8FBE\u5F0F\uFF0C\u8BF7\u4F7F\u7528 selectRaw/whereRaw (field: ${field})`,
+  FIELD_INVALID: (field) => `\u5B57\u6BB5\u683C\u5F0F\u975E\u6CD5\uFF0C\u8BF7\u4F7F\u7528\u7B80\u5355\u5B57\u6BB5\u540D\u6216\u5B89\u5168\u5F15\u7528\uFF0C\u590D\u6742\u8868\u8FBE\u5F0F\u8BF7\u4F7F\u7528 selectRaw/whereRaw (field: ${field})`,
+  FROM_EMPTY: "FROM \u8868\u540D\u4E0D\u80FD\u4E3A\u7A7A",
+  FROM_NEED_NON_EMPTY: (table) => `FROM \u8868\u540D\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32 (table: ${String(table)})`,
+  FROM_REQUIRED: "FROM \u8868\u540D\u662F\u5FC5\u9700\u7684",
+  COUNT_NEED_FROM: "COUNT \u9700\u8981 FROM \u8868\u540D",
+  TABLE_REF_TOO_MANY_PARTS: (table) => `\u4E0D\u652F\u6301\u7684\u8868\u5F15\u7528\u683C\u5F0F\uFF08\u5305\u542B\u8FC7\u591A\u7247\u6BB5\uFF09\u3002\u8BF7\u4F7F\u7528 fromRaw \u663E\u5F0F\u4F20\u5165\u590D\u6742\u8868\u8FBE\u5F0F (table: ${table})`,
+  TABLE_REF_SCHEMA_TOO_DEEP: (table) => `\u4E0D\u652F\u6301\u7684\u8868\u5F15\u7528\u683C\u5F0F\uFF08schema \u5C42\u7EA7\u8FC7\u6DF1\uFF09\u3002\u8BF7\u4F7F\u7528 fromRaw (table: ${table})`,
+  SCHEMA_QUOTE_NOT_PAIRED: (schema) => `schema \u6807\u8BC6\u7B26\u5F15\u7528\u4E0D\u5B8C\u6574\uFF0C\u8BF7\u4F7F\u7528\u6210\u5BF9\u7684 \`...\` \u6216 "..." (schema: ${schema})`,
+  TABLE_QUOTE_NOT_PAIRED: (tableName) => `table \u6807\u8BC6\u7B26\u5F15\u7528\u4E0D\u5B8C\u6574\uFF0C\u8BF7\u4F7F\u7528\u6210\u5BF9\u7684 \`...\` \u6216 "..." (table: ${tableName})`,
+  SELECT_FIELDS_INVALID: "SELECT \u5B57\u6BB5\u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6216\u6570\u7EC4",
+  SELECT_RAW_NEED_NON_EMPTY: (expr) => `selectRaw \u9700\u8981\u975E\u7A7A\u5B57\u7B26\u4E32 (expr: ${String(expr)})`,
+  FROM_RAW_NEED_NON_EMPTY: (tableExpr) => `fromRaw \u9700\u8981\u975E\u7A7A\u5B57\u7B26\u4E32 (tableExpr: ${String(tableExpr)})`,
+  WHERE_RAW_NEED_NON_EMPTY: (sql) => `whereRaw \u9700\u8981\u975E\u7A7A\u5B57\u7B26\u4E32 (sql: ${String(sql)})`,
+  WHERE_VALUE_REQUIRED: "where(field, value) \u4E0D\u5141\u8BB8\u7701\u7565 value\u3002\u82E5\u9700\u4F20\u5165\u539F\u59CB WHERE\uFF0C\u8BF7\u4F7F\u7528 whereRaw",
+  JOIN_NEED_STRING: (table, on) => `JOIN \u8868\u540D\u548C\u6761\u4EF6\u5FC5\u987B\u662F\u5B57\u7B26\u4E32 (table: ${String(table)}, on: ${String(on)})`,
+  ORDER_BY_NEED_ARRAY: 'orderBy \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4\uFF0C\u683C\u5F0F\u4E3A "\u5B57\u6BB5#\u65B9\u5411"',
+  ORDER_BY_ITEM_NEED_HASH: (item) => `orderBy \u5B57\u6BB5\u5FC5\u987B\u662F "\u5B57\u6BB5#\u65B9\u5411" \u683C\u5F0F\u7684\u5B57\u7B26\u4E32\uFF08\u4F8B\u5982\uFF1A"name#ASC", "id#DESC"\uFF09 (item: ${String(item)})`,
+  ORDER_BY_FIELD_EMPTY: (item) => `orderBy \u4E2D\u5B57\u6BB5\u540D\u4E0D\u80FD\u4E3A\u7A7A (item: ${item})`,
+  ORDER_BY_DIR_INVALID: (direction) => `ORDER BY \u65B9\u5411\u5FC5\u987B\u662F ASC \u6216 DESC (direction: ${direction})`,
+  LIMIT_MUST_NON_NEGATIVE: (count) => `LIMIT \u6570\u91CF\u5FC5\u987B\u662F\u975E\u8D1F\u6570 (count: ${String(count)})`,
+  OFFSET_MUST_NON_NEGATIVE: (offset) => `OFFSET \u5FC5\u987B\u662F\u975E\u8D1F\u6570 (offset: ${String(offset)})`,
+  OFFSET_COUNT_MUST_NON_NEGATIVE: (count) => `OFFSET \u5FC5\u987B\u662F\u975E\u8D1F\u6570 (count: ${String(count)})`,
+  INSERT_NEED_TABLE: (table) => `INSERT \u9700\u8981\u8868\u540D (table: ${String(table)})`,
+  INSERT_NEED_DATA: (table, data) => `INSERT \u9700\u8981\u6570\u636E (table: ${String(table)}, data: ${JSON.stringify(data)})`,
+  INSERT_NEED_AT_LEAST_ONE_FIELD: (table) => `\u63D2\u5165\u6570\u636E\u5FC5\u987B\u81F3\u5C11\u6709\u4E00\u4E2A\u5B57\u6BB5 (table: ${table})`,
+  UPDATE_NEED_TABLE: "UPDATE \u9700\u8981\u8868\u540D",
+  UPDATE_NEED_OBJECT: "UPDATE \u9700\u8981\u6570\u636E\u5BF9\u8C61",
+  UPDATE_NEED_AT_LEAST_ONE_FIELD: "\u66F4\u65B0\u6570\u636E\u5FC5\u987B\u81F3\u5C11\u6709\u4E00\u4E2A\u5B57\u6BB5",
+  UPDATE_NEED_WHERE: "\u4E3A\u5B89\u5168\u8D77\u89C1\uFF0CUPDATE \u9700\u8981 WHERE \u6761\u4EF6",
+  DELETE_NEED_TABLE: "DELETE \u9700\u8981\u8868\u540D",
+  DELETE_NEED_WHERE: "\u4E3A\u5B89\u5168\u8D77\u89C1\uFF0CDELETE \u9700\u8981 WHERE \u6761\u4EF6",
+  TO_DELETE_IN_NEED_TABLE: (table) => `toDeleteInSql \u9700\u8981\u975E\u7A7A\u8868\u540D (table: ${String(table)})`,
+  TO_DELETE_IN_NEED_ID_FIELD: (idField) => `toDeleteInSql \u9700\u8981\u975E\u7A7A idField (idField: ${String(idField)})`,
+  TO_DELETE_IN_NEED_IDS: "toDeleteInSql \u9700\u8981 ids \u6570\u7EC4",
+  TO_UPDATE_CASE_NEED_TABLE: (table) => `toUpdateCaseByIdSql \u9700\u8981\u975E\u7A7A\u8868\u540D (table: ${String(table)})`,
+  TO_UPDATE_CASE_NEED_ID_FIELD: (idField) => `toUpdateCaseByIdSql \u9700\u8981\u975E\u7A7A idField (idField: ${String(idField)})`,
+  TO_UPDATE_CASE_NEED_ROWS: "toUpdateCaseByIdSql \u9700\u8981 rows \u6570\u7EC4",
+  TO_UPDATE_CASE_NEED_FIELDS: "toUpdateCaseByIdSql \u9700\u8981 fields \u6570\u7EC4",
+  IN_NEED_ARRAY: (operator) => `$in \u64CD\u4F5C\u7B26\u7684\u503C\u5FC5\u987B\u662F\u6570\u7EC4 (operator: ${operator})`,
+  IN_NEED_NON_EMPTY: "$in \u64CD\u4F5C\u7B26\u7684\u6570\u7EC4\u4E0D\u80FD\u4E3A\u7A7A\u3002\u63D0\u793A\uFF1A\u7A7A\u6570\u7EC4\u4F1A\u5BFC\u81F4\u67E5\u8BE2\u6C38\u8FDC\u4E0D\u5339\u914D\u4EFB\u4F55\u8BB0\u5F55\uFF0C\u8FD9\u901A\u5E38\u4E0D\u662F\u9884\u671F\u884C\u4E3A\u3002\u8BF7\u68C0\u67E5\u67E5\u8BE2\u6761\u4EF6\u6216\u79FB\u9664\u8BE5\u5B57\u6BB5\u3002",
+  NIN_NEED_ARRAY: (operator) => `$nin/$notIn \u64CD\u4F5C\u7B26\u7684\u503C\u5FC5\u987B\u662F\u6570\u7EC4 (operator: ${operator})`,
+  NIN_NEED_NON_EMPTY: "$nin/$notIn \u64CD\u4F5C\u7B26\u7684\u6570\u7EC4\u4E0D\u80FD\u4E3A\u7A7A\u3002\u63D0\u793A\uFF1A\u7A7A\u6570\u7EC4\u4F1A\u5BFC\u81F4\u67E5\u8BE2\u5339\u914D\u6240\u6709\u8BB0\u5F55\uFF0C\u8FD9\u901A\u5E38\u4E0D\u662F\u9884\u671F\u884C\u4E3A\u3002\u8BF7\u68C0\u67E5\u67E5\u8BE2\u6761\u4EF6\u6216\u79FB\u9664\u8BE5\u5B57\u6BB5\u3002"
+};
+
+// lib/sqlBuilder/util.js
+function resolveQuoteIdent(options) {
+  if (options && options.quoteIdent) {
+    return options.quoteIdent;
+  }
+  return (identifier) => {
+    if (!isString(identifier)) {
+      throw new Error(SqlErrors.QUOTE_IDENT_NEED_STRING(identifier), {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const trimmed = identifier.trim();
+    if (!trimmed) {
+      throw new Error(SqlErrors.IDENT_EMPTY, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const escaped = trimmed.replace(/`/g, "``");
+    return `\`${escaped}\``;
+  };
+}
+function isQuotedIdent(value) {
+  return SqlCheck.isQuotedIdentPaired(value);
+}
+function startsWithQuote(value) {
+  return SqlCheck.startsWithQuote(value);
+}
+function escapeField(field, quoteIdent) {
+  if (!isString(field)) {
+    return field;
+  }
+  const trimmed = field.trim();
+  SqlCheck.assertPairedQuotedIdentIfStartsWithQuote(trimmed, "\u5B57\u6BB5\u6807\u8BC6\u7B26");
+  if (trimmed === "*" || isQuotedIdent(trimmed)) {
+    return trimmed;
+  }
+  try {
+    SqlCheck.assertNoExprField(trimmed);
+  } catch {
+    throw new Error(SqlErrors.FIELD_EXPR_NOT_ALLOWED(trimmed), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (trimmed.toUpperCase().includes(" AS ")) {
+    const parts = trimmed.split(/\s+AS\s+/i);
+    if (parts.length !== 2) {
+      throw new Error(SqlErrors.FIELD_INVALID(trimmed), {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const fieldPart = parts[0];
+    const aliasPart = parts[1];
+    const cleanFieldPart = fieldPart.trim();
+    const cleanAliasPart = aliasPart.trim();
+    SqlCheck.assertSafeAlias(cleanAliasPart);
+    return `${escapeField(cleanFieldPart, quoteIdent)} AS ${cleanAliasPart}`;
+  }
+  if (trimmed.includes(".")) {
+    const parts = trimmed.split(".");
+    return parts.map((part) => {
+      const cleanPart = part.trim();
+      if (cleanPart === "*" || isQuotedIdent(cleanPart)) {
+        return cleanPart;
+      }
+      SqlCheck.assertPairedQuotedIdentIfStartsWithQuote(cleanPart, "\u5B57\u6BB5\u6807\u8BC6\u7B26");
+      return quoteIdent(cleanPart);
+    }).join(".");
+  }
+  return quoteIdent(trimmed);
+}
+function escapeTable(table, quoteIdent) {
+  if (!isString(table)) {
+    return table;
+  }
+  const trimmed = table.trim();
+  if (isQuotedIdent(trimmed)) {
+    return trimmed;
+  }
+  const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
+  if (parts.length === 0) {
+    throw new Error(SqlErrors.FROM_EMPTY, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (parts.length > 2) {
+    throw new Error(SqlErrors.TABLE_REF_TOO_MANY_PARTS(trimmed), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const namePart = parts[0].trim();
+  const aliasPart = parts.length === 2 ? parts[1].trim() : null;
+  const nameSegments = namePart.split(".");
+  if (nameSegments.length > 2) {
+    throw new Error(SqlErrors.TABLE_REF_SCHEMA_TOO_DEEP(trimmed), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  let escapedName = "";
+  if (nameSegments.length === 2) {
+    const schemaRaw = nameSegments[0];
+    const tableNameRaw = nameSegments[1];
+    const schema = schemaRaw.trim();
+    const tableName = tableNameRaw.trim();
+    const escapedSchema = isQuotedIdent(schema) ? schema : (() => {
+      if (startsWithQuote(schema) && !isQuotedIdent(schema)) {
+        throw new Error(SqlErrors.SCHEMA_QUOTE_NOT_PAIRED(schema), {
+          cause: null,
+          code: "validation"
+        });
+      }
+      SqlCheck.assertSafeIdentifierPart(schema, "schema");
+      return quoteIdent(schema);
+    })();
+    const escapedTableName = isQuotedIdent(tableName) ? tableName : (() => {
+      if (startsWithQuote(tableName) && !isQuotedIdent(tableName)) {
+        throw new Error(SqlErrors.TABLE_QUOTE_NOT_PAIRED(tableName), {
+          cause: null,
+          code: "validation"
+        });
+      }
+      SqlCheck.assertSafeIdentifierPart(tableName, "table");
+      return quoteIdent(tableName);
+    })();
+    escapedName = `${escapedSchema}.${escapedTableName}`;
+  } else {
+    const tableNameRaw = nameSegments[0];
+    const tableName = tableNameRaw.trim();
+    if (isQuotedIdent(tableName)) {
+      escapedName = tableName;
+    } else {
+      if (startsWithQuote(tableName) && !isQuotedIdent(tableName)) {
+        throw new Error(SqlErrors.TABLE_QUOTE_NOT_PAIRED(tableName), {
+          cause: null,
+          code: "validation"
+        });
+      }
+      SqlCheck.assertSafeIdentifierPart(tableName, "table");
+      escapedName = quoteIdent(tableName);
+    }
+  }
+  if (aliasPart) {
+    SqlCheck.assertSafeIdentifierPart(aliasPart, "alias");
+    return `${escapedName} ${aliasPart}`;
+  }
+  return escapedName;
+}
+function validateParam(value) {
+  SqlCheck.assertNoUndefinedParam(value, "SQL \u53C2\u6570\u503C");
+}
+function normalizeLimitValue(count, offset) {
+  if (typeof count !== "number" || count < 0) {
+    throw new Error(SqlErrors.LIMIT_MUST_NON_NEGATIVE(count), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const limitValue = Math.floor(count);
+  let offsetValue = null;
+  if (!isNullable(offset)) {
+    if (typeof offset !== "number" || offset < 0) {
+      throw new Error(SqlErrors.OFFSET_MUST_NON_NEGATIVE(offset), {
+        cause: null,
+        code: "validation"
+      });
+    }
+    offsetValue = Math.floor(offset);
+  }
+  return { limitValue, offsetValue };
+}
+function normalizeOffsetValue(count) {
+  if (typeof count !== "number" || count < 0) {
+    throw new Error(SqlErrors.OFFSET_COUNT_MUST_NON_NEGATIVE(count), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  return Math.floor(count);
+}
+function toSqlParams(params) {
+  if (isNullable(params)) {
+    return [];
+  }
+  if (!Array.isArray(params)) {
+    throw new Error(`SQL \u53C2\u6570\u5FC5\u987B\u662F\u6570\u7EC4\uFF0C\u5F53\u524D\u7C7B\u578B: ${typeof params}`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const out = [];
+  for (const value of params) {
+    if (value === undefined) {
+      throw new Error("SQL \u53C2\u6570\u4E0D\u80FD\u4E3A undefined", {
+        cause: null,
+        code: "validation"
+      });
+    }
+    if (typeof value === "bigint") {
+      out.push(value.toString());
+      continue;
+    }
+    out.push(value);
+  }
+  return out;
+}
+
+// lib/sqlBuilder/parser.js
+function createWhereRoot() {
+  return { type: "group", join: "AND", items: [] };
+}
+function appendSelectItems(list, fields) {
+  if (Array.isArray(fields)) {
+    for (const field of fields) {
+      list.push({ type: "field", value: field });
+    }
+    return;
+  }
+  if (isString(fields)) {
+    list.push({ type: "field", value: fields });
+    return;
+  }
+  throw new Error(SqlErrors.SELECT_FIELDS_INVALID, {
+    cause: null,
+    code: "validation"
+  });
+}
+function appendSelectRaw(list, expr) {
+  if (!isNonEmptyString(expr)) {
+    throw new Error(SqlErrors.SELECT_RAW_NEED_NON_EMPTY(expr), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  list.push({ type: "raw", value: expr });
+}
+function setFromValue(state, table, isRaw) {
+  if (!isNonEmptyString(table)) {
+    const err = isRaw ? SqlErrors.FROM_RAW_NEED_NON_EMPTY(table) : SqlErrors.FROM_NEED_NON_EMPTY(table);
+    throw new Error(err, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  state.from = { type: isRaw ? "raw" : "table", value: table.trim() };
+}
+function appendJoinItem(list, joinType, table, on) {
+  if (!isString(table) || !isString(on)) {
+    throw new Error(SqlErrors.JOIN_NEED_STRING(table, on), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  list.push({ type: joinType, table, on });
+}
+function appendOrderByItems(list, fields) {
+  if (!Array.isArray(fields)) {
+    throw new Error(SqlErrors.ORDER_BY_NEED_ARRAY, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  for (const item of fields) {
+    if (!isString(item) || !item.includes("#")) {
+      throw new Error(SqlErrors.ORDER_BY_ITEM_NEED_HASH(item), {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const parts = item.split("#");
+    if (parts.length !== 2) {
+      throw new Error(SqlErrors.ORDER_BY_ITEM_NEED_HASH(item), {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const fieldName = parts[0];
+    const direction = parts[1];
+    const cleanField = fieldName.trim();
+    const cleanDir = direction.trim().toUpperCase();
+    if (!cleanField) {
+      throw new Error(SqlErrors.ORDER_BY_FIELD_EMPTY(item), {
+        cause: null,
+        code: "validation"
+      });
+    }
+    if (!["ASC", "DESC"].includes(cleanDir)) {
+      throw new Error(SqlErrors.ORDER_BY_DIR_INVALID(cleanDir), {
+        cause: null,
+        code: "validation"
+      });
+    }
+    list.push({ field: cleanField, dir: cleanDir });
+  }
+}
+function appendGroupByItems(list, field) {
+  if (Array.isArray(field)) {
+    for (const item of field) {
+      if (isString(item)) {
+        list.push(item);
+      }
+    }
+    return;
+  }
+  if (isString(field)) {
+    list.push(field);
+  }
+}
+function appendHavingItems(list, condition) {
+  if (isString(condition)) {
+    list.push(condition);
+  }
+}
+function appendWhereInput(root, conditionOrField, value) {
+  if (conditionOrField && typeof conditionOrField === "object" && !Array.isArray(conditionOrField)) {
+    const node = parseWhereObject(conditionOrField);
+    if (node && node.items.length > 0) {
+      root.items.push(node);
+    }
+    return;
+  }
+  if (isString(conditionOrField)) {
+    if (value === undefined) {
+      throw new Error(SqlErrors.WHERE_VALUE_REQUIRED, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const node = buildOperatorNode(conditionOrField, "=", value);
+    if (node) {
+      root.items.push(node);
+    }
+  }
+}
+function appendWhereRaw(root, sql, params) {
+  if (!isNonEmptyString(sql)) {
+    throw new Error(SqlErrors.WHERE_RAW_NEED_NON_EMPTY(sql), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const paramList = Array.isArray(params) ? params : [];
+  for (const param of paramList) {
+    validateParam(param);
+  }
+  root.items.push({ type: "raw", sql, params: paramList });
+}
+function parseWhereObject(whereObj) {
+  if (!whereObj || typeof whereObj !== "object") {
+    return { type: "group", join: "AND", items: [] };
+  }
+  const group = { type: "group", join: "AND", items: [] };
+  for (const [key, value] of Object.entries(whereObj)) {
+    if (value === undefined) {
+      continue;
+    }
+    if (key === "$and") {
+      if (Array.isArray(value)) {
+        for (const condition of value) {
+          if (condition && typeof condition === "object" && !Array.isArray(condition)) {
+            const sub = parseWhereObject(condition);
+            if (sub.items.length > 0) {
+              if (sub.join === "AND") {
+                for (const item of sub.items) {
+                  group.items.push(item);
+                }
+              } else {
+                group.items.push(sub);
+              }
+            }
+          }
+        }
+      }
+      continue;
+    }
+    if (key === "$or") {
+      if (Array.isArray(value)) {
+        const orGroup = { type: "group", join: "OR", items: [] };
+        for (const condition of value) {
+          if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+            continue;
+          }
+          const sub = parseWhereObject(condition);
+          if (sub.items.length > 0) {
+            orGroup.items.push(sub);
+          }
+        }
+        if (orGroup.items.length > 0) {
+          group.items.push(orGroup);
+        }
+      }
+      continue;
+    }
+    if (key.includes("$")) {
+      const lastDollarIndex = key.lastIndexOf("$");
+      const fieldName = key.substring(0, lastDollarIndex);
+      const operator = "$" + key.substring(lastDollarIndex + 1);
+      const node2 = buildOperatorNode(fieldName, operator, value);
+      if (node2) {
+        group.items.push(node2);
+      }
+      continue;
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      for (const [op, val] of Object.entries(value)) {
+        const node2 = buildOperatorNode(key, op, val);
+        if (node2) {
+          group.items.push(node2);
+        }
+      }
+      continue;
+    }
+    const node = buildOperatorNode(key, "=", value);
+    if (node) {
+      group.items.push(node);
+    }
+  }
+  return group;
+}
+function buildOperatorNode(fieldName, operator, value) {
+  switch (operator) {
+    case "$in":
+      if (!Array.isArray(value)) {
+        throw new Error(SqlErrors.IN_NEED_ARRAY(operator), {
+          cause: null,
+          code: "validation"
+        });
+      }
+      if (value.length === 0) {
+        throw new Error(SqlErrors.IN_NEED_NON_EMPTY, {
+          cause: null,
+          code: "validation"
+        });
+      }
+      return { type: "op", field: fieldName, operator, value };
+    case "$nin":
+    case "$notIn":
+      if (!Array.isArray(value)) {
+        throw new Error(SqlErrors.NIN_NEED_ARRAY(operator), {
+          cause: null,
+          code: "validation"
+        });
+      }
+      if (value.length === 0) {
+        throw new Error(SqlErrors.NIN_NEED_NON_EMPTY, {
+          cause: null,
+          code: "validation"
+        });
+      }
+      return { type: "op", field: fieldName, operator, value };
+    case "$between":
+    case "$notBetween":
+      if (Array.isArray(value) && value.length === 2) {
+        return { type: "op", field: fieldName, operator, value };
+      }
+      return null;
+    case "$null":
+    case "$notNull":
+      if (value === true) {
+        return { type: "op", field: fieldName, operator, value };
+      }
+      return null;
+    default:
+      validateParam(value);
+      return { type: "op", field: fieldName, operator, value };
+  }
+}
+
+// lib/sqlBuilder/compiler.js
+function compileSelect(model, quoteIdent) {
+  let sql = "SELECT ";
+  const params = [];
+  if (model.select.length > 0) {
+    const fields = model.select.map((item) => {
+      if (item.type === "raw") {
+        return item.value;
+      }
+      return escapeField(item.value, quoteIdent);
+    });
+    sql += fields.join(", ");
+  } else {
+    sql += "*";
+  }
+  if (!model.from) {
+    throw new Error(SqlErrors.FROM_REQUIRED, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const fromSql = model.from.type === "raw" ? model.from.value : escapeTable(model.from.value, quoteIdent);
+  sql += ` FROM ${fromSql}`;
+  if (model.joins.length > 0) {
+    const joinSql = model.joins.map((join3) => {
+      const joinTable = escapeTable(join3.table, quoteIdent);
+      const joinType = join3.type.toUpperCase();
+      return `${joinType} JOIN ${joinTable} ON ${join3.on}`;
+    }).join(" ");
+    sql += ` ${joinSql}`;
+  }
+  const whereResult = compileWhere(model.where, quoteIdent);
+  if (whereResult.sql) {
+    sql += ` WHERE ${whereResult.sql}`;
+    for (const param of whereResult.params) {
+      params.push(param);
+    }
+  }
+  if (model.groupBy.length > 0) {
+    const groupSql = model.groupBy.map((field) => escapeField(field, quoteIdent)).join(", ");
+    sql += ` GROUP BY ${groupSql}`;
+  }
+  if (model.having.length > 0) {
+    sql += ` HAVING ${model.having.join(" AND ")}`;
+  }
+  if (model.orderBy.length > 0) {
+    const orderSql = model.orderBy.map((item) => {
+      const escapedField = escapeField(item.field, quoteIdent);
+      return `${escapedField} ${item.dir}`;
+    }).join(", ");
+    sql += ` ORDER BY ${orderSql}`;
+  }
+  if (model.limit !== null) {
+    sql += ` LIMIT ${model.limit}`;
+    if (model.offset !== null) {
+      sql += ` OFFSET ${model.offset}`;
+    }
+  }
+  return { sql, params };
+}
+function compileCount(model, quoteIdent) {
+  let sql = "SELECT COUNT(*) as total";
+  const params = [];
+  if (!model.from) {
+    throw new Error(SqlErrors.COUNT_NEED_FROM, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const fromSql = model.from.type === "raw" ? model.from.value : escapeTable(model.from.value, quoteIdent);
+  sql += ` FROM ${fromSql}`;
+  if (model.joins.length > 0) {
+    const joinSql = model.joins.map((join3) => {
+      const joinTable = escapeTable(join3.table, quoteIdent);
+      const joinType = join3.type.toUpperCase();
+      return `${joinType} JOIN ${joinTable} ON ${join3.on}`;
+    }).join(" ");
+    sql += ` ${joinSql}`;
+  }
+  const whereResult = compileWhere(model.where, quoteIdent);
+  if (whereResult.sql) {
+    sql += ` WHERE ${whereResult.sql}`;
+    for (const param of whereResult.params) {
+      params.push(param);
+    }
+  }
+  return { sql, params };
+}
+function compileInsert(table, data, quoteIdent) {
+  if (!table || !isString(table)) {
+    throw new Error(SqlErrors.INSERT_NEED_TABLE(table), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!data || typeof data !== "object") {
+    throw new Error(SqlErrors.INSERT_NEED_DATA(table, data), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const escapedTable = escapeTable(table, quoteIdent);
+  if (Array.isArray(data)) {
+    const fields2 = SqlCheck.assertBatchInsertRowsConsistent(data, { table });
+    const escapedFields2 = fields2.map((field) => escapeField(field, quoteIdent));
+    const placeholders2 = fields2.map(() => "?").join(", ");
+    const values = data.map(() => `(${placeholders2})`).join(", ");
+    const sql2 = `INSERT INTO ${escapedTable} (${escapedFields2.join(", ")}) VALUES ${values}`;
+    const params2 = [];
+    for (let i = 0;i < data.length; i++) {
+      const row = data[i];
+      for (const field of fields2) {
+        const value = row[field];
+        validateParam(value);
+        params2.push(value);
+      }
+    }
+    return { sql: sql2, params: params2 };
+  }
+  const fields = Object.keys(data);
+  if (fields.length === 0) {
+    throw new Error(SqlErrors.INSERT_NEED_AT_LEAST_ONE_FIELD(table), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  for (const field of fields) {
+    validateParam(data[field]);
+  }
+  const escapedFields = fields.map((field) => escapeField(field, quoteIdent));
+  const placeholders = fields.map(() => "?").join(", ");
+  const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES (${placeholders})`;
+  const params = [];
+  for (const field of fields) {
+    params.push(data[field]);
+  }
+  return { sql, params };
+}
+function compileUpdate(model, table, data, quoteIdent) {
+  if (!table || !isString(table)) {
+    throw new Error(SqlErrors.UPDATE_NEED_TABLE, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new Error(SqlErrors.UPDATE_NEED_OBJECT, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const fields = Object.keys(data);
+  if (fields.length === 0) {
+    throw new Error(SqlErrors.UPDATE_NEED_AT_LEAST_ONE_FIELD, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const escapedTable = escapeTable(table, quoteIdent);
+  const setFields = fields.map((field) => `${escapeField(field, quoteIdent)} = ?`);
+  const params = [];
+  for (const value of Object.values(data)) {
+    params.push(value);
+  }
+  let sql = `UPDATE ${escapedTable} SET ${setFields.join(", ")}`;
+  const whereResult = compileWhere(model.where, quoteIdent);
+  if (whereResult.sql) {
+    sql += ` WHERE ${whereResult.sql}`;
+    for (const param of whereResult.params) {
+      params.push(param);
+    }
+  } else {
+    throw new Error(SqlErrors.UPDATE_NEED_WHERE, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  return { sql, params };
+}
+function compileDelete(model, table, quoteIdent) {
+  if (!table || !isString(table)) {
+    throw new Error(SqlErrors.DELETE_NEED_TABLE, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const escapedTable = escapeTable(table, quoteIdent);
+  let sql = `DELETE FROM ${escapedTable}`;
+  const whereResult = compileWhere(model.where, quoteIdent);
+  if (whereResult.sql) {
+    sql += ` WHERE ${whereResult.sql}`;
+  } else {
+    throw new Error(SqlErrors.DELETE_NEED_WHERE, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  return { sql, params: whereResult.params };
+}
+function compileWhere(node, quoteIdent) {
+  if (!node) {
+    return { sql: "", params: [] };
+  }
+  if (node.type === "raw") {
+    const params = Array.isArray(node.params) ? node.params.slice() : [];
+    return { sql: node.sql, params };
+  }
+  if (node.type === "op") {
+    return compileOperatorNode(node, quoteIdent);
+  }
+  if (node.type === "group") {
+    if (!node.items || node.items.length === 0) {
+      return { sql: "", params: [] };
+    }
+    const parts = [];
+    const params = [];
+    for (const item of node.items) {
+      const built = compileWhere(item, quoteIdent);
+      if (!built.sql) {
+        continue;
+      }
+      let clause = built.sql;
+      if (node.join === "OR") {
+        clause = `(${clause})`;
+      } else if (item.type === "group" && item.join === "OR") {
+        clause = `(${clause})`;
+      }
+      parts.push(clause);
+      for (const param of built.params) {
+        params.push(param);
+      }
+    }
+    return { sql: parts.join(` ${node.join} `), params };
+  }
+  return { sql: "", params: [] };
+}
+function compileOperatorNode(node, quoteIdent) {
+  const escapedField = escapeField(node.field, quoteIdent);
+  const operator = node.operator;
+  switch (operator) {
+    case "$ne":
+    case "$not":
+      validateParam(node.value);
+      return { sql: `${escapedField} != ?`, params: [node.value] };
+    case "$in": {
+      const placeholders = node.value.map(() => "?").join(",");
+      const params = [];
+      for (const item of node.value) {
+        params.push(item);
+      }
+      return { sql: `${escapedField} IN (${placeholders})`, params };
+    }
+    case "$nin":
+    case "$notIn": {
+      const placeholders = node.value.map(() => "?").join(",");
+      const params = [];
+      for (const item of node.value) {
+        params.push(item);
+      }
+      return { sql: `${escapedField} NOT IN (${placeholders})`, params };
+    }
+    case "$like":
+      validateParam(node.value);
+      return { sql: `${escapedField} LIKE ?`, params: [node.value] };
+    case "$notLike":
+      validateParam(node.value);
+      return { sql: `${escapedField} NOT LIKE ?`, params: [node.value] };
+    case "$gt":
+      validateParam(node.value);
+      return { sql: `${escapedField} > ?`, params: [node.value] };
+    case "$gte":
+      validateParam(node.value);
+      return { sql: `${escapedField} >= ?`, params: [node.value] };
+    case "$lt":
+      validateParam(node.value);
+      return { sql: `${escapedField} < ?`, params: [node.value] };
+    case "$lte":
+      validateParam(node.value);
+      return { sql: `${escapedField} <= ?`, params: [node.value] };
+    case "$between":
+      return { sql: `${escapedField} BETWEEN ? AND ?`, params: [node.value[0], node.value[1]] };
+    case "$notBetween":
+      return { sql: `${escapedField} NOT BETWEEN ? AND ?`, params: [node.value[0], node.value[1]] };
+    case "$null":
+      return { sql: `${escapedField} IS NULL`, params: [] };
+    case "$notNull":
+      return { sql: `${escapedField} IS NOT NULL`, params: [] };
+    default:
+      validateParam(node.value);
+      return { sql: `${escapedField} = ?`, params: [node.value] };
+  }
+}
+
+// lib/sqlBuilder/batch.js
+function toDeleteInSql(options) {
+  if (!isNonEmptyString(options.table)) {
+    throw new Error(SqlErrors.TO_DELETE_IN_NEED_TABLE(options.table), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!isNonEmptyString(options.idField)) {
+    throw new Error(SqlErrors.TO_DELETE_IN_NEED_ID_FIELD(options.idField), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!Array.isArray(options.ids)) {
+    throw new Error(SqlErrors.TO_DELETE_IN_NEED_IDS, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (options.ids.length === 0) {
+    return { sql: "", params: [] };
+  }
+  const placeholders = options.ids.map(() => "?").join(",");
+  const sql = `DELETE FROM ${options.quoteIdent(options.table)} WHERE ${options.quoteIdent(options.idField)} IN (${placeholders})`;
+  const params = [];
+  for (const id of options.ids) {
+    params.push(id);
+  }
+  return { sql, params };
+}
+function toUpdateCaseByIdSql(options) {
+  if (!isNonEmptyString(options.table)) {
+    throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_TABLE(options.table), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!isNonEmptyString(options.idField)) {
+    throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_ID_FIELD(options.idField), {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!Array.isArray(options.rows)) {
+    throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_ROWS, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (options.rows.length === 0) {
+    return { sql: "", params: [] };
+  }
+  if (!Array.isArray(options.fields)) {
+    throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_FIELDS, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (options.fields.length === 0) {
+    return { sql: "", params: [] };
+  }
+  const ids = options.rows.map((row) => row.id);
+  const placeholders = ids.map(() => "?").join(",");
+  const setSqlList = [];
+  const args = [];
+  const quotedId = options.quoteIdent(options.idField);
+  for (const field of options.fields) {
+    const whenList = [];
+    for (const row of options.rows) {
+      if (!(field in row.data)) {
+        continue;
+      }
+      whenList.push("WHEN ? THEN ?");
+      args.push(row.id);
+      const value = row.data[field];
+      SqlCheck.assertNoUndefinedParam(value, "SQL \u53C2\u6570\u503C");
+      args.push(value);
+    }
+    if (whenList.length === 0) {
+      continue;
+    }
+    const quotedField = options.quoteIdent(field);
+    setSqlList.push(`${quotedField} = CASE ${quotedId} ${whenList.join(" ")} ELSE ${quotedField} END`);
+  }
+  setSqlList.push(`${options.quoteIdent(options.updatedAtField)} = ?`);
+  args.push(options.updatedAtValue);
+  for (const id of ids) {
+    args.push(id);
+  }
+  let sql = `UPDATE ${options.quoteIdent(options.table)} SET ${setSqlList.join(", ")} WHERE ${quotedId} IN (${placeholders})`;
+  if (options.stateGtZero && options.stateField) {
+    sql += ` AND ${options.quoteIdent(options.stateField)} > 0`;
+  }
+  return { sql, params: args };
+}
+
+// lib/sqlBuilder/index.js
+function createModel() {
+  return {
+    select: [],
+    from: null,
+    where: createWhereRoot(),
+    joins: [],
+    orderBy: [],
+    groupBy: [],
+    having: [],
+    limit: null,
+    offset: null
+  };
+}
+
+class SqlBuilder {
+  _model;
+  _quoteIdent;
+  constructor(options) {
+    this._quoteIdent = resolveQuoteIdent(options);
+    this._model = createModel();
+  }
+  reset() {
+    this._model = createModel();
+    return this;
+  }
+  getWhereConditions() {
+    const result = compileWhere(this._model.where, this._quoteIdent);
+    return { sql: result.sql, params: result.params };
+  }
+  select(fields = "*") {
+    appendSelectItems(this._model.select, fields);
+    return this;
+  }
+  selectRaw(expr) {
+    appendSelectRaw(this._model.select, expr);
+    return this;
+  }
+  from(table) {
+    setFromValue(this._model, table, false);
+    return this;
+  }
+  fromRaw(tableExpr) {
+    setFromValue(this._model, tableExpr, true);
+    return this;
+  }
+  where(conditionOrField, value) {
+    appendWhereInput(this._model.where, conditionOrField, value);
+    return this;
+  }
+  whereRaw(sql, params) {
+    appendWhereRaw(this._model.where, sql, params);
+    return this;
+  }
+  leftJoin(table, on) {
+    appendJoinItem(this._model.joins, "left", table, on);
+    return this;
+  }
+  rightJoin(table, on) {
+    appendJoinItem(this._model.joins, "right", table, on);
+    return this;
+  }
+  innerJoin(table, on) {
+    appendJoinItem(this._model.joins, "inner", table, on);
+    return this;
+  }
+  orderBy(fields) {
+    appendOrderByItems(this._model.orderBy, fields);
+    return this;
+  }
+  groupBy(field) {
+    appendGroupByItems(this._model.groupBy, field);
+    return this;
+  }
+  having(condition) {
+    appendHavingItems(this._model.having, condition);
+    return this;
+  }
+  limit(count, offset) {
+    const result = normalizeLimitValue(count, offset);
+    this._model.limit = result.limitValue;
+    this._model.offset = result.offsetValue;
+    return this;
+  }
+  offset(count) {
+    const offsetValue = normalizeOffsetValue(count);
+    this._model.offset = offsetValue;
+    return this;
+  }
+  toSelectSql() {
+    return compileSelect(this._model, this._quoteIdent);
+  }
+  toInsertSql(table, data) {
+    return compileInsert(table, data, this._quoteIdent);
+  }
+  toUpdateSql(table, data) {
+    return compileUpdate(this._model, table, data, this._quoteIdent);
+  }
+  toDeleteSql(table) {
+    return compileDelete(this._model, table, this._quoteIdent);
+  }
+  toCountSql() {
+    return compileCount(this._model, this._quoteIdent);
+  }
+  static toDeleteInSql(options) {
+    return toDeleteInSql(options);
+  }
+  static toUpdateCaseByIdSql(options) {
+    return toUpdateCaseByIdSql(options);
+  }
+}
+
+// lib/dbHelper/context.js
+function quoteIdentMySql(identifier) {
+  if (!isString(identifier)) {
+    throw new Error(`quoteIdentifier \u9700\u8981\u5B57\u7B26\u4E32\u7C7B\u578B\u6807\u8BC6\u7B26 (identifier: ${String(identifier)})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const trimmed = identifier.trim();
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(trimmed)) {
+    throw new Error(`\u65E0\u6548\u7684 SQL \u6807\u8BC6\u7B26: ${trimmed}`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  return `\`${trimmed}\``;
+}
+function hasBegin(sql) {
+  return typeof sql.begin === "function";
+}
+
+class DbSqlError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.originalError = options.originalError;
+    this.params = options.params;
+    this.duration = options.duration;
+    this.sqlInfo = options.sqlInfo;
+  }
+}
+
+class TransAbortError extends Error {
+  constructor(payload) {
+    super("TRANSACTION_ABORT");
+    this.payload = payload;
+  }
+}
+function isBeflyResponse(value) {
+  if (!isPlainObject2(value)) {
+    return false;
+  }
+  const record2 = value;
+  return isNumber(record2["code"]) && isString(record2["msg"]);
+}
+function convertBigIntFields(arr, fields) {
+  if (isNullable(arr)) {
+    return arr;
+  }
+  const defaultFields = ["id", "pid", "sort"];
+  const buildFields = (userFields) => {
+    if (!userFields || userFields.length === 0) {
+      return defaultFields;
+    }
+    const merged = ["id", "pid", "sort"];
+    for (const f of userFields) {
+      if (!isString(f)) {
+        continue;
+      }
+      if (!isNonEmptyString(f)) {
+        continue;
+      }
+      const trimmed = f.trim();
+      if (!merged.includes(trimmed)) {
+        merged.push(trimmed);
+      }
+    }
+    return merged;
+  };
+  const effectiveFields = buildFields(fields);
+  const fieldSet = new Set(effectiveFields);
+  const convertRecord = (source) => {
+    const converted = {};
+    for (const [key, value] of Object.entries(source)) {
+      let nextValue = value;
+      if (!isNullable(value)) {
+        const shouldConvert = fieldSet.has(key) || key.endsWith("Id") || key.endsWith("_id") || key.endsWith("At") || key.endsWith("_at");
+        if (shouldConvert) {
+          let bigintValue = null;
+          if (typeof value === "bigint") {
+            bigintValue = value;
+          } else if (isString(value)) {
+            if (/^-?\d+$/.test(value)) {
+              try {
+                bigintValue = BigInt(value);
+              } catch {
+                bigintValue = null;
+              }
+            }
+          }
+          if (bigintValue !== null) {
+            const convertedNumber = canConvertToNumber(bigintValue);
+            if (convertedNumber !== null) {
+              nextValue = convertedNumber;
+            }
+          }
+        }
+      }
+      converted[key] = nextValue;
+    }
+    return converted;
+  };
+  if (Array.isArray(arr)) {
+    return arr.map((item) => convertRecord(item));
+  }
+  if (typeof arr === "object") {
+    return convertRecord(arr);
+  }
+  return arr;
+}
+
+// lib/dbHelper/validate.js
+function assertNonEmptyString(value, label) {
+  if (!isNonEmptyString(value)) {
+    throw new Error(`${label} \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function assertPlainObjectValue(value, label) {
+  if (!isPlainObject2(value)) {
+    throw new Error(`${label} \u5FC5\u987B\u662F\u5BF9\u8C61`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateWhereObject(where, label, required2 = false) {
+  if (isNullable(where)) {
+    if (required2) {
+      throw new Error(`${label} \u5FC5\u987B\u662F\u5BF9\u8C61`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    return;
+  }
+  if (!isPlainObject2(where)) {
+    throw new Error(`${label} \u5FC5\u987B\u662F\u5BF9\u8C61`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateOrderByItems(orderBy, label) {
+  if (!Array.isArray(orderBy)) {
+    throw new Error(`${label} \u5FC5\u987B\u662F\u6570\u7EC4`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  for (const item of orderBy) {
+    if (!isString(item) || !item.includes("#")) {
+      throw new Error(`${label} \u5B57\u6BB5\u5FC5\u987B\u662F "\u5B57\u6BB5#\u65B9\u5411" \u683C\u5F0F\u7684\u5B57\u7B26\u4E32`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const parts = item.split("#");
+    if (parts.length !== 2) {
+      throw new Error(`${label} \u5B57\u6BB5\u5FC5\u987B\u662F "\u5B57\u6BB5#\u65B9\u5411" \u683C\u5F0F\u7684\u5B57\u7B26\u4E32`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const field = isString(parts[0]) ? parts[0].trim() : "";
+    const direction = isString(parts[1]) ? parts[1].trim().toUpperCase() : "";
+    if (!field) {
+      throw new Error(`${label} \u4E2D\u5B57\u6BB5\u540D\u4E0D\u80FD\u4E3A\u7A7A`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    if (direction !== "ASC" && direction !== "DESC") {
+      throw new Error(`${label} \u65B9\u5411\u5FC5\u987B\u662F ASC \u6216 DESC`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+}
+function validateJoins(joins, label) {
+  if (!Array.isArray(joins)) {
+    throw new Error(`${label} \u5FC5\u987B\u662F\u6570\u7EC4`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  for (let i = 0;i < joins.length; i++) {
+    const join3 = joins[i];
+    if (!isPlainObject2(join3)) {
+      throw new Error(`${label}[${i}] \u5FC5\u987B\u662F\u5BF9\u8C61`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    assertNonEmptyString(join3.table, `${label}[${i}].table`);
+    assertNonEmptyString(join3.on, `${label}[${i}].on`);
+    if (!isNullable(join3.type)) {
+      const type = isString(join3.type) ? join3.type.trim().toLowerCase() : "";
+      if (type !== "left" && type !== "right" && type !== "inner") {
+        throw new Error(`${label}[${i}].type \u53EA\u5141\u8BB8 left/right/inner`, {
+          cause: null,
+          code: "validation"
+        });
+      }
+    }
+  }
+}
+function validateQueryOptions(options, label) {
+  if (!isPlainObject2(options)) {
+    throw new Error(`${label} \u5FC5\u987B\u662F\u5BF9\u8C61`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  assertNonEmptyString(options.table, `${label}.table`);
+  if (!isNullable(options.where)) {
+    validateWhereObject(options.where, `${label}.where`);
+  }
+  if (!isNullable(options.fields) && !Array.isArray(options.fields)) {
+    throw new Error(`${label}.fields \u5FC5\u987B\u662F\u6570\u7EC4`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!isNullable(options.orderBy)) {
+    validateOrderByItems(options.orderBy, `${label}.orderBy`);
+  }
+  if (!isNullable(options.joins)) {
+    validateJoins(options.joins, `${label}.joins`);
+  }
+  if (!isNullable(options.page) && (!isFiniteNumber(options.page) || Math.floor(options.page) !== options.page)) {
+    throw new Error(`${label}.page \u5FC5\u987B\u662F\u6574\u6570`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (!isNullable(options.limit) && (!isFiniteNumber(options.limit) || Math.floor(options.limit) !== options.limit)) {
+    throw new Error(`${label}.limit \u5FC5\u987B\u662F\u6574\u6570`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateWriteData(data, label) {
+  assertPlainObjectValue(data, label);
+}
+function validateBatchDataList(dataList, label) {
+  if (!Array.isArray(dataList)) {
+    throw new Error(`${label} \u5FC5\u987B\u662F\u6570\u7EC4`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  for (let i = 0;i < dataList.length; i++) {
+    if (!isPlainObject2(dataList[i])) {
+      throw new Error(`${label}[${i}] \u5FC5\u987B\u662F\u5BF9\u8C61`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+}
+function validateTableName(table, label) {
+  assertNonEmptyString(table, label);
+}
+function validateTableWhereOptions(options, label, required2 = false) {
+  validateTableName(options.table, `${label}.table`);
+  validateWhereObject(options.where, `${label}.where`, required2);
+}
+function validateTableDataOptions(options, label) {
+  validateTableName(options.table, `${label}.table`);
+  validateWriteData(options.data, `${label}.data`);
+}
+function validateTableBatchDataOptions(table, dataList, label) {
+  validateTableName(table, `${label}.table`);
+  validateBatchDataList(dataList, `${label}.dataList`);
+}
+function validateNoJoinReadOptions(options, label, joinErrorMessage) {
+  validateTableWhereOptions(options, label, false);
+  validateNoJoins(options.joins, joinErrorMessage);
+  validateSimpleTableName(options.table, label);
+}
+function validateIncrementOptions(table, field, where, value, label) {
+  validateTableWhereOptions({ table, where }, label, true);
+  validateSafeFieldName(snakeCase(table));
+  validateSafeFieldName(snakeCase(field));
+  validateIncrementValue(table, field, value);
+}
+function validateSimpleTableName(rawTable, label) {
+  const table = isString(rawTable) ? rawTable.trim() : "";
+  if (!table) {
+    throw new Error(`${label}.table \u4E0D\u80FD\u4E3A\u7A7A`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (table.includes(" ")) {
+    throw new Error(`${label} \u4E0D\u652F\u6301\u522B\u540D\u8868\u5199\u6CD5\uFF08table: ${table}\uFF09`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (table.includes(".")) {
+    throw new Error(`${label} \u4E0D\u652F\u6301 schema.table \u5199\u6CD5\uFF08table: ${table}\uFF09`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateSafeFieldName(field) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
+    throw new Error(`\u65E0\u6548\u7684\u5B57\u6BB5\u540D: ${field}\uFF0C\u53EA\u5141\u8BB8\u5B57\u6BCD\u3001\u6570\u5B57\u548C\u4E0B\u5212\u7EBF`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validatePageLimitRange(prepared, rawTable) {
+  if (prepared.page < 1 || prepared.page > 1e4) {
+    throw new Error(`\u9875\u7801\u5FC5\u987B\u5728 1 \u5230 10000 \u4E4B\u95F4 (table: ${rawTable}, page: ${prepared.page}, limit: ${prepared.limit})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (prepared.limit < 1 || prepared.limit > 1000) {
+    throw new Error(`\u6BCF\u9875\u6570\u91CF\u5FC5\u987B\u5728 1 \u5230 1000 \u4E4B\u95F4 (table: ${rawTable}, page: ${prepared.page}, limit: ${prepared.limit})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateNoJoins(joins, message) {
+  if (Array.isArray(joins) && joins.length > 0) {
+    throw new Error(message, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateIncrementValue(table, field, value) {
+  if (typeof value !== "number" || isNaN(value)) {
+    throw new Error(`\u81EA\u589E\u503C\u5FC5\u987B\u662F\u6709\u6548\u7684\u6570\u5B57 (table: ${table}, field: ${field}, value: ${value})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateExecuteSql(sql) {
+  if (!isString(sql)) {
+    throw new Error(`execute \u53EA\u63A5\u53D7\u5B57\u7B26\u4E32\u7C7B\u578B\u7684 SQL\uFF0C\u6536\u5230\u7C7B\u578B: ${typeof sql}\uFF0C\u503C: ${JSON.stringify(sql)}`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateExcludeFieldsResult(resultFields, table, excludeSnakeFields) {
+  if (resultFields.length === 0) {
+    throw new Error(`\u6392\u9664\u5B57\u6BB5\u540E\u6CA1\u6709\u5269\u4F59\u5B57\u6BB5\u53EF\u67E5\u8BE2\u3002\u8868: ${table}, \u6392\u9664: ${excludeSnakeFields.join(", ")}`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateTimeIdValue(id) {
+  if (!Number.isFinite(id) || id <= 0) {
+    throw new Error(`buildInsertRow(timeId) \u5931\u8D25\uFF1Aid \u5FC5\u987B\u4E3A > 0 \u7684\u6709\u9650 number (id: ${String(id)})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function validateInsertBatchSize(count, maxBatchSize) {
+  if (count > maxBatchSize) {
+    throw new Error(`\u6279\u91CF\u63D2\u5165\u6570\u91CF ${count} \u8D85\u8FC7\u6700\u5927\u9650\u5236 ${maxBatchSize}`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function assertNoExprField(field) {
+  if (!isString(field)) {
+    return;
+  }
+  if (!isNonEmptyString(field)) {
+    return;
+  }
+  const trimmed = field.trim();
+  if (trimmed.includes("(") || trimmed.includes(")")) {
+    throw new Error(`\u5B57\u6BB5\u5305\u542B\u51FD\u6570/\u8868\u8FBE\u5F0F\uFF0C\u8BF7\u4F7F\u7528 selectRaw/whereRaw (field: ${trimmed})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+}
+function assertNoUndefinedInRecord(row, label) {
+  for (const [key, value] of Object.entries(row)) {
+    if (value === undefined) {
+      throw new Error(`${label} \u5B58\u5728 undefined \u5B57\u6BB5\u503C (field: ${key})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+  }
+}
+function assertBatchInsertRowsConsistent(rows, options) {
+  if (!Array.isArray(rows)) {
+    throw new Error("\u6279\u91CF\u63D2\u5165 rows \u5FC5\u987B\u662F\u6570\u7EC4", {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (rows.length === 0) {
+    throw new Error(`\u63D2\u5165\u6570\u636E\u4E0D\u80FD\u4E3A\u7A7A (table: ${options.table})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const first = rows[0];
+  if (!first || typeof first !== "object" || Array.isArray(first)) {
+    throw new Error(`\u6279\u91CF\u63D2\u5165\u7684\u6BCF\u4E00\u884C\u5FC5\u987B\u662F\u5BF9\u8C61 (table: ${options.table}, rowIndex: 0)`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const fields = Object.keys(first);
+  if (fields.length === 0) {
+    throw new Error(`\u63D2\u5165\u6570\u636E\u5FC5\u987B\u81F3\u5C11\u6709\u4E00\u4E2A\u5B57\u6BB5 (table: ${options.table})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const fieldSet = new Set(fields);
+  for (let i = 0;i < rows.length; i++) {
+    const row = rows[i];
+    if (!row || typeof row !== "object" || Array.isArray(row)) {
+      throw new Error(`\u6279\u91CF\u63D2\u5165\u7684\u6BCF\u4E00\u884C\u5FC5\u987B\u662F\u5BF9\u8C61 (table: ${options.table}, rowIndex: ${i})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    const rowKeys = Object.keys(row);
+    if (rowKeys.length !== fields.length) {
+      throw new Error(`\u6279\u91CF\u63D2\u5165\u6BCF\u884C\u5B57\u6BB5\u5FC5\u987B\u4E00\u81F4 (table: ${options.table}, rowIndex: ${i})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    for (const key of rowKeys) {
+      if (!fieldSet.has(key)) {
+        throw new Error(`\u6279\u91CF\u63D2\u5165\u6BCF\u884C\u5B57\u6BB5\u5FC5\u987B\u4E00\u81F4 (table: ${options.table}, rowIndex: ${i}, extraField: ${key})`, {
+          cause: null,
+          code: "validation"
+        });
+      }
+    }
+    for (const field of fields) {
+      if (!(field in row)) {
+        throw new Error(`\u6279\u91CF\u63D2\u5165\u7F3A\u5C11\u5B57\u6BB5 (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+          cause: null,
+          code: "validation"
+        });
+      }
+      if (row[field] === undefined) {
+        throw new Error(`\u6279\u91CF\u63D2\u5165\u5B57\u6BB5\u503C\u4E0D\u80FD\u4E3A undefined (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+          cause: null,
+          code: "validation"
+        });
+      }
+    }
+  }
+  return fields;
+}
+function parseTableRef(tableRef) {
+  if (!isString(tableRef)) {
+    throw new Error(`tableRef \u5FC5\u987B\u662F\u5B57\u7B26\u4E32 (tableRef: ${String(tableRef)})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const trimmed = tableRef.trim();
+  if (!isNonEmptyString(tableRef)) {
+    throw new Error("tableRef \u4E0D\u80FD\u4E3A\u7A7A", {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
+  if (parts.length === 0) {
+    throw new Error("tableRef \u4E0D\u80FD\u4E3A\u7A7A", {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (parts.length > 2) {
+    throw new Error(`\u4E0D\u652F\u6301\u7684\u8868\u5F15\u7528\u683C\u5F0F\uFF08\u5305\u542B\u8FC7\u591A\u7247\u6BB5\uFF09\u3002\u8BF7\u4F7F\u7528\u6700\u7B80\u5F62\u5F0F\uFF1Atable \u6216 table alias \u6216 schema.table \u6216 schema.table alias (tableRef: ${trimmed})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  const namePart = parts[0];
+  if (!isNonEmptyString(namePart)) {
+    throw new Error(`tableRef \u89E3\u6790\u5931\u8D25\uFF1A\u7F3A\u5C11\u8868\u540D (tableRef: ${trimmed})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  let aliasPart = null;
+  if (parts.length === 2) {
+    const alias = parts[1];
+    if (!isNonEmptyString(alias)) {
+      throw new Error(`tableRef \u89E3\u6790\u5931\u8D25\uFF1A\u7F3A\u5C11 alias (tableRef: ${trimmed})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    aliasPart = alias;
+  }
+  const nameSegments = namePart.split(".");
+  if (nameSegments.length > 2) {
+    throw new Error(`\u4E0D\u652F\u6301\u7684\u8868\u5F15\u7528\u683C\u5F0F\uFF08schema \u5C42\u7EA7\u8FC7\u6DF1\uFF09 (tableRef: ${trimmed})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (nameSegments.length === 2) {
+    const schema = nameSegments[0];
+    const table2 = nameSegments[1];
+    if (!isNonEmptyString(schema)) {
+      throw new Error(`tableRef \u89E3\u6790\u5931\u8D25\uFF1Aschema \u4E3A\u7A7A (tableRef: ${trimmed})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    if (!isNonEmptyString(table2)) {
+      throw new Error(`tableRef \u89E3\u6790\u5931\u8D25\uFF1Atable \u4E3A\u7A7A (tableRef: ${trimmed})`, {
+        cause: null,
+        code: "validation"
+      });
+    }
+    return { schema, table: table2, alias: aliasPart };
+  }
+  const table = nameSegments[0];
+  if (!isNonEmptyString(table)) {
+    throw new Error(`tableRef \u89E3\u6790\u5931\u8D25\uFF1Atable \u4E3A\u7A7A (tableRef: ${trimmed})`, {
+      cause: null,
+      code: "validation"
+    });
+  }
+  return { schema: null, table, alias: aliasPart };
+}
+function validateGeneratedBatchId(id, table, index) {
+  if (typeof id !== "number") {
+    throw new Error(`\u6279\u91CF\u63D2\u5165\u751F\u6210 ID \u5931\u8D25\uFF1Aids[${index}] \u4E0D\u662F number (table: ${table})`, {
+      cause: null,
+      code: "runtime"
+    });
+  }
+}
+function validateAndClassifyFields(fields) {
+  if (!fields || fields.length === 0) {
+    return { type: "all", fields: [] };
+  }
+  if (fields.some((f) => f === "*")) {
+    throw new Error("fields \u4E0D\u652F\u6301 * \u661F\u53F7\uFF0C\u8BF7\u4F7F\u7528\u7A7A\u6570\u7EC4 [] \u6216\u4E0D\u4F20\u53C2\u6570\u8868\u793A\u67E5\u8BE2\u6240\u6709\u5B57\u6BB5", {
+      cause: null,
+      code: "validation"
+    });
+  }
+  if (fields.some((f) => !isNonEmptyString(f))) {
+    throw new Error("fields \u4E0D\u80FD\u5305\u542B\u7A7A\u5B57\u7B26\u4E32\u6216\u65E0\u6548\u503C", {
+      cause: null,
+      code: "validation"
+    });
+  }
+  for (const rawField of fields) {
+    const checkField = rawField.startsWith("!") ? rawField.substring(1) : rawField;
+    assertNoExprField(checkField);
+  }
+  const includeFields = fields.filter((f) => !f.startsWith("!"));
+  const excludeFields = fields.filter((f) => f.startsWith("!"));
+  if (includeFields.length > 0 && excludeFields.length === 0) {
+    return { type: "include", fields: includeFields };
+  }
+  if (excludeFields.length > 0 && includeFields.length === 0) {
+    return { type: "exclude", fields: excludeFields.map((f) => f.substring(1)) };
+  }
+  throw new Error(`fields \u4E0D\u80FD\u540C\u65F6\u5305\u542B\u666E\u901A\u5B57\u6BB5\u548C\u6392\u9664\u5B57\u6BB5\uFF08! \u5F00\u5934\uFF09\u3002\u53EA\u80FD\u4F7F\u7528\u4EE5\u4E0B3\u79CD\u65B9\u5F0F\u4E4B\u4E00\uFF1A
+1. \u7A7A\u6570\u7EC4 [] \u6216\u4E0D\u4F20\uFF08\u67E5\u8BE2\u6240\u6709\uFF09
+2. \u5168\u90E8\u6307\u5B9A\u5B57\u6BB5 ["id", "name"]
+3. \u5168\u90E8\u6392\u9664\u5B57\u6BB5 ["!password", "!token"]`, {
+    cause: null,
+    code: "validation"
+  });
+}
+
+// lib/dbHelper/util.js
+function normalizeTableRef(tableRef) {
+  const parsed = parseTableRef(tableRef);
+  const schemaPart = parsed.schema ? snakeCase(parsed.schema) : null;
+  const tablePart = snakeCase(parsed.table);
+  const aliasPart = parsed.alias ? snakeCase(parsed.alias) : null;
+  let result = schemaPart ? `${schemaPart}.${tablePart}` : tablePart;
+  if (aliasPart) {
+    result = `${result} ${aliasPart}`;
+  }
+  return result;
+}
+function getJoinMainQualifier(tableRef) {
+  const parsed = parseTableRef(tableRef);
+  if (parsed.alias) {
+    return snakeCase(parsed.alias);
+  }
+  return snakeCase(parsed.table);
+}
+function toNumberFromSql(value) {
+  if (isNullable(value)) {
+    return 0;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return 0;
+    }
+    return value;
+  }
+  if (typeof value === "bigint") {
+    const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+    const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
+    if (value <= maxSafe && value >= minSafe) {
+      return Number(value);
+    }
+    return 0;
+  }
+  if (typeof value === "string") {
+    if (!value.trim()) {
+      return 0;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+      return 0;
+    }
+    return parsed;
+  }
+  return 0;
+}
+
+// lib/dbHelper/builders.js
+function clearDeep(value, options) {
+  const arrayObjectKeys = Array.isArray(options?.arrayObjectKeys) ? options.arrayObjectKeys : ["$or", "$and"];
+  const arrayObjectKeySet = new Set;
+  for (const key of arrayObjectKeys) {
+    arrayObjectKeySet.add(key);
+  }
+  const depthRaw = isFiniteNumber(options?.depth) ? Math.floor(options.depth) : 0;
+  const depth = depthRaw < 0 ? 0 : depthRaw;
+  const clearInternal = (input, remainingDepth) => {
+    if (!input || typeof input !== "object") {
+      return input;
+    }
+    if (Array.isArray(input)) {
+      return input;
+    }
+    const canRecurse = remainingDepth === 0 || remainingDepth > 1;
+    const childDepth = remainingDepth === 0 ? 0 : remainingDepth - 1;
+    const result = {};
+    for (const [key, item] of Object.entries(input)) {
+      if (isNullable(item)) {
+        continue;
+      }
+      if (arrayObjectKeySet.has(key)) {
+        if (!Array.isArray(item)) {
+          continue;
+        }
+        const outList = [];
+        for (const child of item) {
+          if (!child || typeof child !== "object" || Array.isArray(child)) {
+            continue;
+          }
+          const cleaned = clearInternal(child, remainingDepth);
+          if (!cleaned || typeof cleaned !== "object" || Array.isArray(cleaned)) {
+            continue;
+          }
+          if (Object.keys(cleaned).length === 0) {
+            continue;
+          }
+          outList.push(cleaned);
+        }
+        if (outList.length > 0) {
+          result[key] = outList;
+        }
+        continue;
+      }
+      if (typeof item === "object" && !Array.isArray(item)) {
+        if (!canRecurse) {
+          result[key] = item;
+          continue;
+        }
+        const cleanedObj = clearInternal(item, childDepth);
+        if (!cleanedObj || typeof cleanedObj !== "object" || Array.isArray(cleanedObj)) {
+          continue;
+        }
+        if (Object.keys(cleanedObj).length === 0) {
+          continue;
+        }
+        result[key] = cleanedObj;
+        continue;
+      }
+      result[key] = item;
+    }
+    return result;
+  };
+  return clearInternal(value, depth);
+}
+async function fieldsToSnake(table, fields, getTableColumns) {
+  if (!fields || !Array.isArray(fields)) {
+    return ["*"];
+  }
+  const classified = validateAndClassifyFields(fields);
+  if (classified.type === "all") {
+    return ["*"];
+  }
+  if (classified.type === "include") {
+    return classified.fields.map((field) => processJoinField(field));
+  }
+  if (classified.type === "exclude") {
+    const allColumns = await getTableColumns(table);
+    const excludeSnakeFields = classified.fields.map((f) => snakeCase(f));
+    const resultFields = allColumns.filter((col) => !excludeSnakeFields.includes(col));
+    validateExcludeFieldsResult(resultFields, table, excludeSnakeFields);
+    return resultFields;
+  }
+  return ["*"];
+}
+function orderByToSnake(orderBy) {
+  if (!orderBy || !Array.isArray(orderBy)) {
+    return orderBy;
+  }
+  return orderBy.map((item) => {
+    if (!isString(item) || !item.includes("#")) {
+      return item;
+    }
+    const parts = item.split("#");
+    if (parts.length !== 2) {
+      return item;
+    }
+    const field = parts[0];
+    const direction = parts[1];
+    if (!isString(field) || !isString(direction)) {
+      return item;
+    }
+    return `${snakeCase(field.trim())}#${direction.trim()}`;
+  });
+}
+function processJoinField(field) {
+  assertNoExprField(field);
+  if (field === "*" || field.startsWith("`")) {
+    return field;
+  }
+  if (field.toUpperCase().includes(" AS ")) {
+    const parts = field.split(/\s+AS\s+/i);
+    const fieldPart = parts[0];
+    const aliasPart = parts[1];
+    if (!isString(fieldPart) || !isString(aliasPart)) {
+      return field;
+    }
+    return `${processJoinField(fieldPart.trim())} AS ${aliasPart.trim()}`;
+  }
+  if (field.includes(".")) {
+    const parts = field.split(".");
+    if (parts.length < 2) {
+      return snakeCase(field);
+    }
+    if (parts.some((p) => !isNonEmptyString(p))) {
+      return field;
+    }
+    const fieldName = parts[parts.length - 1];
+    const tableName = parts.slice(0, parts.length - 1).join(".");
+    if (!isString(fieldName) || !isString(tableName)) {
+      return snakeCase(field);
+    }
+    const normalizedTableName = tableName.split(".").map((item) => {
+      const trimmed = item.trim();
+      if (!trimmed) {
+        return trimmed;
+      }
+      return /[A-Z]/.test(trimmed) ? snakeCase(trimmed) : trimmed;
+    }).join(".");
+    return `${normalizedTableName}.${snakeCase(fieldName)}`;
+  }
+  return snakeCase(field);
+}
+function processJoinWhereKey(key) {
+  if (key === "$or" || key === "$and") {
+    return key;
+  }
+  assertNoExprField(key);
+  if (key.includes("$")) {
+    const lastDollarIndex = key.lastIndexOf("$");
+    const fieldPart = key.substring(0, lastDollarIndex);
+    const operator = key.substring(lastDollarIndex);
+    if (fieldPart.includes(".")) {
+      const parts = fieldPart.split(".");
+      if (parts.length < 2) {
+        return `${snakeCase(fieldPart)}${operator}`;
+      }
+      if (parts.some((p) => !isNonEmptyString(p))) {
+        return `${snakeCase(fieldPart)}${operator}`;
+      }
+      const fieldName = parts[parts.length - 1];
+      const tableName = parts.slice(0, parts.length - 1).join(".");
+      if (!isString(fieldName) || !isString(tableName)) {
+        return `${snakeCase(fieldPart)}${operator}`;
+      }
+      const normalizedTableName = tableName.split(".").map((item) => {
+        const trimmed = item.trim();
+        if (!trimmed) {
+          return trimmed;
+        }
+        return /[A-Z]/.test(trimmed) ? snakeCase(trimmed) : trimmed;
+      }).join(".");
+      return `${normalizedTableName}.${snakeCase(fieldName)}${operator}`;
+    }
+    return `${snakeCase(fieldPart)}${operator}`;
+  }
+  if (key.includes(".")) {
+    const parts = key.split(".");
+    if (parts.length < 2) {
+      return snakeCase(key);
+    }
+    if (parts.some((p) => !isNonEmptyString(p))) {
+      return snakeCase(key);
+    }
+    const fieldName = parts[parts.length - 1];
+    const tableName = parts.slice(0, parts.length - 1).join(".");
+    if (!isString(fieldName) || !isString(tableName)) {
+      return snakeCase(key);
+    }
+    const normalizedTableName = tableName.split(".").map((item) => {
+      const trimmed = item.trim();
+      if (!trimmed) {
+        return trimmed;
+      }
+      return /[A-Z]/.test(trimmed) ? snakeCase(trimmed) : trimmed;
+    }).join(".");
+    return `${normalizedTableName}.${snakeCase(fieldName)}`;
+  }
+  return snakeCase(key);
+}
+function processJoinWhere(where) {
+  if (!where || typeof where !== "object") {
+    return where;
+  }
+  if (Array.isArray(where)) {
+    return where.map((item) => processJoinWhere(item));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(where)) {
+    const newKey = processJoinWhereKey(key);
+    if (key === "$or" || key === "$and") {
+      result[newKey] = Array.isArray(value) ? value.map((item) => processJoinWhere(item)) : [];
+    } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      result[newKey] = processJoinWhere(value);
+    } else {
+      result[newKey] = value;
+    }
+  }
+  return result;
+}
+function processJoinOrderBy(orderBy) {
+  if (!orderBy || !Array.isArray(orderBy)) {
+    return orderBy;
+  }
+  return orderBy.map((item) => {
+    if (!isString(item) || !item.includes("#")) {
+      return item;
+    }
+    const parts = item.split("#");
+    if (parts.length !== 2) {
+      return item;
+    }
+    const field = parts[0];
+    const direction = parts[1];
+    if (!isString(field) || !isString(direction)) {
+      return item;
+    }
+    return `${processJoinField(field.trim())}#${direction.trim()}`;
+  });
+}
+function processJoinOn(on) {
+  if (!isString(on)) {
+    return String(on);
+  }
+  const raw = String(on);
+  if (!isNonEmptyString(raw)) {
+    return raw;
+  }
+  const replaceSegment = (segment) => {
+    return segment.replace(/([a-zA-Z_][a-zA-Z0-9_]*)(\s*\.\s*)([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, left, dot, right) => {
+      return `${snakeCase(left)}${dot}${snakeCase(right)}`;
+    });
+  };
+  let result = "";
+  let buffer = "";
+  let quote = null;
+  let prev = "";
+  for (const ch of raw) {
+    if (quote) {
+      result += ch;
+      if (ch === quote && prev !== "\\") {
+        quote = null;
+      }
+      prev = ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      if (buffer.length > 0) {
+        result += replaceSegment(buffer);
+        buffer = "";
+      }
+      quote = ch;
+      result += ch;
+      prev = ch;
+      continue;
+    }
+    buffer += ch;
+    prev = ch;
+  }
+  if (buffer.length > 0) {
+    result += replaceSegment(buffer);
+  }
+  return result;
+}
+function addDefaultStateFilter(where = {}, table, hasJoins = false) {
+  const hasStateCondition = Object.keys(where).some((key) => key.startsWith("state") || key.includes(".state"));
+  if (hasStateCondition) {
+    return where;
+  }
+  if (hasJoins && table) {
+    const result2 = {};
+    for (const [key, value] of Object.entries(where)) {
+      result2[key] = value;
+    }
+    result2[`${table}.state$gt`] = 0;
+    return result2;
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(where)) {
+    result[key] = value;
+  }
+  result.state$gt = 0;
+  return result;
+}
+function whereKeysToSnake(where) {
+  if (!where || typeof where !== "object") {
+    return where;
+  }
+  if (Array.isArray(where)) {
+    return where.map((item) => whereKeysToSnake(item));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(where)) {
+    if (key === "$or" || key === "$and") {
+      result[key] = Array.isArray(value) ? value.map((item) => whereKeysToSnake(item)) : [];
+      continue;
+    }
+    assertNoExprField(key);
+    if (key.includes("$")) {
+      const lastDollarIndex = key.lastIndexOf("$");
+      const fieldName = key.substring(0, lastDollarIndex);
+      const operator = key.substring(lastDollarIndex);
+      result[snakeCase(fieldName) + operator] = value;
+      continue;
+    }
+    const snakeKey = snakeCase(key);
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      result[snakeKey] = whereKeysToSnake(value);
+    } else {
+      result[snakeKey] = value;
+    }
+  }
+  return result;
+}
+function serializeArrayFields(data) {
+  const serialized = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (isNullable(value)) {
+      serialized[key] = value;
+      continue;
+    }
+    if (Array.isArray(value)) {
+      serialized[key] = JSON.stringify(value);
+      continue;
+    }
+    serialized[key] = value;
+  }
+  return serialized;
+}
+function deserializeArrayFields(data) {
+  if (!data) {
+    return null;
+  }
+  const deserialized = {};
+  for (const [key, value] of Object.entries(data)) {
+    deserialized[key] = value;
+  }
+  for (const [key, value] of Object.entries(deserialized)) {
+    if (!isString(value)) {
+      continue;
+    }
+    if (value.startsWith("[") && value.endsWith("]")) {
+      try {
+        const parsed = JSON.parse(value);
+        if (Array.isArray(parsed)) {
+          deserialized[key] = parsed;
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return deserialized;
+}
+function cleanAndSnakeAndSerializeWriteData(data, excludeValues = [null, undefined]) {
+  const cleanData = fieldClear(data, { excludeValues });
+  const snakeData = keysToSnake(cleanData);
+  return serializeArrayFields(snakeData);
+}
+function stripSystemFieldsForWrite(data, options) {
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (key === "id")
+      continue;
+    if (key === "created_at")
+      continue;
+    if (key === "updated_at")
+      continue;
+    if (key === "deleted_at")
+      continue;
+    if (!options.allowState && key === "state")
+      continue;
+    result[key] = value;
+  }
+  return result;
+}
+function buildInsertRow(options) {
+  const serializedData = cleanAndSnakeAndSerializeWriteData(options.data);
+  const userData = stripSystemFieldsForWrite(serializedData, { allowState: false });
+  const result = {};
+  for (const [key, value] of Object.entries(userData)) {
+    result[key] = value;
+  }
+  if (options.idMode === "timeId") {
+    validateTimeIdValue(options.id);
+    result["id"] = options.id;
+  }
+  result["created_at"] = options.now;
+  result["updated_at"] = options.now;
+  result["state"] = 1;
+  return result;
+}
+function buildUpdateRow(options) {
+  const serializedData = cleanAndSnakeAndSerializeWriteData(options.data);
+  const userData = stripSystemFieldsForWrite(serializedData, { allowState: options.allowState });
+  const result = {};
+  for (const [key, value] of Object.entries(userData)) {
+    result[key] = value;
+  }
+  result["updated_at"] = options.now;
+  return result;
+}
+function buildPartialUpdateData(options) {
+  const serializedData = cleanAndSnakeAndSerializeWriteData(options.data);
+  return stripSystemFieldsForWrite(serializedData, { allowState: options.allowState });
+}
+var builderMethods = {
+  createSqlBuilder() {
+    return new SqlBuilder({ quoteIdent: quoteIdentMySql });
+  },
+  createListBuilder(prepared, whereFiltered, limit, offset) {
+    const builder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered).limit(limit);
+    this.applyJoins(builder, prepared.joins);
+    if (!isNullable(offset)) {
+      builder.offset(offset);
+    }
+    if (prepared.orderBy && prepared.orderBy.length > 0) {
+      builder.orderBy(prepared.orderBy);
+    }
+    return builder;
+  },
+  async fetchCount(prepared, whereFiltered, alias) {
+    const builder = this.createSqlBuilder().selectRaw(alias).from(prepared.table).where(whereFiltered);
+    this.applyJoins(builder, prepared.joins);
+    const result = builder.toSelectSql();
+    const executeRes = await this.execute(result.sql, result.params);
+    const total = executeRes.data?.[0]?.total || executeRes.data?.[0]?.count || 0;
+    return {
+      total,
+      sql: executeRes.sql
+    };
+  },
+  normalizeRowData(row, bigintFields) {
+    if (!row) {
+      return {};
+    }
+    const camelRow = keysToCamel(row);
+    const deserialized = deserializeArrayFields(camelRow);
+    if (!deserialized) {
+      return {};
+    }
+    const convertedList = convertBigIntFields([deserialized], bigintFields);
+    if (convertedList && convertedList.length > 0) {
+      return convertedList[0];
+    }
+    return deserialized;
+  },
+  normalizeListData(list, bigintFields) {
+    const camelList = arrayKeysToCamel(list);
+    const deserializedList = camelList.map((item) => deserializeArrayFields(item)).filter((item) => item !== null);
+    return convertBigIntFields(deserializedList, bigintFields);
+  },
+  normalizeJoinOptions(options, cleanWhere) {
+    const processedFields = (options.fields || []).map((field) => processJoinField(field));
+    const normalizedTableRef = normalizeTableRef(options.table);
+    const mainQualifier = getJoinMainQualifier(options.table);
+    return {
+      table: normalizedTableRef,
+      tableQualifier: mainQualifier,
+      fields: processedFields.length > 0 ? processedFields : ["*"],
+      where: processJoinWhere(cleanWhere),
+      joins: options.joins,
+      orderBy: processJoinOrderBy(options.orderBy || []),
+      page: options.page || 1,
+      limit: options.limit || 10
+    };
+  },
+  async normalizeSingleTableOptions(options, cleanWhere) {
+    const snakeTable = snakeCase(options.table);
+    const processedFields = await fieldsToSnake(snakeTable, options.fields || [], this.getTableColumns.bind(this));
+    return {
+      table: snakeTable,
+      tableQualifier: snakeTable,
+      fields: processedFields,
+      where: whereKeysToSnake(cleanWhere),
+      joins: undefined,
+      orderBy: orderByToSnake(options.orderBy || []),
+      page: options.page || 1,
+      limit: options.limit || 10
+    };
+  },
+  buildQueryOptions(options, defaults) {
+    const output = {
+      table: options.table,
+      page: defaults.page,
+      limit: defaults.limit
+    };
+    if (options.fields !== undefined)
+      output.fields = options.fields;
+    if (options.bigint !== undefined)
+      output.bigint = options.bigint;
+    if (options.where !== undefined)
+      output.where = options.where;
+    if (options.joins !== undefined)
+      output.joins = options.joins;
+    if (options.orderBy !== undefined)
+      output.orderBy = options.orderBy;
+    return output;
+  },
+  resolveFieldValue(record2, field) {
+    if (!isPlainObject2(record2)) {
+      return null;
+    }
+    if (Object.hasOwn(record2, field)) {
+      return record2[field];
+    }
+    const camelField = field.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (camelField !== field && Object.hasOwn(record2, camelField)) {
+      return record2[camelField];
+    }
+    const snakeField = field.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+    if (snakeField !== field && Object.hasOwn(record2, snakeField)) {
+      return record2[snakeField];
+    }
+    return null;
+  },
+  async getTableColumns(table) {
+    const quotedTable = quoteIdentMySql(table);
+    const executeRes = await this.execute(`SHOW COLUMNS FROM ${quotedTable}`, []);
+    const result = executeRes.data;
+    if (!result || result.length === 0) {
+      throw new Error(`\u8868 ${table} \u4E0D\u5B58\u5728\u6216\u6CA1\u6709\u5B57\u6BB5`, {
+        cause: null,
+        code: "runtime"
+      });
+    }
+    const columnNames = [];
+    for (const row of result) {
+      const record2 = row;
+      const name = record2["Field"];
+      if (isNonEmptyString(name)) {
+        columnNames.push(name);
+      }
+    }
+    return columnNames;
+  },
+  async prepareQueryOptions(options, label = "queryOptions") {
+    validateQueryOptions(options, label);
+    const cleanWhere = clearDeep(options.where || {});
+    const hasJoins = options.joins && options.joins.length > 0;
+    if (hasJoins) {
+      return this.normalizeJoinOptions(options, cleanWhere);
+    }
+    return await this.normalizeSingleTableOptions(options, cleanWhere);
+  },
+  applyJoins(builder, joins) {
+    if (!joins || joins.length === 0)
+      return;
+    for (const join3 of joins) {
+      const processedTable = normalizeTableRef(join3.table);
+      const processedOn = processJoinOn(join3.on);
+      const type = join3.type || "left";
+      switch (type) {
+        case "inner":
+          builder.innerJoin(processedTable, processedOn);
+          break;
+        case "right":
+          builder.rightJoin(processedTable, processedOn);
+          break;
+        case "left":
+        default:
+          builder.leftJoin(processedTable, processedOn);
+          break;
+      }
+    }
+  }
+};
+
+// lib/dbHelper/dataOps.js
+var dataOpsMethods = {
+  async getCount(options) {
+    const { table, where, joins, tableQualifier } = await this.prepareQueryOptions(options, "getCount.options");
+    const hasJoins = Array.isArray(joins) && joins.length > 0;
+    const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasJoins);
+    const result = await this.fetchCount({ table, joins }, whereFiltered, "COUNT(*) as count");
+    return {
+      data: result.total,
+      sql: result.sql
+    };
+  },
+  async getOne(options) {
+    const { table, fields, where, joins, tableQualifier } = await this.prepareQueryOptions(options, "getOne.options");
+    const hasJoins = Array.isArray(joins) && joins.length > 0;
+    const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasJoins);
+    const builder = this.createSqlBuilder().select(fields).from(table).where(whereFiltered);
+    this.applyJoins(builder, joins);
+    const { sql, params } = builder.toSelectSql();
+    const executeRes = await this.execute(sql, params);
+    const result = executeRes.data;
+    const data = this.normalizeRowData(result?.[0] || null, options.bigint);
+    return {
+      data,
+      sql: executeRes.sql
+    };
+  },
+  async getDetail(options) {
+    return await this.getOne(options);
+  },
+  async getList(options) {
+    const prepared = await this.prepareQueryOptions(options, "getList.options");
+    validatePageLimitRange(prepared, options.table);
+    const hasJoins = Array.isArray(prepared.joins) && prepared.joins.length > 0;
+    const whereFiltered = addDefaultStateFilter(prepared.where, prepared.tableQualifier, hasJoins);
+    const countResult = await this.fetchCount(prepared, whereFiltered, "COUNT(*) as total");
+    const total = countResult.total;
+    const offset = (prepared.page - 1) * prepared.limit;
+    const dataBuilder = this.createListBuilder(prepared, whereFiltered, prepared.limit, offset);
+    const { sql: dataSql, params: dataParams } = dataBuilder.toSelectSql();
+    if (total === 0) {
+      return {
+        data: {
+          lists: [],
+          total: 0,
+          page: prepared.page,
+          limit: prepared.limit,
+          pages: 0
+        },
+        sql: {
+          count: countResult.sql,
+          data: {
+            sql: dataSql,
+            params: dataParams,
+            duration: 0
+          }
+        }
+      };
+    }
+    const listExecuteRes = await this.execute(dataSql, dataParams);
+    const list = listExecuteRes.data || [];
+    return {
+      data: {
+        lists: this.normalizeListData(list, options.bigint),
+        total,
+        page: prepared.page,
+        limit: prepared.limit,
+        pages: Math.ceil(total / prepared.limit)
+      },
+      sql: {
+        count: countResult.sql,
+        data: listExecuteRes.sql
+      }
+    };
+  },
+  async getAll(options) {
+    const MAX_LIMIT = 1e4;
+    const WARNING_LIMIT = 1000;
+    const prepareOptions = this.buildQueryOptions(options, { page: 1, limit: 10 });
+    const prepared = await this.prepareQueryOptions(prepareOptions, "getAll.options");
+    const hasJoins = Array.isArray(prepared.joins) && prepared.joins.length > 0;
+    const whereFiltered = addDefaultStateFilter(prepared.where, prepared.tableQualifier, hasJoins);
+    const countResult = await this.fetchCount(prepared, whereFiltered, "COUNT(*) as total");
+    const total = countResult.total;
+    if (total === 0) {
+      return {
+        data: {
+          lists: [],
+          total: 0
+        },
+        sql: {
+          count: countResult.sql
+        }
+      };
+    }
+    const dataBuilder = this.createListBuilder(prepared, whereFiltered, MAX_LIMIT, null);
+    const { sql: dataSql, params: dataParams } = dataBuilder.toSelectSql();
+    const listExecuteRes = await this.execute(dataSql, dataParams);
+    const result = listExecuteRes.data || [];
+    if (result.length >= WARNING_LIMIT) {
+      Logger.warn("getAll \u8FD4\u56DE\u6570\u636E\u8FC7\u591A\uFF0C\u5EFA\u8BAE\u4F7F\u7528 getList \u5206\u9875\u67E5\u8BE2", { table: options.table, count: result.length, total });
+    }
+    if (result.length >= MAX_LIMIT) {
+      Logger.warn(`getAll \u8FBE\u5230\u6700\u5927\u9650\u5236 ${MAX_LIMIT}\uFF0C\u5B9E\u9645\u603B\u6570 ${total}\uFF0C\u53EA\u8FD4\u56DE\u524D ${MAX_LIMIT} \u6761`, { table: options.table, limit: MAX_LIMIT, total });
+    }
+    const lists = this.normalizeListData(result, options.bigint);
+    return {
+      data: {
+        lists,
+        total
+      },
+      sql: {
+        count: countResult.sql,
+        data: listExecuteRes.sql
+      }
+    };
+  },
+  async exists(options) {
+    validateNoJoinReadOptions(options, "exists", "exists \u4E0D\u652F\u6301 joins\uFF08\u8BF7\u4F7F\u7528\u663E\u5F0F query \u6216\u62C6\u5206\u67E5\u8BE2\uFF09");
+    const snakeTable = snakeCase(options.table);
+    const snakeWhere = whereKeysToSnake(clearDeep(options.where || {}));
+    const whereFiltered = addDefaultStateFilter(snakeWhere, snakeTable, false);
+    const builder = this.createSqlBuilder().selectRaw("COUNT(1) as cnt").from(snakeTable).where(whereFiltered).limit(1);
+    const { sql, params } = builder.toSelectSql();
+    const executeRes = await this.execute(sql, params);
+    const exists = (executeRes.data?.[0]?.cnt || 0) > 0;
+    return { data: exists, sql: executeRes.sql };
+  },
+  async getFieldValue(options) {
+    validateNoJoinReadOptions(options, "getFieldValue", "getFieldValue \u4E0D\u652F\u6301 joins\uFF08\u8BF7\u4F7F\u7528 getOne/getList \u5E76\u81EA\u884C\u53D6\u5B57\u6BB5\uFF09");
+    const field = options.field;
+    validateSafeFieldName(field);
+    const oneOptions = {
+      table: options.table
+    };
+    if (options.where !== undefined)
+      oneOptions.where = options.where;
+    if (options.joins !== undefined)
+      oneOptions.joins = options.joins;
+    if (options.orderBy !== undefined)
+      oneOptions.orderBy = options.orderBy;
+    if (options.page !== undefined)
+      oneOptions.page = options.page;
+    if (options.limit !== undefined)
+      oneOptions.limit = options.limit;
+    oneOptions.fields = [field];
+    const oneRes = await this.getOne(oneOptions);
+    const result = oneRes.data;
+    const value = this.resolveFieldValue(result, field);
+    return {
+      data: value,
+      sql: oneRes.sql
+    };
+  },
+  async insData(options) {
+    validateTableDataOptions(options, "insData");
+    const { table, data } = options;
+    const snakeTable = snakeCase(table);
+    const now = Date.now();
+    let processed;
+    if (this.idMode === "autoId") {
+      processed = buildInsertRow({ idMode: "autoId", data, now });
+    } else {
+      let id;
+      try {
+        id = await this.redis.genTimeID();
+      } catch (error48) {
+        throw new Error(`\u751F\u6210 ID \u5931\u8D25\uFF0CRedis \u53EF\u80FD\u4E0D\u53EF\u7528 (table: ${table})`, {
+          cause: error48,
+          code: "runtime",
+          subsystem: "db",
+          operation: "genTimeId",
+          table
+        });
+      }
+      processed = buildInsertRow({ idMode: "timeId", data, id, now });
+    }
+    assertNoUndefinedInRecord(processed, `insData \u63D2\u5165\u6570\u636E (table: ${snakeTable})`);
+    const builder = this.createSqlBuilder();
+    const { sql, params } = builder.toInsertSql(snakeTable, processed);
+    const executeRes = await this.execute(sql, params);
+    const processedId = processed["id"];
+    const processedIdNum = isNumber(processedId) ? processedId : 0;
+    const lastInsertRowidNum = toNumberFromSql(executeRes.data?.lastInsertRowid);
+    const insertedId = this.idMode === "autoId" ? lastInsertRowidNum || 0 : processedIdNum || lastInsertRowidNum || 0;
+    if (this.idMode === "autoId" && insertedId <= 0) {
+      throw new Error(`\u63D2\u5165\u5931\u8D25\uFF1AautoId \u6A21\u5F0F\u4E0B\u65E0\u6CD5\u83B7\u53D6 lastInsertRowid (table: ${table})`, {
+        cause: null,
+        code: "runtime"
+      });
+    }
+    return {
+      data: insertedId,
+      sql: executeRes.sql
+    };
+  },
+  async insBatch(table, dataList) {
+    validateTableBatchDataOptions(table, dataList, "insBatch");
+    if (dataList.length === 0) {
+      return {
+        data: [],
+        sql: { sql: "", params: [], duration: 0 }
+      };
+    }
+    const MAX_BATCH_SIZE = 1000;
+    validateInsertBatchSize(dataList.length, MAX_BATCH_SIZE);
+    const snakeTable = snakeCase(table);
+    const now = Date.now();
+    let ids = [];
+    let processedList;
+    if (this.idMode === "autoId") {
+      processedList = dataList.map((data) => {
+        return buildInsertRow({ idMode: "autoId", data, now });
+      });
+    } else {
+      const nextIds = [];
+      for (let i = 0;i < dataList.length; i++) {
+        nextIds.push(await this.redis.genTimeID());
+      }
+      ids = nextIds;
+      processedList = dataList.map((data, index) => {
+        const id = nextIds[index];
+        validateGeneratedBatchId(id, snakeTable, index);
+        return buildInsertRow({ idMode: "timeId", data, id, now });
+      });
+    }
+    const insertFields = assertBatchInsertRowsConsistent(processedList, { table: snakeTable });
+    const builder = this.createSqlBuilder();
+    const { sql, params } = builder.toInsertSql(snakeTable, processedList);
+    try {
+      const executeRes = await this.execute(sql, params);
+      if (this.idMode === "autoId") {
+        const firstId = toNumberFromSql(executeRes.data?.lastInsertRowid);
+        if (firstId <= 0) {
+          throw new Error(`\u6279\u91CF\u63D2\u5165\u5931\u8D25\uFF1AautoId \u6A21\u5F0F\u4E0B\u65E0\u6CD5\u83B7\u53D6 lastInsertRowid (table: ${table})`, {
+            cause: null,
+            code: "runtime"
+          });
+        }
+        const outIds = [];
+        for (let i = 0;i < dataList.length; i++) {
+          outIds.push(firstId + i);
+        }
+        return {
+          data: outIds,
+          sql: executeRes.sql
+        };
+      }
+      return {
+        data: ids,
+        sql: executeRes.sql
+      };
+    } catch (error48) {
+      Logger.error("\u6279\u91CF\u63D2\u5165\u5931\u8D25", error48, {
+        table,
+        snakeTable,
+        count: dataList.length,
+        fields: insertFields
+      });
+      throw new Error("\u6279\u91CF\u63D2\u5165\u5931\u8D25", {
+        cause: error48,
+        code: "runtime",
+        subsystem: "sql",
+        operation: "insBatch",
+        table,
+        snakeTable,
+        count: dataList.length,
+        fields: insertFields
+      });
+    }
+  },
+  async delForceBatch(table, ids) {
+    validateTableName(table, "delForceBatch.table");
+    if (ids.length === 0) {
+      return {
+        data: 0,
+        sql: { sql: "", params: [], duration: 0 }
+      };
+    }
+    const snakeTable = snakeCase(table);
+    const query = SqlBuilder.toDeleteInSql({
+      table: snakeTable,
+      idField: "id",
+      ids,
+      quoteIdent: quoteIdentMySql
+    });
+    const executeRes = await this.execute(query.sql, query.params);
+    const changes = toNumberFromSql(executeRes.data?.changes);
+    return {
+      data: changes,
+      sql: executeRes.sql
+    };
+  },
+  async updBatch(table, dataList) {
+    validateTableBatchDataOptions(table, dataList, "updBatch");
+    if (dataList.length === 0) {
+      return {
+        data: 0,
+        sql: { sql: "", params: [], duration: 0 }
+      };
+    }
+    const snakeTable = snakeCase(table);
+    const now = Date.now();
+    const processedList = [];
+    const fieldSet = new Set;
+    for (const item of dataList) {
+      const userData = buildPartialUpdateData({ data: item.data, allowState: true });
+      for (const key of Object.keys(userData)) {
+        fieldSet.add(key);
+      }
+      processedList.push({ id: item.id, data: userData });
+    }
+    const fields = Array.from(fieldSet).sort();
+    if (fields.length === 0) {
+      return {
+        data: 0,
+        sql: { sql: "", params: [], duration: 0 }
+      };
+    }
+    const query = SqlBuilder.toUpdateCaseByIdSql({
+      table: snakeTable,
+      idField: "id",
+      rows: processedList,
+      fields,
+      quoteIdent: quoteIdentMySql,
+      updatedAtField: "updated_at",
+      updatedAtValue: now,
+      stateField: "state",
+      stateGtZero: true
+    });
+    const executeRes = await this.execute(query.sql, query.params);
+    const changes = toNumberFromSql(executeRes.data?.changes);
+    return {
+      data: changes,
+      sql: executeRes.sql
+    };
+  },
+  async updData(options) {
+    validateTableDataOptions(options, "updData");
+    validateTableWhereOptions(options, "updData", true);
+    const { table, data, where } = options;
+    const snakeTable = snakeCase(table);
+    const snakeWhere = whereKeysToSnake(clearDeep(where));
+    const processed = buildUpdateRow({ data, now: Date.now(), allowState: true });
+    const whereFiltered = addDefaultStateFilter(snakeWhere, snakeTable, false);
+    const builder = this.createSqlBuilder().where(whereFiltered);
+    const { sql, params } = builder.toUpdateSql(snakeTable, processed);
+    const executeRes = await this.execute(sql, params);
+    const changes = toNumberFromSql(executeRes.data?.changes);
+    return {
+      data: changes,
+      sql: executeRes.sql
+    };
+  },
+  async delData(options) {
+    validateTableWhereOptions(options, "delData", true);
+    const { table, where } = options;
+    return await this.updData({
+      table,
+      data: { state: 0, deleted_at: Date.now() },
+      where
+    });
+  },
+  async delForce(options) {
+    validateTableWhereOptions(options, "delForce", true);
+    const { table, where } = options;
+    const snakeTable = snakeCase(table);
+    const snakeWhere = whereKeysToSnake(clearDeep(where));
+    const builder = this.createSqlBuilder().where(snakeWhere);
+    const { sql, params } = builder.toDeleteSql(snakeTable);
+    const executeRes = await this.execute(sql, params);
+    const changes = toNumberFromSql(executeRes.data?.changes);
+    return {
+      data: changes,
+      sql: executeRes.sql
+    };
+  },
+  async disableData(options) {
+    validateTableWhereOptions(options, "disableData", true);
+    const { table, where } = options;
+    return await this.updData({
+      table,
+      data: {
+        state: 2
+      },
+      where
+    });
+  },
+  async enableData(options) {
+    validateTableWhereOptions(options, "enableData", true);
+    const { table, where } = options;
+    return await this.updData({
+      table,
+      data: {
+        state: 1
+      },
+      where
+    });
+  },
+  async increment(table, field, where, value = 1) {
+    validateIncrementOptions(table, field, where, value, "increment");
+    const snakeTable = snakeCase(table);
+    const snakeField = snakeCase(field);
+    const snakeWhere = whereKeysToSnake(clearDeep(where));
+    const whereFiltered = addDefaultStateFilter(snakeWhere, snakeTable, false);
+    const builder = this.createSqlBuilder().where(whereFiltered);
+    const { sql: whereClause, params: whereParams } = builder.getWhereConditions();
+    const quotedTable = quoteIdentMySql(snakeTable);
+    const quotedField = quoteIdentMySql(snakeField);
+    const sql = whereClause ? `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ? WHERE ${whereClause}` : `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ?`;
+    const params = [value];
+    for (const param of whereParams) {
+      params.push(param);
+    }
+    const executeRes = await this.execute(sql, params);
+    const changes = toNumberFromSql(executeRes.data?.changes);
+    return {
+      data: changes,
+      sql: executeRes.sql
+    };
+  },
+  async decrement(table, field, where, value = 1) {
+    return await this.increment(table, field, where, -value);
+  }
+};
+
+// lib/dbHelper/execute.js
+var executeMethods = {
+  async execute(sql, params) {
+    if (!this.sql) {
+      throw new Error("\u6570\u636E\u5E93\u8FDE\u63A5\u672A\u521D\u59CB\u5316", {
+        cause: null,
+        code: "runtime"
+      });
+    }
+    validateExecuteSql(sql);
+    const startTime = Date.now();
+    const safeParams = toSqlParams(params);
+    try {
+      let queryResult;
+      if (safeParams.length > 0) {
+        queryResult = await this.sql.unsafe(sql, safeParams);
+      } else {
+        queryResult = await this.sql.unsafe(sql);
+      }
+      const duration3 = Date.now() - startTime;
+      return {
+        data: queryResult,
+        sql: {
+          sql,
+          params: safeParams,
+          duration: duration3
+        }
+      };
+    } catch (error48) {
+      const duration3 = Date.now() - startTime;
+      const msg = error48 instanceof Error ? error48.message : String(error48);
+      throw new DbSqlError(`SQL\u6267\u884C\u5931\u8D25: ${msg}`, {
+        originalError: error48,
+        params: safeParams,
+        duration: duration3,
+        sqlInfo: {
+          sql,
+          params: safeParams,
+          duration: duration3
+        }
+      });
+    }
+  },
+  async tableExists(tableName) {
+    const snakeTableName = snakeCase(tableName);
+    const executeRes = await this.execute("SELECT COUNT(*) as count FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?", [snakeTableName]);
+    const exists = (executeRes.data?.[0]?.count || 0) > 0;
+    return {
+      data: exists,
+      sql: executeRes.sql
+    };
+  }
+};
+
+// lib/dbHelper/transaction.js
+var transactionMethods = {
+  async trans(callback) {
+    if (this.isTransaction) {
+      const innerResult = await callback(this);
+      if (isBeflyResponse(innerResult) && innerResult.code !== 0) {
+        throw new TransAbortError(innerResult);
+      }
+      return innerResult;
+    }
+    const sql = this.sql;
+    if (!sql) {
+      throw new Error("\u6570\u636E\u5E93\u8FDE\u63A5\u672A\u521D\u59CB\u5316", {
+        cause: null,
+        code: "runtime"
+      });
+    }
+    if (!hasBegin(sql)) {
+      throw new Error("\u5F53\u524D SQL \u5BA2\u6237\u7AEF\u4E0D\u652F\u6301\u4E8B\u52A1 begin() \u65B9\u6CD5", {
+        cause: null,
+        code: "runtime"
+      });
+    }
+    try {
+      return await sql.begin(async (tx) => {
+        const trans = new this.constructor({ redis: this.redis, dbName: this.dbName, sql: tx, idMode: this.idMode });
+        const result = await callback(trans);
+        if (isBeflyResponse(result) && result.code !== 0) {
+          throw new TransAbortError(result);
+        }
+        return result;
+      });
+    } catch (error48) {
+      if (error48 instanceof TransAbortError) {
+        return error48.payload;
+      }
+      throw error48;
+    }
+  }
+};
+
+// lib/dbHelper/index.js
+function DbHelper(options) {
+  this.redis = options.redis;
+  if (!isNonEmptyString(options.dbName)) {
+    throw new Error("DbHelper \u521D\u59CB\u5316\u5931\u8D25\uFF1AdbName \u5FC5\u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32", {
+      cause: null,
+      code: "validation"
+    });
+  }
+  this.dbName = options.dbName;
+  this.sql = options.sql || null;
+  this.isTransaction = Boolean(options.sql);
+  this.idMode = options.idMode === "autoId" ? "autoId" : "timeId";
+}
+Object.assign(DbHelper.prototype, builderMethods, executeMethods, dataOpsMethods, transactionMethods);
+DbHelper.convertBigIntFields = convertBigIntFields;
+
+// utils/importDefault.js
+import { isAbsolute as isAbsolute2 } from "path";
+import { pathToFileURL } from "url";
+function isWindowsAbsPath(file) {
+  return /^[a-zA-Z]:[\\/]/.test(file);
+}
+function toFileImportUrl(file) {
+  if (isAbsolute2(file) || isWindowsAbsPath(file)) {
+    return pathToFileURL(file).href;
+  }
+  return file;
+}
+async function importDefault(file, defaultValue) {
+  try {
+    const isJson = file.endsWith(".json");
+    const mod = isJson ? await import(toFileImportUrl(file), { with: { type: "json" } }) : await import(file);
+    const value = mod?.default;
+    if (isNullable(value)) {
+      return defaultValue;
+    }
+    const expectedType = getTypeTag(defaultValue);
+    const actualType = getTypeTag(value);
+    if (expectedType !== actualType) {
+      Logger.warn("importDefault \u5BFC\u5165\u7C7B\u578B\u4E0E\u9ED8\u8BA4\u503C\u4E0D\u4E00\u81F4\uFF0C\u5DF2\u56DE\u9000\u5230\u9ED8\u8BA4\u503C", { file, expectedType, actualType });
+      return defaultValue;
+    }
+    return value;
+  } catch (err) {
+    Logger.warn("importDefault \u5BFC\u5165\u5931\u8D25\uFF0C\u5DF2\u56DE\u9000\u5230\u9ED8\u8BA4\u503C", { err, file });
+    return defaultValue;
+  }
+}
+
+// scripts/syncDb/query.js
+var 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
+`;
+async function querySyncDbColumns(mysql) {
+  const queryRes = await mysql.execute(SYNC_DB_COLUMNS_SQL);
+  if (!Array.isArray(queryRes.data)) {
+    return [];
+  }
+  return queryRes.data;
+}
+
+// scripts/syncDb/context.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 = basename2(filePath, ".json");
+    const tableKey = String(camelCase(fileName)).toLowerCase();
+    if (fileName.startsWith("_")) {
+      continue;
+    }
+    const loaded = await importDefault(filePath, {});
+    if (!isPlainObject2(loaded)) {
+      Logger.warn("tables \u5B9A\u4E49\u6587\u4EF6\u4E0D\u662F\u5BF9\u8C61\uFF0C\u5DF2\u6309\u7A7A\u5BF9\u8C61\u5904\u7406", {
+        filePath
+      });
+      tableMap.set(tableKey, {
+        filePath,
+        tableDef: {}
+      });
+      continue;
+    }
+    tableMap.set(tableKey, {
+      filePath,
+      tableDef: loaded
+    });
+  }
+  return tableMap;
+}
+async function prepareSyncDbBaseContext(mysqlConfig) {
+  const tablesDir = resolve2(join3(process.cwd(), "tables"));
+  await mkdir(tablesDir, { recursive: true });
+  if (!isPlainObject2(mysqlConfig)) {
+    throw new Error("syncDb \u7F3A\u5C11 mysql \u914D\u7F6E", {
+      cause: null,
+      code: "validation",
+      subsystem: "scripts",
+      operation: "syncDb"
+    });
+  }
+  await Connect.connectMysql(mysqlConfig);
+  const mysql = new DbHelper({
+    redis: null,
+    dbName: mysqlConfig.database,
+    sql: Connect.getMysql(),
+    idMode: mysqlConfig.idMode
+  });
+  const dbColumns = await querySyncDbColumns(mysql);
+  const skippedBeflyTables = new Set;
+  for (const row of dbColumns) {
+    const tableName = String(row?.tableName || "");
+    if (isNonEmptyString(tableName) && tableName.toLowerCase().startsWith("befly_")) {
+      skippedBeflyTables.add(tableName);
+    }
+  }
+  if (skippedBeflyTables.size > 0) {
+    const skippedTables = Array.from(skippedBeflyTables).sort((left, right) => left.localeCompare(right));
+    Logger.info("\u5DF2\u8DF3\u8FC7 befly_ \u524D\u7F00\u8868\uFF0C\u4E0D\u53C2\u4E0E\u5BF9\u6BD4", {
+      skippedTableCount: skippedBeflyTables.size,
+      skippedTables
+    });
+  }
+  const groupedDbColumns = groupSyncDbColumns(dbColumns);
+  const existingTableMap = await loadSyncDbTableDefs(tablesDir);
+  const diff = buildSyncDbDiff(groupedDbColumns, existingTableMap);
+  return {
+    diff,
+    groupedDbColumns,
+    tablesDir,
+    existingTableMap
+  };
+}
+
+// scripts/syncDb/report.js
+import { mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname2 } from "path";
+function printSyncDbDiffSummary(mode, diff) {
+  const tableNames = diff.missingTables.map((item) => item.tableName);
+  const missingFieldGroups = Object.values(diff.missingFieldsByTable);
+  const missingFieldCount = countSyncDbMissingFields(diff);
+  Logger.info("DB \u4E0E\u9879\u76EE\u6839\u76EE\u5F55 tables \u5DEE\u5F02\u68C0\u67E5\u5B8C\u6210", {
+    mode,
+    missingTableCount: diff.missingTables.length,
+    missingFieldCount,
+    missingTables: tableNames
+  });
+  for (const item of missingFieldGroups) {
+    Logger.info("\u53D1\u73B0\u7F3A\u5931\u5B57\u6BB5", {
+      tableName: item.tableName,
+      tableFileName: item.tableFileName,
+      fieldNames: item.fields.map((field) => field.fieldName)
+    });
+  }
+}
+function escapeSyncDbMdCell(value) {
+  const text = String(value ?? "");
+  return text.replaceAll("|", "\\|").replaceAll(`
+`, "<br>");
+}
+function formatSyncDbValue(value) {
+  if (value === null || value === undefined) {
+    return "-";
+  }
+  if (value === "") {
+    return "-";
+  }
+  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: "\u7F3A\u5C11\u8868",
+        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
+      });
+    }
+  }
+  for (const tableInfo of Object.values(diff.missingFieldsByTable)) {
+    for (const fieldItem of tableInfo.fields) {
+      rows.push({
+        diffType: "\u7F3A\u5C11\u5B57\u6BB5",
+        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
+      });
+    }
+  }
+  return rows;
+}
+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,
+        tableFileName,
+        rows: []
+      });
+    }
+    grouped.get(groupKey).rows.push(row);
+  }
+  return Array.from(grouped.values());
+}
+function buildSyncDbAllTableRows(groupedDbColumns, existingTableMap) {
+  const rows = [];
+  for (const [tableName, columns] of groupedDbColumns.entries()) {
+    const hasTableDef = existingTableMap.has(String(camelCase(tableName)).toLowerCase()) ? "\u662F" : "\u5426";
+    const tableComment = isNonEmptyString(columns[0]?.tableComment) ? String(columns[0].tableComment).trim() : "-";
+    rows.push({
+      tableName,
+      tableComment,
+      columnCount: columns.length,
+      hasTableDef
+    });
+  }
+  return rows;
+}
+function buildSyncDbCheckMarkdown(diff, groupedDbColumns, existingTableMap) {
+  const allTableRows = buildSyncDbAllTableRows(groupedDbColumns, existingTableMap);
+  const rows = buildSyncDbCheckRows(diff);
+  const diffGroups = groupSyncDbDiffRowsByTable(rows);
+  const missingFieldCount = countSyncDbMissingFields(diff);
+  const lines = [];
+  lines.push("# DB \u4E0E\u9879\u76EE\u6839\u76EE\u5F55 tables \u5DEE\u5F02\u62A5\u544A");
+  lines.push("");
+  lines.push(`- \u751F\u6210\u65F6\u95F4\u6233: ${String(Date.now())}`);
+  lines.push(`- \u626B\u63CF\u6570\u636E\u5E93\u8868\u6570\u91CF: ${String(allTableRows.length)}`);
+  lines.push(`- \u7F3A\u5C11\u8868\u6570\u91CF: ${String(diff.missingTables.length)}`);
+  lines.push(`- \u7F3A\u5C11\u5B57\u6BB5\u6570\u91CF: ${String(missingFieldCount)}`);
+  lines.push("");
+  lines.push("## \u5168\u90E8\u6570\u636E\u5E93\u8868\u4FE1\u606F");
+  lines.push("");
+  lines.push(`| \u6570\u636E\u5E93\u8868 | \u8868\u8BF4\u660E | \u5217\u6570\u91CF | tables\u4E2D\u662F\u5426\u5B58\u5728 |
+|---|---|---:|---|`);
+  if (allTableRows.length === 0) {
+    lines.push("| - | - | - | \u672A\u626B\u63CF\u5230\u53EF\u5BF9\u6BD4\u8868\uFF08\u53EF\u80FD\u5168\u90E8\u88AB\u8FC7\u6EE4\uFF09 |");
+  } else {
+    for (const row of allTableRows) {
+      lines.push(`| ${escapeSyncDbMdCell(formatSyncDbValue(row.tableName))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.tableComment))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.columnCount))} | ${escapeSyncDbMdCell(formatSyncDbValue(row.hasTableDef))} |`);
+    }
+  }
+  lines.push("");
+  lines.push("## \u5168\u90E8\u5DEE\u5F02\u4FE1\u606F");
+  lines.push("");
+  if (rows.length === 0) {
+    lines.push("- \u672A\u53D1\u73B0\u5DEE\u5F02");
+    lines.push("");
+    return lines.join(`
+`);
+  }
+  for (const group of diffGroups) {
+    lines.push(`### ${escapeSyncDbMdCell(formatSyncDbValue(group.tableName))}\uFF08${escapeSyncDbMdCell(formatSyncDbValue(group.tableFileName))}\uFF09`);
+    lines.push("");
+    lines.push("| \u5DEE\u5F02\u7C7B\u578B | \u6570\u636E\u5E93\u5B57\u6BB5\u540D | \u5B57\u6BB5\u6807\u8BC6 | \u5B57\u6BB5\u540D\u79F0 | \u5B57\u6BB5\u7C7B\u578B | \u5217\u7C7B\u578B | \u5B57\u7B26\u4E32\u957F\u5EA6 | \u63A8\u65ADinput | \u63A8\u65ADmax |");
+    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))} |`);
+    }
+    lines.push("");
+  }
+  lines.push("");
+  return lines.join(`
+`);
+}
+async function writeSyncDbCheckReport(reportPath, diff, groupedDbColumns, existingTableMap) {
+  if (!isNonEmptyString(reportPath)) {
+    return "";
+  }
+  await mkdir2(dirname2(reportPath), { recursive: true });
+  const markdown = buildSyncDbCheckMarkdown(diff, groupedDbColumns, existingTableMap);
+  await Bun.write(reportPath, markdown);
+  Logger.info("\u5DEE\u5F02\u62A5\u544A\u5199\u5165\u5B8C\u6210", {
+    reportPath
+  });
+  return reportPath;
+}
+
+// scripts/syncDb/index.js
+async function syncDbCheck(mysqlConfig) {
+  try {
+    const reportPath = resolve3(join4(process.cwd(), "db.check.md"));
+    await mkdir3(dirname3(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);
+    return {
+      mode: "check",
+      createdTableFileCount: 0,
+      appendedFieldCount: 0,
+      missingTableCount: diff.missingTables.length,
+      missingFieldCount,
+      hasDiff: diff.missingTables.length > 0 || missingFieldCount > 0,
+      reportPath: writtenReportPath
+    };
+  } catch (error48) {
+    throw new Error("\u6267\u884C\u8868\u5B9A\u4E49\u540C\u6B65\u5931\u8D25", {
+      cause: error48,
+      code: "runtime",
+      subsystem: "scripts",
+      operation: "syncDb"
+    });
+  } finally {
+    await Connect.disconnect();
+    await Logger.flush();
+  }
+}
+async function syncDbApply(mysqlConfig) {
+  try {
+    const { diff, tablesDir, existingTableMap } = await prepareSyncDbBaseContext(mysqlConfig);
+    printSyncDbDiffSummary("check", diff);
+    const applyResult = await applySyncDbDiff(diff, tablesDir, existingTableMap);
+    printSyncDbDiffSummary("apply", diff);
+    return {
+      mode: "apply",
+      createdTableFileCount: applyResult.createdTableFileCount,
+      appendedFieldCount: applyResult.appendedFieldCount,
+      missingTableCount: diff.missingTables.length,
+      missingFieldCount: applyResult.appendedFieldCount,
+      hasDiff: diff.missingTables.length > 0 || applyResult.appendedFieldCount > 0,
+      reportPath: ""
+    };
+  } catch (error48) {
+    throw new Error("\u6267\u884C\u8868\u5B9A\u4E49\u540C\u6B65\u5931\u8D25", {
+      cause: error48,
+      code: "runtime",
+      subsystem: "scripts",
+      operation: "syncDb"
+    });
+  } finally {
+    await Connect.disconnect();
+    await Logger.flush();
+  }
+}
+
+// utils/calcPerfTime.js
+var calcPerfTime = (startTime, endTime = Bun.nanoseconds()) => {
+  const elapsedMs = (endTime - startTime) / 1e6;
+  if (elapsedMs < 1000) {
+    return `${elapsedMs.toFixed(2)} \u6BEB\u79D2`;
+  } else {
+    const elapsedSeconds = elapsedMs / 1000;
+    return `${elapsedSeconds.toFixed(2)} \u79D2`;
+  }
+};
+
+// utils/scanFiles.js
+import { existsSync as existsSync2 } from "fs";
+async function scanFiles(dir, source, type, pattern) {
+  try {
+    const glob = new Bun.Glob(pattern);
+    if (!existsSync2(dir))
+      return [];
+    const results = [];
+    const files = await glob.scan({
+      cwd: dir,
+      onlyFiles: true,
+      absolute: true,
+      followSymlinks: true
+    });
+    for await (const file of files) {
+      const filePath = normalize(file);
+      const parsedFile = parse5(filePath);
+      const fileName = parsedFile.name;
+      const parsedRelativePath = parse5(relative(dir, filePath));
+      const relativePath = parsedRelativePath.dir ? join(parsedRelativePath.dir, parsedRelativePath.name) : parsedRelativePath.name;
+      if (relativePath.split("/").some((part) => part.startsWith("_")))
+        continue;
+      const content = await importDefault(filePath, {});
+      const contentObj = isPlainObject2(content) ? content : {};
+      const base = {
+        source,
+        type,
+        filePath,
+        relativePath,
+        fileName,
+        apiPath: `/api/${source}/${relativePath}`
+      };
+      if (type === "table") {
+        base["fieldsDef"] = contentObj;
+      }
+      if (type === "api") {
+        base["name"] = "";
+      }
+      if (type !== "table") {
+        for (const [key, value] of Object.entries(contentObj)) {
+          if (base[key])
+            continue;
+          base[key] = value;
+        }
+      }
+      results.push(base);
+    }
+    return results;
+  } catch (error48) {
+    throw new Error(`\u626B\u63CF\u5931\u8D25: source=${source} type=${type} dir=${dir} pattern=${pattern}`, {
+      cause: error48,
+      code: "runtime"
+    });
+  }
+}
+
+// utils/scanSources.js
+var scanSources = async () => {
+  const apis = [];
+  const plugins = [];
+  const hooks = [];
+  const tables = [];
+  const allCoreTables = await scanFiles(coreTableDir, "core", "table", "*.json");
+  for (const item of allCoreTables) {
+    tables.push(item);
+  }
+  const allAppTables = await scanFiles(appTableDir, "app", "table", "*.json");
+  for (const item of allAppTables) {
+    tables.push(item);
+  }
+  const allCorePlugins = await scanFiles(corePluginDir, "core", "plugin", "*.js");
+  for (const item of allCorePlugins) {
+    plugins.push(item);
+  }
+  const allAppPlugins = await scanFiles(appPluginDir, "app", "plugin", "*.js");
+  for (const item of allAppPlugins) {
+    plugins.push(item);
+  }
+  const allCoreHooks = await scanFiles(coreHookDir, "core", "hook", "*.js");
+  for (const item of allCoreHooks) {
+    hooks.push(item);
+  }
+  const allAppHooks = await scanFiles(appHookDir, "app", "hook", "*.js");
+  for (const item of allAppHooks) {
+    hooks.push(item);
+  }
+  const allCoreApis = await scanFiles(coreApiDir, "core", "api", "**/*.js");
+  for (const item of allCoreApis) {
+    apis.push(item);
+  }
+  const allAppApis = await scanFiles(appApiDir, "app", "api", "**/*.js");
+  for (const item of allAppApis) {
+    apis.push(item);
+  }
+  return {
+    hooks,
+    plugins,
+    apis,
+    tables
+  };
+};
+
+// utils/deepMerge.js
+function clone2(value) {
+  return structuredClone(value);
+}
+function concat(targetArr, sourceArr, cloneTargetItems) {
+  const nextArr = [];
+  if (cloneTargetItems) {
+    for (const item of targetArr) {
+      nextArr.push(clone2(item));
+    }
+  } else {
+    for (const item of targetArr) {
+      nextArr.push(item);
+    }
+  }
+  for (const item of sourceArr) {
+    nextArr.push(clone2(item));
+  }
+  return nextArr;
+}
+function mergeValue(baseValue, incomingValue) {
+  if (Array.isArray(baseValue) && Array.isArray(incomingValue)) {
+    return concat(baseValue, incomingValue, false);
+  }
+  if (isPlainObject2(baseValue) && isPlainObject2(incomingValue)) {
+    mergeInto(baseValue, incomingValue);
+    return baseValue;
+  }
+  return clone2(incomingValue);
+}
+function mergeInto(base, incoming) {
+  for (const key of Object.keys(incoming)) {
+    const incomingValue = incoming[key];
+    if (incomingValue === undefined) {
+      continue;
+    }
+    base[key] = mergeValue(base[key], incomingValue);
+  }
+  return base;
+}
+function deepMerge(source, target) {
+  if (Array.isArray(source) && Array.isArray(target)) {
+    const base = clone2(source);
+    const incoming = clone2(target);
+    return concat(base, incoming, false);
+  }
+  if (isPlainObject2(source) && isPlainObject2(target)) {
+    const base = clone2(source);
+    const incoming = clone2(target);
+    return mergeInto(base, incoming);
+  }
+  throw new Error("deepMerge: source/target \u5FC5\u987B\u540C\u4E3A\u6570\u7EC4\u6216\u540C\u4E3A\u666E\u901A\u5BF9\u8C61", {
+    cause: null,
+    code: "validation",
+    subsystem: "utils",
+    operation: "deepMerge"
+  });
+}
+
+// utils/sortModules.js
+function sortModules(items) {
+  const result = [];
+  const visited = new Set;
   const visiting = new Set;
   const nameToItem = {};
   let isPass = true;
@@ -12655,32 +16263,58 @@ class Befly {
   plugins = [];
   hooks = [];
   apis = {};
-  constructor(env = {}, config3 = {}, menus = []) {
-    this.context.env = env;
-    this.context.config = deepMerge(beflyConfig_default, config3);
-    this.menus = deepMerge(prefixMenuPaths(beflyMenus_default, "core"), prefixMenuPaths(menus, "app"));
+  scanApis = [];
+  scanPlugins = [];
+  scanHooks = [];
+  createdByFactory = false;
+  static async create(env = {}, config3 = {}, menus = []) {
+    const instance = new Befly;
+    instance.context.env = env;
+    instance.context.config = deepMerge(beflyConfig_default, config3);
+    instance.menus = deepMerge(prefixMenuPaths(beflyMenus_default, "core"), prefixMenuPaths(menus, "app"));
+    instance.createdByFactory = true;
+    const configHasError = await checkConfig(instance.context.config);
+    const { apis, tables, plugins, hooks } = await scanSources();
+    const apiHasError = await checkApi(apis);
+    const tableHasError = await checkTable(tables);
+    const pluginHasError = await checkPlugin(plugins);
+    const hookHasError = await checkHook(hooks);
+    const menuHasError = await checkMenu(instance.menus);
+    if (configHasError || apiHasError || tableHasError || pluginHasError || hookHasError || menuHasError) {
+      throw new Error("\u68C0\u67E5\u5931\u8D25\uFF1A\u5B58\u5728\u914D\u7F6E/\u7ED3\u6784\u95EE\u9898", {
+        cause: null,
+        code: "policy",
+        subsystem: "checks",
+        operation: "checkAll"
+      });
+    }
+    instance.scanApis = apis;
+    instance.scanPlugins = plugins;
+    instance.scanHooks = hooks;
+    return instance;
   }
   async start() {
     try {
+      if (!this.createdByFactory) {
+        throw new Error("\u8BF7\u4F7F\u7528 Befly.create(...) \u521B\u5EFA\u5B9E\u4F8B\u540E\u518D\u8C03\u7528 start", {
+          cause: null,
+          code: "policy",
+          subsystem: "start",
+          operation: "factoryGuard"
+        });
+      }
       const serverStartTime = Bun.nanoseconds();
-      const configHasError = await checkConfig(this.context.config);
-      const { apis, tables, plugins, hooks } = await scanSources();
-      const apiHasError = await checkApi(apis);
-      const tableHasError = await checkTable(tables);
-      const pluginHasError = await checkPlugin(plugins);
-      const hookHasError = await checkHook(hooks);
-      const menuHasError = await checkMenu(this.menus);
-      if (configHasError || apiHasError || tableHasError || pluginHasError || hookHasError || menuHasError) {
-        throw new Error("\u68C0\u67E5\u5931\u8D25\uFF1A\u5B58\u5728\u914D\u7F6E/\u7ED3\u6784\u95EE\u9898", {
+      if (!Array.isArray(this.scanApis) || !Array.isArray(this.scanPlugins) || !Array.isArray(this.scanHooks)) {
+        throw new Error("\u8BF7\u4F7F\u7528 Befly.create(...) \u5B8C\u6210\u9884\u68C0\u540E\u518D\u8C03\u7528 start", {
           cause: null,
           code: "policy",
-          subsystem: "checks",
-          operation: "checkAll"
+          subsystem: "start",
+          operation: "preflightGuard"
         });
       }
       await Connect.connectRedis(this.context.config.redis);
       await Connect.connectMysql(this.context.config.mysql);
-      const sortedPlugins = sortModules(plugins);
+      const sortedPlugins = sortModules(this.scanPlugins);
       if (sortedPlugins) {
         for (const item of sortedPlugins) {
           const pluginInstance = await item.handler(this.context);
@@ -12694,12 +16328,12 @@ class Befly {
       }
       await ensureSyncPrerequisites(this.context);
       if (isPrimaryProcess(this.context.env)) {
-        await syncApi(this.context, apis);
+        await syncApi(this.context, this.scanApis);
         await syncMenu(this.context, this.menus);
         await syncDev(this.context);
         await syncCache(this.context);
       }
-      const sortedHooks = sortModules(hooks);
+      const sortedHooks = sortModules(this.scanHooks);
       if (sortedHooks) {
         this.hooks = sortedHooks;
       } else {
@@ -12708,7 +16342,7 @@ class Befly {
           code: "policy"
         });
       }
-      for (const api2 of apis) {
+      for (const api2 of this.scanApis) {
         this.apis[api2.apiPath] = api2;
       }
       const apiFetch = apiHandler(this.apis, this.hooks, this.context);
@@ -12763,7 +16397,17 @@ class Befly {
     }
   }
 }
+async function dbCheck(config3 = {}) {
+  const mergedConfig = deepMerge(beflyConfig_default, config3);
+  return syncDbCheck(mergedConfig.mysql);
+}
+async function dbApply(config3 = {}) {
+  const mergedConfig = deepMerge(beflyConfig_default, config3);
+  return syncDbApply(mergedConfig.mysql);
+}
 export {
+  dbCheck,
+  dbApply,
   Logger,
   Befly
 };