midway-fatcms 0.0.7 → 0.0.9

package/src/libs/crud-sharding/ShardingCrudPro.ts

@@ -1,835 +0,0 @@
-import { CrudPro } from '@/libs/crud-pro/CrudPro';
-import { IRequestModel, IRequestCfgModel } from '@/libs/crud-pro/interfaces';
-import { OrderByUtils } from '@/libs/crud-pro/utils/OrderByUtils';
-import { ExecuteContext } from '@/libs/crud-pro/models/ExecuteContext';
-import { KeysOfSimpleSQL } from '@/libs/crud-pro/models/keys';
-import { ShardingType, IShardingConfig, IShardingRouterContext } from './ShardingConfig';
-import { ShardingRouter, ITableInfoProvider } from './ShardingRouter';
-import { ShardingMerger, IShardingPageQueryResult } from './ShardingMerger';
-import { ShardingTableCreator } from './ShardingTableCreator';
-import { ShardingCountCache } from './ShardingCountCache';
-
-/**
- * 智能批量插入结果
- */
-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 class ShardingCrudPro {
-  private readonly crudPro: CrudPro;
-  private readonly config: IShardingConfig;
-  private readonly router: ShardingRouter;
-  private readonly merger: ShardingMerger;
-  private readonly tableCreator: ShardingTableCreator;
-
-  private baseCfg: Partial<IRequestCfgModel> = {};
-
-  constructor(crudPro: CrudPro, config: IShardingConfig) {
-    this.crudPro = crudPro;
-    this.config = config;
-
-    // 时间分表必须显式指定 timeColumn
-    if ([ShardingType.YEAR, ShardingType.MONTH, ShardingType.DAY].includes(config.type)) {
-      if (!config.timeColumn) {
-        throw new Error('[ShardingCrudPro] 时间分表（YEAR/MONTH/DAY）必须显式指定 timeColumn 字段');
-      }
-    }
-
-    this.router = new ShardingRouter();
-    this.merger = new ShardingMerger();
-    this.tableCreator = new ShardingTableCreator(crudPro, config);
-
-    // 初始化 COUNT 缓存（如果配置了）
-    if (config.countCache) {
-      const countCache = new ShardingCountCache(
-        config.type,
-        config.baseTable,
-        config.countCache.ttlSeconds,
-        config.countCache.maxSize
-      );
-      this.merger.setCountCache(countCache);
-    }
-  }
-
-  // ============ 配置方法 ============
-
-  /**
-   * 设置基础配置（会应用到所有操作）
-   *
-   * @param cfg 配置项，如 sqlDatabase、sqlDbType 等
-   * @returns this，支持链式调用
-   *
-   * @example
-   * sharding.setBaseCfg({
-   *   sqlDatabase: 'mydb',
-   *   sqlDbType: SqlDbType.mysql,
-   * });
-   */
-  public setBaseCfg(cfg: Partial<IRequestCfgModel>): this {
-    this.baseCfg = { ...this.baseCfg, ...cfg };
-    return this;
-  }
-
-  /**
-   * 获取分表配置
-   */
-  public getConfig(): IShardingConfig {
-    return this.config;
-  }
-
-  // ============ 写操作（单表路由） ============
-
-  /**
-   * 插入数据
-   *
-   * 根据分表规则自动路由到目标分表。
-   * 对于时间分表，需要确保 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',
-   *   },
-   * });
-   */
-  public async insert(reqJson: IRequestModel): Promise<ExecuteContext> {
-    const targetTable = this.resolveSingleTable(reqJson, 'insert');
-
-    // 确保分表存在（根据配置决定是否自动创建）
-    await this.createShardingTableIfNeeded(targetTable);
-
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT);
-  }
-
-  /**
-   * 批量插入数据（支持跨分表）
-   *
-   * 自动将数据按分表分组，并行插入到对应的分表。
-   *
-   * @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 },
-   * // ]
-   */
-  public async batchInsert(reqJson: IRequestModel): Promise<IShardingSmartBatchInsertResult> {
-    const dataArray = reqJson.data as Record<string, any>[];
-
-    if (!Array.isArray(dataArray) || dataArray.length === 0) {
-      return {
-        totalAffected: 0,
-        tableResults: [],
-        tableCount: 0,
-        success: true,
-        errors: [],
-      };
-    }
-
-    // 按分表分组
-    const groupedData = this.batchInsertGroupDataByTable(dataArray);
-
-    // 确保所有目标分表存在（根据配置决定是否自动创建）
-    const tableNames = Array.from(groupedData.keys());
-    for (let i = 0; i < tableNames.length; i++) {
-      await this.createShardingTableIfNeeded(tableNames[i]);
-    }
-
-    // 并行执行各分表的批量插入
-    const insertPromises = Array.from(groupedData.entries()).map(async ([table, items]) => {
-      try {
-        const ctx = await this.executeOnTable(table, { data: items }, KeysOfSimpleSQL.SIMPLE_BATCH_INSERT);
-        return {
-          table,
-          affected: ctx.getResModelItem('affected') || items.length,
-          rowCount: items.length,
-          error: null as Error | null,
-        };
-      } catch (e) {
-        return {
-          table,
-          affected: 0,
-          rowCount: items.length,
-          error: e as Error,
-        };
-      }
-    });
-
-    const results = await Promise.all(insertPromises);
-
-    // 汇总结果
-    const tableResults = results.map(r => ({
-      table: r.table,
-      affected: r.affected,
-      rowCount: r.rowCount,
-    }));
-
-    const errors = results
-      .filter(r => r.error !== null)
-      .map(r => ({ table: r.table, error: r.error! }));
-
-    const totalAffected = results.reduce((sum, r) => sum + r.affected, 0);
-
-    return {
-      totalAffected,
-      tableResults,
-      tableCount: groupedData.size,
-      success: errors.length === 0,
-      errors,
-    };
-  }
-
-  /**
-   * 更新数据
-   *
-   * 根据条件中的分表字段自动路由到目标分表。
-   *
-   * @param reqJson 请求参数，condition 为更新条件，data 为更新数据
-   * @returns 执行上下文
-   *
-   * @example
-   * await sharding.update({
-   *   condition: { order_id: 'ORD001', created_at: '2024-03-15' },
-   *   data: { amount: 200 },
-   * });
-   */
-  public async update(reqJson: IRequestModel): Promise<ExecuteContext> {
-    const targetTable = this.resolveSingleTable(reqJson, 'update');
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
-  }
-
-  /**
-   * 删除数据
-   *
-   * 根据条件中的分表字段自动路由到目标分表。
-   *
-   * @param reqJson 请求参数，condition 为删除条件
-   * @returns 执行上下文
-   */
-  public async delete(reqJson: IRequestModel): Promise<ExecuteContext> {
-    const targetTable = this.resolveSingleTable(reqJson, 'delete');
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_DELETE);
-  }
-
-  /**
-   * 插入或更新（存在则更新，不存在则插入）
-   *
-   * 路由逻辑：根据 condition 路由（先查询是否存在）
-   *
-   * @param reqJson 请求参数
-   * @returns 执行上下文
-   */
-  public async insertOrUpdate(reqJson: IRequestModel): Promise<ExecuteContext> {
-    const targetTable = this.resolveSingleTable(reqJson, 'update');  // 使用 condition 路由
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE);
-  }
-
-  /**
-   * 插入或更新（ON DUPLICATE KEY UPDATE）
-   *
-   * 路由逻辑：根据 condition 路由（先查询是否存在）
-   *
-   * @param reqJson 请求参数
-   * @returns 执行上下文
-   */
-  public async insertOnDuplicateUpdate(reqJson: IRequestModel): Promise<ExecuteContext> {
-    const targetTable = this.resolveSingleTable(reqJson, 'update');  // 使用 condition 路由
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE);
-  }
-
-  // ============ 查询操作（可能多表） ============
-
-  /**
-   * 查询单条记录
-   *
-   * 如果能根据条件确定单一分表，则查询单表；
-   * 否则按顺序查询各分表，返回第一条匹配记录。
-   *
-   * @param reqJson 请求参数，condition 为查询条件
-   * @returns 单条记录，未找到返回 null
-   *
-   * @example
-   * const order = await sharding.queryOne({
-   *   condition: { order_id: 'ORD001' },
-   * });
-   */
-  public async queryOne(reqJson: IRequestModel): Promise<any> {
-    const targetTables = await this.resolveQueryTables(reqJson);
-
-    if (targetTables.length === 0) {
-      return null; // 无匹配表
-    }
-
-    // 多表：顺序查询，找到即返回
-    for (const table of targetTables) {
-      const result = await this.queryOneFromTable(table, reqJson);
-      if (result) return result;
-    }
-    return null;
-  }
-
-  /**
-   * 查询列表
-   *
-   * 可能涉及多个分表，结果会自动合并。
-   *
-   * 使用约束：
-   * - 必须传 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'
-   * });
-   */
-  public async query(reqJson: IRequestModel): Promise<any[]> {
-
-
-    const targetTables = await this.resolveQueryTables(reqJson);
-
-    if (targetTables.length === 0) {
-      return []; // 无匹配表，返回空结果
-    }
-
-    if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY);
-      return ctx.getResRows();
-    }
-
-    // 多表查询时，需要参数校验
-    this.validateQueryOrderBy(reqJson);
-
-    // 根据排序方向确定表顺序：DESC 新→旧，ASC 旧→新
-    const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
-
-    // 多表查询合并
-    return this.merger.mergeQuery(
-      this.crudPro,
-      tablesForMerge,
-      reqJson,
-      this.buildCfg(KeysOfSimpleSQL.SIMPLE_QUERY)
-    );
-  }
-
-  /**
-   * 分页查询
-   *
-   * 自动处理跨分表的分页：
-   * 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);
-   */
-  public async queryPage(reqJson: IRequestModel): Promise<IShardingPageQueryResult> {
-
-    const targetTables = await this.resolveQueryTables(reqJson);
-
-    if (targetTables.length === 0) {
-      return { rows: [], total_count: 0 }; // 无匹配表
-    }
-
-    if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
-      return ctx.getResModelForQueryPage();
-    }
-
-    // 多表查询时，需要参数校验
-    this.validateQueryOrderBy(reqJson);
-
-    // 根据排序方向确定表顺序：DESC 新→旧，ASC 旧→新
-    const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
-
-    // 多表分页查询：顺序累计
-    return this.merger.mergePageQuery(
-      this.crudPro,
-      tablesForMerge,
-      reqJson,
-      this.buildCfg(KeysOfSimpleSQL.SIMPLE_QUERY_PAGE)
-    );
-  }
-
-  /**
-   * 查询记录总数
-   *
-   * 如果涉及多个分表，会并行查询各分表并汇总。
-   *
-   * @param reqJson 请求参数
-   * @returns 记录总数
-   */
-  public async queryCount(reqJson: IRequestModel): Promise<number> {
-    const targetTables = await this.resolveQueryTables(reqJson);
-
-    if (targetTables.length === 0) {
-      return 0; // 无匹配表
-    }
-
-    if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
-      return ctx.getResModelItem('total_count') || 0;
-    }
-
-    // 多表统计：并行查询后求和
-    const countPromises = targetTables.map(table =>
-      this.queryCountFromTable(table, reqJson)
-    );
-    const counts = await Promise.all(countPromises);
-    return counts.reduce((sum, c) => sum + c, 0);
-  }
-
-  /**
-   * 判断记录是否存在
-   *
-   * 如果涉及多个分表，会并行查询，任一分表存在即返回 true。
-   *
-   * @param reqJson 请求参数
-   * @returns 是否存在
-   */
-  public async isExist(reqJson: IRequestModel): Promise<boolean> {
-    const targetTables = await this.resolveQueryTables(reqJson);
-
-    if (targetTables.length === 0) {
-      return false; // 无匹配表
-    }
-
-    if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
-      return ctx.getResModelItem('is_exist') === true;
-    }
-
-    // 多表判断：任一表存在即返回 true
-    const promises = targetTables.map(table =>
-      this.isExistInTable(table, reqJson)
-    );
-    const results = await Promise.all(promises);
-    return results.some(exists => exists);
-  }
-
-  // ============ 私有方法：分表路由 ============
-
-  /**
-   * 【batchInsert 专用】按分表对数据进行分组
-   *
-   * 仅用于 batchInsert 方法，遍历所有数据项，
-   * 根据分表规则计算每条数据的目标分表，将相同分表的数据归为一组。
-   *
-   * @param dataArray 数据数组
-   * @returns 分表 -> 数据列表 的映射
-   */
-  private batchInsertGroupDataByTable(dataArray: Record<string, any>[]): Map<string, Record<string, any>[]> {
-    const groupedData = new Map<string, Record<string, any>[]>();
-
-    for (const item of dataArray) {
-      const targetTable = this.batchInsertResolveTableForData(item);
-
-      if (!groupedData.has(targetTable)) {
-        groupedData.set(targetTable, []);
-      }
-      groupedData.get(targetTable)!.push(item);
-    }
-
-    return groupedData;
-  }
-
-  private batchInsertResolveTableForData(item: Record<string, any>): string {
-    const context: IShardingRouterContext = {
-      config: this.config,
-      data: item,
-    };
-
-    // 批量插入使用 resolveForInsert，确保返回单一表名
-    return this.router.resolveForInsert(this.config, context);
-  }
-
-  /**
-   * 解析单个目标表
-   *
-   * 写操作必须确定单一目标表，否则抛出异常。
-   */
-  private resolveSingleTable(
-    reqJson: IRequestModel,
-    operation: 'insert' | 'update' | 'delete'
-  ): string {
-    // insert 操作使用 resolveForInsert（从 data 提取字段）
-    if (operation === 'insert') {
-      const context: IShardingRouterContext = {
-        config: this.config,
-        data: reqJson.data as Record<string, any>,
-      };
-      return this.router.resolveForInsert(this.config, context);
-    }
-
-    // 其他操作使用 resolveForCondition（从 condition 提取字段）
-    const context: IShardingRouterContext = {
-      config: this.config,
-      condition: reqJson.condition,
-    };
-    const result = this.router.resolveForCondition(this.config, context);
-
-    if (Array.isArray(result)) {
-      throw new Error(
-        `[ShardingCrudPro] ${operation} 操作必须能确定单一目标表，` +
-        `但分表规则返回了多个表: ${result.slice(0, 5).join(', ')}${result.length > 5 ? '...' : ''}。` +
-        `请检查 condition 中是否包含分表字段（${this.getShardingColumnHint()}）。`
-      );
-    }
-
-    return result;
-  }
-
-  /**
-   * 获取分表字段提示
-   */
-  private getShardingColumnHint(): string {
-    if (this.config.type === ShardingType.RANGE || this.config.type === ShardingType.HASH) {
-      return this.config.shardingColumn || '分表字段';
-    }
-    if ([ShardingType.YEAR, ShardingType.MONTH, ShardingType.DAY].includes(this.config.type)) {
-      return this.config.timeColumn || 'created_at';
-    }
-    return '分表字段';
-  }
-
-  // ============ 私有方法：配置构建 ============
-
-  /**
-   * 构建配置
-   */
-  private buildCfg(sqlSimpleName: KeysOfSimpleSQL): IRequestCfgModel {
-    return {
-      ...this.baseCfg,
-      sqlTable: this.config.baseTable,
-      sqlSimpleName,
-    };
-  }
-
-  // ============ 私有方法：执行操作 ============
-
-  /**
-   * 在指定表上执行操作
-   */
-  private async executeOnTable(
-    table: string,
-    reqJson: IRequestModel,
-    sqlSimpleName: KeysOfSimpleSQL
-  ): Promise<ExecuteContext> {
-    const cfg = this.buildCfg(sqlSimpleName);
-    cfg.sqlTable = table; // 替换为实际分表名
-
-    return this.crudPro.executeCrudByCfg(reqJson, cfg);
-  }
-
-  /**
-   * 从指定表查询单条
-   */
-  private async queryOneFromTable(table: string, reqJson: IRequestModel): Promise<any> {
-    try {
-      const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
-      return ctx.getOneObj();
-    } catch (e) {
-      // 表不存在时返回 null
-      return null;
-    }
-  }
-
-  /**
-   * 从指定表查询数量
-   */
-  private async queryCountFromTable(table: string, reqJson: IRequestModel): Promise<number> {
-    try {
-      const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
-      return ctx.getResModelItem('total_count') || 0;
-    } catch (e) {
-      // 表不存在时返回 0
-      return 0;
-    }
-  }
-
-  /**
-   * 判断指定表中是否存在记录
-   */
-  private async isExistInTable(table: string, reqJson: IRequestModel): Promise<boolean> {
-    try {
-      const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
-      return ctx.getResModelItem('is_exist') === true;
-    } catch (e) {
-      // 表不存在时返回 false
-      return false;
-    }
-  }
-
-  // ============ 表存在性检查和自动创建 ============
-
-  /**
-   * 获取数据库中真实存在的表名集合
-   */
-  private async getExistingTablesSet(): Promise<Set<string>> {
-    const { sqlDatabase, sqlDbType } = this.baseCfg;
-
-    if (!sqlDatabase || !sqlDbType) {
-      throw new Error('[ShardingCrudPro] 未配置 sqlDatabase 或 sqlDbType');
-    }
-
-    const { tables } = await this.crudPro.getAllTableInfos({
-      sqlDatabase,
-      sqlDbType: sqlDbType as any,
-    });
-
-    return new Set(tables.map(t => t.name));
-  }
-
-  /**
-   * 检查表是否存在
-   */
-  private async isTableExists(tableName: string): Promise<boolean> {
-    const existingSet = await this.getExistingTablesSet();
-    return existingSet.has(tableName);
-  }
-
-  /**
-   * 创建分表（如果需要）
-   *
-   * 根据配置检查分表是否存在：
-   * - 如果分表已存在，直接返回
-   * - 如果分表不存在且 autoCreateTable=true，自动创建
-   * - 如果分表不存在且 autoCreateTable=false，抛出异常
-   *
-   * @param tableName 目标分表名
-   */
-  private async createShardingTableIfNeeded(tableName: string): Promise<void> {
-    // 检查表是否已存在
-    if (await this.isTableExists(tableName)) {
-      return;
-    }
-
-    // 根据配置决定是否自动创建
-    if (!this.config.autoCreateTable) {
-      throw new Error(`[ShardingCrudPro] 分表 ${tableName} 不存在。请先创建分表，或设置 autoCreateTable: true 自动创建`);
-    }
-
-    // 检查数据库配置
-    if (!this.baseCfg.sqlDatabase || !this.baseCfg.sqlDbType) {
-      throw new Error('[ShardingCrudPro] 请先调用 setBaseCfg 设置数据库配置');
-    }
-
-    // 执行创建
-    const result = await this.tableCreator.createTableIfNeeded(
-      tableName,
-      {
-        sqlDatabase: this.baseCfg.sqlDatabase,
-        sqlDbType: this.baseCfg.sqlDbType,
-      },
-      this.config.tableCreateOptions
-    );
-
-    if (!result.success) {
-      throw result.error || new Error(`[ShardingCrudPro] 创建分表 ${tableName} 失败`);
-    }
-  }
-
-  // ============ 参数校验 ============
-
-  /**
-   * 校验查询参数的 orderBy 是否符合约束
-   *
-   * 约束条件：
-   * - 必须传 orderBy 参数
-   * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
-   *
-   * 这是时间分表查询的核心约束：
-   * - 排序字段必须是分表字段（timeColumn），不允许其他字段
-   * - DESC 时表顺序为 新→旧，ASC 时表顺序为 旧→新（由调用方反转）
-   * - 这样无需内存排序，直接按表顺序拼接即可
-   *
-   * @param reqJson 请求参数
-   */
-  private validateQueryOrderBy(reqJson: IRequestModel): void {
-    // 非时间分表不强制 orderBy 约束（多表合并排序由调用方自行保证）
-    const timeColumn = this.config.timeColumn;
-    if (!timeColumn) {
-      return;
-    }
-
-    const orderBy = reqJson.orderBy;
-
-    // 1. 必须传 orderBy
-    if (!orderBy) {
-      throw new Error(
-        `[ShardingCrudPro] 查询操作必须传 orderBy 参数。` +
-        `期望值: '${timeColumn} DESC' 或 '${timeColumn} ASC'`
-      );
-    }
-
-    // 2. 使用工具类解析并校验首个排序字段是否为 timeColumn
-    const firstOrderBy = OrderByUtils.getFirstOrderBy(orderBy);
-
-    if (!firstOrderBy) {
-      throw new Error(
-        `[ShardingCrudPro] orderBy 参数格式错误，无法解析。` +
-        `期望值: '${timeColumn} DESC' 或 '${timeColumn} ASC'`
-      );
-    }
-
-    if (firstOrderBy.fieldName !== timeColumn) {
-      throw new Error(
-        `[ShardingCrudPro] orderBy 首个排序字段必须为 '${timeColumn}'，` +
-        `当前值: '${firstOrderBy.fieldName}'`
-      );
-    }
-
-    // 校验排序方向是否为 ASC 或 DESC
-    const orderType = firstOrderBy.orderType.toUpperCase();
-    if (orderType !== 'ASC' && orderType !== 'DESC') {
-      throw new Error(
-        `[ShardingCrudPro] orderBy 排序方向必须是 'ASC' 或 'DESC'，` +
-        `当前值: '${firstOrderBy.orderType}'`
-      );
-    }
-  }
-
-  /**
-   * 判断 orderBy 是否为 ASC 方向
-   *
-   * 前提：validateQueryOrderBy 已通过校验，orderBy 格式合法
-   *
-   * @param reqJson 请求参数
-   * @returns true 表示 ASC，false 表示 DESC
-   */
-  private isAscOrderBy(reqJson: IRequestModel): boolean {
-    return OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
-  }
-
-  /**
-   * 根据排序方向对分表列表进行排序
-   *
-   * 分表名后缀为时间格式（如 202403、20240101），字典序即时间序。
-   * - DESC：降序排列（新→旧）
-   * - ASC：升序排列（旧→新）
-   *
-   * @param tables 分表列表
-   * @param reqJson 请求参数
-   * @returns 排序后的分表列表（新数组，不修改原数组）
-   */
-  private sortTablesForOrderBy(tables: string[], reqJson: IRequestModel): string[] {
-    const isAsc = this.isAscOrderBy(reqJson);
-    return [...tables].sort((a, b) =>
-      isAsc ? a.localeCompare(b) : b.localeCompare(a)
-    );
-  }
-
-  // ============ 查询表解析（委托给 ShardingRouter） ============
-
-  /**
-   * 解析查询表（带真实表过滤）
-   *
-   * 将查询路由委托给 ShardingRouter.resolveQuery，
-   * 由 ShardingRouter 统一处理所有查询路由逻辑。
-   */
-  private async resolveQueryTables(reqJson: IRequestModel): Promise<string[]> {
-    const context: IShardingRouterContext = {
-      config: this.config,
-      condition: reqJson.condition,
-    };
-
-    // 创建表信息提供者
-    const tableInfoProvider: ITableInfoProvider = {
-      getExistingTables: () => this.getExistingTablesSet(),
-    };
-
-    // 委托给 ShardingRouter 处理查询路由
-    return this.router.resolveQuery(this.config, context, tableInfoProvider);
-  }
-}