midway-fatcms 0.0.4 → 0.0.6

package/src/libs/crud-sharding/ShardingUtils.ts

@@ -0,0 +1,84 @@
+import { ShardingType } from './ShardingConfig';
+
+/**
+ * 时间粒度类型
+ */
+export type ShardingTimeGranularity = 'year' | 'month' | 'day';
+
+/**
+ * 将 ShardingType 转换为时间粒度
+ */
+export function shardingTypeToGranularity(type: ShardingType): ShardingTimeGranularity | undefined {
+  switch (type) {
+    case ShardingType.YEAR:
+      return 'year';
+    case ShardingType.MONTH:
+      return 'month';
+    case ShardingType.DAY:
+      return 'day';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * 获取日期对应的时间后缀
+ *
+ * @param date 日期
+ * @param granularity 时间粒度（year/month/day）
+ * @returns 时间后缀字符串
+ *
+ * @example
+ * getTimeSuffix(new Date('2024-03-15'), 'year')   // "2024"
+ * getTimeSuffix(new Date('2024-03-15'), 'month')  // "202403"
+ * getTimeSuffix(new Date('2024-03-15'), 'day')    // "20240315"
+ */
+export function getTimeSuffix(date: Date, granularity: ShardingTimeGranularity): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+
+  switch (granularity) {
+    case 'year':
+      return String(year);
+    case 'month':
+      return `${year}${month}`;
+    case 'day':
+      return `${year}${month}${day}`;
+  }
+}
+
+/**
+ * 获取当前时间周期的后缀（用于识别"当前表"）
+ *
+ * @param shardingType 分表类型
+ * @returns 当前时间后缀，非时间分表返回空字符串
+ */
+export function getCurrentSuffix(shardingType: ShardingType | undefined): string {
+  const granularity = shardingTypeToGranularity(shardingType);
+  if (!granularity) {
+    return '';
+  }
+  return getTimeSuffix(new Date(), granularity);
+}
+
+/**
+ * 判断表名是否为当前时间周期的表
+ *
+ * @param tableName 完整表名（如 t_order_202404）
+ * @param baseTable 基础表名（如 t_order）
+ * @param shardingType 分表类型
+ * @returns 是否为当前表
+ */
+export function isCurrentTable(
+  tableName: string,
+  baseTable: string,
+  shardingType: ShardingType | undefined
+): boolean {
+  const currentSuffix = getCurrentSuffix(shardingType);
+  if (!currentSuffix) {
+    return false;
+  }
+  const expectedTableName = `${baseTable}_${currentSuffix}`;
+  return tableName === expectedTableName;
+}

package/src/libs/crud-sharding/index.ts

@@ -0,0 +1,64 @@
+/**
+ * 分表 CRUD 功能模块
+ *
+ * 在 CrudPro 之上封装分表功能，提供透明的分表路由和多表查询结果合并能力。
+ *
+ * 支持的分表策略：
+ * - YEAR: 按年分表，如 order_2024, order_2025
+ * - MONTH: 按月分表，如 order_202401, order_202402
+ * - DAY: 按日分表，如 order_20240101
+ * - RANGE: 按范围分表，如 user_0 ~ user_99
+ * - HASH: 按哈希分表，如 order_01 ~ order_16
+ * - CUSTOM: 自定义分表规则
+ *
+ * @example
+ * import { ShardingCrudPro, ShardingType } from '@/libs/crud-sharding';
+ *
+ * // 创建分表操作器
+ * const sharding = new ShardingCrudPro(crudPro, {
+ *   type: ShardingType.MONTH,
+ *   baseTable: 't_order',
+ *   timeColumn: 'created_at',
+ * });
+ *
+ * // 插入数据（自动路由）
+ * await sharding.insert({
+ *   data: { order_id: '001', amount: 100, created_at: '2024-03-15' },
+ * });
+ *
+ * // 分页查询（自动合并多表结果）
+ * const result = await sharding.queryPage({
+ *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
+ *   pageNo: 1,
+ *   pageSize: 10,
+ * });
+ */
+
+// 核心类
+export { ShardingCrudPro } from './ShardingCrudPro';
+export { ShardingRouter } from './ShardingRouter';
+export { ShardingMerger } from './ShardingMerger';
+
+// 配置和类型
+export { ShardingType } from './ShardingConfig';
+export type {
+  IShardingConfig,
+  IShardingRouterContext,
+  IShardingRouterFunc,
+  IShardingTimeRange,
+  IShardingTableCreateOptions,
+  IShardingTableCreateResult,
+  IShardingCountCacheConfig,
+} from './ShardingConfig';
+
+// 结果类型
+export type { IShardingPageQueryResult } from './ShardingMerger';
+export type { IShardingSmartBatchInsertResult } from './ShardingCrudPro';
+
+// 分表创建器
+export { ShardingTableCreator } from './ShardingTableCreator';
+
+// COUNT 缓存
+export { ShardingCountCache, shardingHashCondition } from './ShardingCountCache';
+
+export type { ShardingTimeGranularity } from './ShardingUtils';

package/src/models/StandardColumns.ts

@@ -0,0 +1,76 @@
+/**
+ * 标准表结构字段类型定义
+ * 
+ * 常用标准字段（推荐所有表都包含）：
+ * - deleted_at: 软删除标记，0=未删除，时间戳=已删除
+ * - deleted_by: 删除人ID
+ * - created_by: 创建人ID
+ * - created_at: 创建时间
+ * - modified_by: 最后修改人ID
+ * - modified_at: 最后修改时间
+ * 
+ * 完整标准字段（需要记录详细用户信息时使用）：
+ * - created_account_type: 创建人账号类型
+ * - created_avatar: 创建人头像
+ * - created_nickname: 创建人昵称
+ * - modified_account_type: 修改人账号类型
+ * - modified_avatar: 修改人头像
+ * - modified_nickname: 修改人昵称
+ */
+
+/**
+ * 常用标准表结构字段（6个字段）
+ * 
+ * 推荐所有业务表都包含这些字段：
+ * - deleted_at: 删除时间戳，0=未删除
+ * - deleted_by: 删除人ID
+ * - created_by: 创建人ID
+ * - created_at: 创建时间（毫秒时间戳）
+ * - modified_by: 修改人ID
+ * - modified_at: 修改时间（毫秒时间戳）
+ */
+export interface ICommonStandardColumns {
+  deleted_at?: number;
+  deleted_by?: string;
+  created_by?: string;
+  created_at?: number;
+  modified_by?: string;
+  modified_at?: number;
+}
+
+/**
+ * 完整标准表结构字段（12个字段）
+ * 
+ * 在常用字段基础上增加用户详细信息：
+ * - created_account_type: 创建人账号类型
+ * - created_avatar: 创建人头像URL
+ * - created_nickname: 创建人昵称
+ * - modified_account_type: 修改人账号类型
+ * - modified_avatar: 修改人头像URL
+ * - modified_nickname: 修改人昵称
+ */
+export interface IFullStandardColumns extends ICommonStandardColumns {
+  created_account_type?: string;
+  created_avatar?: string;
+  created_nickname?: string;
+  modified_account_type?: string;
+  modified_avatar?: string;
+  modified_nickname?: string;
+}
+
+/**
+ * 包含常用标准字段的数据模型
+ */
+export type StandardDataModel<T = {}> = T & ICommonStandardColumns;
+
+/**
+ * 包含完整标准字段的数据模型
+ */
+export type FullStandardDataModel<T = {}> = T & IFullStandardColumns;
+
+/**
+ * 未删除查询条件
+ */
+export const NotDeletedCondition: { deleted_at: 0 } = {
+  deleted_at: 0,
+};

package/src/service/FileCenterService.ts

@@ -151,7 +151,7 @@ class FileDB {
     };
 
     const res = await this.curdMixService.executeCrudByCfg({ condition }, cfgModel);
-    return res.getOneObj();
+    return res.getOneObj() as IFileInfo;
   }
 
   async saveFileInfo(fileInfo: IFileInfo) {

package/src/service/SysAppService.ts

@@ -17,12 +17,12 @@ export class SysAppService extends BaseService {
 
   private get sysAppDao() {
     const { SystemDbName, SystemDbType } = GLOBAL_STATIC_CONFIG.getConfig();
-    return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables.sys_app)
+    return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables.sys_app)
   }
 
   private get sysAppPageDao() {
     const { SystemDbName, SystemDbType } = GLOBAL_STATIC_CONFIG.getConfig();
-    return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables.sys_app_page)
+    return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables.sys_app_page)
   }
 
 

package/src/service/SysConfigService.ts

@@ -20,7 +20,7 @@ export class SysConfigService extends BaseService {
 
   private get sysConfigsDao(){
     const { SystemDbName, SystemDbType } = GLOBAL_STATIC_CONFIG.getConfig();
-    return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables.sys_configs)
+    return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables.sys_configs)
   }
 
   async getSysConfigOne(config_code: string): Promise<any> {

package/src/service/SysDictDataService.ts

@@ -17,12 +17,12 @@ export class SysDictDataService extends BaseService {
 
   private get sys_data_dict_item() {
     const { SystemDbName, SystemDbType } = GLOBAL_STATIC_CONFIG.getConfig();
-    return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables.sys_data_dict_item)
+    return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables.sys_data_dict_item)
   }
 
   // private get sys_data_dict(){
   //   const { SystemDbName, SystemDbType } = GLOBAL_STATIC_CONFIG.getConfig();
-  //   return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables.sys_data_dict)
+  //   return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables.sys_data_dict)
   // }
 
 

package/src/service/SysMenuService.ts

@@ -57,13 +57,13 @@ export class SysMenuService extends BaseService {
 
   private get sys_menus_table() {
     const { SystemDbName, SystemDbType } = GLOBAL_STATIC_CONFIG.getConfig();
-    return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables.sys_menus)
+    return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables.sys_menus)
   }
 
 
   /**
    * 获取所有菜单列表
-   * @returns 
+   * @returns
    */
   async getCachedMenusList(): Promise<SysMenus[]> {
     return await this.cacheServiceFactory.getJsonObjectCache({

package/src/service/WorkbenchService.ts

@@ -70,7 +70,7 @@ export class WorkbenchService extends BaseService implements IScheduleService {
           sqlDatabase: SystemDbName,
           sqlDbType: SystemDbType,
         });
-        const listData = res.getResRows();
+        const listData = res.getResRows() as IWorkbenchEntity[];
 
         const domainMap1 = MixinUtils.toMap(listData, (e: any) => e.workbench_domain); // 主域名。其他两个域名。
         const domainMap2 = MixinUtils.toMap(listData, (e: any) => e.workbench_domain2);

package/src/service/anyapi/AnyApiService.ts

@@ -93,7 +93,7 @@ export class AnyApiService extends ApiBaseService {
         updateCfg: {},
       }
     );
-    const obj: ISysAnyApiEntity = res.getOneObj();
+    const obj: ISysAnyApiEntity = res.getOneObj() as ISysAnyApiEntity;
     if (!obj) {
       return null;
     }

package/src/service/asyncTask/AsyncTaskRunnerService.ts

@@ -259,7 +259,7 @@ export class AsyncTaskRunnerService extends BaseService implements IScheduleServ
       }
     );
 
-    const taskList = queryRes.getResRows();
+    const taskList = queryRes.getResRows() as SysAsyncTaskEntity[];
 
     if (taskList.length === 0) {
       return Promise.resolve();

package/src/service/crudstd/CrudStdService.ts

@@ -15,7 +15,6 @@ import { CrudStdRelationService } from './CrudStdRelationService';
 import { ApiBaseService } from '../base/ApiBaseService';
 import { parseDatabaseName } from '@/libs/crud-pro/utils/DatabaseName';
 import { GLOBAL_STATIC_CONFIG } from '@/libs/global-config/global-config';
-import { MixinUtils } from '@/libs/crud-pro/utils/MixinUtils';
 import { SysAppService } from "@/service/SysAppService";
 
 
@@ -141,9 +140,6 @@ export class CrudStdService extends ApiBaseService {
     // 根据用户配置的keepSubmitData字段修改提交的数据
     await this.fixSubmitDataByKeepSubmitData(params, cfgModel, appInfo, { dbType, dbName });
 
-    // 根据表结构的数据类型，修正数据类型
-    await this.fixDataFieldTypeBySqlTableField(params, cfgModel, appInfo, { dbType, dbName });
-
     // 业务系统自定义的修改：查询前的查询条件：cfgModel
     await GLOBAL_STATIC_CONFIG.getConfig().bizUpdateCfgModelForCrudStd(params, cfgModel, appInfo, this.ctx);
 
@@ -394,32 +390,4 @@ export class CrudStdService extends ApiBaseService {
     }
 
   }
-
-
-  private async fixDataFieldTypeBySqlTableField(params: IRequestModel, cfgModel: IRequestCfgModel, appInfo: ICrudStdAppInfoForSettingKey, arg3: { dbType: SqlDbType; dbName: string }) {
-    const tableFields = _.get(appInfo, 'stdCrudCfgObj.tableFields');
-
-    const tableFieldMap = MixinUtils.toMap(tableFields, (e: any) => {
-      return e.fieldIndex;
-    });
-
-    if (arg3.dbType === SqlDbType.postgres) {
-      if (cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_INSERT || cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_UPDATE) {
-        const data = params.data || {};
-        const dataKeys = Object.keys(data);
-        for (let index = 0; index < dataKeys.length; index++) {
-          const dataKey = dataKeys[index];
-          const dataValue = data[dataKey];
-          const fieldInfo = tableFieldMap[dataKey];
-          const fieldType = ('' + _.get(fieldInfo, 'type')).toUpperCase();
-          if (fieldType === 'ARRAY') {
-            const dataValueArray = parseJsonObject(dataValue);
-            if (Array.isArray(dataValueArray)) {
-              data[dataKey] = `{${dataValueArray.map(v => `"${v}"`).join(',')}}`;
-            }
-          }
-        }
-      }
-    }
-  }
 }

package/src/service/curd/CrudProQuick.ts

@@ -2,7 +2,11 @@ import { KeysOfSimpleSQL, SqlDbType } from '@/libs/crud-pro/models/keys';
 import { IRequestCfgModel, IRequestModel, ISqlCfgModel } from '@/libs/crud-pro/interfaces';
 import { IRequestCfgModel2 } from '@/models/bizmodels';
 import { CrudPro } from '@/libs/crud-pro/CrudPro';
-import { ResModelAffected, ResModelPageQuery, ResModelStandard } from '@/libs/crud-pro/models/ResModel';
+import { 
+  ResModelAffected, 
+  ResModelPageQuery, 
+  ResModelStandard
+} from '@/libs/crud-pro/models/ResModel';
 import { fixSoftDelete } from "@/service/curd/fixSoftDelete";
 import { Context } from "@midwayjs/koa";
 
@@ -31,6 +35,11 @@ export class CrudProQuick {
     this.sqlTable = args.sqlTable; // 全局sqlTable为空时，单独调用时就必须传sqlTable参数。
   }
 
+  /**
+   * 设置基础配置模型，合并到实例的 baseCfgModel 中，后续所有 CRUD 操作都会携带这些配置
+   * 例如可以统一设置 maxLimit、sqlSimpleName 等公共参数，避免每次调用都重复传入
+   * @param baseCfgModel 要合并的配置项
+   */
   public setBaseCfgModel(baseCfgModel: IRequestCfgModel2) {
     Object.assign(this.baseCfgModel, baseCfgModel);
   }
@@ -115,6 +124,13 @@ export class CrudProQuick {
     return res.getResRows();
   }
 
+  /**
+   * 分页查询数据列表，返回包含 rows 和 total_count 的分页结果
+   * 内部使用 SIMPLE_QUERY_PAGE 模式，reqJson 中可传入 pageNo、pageSize 控制分页
+   * @param reqJson 请求参数，支持 condition（查询条件）、pageNo、pageSize 等
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns ResModelPageQuery 包含 rows（数据行数组）和 total_count（总记录数）
+   */
   public async getListPage(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelPageQuery> {
     const cfgModel: IRequestCfgModel = {
       sqlTable,
@@ -124,6 +140,29 @@ export class CrudProQuick {
     return res.getResModelForQueryPage();
   }
 
+  /**
+   * 判断满足条件的记录是否存在
+   * 内部使用 SIMPLE_QUERY_EXIST 模式，通过 SELECT EXISTS 子查询实现，找到首条匹配即返回，比 COUNT(*) 更高效
+   * @param reqJson 请求参数，通过 condition 指定查询条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns boolean 存在返回 true，不存在返回 false
+   */
+  public async isExist(reqJson: IRequestModel, sqlTable?: string): Promise<boolean> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_EXIST,
+    };
+    const res = await this.executeCrudByCfg(reqJson, cfgModel);
+    return res.getResModel().is_exist;
+  }
+
+  /**
+   * 查询满足条件的记录总数
+   * 内部使用 SIMPLE_QUERY_COUNT 模式，仅返回 count 结果
+   * @param reqJson 请求参数，通过 condition 指定查询条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns number 满足条件的记录总数
+   */
   public async getTotalCount(reqJson: IRequestModel, sqlTable?: string): Promise<number> {
     const cfgModel: IRequestCfgModel = {
       sqlTable,
@@ -133,6 +172,13 @@ export class CrudProQuick {
     return res.getResModel().total_count;
   }
 
+  /**
+   * 插入一条数据记录
+   * 内部使用 SIMPLE_INSERT 模式，通过 reqJson.data 传入要插入的字段和值
+   * @param reqJson 请求参数，data 字段中包含要插入的键值对
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns ResModelAffected 包含受影响的行数信息
+   */
   public async insertObject(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected> {
     const cfgModel: IRequestCfgModel = {
       sqlTable,
@@ -142,6 +188,37 @@ export class CrudProQuick {
     return res.getResModel().affected;
   }
 
+  /**
+   * 批量插入数据记录
+   * 内部使用 SIMPLE_BATCH_INSERT 模式，单条 SQL 插入多行数据，效率远高于循环单条插入
+   * 
+   * @param reqJson 请求参数，data 为对象数组 [{name:'a'},{name:'b'}]
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns ResModelAffected 包含受影响的行数信息
+   * 
+   * 注意事项：
+   * - affectedRows: 返回实际插入的行数，所有数据库均正确返回
+   * - insertId: 仅返回第一条记录的自增ID，后续记录的ID需通过 insertId + index 推算
+   *   - MySQL: 返回第一条的 insertId
+   *   - PostgreSQL: RETURNING * 返回所有行，但仅取第一条的 id
+   *   - SQL Server: OUTPUT 返回所有行，但仅取第一条的 id
+   */
+  public async batchInsert(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_BATCH_INSERT,
+    };
+    const res = await this.executeCrudByCfg(reqJson, cfgModel);
+    return res.getResModel().affected;
+  }
+
+  /**
+   * 更新数据记录
+   * 内部使用 SIMPLE_UPDATE 模式，通过 reqJson.data 传入要更新的字段和值，通过 reqJson.condition 指定更新条件
+   * @param reqJson 请求参数，data 为更新内容，condition 为更新条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns ResModelAffected 包含受影响的行数信息
+   */
   public async updateObject(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected> {
     const cfgModel: IRequestCfgModel = {
       sqlTable,
@@ -151,6 +228,13 @@ export class CrudProQuick {
     return res.getResModel().affected;
   }
 
+  /**
+   * 插入或更新数据记录（upsert）
+   * 内部使用 SIMPLE_INSERT_OR_UPDATE 模式，若记录已存在则更新，不存在则插入
+   * @param reqJson 请求参数，data 为要插入/更新的内容，condition 为判断条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns ResModelStandard 返回完整的结果模型，包含 affected、insertId 等多种返回值
+   */
   public async insertOrUpdate(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelStandard> {
     const cfgModel: IRequestCfgModel = {
       sqlTable,
@@ -160,6 +244,38 @@ export class CrudProQuick {
     return res.getResModel(); // 因为它有三个返回值
   }
 
+  /**
+   * 使用数据库原生 upsert 语法插入或更新（ON DUPLICATE KEY UPDATE / ON CONFLICT / MERGE）
+   * 内部使用 SIMPLE_INSERT_ON_DUPLICATE_UPDATE 模式，单条 SQL 完成 upsert，效率更高
+   * 
+   * 数据库差异：
+   * - MySQL: ON DUPLICATE KEY UPDATE（依赖唯一索引/主键）
+   * - PostgreSQL: ON CONFLICT (...) DO UPDATE（需配置 uniqueColumn）
+   * - SQL Server: IF EXISTS ... ELSE ...（需配置 uniqueColumn，仅支持单列）
+   * 
+   * @param reqJson 请求参数，data 为要插入/更新的内容
+   * @param uniqueColumn 唯一列名（PostgreSQL/SQL Server 必需），PostgreSQL 支持多列，SQL Server 仅支持单列
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns ResModelAffected 包含受影响的行数信息
+   */
+  public async insertOnDuplicate(reqJson: IRequestModel, uniqueColumn?: string[], sqlTable?: string): Promise<ResModelAffected> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE,
+      uniqueColumn,
+    };
+    const res = await this.executeCrudByCfg(reqJson, cfgModel);
+    return res.getResModel().affected;
+  }
+
+  /**
+   * 删除数据记录
+   * 内部使用 SIMPLE_DELETE 模式，通过 reqJson.condition 指定删除条件
+   * 注意：如果启用了软删除，实际执行的是更新操作而非物理删除
+   * @param reqJson 请求参数，condition 为删除条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns ResModelAffected 包含受影响的行数信息
+   */
   public async deleteObject(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected> {
     const cfgModel: IRequestCfgModel = {
       sqlTable,
@@ -169,6 +285,13 @@ export class CrudProQuick {
     return res.getResModel().affected;
   }
 
+  /**
+   * 执行自定义 SQL 语句（经 CrudPro 框架封装处理）
+   * 与 executeNativeSQL 不同，此方法执行的 SQL 会经过框架的参数绑定等安全处理
+   * @param executeSql 要执行的 SQL 语句，支持参数占位符
+   * @param args SQL 参数数组，与占位符一一对应
+   * @returns any SQL 执行结果
+   */
   public async executeSQL(executeSql: string, args?: any[]): Promise<any> {
     const sqlCfgModel: ISqlCfgModel = {
       executeSql: executeSql,
@@ -182,11 +305,47 @@ export class CrudProQuick {
 
 
   /**
-   * 执行数据库的原生SQL语句，不做任何封装的SQL
-   * @param executeNativeSql
-   * @param args
+   * 执行数据库的原生SQL语句，不做任何封装
+   * 
+   * 返回值结构取决于 SQL 类型和数据库类型：
+   * 
+   * **SELECT 查询**: 返回行数据数组
+   * 
+   * **INSERT/UPDATE/DELETE**: 返回数据库驱动的原始结果
+   * - MySQL: `NativeSqlResultMySQL` - 包含 insertId、affectedRows、changedRows 等
+   * - PostgreSQL: 空数组（pg 驱动返回 rows 为空）
+   * - SQL Server: 空数组（mssql 驱动返回 recordset 为空）
+   * 
+   * **注意**:
+   * - 使用 `?` 作为占位符，框架会自动转换为对应数据库的占位符
+   * - PostgreSQL/SQL Server 会将 `?` 转换为 `$1, $2, ...` 或 `@fatcms_ms1, @fatcms_ms2, ...`
+   * 
+   * @typeParam T 返回值类型，默认 any。
+   * 预定义类型位于 `@/libs/crud-pro/models/ResModel`：
+   * - `NativeSqlSelectResult` - SELECT 查询返回的行数组
+   * - `NativeSqlResultMySQL` - MySQL INSERT/UPDATE/DELETE 返回结果
+   * - 或自定义行类型数组，如 `{id: number, name: string}[]`
+   * 
+   * @param executeNativeSql 原生 SQL 语句，使用 `?` 作为参数占位符
+   * @param args 参数数组，与 SQL 中的 `?` 一一对应
+   * @returns 根据 SQL 类型返回对应结果
+   * 
+   * @example
+   * // SELECT 查询 - 使用自定义行类型
+   * const rows = await crudProQuick.executeNativeSQL<{id: number, name: string}[]>(
+   *   'SELECT id, name FROM user WHERE age > ?', 
+   *   [18]
+   * );
+   * 
+   * // INSERT - MySQL 返回 NativeSqlResultMySQL
+   * // 需先导入: import { NativeSqlResultMySQL } from '@/libs/crud-pro/models/ResModel';
+   * const result = await crudProQuick.executeNativeSQL<NativeSqlResultMySQL>(
+   *   'INSERT INTO user (name, age) VALUES (?, ?)',
+   *   ['张三', 20]
+   * );
+   * console.log(result.insertId, result.affectedRows);
    */
-  public async executeNativeSQL(executeNativeSql: string, args?: any[]): Promise<any> {
+  public async executeNativeSQL<T = any>(executeNativeSql: string, args?: any[]): Promise<T> {
     const sqlCfgModel: ISqlCfgModel = {
       isNativeSQL: true,
       executeSql: executeNativeSql,

package/src/service/curd/CurdMixService.ts

@@ -1,7 +1,7 @@
 import { Inject, Provide } from '@midwayjs/core';
 import { CurdProService } from './CurdProService';
 import { CurdMixByDictService } from './CurdMixByDictService';
-import { ColumnRelation, IRequestCfgModel, IRequestModel, ISqlCfgModel } from '@/libs/crud-pro/interfaces';
+import { ColumnRelation, IRequestCfgModel, IRequestModel, ISqlCfgModel, ITableListResult, ITableNamesOptions, ITableNamesQuery } from '@/libs/crud-pro/interfaces';
 import { CurdMixBySysConfigService } from './CurdMixBySysConfigService';
 import { CurdMixByAccountService } from './CurdMixByAccountService';
 import { RelatedType } from './CurdMixUtils';
@@ -50,7 +50,7 @@ export class CurdMixService {
 
   getBbUtil(sqlDatabase: string, sqlDbType: SqlDbType, sqlTable?: string) {
     this.prepare();
-    return this.curdProService.getBbUtil(sqlDatabase, sqlDbType, sqlTable);
+    return this.curdProService.getQuickCrud(sqlDatabase, sqlDbType, sqlTable);
   }
 
   async executeSQL(sqlCfgModel: ISqlCfgModel) {
@@ -94,4 +94,9 @@ export class CurdMixService {
       await handler.handleExecuteContext(exeCtx);
     }
   }
+
+  public async getAllTableInfos(query: ITableNamesQuery, options?: ITableNamesOptions): Promise<ITableListResult> {
+    this.prepare();
+    return this.curdProService.getAllTableInfos(query, options);
+  }
 }