midway-fatcms 0.0.7 → 0.0.9

package/src/configuration.ts

@@ -15,6 +15,8 @@ import { GlobalMiddleware } from './middleware/global.middleware';
 import { ForbiddenMiddleware } from './middleware/forbidden.middleware';
 import { SCHEDULE_QUEUE, ANONYMOUS_CONTEXT, INNER_SCHEDULE_INTERVAL } from './schedule';
 import { privateAES } from './libs/utils/crypto-utils';
+import { initTableMetaCachePublishClient, initTableMetaCacheSubscriber } from './service/TableMetaCacheRedisSubscriber';
+import { RedisService } from '@midwayjs/redis';
 
 @Configuration({
   // namespace: 'fatcms',
@@ -65,6 +67,11 @@ export class ContainerLifeCycle {
      */
     ANONYMOUS_CONTEXT.setApp(this.app);
 
+    /**
+     * 初始化表元数据缓存 Redis 广播
+     */
+    await this.initTableMetaCacheRedis();
+
     /**
      * 启动定时任务
      */
@@ -78,6 +85,26 @@ export class ContainerLifeCycle {
     // this.app.useFilter([NotFoundFilter, DefaultErrorFilter]);
   }
 
+  /**
+   * 初始化表元数据缓存的 Redis Pub/Sub 广播
+   *
+   * - 发布客户端：复用已有的 RedisService 实例
+   * - 订阅客户端：通过 duplicate() 创建独立连接
+   *
+   * 集群部署时，任意节点调用 clearTableMetaCacheWithBroadcast()
+   * 会通过 Redis 广播通知所有节点清空本地缓存。
+   */
+  private async initTableMetaCacheRedis() {
+    try {
+      const redisService = await this.app.getApplicationContext().getAsync(RedisService);
+      initTableMetaCachePublishClient(redisService);
+      initTableMetaCacheSubscriber(redisService);
+    } catch (e) {
+      // Redis 未配置或不可用时，降级为单节点模式（仅清空本地缓存）
+      this.app.getLogger().warn('ContainerLifeCycle ==> initTableMetaCacheRedis Redis不可用，降级为单节点模式:', e.message);
+    }
+  }
+
   private async startScheduleOnReady() {
     const logger = this.app.getLogger();
     const config = this.app.getConfig();

package/src/controller/base/BaseApiController.ts

@@ -122,11 +122,6 @@ export class BaseApiController extends BaseService {
   }
 
 
-  protected get sysDBUtil() {
-    const { SystemDbName, SystemDbType } = GLOBAL_STATIC_CONFIG.getConfig();
-    return this.curdMixService.getBbUtil(SystemDbName, SystemDbType);
-  }
-
   private addAccountBasicInfoCfgModel(cfgModel: IRequestCfgModel) {
     let columnsRelation = cfgModel.columnsRelation;
     if (!columnsRelation) {

package/src/controller/gateway/DocGatewayController.ts

@@ -122,7 +122,7 @@ export class DocGatewayController extends BaseApiController {
         condition: {
           doc_lib_id: parseInt(docLibId),
           doc_category_code: {
-            $notNull: '',
+            $notNull: true,
           },
         },
       },

package/src/controller/helpers.controller.ts

@@ -7,6 +7,7 @@ import { createUniqueId } from '@/libs/utils/functions';
 import { privateAES } from '@/libs/utils/crypto-utils';
 import { CommonResult } from '@/libs/utils/common-dto';
 import {SystemRoleCode} from "@/models/SystemPerm";
+import { clearTableMetaCacheWithBroadcast } from '@/service/TableMetaCacheRedisSubscriber';
 
 // http://127.0.0.1:7002/ns/api/helpers/getApiScript?prefix=/ns/api/manage
 // http://127.0.0.1:7002/ns/api/helpers/getApiScript
@@ -145,6 +146,20 @@ export class HelpersApi {
     });
   }
 
+  /**
+   * 工具函数: 清空表元数据缓存（集群广播）
+   * 清空本节点缓存，并通过 Redis Pub/Sub 广播通知集群中其他节点。
+   * 清空后，下次请求会自动从数据库重新加载（懒加载刷新）。
+   */
+  @Get('/clearTableMetaCache')
+  async clearTableMetaCacheApi() {
+    const stats = clearTableMetaCacheWithBroadcast();
+    return CommonResult.successRes({
+      message: '表元数据缓存已清空（已广播集群）',
+      beforeClear: stats,
+    });
+  }
+
   private checkLocalPermissionEnv() {
     //是否是开发者
    const isDevelopUser = (): boolean=> {

package/src/controller/manage/CrudStandardDesignApi.ts

@@ -4,6 +4,7 @@ import { parseCreateSqlToTitleMap, parseTableFieldTitleFromComment } from '@/lib
 import { checkPermission } from '@/middleware/permission.middleware';
 import { SystemFuncCode } from '@/models/SystemPerm';
 import { KeyOfCrudTypes, KeysOfSimpleSQL, SqlDbType } from '@/libs/crud-pro/models/keys';
+import { ExecuteSQLRowsResult } from '@/libs/crud-pro/interfaces';
 import { SystemTables } from '@/models/SystemTables';
 import { CommonException } from '@/libs/crud-pro/exceptions';
 import { parseDatabaseName, toDatabaseNameStr } from '@/libs/crud-pro/utils/DatabaseName';
@@ -192,7 +193,7 @@ export class CrudStandardDesignApi extends BaseApiController {
       sqlDbType: dbType,
       crudType: KeyOfCrudTypes.SYS_QUERY,
       executeSqlArgs: [],
-    });
+    }) as ExecuteSQLRowsResult;
 
     const fields = columnArray.map(columnObj => {
       const { column_name, is_nullable, column_default, data_type, is_identity, column_description, ...others } = columnObj;
@@ -242,7 +243,7 @@ export class CrudStandardDesignApi extends BaseApiController {
       sqlDbType: dbType,
       crudType: KeyOfCrudTypes.SYS_QUERY,
       executeSqlArgs: [schemaname, tableName],
-    });
+    }) as ExecuteSQLRowsResult;
 
     const commentMap = await this.getTableFieldsCommentsMapOfPostgreSQL(dbName, schemaname, tableName);
 
@@ -309,7 +310,7 @@ export class CrudStandardDesignApi extends BaseApiController {
       sqlDbType: dbType,
       crudType: KeyOfCrudTypes.SYS_QUERY,
       executeSqlArgs: [schemaname, tableName],
-    });
+    }) as ExecuteSQLRowsResult;
 
     const map: any = {};
     commentArray.forEach(commentObj => {

package/src/controller/manage/FlowConfigManageApi.ts

@@ -46,7 +46,8 @@ export class FlowConfigManageApi extends BaseApiController {
   @Post('/updateFlowConfig')
   async updateFlowConfig() {
     const body: IRequestModel = this.ctx.request.body as any;
-    const { flow_code, flow_version } = body.condition;
+    const flow_code = String(body.condition.flow_code);
+    const flow_version = Number(body.condition.flow_version);
 
     await this.flowConfigService.remove_cache_flow_config_one(flow_code, flow_version);
 
@@ -63,7 +64,8 @@ export class FlowConfigManageApi extends BaseApiController {
   @Post('/deleteFlowConfig')
   async deleteFlowConfig() {
     const body: IRequestModel = this.ctx.request.body as any;
-    const { flow_code, flow_version } = body.condition;
+    const flow_code = String(body.condition.flow_code);
+    const flow_version = Number(body.condition.flow_version);
     await this.flowConfigService.remove_cache_flow_config_one(flow_code, flow_version);
 
     return this.executeSysSimpleSQL(FLOW_TABLES.flow_config, KeysOfSimpleSQL.SIMPLE_DELETE, {

package/src/controller/manage/SysConfigMangeApi.ts

@@ -61,7 +61,12 @@ export class SysConfigMangeApi extends BaseApiController {
       return CommonResult.errorRes('id不能为空');
     }
 
-    const sysConfig = await this.curdMixService.getBbUtil(SystemDbName, SystemDbType).getUniqueOne({ condition: body.condition }, SystemTables.sys_configs);
+    const sysConfigRes = await this.curdMixService.getQuickCrud({
+      sqlDatabase: SystemDbName,
+      sqlDbType: SystemDbType,
+      sqlTable: SystemTables.sys_configs,
+    }).findOne({ condition: body.condition });
+    const sysConfig = sysConfigRes.row;
     if (!sysConfig) {
       return CommonResult.errorRes('配置项不存在');
     }

package/src/controller/manage/UserAccountManageApi.ts

@@ -55,9 +55,14 @@ export class UserAccountManageApi extends BaseApiController {
       return CommonResult.errorRes('id不能为空');
     }
 
-    const userAccountInfo = await this.curdMixService.getBbUtil(SystemDbName, SystemDbType).getUniqueOne({
+    const userAccountInfoRes = await this.curdMixService.getQuickCrud({
+      sqlDatabase: SystemDbName,
+      sqlDbType: SystemDbType,
+      sqlTable: SystemTables.sys_user_account,
+    }).findUniqueOne({
       condition: body.condition
-    }, SystemTables.sys_user_account);
+    });
+    const userAccountInfo = userAccountInfoRes.row;
 
     if (!userAccountInfo) {
       return CommonResult.errorRes('用户信息不存在');

package/src/index.ts

@@ -70,7 +70,7 @@ export * from './service/curd/CurdMixByWorkbenchService';
 export * from './service/curd/CurdMixService';
 export * from './service/curd/CurdMixUtils';
 export * from './service/curd/CurdProService';
-export * from './service/curd/CrudProQuick';
+export * from './libs/crud-pro-quick';
 export * from './service/flow/FlowConfigService';
 export * from './service/flow/FlowInstanceService';
 export * from './service/flow/FlowInstanceCrudService';
@@ -87,7 +87,6 @@ export * from './models/contextLogger';
 export * from './models/devops';
 export * from './models/SystemTables';
 export * from './models/AsyncTaskModel';
-export * from './models/StandardColumns';
 
 export * from './schedule/index';
 
@@ -114,5 +113,6 @@ export * from './libs/crud-pro/models/RequestCfgModel';
 export * from './libs/crud-pro/models/SqlSegArg';
 export * from './libs/crud-pro/models/ResModel';
 export * from './libs/crud-sharding/index';
+export * from './libs/crud-pro-quick/index';
 
 export * from './libs/global-config/global-config';

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

@@ -1,4 +1,4 @@
-import { ICrudProCfg, ILogger, IRequestCfgModel, IRequestModel, ISqlCfgModel, ITableListResult, ITableNamesOptions, ITableNamesQuery, IVisitor } from './interfaces';
+import { ICrudProCfg, ILogger, IRequestCfgModel, IRequestModel, ISqlCfgModel, ITableListResult, ITableMetaQuery, ITableNamesOptions, ITableNamesQuery, IVisitor, ExecuteSQLResult } from './interfaces';
 import { ExecuteContext } from './models/ExecuteContext';
 import { RequestModel } from './models/RequestModel';
 import { CurdProServiceHub } from './services/CurdProServiceHub';
@@ -13,11 +13,44 @@ class CrudPro {
   private readonly executeContext: ExecuteContext;
   private readonly serviceHub: CurdProServiceHub;
 
+  /** 标记是否已被使用（防止重复使用导致状态污染） */
+  private _isUsed: boolean = false;
+  /** 标记是否正在执行中（防止并发调用） */
+  private _isExecuting: boolean = false;
+
   constructor() {
     this.executeContext = new ExecuteContext();
     this.serviceHub = new CurdProServiceHub(this.executeContext);
   }
 
+  /**
+   * 检查是否可以开始执行
+   * @throws 如果已使用或正在执行中则抛出异常
+   */
+  private checkAndMarkExecuting(): void {
+    if (this._isUsed) {
+      throw new Error(
+        '[CrudPro] 此实例已被使用，不能重复使用。' +
+        '每次操作请创建新的 CrudPro 实例，可通过 curdProService.getCrudPro() 或工厂函数获取。'
+      );
+    }
+    if (this._isExecuting) {
+      throw new Error(
+        '[CrudPro] 此实例正在执行中，不能并发调用。' +
+        '请等待当前操作完成后再进行下一次调用，或创建新的实例。'
+      );
+    }
+    this._isExecuting = true;
+  }
+
+  /**
+   * 标记执行完成
+   */
+  private markExecutionComplete(): void {
+    this._isExecuting = false;
+    this._isUsed = true;
+  }
+
   // 必填
   set transaction(transaction: Transaction) {
     this.executeContext.setTransaction(transaction);
@@ -30,6 +63,10 @@ class CrudPro {
   set visitor(visitor: IVisitor) {
     this.executeContext.setVisitor(visitor);
   }
+  // 必填
+  getVisitor() {
+    return this.executeContext.getVisitor();
+  }
 
   set contextFunc(contextFunc: IExecuteContextFunc) {
     contextFunc.setExecuteContext(this.executeContext);
@@ -43,8 +80,11 @@ class CrudPro {
   /**
    * 直接执行一个SQL
    * @param sqlCfgModel
+   * @returns 返回未被包装的数据库原始结果（根据 resPicker 配置返回不同类型，无 {code, data, message} 包装层）
    */
-  public async executeSQL(sqlCfgModel: ISqlCfgModel): Promise<any> {
+  public async executeSQL(sqlCfgModel: ISqlCfgModel): Promise<ExecuteSQLResult> {
+    this.checkAndMarkExecuting();
+
     const RES_NAME = 'executeResult';
 
     const sqlCfgModel2 = {
@@ -64,8 +104,12 @@ class CrudPro {
       sqlCfgList: [sqlCfgModel2],
     };
 
-    const ss = await this.executeCrudByCfg({}, cfgModel);
-    return ss.getResModelItem(RES_NAME);
+    try {
+      const ss = await this.executeCrudByCfgInternal({}, cfgModel);
+      return ss.getResModelItem(RES_NAME);
+    } finally {
+      this.markExecutionComplete();
+    }
   }
 
   /**
@@ -87,6 +131,20 @@ class CrudPro {
    * @param cfgJson
    */
   public async executeCrudByCfg(reqJson: IRequestModel, cfgJson: IRequestCfgModel): Promise<ExecuteContext> {
+    this.checkAndMarkExecuting();
+    try {
+      return await this.executeCrudByCfgInternal(reqJson, cfgJson);
+    } finally {
+      this.markExecutionComplete();
+    }
+  }
+
+  /**
+   * 内部执行方法（不含检查逻辑，供内部调用）
+   * @param reqJson
+   * @param cfgJson
+   */
+  private async executeCrudByCfgInternal(reqJson: IRequestModel, cfgJson: IRequestCfgModel): Promise<ExecuteContext> {
     const logger = this.executeContext.getLogger();
     logger.info('CurdPro executeCrudByCfg', cfgJson);
 
@@ -107,12 +165,16 @@ class CrudPro {
     exeCtx.setReqModel(reqModel);
     exeCtx.setCfgModel(cfgModel);
 
+    // insertOrUpdate 参数校验
+    this.validateParamsIfNeeded(reqModel, cfgModel);
+
     // 如果是 sqlSimpleName模式的 update/insert，则需要将 reqJson.data 部分根据真实的表结构进行过滤
     await this.filterDataByTableMetaIfNeeded(reqModel, cfgModel);
 
-    // 根据表结构字段类型，自动转换数据格式（如 PostgreSQL ARRAY 字段）
+    //插入和更新时： 根据表结构字段类型，自动转换 data 数据格式（如 PostgreSQL ARRAY 字段）
     await this.convertDataFieldTypeIfNeeded(reqModel, cfgModel);
-
+    //查询时：根据表结构字段类型，自动转换 condition 数据格式（防止数据库隐式类型转换导致索引失效）
+    await this.convertConditionTypeIfNeeded(reqModel, cfgModel);
     // 参数校验
     this.serviceHub.validateDataType(cfgModel, reqModel);
     this.serviceHub.validateByAllow(cfgModel, reqModel);
@@ -156,6 +218,19 @@ class CrudPro {
     return this.serviceHub.getAllTableInfos(query, options);
   }
 
+  /**
+   * 获取表的主键列名列表
+   *
+   * 复用 CrudProTableMetaService 的 getTableMeta 缓存，
+   * 从 columnDetails 中筛选 isPrimaryKey 的列。
+   *
+   * @param query 表元数据查询参数
+   * @returns 主键列名数组
+   */
+  public async getPrimaryKeyColumns(query: ITableMetaQuery): Promise<string[]> {
+    return this.serviceHub.getPrimaryKeyColumns(query);
+  }
+
   /**
    * 如果是 INSERT/UPDATE 操作（sqlSimpleName 模式），根据真实表结构过滤 reqModel.data 中的字段
    * 避免传入不存在的字段导致 SQL 执行报错
@@ -208,6 +283,48 @@ class CrudPro {
     reqModel.data = filteredData;
   }
 
+  /**
+   * 校验特定操作的必填参数
+   *
+   * - insertOrUpdate 和 update：condition 和 data 均为必填
+   * - insertOnDuplicateUpdate 和 insert：只有data 为必填
+   * @param reqModel 请求模型
+   * @param cfgModel 配置模型
+   * @throws CommonException 如果缺少必填参数
+   */
+  private validateParamsIfNeeded(reqModel: RequestModel, cfgModel: RequestCfgModel): void {
+    // insertOrUpdate 和 update：condition 和 data 均为必填
+    if (cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE ||
+        cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_UPDATE) {
+      if (!reqModel.condition || Object.keys(reqModel.condition).length === 0) {
+        throw new CommonException(
+          Exceptions.INSERT_OR_UPDATE_CONDITION_EMPTY,
+          '[CrudPro] insertOrUpdate/update 操作的 condition 不能为空。' +
+          'condition 用于判断记录是否存在或定位更新目标。'
+        );
+      }
+      if (!reqModel.data || Object.keys(reqModel.data as Record<string, any>).length === 0) {
+        throw new CommonException(
+          Exceptions.INSERT_OR_UPDATE_DATA_EMPTY,
+          '[CrudPro] insertOrUpdate/update 操作的 data 不能为空。' +
+          'data 用于指定插入或更新的内容。'
+        );
+      }
+    }
+
+    // insertOnDuplicateUpdate 和 insert：只有 data 为必填
+    if (cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE ||
+        cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_INSERT) {
+      if (!reqModel.data || Object.keys(reqModel.data as Record<string, any>).length === 0) {
+        throw new CommonException(
+          Exceptions.INSERT_OR_DUPLICATE_UPDATE_DATA_EMPTY,
+          '[CrudPro] insert/insertOnDuplicateUpdate 操作的 data 不能为空。' +
+          'data 用于指定插入或更新的内容。'
+        );
+      }
+    }
+  }
+
   /**
    * 判断 sqlSimpleName 是否为 INSERT/UPDATE 类型
    * @param sqlSimpleName 简单 SQL 名称
@@ -224,7 +341,7 @@ class CrudPro {
   }
 
   /**
-   * 根据表结构字段类型，自动转换数据格式
+   * 根据表结构字段类型，自动转换 data 数据格式
    * 例如：PostgreSQL 的 ARRAY 类型字段，需要将 JSON 数组转为 PG 数组字面量格式
    * @param reqModel 请求模型
    * @param cfgModel 配置模型
@@ -233,6 +350,16 @@ class CrudPro {
     await this.serviceHub.convertDataTypeByTableMeta(reqModel, cfgModel);
   }
 
+  /**
+   * 查询时：根据表结构字段类型，自动转换 condition 数据格式
+   * 防止数据库隐式类型转换导致索引失效（如 WHERE int_col = '123' 导致索引无法命中）
+   * @param reqModel 请求模型
+   * @param cfgModel 配置模型
+   */
+  private async convertConditionTypeIfNeeded(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void> {
+    await this.serviceHub.convertConditionTypeByTableMeta(reqModel, cfgModel);
+  }
+
   private async executeSQLList() {
     try {
       await this.serviceHub.executeSqlCfgModels();

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

@@ -61,6 +61,13 @@ export enum Exceptions {
   DATA_GET_DATA_EMPTY_ON_INSERT_VALUES = 'DATA_GET_DATA_EMPTY_ON_INSERT_VALUES',
   BATCH_INSERT_KEYS_MISMATCH = 'BATCH_INSERT_KEYS_MISMATCH', // 批量插入时字段不一致
 
+  /**
+   * insertOrUpdate 参数缺失
+   */
+  INSERT_OR_UPDATE_CONDITION_EMPTY = 'INSERT_OR_UPDATE_CONDITION_EMPTY', // insertOrUpdate/update 的 condition 不能为空
+  INSERT_OR_UPDATE_DATA_EMPTY = 'INSERT_OR_UPDATE_DATA_EMPTY', // insertOrUpdate/update 的 data 不能为空
+  INSERT_OR_DUPLICATE_UPDATE_DATA_EMPTY = 'INSERT_ON_DUPLICATE_UPDATE_DATA_EMPTY', // insertOnDuplicateUpdate/insert 的 data 不能为空
+
   /**
    * 请求的Method字段为空
    */
@@ -85,6 +92,7 @@ export enum Exceptions {
   RUN_PICK_ERR_VISITOR_FIELD_NULL = 'RUN_PICK_ERR_VISITOR_FIELD_NULL',
   RUN_EXECUTE_VALIDATE = 'RUN_EXECUTE_VALIDATE',
   RUN_FUNCTION_NOT_FOUND = 'RUN_FUNCTION_NOT_FOUND',
+  MORE_THAN_ONE_RECORDS_FOUND = 'MORE_THAN_ONE_RECORDS_FOUND',
 
   /**
    * 参数校验错误

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

@@ -17,6 +17,7 @@ export interface ITableColumn {
   type: string; // 数据类型
   isNullable: boolean; // 是否可空
   isPrimaryKey?: boolean; // 是否主键
+  isIdentity?: boolean; // 是否自增列（SQL Server）
   defaultValue?: any; // 默认值
   maxLength?: number; // 最大长度
   comment?: string; // 字段注释
@@ -53,7 +54,7 @@ export interface IPoolConnectionClient {
 export interface IRequestModel {
   method?: string;
   columns?: string | string[]; // "columns": "id,name,age,sex,addr",
-  condition?: Record<string, any>; // 拼接查询条件
+  condition?: IRequestCondition; // 拼接查询条件
   data?: Record<string, any> | Record<string, any>[]; // 单条或批量插入/更新的数据部分
   orderBy?: string | IOrderByItem[];
   limit?: number;
@@ -64,23 +65,57 @@ export interface IRequestModel {
 
 type IBasicType = boolean | string | number;
 
+/**
+ * 比较操作符条件
+ * 支持 MongoDB 风格的所有查询操作符
+ */
 export interface ICompareCondition {
-  $gt?: IBasicType;
-  $gte?: IBasicType;
-  $lt?: IBasicType;
-  $lte?: IBasicType;
-  $ne?: IBasicType;
-
-  $in?: IRequestCondition[];
-  $nin?: IRequestCondition[];
-  $like?: IBasicType;
-  $match?: IBasicType;
-  $matchBool?: IBasicType;
-  $range?: number[];
+  // 比较操作符
+  $ne?: IBasicType;                    // 不等于
+  $lt?: IBasicType;                    // 小于
+  $lte?: IBasicType;                   // 小于或等于
+  $gt?: IBasicType;                    // 大于
+  $gte?: IBasicType;                   // 大于或等于
+
+  // 集合操作符
+  $in?: IBasicType[];                  // 在集合中
+  $nin?: IBasicType[];                 // 不在集合中
+
+  // 范围操作符
+  $range?: [number, number];           // 范围查询 [min, max]
+
+  // 模糊匹配操作符
+  $like?: string;                      // 前缀匹配 A%
+  $notLike?: string;                   // 非前缀匹配
+  $likeInclude?: string;               // 包含匹配 %A%
+  $notLikeInclude?: string;            // 不包含匹配
+
+  // 全文索引操作符
+  $match?: string;                     // MySQL 全文索引
+  $matchBool?: string | boolean;       // MySQL 布尔全文索引
+
+  // NULL 判断操作符
+  $null?: boolean;                     // IS NULL
+  $notNull?: boolean;                  // IS NOT NULL
+
+  // JSON 操作符
+  $jsonArrayContains?: string;         // JSON 数组包含
+}
+
+/**
+ * 逻辑操作符条件
+ */
+export interface ILogicalCondition {
+  $or?: IRequestCondition[];           // 逻辑或
+  $and?: IRequestCondition[];          // 逻辑与
 }
 
-export interface IRequestCondition extends Record<string, any>, ICompareCondition {
-  $or?: IRequestCondition[];
+/**
+ * 查询条件类型
+ * 支持字段值直接匹配或比较操作符
+ * 支持 $or, $and 逻辑组合
+ */
+export interface IRequestCondition extends Record<string, IBasicType | ICompareCondition | ILogicalCondition | IRequestCondition[] | undefined>, ILogicalCondition {
 }
 
 /**
@@ -163,6 +198,67 @@ export interface ISqlCfgModel extends IBaseCfgModel {
   crudType?: string;
 }
 
+/**
+ * executeSQL 的返回结果类型说明（未被包装的直接结果）
+ *
+ * 注意：executeSQL 返回的是数据库查询的原始结果，没有 {code, data, message} 包装层。
+ * 返回类型取决于 resPicker 配置，请根据实际 SQL 类型选择合适的类型断言。
+ *
+ * 使用示例：
+ *   // 查询列表 - 返回数组
+ *   const rows = await executeSQL({ executeSql: 'SELECT * FROM users', resPicker: KeysOfSqlResPicker.RESULT_ROWS }) as ExecuteSQLRowResult<User>;
+ *
+ *   // 查询单行 - 返回对象或null
+ *   const user = await executeSQL({ executeSql: 'SELECT * FROM users WHERE id=?', executeSqlArgs: [1], resPicker: KeysOfSqlResPicker.RESULT_FIRST_ROW }) as ExecuteSQLSingleResult<User>;
+ *
+ *   // 查询总数 - 返回数字
+ *   const count = await executeSQL({ executeSql: 'SELECT COUNT(*) as total_count FROM users', resPicker: KeysOfSqlResPicker.RESULT_TOTAL_COUNT }) as ExecuteSQLCountResult;
+ *
+ *   // 判断存在 - 返回布尔
+ *   const exists = await executeSQL({ executeSql: 'SELECT 1 as is_exist FROM users WHERE id=?', executeSqlArgs: [1], resPicker: KeysOfSqlResPicker.RESULT_IS_EXIST }) as ExecuteSQLExistResult;
+ *
+ *   // 增删改操作 - 返回受影响行数信息
+ *   const result = await executeSQL({ executeSql: 'INSERT INTO users(name) VALUES(?)', executeSqlArgs: ['张三'], resPicker: KeysOfSqlResPicker.UPDATE_RESULT }) as ExecuteSQLUpdateResult;
+ */
+
+/** 查询多行时的返回类型（默认情况）：原始数据行数组，无包装 */
+export type ExecuteSQLRowsResult<T = Record<string, any>> = T[];
+
+/** 查询单行时的返回类型：首行对象或null，无包装 */
+export type ExecuteSQLSingleResult<T = Record<string, any>> = T | null;
+
+/** 查询数量时的返回类型：数字，无包装 */
+export type ExecuteSQLCountResult = number;
+
+/** 判断存在时的返回类型：布尔值，无包装 */
+export type ExecuteSQLExistResult = boolean;
+
+/** 增删改操作时的返回类型：包含 insertId 和 affectedRows，无包装 */
+export interface ExecuteSQLUpdateResult {
+  /** 插入记录的自增ID（仅INSERT操作有效） */
+  insertId: any;
+  /** 受影响的行数 */
+  affectedRows: number;
+}
+
+/**
+ * executeSQL 的通用返回类型（未被包装的直接结果）
+ * 根据 resPicker 的不同配置，实际返回类型可能是：
+ * - ExecuteSQLRowResult<T> : 多行数据（默认）
+ * - ExecuteSQLSingleResult<T> : 单行数据或null
+ * - ExecuteSQLCountResult : 数字
+ * - ExecuteSQLExistResult : 布尔值
+ * - ExecuteSQLUpdateResult : 增删改结果
+ *
+ * 警告：此类型为联合类型，使用时建议根据实际 resPicker 进行类型断言以获得精确类型提示
+ */
+export type ExecuteSQLResult<T = Record<string, any>> =
+  | ExecuteSQLRowsResult<T>
+  | ExecuteSQLSingleResult<T>
+  | ExecuteSQLCountResult
+  | ExecuteSQLExistResult
+  | ExecuteSQLUpdateResult;
+
 /**
  * 自定义校验函数。如果不正确请抛出异常。{code:'xxx',message:'xxx'}
  */