befly 3.9.39 → 3.10.0

package/lib/dbHelper.ts

@@ -3,83 +3,56 @@
  * 提供数据库 CRUD 操作的封装
  */
 
-import type { BeflyContext } from "../types/befly.js";
 import type { WhereConditions, JoinOption } from "../types/common.js";
 import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, ListResult, AllResult, TransactionCallback } from "../types/database.js";
+import type { DbDialect } from "./dbDialect.js";
 
 import { snakeCase } from "es-toolkit/string";
 
 import { arrayKeysToCamel } from "../utils/arrayKeysToCamel.js";
+import { convertBigIntFields } from "../utils/convertBigIntFields.js";
 import { fieldClear } from "../utils/fieldClear.js";
 import { keysToCamel } from "../utils/keysToCamel.js";
-import { keysToSnake } from "../utils/keysToSnake.js";
 import { CacheKeys } from "./cacheKeys.js";
+import { MySqlDialect } from "./dbDialect.js";
+import { DbUtils } from "./dbUtils.js";
 import { Logger } from "./logger.js";
 import { SqlBuilder } from "./sqlBuilder.js";
+import { SqlCheck } from "./sqlCheck.js";
 
 const TABLE_COLUMNS_CACHE_TTL_SECONDS = 3600;
 
+type RedisCacheLike = {
+    getObject<T = any>(key: string): Promise<T | null>;
+    setObject<T = any>(key: string, obj: T, ttl?: number | null): Promise<string | null>;
+    genTimeID(): Promise<number>;
+};
+
 /**
  * 数据库助手类
  */
 export class DbHelper {
-    private befly: BeflyContext;
+    private redis: RedisCacheLike;
+    private dialect: DbDialect;
     private sql: any = null;
     private isTransaction: boolean = false;
 
     /**
      * 构造函数
-     * @param befly - Befly 上下文
+     * @param redis - Redis 实例
      * @param sql - Bun SQL 客户端（可选，用于事务）
      */
-    constructor(befly: BeflyContext, sql: any = null) {
-        this.befly = befly;
-        this.sql = sql;
-        this.isTransaction = !!sql;
-    }
-
-    /**
-     * 验证 fields 格式并分类
-     * @returns { type: 'all' | 'include' | 'exclude', fields: string[] }
-     * @throws 如果 fields 格式非法
-     */
-    private validateAndClassifyFields(fields?: string[]): {
-        type: "all" | "include" | "exclude";
-        fields: string[];
-    } {
-        // 情况1：空数组或 undefined，表示查询所有
-        if (!fields || fields.length === 0) {
-            return { type: "all", fields: [] };
-        }
-
-        // 检测是否有星号（禁止）
-        if (fields.some((f) => f === "*")) {
-            throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段");
-        }
-
-        // 检测是否有空字符串或无效值
-        if (fields.some((f) => !f || typeof f !== "string" || f.trim() === "")) {
-            throw new Error("fields 不能包含空字符串或无效值");
-        }
-
-        // 统计包含字段和排除字段
-        const includeFields = fields.filter((f) => !f.startsWith("!"));
-        const excludeFields = fields.filter((f) => f.startsWith("!"));
-
-        // 情况2：全部是包含字段
-        if (includeFields.length > 0 && excludeFields.length === 0) {
-            return { type: "include", fields: includeFields };
-        }
+    constructor(options: { redis: RedisCacheLike; sql?: any | null; dialect?: DbDialect }) {
+        this.redis = options.redis;
+        this.sql = options.sql || null;
+        this.isTransaction = !!options.sql;
 
-        // 情况3：全部是排除字段
-        if (excludeFields.length > 0 && includeFields.length === 0) {
-            // 去掉感叹号前缀
-            const cleanExcludeFields = excludeFields.map((f) => f.substring(1));
-            return { type: "exclude", fields: cleanExcludeFields };
-        }
+        // 默认使用 MySQL 方言（当前 core 的表结构/语法也主要基于 MySQL）
+        this.dialect = options.dialect ? options.dialect : new MySqlDialect();
+    }
 
-        // 混用情况：报错
-        throw new Error('fields 不能同时包含普通字段和排除字段（! 开头）。只能使用以下3种方式之一：\n1. 空数组 [] 或不传（查询所有）\n2. 全部指定字段 ["id", "name"]\n3. 全部排除字段 ["!password", "!token"]');
+    private createSqlBuilder(): SqlBuilder {
+        return new SqlBuilder({ quoteIdent: this.dialect.quoteIdent.bind(this.dialect) });
     }
 
     /**
@@ -90,226 +63,68 @@ export class DbHelper {
     private async getTableColumns(table: string): Promise<string[]> {
         // 1. 先查 Redis 缓存
         const cacheKey = CacheKeys.tableColumns(table);
-        const columns = await this.befly.redis.getObject<string[]>(cacheKey);
+        const columns = await this.redis.getObject<string[]>(cacheKey);
 
         if (columns && columns.length > 0) {
             return columns;
         }
 
         // 2. 缓存未命中，查询数据库
-        const sql = `SHOW COLUMNS FROM \`${table}\``;
-        const result = await this.executeWithConn(sql);
+        const query = this.dialect.getTableColumnsQuery(table);
+        const result = await this.executeWithConn(query.sql, query.params);
 
         if (!result || result.length === 0) {
             throw new Error(`表 ${table} 不存在或没有字段`);
         }
 
-        const columnNames = result.map((row: any) => row.Field) as string[];
+        const columnNames = this.dialect.getTableColumnsFromResult(result);
 
         // 3. 写入 Redis 缓存
-        await this.befly.redis.setObject(cacheKey, columnNames, TABLE_COLUMNS_CACHE_TTL_SECONDS);
-
-        return columnNames;
-    }
-
-    /**
-     * 字段数组转下划线格式（私有方法）
-     * 支持排除字段语法
-     */
-    private async fieldsToSnake(table: string, fields: string[]): Promise<string[]> {
-        if (!fields || !Array.isArray(fields)) return ["*"];
-
-        // 验证并分类字段
-        const { type, fields: classifiedFields } = this.validateAndClassifyFields(fields);
-
-        // 情况1：查询所有字段
-        if (type === "all") {
-            return ["*"];
-        }
-
-        // 情况2：指定包含字段
-        if (type === "include") {
-            return classifiedFields.map((field) => {
-                // 保留函数和特殊字段
-                if (field.includes("(") || field.includes(" ")) {
-                    return field;
-                }
-                return snakeCase(field);
-            });
-        }
-
-        // 情况3：排除字段
-        if (type === "exclude") {
-            // 获取表的所有字段
-            const allColumns = await this.getTableColumns(table);
-
-            // 转换排除字段为下划线格式
-            const excludeSnakeFields = classifiedFields.map((f) => snakeCase(f));
-
-            // 过滤掉排除字段
-            const resultFields = allColumns.filter((col) => !excludeSnakeFields.includes(col));
-
-            if (resultFields.length === 0) {
-                throw new Error(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(", ")}`);
-            }
-
-            return resultFields;
-        }
-
-        return ["*"];
-    }
-
-    /**
-     * orderBy 数组转下划线格式（私有方法）
-     */
-    private orderByToSnake(orderBy: string[]): string[] {
-        if (!orderBy || !Array.isArray(orderBy)) return orderBy;
-        return orderBy.map((item) => {
-            if (typeof item !== "string" || !item.includes("#")) return item;
-            const [field, direction] = item.split("#");
-            return `${snakeCase(field.trim())}#${direction.trim()}`;
-        });
-    }
-
-    /**
-     * 处理表名（转下划线格式）
-     * 'userProfile' -> 'user_profile'
-     */
-    private processTableName(table: string): string {
-        return snakeCase(table.trim());
-    }
-
-    /**
-     * 处理联查字段（支持表名.字段名格式）
-     * 'user.userId' -> 'user.user_id'
-     * 'username' -> 'user_name'
-     */
-    private processJoinField(field: string): string {
-        // 跳过函数、星号、已处理的字段
-        if (field.includes("(") || field === "*" || field.startsWith("`")) {
-            return field;
-        }
-
-        // 处理别名 AS
-        if (field.toUpperCase().includes(" AS ")) {
-            const [fieldPart, aliasPart] = field.split(/\s+AS\s+/i);
-            return `${this.processJoinField(fieldPart.trim())} AS ${aliasPart.trim()}`;
+        const cacheRes = await this.redis.setObject(cacheKey, columnNames, TABLE_COLUMNS_CACHE_TTL_SECONDS);
+        if (cacheRes === null) {
+            Logger.warn({ table: table, cacheKey: cacheKey }, "表字段缓存写入 Redis 失败");
         }
 
-        // 处理表名.字段名
-        if (field.includes(".")) {
-            const [tableName, fieldName] = field.split(".");
-            return `${snakeCase(tableName)}.${snakeCase(fieldName)}`;
-        }
-
-        // 普通字段
-        return snakeCase(field);
-    }
-
-    /**
-     * 处理联查的 where 条件键名
-     * 'user.userId': 1 -> 'user.user_id': 1
-     * 'user.status$in': [...] -> 'user.status$in': [...]
-     */
-    private processJoinWhereKey(key: string): string {
-        // 保留逻辑操作符
-        if (key === "$or" || key === "$and") {
-            return key;
-        }
-
-        // 处理带操作符的字段名（如 user.userId$gt）
-        if (key.includes("$")) {
-            const lastDollarIndex = key.lastIndexOf("$");
-            const fieldPart = key.substring(0, lastDollarIndex);
-            const operator = key.substring(lastDollarIndex);
-
-            if (fieldPart.includes(".")) {
-                const [tableName, fieldName] = fieldPart.split(".");
-                return `${snakeCase(tableName)}.${snakeCase(fieldName)}${operator}`;
-            }
-            return `${snakeCase(fieldPart)}${operator}`;
-        }
-
-        // 处理表名.字段名
-        if (key.includes(".")) {
-            const [tableName, fieldName] = key.split(".");
-            return `${snakeCase(tableName)}.${snakeCase(fieldName)}`;
-        }
-
-        // 普通字段
-        return snakeCase(key);
-    }
-
-    /**
-     * 递归处理联查的 where 条件
-     */
-    private processJoinWhere(where: any): any {
-        if (!where || typeof where !== "object") return where;
-
-        if (Array.isArray(where)) {
-            return where.map((item) => this.processJoinWhere(item));
-        }
-
-        const result: any = {};
-        for (const [key, value] of Object.entries(where)) {
-            const newKey = this.processJoinWhereKey(key);
-
-            if (key === "$or" || key === "$and") {
-                result[newKey] = (value as any[]).map((item) => this.processJoinWhere(item));
-            } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-                result[newKey] = this.processJoinWhere(value);
-            } else {
-                result[newKey] = value;
-            }
-        }
-        return result;
-    }
-
-    /**
-     * 处理联查的 orderBy
-     * 'o.createdAt#DESC' -> 'o.created_at#DESC'
-     */
-    private processJoinOrderBy(orderBy: string[]): string[] {
-        if (!orderBy || !Array.isArray(orderBy)) return orderBy;
-        return orderBy.map((item) => {
-            if (typeof item !== "string" || !item.includes("#")) return item;
-            const [field, direction] = item.split("#");
-            return `${this.processJoinField(field.trim())}#${direction.trim()}`;
-        });
+        return columnNames;
     }
 
     /**
      * 统一的查询参数预处理方法
      */
     private async prepareQueryOptions(options: QueryOptions) {
-        const cleanWhere = this.cleanFields(options.where || {});
+        const cleanWhere = fieldClear(options.where || {}, { excludeValues: [null, undefined] });
         const hasJoins = options.joins && options.joins.length > 0;
 
         // 联查时使用特殊处理逻辑
         if (hasJoins) {
             // 联查时字段直接处理（支持表名.字段名格式）
-            const processedFields = (options.fields || []).map((f) => this.processJoinField(f));
+            const processedFields = (options.fields || []).map((f) => DbUtils.processJoinField(f));
+
+            const normalizedTableRef = DbUtils.normalizeTableRef(options.table);
+            const mainQualifier = DbUtils.getJoinMainQualifier(options.table);
 
             return {
-                table: this.processTableName(options.table),
+                table: normalizedTableRef,
+                tableQualifier: mainQualifier,
                 fields: processedFields.length > 0 ? processedFields : ["*"],
-                where: this.processJoinWhere(cleanWhere),
+                where: DbUtils.processJoinWhere(cleanWhere),
                 joins: options.joins,
-                orderBy: this.processJoinOrderBy(options.orderBy || []),
+                orderBy: DbUtils.processJoinOrderBy(options.orderBy || []),
                 page: options.page || 1,
                 limit: options.limit || 10
             };
         }
 
         // 单表查询使用原有逻辑
-        const processedFields = await this.fieldsToSnake(snakeCase(options.table), options.fields || []);
+        const processedFields = await DbUtils.fieldsToSnake(snakeCase(options.table), options.fields || [], this.getTableColumns.bind(this));
 
         return {
             table: snakeCase(options.table),
+            tableQualifier: snakeCase(options.table),
             fields: processedFields,
-            where: this.whereKeysToSnake(cleanWhere),
+            where: DbUtils.whereKeysToSnake(cleanWhere),
             joins: undefined,
-            orderBy: this.orderByToSnake(options.orderBy || []),
+            orderBy: DbUtils.orderByToSnake(options.orderBy || []),
             page: options.page || 1,
             limit: options.limit || 10
         };
@@ -322,7 +137,7 @@ export class DbHelper {
         if (!joins || joins.length === 0) return;
 
         for (const join of joins) {
-            const processedTable = this.processTableName(join.table);
+            const processedTable = DbUtils.normalizeTableRef(join.table);
             const type = join.type || "left";
 
             switch (type) {
@@ -339,180 +154,6 @@ export class DbHelper {
             }
         }
     }
-
-    /**
-     * 添加默认的 state 过滤条件
-     * 默认查询 state > 0 的数据（排除已删除和特殊状态）
-     * @param where - where 条件
-     * @param table - 主表名（JOIN 查询时需要，用于添加表名前缀避免歧义）
-     * @param hasJoins - 是否有 JOIN 查询
-     */
-    private addDefaultStateFilter(where: WhereConditions = {}, table?: string, hasJoins: boolean = false): WhereConditions {
-        // 如果用户已经指定了 state 条件，优先使用用户的条件
-        const hasStateCondition = Object.keys(where).some((key) => key.startsWith("state") || key.includes(".state"));
-
-        if (hasStateCondition) {
-            return where;
-        }
-
-        // JOIN 查询时需要指定主表名前缀避免歧义
-        if (hasJoins && table) {
-            return {
-                ...where,
-                [`${table}.state$gt`]: 0
-            };
-        }
-
-        // 默认查询 state > 0 的数据
-        return {
-            ...where,
-            state$gt: 0
-        };
-    }
-
-    /**
-     * 清理数据或 where 条件（默认排除 null 和 undefined）
-     */
-    public cleanFields<T extends Record<string, any>>(data: T, excludeValues: any[] = [null, undefined], keepValues: Record<string, any> = {}): Partial<T> {
-        return fieldClear(data || ({} as T), { excludeValues, keepMap: keepValues });
-    }
-
-    /**
-     * 转换数据库 BIGINT 字段为数字类型（私有方法）
-     * 当 bigint: false 时，Bun SQL 会将大于 u32 的 BIGINT 返回为字符串，此方法将其转换为 number
-     *
-     * 转换规则：
-     * 1. 白名单中的字段会被转换
-     * 2. 所有以 'Id' 或 '_id' 结尾的字段会被自动转换
-     * 3. 所有以 'At' 或 '_at' 结尾的字段会被自动转换（时间戳字段）
-     * 4. 其他字段保持不变
-     */
-    private convertBigIntFields<T = any>(arr: Record<string, any>[], fields: string[] = ["id", "pid", "sort"]): T[] {
-        if (!arr || !Array.isArray(arr)) return arr as T[];
-
-        return arr.map((item) => {
-            const converted = { ...item };
-
-            // 遍历对象的所有字段
-            for (const [key, value] of Object.entries(converted)) {
-                // 跳过 undefined 和 null
-                if (value === undefined || value === null) {
-                    continue;
-                }
-
-                // 判断是否需要转换：
-                // 1. 在白名单中
-                // 2. 以 'Id' 结尾（如 userId, roleId, categoryId）
-                // 3. 以 '_id' 结尾（如 user_id, role_id）
-                // 4. 以 'At' 结尾（如 createdAt, updatedAt）
-                // 5. 以 '_at' 结尾（如 created_at, updated_at）
-                const shouldConvert = fields.includes(key) || key.endsWith("Id") || key.endsWith("_id") || key.endsWith("At") || key.endsWith("_at");
-
-                if (shouldConvert && typeof value === "string") {
-                    const num = Number(value);
-                    if (!isNaN(num)) {
-                        converted[key] = num;
-                    }
-                }
-                // number 类型保持不变（小于 u32 的值）
-            }
-
-            return converted as T;
-        }) as T[];
-    }
-
-    /**
-     * 序列化数组字段（写入数据库前）
-     * 将数组类型的字段转换为 JSON 字符串
-     */
-    private serializeArrayFields(data: Record<string, any>): Record<string, any> {
-        const serialized = { ...data };
-
-        for (const [key, value] of Object.entries(serialized)) {
-            // 跳过 null 和 undefined
-            if (value === null || value === undefined) continue;
-
-            // 数组类型序列化为 JSON 字符串
-            if (Array.isArray(value)) {
-                serialized[key] = JSON.stringify(value);
-            }
-        }
-
-        return serialized;
-    }
-
-    /**
-     * 反序列化数组字段（从数据库读取后）
-     * 将 JSON 字符串转换回数组
-     */
-    private deserializeArrayFields<T = any>(data: Record<string, any> | null): T | null {
-        if (!data) return null;
-
-        const deserialized = { ...data };
-
-        for (const [key, value] of Object.entries(deserialized)) {
-            // 跳过非字符串值
-            if (typeof value !== "string") continue;
-
-            // 尝试解析 JSON 数组字符串
-            // 只解析符合 JSON 数组格式的字符串（以 [ 开头，以 ] 结尾）
-            if (value.startsWith("[") && value.endsWith("]")) {
-                try {
-                    const parsed = JSON.parse(value);
-                    if (Array.isArray(parsed)) {
-                        deserialized[key] = parsed;
-                    }
-                } catch {
-                    // 解析失败则保持原值
-                }
-            }
-        }
-
-        return deserialized as T;
-    }
-
-    /**
-     * Where 条件键名转下划线格式（递归处理嵌套）（私有方法）
-     * 支持操作符字段（如 userId$gt）和逻辑操作符（$or, $and）
-     */
-    private whereKeysToSnake(where: any): any {
-        if (!where || typeof where !== "object") return where;
-
-        // 处理数组（$or, $and 等）
-        if (Array.isArray(where)) {
-            return where.map((item) => this.whereKeysToSnake(item));
-        }
-
-        const result: any = {};
-        for (const [key, value] of Object.entries(where)) {
-            // 保留 $or, $and 等逻辑操作符
-            if (key === "$or" || key === "$and") {
-                result[key] = (value as any[]).map((item) => this.whereKeysToSnake(item));
-                continue;
-            }
-
-            // 处理带操作符的字段名（如 userId$gt）
-            if (key.includes("$")) {
-                const lastDollarIndex = key.lastIndexOf("$");
-                const fieldName = key.substring(0, lastDollarIndex);
-                const operator = key.substring(lastDollarIndex);
-                const snakeKey = snakeCase(fieldName) + operator;
-                result[snakeKey] = value;
-                continue;
-            }
-
-            // 普通字段：转换键名，递归处理值（支持嵌套对象）
-            const snakeKey = snakeCase(key);
-            if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-                result[snakeKey] = this.whereKeysToSnake(value);
-            } else {
-                result[snakeKey] = value;
-            }
-        }
-
-        return result;
-    }
-
     /**
      * 执行 SQL（使用 sql.unsafe，带慢查询日志和错误处理）
      */
@@ -580,6 +221,16 @@ export class DbHelper {
         }
     }
 
+    /**
+     * 执行原生 SQL（内部工具/同步脚本专用）
+     *
+     * - 复用当前 DbHelper 持有的连接/事务
+     * - 统一走 executeWithConn，保持参数校验与错误行为一致
+     */
+    public async unsafe(sqlStr: string, params?: any[]): Promise<any> {
+        return await this.executeWithConn(sqlStr, params);
+    }
+
     /**
      * 检查表是否存在
      * @param tableName - 表名（支持小驼峰，会自动转换为下划线）
@@ -589,7 +240,8 @@ export class DbHelper {
         // 将表名转换为下划线格式
         const snakeTableName = snakeCase(tableName);
 
-        const result = await this.executeWithConn("SELECT COUNT(*) as count FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?", [snakeTableName]);
+        const query = this.dialect.tableExistsQuery(snakeTableName);
+        const result = await this.executeWithConn(query.sql, query.params);
 
         return result?.[0]?.count > 0;
     }
@@ -612,12 +264,12 @@ export class DbHelper {
      * });
      */
     async getCount(options: Omit<QueryOptions, "fields" | "page" | "limit" | "orderBy">): Promise<number> {
-        const { table, where, joins } = await this.prepareQueryOptions(options as QueryOptions);
+        const { table, where, joins, tableQualifier } = await this.prepareQueryOptions(options as QueryOptions);
 
-        const builder = new SqlBuilder()
-            .select(["COUNT(*) as count"])
+        const builder = this.createSqlBuilder()
+            .selectRaw("COUNT(*) as count")
             .from(table)
-            .where(this.addDefaultStateFilter(where, table, !!joins));
+            .where(DbUtils.addDefaultStateFilter(where, tableQualifier, !!joins));
 
         // 添加 JOIN
         this.applyJoins(builder, joins);
@@ -645,12 +297,12 @@ export class DbHelper {
      * })
      */
     async getOne<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<T | null> {
-        const { table, fields, where, joins } = await this.prepareQueryOptions(options);
+        const { table, fields, where, joins, tableQualifier } = await this.prepareQueryOptions(options);
 
-        const builder = new SqlBuilder()
+        const builder = this.createSqlBuilder()
             .select(fields)
             .from(table)
-            .where(this.addDefaultStateFilter(where, table, !!joins));
+            .where(DbUtils.addDefaultStateFilter(where, tableQualifier, !!joins));
 
         // 添加 JOIN
         this.applyJoins(builder, joins);
@@ -665,11 +317,11 @@ export class DbHelper {
         const camelRow = keysToCamel<T>(row);
 
         // 反序列化数组字段（JSON 字符串 → 数组）
-        const deserialized = this.deserializeArrayFields<T>(camelRow);
+        const deserialized = DbUtils.deserializeArrayFields<T>(camelRow);
         if (!deserialized) return null;
 
         // 转换 BIGINT 字段（id, pid 等）为数字类型
-        return this.convertBigIntFields<T>([deserialized])[0];
+        return convertBigIntFields<T>([deserialized])[0];
     }
 
     /**
@@ -706,10 +358,10 @@ export class DbHelper {
         }
 
         // 构建查询
-        const whereFiltered = this.addDefaultStateFilter(prepared.where, prepared.table, !!prepared.joins);
+        const whereFiltered = DbUtils.addDefaultStateFilter(prepared.where, prepared.tableQualifier, !!prepared.joins);
 
         // 查询总数
-        const countBuilder = new SqlBuilder().select(["COUNT(*) as total"]).from(prepared.table).where(whereFiltered);
+        const countBuilder = this.createSqlBuilder().selectRaw("COUNT(*) as total").from(prepared.table).where(whereFiltered);
 
         // 添加 JOIN（计数也需要）
         this.applyJoins(countBuilder, prepared.joins);
@@ -731,7 +383,7 @@ export class DbHelper {
 
         // 查询数据
         const offset = (prepared.page - 1) * prepared.limit;
-        const dataBuilder = new SqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered).limit(prepared.limit).offset(offset);
+        const dataBuilder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered).limit(prepared.limit).offset(offset);
 
         // 添加 JOIN
         this.applyJoins(dataBuilder, prepared.joins);
@@ -748,11 +400,11 @@ export class DbHelper {
         const camelList = arrayKeysToCamel<T>(list);
 
         // 反序列化数组字段
-        const deserializedList = camelList.map((item) => this.deserializeArrayFields<T>(item)).filter((item): item is T => item !== null);
+        const deserializedList = camelList.map((item) => DbUtils.deserializeArrayFields<T>(item)).filter((item): item is T => item !== null);
 
         // 转换 BIGINT 字段（id, pid 等）为数字类型
         return {
-            lists: this.convertBigIntFields<T>(deserializedList),
+            lists: convertBigIntFields<T>(deserializedList),
             total: total,
             page: prepared.page,
             limit: prepared.limit,
@@ -784,10 +436,10 @@ export class DbHelper {
 
         const prepared = await this.prepareQueryOptions({ ...options, page: 1, limit: 10 });
 
-        const whereFiltered = this.addDefaultStateFilter(prepared.where, prepared.table, !!prepared.joins);
+        const whereFiltered = DbUtils.addDefaultStateFilter(prepared.where, prepared.tableQualifier, !!prepared.joins);
 
         // 查询真实总数
-        const countBuilder = new SqlBuilder().select(["COUNT(*) as total"]).from(prepared.table).where(whereFiltered);
+        const countBuilder = this.createSqlBuilder().selectRaw("COUNT(*) as total").from(prepared.table).where(whereFiltered);
 
         // 添加 JOIN（计数也需要）
         this.applyJoins(countBuilder, prepared.joins);
@@ -805,7 +457,7 @@ export class DbHelper {
         }
 
         // 查询数据（受上限保护）
-        const dataBuilder = new SqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered).limit(MAX_LIMIT);
+        const dataBuilder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered).limit(MAX_LIMIT);
 
         // 添加 JOIN
         this.applyJoins(dataBuilder, prepared.joins);
@@ -831,10 +483,10 @@ export class DbHelper {
         const camelResult = arrayKeysToCamel<T>(result);
 
         // 反序列化数组字段
-        const deserializedList = camelResult.map((item) => this.deserializeArrayFields<T>(item)).filter((item): item is T => item !== null);
+        const deserializedList = camelResult.map((item) => DbUtils.deserializeArrayFields<T>(item)).filter((item): item is T => item !== null);
 
         // 转换 BIGINT 字段（id, pid 等）为数字类型
-        const lists = this.convertBigIntFields<T>(deserializedList);
+        const lists = convertBigIntFields<T>(deserializedList);
 
         return {
             lists: lists,
@@ -849,43 +501,24 @@ export class DbHelper {
     async insData(options: InsertOptions): Promise<number> {
         const { table, data } = options;
 
-        // 清理数据（排除 null 和 undefined）
-        const cleanData = this.cleanFields(data);
-
-        // 转换表名：小驼峰 → 下划线
         const snakeTable = snakeCase(table);
 
-        // 处理数据（自动添加必要字段）
-        // 字段名转换：小驼峰 → 下划线
-        const snakeData = keysToSnake(cleanData);
-
-        // 序列化数组字段（数组 → JSON 字符串）
-        const serializedData = this.serializeArrayFields(snakeData);
-
-        // 复制用户数据，但移除系统字段（防止用户尝试覆盖）
-        const { id: _id, created_at: _created_at, updated_at: _updated_at, deleted_at: _deleted_at, state: _state, ...userData } = serializedData;
-
-        const processed: Record<string, any> = { ...userData };
+        const now = Date.now();
 
-        // 强制生成 ID（不可被用户覆盖）
+        let id: number;
         try {
-            processed.id = await this.befly.redis.genTimeID();
+            id = await this.redis.genTimeID();
         } catch (error: any) {
-            throw new Error(`生成 ID 失败，Redis 可能不可用 (table: ${table})`, error);
+            throw new Error(`生成 ID 失败，Redis 可能不可用 (table: ${table})`, { cause: error });
         }
 
-        // 强制生成时间戳（不可被用户覆盖）
-        const now = Date.now();
-        processed.created_at = now;
-        processed.updated_at = now;
-
-        // 强制设置 state 为 1（激活状态，不可被用户覆盖）
-        processed.state = 1;
+        const processed = DbUtils.buildInsertRow({ data: data, id: id, now: now });
 
-        // 注意：deleted_at 字段不在插入时生成，只在软删除时设置
+        // 入口校验：保证进入 SqlBuilder 的数据无 undefined
+        SqlCheck.assertNoUndefinedInRecord(processed as any, `insData 插入数据 (table: ${snakeTable})`);
 
         // 构建 SQL
-        const builder = new SqlBuilder();
+        const builder = this.createSqlBuilder();
         const { sql, params } = builder.toInsertSql(snakeTable, processed);
 
         // 执行
@@ -917,36 +550,20 @@ export class DbHelper {
         // 批量生成 ID（逐个获取）
         const ids: number[] = [];
         for (let i = 0; i < dataList.length; i++) {
-            ids.push(await this.befly.redis.genTimeID());
+            ids.push(await this.redis.genTimeID());
         }
         const now = Date.now();
 
         // 处理所有数据（自动添加系统字段）
         const processedList = dataList.map((data, index) => {
-            // 清理数据（排除 null 和 undefined）
-            const cleanData = this.cleanFields(data);
-
-            // 字段名转换：小驼峰 → 下划线
-            const snakeData = keysToSnake(cleanData);
-
-            // 序列化数组字段（数组 → JSON 字符串）
-            const serializedData = this.serializeArrayFields(snakeData);
-
-            // 移除系统字段（防止用户尝试覆盖）
-            const { id: _id, created_at: _created_at, updated_at: _updated_at, deleted_at: _deleted_at, state: _state, ...userData } = serializedData;
-
-            // 强制生成系统字段（不可被用户覆盖）
-            return {
-                ...userData,
-                id: ids[index],
-                created_at: now,
-                updated_at: now,
-                state: 1
-            };
+            return DbUtils.buildInsertRow({ data: data, id: ids[index], now: now });
         });
 
+        // 入口校验：保证进入 SqlBuilder 的批量数据结构一致且无 undefined
+        const insertFields = SqlCheck.assertBatchInsertRowsConsistent(processedList as any, { table: snakeTable });
+
         // 构建批量插入 SQL
-        const builder = new SqlBuilder();
+        const builder = this.createSqlBuilder();
         const { sql, params } = builder.toInsertSql(snakeTable, processedList);
 
         // 在事务中执行批量插入
@@ -954,11 +571,79 @@ export class DbHelper {
             await this.executeWithConn(sql, params);
             return ids;
         } catch (error: any) {
-            Logger.error({ err: error, table: table }, "批量插入失败");
+            Logger.error(
+                {
+                    err: error,
+                    table: table,
+                    snakeTable: snakeTable,
+                    count: dataList.length,
+                    fields: insertFields
+                },
+                "批量插入失败"
+            );
             throw error;
         }
     }
 
+    async delForceBatch(table: string, ids: number[]): Promise<number> {
+        if (ids.length === 0) {
+            return 0;
+        }
+
+        const snakeTable = snakeCase(table);
+
+        const query = SqlBuilder.toDeleteInSql({
+            table: snakeTable,
+            idField: "id",
+            ids: ids,
+            quoteIdent: this.dialect.quoteIdent.bind(this.dialect)
+        });
+        const result: any = await this.executeWithConn(query.sql, query.params);
+        return result?.changes || 0;
+    }
+
+    async updBatch(table: string, dataList: Array<{ id: number; data: Record<string, any> }>): Promise<number> {
+        if (dataList.length === 0) {
+            return 0;
+        }
+
+        const snakeTable = snakeCase(table);
+        const now = Date.now();
+
+        const processedList: Array<{ id: number; data: Record<string, any> }> = [];
+        const fieldSet = new Set<string>();
+
+        for (const item of dataList) {
+            const userData = DbUtils.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 0;
+        }
+
+        const query = SqlBuilder.toUpdateCaseByIdSql({
+            table: snakeTable,
+            idField: "id",
+            rows: processedList,
+            fields: fields,
+            quoteIdent: this.dialect.quoteIdent.bind(this.dialect),
+            updatedAtField: "updated_at",
+            updatedAtValue: now,
+            stateField: "state",
+            stateGtZero: true
+        });
+
+        const result: any = await this.executeWithConn(query.sql, query.params);
+        return result?.changes || 0;
+    }
+
     /**
      * 更新数据（强制更新时间戳，系统字段不可修改）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
@@ -966,33 +651,18 @@ export class DbHelper {
     async updData(options: UpdateOptions): Promise<number> {
         const { table, data, where } = options;
 
-        // 清理数据和条件（排除 null 和 undefined）
-        const cleanData = this.cleanFields(data);
-        const cleanWhere = this.cleanFields(where);
+        // 清理条件（排除 null 和 undefined）
+        const cleanWhere = fieldClear(where, { excludeValues: [null, undefined] });
 
         // 转换表名：小驼峰 → 下划线
         const snakeTable = snakeCase(table);
+        const snakeWhere = DbUtils.whereKeysToSnake(cleanWhere);
 
-        // 字段名转换：小驼峰 → 下划线
-        const snakeData = keysToSnake(cleanData);
-        const snakeWhere = this.whereKeysToSnake(cleanWhere);
-
-        // 序列化数组字段（数组 → JSON 字符串）
-        const serializedData = this.serializeArrayFields(snakeData);
-
-        // 移除系统字段（防止用户尝试修改）
-        // 注意：state 允许用户修改（用于设置禁用状态 state=2）
-        const { id: _id, created_at: _created_at, updated_at: _updated_at, deleted_at: _deleted_at, ...userData } = serializedData;
-
-        // 强制更新时间戳（不可被用户覆盖）
-        const processed: Record<string, any> = {
-            ...userData,
-            updated_at: Date.now()
-        };
+        const processed = DbUtils.buildUpdateRow({ data: data, now: Date.now(), allowState: true });
 
         // 构建 SQL
-        const whereFiltered = this.addDefaultStateFilter(snakeWhere, snakeTable, false);
-        const builder = new SqlBuilder().where(whereFiltered);
+        const whereFiltered = DbUtils.addDefaultStateFilter(snakeWhere, snakeTable, false);
+        const builder = this.createSqlBuilder().where(whereFiltered);
         const { sql, params } = builder.toUpdateSql(snakeTable, processed);
 
         // 执行
@@ -1025,11 +695,11 @@ export class DbHelper {
         const snakeTable = snakeCase(table);
 
         // 清理条件字段
-        const cleanWhere = this.cleanFields(where);
-        const snakeWhere = this.whereKeysToSnake(cleanWhere);
+        const cleanWhere = fieldClear(where, { excludeValues: [null, undefined] });
+        const snakeWhere = DbUtils.whereKeysToSnake(cleanWhere);
 
         // 物理删除
-        const builder = new SqlBuilder().where(snakeWhere);
+        const builder = this.createSqlBuilder().where(snakeWhere);
         const { sql, params } = builder.toDeleteSql(snakeTable);
 
         const result = await this.executeWithConn(sql, params);
@@ -1081,7 +751,7 @@ export class DbHelper {
         // 使用 Bun SQL 的 begin 方法开启事务
         // begin 方法会自动处理 commit/rollback
         return await this.sql.begin(async (tx: any) => {
-            const trans = new DbHelper(this.befly, tx);
+            const trans = new DbHelper({ redis: this.redis, sql: tx, dialect: this.dialect });
             return await callback(trans);
         });
     }
@@ -1098,13 +768,13 @@ export class DbHelper {
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
      */
     async exists(options: Omit<QueryOptions, "fields" | "orderBy" | "page" | "limit">): Promise<boolean> {
-        const { table, where } = await this.prepareQueryOptions({ ...options, page: 1, limit: 1 });
+        const { table, where, tableQualifier } = await this.prepareQueryOptions({ ...options, page: 1, limit: 1 } as any);
 
         // 使用 COUNT(1) 性能更好
-        const builder = new SqlBuilder()
+        const builder = this.createSqlBuilder()
             .select(["COUNT(1) as cnt"])
             .from(table)
-            .where(this.addDefaultStateFilter(where, table, false))
+            .where(DbUtils.addDefaultStateFilter(where, tableQualifier, false))
             .limit(1);
 
         const { sql, params } = builder.toSelectSql();
@@ -1180,18 +850,20 @@ export class DbHelper {
         }
 
         // 清理 where 条件（排除 null 和 undefined）
-        const cleanWhere = this.cleanFields(where);
+        const cleanWhere = fieldClear(where, { excludeValues: [null, undefined] });
 
         // 转换 where 条件字段名：小驼峰 → 下划线
-        const snakeWhere = this.whereKeysToSnake(cleanWhere);
+        const snakeWhere = DbUtils.whereKeysToSnake(cleanWhere);
 
         // 使用 SqlBuilder 构建安全的 WHERE 条件
-        const whereFiltered = this.addDefaultStateFilter(snakeWhere, snakeTable, false);
-        const builder = new SqlBuilder().where(whereFiltered);
+        const whereFiltered = DbUtils.addDefaultStateFilter(snakeWhere, snakeTable, false);
+        const builder = this.createSqlBuilder().where(whereFiltered);
         const { sql: whereClause, params: whereParams } = builder.getWhereConditions();
 
         // 构建安全的 UPDATE SQL（表名和字段名使用反引号转义，已经是下划线格式）
-        const sql = whereClause ? `UPDATE \`${snakeTable}\` SET \`${snakeField}\` = \`${snakeField}\` + ? WHERE ${whereClause}` : `UPDATE \`${snakeTable}\` SET \`${snakeField}\` = \`${snakeField}\` + ?`;
+        const quotedTable = this.dialect.quoteIdent(snakeTable);
+        const quotedField = this.dialect.quoteIdent(snakeField);
+        const sql = whereClause ? `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ? WHERE ${whereClause}` : `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ?`;
 
         const result = await this.executeWithConn(sql, [value, ...whereParams]);
         return result?.changes || 0;