befly 3.9.38 → 3.9.40

package/lib/dbHelper.ts

@@ -1,19 +1,23 @@
-/**
+/**
  * 数据库助手 - TypeScript 版本
  * 提供数据库 CRUD 操作的封装
  */
 
-import { snakeCase } from 'es-toolkit/string';
-import { SqlBuilder } from './sqlBuilder.js';
-import { keysToCamel } from 'befly-shared/keysToCamel';
-import { arrayKeysToCamel } from 'befly-shared/arrayKeysToCamel';
-import { keysToSnake } from 'befly-shared/keysToSnake';
-import { fieldClear } from 'befly-shared/fieldClear';
-import { RedisTTL, RedisKeys } from 'befly-shared/redisKeys';
-import { Logger } from './logger.js';
-import type { WhereConditions, JoinOption } from '../types/common.js';
-import type { BeflyContext } from '../types/befly.js';
-import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, ListResult, AllResult, TransactionCallback } from '../types/database.js';
+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 { snakeCase } from "es-toolkit/string";
+
+import { arrayKeysToCamel } from "../utils/arrayKeysToCamel.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 { Logger } from "./logger.js";
+import { SqlBuilder } from "./sqlBuilder.js";
+
+const TABLE_COLUMNS_CACHE_TTL_SECONDS = 3600;
 
 /**
  * 数据库助手类
@@ -40,38 +44,38 @@ export class DbHelper {
      * @throws 如果 fields 格式非法
      */
     private validateAndClassifyFields(fields?: string[]): {
-        type: 'all' | 'include' | 'exclude';
+        type: "all" | "include" | "exclude";
         fields: string[];
     } {
         // 情况1：空数组或 undefined，表示查询所有
         if (!fields || fields.length === 0) {
-            return { type: 'all', fields: [] };
+            return { type: "all", fields: [] };
         }
 
         // 检测是否有星号（禁止）
-        if (fields.some((f) => f === '*')) {
-            throw new Error('fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段');
+        if (fields.some((f) => f === "*")) {
+            throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段");
         }
 
         // 检测是否有空字符串或无效值
-        if (fields.some((f) => !f || typeof f !== 'string' || f.trim() === '')) {
-            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('!'));
+        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 };
+            return { type: "include", fields: includeFields };
         }
 
         // 情况3：全部是排除字段
         if (excludeFields.length > 0 && includeFields.length === 0) {
             // 去掉感叹号前缀
             const cleanExcludeFields = excludeFields.map((f) => f.substring(1));
-            return { type: 'exclude', fields: cleanExcludeFields };
+            return { type: "exclude", fields: cleanExcludeFields };
         }
 
         // 混用情况：报错
@@ -85,7 +89,7 @@ export class DbHelper {
      */
     private async getTableColumns(table: string): Promise<string[]> {
         // 1. 先查 Redis 缓存
-        const cacheKey = RedisKeys.tableColumns(table);
+        const cacheKey = CacheKeys.tableColumns(table);
         const columns = await this.befly.redis.getObject<string[]>(cacheKey);
 
         if (columns && columns.length > 0) {
@@ -103,7 +107,7 @@ export class DbHelper {
         const columnNames = result.map((row: any) => row.Field) as string[];
 
         // 3. 写入 Redis 缓存
-        await this.befly.redis.setObject(cacheKey, columnNames, RedisTTL.tableColumns);
+        await this.befly.redis.setObject(cacheKey, columnNames, TABLE_COLUMNS_CACHE_TTL_SECONDS);
 
         return columnNames;
     }
@@ -113,21 +117,21 @@ export class DbHelper {
      * 支持排除字段语法
      */
     private async fieldsToSnake(table: string, fields: string[]): Promise<string[]> {
-        if (!fields || !Array.isArray(fields)) return ['*'];
+        if (!fields || !Array.isArray(fields)) return ["*"];
 
         // 验证并分类字段
         const { type, fields: classifiedFields } = this.validateAndClassifyFields(fields);
 
         // 情况1：查询所有字段
-        if (type === 'all') {
-            return ['*'];
+        if (type === "all") {
+            return ["*"];
         }
 
         // 情况2：指定包含字段
-        if (type === 'include') {
+        if (type === "include") {
             return classifiedFields.map((field) => {
                 // 保留函数和特殊字段
-                if (field.includes('(') || field.includes(' ')) {
+                if (field.includes("(") || field.includes(" ")) {
                     return field;
                 }
                 return snakeCase(field);
@@ -135,7 +139,7 @@ export class DbHelper {
         }
 
         // 情况3：排除字段
-        if (type === 'exclude') {
+        if (type === "exclude") {
             // 获取表的所有字段
             const allColumns = await this.getTableColumns(table);
 
@@ -146,13 +150,13 @@ export class DbHelper {
             const resultFields = allColumns.filter((col) => !excludeSnakeFields.includes(col));
 
             if (resultFields.length === 0) {
-                throw new Error(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(', ')}`);
+                throw new Error(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(", ")}`);
             }
 
             return resultFields;
         }
 
-        return ['*'];
+        return ["*"];
     }
 
     /**
@@ -161,8 +165,8 @@ export class DbHelper {
     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('#');
+            if (typeof item !== "string" || !item.includes("#")) return item;
+            const [field, direction] = item.split("#");
             return `${snakeCase(field.trim())}#${direction.trim()}`;
         });
     }
@@ -182,19 +186,19 @@ export class DbHelper {
      */
     private processJoinField(field: string): string {
         // 跳过函数、星号、已处理的字段
-        if (field.includes('(') || field === '*' || field.startsWith('`')) {
+        if (field.includes("(") || field === "*" || field.startsWith("`")) {
             return field;
         }
 
         // 处理别名 AS
-        if (field.toUpperCase().includes(' AS ')) {
+        if (field.toUpperCase().includes(" AS ")) {
             const [fieldPart, aliasPart] = field.split(/\s+AS\s+/i);
             return `${this.processJoinField(fieldPart.trim())} AS ${aliasPart.trim()}`;
         }
 
         // 处理表名.字段名
-        if (field.includes('.')) {
-            const [tableName, fieldName] = field.split('.');
+        if (field.includes(".")) {
+            const [tableName, fieldName] = field.split(".");
             return `${snakeCase(tableName)}.${snakeCase(fieldName)}`;
         }
 
@@ -209,26 +213,26 @@ export class DbHelper {
      */
     private processJoinWhereKey(key: string): string {
         // 保留逻辑操作符
-        if (key === '$or' || key === '$and') {
+        if (key === "$or" || key === "$and") {
             return key;
         }
 
         // 处理带操作符的字段名（如 user.userId$gt）
-        if (key.includes('$')) {
-            const lastDollarIndex = key.lastIndexOf('$');
+        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('.');
+            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('.');
+        if (key.includes(".")) {
+            const [tableName, fieldName] = key.split(".");
             return `${snakeCase(tableName)}.${snakeCase(fieldName)}`;
         }
 
@@ -240,7 +244,7 @@ export class DbHelper {
      * 递归处理联查的 where 条件
      */
     private processJoinWhere(where: any): any {
-        if (!where || typeof where !== 'object') return where;
+        if (!where || typeof where !== "object") return where;
 
         if (Array.isArray(where)) {
             return where.map((item) => this.processJoinWhere(item));
@@ -250,9 +254,9 @@ export class DbHelper {
         for (const [key, value] of Object.entries(where)) {
             const newKey = this.processJoinWhereKey(key);
 
-            if (key === '$or' || key === '$and') {
+            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)) {
+            } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
                 result[newKey] = this.processJoinWhere(value);
             } else {
                 result[newKey] = value;
@@ -268,8 +272,8 @@ export class DbHelper {
     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('#');
+            if (typeof item !== "string" || !item.includes("#")) return item;
+            const [field, direction] = item.split("#");
             return `${this.processJoinField(field.trim())}#${direction.trim()}`;
         });
     }
@@ -288,7 +292,7 @@ export class DbHelper {
 
             return {
                 table: this.processTableName(options.table),
-                fields: processedFields.length > 0 ? processedFields : ['*'],
+                fields: processedFields.length > 0 ? processedFields : ["*"],
                 where: this.processJoinWhere(cleanWhere),
                 joins: options.joins,
                 orderBy: this.processJoinOrderBy(options.orderBy || []),
@@ -319,16 +323,16 @@ export class DbHelper {
 
         for (const join of joins) {
             const processedTable = this.processTableName(join.table);
-            const type = join.type || 'left';
+            const type = join.type || "left";
 
             switch (type) {
-                case 'inner':
+                case "inner":
                     builder.innerJoin(processedTable, join.on);
                     break;
-                case 'right':
+                case "right":
                     builder.rightJoin(processedTable, join.on);
                     break;
-                case 'left':
+                case "left":
                 default:
                     builder.leftJoin(processedTable, join.on);
                     break;
@@ -345,7 +349,7 @@ export class DbHelper {
      */
     private addDefaultStateFilter(where: WhereConditions = {}, table?: string, hasJoins: boolean = false): WhereConditions {
         // 如果用户已经指定了 state 条件，优先使用用户的条件
-        const hasStateCondition = Object.keys(where).some((key) => key.startsWith('state') || key.includes('.state'));
+        const hasStateCondition = Object.keys(where).some((key) => key.startsWith("state") || key.includes(".state"));
 
         if (hasStateCondition) {
             return where;
@@ -383,7 +387,7 @@ export class DbHelper {
      * 3. 所有以 'At' 或 '_at' 结尾的字段会被自动转换（时间戳字段）
      * 4. 其他字段保持不变
      */
-    private convertBigIntFields<T = any>(arr: Record<string, any>[], fields: string[] = ['id', 'pid', 'sort']): T[] {
+    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) => {
@@ -402,9 +406,9 @@ export class DbHelper {
                 // 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');
+                const shouldConvert = fields.includes(key) || key.endsWith("Id") || key.endsWith("_id") || key.endsWith("At") || key.endsWith("_at");
 
-                if (shouldConvert && typeof value === 'string') {
+                if (shouldConvert && typeof value === "string") {
                     const num = Number(value);
                     if (!isNaN(num)) {
                         converted[key] = num;
@@ -417,12 +421,62 @@ export class DbHelper {
         }) 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;
+        if (!where || typeof where !== "object") return where;
 
         // 处理数组（$or, $and 等）
         if (Array.isArray(where)) {
@@ -432,14 +486,14 @@ export class DbHelper {
         const result: any = {};
         for (const [key, value] of Object.entries(where)) {
             // 保留 $or, $and 等逻辑操作符
-            if (key === '$or' || key === '$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('$');
+            if (key.includes("$")) {
+                const lastDollarIndex = key.lastIndexOf("$");
                 const fieldName = key.substring(0, lastDollarIndex);
                 const operator = key.substring(lastDollarIndex);
                 const snakeKey = snakeCase(fieldName) + operator;
@@ -449,7 +503,7 @@ export class DbHelper {
 
             // 普通字段：转换键名，递归处理值（支持嵌套对象）
             const snakeKey = snakeCase(key);
-            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            if (typeof value === "object" && value !== null && !Array.isArray(value)) {
                 result[snakeKey] = this.whereKeysToSnake(value);
             } else {
                 result[snakeKey] = value;
@@ -464,11 +518,11 @@ export class DbHelper {
      */
     private async executeWithConn(sqlStr: string, params?: any[]): Promise<any> {
         if (!this.sql) {
-            throw new Error('数据库连接未初始化');
+            throw new Error("数据库连接未初始化");
         }
 
         // 强制类型检查：只接受字符串类型的 SQL
-        if (typeof sqlStr !== 'string') {
+        if (typeof sqlStr !== "string") {
             throw new Error(`executeWithConn 只接受字符串类型的 SQL，收到类型: ${typeof sqlStr}，值: ${JSON.stringify(sqlStr)}`);
         }
 
@@ -487,27 +541,35 @@ export class DbHelper {
             // 计算执行时间
             const duration = Date.now() - startTime;
 
-            // 慢查询警告（超过 1000ms）
-            if (duration > 1000) {
-                const sqlPreview = sqlStr.length > 100 ? sqlStr.substring(0, 100) + '...' : sqlStr;
-                Logger.warn(`🐌 检测到慢查询 (${duration}ms): ${sqlPreview}`);
+            // 慢查询警告（超过 5000ms）
+            if (duration > 5000) {
+                Logger.warn(
+                    {
+                        subsystem: "db",
+                        event: "slow",
+                        duration: duration,
+                        sqlPreview: sqlStr,
+                        params: params || [],
+                        paramsCount: (params || []).length
+                    },
+                    "🐌 检测到慢查询"
+                );
             }
 
             return result;
         } catch (error: any) {
             const duration = Date.now() - startTime;
 
-            Logger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-            Logger.error('SQL 执行错误');
-            Logger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-            Logger.error(`SQL 语句: ${sqlStr.length > 200 ? sqlStr.substring(0, 200) + '...' : sqlStr}`);
-            Logger.error(`参数列表: ${JSON.stringify(params || [])}`);
-            Logger.error(`执行耗时: ${duration}ms`);
-            Logger.error(`错误信息: ${error.message}`);
-            if (error.stack) {
-                Logger.error(`错误堆栈:\n${error.stack}`);
-            }
-            Logger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            const sqlPreview = sqlStr.length > 200 ? sqlStr.substring(0, 200) + "..." : sqlStr;
+            Logger.error(
+                {
+                    err: error,
+                    sqlPreview: sqlPreview,
+                    params: params || [],
+                    duration: duration
+                },
+                "SQL 执行错误"
+            );
 
             const enhancedError: any = new Error(`SQL执行失败: ${error.message}`);
             enhancedError.originalError = error;
@@ -527,7 +589,7 @@ 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 result = await this.executeWithConn("SELECT COUNT(*) as count FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?", [snakeTableName]);
 
         return result?.[0]?.count > 0;
     }
@@ -549,11 +611,11 @@ export class DbHelper {
      *     where: { 'o.state': 1 }
      * });
      */
-    async getCount(options: Omit<QueryOptions, 'fields' | 'page' | 'limit' | 'orderBy'>): Promise<number> {
+    async getCount(options: Omit<QueryOptions, "fields" | "page" | "limit" | "orderBy">): Promise<number> {
         const { table, where, joins } = await this.prepareQueryOptions(options as QueryOptions);
 
         const builder = new SqlBuilder()
-            .select(['COUNT(*) as count'])
+            .select(["COUNT(*) as count"])
             .from(table)
             .where(this.addDefaultStateFilter(where, table, !!joins));
 
@@ -602,8 +664,12 @@ export class DbHelper {
 
         const camelRow = keysToCamel<T>(row);
 
+        // 反序列化数组字段（JSON 字符串 → 数组）
+        const deserialized = this.deserializeArrayFields<T>(camelRow);
+        if (!deserialized) return null;
+
         // 转换 BIGINT 字段（id, pid 等）为数字类型
-        return this.convertBigIntFields<T>([camelRow])[0];
+        return this.convertBigIntFields<T>([deserialized])[0];
     }
 
     /**
@@ -643,7 +709,7 @@ export class DbHelper {
         const whereFiltered = this.addDefaultStateFilter(prepared.where, prepared.table, !!prepared.joins);
 
         // 查询总数
-        const countBuilder = new SqlBuilder().select(['COUNT(*) as total']).from(prepared.table).where(whereFiltered);
+        const countBuilder = new SqlBuilder().select(["COUNT(*) as total"]).from(prepared.table).where(whereFiltered);
 
         // 添加 JOIN（计数也需要）
         this.applyJoins(countBuilder, prepared.joins);
@@ -681,9 +747,12 @@ export class DbHelper {
         // 字段名转换：下划线 → 小驼峰
         const camelList = arrayKeysToCamel<T>(list);
 
+        // 反序列化数组字段
+        const deserializedList = camelList.map((item) => this.deserializeArrayFields<T>(item)).filter((item): item is T => item !== null);
+
         // 转换 BIGINT 字段（id, pid 等）为数字类型
         return {
-            lists: this.convertBigIntFields<T>(camelList),
+            lists: this.convertBigIntFields<T>(deserializedList),
             total: total,
             page: prepared.page,
             limit: prepared.limit,
@@ -708,7 +777,7 @@ export class DbHelper {
      *     where: { 'o.state': 1 }
      * })
      */
-    async getAll<T extends Record<string, any> = Record<string, any>>(options: Omit<QueryOptions, 'page' | 'limit'>): Promise<AllResult<T>> {
+    async getAll<T extends Record<string, any> = Record<string, any>>(options: Omit<QueryOptions, "page" | "limit">): Promise<AllResult<T>> {
         // 添加硬性上限保护，防止内存溢出
         const MAX_LIMIT = 10000;
         const WARNING_LIMIT = 1000;
@@ -718,7 +787,7 @@ export class DbHelper {
         const whereFiltered = this.addDefaultStateFilter(prepared.where, prepared.table, !!prepared.joins);
 
         // 查询真实总数
-        const countBuilder = new SqlBuilder().select(['COUNT(*) as total']).from(prepared.table).where(whereFiltered);
+        const countBuilder = new SqlBuilder().select(["COUNT(*) as total"]).from(prepared.table).where(whereFiltered);
 
         // 添加 JOIN（计数也需要）
         this.applyJoins(countBuilder, prepared.joins);
@@ -750,7 +819,7 @@ export class DbHelper {
 
         // 警告日志：返回数据超过警告阈值
         if (result.length >= WARNING_LIMIT) {
-            Logger.warn({ table: options.table, count: result.length, total: total }, 'getAll 返回数据过多，建议使用 getList 分页查询');
+            Logger.warn({ table: options.table, count: result.length, total: total }, "getAll 返回数据过多，建议使用 getList 分页查询");
         }
 
         // 如果达到上限，额外警告
@@ -761,8 +830,11 @@ export class DbHelper {
         // 字段名转换：下划线 → 小驼峰
         const camelResult = arrayKeysToCamel<T>(result);
 
+        // 反序列化数组字段
+        const deserializedList = camelResult.map((item) => this.deserializeArrayFields<T>(item)).filter((item): item is T => item !== null);
+
         // 转换 BIGINT 字段（id, pid 等）为数字类型
-        const lists = this.convertBigIntFields<T>(camelResult);
+        const lists = this.convertBigIntFields<T>(deserializedList);
 
         return {
             lists: lists,
@@ -787,8 +859,11 @@ export class DbHelper {
         // 字段名转换：小驼峰 → 下划线
         const snakeData = keysToSnake(cleanData);
 
+        // 序列化数组字段（数组 → JSON 字符串）
+        const serializedData = this.serializeArrayFields(snakeData);
+
         // 复制用户数据，但移除系统字段（防止用户尝试覆盖）
-        const { id, created_at, updated_at, deleted_at, state, ...userData } = 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 };
 
@@ -854,8 +929,11 @@ export class DbHelper {
             // 字段名转换：小驼峰 → 下划线
             const snakeData = keysToSnake(cleanData);
 
+            // 序列化数组字段（数组 → JSON 字符串）
+            const serializedData = this.serializeArrayFields(snakeData);
+
             // 移除系统字段（防止用户尝试覆盖）
-            const { id, created_at, updated_at, deleted_at, state, ...userData } = snakeData;
+            const { id: _id, created_at: _created_at, updated_at: _updated_at, deleted_at: _deleted_at, state: _state, ...userData } = serializedData;
 
             // 强制生成系统字段（不可被用户覆盖）
             return {
@@ -876,7 +954,7 @@ 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 }, "批量插入失败");
             throw error;
         }
     }
@@ -899,9 +977,12 @@ export class DbHelper {
         const snakeData = keysToSnake(cleanData);
         const snakeWhere = this.whereKeysToSnake(cleanWhere);
 
+        // 序列化数组字段（数组 → JSON 字符串）
+        const serializedData = this.serializeArrayFields(snakeData);
+
         // 移除系统字段（防止用户尝试修改）
         // 注意：state 允许用户修改（用于设置禁用状态 state=2）
-        const { id, created_at, updated_at, deleted_at, ...userData } = snakeData;
+        const { id: _id, created_at: _created_at, updated_at: _updated_at, deleted_at: _deleted_at, ...userData } = serializedData;
 
         // 强制更新时间戳（不可被用户覆盖）
         const processed: Record<string, any> = {
@@ -937,7 +1018,7 @@ export class DbHelper {
      * 硬删除数据（物理删除，不可恢复）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
      */
-    async delForce(options: Omit<DeleteOptions, 'hard'>): Promise<number> {
+    async delForce(options: Omit<DeleteOptions, "hard">): Promise<number> {
         const { table, where } = options;
 
         // 转换表名：小驼峰 → 下划线
@@ -959,7 +1040,7 @@ export class DbHelper {
      * 禁用数据（设置 state=2）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
      */
-    async disableData(options: Omit<DeleteOptions, 'hard'>): Promise<number> {
+    async disableData(options: Omit<DeleteOptions, "hard">): Promise<number> {
         const { table, where } = options;
 
         return await this.updData({
@@ -975,7 +1056,7 @@ export class DbHelper {
      * 启用数据（设置 state=1）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
      */
-    async enableData(options: Omit<DeleteOptions, 'hard'>): Promise<number> {
+    async enableData(options: Omit<DeleteOptions, "hard">): Promise<number> {
         const { table, where } = options;
 
         return await this.updData({
@@ -1016,12 +1097,12 @@ export class DbHelper {
      * 检查数据是否存在（优化性能）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
      */
-    async exists(options: Omit<QueryOptions, 'fields' | 'orderBy' | 'page' | 'limit'>): Promise<boolean> {
+    async exists(options: Omit<QueryOptions, "fields" | "orderBy" | "page" | "limit">): Promise<boolean> {
         const { table, where } = await this.prepareQueryOptions({ ...options, page: 1, limit: 1 });
 
         // 使用 COUNT(1) 性能更好
         const builder = new SqlBuilder()
-            .select(['COUNT(1) as cnt'])
+            .select(["COUNT(1) as cnt"])
             .from(table)
             .where(this.addDefaultStateFilter(where, table, false))
             .limit(1);
@@ -1036,7 +1117,7 @@ export class DbHelper {
      * 查询单个字段值（带字段名验证）
      * @param field - 字段名（支持小驼峰或下划线格式）
      */
-    async getFieldValue<T = any>(options: Omit<QueryOptions, 'fields'> & { field: string }): Promise<T | null> {
+    async getFieldValue<T = any>(options: Omit<QueryOptions, "fields"> & { field: string }): Promise<T | null> {
         const { field, ...queryOptions } = options;
 
         // 验证字段名格式（只允许字母、数字、下划线）
@@ -1094,7 +1175,7 @@ export class DbHelper {
         }
 
         // 验证 value 必须是数字
-        if (typeof value !== 'number' || isNaN(value)) {
+        if (typeof value !== "number" || isNaN(value)) {
             throw new Error(`自增值必须是有效的数字 (table: ${table}, field: ${field}, value: ${value})`);
         }