midway-fatcms 0.0.5 → 0.0.7

package/src/libs/crud-pro/README_FUNC.md

@@ -0,0 +1,193 @@
+# CrudPro 内置函数参考
+
+CrudPro 的 `IFuncCfgModel` 支持 `functionName` 方式调用内置函数。内置函数由四个工具类注册：`DateTimeUtils`、`CompareUtils`、`MixinUtils`、`TypeUtils`。
+
+> 源码位置：`src/libs/crud-pro/services/CrudProServiceBase.ts` → `createBuildInExecuteFuncMap()`
+
+## 调用方式
+
+`functionName` 是 `IFuncCfgModel` 的属性之一，可在 `updateCfg`、`validateCfg`、`executeWhen`、`validate` 等配置中使用。
+
+### 无参调用
+
+```typescript
+'data.created_at': { functionName: 'getCurrentTimeString' }
+```
+
+### 带参调用
+
+```typescript
+'data.order_date': { functionName: 'getCurrentDateFormat', functionParams: ['YYYYMMDD'] }
+```
+
+`functionParams` 中的每个元素可以是基础类型（string / number / boolean），也可以嵌套 `IFuncCfgModel` 对象：
+
+```typescript
+{
+  functionName: 'eq',
+  functionParams: [
+    { contextAsBool: 'res.is_exist' },
+    { constBool: false }
+  ]
+}
+```
+
+## DateTimeUtils — 日期时间
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `getCurrentTimeStampMs` | 无 | `number` | 当前时间戳（毫秒） |
+| `getCurrentTimeStampSecond` | 无 | `number` | 当前时间戳（秒） |
+| `getCurrentTimeString` | 无 | `string` | 当前时间，格式 `YYYY-MM-DD HH:mm:ss` |
+| `getCurrentDateFormat` | `format: string` | `string` | 按指定格式返回当前时间 |
+| `getYesterdayDateFormat` | `format: string` | `string` | 按指定格式返回昨天时间 |
+
+**示例：**
+
+```typescript
+updateCfg: {
+  'data.created_at': { functionName: 'getCurrentTimeString' },
+  'data.created_ts': { functionName: 'getCurrentTimeStampMs' },
+  'data.order_date': { functionName: 'getCurrentDateFormat', functionParams: ['YYYYMMDD'] },
+  'data.yesterday': { functionName: 'getYesterdayDateFormat', functionParams: ['YYYY-MM-DD'] },
+}
+```
+
+## CompareUtils — 比较运算
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `eq` | `a: any, b: any` | `boolean` | 相等比较（`==`，兼容类型转换） |
+| `ne` | `a: any, b: any` | `boolean` | 不相等 |
+| `gt` | `a: any, b: any` | `boolean` | 大于 |
+| `gte` | `a: any, b: any` | `boolean` | 大于等于 |
+| `lt` | `a: any, b: any` | `boolean` | 小于 |
+| `lte` | `a: any, b: any` | `boolean` | 小于等于 |
+
+**示例：**
+
+```typescript
+// executeWhen：仅当 is_exist 为 false 时执行插入
+executeWhen: {
+  functionName: 'eq',
+  functionParams: [{ contextAsBool: 'res.is_exist' }, { constBool: false }]
+}
+
+// validate：确保数量大于 0
+validate: {
+  functionName: 'gt',
+  functionParams: [{ context: '$current' }, { constNumber: 0 }],
+  message: '数量必须大于0'
+}
+```
+
+## MixinUtils — 通用工具
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `isNil` | `obj: any` | `boolean` | 是否为 null 或 undefined |
+| `isNotNil` | `obj: any` | `boolean` | 不为 null 且不为 undefined |
+| `isEmpty` | `obj: any` | `boolean` | 是否为空（null / undefined / 空字符串 / 空数组 / 空对象） |
+| `isNotEmpty` | `obj: any` | `boolean` | 是否非空 |
+| `equals` | `obj1: any, obj2: any` | `boolean` | 严格相等（`===`） |
+| `equalsIgnoreCase` | `str1: string, str2: string` | `boolean` | 忽略大小写比较字符串 |
+| `startsWith` | `str1: string, str2: string` | `boolean` | 字符串前缀判断 |
+| `isValidFieldName` | `s: string` | `boolean` | 合法字段名（字母开头，仅含字母/数字/下划线） |
+| `selectNotEmpty` | `a: any, b: any` | `any` | 返回第一个非空值 |
+| `hasAny` | `a: string[], b: string[]` | `boolean` | 集合 A 是否包含集合 B 中的任意元素 |
+| `parseValueByType` | `value: any, targetType: string` | `any` | 按类型转换值（string / number / boolean / array / JSONObject） |
+| `sleepMs` | `ms: number` | `Promise` | 延时等待 |
+| `uuid` | 无 | `string` | 生成 UUID v4（优先 `crypto.getRandomValues`，降级 `Math.random`） |
+| `generateSnowflakeId` | `machineId?: number` | `string` | 生成雪花ID（64位整数字符串） |
+
+**uuid 和雪花ID 示例：**
+
+```typescript
+updateCfg: {
+  // UUID v4：适合需要标准唯一标识的场景
+  'data.id': { functionName: 'uuid' },
+
+  // 雪花ID：适合需要趋势递增、时间有序的场景
+  'data.order_id': { functionName: 'generateSnowflakeId' },
+
+  // 雪花ID：指定机器ID（0-1023），多实例部署时区分
+  'data.trace_id': { functionName: 'generateSnowflakeId', functionParams: [1] },
+}
+```
+
+> **雪花ID machineId 获取优先级**：函数参数 > 环境变量 `SNOWFLAKE_MACHINE_ID` > `process.pid` 低10位。多实例部署时建议设置环境变量 `SNOWFLAKE_MACHINE_ID` 为 0-1023 的唯一值。
+
+## TypeUtils — 类型判断
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `isBasicType` | `value: any` | `boolean` | 基础类型（boolean / string / number / null） |
+| `isBoolean` | `value: any` | `boolean` | 布尔值 |
+| `isString` | `value: any` | `boolean` | 字符串 |
+| `isInteger` | `value: any` | `boolean` | 整数 |
+| `isNumber` | `value: any` | `boolean` | 数字 |
+| `isNumeric` | `value: any` | `boolean` | 数字或可转换数字的字符串 |
+| `isValidName` | `value: any` | `boolean` | 合法命名（字母开头，字母/数字/下划线） |
+| `isChinesePhone` | `value: string` | `boolean` | 中文手机号 |
+| `isEmailStrValid` | `value: string` | `boolean` | 合法邮箱地址 |
+| `pickNumber` | `s: string` | `number \| null` | 从字符串中提取数字部分 |
+
+## 自定义函数扩展
+
+除内置函数外，可通过覆写 `IExecuteContextFunc.getFunctionMap()` 注册自定义函数。
+
+函数查找顺序：`getFunctionMap()` → `buildInExecuteFuncMap`（内置函数），自定义函数优先级更高，可覆盖内置函数。
+
+### 注册方式
+
+继承 `BaseExecuteContextFunc`，覆写 `getFunctionMap()` 方法返回函数映射表：
+
+```typescript
+import { BaseExecuteContextFunc } from './libs/crud-pro/models/ExecuteContextFunc';
+
+class MyContextFunc extends BaseExecuteContextFunc {
+
+  // 覆写此方法，返回自定义函数映射表
+  getFunctionMap(): any {
+    return {
+      // 无参函数
+      generateOrderNo: (prefix: string) => {
+        return prefix + Date.now().toString(36).toUpperCase();
+      },
+
+      // 带参函数：参数来自 functionParams 配置
+      formatAmount: (amount: number, currency: string) => {
+        return currency + ' ' + amount.toFixed(2);
+      },
+
+      // 可访问 FuncContext 的函数（通过 this 关键字）
+      getVisitorName: function(this: any) {
+        return this.reqModel?.visitor?.nickName || 'anonymous';
+      },
+    };
+  }
+}
+
+// 创建 CrudPro 实例时注入
+const crudPro = new CrudPro();
+crudPro.contextFunc = new MyContextFunc(/* 构造参数 */);
+```
+
+### 在配置中使用
+
+注册后即可在 `updateCfg`、`validateCfg`、`functionCfg` 等场景中通过 `functionName` 调用：
+
+```typescript
+const cfgJson: IRequestCfgModel = {
+  method: 'order.create',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT,
+  updateCfg: {
+    'data.order_no': { functionName: 'generateOrderNo', functionParams: ['PRE'] },
+  },
+};
+```
+
+> **注意**：`functionParams` 中配置的参数会按顺序传入函数。如果函数需要访问 `FuncContext`（如 `reqModel`、`resModel`、`currentValue`），
+> 需使用普通 `function`（非箭头函数）并通过 `this` 访问，框架会以 `func.apply(funcContext, params)` 方式调用。
+
+> **注意**：`generateOrderNo` 等并非内置函数，需通过 `contextFunc` 扩展注册后才可使用，否则运行时抛出 `RUN_FUNCTION_NOT_FOUND` 异常。

package/src/libs/crud-pro/exceptions.ts

@@ -49,6 +49,7 @@ export enum Exceptions {
   CFG_UNIQUE_COLUMN_COUNT_MUST_ONE = 'CFG_UNIQUE_COLUMN_COUNT_MUST_ONE',
   CFG_ORDER_BY_TYPE_ERROR = 'CFG_ORDER_BY_TYPE_ERROR',
   CFG_ERROR_POSTGRES_COLUMN_NAME_INVALID = 'CFG_ERROR_POSTGRES_COLUMN_NAME_INVALID',
+  CFG_INVALID_DATA_TYPE = 'CFG_INVALID_DATA_TYPE',
 
   /**
    * 数据传错
@@ -58,6 +59,7 @@ export enum Exceptions {
   DATA_GET_DATA_EMPTY_ON_UPDATE = 'DATA_GET_DATA_EMPTY_ON_UPDATE',
   DATA_GET_DATA_EMPTY_ON_INSERT_KEYS = 'DATA_GET_DATA_EMPTY_ON_INSERT_KEYS',
   DATA_GET_DATA_EMPTY_ON_INSERT_VALUES = 'DATA_GET_DATA_EMPTY_ON_INSERT_VALUES',
+  BATCH_INSERT_KEYS_MISMATCH = 'BATCH_INSERT_KEYS_MISMATCH', // 批量插入时字段不一致
 
   /**
    * 请求的Method字段为空

package/src/libs/crud-pro/interfaces.ts

@@ -54,7 +54,7 @@ export interface IRequestModel {
   method?: string;
   columns?: string | string[]; // "columns": "id,name,age,sex,addr",
   condition?: Record<string, any>; // 拼接查询条件
-  data?: Record<string, any>; //拼接update/insert语句的数据部分
+  data?: Record<string, any> | Record<string, any>[]; // 单条或批量插入/更新的数据部分
   orderBy?: string | IOrderByItem[];
   limit?: number;
   offset?: number;
@@ -182,6 +182,7 @@ export interface IRequestCfgModel extends IBaseCfgModel {
   transactionIsolation?: number; // 事务隔离级别
   sqlSimpleName?: KeysOfSimpleSQL; // 二选一 sqlSimpleName  sqlCfgList；； sqlCfgList 优先级高于sqlSimpleName
   sqlCfgList?: ISqlCfgModel[]; // 二选一 sqlSimpleName  sqlCfgList；； sqlCfgList 优先级高于sqlSimpleName
+  uniqueColumn?: string[]; // PostgreSQL/SQL Server 的唯一键列，用于 INSERT ON CONFLICT / MERGE
   updateCfg?: Record<string, IFuncCfgModel>;
   allowCfg?: Record<string, string[]>;
   rejectCfg?: Record<string, string[]>;
@@ -223,3 +224,39 @@ export interface ITableMetaQuery {
   sqlDbType: SqlDbType;
   sqlSchema?: string;
 }
+
+/**
+ * 表名列表查询参数
+ */
+export interface ITableNamesQuery {
+  sqlDatabase: string;
+  sqlDbType: SqlDbType;
+  sqlSchema?: string;
+}
+
+/**
+ * 表名查询缓存选项
+ */
+export interface ITableNamesOptions {
+  /** 是否跳过缓存，直接查询数据库 */
+  skipCache?: boolean;
+  /** 查询后是否更新缓存 */
+  refreshCache?: boolean;
+}
+
+/**
+ * 表信息项（包含表名和类型）
+ */
+export interface ITableInfo {
+  name: string;      // 表名
+  tableType: string; // 类型：'table' | 'view'
+}
+
+/**
+ * 表信息查询结果
+ */
+export interface ITableListResult {
+  tables: ITableInfo[];  // 所有表和视图
+  tableNames: string[];  // 仅表名（不含视图）
+  viewNames: string[];   // 仅视图名
+}

package/src/libs/crud-pro/models/ExecuteContext.ts

@@ -7,7 +7,7 @@ import { Transaction } from './Transaction';
 import { ColumnRelation, ICrudProCfg, ILogger, IVisitor } from '../interfaces';
 import { IExecuteContextFunc } from './ExecuteContextFunc';
 import { defaultCrudProCfg } from '../defaultConfigs';
-import { ResModelFlexible, ResModelPageQuery } from './ResModel';
+import { ResModelFlexible, ResModelPageQuery, ResModelRowEntity } from './ResModel';
 
 class ExecuteContext {
   // 运行前设置的
@@ -66,11 +66,14 @@ class ExecuteContext {
     return this.resModel;
   }
 
-  getOneObj() {
+
+  // 获取单条数据对象
+  getOneObj(): ResModelRowEntity {
     return this.resModel['row'];
   }
 
-  getResRows(): any[] {
+  // 获取多条数据对象
+  getResRows(): ResModelRowEntity[] {
     return this.resModel['rows'];
   }
 

package/src/libs/crud-pro/models/RequestModel.ts

@@ -1,6 +1,7 @@
 import * as _ from 'lodash';
 import { ILimitOffset, IOrderByItem, IRequestModel, IVisitor } from '../interfaces';
 import { MixinUtils } from '../utils/MixinUtils';
+import { OrderByUtils } from '../utils/OrderByUtils';
 import { CommonException, Exceptions } from '../exceptions';
 import { DEFAULT_LIMIT } from '../defaultConfigs';
 
@@ -10,7 +11,7 @@ class RequestModel {
   method: string;
   columns?: string[]; // "columns": "id,name,age,sex,addr",
   condition?: Record<string, any>;
-  data?: Record<string, any>;
+  data?: Record<string, any> | Record<string, any>[]; // 支持单条或批量数据
   limit: number;
   offset: number;
   orderBys?: IOrderByItem[];
@@ -19,75 +20,12 @@ class RequestModel {
     Object.assign(this, req);
     this.visitor = visitor;
     this.columns = MixinUtils.parseColumns(req.columns);
-    this.orderBys = this.parseOrderBys(req.orderBy);
+    this.orderBys = OrderByUtils.parseOrderBys(req.orderBy);
     const limitOffset = this.parseOffsetList(req);
     this.limit = limitOffset.limit;
     this.offset = limitOffset.offset;
   }
 
-  private parseOrderBys(orderByStr: any): IOrderByItem[] {
-    if (MixinUtils.isEmpty(orderByStr)) {
-      return [];
-    }
-
-    if (Array.isArray(orderByStr)) {
-      return orderByStr
-        .map(obj => {
-          if (typeof obj === 'string') {
-            return { fieldName: obj, orderType: 'asc' };
-          }
-
-          const { fieldName, orderType = 'asc' } = obj;
-          if (fieldName) {
-            return { fieldName, orderType };
-          }
-
-          return null;
-        })
-        .filter(o => {
-          return !!o;
-        });
-    }
-
-    const orderByResult: IOrderByItem[] = [];
-    const orderByArray = orderByStr
-      .split(',')
-      .map(s => {
-        return s.trim();
-      })
-      .filter(s => !!s);
-
-    if (MixinUtils.isEmpty(orderByArray)) {
-      return orderByResult;
-    }
-
-    for (let i = 0; i < orderByArray.length; i++) {
-      const orderByItem = orderByArray[i];
-      let orderType = 'asc'; //默认升序
-      let fieldName = orderByItem;
-
-      if (orderByItem.endsWith('+')) {
-        // 升序
-        fieldName = orderByItem.substring(0, orderByItem.length - 1);
-        orderType = 'asc'; //升序
-      } else if (orderByItem.endsWith('-')) {
-        //降序
-        fieldName = orderByItem.substring(0, orderByItem.length - 1);
-        orderType = 'desc'; //降序
-      }
-
-      fieldName = fieldName.trim();
-
-      if (MixinUtils.isEmpty(fieldName) || !MixinUtils.isValidFieldName(fieldName)) {
-        throw new CommonException(Exceptions.REQUEST_MODEL_PARSE_ORDER_BY_FAILED, orderByItem);
-      }
-
-      orderByResult.push({ fieldName, orderType });
-    }
-
-    return orderByResult;
-  }
-
   private parseOffsetList(req: IRequestModel): ILimitOffset {
     const { limit, offset, pageSize, pageNo } = req;
 
@@ -129,6 +67,26 @@ class RequestModel {
     throw new CommonException(Exceptions.RUN_GET_COND_OR_DATA_JSONOBJECT, attrName);
   }
 
+  /**
+   * 获取数组类型的数据（用于批量插入）
+   * @param attrName
+   */
+  getCondOrDataAsArray(attrName: string): Record<string, any>[] {
+    if (attrName.startsWith('data')) {
+      const dataValue = _.get(this, attrName);
+      if (!dataValue) {
+        return null;
+      }
+      // 如果是数组直接返回
+      if (Array.isArray(dataValue)) {
+        return dataValue;
+      }
+
+      throw new CommonException(Exceptions.RUN_GET_COND_OR_DATA_JSONOBJECT, attrName);
+    }
+    throw new CommonException(Exceptions.RUN_GET_COND_OR_DATA_JSONOBJECT, attrName);
+  }
+
   /**
    * 获取基本数据类型
    * @param attrName

package/src/libs/crud-pro/models/ResModel.ts

@@ -3,17 +3,23 @@ interface ResModelAffected {
   affectedRows: number;
 }
 
+
+// 单条数据对象
+type ResModelRowEntity = Record<string, any>;
+
+
 interface ResModelStandard {
-  row?: any;
-  rows?: any[];
+  row?: ResModelRowEntity;
+  rows?: ResModelRowEntity[];
   total_count?: number;
+  is_exist?: boolean;
   affected?: ResModelAffected;
   insert_affected?: ResModelAffected;
   update_affected?: ResModelAffected;
 }
 
 interface ResModelPageQuery {
-  rows: any[];
+  rows: ResModelRowEntity[];
   total_count: number;
 }
 
@@ -21,4 +27,4 @@ type ResModelFlexible = ResModelStandard & {
   [key: string]: any;
 };
 
-export { ResModelAffected, ResModelStandard, ResModelFlexible, ResModelPageQuery };
+export { ResModelAffected, ResModelStandard, ResModelFlexible, ResModelPageQuery, ResModelRowEntity };

package/src/libs/crud-pro/models/ServiceHub.ts

@@ -29,4 +29,6 @@ export interface ICurdProServiceHub {
   executeFuncCfg(tmpFunCfg: IFuncCfgModel, exeFunCtx: FuncContext): string;
 
   getTableMeta(query: ITableMetaQuery): Promise<ITableMeta>;
+
+  convertDataTypeByTableMeta(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void>;
 }

package/src/libs/crud-pro/models/keys.ts

@@ -57,8 +57,10 @@ export enum KeysOfSimpleSQL {
   SIMPLE_QUERY_ONE = 'SIMPLE_QUERY_ONE', //只查询一条 select * from xx where @condition limit 1,
   SIMPLE_QUERY_PAGE = 'SIMPLE_QUERY_PAGE', //分页查询 select * from xx where @condition limit 100 offset 100,
   SIMPLE_QUERY_COUNT = 'SIMPLE_QUERY_COUNT', //查询数量 select count(0) as totalCount from xx where @condition,
+  SIMPLE_QUERY_EXIST = 'SIMPLE_QUERY_EXIST', //判断一个元素是否存在
   SIMPLE_UPDATE = 'SIMPLE_UPDATE', // update xx set @data where @condition limit 1
   SIMPLE_INSERT = 'SIMPLE_INSERT', // insert into xx values @datas
+  SIMPLE_BATCH_INSERT = 'SIMPLE_BATCH_INSERT', // 批量插入 insert into xx values (...),(...),(...)
   SIMPLE_DELETE = 'SIMPLE_DELETE', // delete from  xx values where @condition limit 1
   SIMPLE_INSERT_ON_DUPLICATE_UPDATE = 'SIMPLE_INSERT_ON_DUPLICATE_UPDATE',
   SIMPLE_INSERT_OR_UPDATE = 'SIMPLE_INSERT_OR_UPDATE',
@@ -70,6 +72,7 @@ export enum KeysOfSqlResPicker {
   RESULT_FIRST_ROW = 'RESULT_FIRST_ROW', // $ResultSet[0]， 只取第一行的数据返回。返回JSONObject
   RESULT_TOTAL_COUNT = 'RESULT_TOTAL_COUNT', // $ResultSet[0].total_count ， 只取第一行的的total_count。返回long
   RESULT_ONE_VALUE = 'RESULT_ONE_VALUE', //   $ResultSet[0].total_count ， 只取第一行的的total_count。返回long
+  RESULT_IS_EXIST = 'RESULT_IS_EXIST', //   返回boolean
 }
 
 export const KeysOfCustomSQL = {
@@ -82,6 +85,8 @@ export const KeysOfCustomSQL = {
   SQL_AS_UPDATE: '@@asUpdate:', // @@asUpdate:data,  @@asWhere:data_zhangsan
   SQL_AS_INSERT_KEYS: '@@asInsertKeys:', // @@asInsertKeys:data,  @@asInsertKeys:data_zhangsan
   SQL_AS_INSERT_VALUES: '@@asInsertValues:', // @@asInsertValues:data,  @@asInsertValues:data_zhangsan
+  SQL_AS_BATCH_INSERT_KEYS: '@@asBatchInsertKeys:', // 批量插入：列名部分，取第一条数据的keys
+  SQL_AS_BATCH_INSERT_VALUES: '@@asBatchInsertValues:', // 批量插入：值部分，生成 (?,?,?),(?,?),...
 
   // 从Req中取值：单独取Data中的某个字段：获取单个值。
   SQL_GET_DATA_ATTR_START: '@@data', // // select * from fa_lang_faq where id = @@data.id

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 };