midway-fatcms 0.0.5 → 0.0.6

package/src/libs/crud-pro/services/CrudProDataTypeConvertService.ts

@@ -0,0 +1,171 @@
+import { CrudProServiceBase } from './CrudProServiceBase';
+import { RequestModel } from '../models/RequestModel';
+import { RequestCfgModel } from '../models/RequestCfgModel';
+import { KeysOfSimpleSQL, SqlDbType } from '../models/keys';
+import { ITableMetaQuery } from '../interfaces';
+
+/**
+ * 数据类型转换服务
+ * 根据表结构字段类型，在 INSERT/UPDATE 操作前自动转换数据格式，确保数据与数据库方言兼容
+ *
+ * 当前支持的转换：
+ * - PostgreSQL ARRAY 类型：JSON 数组 → PG 数组字面量 {"a","b","c"}
+ */
+class CrudProDataTypeConvertService extends CrudProServiceBase {
+
+  /**
+   * 根据表结构字段类型自动转换 reqModel.data 中的数据格式
+   * 仅对 PostgreSQL 的 INSERT/UPDATE 类型操作生效
+   *
+   * @param reqModel 请求模型
+   * @param cfgModel 配置模型
+   */
+  async convertDataTypeByTableMeta(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void> {
+    if (cfgModel.sqlDbType !== SqlDbType.postgres) {
+      return;
+    }
+
+    const sqlSimpleName = cfgModel.sqlSimpleName;
+    if (!this.isInsertOrUpdateType(sqlSimpleName)) {
+      return;
+    }
+
+    if (!reqModel.data) {
+      return;
+    }
+
+    const query: ITableMetaQuery = {
+      sqlTable: cfgModel.sqlTable,
+      sqlDatabase: cfgModel.sqlDatabase,
+      sqlDbType: cfgModel.sqlDbType,
+      sqlSchema: cfgModel.sqlSchema,
+    };
+
+    const tableMeta = await this.serviceHub.getTableMeta(query);
+    if (!tableMeta || !tableMeta.columnDetails || tableMeta.columnDetails.length === 0) {
+      this.logger.warn('CrudProDataTypeConvertService: 无法获取表结构信息，跳过数据类型转换', cfgModel.sqlTable);
+      return;
+    }
+
+    const arrayFieldSet = new Set<string>();
+    for (const col of tableMeta.columnDetails) {
+      if (('' + col.type).toUpperCase() === 'ARRAY') {
+        arrayFieldSet.add(col.name);
+      }
+    }
+
+    if (arrayFieldSet.size === 0) {
+      return;
+    }
+
+    const data = reqModel.data;
+    if (Array.isArray(data)) {
+      for (const row of data) {
+        this.convertArrayFields(row, arrayFieldSet);
+      }
+    } else {
+      this.convertArrayFields(data, arrayFieldSet);
+    }
+  }
+
+  /**
+   * 遍历数据对象中的 ARRAY 类型字段，将 JSON 数组转为 PG 数组字面量格式
+   */
+  private convertArrayFields(dataObj: Record<string, any>, arrayFieldSet: Set<string>): void {
+    const keys = Object.keys(dataObj);
+    for (const key of keys) {
+      if (!arrayFieldSet.has(key)) {
+        continue;
+      }
+      const value = dataObj[key];
+      const parsed = this.tryParseArray(value);
+      if (Array.isArray(parsed)) {
+        dataObj[key] = this.toPgArrayLiteral(parsed);
+      }
+    }
+  }
+
+  /**
+   * 尝试将值解析为数组
+   * 支持：数组对象、JSON 数组字符串
+   */
+  private tryParseArray(value: any): any {
+    if (value === null || value === undefined) {
+      return null;
+    }
+    if (Array.isArray(value)) {
+      return value;
+    }
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      if (trimmed.startsWith('[')) {
+        try {
+          return JSON.parse(trimmed);
+        } catch (e) {
+          return null;
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * 将 JS 数组转为 PostgreSQL 数组字面量格式
+   *
+   * PG 数组字面量规则：
+   * - 字符串：双引号包裹，内部 " 转义为 \"，\ 转义为 \\   例：{"hello","world"}
+   * - 数字：不加引号                                                    例：{1,2,3}
+   * - 布尔：转为 t/f 不加引号                                           例：{t,f}
+   * - null/undefined：输出 NULL 不加引号                                例：{1,NULL,3}
+   * - 空数组：输出 {}
+   *
+   * @param arr JS 数组
+   * @returns PG 数组字面量字符串
+   */
+  private toPgArrayLiteral(arr: any[]): string {
+    if (arr.length === 0) {
+      return '{}';
+    }
+    const items = arr.map(v => this.toPgArrayItem(v));
+    return '{' + items.join(',') + '}';
+  }
+
+  /**
+   * 将单个 JS 值转为 PG 数组元素的字面量表示
+   */
+  private toPgArrayItem(value: any): string {
+    if (value === null || value === undefined) {
+      return 'NULL';
+    }
+    if (typeof value === 'number') {
+      return '' + value;
+    }
+    if (typeof value === 'boolean') {
+      return value ? 't' : 'f';
+    }
+    // 字符串及其它类型：转义后用双引号包裹
+    const escaped = ('' + value)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"');
+    return '"' + escaped + '"';
+  }
+
+  /**
+   * 判断 sqlSimpleName 是否为 INSERT/UPDATE 类型
+   */
+  private isInsertOrUpdateType(sqlSimpleName: string): boolean {
+    if (!sqlSimpleName) {
+      return false;
+    }
+    const types = [
+      KeysOfSimpleSQL.SIMPLE_INSERT,
+      KeysOfSimpleSQL.SIMPLE_UPDATE,
+      KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE,
+      KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE,
+      KeysOfSimpleSQL.SIMPLE_BATCH_INSERT,
+    ];
+    return types.includes(sqlSimpleName as KeysOfSimpleSQL);
+  }
+}
+
+export { CrudProDataTypeConvertService };

package/src/libs/crud-pro/services/CrudProExecuteSqlService.ts

@@ -201,7 +201,15 @@ class CrudProExecuteSqlService extends CrudProServiceBase {
   }
 
   private toQueryResByResPicker(rows: any[], originRes: any, sqlCfgModel: SqlCfgModel) {
-    const resPicker = sqlCfgModel.resPicker;
+    let resPicker = sqlCfgModel.resPicker;
+
+    // resPicker 未设置时，根据 SQL 类型自动推断
+    if (isEmpty(resPicker)) {
+      const crudType = sqlCfgModel.getCrudType();
+      if (crudType === KeyOfCrudTypes.INSERT || crudType === KeyOfCrudTypes.UPDATE || crudType === KeyOfCrudTypes.DELETE) {
+        resPicker = KeysOfSqlResPicker.UPDATE_RESULT;
+      }
+    }
 
     // 返回第一行
     if (KeysOfSqlResPicker.RESULT_FIRST_ROW === resPicker) {
@@ -220,6 +228,19 @@ class CrudProExecuteSqlService extends CrudProServiceBase {
       return Number(map0['total_count'] || 0);
     }
 
+    // 判断元素是否存在，返回 boolean
+    if (KeysOfSqlResPicker.RESULT_IS_EXIST === resPicker) {
+      if (isEmpty(rows) || rows.length === 0) {
+        return false;
+      }
+      const val = rows[0]['is_exist'];
+      // MySQL/SQLServer 返回 0/1，PostgreSQL 返回 false/true
+      if (typeof val === 'boolean') {
+        return val;
+      }
+      return Number(val) > 0;
+    }
+
     // 增删改res的内容是修改结果：包括： insert\delete\update
     if (KeysOfSqlResPicker.UPDATE_RESULT === resPicker) {
       if (sqlCfgModel.sqlDbType === SqlDbType.postgres) {
@@ -248,6 +269,8 @@ class CrudProExecuteSqlService extends CrudProServiceBase {
       return rows;
     }
 
+
+
     //其他配置：形如： sqlRes[0].total_count
     if (typeof resPicker === 'string') {
       if (resPicker.startsWith('sqlRes')) {

package/src/libs/crud-pro/services/CrudProFieldValidateService.ts

@@ -2,7 +2,7 @@ import { RequestModel } from '../models/RequestModel';
 import { CrudProServiceBase } from './CrudProServiceBase';
 import { RequestCfgModel } from '../models/RequestCfgModel';
 import { MixinUtils } from '../utils/MixinUtils';
-import { KeysOfConditions, KeysOfValidators } from '../models/keys';
+import { KeysOfConditions, KeysOfSimpleSQL, KeysOfValidators } from '../models/keys';
 import { CommonException, Exceptions } from '../exceptions';
 import { ModelUtils } from '../utils/ModelUtils';
 import { ICustomValidateFunc, IFuncCfgModel, IValidatorCfgItem } from '../interfaces';
@@ -175,6 +175,58 @@ class CrudProFieldValidateService extends CrudProServiceBase {
       }
     }
   }
+
+  /**
+   * 校验 data 字段类型是否符合 sqlSimpleName 的要求
+   * 
+   * - SIMPLE_BATCH_INSERT: data 必须是数组
+   * - 其他 INSERT/UPDATE 类型: data 必须是普通对象
+   */
+  validateDataType(cfgModel: RequestCfgModel, reqModel: RequestModel): void {
+    const sqlSimpleName = cfgModel.sqlSimpleName;
+    if (!sqlSimpleName) {
+      return;
+    }
+
+    const data = reqModel.data;
+
+    const isArrayData = Array.isArray(data);
+
+    if (sqlSimpleName === KeysOfSimpleSQL.SIMPLE_BATCH_INSERT) {
+      if (!isArrayData || data.length === 0) {
+        throw new CommonException(
+          Exceptions.CFG_INVALID_DATA_TYPE,
+          `${sqlSimpleName} 要求 data 必须是数组。并且不能为空数组。`
+        );
+      }
+      return;
+    }
+
+    const needsObjectData = [
+      KeysOfSimpleSQL.SIMPLE_INSERT,
+      KeysOfSimpleSQL.SIMPLE_UPDATE,
+      KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE,
+      KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE,
+    ].includes(sqlSimpleName as KeysOfSimpleSQL);
+
+
+    if(needsObjectData && (!data || Object.keys(data).length === 0)) {
+      throw new CommonException(
+        Exceptions.CFG_INVALID_DATA_TYPE,
+        `${sqlSimpleName} 要求 data 必须是对象，不能为空`
+      );
+    }
+
+    if (needsObjectData && isArrayData) {
+      throw new CommonException(
+        Exceptions.CFG_INVALID_DATA_TYPE,
+        `${sqlSimpleName} 要求 data 必须是普通对象，不能是数组`
+      );
+    }
+
+
+
+  }
 }
 
 export { CrudProFieldValidateService };

package/src/libs/crud-pro/services/CrudProGenSqlService.ts

@@ -39,7 +39,11 @@ class CrudProGenSqlService extends CrudProServiceBase {
     let sql1 = null;
     let sql2 = null;
     let sql3 = null;
-    if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_QUERY, simpleSqlName)) {
+
+    if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_QUERY_EXIST, simpleSqlName)) {
+      sql1 = this.generateOriginSqlForIsExist(cfgModel);
+      cfgModel.addSqlCfgModel('is_exist', sql1, KeysOfSqlResPicker.RESULT_IS_EXIST);
+    } else if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_QUERY, simpleSqlName)) {
       sql1 = 'select @@columns from @@table where @@asWhere:condition @@orderBys @@offsetLimit';
       cfgModel.addSqlCfgModel('rows', sql1);
     } else if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_QUERY_ONE, simpleSqlName)) {
@@ -61,6 +65,9 @@ class CrudProGenSqlService extends CrudProServiceBase {
     } else if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_INSERT, simpleSqlName)) {
       sql1 = this.generateOriginSqlForInsert(cfgModel);
       cfgModel.addSqlCfgModel('affected', sql1, KeysOfSqlResPicker.UPDATE_RESULT);
+    } else if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_BATCH_INSERT, simpleSqlName)) {
+      sql1 = this.generateOriginSqlForBatchInsert(cfgModel);
+      cfgModel.addSqlCfgModel('affected', sql1, KeysOfSqlResPicker.UPDATE_RESULT);
     } else if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_UPDATE, simpleSqlName)) {
       sql1 = 'update @@table set @@asUpdate:data where @@asWhere:condition ';
       cfgModel.addSqlCfgModel('affected', sql1, KeysOfSqlResPicker.UPDATE_RESULT);
@@ -68,20 +75,21 @@ class CrudProGenSqlService extends CrudProServiceBase {
       sql1 = this.generateOriginSqlForDuplicateInsert(cfgModel);
       cfgModel.addSqlCfgModel('affected', sql1, KeysOfSqlResPicker.UPDATE_RESULT);
     } else if (equalsIgnoreCase(KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE, simpleSqlName)) {
-      sql1 = 'select count(0) as total_count from @@table where @@asWhere:condition ';
-      sql2 = 'insert into @@table ( @@asInsertKeys:data ) values( @@asInsertValues:data )';
+      
+      sql1 = this.generateOriginSqlForIsExist(cfgModel); // 判断元素是否存在
+      sql2 = this.generateOriginSqlForInsert(cfgModel); // 插入语句
       sql3 = 'update @@table set @@asUpdate:data where @@asWhere:condition ';
 
       const insertWhen2 = {
         functionName: 'eq',
-        functionParams: [{ contextAsNumber: 'res.total_count' }, { constNumber: 0 }],
+        functionParams: [{ contextAsBool: 'res.is_exist' }, { constBool: false }],
       };
       const updateWhen3 = {
-        functionName: 'gt',
-        functionParams: [{ contextAsNumber: 'res.total_count' }, { constNumber: 0 }],
+        functionName: 'eq',
+        functionParams: [{ contextAsBool: 'res.is_exist' }, { constBool: true }],
       };
 
-      cfgModel.addSqlCfgModel('total_count', sql1, KeysOfSqlResPicker.RESULT_TOTAL_COUNT);
+      cfgModel.addSqlCfgModel('is_exist', sql1, KeysOfSqlResPicker.RESULT_IS_EXIST);
       cfgModel.addSqlCfgModel('insert_affected', sql2, KeysOfSqlResPicker.UPDATE_RESULT, insertWhen2);
       cfgModel.addSqlCfgModel('update_affected', sql3, KeysOfSqlResPicker.UPDATE_RESULT, updateWhen3);
     }
@@ -91,6 +99,27 @@ class CrudProGenSqlService extends CrudProServiceBase {
     }
   }
 
+
+
+
+
+  /**
+   * 判断元素是否存在
+   * 使用 SELECT EXISTS 子查询，数据库引擎找到第一条匹配记录即停止扫描，比 COUNT(*) 更高效
+   * @param cfgModel
+   * @private
+   */
+  private generateOriginSqlForIsExist(cfgModel: RequestCfgModel): string {
+    if (cfgModel.sqlDbType === SqlDbType.postgres) {
+      return 'SELECT EXISTS(SELECT 1 FROM @@table WHERE @@asWhere:condition) AS is_exist';
+    }
+    if (cfgModel.sqlDbType === SqlDbType.sqlserver) {
+      return 'SELECT CASE WHEN EXISTS(SELECT 1 FROM @@table WHERE @@asWhere:condition) THEN 1 ELSE 0 END AS is_exist';
+    }
+    return 'SELECT EXISTS(SELECT 1 FROM @@table WHERE @@asWhere:condition) AS is_exist';
+  }
+
+
   /**
    * 删除语句
    * @param cfgModel
@@ -157,6 +186,21 @@ class CrudProGenSqlService extends CrudProServiceBase {
     return 'insert into @@table ( @@asInsertKeys:data ) values( @@asInsertValues:data )'; // 关键字的前后，必须有空格
   }
 
+  /**
+   * 创建批量插入语句
+   * @param cfgModel
+   * @private
+   */
+  private generateOriginSqlForBatchInsert(cfgModel: RequestCfgModel): string {
+    if (cfgModel.sqlDbType === SqlDbType.postgres) {
+      return 'insert into @@table ( @@asBatchInsertKeys:data ) values @@asBatchInsertValues:data RETURNING * ';
+    }
+    if (cfgModel.sqlDbType === SqlDbType.sqlserver) {
+      return 'insert into @@table ( @@asBatchInsertKeys:data ) OUTPUT INSERTED.* values @@asBatchInsertValues:data ';
+    }
+    return 'insert into @@table ( @@asBatchInsertKeys:data ) values @@asBatchInsertValues:data '; // MySQL 默认语法
+  }
+
   private async generateExecuteSql() {
     const exeCtx = this.getExecuteContext();
 

package/src/libs/crud-pro/services/CrudProOriginToExecuteSql.ts

@@ -3,7 +3,7 @@ import { SqlCfgModel } from '../models/SqlCfgModel';
 import { ITableMetaQuery } from '../interfaces';
 import { MixinUtils } from '../utils/MixinUtils';
 import { SqlSegArg } from '../models/SqlSegArg';
-import { KeysOfCustomSQL, SqlDbType } from '../models/keys';
+import { KeysOfCustomSQL, KeyOfCrudTypes, SqlDbType } from '../models/keys';
 import { RequestModel } from '../models/RequestModel';
 import { CommonException, Exceptions } from '../exceptions';
 import { RequestCfgModel } from '../models/RequestCfgModel';
@@ -73,7 +73,43 @@ class CrudProOriginToExecuteSql extends CrudProServiceBase {
     }
 
     sqlCfgModel.executeSqlArgs = argList;
-    sqlCfgModel.executeSql = executeSql;
+    sqlCfgModel.executeSql = this.appendDialectClause(executeSql, sqlCfgModel);
+  }
+
+  /**
+   * 对于自定义 INSERT SQL，自动追加数据库方言子句：
+   * - PostgreSQL: RETURNING *
+   * - SQL Server: OUTPUT INSERTED.*
+   * - MySQL: 无需追加，驱动自动返回 insertId
+   * 
+   * 仅当 originSql 中用户未手动添加这些子句时才追加
+   */
+  private appendDialectClause(executeSql: string, sqlCfgModel: SqlCfgModel): string {
+    const sqlDbType = sqlCfgModel.sqlDbType;
+    const sqlUpper = executeSql.trim().toUpperCase();
+
+    if (!sqlUpper.startsWith(KeyOfCrudTypes.INSERT)) {
+      return executeSql;
+    }
+
+    if (sqlDbType === SqlDbType.postgres) {
+      if (sqlUpper.indexOf('RETURNING') < 0) {
+        return executeSql + ' RETURNING *';
+      }
+    } else if (sqlDbType === SqlDbType.sqlserver) {
+      if (sqlUpper.indexOf('OUTPUT INSERTED') < 0) {
+        // SQL Server: OUTPUT INSERTED.* 需放在 VALUES 之前
+        // INSERT INTO table (...) OUTPUT INSERTED.* VALUES (...)
+        const valuesIndex = sqlUpper.lastIndexOf('VALUES');
+        if (valuesIndex > 0) {
+          const beforeValues = executeSql.substring(0, valuesIndex);
+          const fromValues = executeSql.substring(valuesIndex);
+          return beforeValues + ' OUTPUT INSERTED.* ' + fromValues;
+        }
+      }
+    }
+
+    return executeSql;
   }
 
   private async generateWordMap(originSql: string, sqlCfgModel: SqlCfgModel): Promise<Record<string, SqlSegArg>> {
@@ -123,6 +159,10 @@ class CrudProOriginToExecuteSql extends CrudProServiceBase {
       return this.generateDataAsInsertKeys(reqModel, sqlCfg, MixinUtils.removeStringPrefix(word, KeysOfCustomSQL.SQL_AS_INSERT_KEYS));
     } else if (word.startsWith(KeysOfCustomSQL.SQL_AS_INSERT_VALUES)) {
       return this.generateDataAsInsertValues(reqModel, MixinUtils.removeStringPrefix(word, KeysOfCustomSQL.SQL_AS_INSERT_VALUES));
+    } else if (word.startsWith(KeysOfCustomSQL.SQL_AS_BATCH_INSERT_KEYS)) {
+      return this.generateDataAsBatchInsertKeys(reqModel, sqlCfg, MixinUtils.removeStringPrefix(word, KeysOfCustomSQL.SQL_AS_BATCH_INSERT_KEYS));
+    } else if (word.startsWith(KeysOfCustomSQL.SQL_AS_BATCH_INSERT_VALUES)) {
+      return this.generateDataAsBatchInsertValues(reqModel, MixinUtils.removeStringPrefix(word, KeysOfCustomSQL.SQL_AS_BATCH_INSERT_VALUES));
     } else if (word.startsWith(KeysOfCustomSQL.SQL_FUNCTION)) {
       return this.generateSqlJavaFunction(reqCfg, MixinUtils.removeStringPrefix(word, KeysOfCustomSQL.SQL_FUNCTION));
     } else {
@@ -334,6 +374,123 @@ class CrudProOriginToExecuteSql extends CrudProServiceBase {
     return new SqlSegArg(sql, argList);
   }
 
+  /**
+   * 获取批量插入的字段名列表
+   * 
+   * 策略：
+   * - 如果指定了 columns，直接使用 columns（允许数据行包含额外字段，仅插入指定列）
+   * - 否则取第一条数据的 keys，并校验后续行是否一致（严格模式）
+   * 
+   * 严格模式限制：
+   * - 所有数据行必须包含完全相同的字段
+   * - 字段数量必须一致
+   * - 字段名必须一致（顺序可不同）
+   * - 若不一致，抛出 BATCH_INSERT_KEYS_MISMATCH 异常
+   * 
+   * @param req RequestModel 请求模型
+   * @param dataArray 数据数组
+   * @returns 排序后的字段名数组
+   */
+  private getBatchInsertKeys(req: RequestModel, dataArray: Record<string, any>[]): string[] {
+    // 如果指定了 columns，直接使用
+    if (MixinUtils.isNotEmpty(req.columns) && req.columns.length > 0) {
+      return [...req.columns].sort();
+    }
+
+    // 严格模式：取第一条数据的 keys，并校验后续行
+    const firstRow = dataArray[0];
+    const keys = Object.keys(firstRow).sort();
+
+    for (let i = 1; i < dataArray.length; i++) {
+      const row = dataArray[i];
+      const rowKeys = Object.keys(row).sort();
+
+      if (rowKeys.length !== keys.length) {
+        throw new CommonException(
+          Exceptions.BATCH_INSERT_KEYS_MISMATCH,
+          `批量插入第 ${i + 1} 行数据字段数量不一致，期望 ${keys.length} 个，实际 ${rowKeys.length} 个`
+        );
+      }
+
+      for (let j = 0; j < keys.length; j++) {
+        if (rowKeys[j] !== keys[j]) {
+          throw new CommonException(
+            Exceptions.BATCH_INSERT_KEYS_MISMATCH,
+            `批量插入第 ${i + 1} 行数据字段不一致，缺少字段 "${keys[j]}" 或包含额外字段`
+          );
+        }
+      }
+    }
+
+    return keys;
+  }
+
+  /**
+   * 批量插入：生成列名部分
+   * 
+   * 列名获取策略：
+   * - 优先使用 req.columns（若指定）
+   * - 否则使用严格模式：取第一条数据的 keys，校验后续行字段一致性
+   */
+  private generateDataAsBatchInsertKeys(req: RequestModel, sqlCfgModel: SqlCfgModel, dataName: string): SqlSegArg {
+    const dataArray = req.getCondOrDataAsArray(dataName);
+
+    if (MixinUtils.isEmpty(dataArray) || dataArray.length === 0) {
+      throw new CommonException(Exceptions.DATA_GET_DATA_EMPTY_ON_INSERT_KEYS, dataName);
+    }
+
+    const keys = this.getBatchInsertKeys(req, dataArray);
+
+    const columnList = keys.map(columnName => {
+      return toSqlColumnName(columnName, sqlCfgModel);
+    });
+
+    const sql = columnList.join(','); // `column1`,`column2`,`column3`
+    return new SqlSegArg(sql);
+  }
+
+  /**
+   * 批量插入：生成值部分，格式为 (?,?,?),(?,?,?),...
+   * 
+   * 列名获取策略：
+   * - 优先使用 req.columns（若指定）
+   * - 否则使用严格模式：取第一条数据的 keys，校验后续行字段一致性
+   */
+  private generateDataAsBatchInsertValues(req: RequestModel, dataName: string): SqlSegArg {
+    const dataArray = req.getCondOrDataAsArray(dataName);
+
+    if (MixinUtils.isEmpty(dataArray) || dataArray.length === 0) {
+      throw new CommonException(Exceptions.DATA_GET_DATA_EMPTY_ON_INSERT_VALUES, dataName);
+    }
+
+    const keys = this.getBatchInsertKeys(req, dataArray);
+
+    const valueGroups: string[] = [];
+    const argList: any[] = [];
+
+    for (let i = 0; i < dataArray.length; i++) {
+      const row = dataArray[i];
+      const rowValues: string[] = [];
+
+      for (let j = 0; j < keys.length; j++) {
+        const key = keys[j];
+        const arg = row[key];
+
+        if (sqlFuncUtils.isSqlFuncArg(arg)) {
+          rowValues.push(sqlFuncUtils.toFuncSQL(arg));
+        } else {
+          rowValues.push('?');
+          argList.push(arg);
+        }
+      }
+
+      valueGroups.push('(' + rowValues.join(',') + ')');
+    }
+
+    const sql = valueGroups.join(','); // "(?,?,?),(?,?,?),..."
+    return new SqlSegArg(sql, argList);
+  }
+
   private generateSqlJavaFunction(requestCfg: RequestCfgModel, tmpFuncName: string): SqlSegArg {
     const exeCtx = this.getExecuteContext();