midway-fatcms 0.0.6 → 0.0.8

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

@@ -0,0 +1,594 @@
+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';
+
+const DEFAULT_MAX_LIMIT = 10 * 10000;
+
+/**
+ * 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;
+    enableSoftDelete?: boolean;
+    enableStandardUpdateCfg?: boolean;
+    enableStandardUpdateCfgCondition?: string[];
+    [key: string]: any;
+  } = {
+    maxLimit: DEFAULT_MAX_LIMIT,
+  };
+
+  /**
+   * 构造函数（工厂函数模式）
+   * @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 cfgModel: IRequestCfgModel = {
+      sqlTable,
+      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(sqlTable, reqJson.condition) });
+  }
+
+  /**
+   * 查询唯一单条记录（期望结果为 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) {
+      const debugInfo = this.buildDebugInfo(effectiveTable, reqJson.condition);
+      const errorMsg = this.formatUniqueError(rows.length, debugInfo);
+      throw new Error(errorMsg);
+    }
+    
+    return new CrudQueryOneResult<T>({ 
+      row: rows[0] || null, 
+      rawContext: ctx,
+      debugInfo: this.buildDebugInfo(effectiveTable, reqJson.condition),
+    });
+  }
+
+  /**
+   * 构建辅助定位信息
+   */
+  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;
+  }
+
+  /**
+   * 格式化唯一性错误消息
+   */
+  private formatUniqueError(foundCount: number, debugInfo: { sqlDatabase: string; sqlTable: string; condition?: Record<string, any> }): string {
+    const parts = [
+      `[CrudProQuick] findUniqueOne 期望唯一一条记录，但查询到 ${foundCount} 条`,
+    ];
+    
+    if (debugInfo.sqlDatabase) {
+      parts.push(`数据库: ${debugInfo.sqlDatabase}`);
+    }
+    if (debugInfo.sqlTable) {
+      parts.push(`表: ${debugInfo.sqlTable}`);
+    }
+    if (debugInfo.condition) {
+      try {
+        parts.push(`条件: ${JSON.stringify(debugInfo.condition)}`);
+      } catch {
+        parts.push(`条件: [无法序列化]`);
+      }
+    }
+    
+    return parts.join(' | ');
+  }
+
+  /**
+   * 查询数据列表
+   * @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）
+   * 内部使用 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({
+      affected: resModel.affected,
+      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,
+    });
+  }
+
+  /**
+   * 根据主键 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 列表查询多条记录
+   *
+   * 等价于 `findList({ condition: { id: { $in: ids } } })`，但更简洁。
+   *
+   * @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>> {
+    return this.findList<T>({ condition: { id: { $in: ids } } }, sqlTable);
+  }
+
+  /**
+   * 执行自定义 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>;
+  }
+
+}

package/src/{service/curd → libs/crud-pro-quick}/fixSoftDelete.ts

@@ -1,28 +1,38 @@
 import { KeysOfSimpleSQL } from "@/libs/crud-pro/models/keys";
-import { IRequestModel } from "@/libs/crud-pro/interfaces";
-import { IRequestCfgModel2 } from "@/models/bizmodels";
-import { Context } from "@midwayjs/koa";
-import type { ICommonStandardColumns } from "@/models/StandardColumns";
+import { IRequestModel, IVisitor } from "@/libs/crud-pro/interfaces";
+import { IRequestCfgModel2, ICommonStandardColumns } from "./models";
+
+/**
+ * 软删除需要的用户信息（最小子集）
+ */
+interface ISoftDeleteUserInfo {
+  accountId: string;
+}
+
+/**
+ * 获取当前用户信息的函数类型
+ */
+type GetCurrentUserFunc = () => ISoftDeleteUserInfo | null | undefined;
 
 /**
  * 软删除处理函数
- * 
+ *
  * 当 cfgModel.enableSoftDelete === true 时，自动处理软删除逻辑：
- * 
+ *
  * 1. INSERT 操作：自动设置 deleted_at = 0
  * 2. DELETE 操作：转为 UPDATE，设置 deleted_at = 时间戳, deleted_by = 当前用户
  * 3. QUERY 操作：自动添加 deleted_at = 0 条件
- * 
+ *
  * @param oldSqlSimpleName 原始 SQL 类型
  * @param cfgModel 配置模型
  * @param params 请求参数（会被修改）
- * @param ctx 请求上下文（用于获取当前用户信息）
+ * @param visitor 获取当前用户信息的函数（用于软删除时记录删除人）
  */
 function fixSoftDelete(
   oldSqlSimpleName: KeysOfSimpleSQL,
   cfgModel: IRequestCfgModel2,
   params: IRequestModel,
-  ctx?: Context
+  visitor?: IVisitor
 ): void {
 
   // 没有开启软删除，不做处理，直接物理删除
@@ -47,8 +57,6 @@ function fixSoftDelete(
       throw new Error('执行删除操作，必须指定删除条件');
     }
 
-    // 获取当前用户信息
-    const sessionInfo = ctx?.userSession?.getSessionInfo();
 
     // 在原有 data 对象上添加软删除字段
     if (!params.data) {
@@ -56,7 +64,7 @@ function fixSoftDelete(
     }
     const dataObj = params.data as ICommonStandardColumns;
     dataObj.deleted_at = Date.now();
-    dataObj.deleted_by = sessionInfo?.accountId || '';
+    dataObj.deleted_by = visitor?.accountId || '';
 
     // 改为执行 UPDATE 操作
     cfgModel.sqlSimpleName = KeysOfSimpleSQL.SIMPLE_UPDATE;
@@ -77,4 +85,6 @@ function fixSoftDelete(
 
 export {
   fixSoftDelete,
-}
+};
+
+export type { ISoftDeleteUserInfo, GetCurrentUserFunc };