midway-fatcms 0.0.8 → 0.0.9

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

@@ -11,8 +11,10 @@ import {
   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 构造参数（工厂函数模式）
@@ -55,15 +57,18 @@ export class CrudProQuick {
   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,
-  };
+      maxLimit: DEFAULT_MAX_LIMIT,
+      batchSizeForIdsQuery: DEFAULT_BATCH_SIZE_FOR_IDS_QUERY,
+    };
 
   /**
    * 构造函数（工厂函数模式）
@@ -102,7 +107,7 @@ export class CrudProQuick {
       throw new Error('[CrudProQuick] sqlTable not found');
     }
 
-        // 创建 CrudPro 实例并设置 visitor
+    // 创建 CrudPro 实例并设置 visitor
     const crudPro = this.crudProFactory();
 
     // 应用软删除动作。
@@ -118,28 +123,36 @@ export class CrudProQuick {
    * @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,
+      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(sqlTable, reqJson.condition) });
+    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' } });
@@ -149,7 +162,7 @@ export class CrudProQuick {
    */
   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,
@@ -158,17 +171,16 @@ export class CrudProQuick {
     };
     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);
+      throw new CommonException(Exceptions.MORE_THAN_ONE_RECORDS_FOUND, '发现了不止一条数据')
     }
-    
-    return new CrudQueryOneResult<T>({ 
-      row: rows[0] || null, 
+
+    return new CrudQueryOneResult<T>({
+      row: rows[0] || null,
       rawContext: ctx,
       debugInfo: this.buildDebugInfo(effectiveTable, reqJson.condition),
+      fromTable: effectiveTable,
     });
   }
 
@@ -185,32 +197,6 @@ export class CrudProQuick {
     }
     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 请求参数
@@ -355,6 +341,9 @@ export class CrudProQuick {
 
   /**
    * 插入或更新数据记录（upsert）
+   * 限制：
+   *  - 必须有condition字段，用于判断记录是否存在
+   *  - 必须有data字段，用于指定插入/更新的内容
    * 内部使用 SIMPLE_INSERT_OR_UPDATE 模式，若记录已存在则更新，不存在则插入
    * @param reqJson 请求参数，data 为要插入/更新的内容，condition 为判断条件
    * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
@@ -368,7 +357,6 @@ export class CrudProQuick {
     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,
@@ -476,6 +464,98 @@ export class CrudProQuick {
     });
   }
 
+  /**
+   * 保存数据记录（自动判断 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 查询单条记录
    *
@@ -503,9 +583,14 @@ export class CrudProQuick {
   /**
    * 根据主键 ID 列表查询多条记录
    *
-   * 等价于 `findList({ condition: { id: { $in: ids } } })`，但更简洁。
+   * 实现逻辑：
+   * 1. 先对 ids 去重，避免重复 ID 导致无效查询和重复结果
+   * 2. 若去重后为空，直接返回空结果
+   * 3. 若 ID 数量不超过批次大小，单次 findList 查询完成
+   * 4. 若 ID 数量超过批次大小，自动分批查询（每批默认 200 个 ID），
+   *    避免单次 IN 列表过大导致执行计划退化和内存尖峰，最后合并结果返回
    *
-   * @param ids 主键值数组
+   * @param ids 主键值数组（内部会自动去重）
    * @param sqlTable 数据库表名，若构造实例时已设置全局 sqlTable 则可省略
    * @returns CrudQueryListResult 包含 rows、count 和 getRawContext()
    *
@@ -518,7 +603,32 @@ export class CrudProQuick {
    * 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);
+    // 去重：避免重复 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 });
   }
 
   /**
@@ -591,4 +701,82 @@ export class CrudProQuick {
     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;
+  }
+
+
+
 }

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

@@ -0,0 +1,256 @@
+import { IRequestModel, IRequestCfgModel } from '@/libs/crud-pro/interfaces';
+import { ExecuteContext } from '@/libs/crud-pro/models/ExecuteContext';
+import { KeysOfSimpleSQL } from '@/libs/crud-pro/models/keys';
+import { IShardingConfig, IShardingRouterContext, CrudProFactory } from './ShardingConfig';
+import { fixSoftDelete } from '@/libs/crud-pro-quick/fixSoftDelete';
+import { ShardingTableCreator } from './ShardingTableCreator';
+import {
+  CrudWriteResult,
+  CrudQueryOneResult,
+  CrudQueryListResult,
+  CrudQueryPageResult,
+  CrudExistResult,
+  CrudCountResult,
+  CrudUpsertResult,
+} from '@/libs/crud-pro/models/CrudResult';
+import { ShardingBatchInsertResult } from './ShardingResult';
+
+/**
+ * 分表 CRUD 基类
+ *
+ * 提供所有分表子类共用的基础设施方法，不包含任何路由逻辑。
+ * 路由逻辑由各子类自行实现。
+ *
+ * 子类：
+ * - ShardingByTimeCrud: 时间分表（YEAR/MONTH/DAY）
+ * - ShardingByHashCrud: 哈希分表
+ * - ShardingByKeyCrud: 键值分表
+ * - ShardingByCustomCrud: 自定义分表
+ */
+export abstract class ShardingBase {
+  protected readonly crudProFactory: CrudProFactory;
+  protected readonly config: IShardingConfig;
+  protected readonly tableCreator: ShardingTableCreator;
+
+  protected baseCfg: Partial<IRequestCfgModel> = {};
+  protected enableSoftDelete: boolean = false;
+
+  constructor(crudProFactory: CrudProFactory, config: IShardingConfig) {
+    this.config = config;
+
+    if (typeof crudProFactory === 'function') {
+      this.crudProFactory = crudProFactory;
+    } else {
+      throw new Error('[ShardingBase] 请使用 CrudProFactory 工厂函数模式');
+    }
+
+    this.tableCreator = new ShardingTableCreator(this.crudProFactory, config);
+  }
+
+  // ============ 配置方法 ============
+
+  public setBaseCfg(cfg: Partial<IRequestCfgModel>): this {
+    this.baseCfg = { ...this.baseCfg, ...cfg };
+    return this;
+  }
+
+  public getConfig(): IShardingConfig {
+    return this.config;
+  }
+
+  public setEnableSoftDelete(enable: boolean): this {
+    this.enableSoftDelete = enable;
+    return this;
+  }
+
+  // ============ 抽象 CRUD 方法（子类必须实现） ============
+
+  public abstract insert(reqJson: IRequestModel): Promise<CrudWriteResult>;
+  public abstract batchInsert(reqJson: IRequestModel): Promise<ShardingBatchInsertResult>;
+  public abstract update(reqJson: IRequestModel): Promise<CrudWriteResult>;
+  public abstract delete(reqJson: IRequestModel): Promise<CrudWriteResult>;
+  public abstract restore(reqJson: IRequestModel): Promise<CrudWriteResult>;
+  public abstract insertOrUpdate(reqJson: IRequestModel): Promise<CrudUpsertResult>;
+  public abstract findOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
+  public abstract findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
+  public abstract findList<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryListResult<T>>;
+  public abstract findPage<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryPageResult<T>>;
+  public abstract findCount(reqJson: IRequestModel): Promise<CrudCountResult>;
+  public abstract isExist(reqJson: IRequestModel): Promise<CrudExistResult>;
+
+  /**
+   * 判断当前路由上下文是否处于「插入阶段」（应从 data 提取分表字段）
+   *
+   * - INSERT / BATCH_INSERT → 始终从 data
+   * - 其余操作（QUERY / UPDATE / DELETE / INSERT_OR_UPDATE）→ 从 condition
+   */
+  protected static isInsertPhase(ctx: IShardingRouterContext): boolean {
+    return [KeysOfSimpleSQL.SIMPLE_INSERT, KeysOfSimpleSQL.SIMPLE_BATCH_INSERT].includes(ctx.sqlSimpleName);
+  }
+
+  // ============ 执行基础设施 ============
+
+  protected buildCfg(sqlSimpleName: KeysOfSimpleSQL): IRequestCfgModel & { enableSoftDelete?: boolean } {
+    return {
+      method: `ShardingCrudProAnonymous_${sqlSimpleName}`,
+      ...this.baseCfg,
+      sqlTable: this.config.baseTable,
+      sqlSimpleName,
+    } as IRequestCfgModel & { enableSoftDelete?: boolean };
+  }
+
+  protected async executeOnTable(
+    table: string,
+    reqJson: IRequestModel,
+    sqlSimpleName: KeysOfSimpleSQL,
+    extraCfg?: Partial<IRequestCfgModel>
+  ): Promise<ExecuteContext> {
+    const cfg = this.buildCfg(sqlSimpleName);
+    cfg.sqlTable = table;
+    cfg.enableSoftDelete = this.enableSoftDelete;
+
+    if (extraCfg) {
+      Object.assign(cfg, extraCfg);
+    }
+
+    const crudPro = this.crudProFactory();
+    fixSoftDelete(sqlSimpleName, cfg as any, reqJson, crudPro.getVisitor());
+    return crudPro.executeCrudByCfg(reqJson, cfg);
+  }
+
+  // ============ 单表查询辅助 ============
+
+  protected async findCountFromTable(table: string, reqJson: IRequestModel): Promise<{ count: number; ctx: ExecuteContext | null }> {
+    try {
+      const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+      return { count: ctx.getResModelItem('total_count') || 0, ctx };
+    } catch (e) {
+      return { count: 0, ctx: null };
+    }
+  }
+
+  protected async isExistInTable(table: string, reqJson: IRequestModel): Promise<{ exists: boolean; ctx: ExecuteContext | null }> {
+    try {
+      const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+      return { exists: ctx.getResModelItem('is_exist') === true, ctx };
+    } catch (e) {
+      return { exists: false, ctx: null };
+    }
+  }
+
+  // ============ 表管理 ============
+
+  protected async getExistingTablesSet(skipCache = false): Promise<Set<string>> {
+    const { sqlDatabase, sqlDbType } = this.baseCfg;
+
+    if (!sqlDatabase || !sqlDbType) {
+      throw new Error('[ShardingBase] 未配置 sqlDatabase 或 sqlDbType');
+    }
+
+    const { tables } = await this.crudProFactory().getAllTableInfos(
+      { sqlDatabase, sqlDbType: sqlDbType as any },
+      { skipCache }
+    );
+
+    return new Set(tables.map(t => t.name));
+  }
+
+  protected async isTableExists(tableName: string): Promise<boolean> {
+    const existingSet = await this.getExistingTablesSet();
+    return existingSet.has(tableName);
+  }
+
+  protected async createShardingTableIfNeeded(tableName: string): Promise<void> {
+    if (!this.config.autoCreateTable) {
+      if (!(await this.isTableExists(tableName))) {
+        throw new Error(`[ShardingBase] 分表 ${tableName} 不存在。请先创建分表，或设置 autoCreateTable: true 自动创建`);
+      }
+      return;
+    }
+
+    if (!this.baseCfg.sqlDatabase || !this.baseCfg.sqlDbType) {
+      throw new Error('[ShardingBase] 请先调用 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(`[ShardingBase] 创建分表 ${tableName} 失败`);
+    }
+
+    if (result.createSql) {
+      await this.getExistingTablesSet(true);
+    }
+  }
+
+  // ============ 辅助方法 ============
+
+  protected 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.baseCfg.sqlDatabase || 'unknown',
+      sqlTable: sqlTable || this.config.baseTable,
+    };
+    if (condition) {
+      info.condition = condition;
+    }
+    return info;
+  }
+
+  protected formatUniqueError(
+    foundCount: number,
+    tables: string | string[],
+    condition: Record<string, any> | undefined,
+    isMultiTable: boolean = false
+  ): string {
+    const parts = [
+      `[ShardingBase] findUniqueOne 期望唯一一条记录，但查询到 ${foundCount} 条`,
+    ];
+
+    if (this.baseCfg.sqlDatabase) {
+      parts.push(`数据库: ${this.baseCfg.sqlDatabase}`);
+    }
+
+    if (isMultiTable && Array.isArray(tables)) {
+      parts.push(`基表: ${this.config.baseTable}`);
+      parts.push(`分表: [${tables.join(', ')}]`);
+    } else {
+      parts.push(`表: ${typeof tables === 'string' ? tables : tables[0]}`);
+    }
+
+    if (condition) {
+      try {
+        parts.push(`条件: ${JSON.stringify(condition)}`);
+      } catch {
+        parts.push(`条件: [无法序列化]`);
+      }
+    }
+
+    return parts.join(' | ');
+  }
+
+  /**
+   * 获取所有以 baseTable_ 开头的已存在分表（按字典序排序）
+   */
+  protected async getAllExistingShardingTables(): Promise<string[]> {
+    const existingTables = await this.getExistingTablesSet();
+    const prefix = `${this.config.baseTable}_`;
+    const tables = Array.from(existingTables).filter(t => t.startsWith(prefix));
+    tables.sort();
+    return tables;
+  }
+
+  /**
+   * 过滤出真实存在的分表
+   */
+  protected async filterExistingTables(candidateTables: string[]): Promise<string[]> {
+    const existingTables = await this.getExistingTablesSet();
+    return candidateTables.filter(table => existingTables.has(table));
+  }
+}