midway-fatcms 0.0.5 → 0.0.7

package/dist/libs/crud-sharding/ShardingUtils.d.ts

@@ -0,0 +1,38 @@
+import { ShardingType } from './ShardingConfig';
+/**
+ * 时间粒度类型
+ */
+export declare type ShardingTimeGranularity = 'year' | 'month' | 'day';
+/**
+ * 将 ShardingType 转换为时间粒度
+ */
+export declare function shardingTypeToGranularity(type: ShardingType): ShardingTimeGranularity | 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 declare function getTimeSuffix(date: Date, granularity: ShardingTimeGranularity): string;
+/**
+ * 获取当前时间周期的后缀（用于识别"当前表"）
+ *
+ * @param shardingType 分表类型
+ * @returns 当前时间后缀，非时间分表返回空字符串
+ */
+export declare function getCurrentSuffix(shardingType: ShardingType | undefined): string;
+/**
+ * 判断表名是否为当前时间周期的表
+ *
+ * @param tableName 完整表名（如 t_order_202404）
+ * @param baseTable 基础表名（如 t_order）
+ * @param shardingType 分表类型
+ * @returns 是否为当前表
+ */
+export declare function isCurrentTable(tableName: string, baseTable: string, shardingType: ShardingType | undefined): boolean;

package/dist/libs/crud-sharding/ShardingUtils.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCurrentTable = exports.getCurrentSuffix = exports.getTimeSuffix = exports.shardingTypeToGranularity = void 0;
+const ShardingConfig_1 = require("./ShardingConfig");
+/**
+ * 将 ShardingType 转换为时间粒度
+ */
+function shardingTypeToGranularity(type) {
+    switch (type) {
+        case ShardingConfig_1.ShardingType.YEAR:
+            return 'year';
+        case ShardingConfig_1.ShardingType.MONTH:
+            return 'month';
+        case ShardingConfig_1.ShardingType.DAY:
+            return 'day';
+        default:
+            return undefined;
+    }
+}
+exports.shardingTypeToGranularity = shardingTypeToGranularity;
+/**
+ * 获取日期对应的时间后缀
+ *
+ * @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"
+ */
+function getTimeSuffix(date, granularity) {
+    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}`;
+    }
+}
+exports.getTimeSuffix = getTimeSuffix;
+/**
+ * 获取当前时间周期的后缀（用于识别"当前表"）
+ *
+ * @param shardingType 分表类型
+ * @returns 当前时间后缀，非时间分表返回空字符串
+ */
+function getCurrentSuffix(shardingType) {
+    const granularity = shardingTypeToGranularity(shardingType);
+    if (!granularity) {
+        return '';
+    }
+    return getTimeSuffix(new Date(), granularity);
+}
+exports.getCurrentSuffix = getCurrentSuffix;
+/**
+ * 判断表名是否为当前时间周期的表
+ *
+ * @param tableName 完整表名（如 t_order_202404）
+ * @param baseTable 基础表名（如 t_order）
+ * @param shardingType 分表类型
+ * @returns 是否为当前表
+ */
+function isCurrentTable(tableName, baseTable, shardingType) {
+    const currentSuffix = getCurrentSuffix(shardingType);
+    if (!currentSuffix) {
+        return false;
+    }
+    const expectedTableName = `${baseTable}_${currentSuffix}`;
+    return tableName === expectedTableName;
+}
+exports.isCurrentTable = isCurrentTable;

package/dist/libs/crud-sharding/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 分表 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';
+export { ShardingCountCache, shardingHashCondition } from './ShardingCountCache';
+export type { ShardingTimeGranularity } from './ShardingUtils';

package/dist/libs/crud-sharding/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * 分表 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,
+ * });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shardingHashCondition = exports.ShardingCountCache = exports.ShardingTableCreator = exports.ShardingType = exports.ShardingMerger = exports.ShardingRouter = exports.ShardingCrudPro = void 0;
+// 核心类
+var ShardingCrudPro_1 = require("./ShardingCrudPro");
+Object.defineProperty(exports, "ShardingCrudPro", { enumerable: true, get: function () { return ShardingCrudPro_1.ShardingCrudPro; } });
+var ShardingRouter_1 = require("./ShardingRouter");
+Object.defineProperty(exports, "ShardingRouter", { enumerable: true, get: function () { return ShardingRouter_1.ShardingRouter; } });
+var ShardingMerger_1 = require("./ShardingMerger");
+Object.defineProperty(exports, "ShardingMerger", { enumerable: true, get: function () { return ShardingMerger_1.ShardingMerger; } });
+// 配置和类型
+var ShardingConfig_1 = require("./ShardingConfig");
+Object.defineProperty(exports, "ShardingType", { enumerable: true, get: function () { return ShardingConfig_1.ShardingType; } });
+// 分表创建器
+var ShardingTableCreator_1 = require("./ShardingTableCreator");
+Object.defineProperty(exports, "ShardingTableCreator", { enumerable: true, get: function () { return ShardingTableCreator_1.ShardingTableCreator; } });
+// COUNT 缓存
+var ShardingCountCache_1 = require("./ShardingCountCache");
+Object.defineProperty(exports, "ShardingCountCache", { enumerable: true, get: function () { return ShardingCountCache_1.ShardingCountCache; } });
+Object.defineProperty(exports, "shardingHashCondition", { enumerable: true, get: function () { return ShardingCountCache_1.shardingHashCondition; } });

package/dist/models/StandardColumns.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 标准表结构字段类型定义
+ *
+ * 常用标准字段（推荐所有表都包含）：
+ * - 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 declare type StandardDataModel<T = {}> = T & ICommonStandardColumns;
+/**
+ * 包含完整标准字段的数据模型
+ */
+export declare type FullStandardDataModel<T = {}> = T & IFullStandardColumns;
+/**
+ * 未删除查询条件
+ */
+export declare const NotDeletedCondition: {
+    deleted_at: 0;
+};

package/dist/models/StandardColumns.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * 标准表结构字段类型定义
+ *
+ * 常用标准字段（推荐所有表都包含）：
+ * - 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: 修改人昵称
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotDeletedCondition = void 0;
+/**
+ * 未删除查询条件
+ */
+exports.NotDeletedCondition = {
+    deleted_at: 0,
+};

package/dist/service/SysAppService.js

@@ -20,11 +20,11 @@ const bizmodels_1 = require("../models/bizmodels");
 let SysAppService = class SysAppService extends BaseService_1.BaseService {
     get sysAppDao() {
         const { SystemDbName, SystemDbType } = global_config_1.GLOBAL_STATIC_CONFIG.getConfig();
-        return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_app);
+        return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_app);
     }
     get sysAppPageDao() {
         const { SystemDbName, SystemDbType } = global_config_1.GLOBAL_STATIC_CONFIG.getConfig();
-        return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_app_page);
+        return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_app_page);
     }
     async getSysAppPageOne({ page_path, workbench_code }) {
         if (!page_path || typeof page_path !== 'string') {

package/dist/service/SysConfigService.js

@@ -20,7 +20,7 @@ const CacheServiceFactory_1 = require("../service/base/cache/CacheServiceFactory
 let SysConfigService = class SysConfigService extends BaseService_1.BaseService {
     get sysConfigsDao() {
         const { SystemDbName, SystemDbType } = global_config_1.GLOBAL_STATIC_CONFIG.getConfig();
-        return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_configs);
+        return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_configs);
     }
     async getSysConfigOne(config_code) {
         if (!config_code || typeof config_code !== 'string') {

package/dist/service/SysDictDataService.js

@@ -20,11 +20,11 @@ const bizmodels_1 = require("../models/bizmodels");
 let SysDictDataService = class SysDictDataService extends BaseService_1.BaseService {
     get sys_data_dict_item() {
         const { SystemDbName, SystemDbType } = global_config_1.GLOBAL_STATIC_CONFIG.getConfig();
-        return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_data_dict_item);
+        return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables_1.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)
     // }
     async getDataDictItemsByDictCode(dict_code) {
         if (!dict_code || typeof dict_code !== 'string') {

package/dist/service/SysMenuService.js

@@ -20,7 +20,7 @@ const bizmodels_1 = require("../models/bizmodels");
 let SysMenuService = class SysMenuService extends BaseService_1.BaseService {
     get sys_menus_table() {
         const { SystemDbName, SystemDbType } = global_config_1.GLOBAL_STATIC_CONFIG.getConfig();
-        return this.curdProService.getBbUtil(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_menus);
+        return this.curdProService.getQuickCrud(SystemDbName, SystemDbType, SystemTables_1.SystemTables.sys_menus);
     }
     /**
      * 获取所有菜单列表

package/dist/service/UserAccountService.d.ts

@@ -7,7 +7,7 @@ export declare class UserAccountService {
      * 查询用户: 根据loginName查询
      * @param loginName
      */
-    queryUserAccountByLoginName(loginName: string): Promise<any>;
+    queryUserAccountByLoginName(loginName: string): Promise<import("../libs/crud-pro/models/ResModel").ResModelRowEntity>;
     /**
      * 查询基本信息：根据accountId数组
      * @param accountIdList

package/dist/service/crudstd/CrudStdService.d.ts

@@ -55,5 +55,4 @@ export declare class CrudStdService extends ApiBaseService {
     private hasOperationPerm;
     private fixCfgModelByFilterValue;
     private fixSubmitDataByKeepSubmitData;
-    private fixDataFieldTypeBySqlTableField;
 }

package/dist/service/crudstd/CrudStdService.js

@@ -23,7 +23,6 @@ const CrudStdRelationService_1 = require("./CrudStdRelationService");
 const ApiBaseService_1 = require("../base/ApiBaseService");
 const DatabaseName_1 = require("../../libs/crud-pro/utils/DatabaseName");
 const global_config_1 = require("../../libs/global-config/global-config");
-const MixinUtils_1 = require("../../libs/crud-pro/utils/MixinUtils");
 const SysAppService_1 = require("../../service/SysAppService");
 exports.SPECIAL_SETTING_KEY = {
     QUERY_LIST: 'QUERY_LIST',
@@ -95,8 +94,6 @@ let CrudStdService = class CrudStdService extends ApiBaseService_1.ApiBaseServic
         await this.fixCfgModelByFilterValue(params, cfgModel, appInfo, { dbType, dbName });
         // 根据用户配置的keepSubmitData字段修改提交的数据
         await this.fixSubmitDataByKeepSubmitData(params, cfgModel, appInfo, { dbType, dbName });
-        // 根据表结构的数据类型，修正数据类型
-        await this.fixDataFieldTypeBySqlTableField(params, cfgModel, appInfo, { dbType, dbName });
         // 业务系统自定义的修改：查询前的查询条件：cfgModel
         await global_config_1.GLOBAL_STATIC_CONFIG.getConfig().bizUpdateCfgModelForCrudStd(params, cfgModel, appInfo, this.ctx);
         const crudExeCtx = await this.curdMixService.executeCrudByCfg(params, cfgModel);
@@ -297,30 +294,6 @@ let CrudStdService = class CrudStdService extends ApiBaseService_1.ApiBaseServic
             _.merge(submitData, keepSubmitDataByGlobal);
         }
     }
-    async fixDataFieldTypeBySqlTableField(params, cfgModel, appInfo, arg3) {
-        const tableFields = _.get(appInfo, 'stdCrudCfgObj.tableFields');
-        const tableFieldMap = MixinUtils_1.MixinUtils.toMap(tableFields, (e) => {
-            return e.fieldIndex;
-        });
-        if (arg3.dbType === keys_1.SqlDbType.postgres) {
-            if (cfgModel.sqlSimpleName === keys_1.KeysOfSimpleSQL.SIMPLE_INSERT || cfgModel.sqlSimpleName === keys_1.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 = (0, functions_1.parseJsonObject)(dataValue);
-                        if (Array.isArray(dataValueArray)) {
-                            data[dataKey] = `{${dataValueArray.map(v => `"${v}"`).join(',')}}`;
-                        }
-                    }
-                }
-            }
-        }
-    }
 };
 __decorate([
     (0, core_1.Inject)(),

package/dist/service/curd/CrudProQuick.d.ts

@@ -19,6 +19,11 @@ export declare class CrudProQuick {
     private readonly ctx?;
     private baseCfgModel;
     constructor(args: ICrudProQuick);
+    /**
+     * 设置基础配置模型，合并到实例的 baseCfgModel 中，后续所有 CRUD 操作都会携带这些配置
+     * 例如可以统一设置 maxLimit、sqlSimpleName 等公共参数，避免每次调用都重复传入
+     * @param baseCfgModel 要合并的配置项
+     */
     setBaseCfgModel(baseCfgModel: IRequestCfgModel2): void;
     private executeCrudByCfg;
     /**
@@ -43,18 +48,143 @@ export declare class CrudProQuick {
      * @returns 返回多条数据对象组成的数组
      */
     getList(reqJson: IRequestModel, sqlTable?: string): Promise<any[]>;
+    /**
+     * 分页查询数据列表，返回包含 rows 和 total_count 的分页结果
+     * 内部使用 SIMPLE_QUERY_PAGE 模式，reqJson 中可传入 pageNo、pageSize 控制分页
+     * @param reqJson 请求参数，支持 condition（查询条件）、pageNo、pageSize 等
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns ResModelPageQuery 包含 rows（数据行数组）和 total_count（总记录数）
+     */
     getListPage(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelPageQuery>;
+    /**
+     * 判断满足条件的记录是否存在
+     * 内部使用 SIMPLE_QUERY_EXIST 模式，通过 SELECT EXISTS 子查询实现，找到首条匹配即返回，比 COUNT(*) 更高效
+     * @param reqJson 请求参数，通过 condition 指定查询条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns boolean 存在返回 true，不存在返回 false
+     */
+    isExist(reqJson: IRequestModel, sqlTable?: string): Promise<boolean>;
+    /**
+     * 查询满足条件的记录总数
+     * 内部使用 SIMPLE_QUERY_COUNT 模式，仅返回 count 结果
+     * @param reqJson 请求参数，通过 condition 指定查询条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns number 满足条件的记录总数
+     */
     getTotalCount(reqJson: IRequestModel, sqlTable?: string): Promise<number>;
+    /**
+     * 插入一条数据记录
+     * 内部使用 SIMPLE_INSERT 模式，通过 reqJson.data 传入要插入的字段和值
+     * @param reqJson 请求参数，data 字段中包含要插入的键值对
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns ResModelAffected 包含受影响的行数信息
+     */
     insertObject(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected>;
+    /**
+     * 批量插入数据记录
+     * 内部使用 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
+     */
+    batchInsert(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected>;
+    /**
+     * 更新数据记录
+     * 内部使用 SIMPLE_UPDATE 模式，通过 reqJson.data 传入要更新的字段和值，通过 reqJson.condition 指定更新条件
+     * @param reqJson 请求参数，data 为更新内容，condition 为更新条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns ResModelAffected 包含受影响的行数信息
+     */
     updateObject(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected>;
+    /**
+     * 插入或更新数据记录（upsert）
+     * 内部使用 SIMPLE_INSERT_OR_UPDATE 模式，若记录已存在则更新，不存在则插入
+     * @param reqJson 请求参数，data 为要插入/更新的内容，condition 为判断条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns ResModelStandard 返回完整的结果模型，包含 affected、insertId 等多种返回值
+     */
     insertOrUpdate(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelStandard>;
+    /**
+     * 使用数据库原生 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 包含受影响的行数信息
+     */
+    insertOnDuplicate(reqJson: IRequestModel, uniqueColumn?: string[], sqlTable?: string): Promise<ResModelAffected>;
+    /**
+     * 删除数据记录
+     * 内部使用 SIMPLE_DELETE 模式，通过 reqJson.condition 指定删除条件
+     * 注意：如果启用了软删除，实际执行的是更新操作而非物理删除
+     * @param reqJson 请求参数，condition 为删除条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns ResModelAffected 包含受影响的行数信息
+     */
     deleteObject(reqJson: IRequestModel, sqlTable?: string): Promise<ResModelAffected>;
+    /**
+     * 执行自定义 SQL 语句（经 CrudPro 框架封装处理）
+     * 与 executeNativeSQL 不同，此方法执行的 SQL 会经过框架的参数绑定等安全处理
+     * @param executeSql 要执行的 SQL 语句，支持参数占位符
+     * @param args SQL 参数数组，与占位符一一对应
+     * @returns any SQL 执行结果
+     */
     executeSQL(executeSql: string, args?: any[]): Promise<any>;
     /**
-     * 执行数据库的原生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);
      */
-    executeNativeSQL(executeNativeSql: string, args?: any[]): Promise<any>;
+    executeNativeSQL<T = any>(executeNativeSql: string, args?: any[]): Promise<T>;
 }
 export {};