midway-fatcms 0.0.4 → 0.0.6

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

@@ -0,0 +1,363 @@
+import { CrudPro } from '../../libs/crud-pro/CrudPro';
+import { IRequestModel, IRequestCfgModel } from '../../libs/crud-pro/interfaces';
+import { ExecuteContext } from '../../libs/crud-pro/models/ExecuteContext';
+import { IShardingConfig } from './ShardingConfig';
+import { IShardingPageQueryResult } from './ShardingMerger';
+/**
+ * 智能批量插入结果
+ */
+export interface IShardingSmartBatchInsertResult {
+    /** 总插入条数 */
+    totalAffected: number;
+    /** 各分表插入结果 */
+    tableResults: Array<{
+        table: string;
+        affected: number;
+        rowCount: number;
+    }>;
+    /** 涉及的分表数量 */
+    tableCount: number;
+    /** 是否全部成功 */
+    success: boolean;
+    /** 错误信息（如果有） */
+    errors: Array<{
+        table: string;
+        error: Error;
+    }>;
+}
+/**
+ * 分表 CRUD 操作封装器
+ *
+ * 在 CrudPro 之上封装分表功能，不修改 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
+ * // 按月分表
+ * 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 declare class ShardingCrudPro {
+    private readonly crudPro;
+    private readonly config;
+    private readonly router;
+    private readonly merger;
+    private readonly tableCreator;
+    private baseCfg;
+    constructor(crudPro: CrudPro, config: IShardingConfig);
+    /**
+     * 设置基础配置（会应用到所有操作）
+     *
+     * @param cfg 配置项，如 sqlDatabase、sqlDbType 等
+     * @returns this，支持链式调用
+     *
+     * @example
+     * sharding.setBaseCfg({
+     *   sqlDatabase: 'mydb',
+     *   sqlDbType: SqlDbType.mysql,
+     * });
+     */
+    setBaseCfg(cfg: Partial<IRequestCfgModel>): this;
+    /**
+     * 获取分表配置
+     */
+    getConfig(): IShardingConfig;
+    /**
+     * 插入数据
+     *
+     * 根据分表规则自动路由到目标分表。
+     * 对于时间分表，需要确保 data 中包含时间字段。
+     * 对于哈希/范围分表，需要确保 data 中包含分表字段。
+     *
+     * 如果目标分表不存在且配置了 autoCreateTable，会自动创建分表。
+     *
+     * @param reqJson 请求参数，data 为要插入的数据
+     * @returns 执行上下文
+     *
+     * @example
+     * await sharding.insert({
+     *   data: {
+     *     order_id: 'ORD001',
+     *     amount: 100,
+     *     created_at: '2024-03-15 10:00:00',
+     *   },
+     * });
+     */
+    insert(reqJson: IRequestModel): Promise<ExecuteContext>;
+    /**
+     * 批量插入数据（支持跨分表）
+     *
+     * 自动将数据按分表分组，并行插入到对应的分表。
+     *
+     * @param reqJson 请求参数，data 为要插入的数据数组
+     * @returns 批量插入结果
+     *
+     * 执行流程：
+     * 1. 遍历所有数据，根据分表字段计算目标分表
+     * 2. 将数据按分表分组
+     * 3. 并行执行各分表的批量插入
+     * 4. 汇总结果返回
+     *
+     * @example
+     * // 数据分布在不同月份的分表
+     * const result = await sharding.batchInsert({
+     *   data: [
+     *     { order_id: '001', amount: 100, created_at: '2024-01-15' },  // -> t_order_202401
+     *     { order_id: '002', amount: 200, created_at: '2024-01-20' },  // -> t_order_202401
+     *     { order_id: '003', amount: 150, created_at: '2024-02-10' },  // -> t_order_202402
+     *     { order_id: '004', amount: 300, created_at: '2024-03-05' },  // -> t_order_202403
+     *   ],
+     * });
+     *
+     * console.log(result.totalAffected);    // 4
+     * console.log(result.tableCount);       // 3
+     * console.log(result.tableResults);
+     * // [
+     * //   { table: 't_order_202401', affected: 2, rowCount: 2 },
+     * //   { table: 't_order_202402', affected: 1, rowCount: 1 },
+     * //   { table: 't_order_202403', affected: 1, rowCount: 1 },
+     * // ]
+     */
+    batchInsert(reqJson: IRequestModel): Promise<IShardingSmartBatchInsertResult>;
+    /**
+     * 更新数据
+     *
+     * 根据条件中的分表字段自动路由到目标分表。
+     *
+     * @param reqJson 请求参数，condition 为更新条件，data 为更新数据
+     * @returns 执行上下文
+     *
+     * @example
+     * await sharding.update({
+     *   condition: { order_id: 'ORD001', created_at: '2024-03-15' },
+     *   data: { amount: 200 },
+     * });
+     */
+    update(reqJson: IRequestModel): Promise<ExecuteContext>;
+    /**
+     * 删除数据
+     *
+     * 根据条件中的分表字段自动路由到目标分表。
+     *
+     * @param reqJson 请求参数，condition 为删除条件
+     * @returns 执行上下文
+     */
+    delete(reqJson: IRequestModel): Promise<ExecuteContext>;
+    /**
+     * 插入或更新（存在则更新，不存在则插入）
+     *
+     * 路由逻辑：根据 condition 路由（先查询是否存在）
+     *
+     * @param reqJson 请求参数
+     * @returns 执行上下文
+     */
+    insertOrUpdate(reqJson: IRequestModel): Promise<ExecuteContext>;
+    /**
+     * 插入或更新（ON DUPLICATE KEY UPDATE）
+     *
+     * 路由逻辑：根据 condition 路由（先查询是否存在）
+     *
+     * @param reqJson 请求参数
+     * @returns 执行上下文
+     */
+    insertOnDuplicateUpdate(reqJson: IRequestModel): Promise<ExecuteContext>;
+    /**
+     * 查询单条记录
+     *
+     * 如果能根据条件确定单一分表，则查询单表；
+     * 否则按顺序查询各分表，返回第一条匹配记录。
+     *
+     * @param reqJson 请求参数，condition 为查询条件
+     * @returns 单条记录，未找到返回 null
+     *
+     * @example
+     * const order = await sharding.queryOne({
+     *   condition: { order_id: 'ORD001' },
+     * });
+     */
+    queryOne(reqJson: IRequestModel): Promise<any>;
+    /**
+     * 查询列表
+     *
+     * 可能涉及多个分表，结果会自动合并。
+     *
+     * 使用约束：
+     * - 必须传 orderBy 参数
+     * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
+     *
+     * @param reqJson 请求参数
+     * @returns 数据列表
+     *
+     * @example
+     * const orders = await sharding.query({
+     *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
+     *   orderBy: 'created_at DESC',  // 或 'created_at ASC'
+     * });
+     */
+    query(reqJson: IRequestModel): Promise<any[]>;
+    /**
+     * 分页查询
+     *
+     * 自动处理跨分表的分页：
+     * 1. 顺序累计查询各分表
+     * 2. 截取目标数据（无需排序）
+     *
+     * 使用约束：
+     * - 必须传 orderBy 参数
+     * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
+     *
+     * @param reqJson 请求参数，包含 pageNo、pageSize 和 orderBy
+     * @returns 分页结果，包含 rows 和 total_count
+     *
+     * @example
+     * const result = await sharding.queryPage({
+     *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
+     *   pageNo: 1,
+     *   pageSize: 10,
+     *   orderBy: 'created_at DESC',  // 或 'created_at ASC'
+     * });
+     * console.log(result.rows, result.total_count);
+     */
+    queryPage(reqJson: IRequestModel): Promise<IShardingPageQueryResult>;
+    /**
+     * 查询记录总数
+     *
+     * 如果涉及多个分表，会并行查询各分表并汇总。
+     *
+     * @param reqJson 请求参数
+     * @returns 记录总数
+     */
+    queryCount(reqJson: IRequestModel): Promise<number>;
+    /**
+     * 判断记录是否存在
+     *
+     * 如果涉及多个分表，会并行查询，任一分表存在即返回 true。
+     *
+     * @param reqJson 请求参数
+     * @returns 是否存在
+     */
+    isExist(reqJson: IRequestModel): Promise<boolean>;
+    /**
+     * 【batchInsert 专用】按分表对数据进行分组
+     *
+     * 仅用于 batchInsert 方法，遍历所有数据项，
+     * 根据分表规则计算每条数据的目标分表，将相同分表的数据归为一组。
+     *
+     * @param dataArray 数据数组
+     * @returns 分表 -> 数据列表 的映射
+     */
+    private batchInsertGroupDataByTable;
+    private batchInsertResolveTableForData;
+    /**
+     * 解析单个目标表
+     *
+     * 写操作必须确定单一目标表，否则抛出异常。
+     */
+    private resolveSingleTable;
+    /**
+     * 获取分表字段提示
+     */
+    private getShardingColumnHint;
+    /**
+     * 构建配置
+     */
+    private buildCfg;
+    /**
+     * 在指定表上执行操作
+     */
+    private executeOnTable;
+    /**
+     * 从指定表查询单条
+     */
+    private queryOneFromTable;
+    /**
+     * 从指定表查询数量
+     */
+    private queryCountFromTable;
+    /**
+     * 判断指定表中是否存在记录
+     */
+    private isExistInTable;
+    /**
+     * 获取数据库中真实存在的表名集合
+     */
+    private getExistingTablesSet;
+    /**
+     * 检查表是否存在
+     */
+    private isTableExists;
+    /**
+     * 创建分表（如果需要）
+     *
+     * 根据配置检查分表是否存在：
+     * - 如果分表已存在，直接返回
+     * - 如果分表不存在且 autoCreateTable=true，自动创建
+     * - 如果分表不存在且 autoCreateTable=false，抛出异常
+     *
+     * @param tableName 目标分表名
+     */
+    private createShardingTableIfNeeded;
+    /**
+     * 校验查询参数的 orderBy 是否符合约束
+     *
+     * 约束条件：
+     * - 必须传 orderBy 参数
+     * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
+     *
+     * 这是时间分表查询的核心约束：
+     * - 排序字段必须是分表字段（timeColumn），不允许其他字段
+     * - DESC 时表顺序为 新→旧，ASC 时表顺序为 旧→新（由调用方反转）
+     * - 这样无需内存排序，直接按表顺序拼接即可
+     *
+     * @param reqJson 请求参数
+     */
+    private validateQueryOrderBy;
+    /**
+     * 判断 orderBy 是否为 ASC 方向
+     *
+     * 前提：validateQueryOrderBy 已通过校验，orderBy 格式合法
+     *
+     * @param reqJson 请求参数
+     * @returns true 表示 ASC，false 表示 DESC
+     */
+    private isAscOrderBy;
+    /**
+     * 根据排序方向对分表列表进行排序
+     *
+     * 分表名后缀为时间格式（如 202403、20240101），字典序即时间序。
+     * - DESC：降序排列（新→旧）
+     * - ASC：升序排列（旧→新）
+     *
+     * @param tables 分表列表
+     * @param reqJson 请求参数
+     * @returns 排序后的分表列表（新数组，不修改原数组）
+     */
+    private sortTablesForOrderBy;
+    /**
+     * 解析查询表（带真实表过滤）
+     *
+     * 将查询路由委托给 ShardingRouter.resolveQuery，
+     * 由 ShardingRouter 统一处理所有查询路由逻辑。
+     */
+    private resolveQueryTables;
+}