midway-fatcms 0.0.7 → 0.0.9

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

@@ -0,0 +1,329 @@
+import { IRequestModel } 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 { ShardingBase } from './ShardingBase';
+import {
+  CrudWriteResult,
+  CrudQueryOneResult,
+  CrudQueryListResult,
+  CrudQueryPageResult,
+  CrudExistResult,
+  CrudCountResult,
+  CrudUpsertResult,
+} from '@/libs/crud-pro/models/CrudResult';
+import { ShardingBatchInsertResult } from './ShardingResult';
+
+/**
+ * 自定义分表 CRUD
+ *
+ * 分表名称完全由用户提供的 customRouter 函数决定。
+ * 适用于无法用时间/哈希/键值覆盖的复杂场景（如原 RANGE 分表）。
+ *
+ * 特性：
+ * - 路由：customRouter({ config, data?, condition? }) → 表名或表名数组
+ * - 插入：customRouter 返回单个表名
+ * - 查询：customRouter 返回表名数组 → 过滤已存在表
+ * - insertOrUpdate：统一由 condition 路由定位分表，查找与插入在同一分表
+ */
+export class ShardingByCustomCrud extends ShardingBase {
+
+  constructor(crudProFactory: CrudProFactory, config: IShardingConfig) {
+    super(crudProFactory, config);
+
+    if (!config.customRouter) {
+      throw new Error('[ShardingByCustomCrud] 自定义分表必须提供 customRouter 函数');
+    }
+  }
+
+  // ============ 路由 ============
+
+  private resolveTableForInsert(data: Record<string, any>, sqlSimpleName: KeysOfSimpleSQL): string {
+    const context: IShardingRouterContext = { config: this.config, data, sqlSimpleName };
+    const result = this.config.customRouter!(context);
+    if (Array.isArray(result)) {
+      if (result.length === 1) {
+         return result[0];
+      }
+      throw new Error(
+        `[ShardingByCustomCrud] 插入操作需要 customRouter 返回单个表名，但返回了 ${result.length} 个: ${result.slice(0, 5).join(', ')}`
+      );
+    }
+    if (typeof result === 'string' && result) {
+      return result;
+    }
+    throw new Error('[ShardingByCustomCrud] 插入操作需要 customRouter 返回单个表名, 实际返回了空值');
+  }
+
+  private resolveTableForCondition(condition: Record<string, any>, sqlSimpleName: KeysOfSimpleSQL): string {
+    const context: IShardingRouterContext = { config: this.config, condition, sqlSimpleName };
+    const result = this.config.customRouter!(context);
+    if (Array.isArray(result)) {
+      if (result.length === 1) return result[0];
+      throw new Error(
+        `[ShardingByCustomCrud] 写操作需要 customRouter 返回单个表名，但返回了 ${result.length} 个: ${result.slice(0, 5).join(', ')}`
+      );
+    }
+    return result;
+  }
+
+  private async resolveFindTables(reqJson: IRequestModel, sqlSimpleName: KeysOfSimpleSQL): Promise<string[]> {
+    const context: IShardingRouterContext = { config: this.config, condition: reqJson.condition, sqlSimpleName };
+    const result = this.config.customRouter!(context);
+    const candidates = Array.isArray(result) ? result : [result];
+    return this.filterExistingTables(candidates);
+  }
+
+  // ============ 写操作 ============
+
+  public async insert(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    const targetTable = this.resolveTableForInsert(reqJson.data as Record<string, any>, KeysOfSimpleSQL.SIMPLE_INSERT);
+    await this.createShardingTableIfNeeded(targetTable);
+
+    const ctx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+  }
+
+  public async batchInsert(reqJson: IRequestModel): Promise<ShardingBatchInsertResult> {
+    const dataArray = reqJson.data as Record<string, any>[];
+    if (!Array.isArray(dataArray) || dataArray.length === 0) {
+      throw new Error('[ShardingByCustomCrud] batchInsert requires non-empty data array');
+    }
+
+    const groupedData = new Map<string, Record<string, any>[]>();
+    for (const item of dataArray) {
+      const table = this.resolveTableForInsert(item, KeysOfSimpleSQL.SIMPLE_BATCH_INSERT);
+      if (!groupedData.has(table)) groupedData.set(table, []);
+      groupedData.get(table)!.push(item);
+    }
+
+    for (const tableName of groupedData.keys()) {
+      await this.createShardingTableIfNeeded(tableName);
+    }
+
+    const results: Array<{ table: string; affected: number; rowCount: number; error: Error | null; context: ExecuteContext | null }> = [];
+    let lastContext: ExecuteContext | null = null;
+
+    for (const [table, items] of groupedData.entries()) {
+      try {
+        const ctx = await this.executeOnTable(table, { data: items }, KeysOfSimpleSQL.SIMPLE_BATCH_INSERT);
+        lastContext = ctx;
+        results.push({ table, affected: ctx.getResModelItem('affected')?.affectedRows || items.length, rowCount: items.length, error: null, context: ctx });
+      } catch (e) {
+        results.push({ table, affected: 0, rowCount: items.length, error: e as Error, context: null });
+      }
+    }
+
+    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);
+    const finalContext = lastContext || results.find(r => r.context)?.context;
+    if (!finalContext) throw new Error('[ShardingByCustomCrud] batchInsert failed - no successful inserts');
+
+    return new ShardingBatchInsertResult({ totalAffected, tableResults, tableCount: groupedData.size, success: errors.length === 0, errors, lastContext: finalContext });
+  }
+
+  public async update(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    const targetTable = this.resolveTableForCondition(reqJson.condition!, KeysOfSimpleSQL.SIMPLE_UPDATE);
+    const ctx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+  }
+
+  public async delete(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    const targetTable = this.resolveTableForCondition(reqJson.condition!, KeysOfSimpleSQL.SIMPLE_DELETE);
+    const ctx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_DELETE);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+  }
+
+  public async restore(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    const targetTable = this.resolveTableForCondition(reqJson.condition!, KeysOfSimpleSQL.SIMPLE_UPDATE);
+    if (!reqJson.condition || Object.keys(reqJson.condition).length === 0) {
+      throw new Error('[ShardingByCustomCrud] restore 操作必须指定恢复条件');
+    }
+    const restoreReqJson: IRequestModel = {
+      ...reqJson,
+      data: { ...reqJson.data, deleted_at: 0, deleted_by: '' },
+    };
+    const ctx = await this.executeOnTable(targetTable, restoreReqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+  }
+
+  public async insertOrUpdate(reqJson: IRequestModel): Promise<CrudUpsertResult> {
+    const targetTable = this.resolveTableForCondition(reqJson.condition!, KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE);
+
+    const existCtx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+    const isExist = existCtx.getResModelItem('is_exist') === true;
+
+    if (isExist) {
+      const updateCtx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
+      return new CrudUpsertResult({ insertAffected: undefined, updateAffected: updateCtx.getResModel().affected, isExist: true, rawContext: updateCtx });
+    }
+
+    await this.createShardingTableIfNeeded(targetTable);
+    const insertCtx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT);
+    return new CrudUpsertResult({ insertAffected: insertCtx.getResModel().affected, updateAffected: undefined, isExist: false, rawContext: insertCtx });
+  }
+
+  // ============ 查询操作 ============
+
+  public async findOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>> {
+    const targetTables = await this.resolveFindTables(reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
+    if (targetTables.length === 0) throw new Error('[ShardingByCustomCrud] findOne: no matching tables found');
+
+    let lastCtx: ExecuteContext | null = null;
+    let lastTable: string | undefined;
+    for (const table of targetTables) {
+      try {
+        const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
+        lastCtx = ctx; lastTable = table;
+        const row = ctx.getOneObj();
+        if (row) return new CrudQueryOneResult<T>({ row: row as T, rawContext: ctx, debugInfo: this.buildDebugInfo(table, reqJson.condition), fromTable: table });
+      } catch (e) { /* skip */ }
+    }
+    return new CrudQueryOneResult<T>({ row: null, rawContext: lastCtx, debugInfo: this.buildDebugInfo(targetTables[0], reqJson.condition), fromTable: lastTable });
+  }
+
+  public async findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>> {
+    const targetTables = await this.resolveFindTables(reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
+    if (targetTables.length === 0) {
+      return new CrudQueryOneResult<T>({ row: null, rawContext: null as any, debugInfo: this.buildDebugInfo(undefined, reqJson.condition), fromTable: null });
+    }
+
+    const allRows: T[] = [];
+    const foundTables: string[] = [];
+    let firstCtx: ExecuteContext | null = null;
+
+    for (const table of targetTables) {
+      try {
+        const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY, { maxLimit: 2 });
+        if (!firstCtx) firstCtx = ctx;
+        const rows = ctx.getResRows() as T[];
+        if (rows.length > 0) {
+          allRows.push(...rows);
+          foundTables.push(table);
+          if (allRows.length > 1) throw new Error(this.formatUniqueError(allRows.length, foundTables, reqJson.condition, foundTables.length > 1));
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.startsWith('[ShardingBase] findUniqueOne')) throw e;
+      }
+    }
+
+    const fromTable = foundTables[0] || null;
+    return new CrudQueryOneResult<T>({ row: allRows[0] || null, rawContext: firstCtx, debugInfo: this.buildDebugInfo(fromTable || targetTables[0], reqJson.condition), fromTable: fromTable || targetTables[0] });
+  }
+
+  public async findList<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryListResult<T>> {
+    const targetTables = await this.resolveFindTables(reqJson, KeysOfSimpleSQL.SIMPLE_QUERY);
+    if (targetTables.length === 0) return new CrudQueryListResult<T>({ rows: [], rawContext: null as any });
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY);
+      return new CrudQueryListResult<T>({ rows: ctx.getResRows() as T[], rawContext: ctx });
+    }
+
+    let allRows: any[] = [];
+    let lastCtx: ExecuteContext | null = null;
+    for (const table of targetTables) {
+      try {
+        const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY);
+        lastCtx = ctx;
+        allRows = allRows.concat(ctx.getResRows() || []);
+      } catch (e) { /* skip */ }
+    }
+    return new CrudQueryListResult<T>({ rows: allRows as T[], rawContext: lastCtx });
+  }
+
+  public async findPage<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryPageResult<T>> {
+    const targetTables = await this.resolveFindTables(reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
+    if (targetTables.length === 0) throw new Error('[ShardingByCustomCrud] findPage: no matching tables found');
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
+      const pageResult = ctx.getResModelForQueryPage();
+      return new CrudQueryPageResult<T>({ rows: pageResult.rows as T[], totalCount: pageResult.total_count, rawContext: ctx });
+    }
+
+    const { pageNo = 1, pageSize = 10 } = reqJson;
+    const offset = (pageNo - 1) * pageSize;
+
+    let totalCount = 0;
+    const tableCounts: Array<{ table: string; count: number }> = [];
+    for (const table of targetTables) {
+      const { count } = await this.findCountFromTable(table, reqJson);
+      tableCounts.push({ table, count });
+      totalCount += count;
+    }
+
+    if (totalCount === 0) {
+      return new CrudQueryPageResult<T>({ rows: [], totalCount: 0, rawContext: null as any });
+    }
+
+    let accumulated = 0;
+    let allRows: any[] = [];
+    let lastCtx: ExecuteContext | null = null;
+    const targetEnd = offset + pageSize;
+
+    for (const { table, count } of tableCounts) {
+      if (count === 0) continue;
+      const tableEnd = accumulated + count;
+      if (tableEnd <= offset) { accumulated = tableEnd; continue; }
+      if (accumulated >= targetEnd) break;
+
+      const innerOffset = Math.max(0, offset - accumulated);
+      const innerLimit = Math.min(count, targetEnd - accumulated) - innerOffset;
+
+      try {
+        const ctx = await this.executeOnTable(table, { ...reqJson, offset: innerOffset, limit: innerLimit } as any, KeysOfSimpleSQL.SIMPLE_QUERY);
+        lastCtx = ctx;
+        allRows = allRows.concat(ctx.getResRows() || []);
+      } catch (e) { /* skip */ }
+
+      accumulated = tableEnd;
+      if (accumulated >= targetEnd) break;
+    }
+
+    return new CrudQueryPageResult<T>({ rows: allRows as T[], totalCount, rawContext: lastCtx });
+  }
+
+  public async findCount(reqJson: IRequestModel): Promise<CrudCountResult> {
+    const targetTables = await this.resolveFindTables(reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+    if (targetTables.length === 0) throw new Error('[ShardingByCustomCrud] findCount: no matching tables found');
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+      return new CrudCountResult({ count: ctx.getResModelItem('total_count') || 0, rawContext: ctx });
+    }
+
+    let totalCount = 0;
+    let firstCtx: ExecuteContext | null = null;
+    for (const table of targetTables) {
+      const { count, ctx } = await this.findCountFromTable(table, reqJson);
+      totalCount += count;
+      if (!firstCtx && ctx) firstCtx = ctx;
+    }
+    return new CrudCountResult({ count: totalCount, rawContext: firstCtx as any });
+  }
+
+  public async isExist(reqJson: IRequestModel): Promise<CrudExistResult> {
+    const targetTables = await this.resolveFindTables(reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+    if (targetTables.length === 0) throw new Error('[ShardingByCustomCrud] isExist: no matching tables found');
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+      return new CrudExistResult({ exists: ctx.getResModelItem('is_exist') === true, rawContext: ctx });
+    }
+
+    let exists = false;
+    let firstCtx: ExecuteContext | null = null;
+    for (const table of targetTables) {
+      const result = await this.isExistInTable(table, reqJson);
+      if (!firstCtx && result.ctx) firstCtx = result.ctx;
+      if (result.exists) { exists = true; break; }
+    }
+    return new CrudExistResult({ exists, rawContext: firstCtx as any });
+  }
+}

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

@@ -0,0 +1,111 @@
+import { IRequestModel, IRequestCfgModel } from '@/libs/crud-pro/interfaces';
+import { IShardingConfig, IShardingRouterContext, CrudProFactory } from './ShardingConfig';
+import { ShardingBase } from './ShardingBase';
+import { ShardingByCustomCrud } from './ShardingByCustomCrud';
+import {
+  CrudWriteResult,
+  CrudQueryOneResult,
+  CrudQueryListResult,
+  CrudQueryPageResult,
+  CrudExistResult,
+  CrudCountResult,
+  CrudUpsertResult,
+} from '@/libs/crud-pro/models/CrudResult';
+import { ShardingBatchInsertResult } from './ShardingResult';
+
+/**
+ * 哈希分表 CRUD
+ *
+ * 根据 shardingColumn 的哈希值取模 tableCount，定位到固定数量的分表。
+ * 表名格式：baseTable_XX（如 t_order_00 ~ t_order_15）
+ *
+ * 内部委托 ShardingByCustomCrud 实现所有 CRUD 操作，
+ * 通过 customRouter 实现哈希路由逻辑。
+ *
+ * 规范：所有操作必须提供 shardingColumn，否则抛出异常。
+ *
+ * 特性：
+ * - 路由：hash(shardingColumn) % tableCount → 固定分表
+ * - insertOrUpdate：统一由 condition 路由定位分表
+ */
+export class ShardingByHashCrud extends ShardingBase {
+  private delegate: ShardingByCustomCrud;
+
+  constructor(crudProFactory: CrudProFactory, config: IShardingConfig) {
+    super(crudProFactory, config);
+
+    if (!config.shardingColumn) {
+      throw new Error('[ShardingByHashCrud] 哈希分表必须指定 shardingColumn');
+    }
+    if (!config.tableCount || config.tableCount <= 0) {
+      throw new Error('[ShardingByHashCrud] 哈希分表必须指定 tableCount（大于 0）');
+    }
+
+    const col = config.shardingColumn;
+    const count = config.tableCount;
+    const baseTable = config.baseTable;
+    const fmt = config.suffixFormatter;
+
+    /** 格式化表名：baseTable + _ + 后缀（可选 suffixFormatter） */
+    const formatTable = (suffix: string): string => {
+      const formatted = fmt ? fmt(suffix) : suffix;
+      return `${baseTable}_${formatted}`;
+    };
+
+    /** djb2 哈希 → 取模 → 零填充后缀 → 表名 */
+    const hashRoute = (value: any): string => {
+      const str = String(value);
+      let hash = 5381;
+      for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash) + str.charCodeAt(i);
+        hash = hash & hash;
+      }
+      return formatTable(String(Math.abs(hash) % count).padStart(2, '0'));
+    };
+
+    const customRouter = (ctx: IShardingRouterContext): string => {
+      // 根据操作类型确定字段来源：insert 类从 data，其余从 condition
+      const fromData = ShardingBase.isInsertPhase(ctx);
+      const val = fromData ? ctx.data?.[col] : ctx.condition?.[col];
+
+      if (val != null && val !== '' && val !== undefined) {
+        return hashRoute(val);
+      }
+
+      throw new Error(
+        `[ShardingByHashCrud] ${fromData ? 'data' : 'condition'} 必须包含分表字段 '${col}'`
+      );
+    };
+
+    this.delegate = new ShardingByCustomCrud(crudProFactory, { ...config, customRouter });
+  }
+
+  // ============ 状态同步 ============
+
+  public setBaseCfg(cfg: Partial<IRequestCfgModel>): this {
+    super.setBaseCfg(cfg);
+    this.delegate.setBaseCfg(cfg);
+    return this;
+  }
+
+  public setEnableSoftDelete(enable: boolean): this {
+    super.setEnableSoftDelete(enable);
+    this.delegate.setEnableSoftDelete(enable);
+    return this;
+  }
+
+  // ============ CRUD 方法：全部委托 ============
+
+  public insert(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.insert(r); }
+  public batchInsert(r: IRequestModel): Promise<ShardingBatchInsertResult> { return this.delegate.batchInsert(r); }
+  public update(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.update(r); }
+  public delete(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.delete(r); }
+  public restore(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.restore(r); }
+  public insertOrUpdate(r: IRequestModel): Promise<CrudUpsertResult> { return this.delegate.insertOrUpdate(r); }
+  public findOne<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryOneResult<T>> { return this.delegate.findOne<T>(r); }
+  public findUniqueOne<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryOneResult<T>> { return this.delegate.findUniqueOne<T>(r); }
+  public findList<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryListResult<T>> { return this.delegate.findList<T>(r); }
+  public findPage<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryPageResult<T>> { return this.delegate.findPage<T>(r); }
+  public findCount(r: IRequestModel): Promise<CrudCountResult> { return this.delegate.findCount(r); }
+  public isExist(r: IRequestModel): Promise<CrudExistResult> { return this.delegate.isExist(r); }
+}

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

@@ -0,0 +1,97 @@
+import { IRequestModel, IRequestCfgModel } from '@/libs/crud-pro/interfaces';
+import { IShardingConfig, IShardingRouterContext, CrudProFactory } from './ShardingConfig';
+import { ShardingBase } from './ShardingBase';
+import { ShardingByCustomCrud } from './ShardingByCustomCrud';
+import {
+  CrudWriteResult,
+  CrudQueryOneResult,
+  CrudQueryListResult,
+  CrudQueryPageResult,
+  CrudExistResult,
+  CrudCountResult,
+  CrudUpsertResult,
+} from '@/libs/crud-pro/models/CrudResult';
+import { ShardingBatchInsertResult } from './ShardingResult';
+
+/**
+ * 键值分表 CRUD
+ *
+ * 字段原值即表后缀，一值一表。
+ * 表名格式：baseTable_{shardingColumn值}（如 t_log_east, t_log_west）
+ *
+ * 内部委托 ShardingByCustomCrud 实现所有 CRUD 操作，
+ * 通过 customRouter 实现键值路由逻辑。
+ *
+ * 规范：所有操作必须提供 shardingColumn，否则抛出异常。
+ *
+ * 特性：
+ * - 路由：shardingColumn 的原始值直接作为表后缀
+ * - 不预定义 keyValues，表按需动态创建
+ * - insertOrUpdate：统一由 condition 路由定位分表
+ */
+export class ShardingByKeyCrud extends ShardingBase {
+  private delegate: ShardingByCustomCrud;
+
+  constructor(crudProFactory: CrudProFactory, config: IShardingConfig) {
+    super(crudProFactory, config);
+
+    if (!config.shardingColumn) {
+      throw new Error('[ShardingByKeyCrud] 键值分表必须指定 shardingColumn');
+    }
+
+    const col = config.shardingColumn;
+    const baseTable = config.baseTable;
+    const fmt = config.suffixFormatter;
+
+    /** 格式化表名：baseTable + _ + 后缀（可选 suffixFormatter） */
+    const formatTable = (suffix: string): string => {
+      const formatted = fmt ? fmt(suffix) : suffix;
+      return `${baseTable}_${formatted}`;
+    };
+
+    const customRouter = (ctx: IShardingRouterContext): string | string[] => {
+      // 根据操作类型确定字段来源：insert 类从 data，其余从 condition
+      const fromData = ShardingBase.isInsertPhase(ctx);
+      const val = fromData ? ctx.data?.[col] : ctx.condition?.[col];
+
+      if (val != null && val !== '' && val !== undefined) {
+        return formatTable(String(val))
+      };
+
+      throw new Error(
+        `[ShardingByKeyCrud] ${fromData ? 'data' : 'condition'} 必须包含分表字段 '${col}'`
+      );
+    };
+
+    this.delegate = new ShardingByCustomCrud(crudProFactory, { ...config, customRouter });
+  }
+
+  // ============ 状态同步 ============
+
+  public setBaseCfg(cfg: Partial<IRequestCfgModel>): this {
+    super.setBaseCfg(cfg);
+    this.delegate.setBaseCfg(cfg);
+    return this;
+  }
+
+  public setEnableSoftDelete(enable: boolean): this {
+    super.setEnableSoftDelete(enable);
+    this.delegate.setEnableSoftDelete(enable);
+    return this;
+  }
+
+  // ============ CRUD 方法：全部委托 ============
+
+  public insert(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.insert(r); }
+  public batchInsert(r: IRequestModel): Promise<ShardingBatchInsertResult> { return this.delegate.batchInsert(r); }
+  public update(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.update(r); }
+  public delete(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.delete(r); }
+  public restore(r: IRequestModel): Promise<CrudWriteResult> { return this.delegate.restore(r); }
+  public insertOrUpdate(r: IRequestModel): Promise<CrudUpsertResult> { return this.delegate.insertOrUpdate(r); }
+  public findOne<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryOneResult<T>> { return this.delegate.findOne<T>(r); }
+  public findUniqueOne<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryOneResult<T>> { return this.delegate.findUniqueOne<T>(r); }
+  public findList<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryListResult<T>> { return this.delegate.findList<T>(r); }
+  public findPage<T = Record<string, any>>(r: IRequestModel): Promise<CrudQueryPageResult<T>> { return this.delegate.findPage<T>(r); }
+  public findCount(r: IRequestModel): Promise<CrudCountResult> { return this.delegate.findCount(r); }
+  public isExist(r: IRequestModel): Promise<CrudExistResult> { return this.delegate.isExist(r); }
+}