midway-fatcms 0.0.7 → 0.0.9

package/src/libs/crud-pro-quick/CrudProQuick.ts

@@ -0,0 +1,782 @@
+import { KeysOfSimpleSQL, SqlDbType } from '@/libs/crud-pro/models/keys';
+import { IRequestCfgModel, IRequestModel, ISqlCfgModel, ExecuteSQLResult } from '@/libs/crud-pro/interfaces';
+import { CrudPro } from '@/libs/crud-pro/CrudPro';
+import { fixSoftDelete } from "./fixSoftDelete";
+import {
+  CrudWriteResult,
+  CrudQueryOneResult,
+  CrudQueryListResult,
+  CrudQueryPageResult,
+  CrudExistResult,
+  CrudCountResult,
+  CrudUpsertResult,
+} from '@/libs/crud-pro/models/CrudResult';
+import { CommonException, Exceptions } from "@/libs/crud-pro/exceptions";
+
+const DEFAULT_MAX_LIMIT = 10 * 10000;
+const DEFAULT_BATCH_SIZE_FOR_IDS_QUERY = 200;
+
+/**
+ * CrudProQuick 构造参数（工厂函数模式）
+ */
+export interface ICrudProQuickFactory {
+  crudProFactory: () => CrudPro;
+  sqlDatabase: string;
+  sqlDbType: SqlDbType;
+  sqlTable?: string;
+}
+
+/**
+ * 快捷 CRUD 操作封装器
+ *
+ * 在 CrudPro 之上封装便捷方法，提供简洁的 API 进行单表 CRUD 操作。
+ * 内部使用工厂函数模式，每次操作都会获取新的 CrudPro 实例，因此**可以安全复用**。
+ *
+ * **使用限制：**
+ * - CrudProQuick 可以安全复用（内部每次获取新 CrudPro）
+ * - 必须通过 CurdProService.getQuickCrud() 获取实例
+ * - sqlTable 必填（构造时或每次调用时传入）
+ *
+ * @example
+ * // 通过 CurdProService 获取实例
+ * const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_user');
+ *
+ * // 查询列表
+ * const result = await quick.findList({ condition: { status: 1 } });
+ * console.log(result.rows, result.count);
+ *
+ * // 插入数据
+ * const insertResult = await quick.insert({ data: { name: '张三', age: 20 } });
+ * console.log(insertResult.affectedRows, insertResult.insertId);
+ *
+ * // 可以安全复用
+ * const updateResult = await quick.update({ condition: { id: 1 }, data: { age: 21 } });
+ */
+export class CrudProQuick {
+  private readonly crudProFactory: () => CrudPro;
+  private readonly sqlDbType: SqlDbType;
+  private readonly sqlDatabase: string;
+  private readonly sqlTable?: string;
+
+  private baseCfgModel: {
+    maxLimit?: number;
+    batchSizeForIdsQuery?: number;
+    enableSoftDelete?: boolean;
+    enableStandardUpdateCfg?: boolean;
+    enableStandardUpdateCfgCondition?: string[];
+    [key: string]: any;
+  } = {
+      maxLimit: DEFAULT_MAX_LIMIT,
+      batchSizeForIdsQuery: DEFAULT_BATCH_SIZE_FOR_IDS_QUERY,
+    };
+
+  /**
+   * 构造函数（工厂函数模式）
+   * @param args 工厂函数参数
+   */
+  constructor(args: ICrudProQuickFactory) {
+    this.sqlDatabase = args.sqlDatabase;
+    this.sqlDbType = args.sqlDbType;
+    this.sqlTable = args.sqlTable;
+    this.crudProFactory = args.crudProFactory;
+  }
+
+  /**
+   * 设置基础配置模型，合并到实例的 baseCfgModel 中，后续所有 CRUD 操作都会携带这些配置
+   * 例如可以统一设置 maxLimit、enableSoftDelete 等公共参数，避免每次调用都重复传入
+   * @param baseCfgModel 要合并的配置项
+   */
+  public setBaseCfgModel(baseCfgModel: Record<string, any>) {
+    Object.assign(this.baseCfgModel, baseCfgModel);
+  }
+
+  private async executeCrudByCfg(reqJson: IRequestModel, cfgModel2: Record<string, any>) {
+    const cfgModel = { ...this.baseCfgModel };
+    Object.assign(cfgModel, cfgModel2);
+
+    cfgModel.method = 'CrudProQuickAnonymous';
+    cfgModel.updateCfg = {};
+    cfgModel.sqlDatabase = this.sqlDatabase;
+    cfgModel.sqlDbType = this.sqlDbType;
+
+    if (!cfgModel.sqlTable) {
+      cfgModel.sqlTable = this.sqlTable;
+    }
+
+    if (!cfgModel.sqlTable) {
+      throw new Error('[CrudProQuick] sqlTable not found');
+    }
+
+    // 创建 CrudPro 实例并设置 visitor
+    const crudPro = this.crudProFactory();
+
+    // 应用软删除动作。
+    fixSoftDelete(cfgModel.sqlSimpleName, cfgModel, reqJson, crudPro.getVisitor());
+
+    return await crudPro.executeCrudByCfg(reqJson, cfgModel);
+  }
+
+  /**
+   * 查询单条记录
+   * @param reqJson 请求参数
+   * @param sqlTable 数据库表名称
+   * @returns CrudQueryOneResult 包含 row、found 和 getRawContext()
+   */
+  public async findOne<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryOneResult<T>> {
+    const effectiveTable = sqlTable || this.sqlTable;
+
+    const cfgModel: IRequestCfgModel = {
+      sqlTable: effectiveTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_ONE,
+    };
+
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const row = ctx.getOneObj() as T | null;
+    return new CrudQueryOneResult<T>({
+      row,
+      rawContext: ctx,
+      debugInfo: this.buildDebugInfo(effectiveTable, reqJson.condition),
+      fromTable: effectiveTable
+    });
+  }
+
+  /**
+   * 查询唯一单条记录（期望结果为 0 条或 1 条）
+   *
+   * 与 findOne 不同，此方法会校验查询结果的唯一性：
+   * - 如果查到 0 条：返回 row = null
+   * - 如果查到 1 条：正常返回
+   * - 如果查到多条：抛出异常，包含详细的定位信息
+   *
+   * @param reqJson 请求参数
+   * @param sqlTable 数据库表名称
+   * @returns CrudQueryOneResult 包含 row、found 和 getRawContext()
+   * @throws Error 如果查询到多条记录
+   *
+   * @example
+   * // 根据唯一索引查询单条
+   * const result = await quick.findUniqueOne({ condition: { email: 'user@example.com' } });
+ * if (result.found) {
+ *   console.log(result.row);
+ * }
+   */
+  public async findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryOneResult<T>> {
+    const effectiveTable = sqlTable || this.sqlTable;
+
+    // 使用 maxLimit: 2 查询，判断是否有多条
+    const cfgModel: IRequestCfgModel = {
+      sqlTable: effectiveTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY,
+      maxLimit: 2,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const rows = ctx.getResRows() as T[];
+
+    if (rows.length > 1) {
+      throw new CommonException(Exceptions.MORE_THAN_ONE_RECORDS_FOUND, '发现了不止一条数据')
+    }
+
+    return new CrudQueryOneResult<T>({
+      row: rows[0] || null,
+      rawContext: ctx,
+      debugInfo: this.buildDebugInfo(effectiveTable, reqJson.condition),
+      fromTable: effectiveTable,
+    });
+  }
+
+  /**
+   * 构建辅助定位信息
+   */
+  private buildDebugInfo(sqlTable: string | undefined, condition: Record<string, any> | undefined): { sqlDatabase: string; sqlTable: string; condition?: Record<string, any> } {
+    const info: { sqlDatabase: string; sqlTable: string; condition?: Record<string, any> } = {
+      sqlDatabase: this.sqlDatabase,
+      sqlTable: sqlTable || this.sqlTable || 'unknown',
+    };
+    if (condition) {
+      info.condition = condition;
+    }
+    return info;
+  }
+  /**
+   * 查询数据列表
+   * @param reqJson 请求参数
+   * @param sqlTable 数据库表名称
+   * @returns CrudQueryListResult 包含 rows、count 和 getRawContext()
+   */
+  public async findList<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryListResult<T>> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const rows = ctx.getResRows() as T[];
+    return new CrudQueryListResult<T>({ rows, rawContext: ctx });
+  }
+
+  /**
+   * 分页查询数据列表
+   * 内部使用 SIMPLE_QUERY_PAGE 模式，reqJson 中可传入 pageNo、pageSize 控制分页
+   * @param reqJson 请求参数，支持 condition（查询条件）、pageNo、pageSize 等
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudQueryPageResult 包含 rows、totalCount、count 和 getRawContext()
+   */
+  public async findPage<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryPageResult<T>> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_PAGE,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const pageResult = ctx.getResModelForQueryPage();
+    return new CrudQueryPageResult<T>({
+      rows: pageResult.rows as T[],
+      totalCount: pageResult.total_count,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 判断满足条件的记录是否存在
+   * 内部使用 SIMPLE_QUERY_EXIST 模式，通过 SELECT EXISTS 子查询实现，找到首条匹配即返回，比 COUNT(*) 更高效
+   * @param reqJson 请求参数，通过 condition 指定查询条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudExistResult 包含 exists 和 getRawContext()
+   */
+  public async isExist(reqJson: IRequestModel, sqlTable?: string): Promise<CrudExistResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_EXIST,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const exists = ctx.getResModel().is_exist;
+    return new CrudExistResult({ exists, rawContext: ctx });
+  }
+
+  /**
+   * 查询满足条件的记录总数
+   * 内部使用 SIMPLE_QUERY_COUNT 模式，仅返回 count 结果
+   * @param reqJson 请求参数，通过 condition 指定查询条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudCountResult 包含 count 和 getRawContext()
+   */
+  public async findCount(reqJson: IRequestModel, sqlTable?: string): Promise<CrudCountResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_COUNT,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const count = ctx.getResModel().total_count || 0;
+    return new CrudCountResult({ count, rawContext: ctx });
+  }
+
+  /**
+   * 插入一条数据记录
+   * 内部使用 SIMPLE_INSERT 模式，通过 reqJson.data 传入要插入的字段和值
+   * @param reqJson 请求参数，data 字段中包含要插入的键值对
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudWriteResult 包含 affectedRows、insertId 和 getRawContext()
+   */
+  public async insert(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 批量插入数据记录
+   * 内部使用 SIMPLE_BATCH_INSERT 模式，单条 SQL 插入多行数据，效率远高于循环单条插入
+   *
+   * @param reqJson 请求参数，data 为对象数组 [{name:'a'},{name:'b'}]
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudWriteResult 包含 affectedRows、insertId 和 getRawContext()
+   *
+   * 注意事项：
+   * - affectedRows: 返回实际插入的行数，所有数据库均正确返回
+   * - insertId: 仅返回第一条记录的自增ID，后续记录的ID需通过 insertId + index 推算
+   *   - MySQL: 返回第一条的 insertId
+   *   - PostgreSQL: RETURNING * 返回所有行，但仅取第一条的 id
+   *   - SQL Server: OUTPUT 返回所有行，但仅取第一条的 id
+   */
+  public async batchInsert(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_BATCH_INSERT,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 更新数据记录
+   * 内部使用 SIMPLE_UPDATE 模式，通过 reqJson.data 传入要更新的字段和值，通过 reqJson.condition 指定更新条件
+   * @param reqJson 请求参数，data 为更新内容，condition 为更新条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
+   */
+  public async update(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_UPDATE,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 插入或更新数据记录（upsert）
+   * 限制：
+   *  - 必须有condition字段，用于判断记录是否存在
+   *  - 必须有data字段，用于指定插入/更新的内容
+   * 内部使用 SIMPLE_INSERT_OR_UPDATE 模式，若记录已存在则更新，不存在则插入
+   * @param reqJson 请求参数，data 为要插入/更新的内容，condition 为判断条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudUpsertResult 包含 affected、insertAffected、updateAffected、isExist 和 getRawContext()
+   */
+  public async insertOrUpdate(reqJson: IRequestModel, sqlTable?: string): Promise<CrudUpsertResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const resModel = ctx.getResModel();
+    return new CrudUpsertResult({
+      insertAffected: resModel.insert_affected,
+      updateAffected: resModel.update_affected,
+      isExist: resModel.is_exist ?? false,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 使用数据库原生 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 CrudWriteResult 包含 affectedRows、insertId 和 getRawContext()
+   */
+  public async insertOnDuplicateUpdate(reqJson: IRequestModel, uniqueColumn?: string[], sqlTable?: string): Promise<CrudWriteResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE,
+      uniqueColumn,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 删除数据记录
+   * 内部使用 SIMPLE_DELETE 模式，通过 reqJson.condition 指定删除条件
+   * 注意：如果启用了软删除，实际执行的是更新操作而非物理删除
+   * @param reqJson 请求参数，condition 为删除条件
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
+   */
+  public async delete(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult> {
+    const cfgModel: IRequestCfgModel = {
+      sqlTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_DELETE,
+    };
+    const ctx = await this.executeCrudByCfg(reqJson, cfgModel);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 恢复软删除的记录
+   * 将 deleted_at 字段重置为 0，deleted_by 重置为空字符串
+   *
+   * @param reqJson 请求参数，通过 condition 指定要恢复的记录
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
+   *
+   * @example
+   * // 恢复指定 ID 的记录
+   * await quick.restore({ condition: { id: 1 } });
+   *
+   * // 恢复多条记录（使用 $in 操作符）
+   * await quick.restore({ condition: { id: { $in: [1, 2, 3] } } });
+   *
+   * // 按条件批量恢复记录
+   * await quick.restore({ condition: { status: 'deleted' } });
+   */
+  public async restore(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult> {
+    const effectiveTable = sqlTable || this.sqlTable;
+
+    if (!reqJson.condition || Object.keys(reqJson.condition).length === 0) {
+      throw new Error('[CrudProQuick] restore 操作必须指定恢复条件');
+    }
+
+    // 构建恢复数据：重置软删除字段
+    const restoreReqJson: IRequestModel = {
+      ...reqJson,
+      data: {
+        ...reqJson.data,
+        deleted_at: 0,
+        deleted_by: '',
+      },
+    };
+
+    const cfgModel: IRequestCfgModel = {
+      sqlTable: effectiveTable,
+      sqlSimpleName: KeysOfSimpleSQL.SIMPLE_UPDATE,
+    };
+
+    const ctx = await this.executeCrudByCfg(restoreReqJson, cfgModel);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
+  }
+
+  /**
+   * 保存数据记录（自动判断 INSERT 或 UPDATE）
+   *
+   * 只需传入 data，无需手动指定 condition。方法会自动从表结构中获取主键列，
+   * 根据 data 中是否包含主键值来决定操作类型：
+   * - data 包含主键且主键值不为 undefined/null → 调用 insertOrUpdate（先查后写，存在则更新，不存在则插入）
+   * - data 不包含主键或主键值为 undefined/null → 调用 insert（直接插入）
+   *
+   * **前置条件**：data 不能为空
+   *
+   * @param reqJson 请求参数，只需 data 字段
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudUpsertResult 包含 affected、insertAffected、updateAffected、isExist 和 getRawContext()
+   *
+   * @example
+   * // 有主键 → 先查后写（存在则 UPDATE，不存在则 INSERT）
+   * await quick.save({ data: { id: 1, name: '张三' } });
+   *
+   * // 无主键 → 直接 INSERT
+   * await quick.save({ data: { name: '李四' } });
+   *
+   * // 主键值为 null → 视为无主键，直接 INSERT
+   * await quick.save({ data: { id: null, name: '王五' } });
+   */
+  public async save(reqJson: IRequestModel, sqlTable?: string): Promise<CrudUpsertResult> {
+    if (!reqJson.data || Object.keys(reqJson.data as Record<string, any>).length === 0) {
+      throw new Error('[CrudProQuick] save 操作的 data 不能为空。data 用于指定保存的内容。');
+    }
+
+    const effectiveTable = sqlTable || this.sqlTable;
+    if (!effectiveTable) {
+      throw new Error('[CrudProQuick] sqlTable not found');
+    }
+
+    // 获取表的主键列
+    const primaryKeys = await this.getPrimaryKeyColumns(effectiveTable);
+    const data = reqJson.data as Record<string, any>;
+
+    // 检查 data 中是否包含所有主键且值有效
+    const hasPrimaryKeyValue = primaryKeys.length > 0 &&
+      primaryKeys.every(pk => pk in data && data[pk] !== undefined && data[pk] !== null);
+
+    if (hasPrimaryKeyValue) {
+      // 从 data 中提取主键作为 condition
+      const condition: Record<string, any> = {};
+      for (const pk of primaryKeys) {
+        condition[pk] = data[pk];
+      }
+      // 调用 insertOrUpdate（先查后写）
+      return this.insertOrUpdate({ ...reqJson, condition }, sqlTable);
+    }
+
+    const condition = reqJson.condition;
+    if (condition && Object.keys(condition).length > 0) {
+      return this.insertOrUpdate(reqJson, sqlTable);
+    }
+
+    // 无主键值 → 直接 INSERT
+    const insertResult = await this.insert(reqJson, sqlTable);
+    // 将 CrudWriteResult 转换为 CrudUpsertResult
+    return new CrudUpsertResult({
+      insertAffected: { affectedRows: insertResult.affectedRows, insertId: insertResult.insertId },
+      updateAffected: { affectedRows: 0, insertId: null },
+      isExist: false,
+      rawContext: insertResult.getRawContext(),
+    });
+  }
+
+  /**
+   * 获取表的主键列名列表
+   *
+   * 委托给 CrudPro.getPrimaryKeyColumns，复用 CrudProTableMetaService 的 getTableMeta 缓存，
+   * 避免重复查询数据库。
+   *
+   * @param sqlTable 表名
+   * @returns 主键列名数组，如果查询失败返回 ['id'] 作为保守默认值
+   */
+  private async getPrimaryKeyColumns(sqlTable: string): Promise<string[]> {
+    try {
+      const crudPro = this.crudProFactory();
+      return await crudPro.getPrimaryKeyColumns({
+        sqlTable,
+        sqlDatabase: this.sqlDatabase,
+        sqlDbType: this.sqlDbType,
+      });
+    } catch (error) {
+      // 查询失败时保守返回 ['id']，避免阻断正常流程
+      console.warn('[CrudProQuick] 获取主键列失败，使用默认值 ["id"]:', error);
+      return ['id'];
+    }
+  }
+
+  /**
+   * 根据主键 ID 查询单条记录
+   *
+   * 等价于 `findUniqueOne({ condition: { id } })`，但更简洁。
+   * 使用 findUniqueOne 确保结果唯一性，如果查询到多条记录会抛出异常。
+   *
+   * @param id 主键值
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudQueryOneResult 包含 row、found 和 getRawContext()
+   *
+   * @example
+   * // 根据 ID 查询单条
+   * const result = await quick.findOneById(1);
+   * if (result.found) {
+   *   console.log(result.row);
+   * }
+   *
+   * // 指定表名
+   * const result = await quick.findOneById('ORD001', 't_order');
+   */
+  public async findOneById<T = Record<string, any>>(id: number | string, sqlTable?: string): Promise<CrudQueryOneResult<T>> {
+    return this.findUniqueOne<T>({ condition: { id } }, sqlTable);
+  }
+
+  /**
+   * 根据主键 ID 列表查询多条记录
+   *
+   * 实现逻辑：
+   * 1. 先对 ids 去重，避免重复 ID 导致无效查询和重复结果
+   * 2. 若去重后为空，直接返回空结果
+   * 3. 若 ID 数量不超过批次大小，单次 findList 查询完成
+   * 4. 若 ID 数量超过批次大小，自动分批查询（每批默认 200 个 ID），
+   *    避免单次 IN 列表过大导致执行计划退化和内存尖峰，最后合并结果返回
+   *
+   * @param ids 主键值数组（内部会自动去重）
+   * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+   * @returns CrudQueryListResult 包含 rows、count 和 getRawContext()
+   *
+   * @example
+   * // 根据 ID 列表查询
+   * const result = await quick.findListByIds([1, 2, 3]);
+   * console.log(result.rows, result.count);
+   *
+   * // 指定表名
+   * const result = await quick.findListByIds(['ORD001', 'ORD002'], 't_order');
+   */
+  public async findListByIds<T = Record<string, any>>(ids: (number | string)[], sqlTable?: string): Promise<CrudQueryListResult<T>> {
+    // 去重：避免重复 ID 导致无效查询和重复结果
+    const uniqueIds = [...new Set(ids)];
+
+    const batchSize = this.baseCfgModel.batchSizeForIdsQuery || DEFAULT_BATCH_SIZE_FOR_IDS_QUERY;
+    if (uniqueIds.length === 0) {
+      return new CrudQueryListResult<T>({ rows: [], rawContext: null });
+    }
+
+    if (uniqueIds.length <= batchSize) {
+      return this.findList<T>({ condition: { id: { $in: uniqueIds } } }, sqlTable);
+    }
+
+    const allRows: T[] = [];
+    let lastRawContext: any = null;
+
+    for (let i = 0; i < uniqueIds.length; i += batchSize) {
+      const batchIds = uniqueIds.slice(i, i + batchSize);
+      const batchResult = await this.findList<T>(
+        { condition: { id: { $in: batchIds } } },
+        sqlTable
+      );
+      allRows.push(...batchResult.rows);
+      lastRawContext = batchResult.getRawContext();
+    }
+
+    return new CrudQueryListResult<T>({ rows: allRows, rawContext: lastRawContext });
+  }
+
+  /**
+   * 执行自定义 SQL 语句（经 CrudPro 框架封装处理）
+   * 与 executeNativeSQL 不同，此方法执行的 SQL 会经过框架的参数绑定等安全处理
+   * @param executeSql 要执行的 SQL 语句，支持参数占位符
+   * @param args SQL 参数数组，与占位符一一对应
+   * @returns 返回未被包装的数据库原始结果（根据 resPicker 配置返回不同类型，无 {code, data, message} 包装层）
+   */
+  public async executeSQL(executeSql: string, args?: any[]): Promise<ExecuteSQLResult> {
+    const sqlCfgModel: ISqlCfgModel = {
+      executeSql: executeSql,
+      executeSqlArgs: args,
+      sqlDatabase: this.sqlDatabase,
+      sqlDbType: this.sqlDbType,
+      maxLimit: this.baseCfgModel.maxLimit || DEFAULT_MAX_LIMIT,
+    };
+    return await this.crudProFactory().executeSQL(sqlCfgModel);
+  }
+
+
+  /**
+   * 执行数据库的原生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 行数据的类型，默认 Record<string, any>。
+   * 影响的是 ExecuteSQLRowsResult 和 ExecuteSQLSingleResult 中的行类型
+   *
+   * @param executeNativeSql 原生 SQL 语句，使用 `?` 作为参数占位符
+   * @param args 参数数组，与 SQL 中的 `?` 一一对应
+   * @returns 根据 SQL 类型返回对应结果（ExecuteSQLResult 联合类型）
+   *
+   * @example
+   * // SELECT 查询 - 使用自定义行类型，返回 ExecuteSQLRowsResult
+   * const rows = await crudProQuick.executeNativeSQL<{id: number, name: string}>(
+   *   'SELECT id, name FROM user WHERE age > ?',
+   *   [18]
+   * );
+   * // rows 类型为 ExecuteSQLResult<{id: number, name: string}>
+   * // 实际运行时如果是 SELECT 查询，返回的是 ExecuteSQLRowsResult<{id: number, name: string}>
+   *
+   * // INSERT - MySQL
+   * const result = await crudProQuick.executeNativeSQL(
+   *   'INSERT INTO user (name, age) VALUES (?, ?)',
+   *   ['张三', 20]
+   * );
+   * // result 类型为 ExecuteSQLResult，实际运行时返回 ExecuteSQLUpdateResult
+   */
+  public async executeNativeSQL<T = Record<string, any>>(executeNativeSql: string, args?: any[]): Promise<ExecuteSQLResult<T>> {
+    const sqlCfgModel: ISqlCfgModel = {
+      isNativeSQL: true,
+      executeSql: executeNativeSql,
+      executeSqlArgs: args,
+      sqlDatabase: this.sqlDatabase,
+      sqlDbType: this.sqlDbType,
+      maxLimit: this.baseCfgModel.maxLimit || DEFAULT_MAX_LIMIT,
+    };
+    return await this.crudProFactory().executeSQL(sqlCfgModel) as ExecuteSQLResult<T>;
+  }
+
+
+
+  
+
+  /**
+   * findOne 的快捷方式，直接返回 row
+   *
+   * @example
+   * const row = await quick.getOne({ condition: { id: 1 } });
+   * // 等价于 (await quick.findOne({ condition: { id: 1 } })).row
+   */
+  public async getOne(reqJson: IRequestModel, sqlTable?: string): Promise<Record<string, any>> {
+    const res = await this.findOne(reqJson, sqlTable);
+    return res.row;
+  }
+
+  /**
+   * findUniqueOne 的快捷方式，直接返回 row
+   *
+   * @example
+   * const row = await quick.getUniqueOne({ condition: { order_id: 'ORD001' } });
+   * // 等价于 (await quick.findUniqueOne({ condition: { order_id: 'ORD001' } })).row
+   */
+  public async getUniqueOne(reqJson: IRequestModel, sqlTable?: string): Promise<Record<string, any>> {
+    const res = await this.findUniqueOne(reqJson, sqlTable);
+    return res.row;
+  }
+
+  /**
+   * findList 的快捷方式，直接返回 rows
+   *
+   * @example
+   * const rows = await quick.getList({ condition: { status: 'active' } });
+   * // 等价于 (await quick.findList({ condition: { status: 'active' } })).rows
+   */
+  public async getList(reqJson: IRequestModel, sqlTable?: string): Promise<Record<string, any>[]> {
+    const res = await this.findList(reqJson, sqlTable);
+    return res.rows;
+  }
+
+  /**
+   * findCount 的快捷方式，直接返回 count
+   *
+   * @example
+   * const count = await quick.getCount({ condition: { status: 'active' } });
+   * // 等价于 (await quick.findCount({ condition: { status: 'active' } })).count
+   */
+  public async getCount(reqJson: IRequestModel, sqlTable?: string): Promise<number> {
+    const res = await this.findCount(reqJson, sqlTable);
+    return res.count;
+  }
+
+  /**
+   * isExist 的快捷方式，直接返回 exists
+   *
+   * @example
+   * const exists = await quick.getIsExist({ condition: { id: 1 } });
+   * // 等价于 (await quick.isExist({ condition: { id: 1 } })).exists
+   */
+  public async getIsExist(reqJson: IRequestModel, sqlTable?: string): Promise<boolean> {
+    const res = await this.isExist(reqJson, sqlTable);
+    return res.exists;
+  }
+
+  /**
+   * findOneById 的快捷方式，直接返回 row
+   *
+   * @example
+   * const row = await quick.getOneById(1);
+   * // 等价于 (await quick.findOneById(1)).row
+   */
+  public async getOneById(id: number | string, sqlTable?: string): Promise<Record<string, any>> {
+    const res = await this.findOneById(id, sqlTable);
+    return res.row;
+  }
+
+
+
+}