midway-fatcms 0.0.7 → 0.0.9

package/dist/libs/crud-pro-quick/CrudProQuick.d.ts

@@ -0,0 +1,382 @@
+import { SqlDbType } from '../../libs/crud-pro/models/keys';
+import { IRequestModel, ExecuteSQLResult } from '../../libs/crud-pro/interfaces';
+import { CrudPro } from '../../libs/crud-pro/CrudPro';
+import { CrudWriteResult, CrudQueryOneResult, CrudQueryListResult, CrudQueryPageResult, CrudExistResult, CrudCountResult, CrudUpsertResult } from '../../libs/crud-pro/models/CrudResult';
+/**
+ * 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 declare class CrudProQuick {
+    private readonly crudProFactory;
+    private readonly sqlDbType;
+    private readonly sqlDatabase;
+    private readonly sqlTable?;
+    private baseCfgModel;
+    /**
+     * 构造函数（工厂函数模式）
+     * @param args 工厂函数参数
+     */
+    constructor(args: ICrudProQuickFactory);
+    /**
+     * 设置基础配置模型，合并到实例的 baseCfgModel 中，后续所有 CRUD 操作都会携带这些配置
+     * 例如可以统一设置 maxLimit、enableSoftDelete 等公共参数，避免每次调用都重复传入
+     * @param baseCfgModel 要合并的配置项
+     */
+    setBaseCfgModel(baseCfgModel: Record<string, any>): void;
+    private executeCrudByCfg;
+    /**
+     * 查询单条记录
+     * @param reqJson 请求参数
+     * @param sqlTable 数据库表名称
+     * @returns CrudQueryOneResult 包含 row、found 和 getRawContext()
+     */
+    findOne<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryOneResult<T>>;
+    /**
+     * 查询唯一单条记录（期望结果为 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);
+   * }
+     */
+    findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryOneResult<T>>;
+    /**
+     * 构建辅助定位信息
+     */
+    private buildDebugInfo;
+    /**
+     * 查询数据列表
+     * @param reqJson 请求参数
+     * @param sqlTable 数据库表名称
+     * @returns CrudQueryListResult 包含 rows、count 和 getRawContext()
+     */
+    findList<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryListResult<T>>;
+    /**
+     * 分页查询数据列表
+     * 内部使用 SIMPLE_QUERY_PAGE 模式，reqJson 中可传入 pageNo、pageSize 控制分页
+     * @param reqJson 请求参数，支持 condition（查询条件）、pageNo、pageSize 等
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns CrudQueryPageResult 包含 rows、totalCount、count 和 getRawContext()
+     */
+    findPage<T = Record<string, any>>(reqJson: IRequestModel, sqlTable?: string): Promise<CrudQueryPageResult<T>>;
+    /**
+     * 判断满足条件的记录是否存在
+     * 内部使用 SIMPLE_QUERY_EXIST 模式，通过 SELECT EXISTS 子查询实现，找到首条匹配即返回，比 COUNT(*) 更高效
+     * @param reqJson 请求参数，通过 condition 指定查询条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns CrudExistResult 包含 exists 和 getRawContext()
+     */
+    isExist(reqJson: IRequestModel, sqlTable?: string): Promise<CrudExistResult>;
+    /**
+     * 查询满足条件的记录总数
+     * 内部使用 SIMPLE_QUERY_COUNT 模式，仅返回 count 结果
+     * @param reqJson 请求参数，通过 condition 指定查询条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns CrudCountResult 包含 count 和 getRawContext()
+     */
+    findCount(reqJson: IRequestModel, sqlTable?: string): Promise<CrudCountResult>;
+    /**
+     * 插入一条数据记录
+     * 内部使用 SIMPLE_INSERT 模式，通过 reqJson.data 传入要插入的字段和值
+     * @param reqJson 请求参数，data 字段中包含要插入的键值对
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns CrudWriteResult 包含 affectedRows、insertId 和 getRawContext()
+     */
+    insert(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult>;
+    /**
+     * 批量插入数据记录
+     * 内部使用 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
+     */
+    batchInsert(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult>;
+    /**
+     * 更新数据记录
+     * 内部使用 SIMPLE_UPDATE 模式，通过 reqJson.data 传入要更新的字段和值，通过 reqJson.condition 指定更新条件
+     * @param reqJson 请求参数，data 为更新内容，condition 为更新条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
+     */
+    update(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult>;
+    /**
+     * 插入或更新数据记录（upsert）
+     * 限制：
+     *  - 必须有condition字段，用于判断记录是否存在
+     *  - 必须有data字段，用于指定插入/更新的内容
+     * 内部使用 SIMPLE_INSERT_OR_UPDATE 模式，若记录已存在则更新，不存在则插入
+     * @param reqJson 请求参数，data 为要插入/更新的内容，condition 为判断条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns CrudUpsertResult 包含 affected、insertAffected、updateAffected、isExist 和 getRawContext()
+     */
+    insertOrUpdate(reqJson: IRequestModel, sqlTable?: string): Promise<CrudUpsertResult>;
+    /**
+     * 使用数据库原生 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()
+     */
+    insertOnDuplicateUpdate(reqJson: IRequestModel, uniqueColumn?: string[], sqlTable?: string): Promise<CrudWriteResult>;
+    /**
+     * 删除数据记录
+     * 内部使用 SIMPLE_DELETE 模式，通过 reqJson.condition 指定删除条件
+     * 注意：如果启用了软删除，实际执行的是更新操作而非物理删除
+     * @param reqJson 请求参数，condition 为删除条件
+     * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
+     * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
+     */
+    delete(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult>;
+    /**
+     * 恢复软删除的记录
+     * 将 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' } });
+     */
+    restore(reqJson: IRequestModel, sqlTable?: string): Promise<CrudWriteResult>;
+    /**
+     * 保存数据记录（自动判断 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: '王五' } });
+     */
+    save(reqJson: IRequestModel, sqlTable?: string): Promise<CrudUpsertResult>;
+    /**
+     * 获取表的主键列名列表
+     *
+     * 委托给 CrudPro.getPrimaryKeyColumns，复用 CrudProTableMetaService 的 getTableMeta 缓存，
+     * 避免重复查询数据库。
+     *
+     * @param sqlTable 表名
+     * @returns 主键列名数组，如果查询失败返回 ['id'] 作为保守默认值
+     */
+    private getPrimaryKeyColumns;
+    /**
+     * 根据主键 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');
+     */
+    findOneById<T = Record<string, any>>(id: number | string, sqlTable?: string): Promise<CrudQueryOneResult<T>>;
+    /**
+     * 根据主键 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');
+     */
+    findListByIds<T = Record<string, any>>(ids: (number | string)[], sqlTable?: string): Promise<CrudQueryListResult<T>>;
+    /**
+     * 执行自定义 SQL 语句（经 CrudPro 框架封装处理）
+     * 与 executeNativeSQL 不同，此方法执行的 SQL 会经过框架的参数绑定等安全处理
+     * @param executeSql 要执行的 SQL 语句，支持参数占位符
+     * @param args SQL 参数数组，与占位符一一对应
+     * @returns 返回未被包装的数据库原始结果（根据 resPicker 配置返回不同类型，无 {code, data, message} 包装层）
+     */
+    executeSQL(executeSql: string, args?: any[]): Promise<ExecuteSQLResult>;
+    /**
+     * 执行数据库的原生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
+     */
+    executeNativeSQL<T = Record<string, any>>(executeNativeSql: string, args?: any[]): Promise<ExecuteSQLResult<T>>;
+    /**
+     * findOne 的快捷方式，直接返回 row
+     *
+     * @example
+     * const row = await quick.getOne({ condition: { id: 1 } });
+     * // 等价于 (await quick.findOne({ condition: { id: 1 } })).row
+     */
+    getOne(reqJson: IRequestModel, sqlTable?: string): Promise<Record<string, any>>;
+    /**
+     * findUniqueOne 的快捷方式，直接返回 row
+     *
+     * @example
+     * const row = await quick.getUniqueOne({ condition: { order_id: 'ORD001' } });
+     * // 等价于 (await quick.findUniqueOne({ condition: { order_id: 'ORD001' } })).row
+     */
+    getUniqueOne(reqJson: IRequestModel, sqlTable?: string): Promise<Record<string, any>>;
+    /**
+     * findList 的快捷方式，直接返回 rows
+     *
+     * @example
+     * const rows = await quick.getList({ condition: { status: 'active' } });
+     * // 等价于 (await quick.findList({ condition: { status: 'active' } })).rows
+     */
+    getList(reqJson: IRequestModel, sqlTable?: string): Promise<Record<string, any>[]>;
+    /**
+     * findCount 的快捷方式，直接返回 count
+     *
+     * @example
+     * const count = await quick.getCount({ condition: { status: 'active' } });
+     * // 等价于 (await quick.findCount({ condition: { status: 'active' } })).count
+     */
+    getCount(reqJson: IRequestModel, sqlTable?: string): Promise<number>;
+    /**
+     * isExist 的快捷方式，直接返回 exists
+     *
+     * @example
+     * const exists = await quick.getIsExist({ condition: { id: 1 } });
+     * // 等价于 (await quick.isExist({ condition: { id: 1 } })).exists
+     */
+    getIsExist(reqJson: IRequestModel, sqlTable?: string): Promise<boolean>;
+    /**
+     * findOneById 的快捷方式，直接返回 row
+     *
+     * @example
+     * const row = await quick.getOneById(1);
+     * // 等价于 (await quick.findOneById(1)).row
+     */
+    getOneById(id: number | string, sqlTable?: string): Promise<Record<string, any>>;
+}