midway-fatcms 0.0.7 → 0.0.9

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

@@ -0,0 +1,628 @@
+import * as moment from 'moment';
+import { IRequestModel } 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, IShardingTimeRange, CrudProFactory } from './ShardingConfig';
+import { ShardingBase } from './ShardingBase';
+import { ShardingMerger } from './ShardingMerger';
+import { ShardingCountCache } from './ShardingCountCache';
+import {
+  CrudWriteResult,
+  CrudQueryOneResult,
+  CrudQueryListResult,
+  CrudQueryPageResult,
+  CrudExistResult,
+  CrudCountResult,
+  CrudUpsertResult,
+} from '@/libs/crud-pro/models/CrudResult';
+import { ShardingBatchInsertResult } from './ShardingResult';
+import { ShardingTimeGranularity, getTimeSuffix, isOperatorExpression, expandDateToRange } from './ShardingUtils';
+
+/**
+ * 时间分表 CRUD
+ *
+ * 支持 YEAR / MONTH / DAY 三种时间粒度分表。
+ * 路由规则：根据 timeColumn 的值计算时间后缀，定位到对应分表。
+ *
+ * 特性：
+ * - 插入：data 中的 timeColumn 决定目标分表
+ * - 更新/删除：condition 中的 timeColumn 定位分表
+ * - 查询：时间范围条件交叉过滤候选表，无条件时回退到 recentTableCount
+ * - insertOrUpdate：condition 路由查找，data 路由插入（双路由）
+ * - 智能清理：timeColumn 在有主键时仅用于路由，不参与 WHERE 条件
+ * - COUNT 缓存：历史表缓存，当前表实时查
+ * - orderBy 约束：多表查询必须以 timeColumn 排序
+ */
+export class ShardingByTimeCrud extends ShardingBase {
+  private readonly merger: ShardingMerger;
+  private readonly granularity: ShardingTimeGranularity;
+
+  constructor(crudProFactory: CrudProFactory, config: IShardingConfig) {
+    super(crudProFactory, config);
+
+    // 校验
+    if (!config.timeColumn) {
+      throw new Error('[ShardingByTimeCrud] 时间分表必须显式指定 timeColumn 字段');
+    }
+
+    this.granularity = this.typeToGranularity(config.type);
+    this.merger = new ShardingMerger();
+
+    // 初始化 COUNT 缓存
+    if (config.countCache) {
+      const countCache = new ShardingCountCache(
+        config.type, config.baseTable,
+        config.countCache.ttlSeconds, config.countCache.maxSize
+      );
+      this.merger.setCountCache(countCache);
+    }
+  }
+
+  // ============ 路由 ============
+
+  private typeToGranularity(type: ShardingType): ShardingTimeGranularity {
+    switch (type) {
+      case ShardingType.YEAR: return 'year';
+      case ShardingType.MONTH: return 'month';
+      case ShardingType.DAY: return 'day';
+      default: throw new Error(`[ShardingByTimeCrud] 不支持的分表类型: ${type}`);
+    }
+  }
+
+  /** 从 data 中提取时间字段，计算目标分表名 */
+  private resolveTableForInsert(data: Record<string, any>): string {
+    const timeValue = data[this.config.timeColumn!];
+    if (timeValue === undefined || timeValue === null) {
+      throw new Error(`[ShardingByTimeCrud] insert 操作的 data 必须包含时间字段 '${this.config.timeColumn}'`);
+    }
+    const m = moment(timeValue);
+    if (!m.isValid()) {
+      throw new Error(`[ShardingByTimeCrud] 无法解析时间值: ${timeValue}`);
+    }
+    const suffix = getTimeSuffix(m.toDate(), this.granularity);
+    return this.formatTableName(suffix);
+  }
+
+  /** 从 condition 中提取时间字段，计算目标分表名（单表） */
+  private resolveTableForCondition(condition: Record<string, any>): string {
+    const timeColumn = this.config.timeColumn!;
+    const timeValue = condition[timeColumn];
+    if (timeValue === undefined || timeValue === null) {
+      throw new Error(
+        `[ShardingByTimeCrud] 写操作的 condition 必须包含时间字段 '${timeColumn}'，` +
+        `用于路由到正确的分表。`
+      );
+    }
+
+    // 如果是操作符表达式（$gte/$lte），尝试提取范围的 start
+    if (isOperatorExpression(timeValue)) {
+      const range = this.extractTimeRange(condition);
+      if (range) {
+        const suffix = getTimeSuffix(range.start, this.granularity);
+        return this.formatTableName(suffix);
+      }
+    }
+
+    const m = moment(timeValue);
+    if (!m.isValid()) {
+      throw new Error(`[ShardingByTimeCrud] 无法解析时间值: ${timeValue}`);
+    }
+    const suffix = getTimeSuffix(m.toDate(), this.granularity);
+    return this.formatTableName(suffix);
+  }
+
+  /** 解析查询目标表列表 */
+  private async resolveFindTables(reqJson: IRequestModel): Promise<string[]> {
+    const existingTables = await this.getExistingTablesSet();
+    const baseTablePrefix = `${this.config.baseTable}_`;
+    const shardingTables = Array.from(existingTables).filter(t => t.startsWith(baseTablePrefix));
+
+    if (shardingTables.length === 0) return [];
+    shardingTables.sort();
+
+    const condition = reqJson.condition;
+
+    // 有 recentTableCount：取最近N张，再与条件取交集
+    if (this.config.recentTableCount !== undefined) {
+      const recentTables = shardingTables.slice(-this.config.recentTableCount);
+      return this.intersectWithCondition(recentTables, condition);
+    }
+
+    // 无 recentTableCount：所有表与条件取交集，最多取默认数量
+    const intersected = this.intersectWithCondition(shardingTables, condition);
+    const defaultCount = this.getDefaultRecentCount();
+    return intersected.slice(0, defaultCount);
+  }
+
+  private intersectWithCondition(tables: string[], condition?: Record<string, any>): string[] {
+    if (!condition) return this.sortTablesByTimeDesc(tables);
+
+    const timeRange = this.extractTimeRange(condition);
+    if (timeRange) {
+      return this.intersectTablesByTimeRange(tables, timeRange);
+    }
+
+    const singleTimeValue = this.tryExtractTimeFromCondition(condition);
+    if (singleTimeValue) {
+      const suffix = getTimeSuffix(singleTimeValue, this.granularity);
+      const targetTable = this.formatTableName(suffix);
+      return tables.includes(targetTable) ? [targetTable] : [];
+    }
+
+    // condition 存在但不包含时间字段，返回所有表（降序）
+    return this.sortTablesByTimeDesc(tables);
+  }
+
+  private intersectTablesByTimeRange(tables: string[], timeRange: IShardingTimeRange): string[] {
+    const startSuffix = getTimeSuffix(timeRange.start, this.granularity);
+    const endSuffix = getTimeSuffix(timeRange.end, this.granularity);
+    const prefix = `${this.config.baseTable}_`;
+    const prefixLen = prefix.length;
+    return this.sortTablesByTimeDesc(
+      tables.filter(table => {
+        const suffix = table.substring(prefixLen);
+        return suffix >= startSuffix && suffix <= endSuffix;
+      })
+    );
+  }
+
+  private extractTimeRange(condition: Record<string, any>): IShardingTimeRange | null {
+    const colCond = condition[this.config.timeColumn!];
+    if (!colCond || typeof colCond !== 'object') return null;
+
+    const start = colCond.$gte ?? colCond.$gt;
+    const end = colCond.$lte ?? colCond.$lt;
+
+    if (start && end) {
+      const sm = moment(start), em = moment(end);
+      if (!sm.isValid() || !em.isValid()) return null;
+      return { start: sm.toDate(), end: em.toDate() };
+    }
+    if (start) {
+      const sm = moment(start);
+      return sm.isValid() ? { start: sm.toDate(), end: new Date() } : null;
+    }
+    if (end) {
+      const em = moment(end);
+      return em.isValid() ? { start: new Date(0), end: em.toDate() } : null;
+    }
+    return null;
+  }
+
+  private tryExtractTimeFromCondition(condition: Record<string, any>): Date | null {
+    const value = condition[this.config.timeColumn!];
+    if (value === undefined || value === null) return null;
+    const m = moment(value);
+    return m.isValid() ? m.toDate() : null;
+  }
+
+  private sortTablesByTimeDesc(tables: string[]): string[] {
+    return [...tables].sort((a, b) => b.localeCompare(a));
+  }
+
+  private getDefaultRecentCount(): number {
+    if (this.config.recentTableCount !== undefined && this.config.recentTableCount > 0) {
+      return this.config.recentTableCount;
+    }
+    switch (this.granularity) {
+      case 'year': return 2;
+      case 'month': return 3;
+      case 'day': return 7;
+    }
+  }
+
+  private formatTableName(suffix: string): string {
+    const formattedSuffix = this.config.suffixFormatter ? this.config.suffixFormatter(suffix) : suffix;
+    return `${this.config.baseTable}_${formattedSuffix}`;
+  }
+
+  // ============ 写操作 ============
+
+  public async insert(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    this.validateTimeColumnForData(reqJson, 'insert');
+    const targetTable = this.resolveTableForInsert(reqJson.data as Record<string, any>);
+    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('[ShardingByTimeCrud] batchInsert requires non-empty data array');
+    }
+
+    this.validateTimeColumnForBatchData(dataArray, 'batchInsert');
+
+    // 按分表分组
+    const groupedData = new Map<string, Record<string, any>[]>();
+    for (const item of dataArray) {
+      const table = this.resolveTableForInsert(item);
+      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('[ShardingByTimeCrud] 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> {
+    this.validateRoutingFieldForCondition(reqJson, 'update');
+    const targetTable = this.resolveTableForCondition(reqJson.condition!);
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const ctx = await this.executeOnTable(targetTable, cleanedReqJson, 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> {
+    this.validateRoutingFieldForCondition(reqJson, 'delete');
+    const targetTable = this.resolveTableForCondition(reqJson.condition!);
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const ctx = await this.executeOnTable(targetTable, cleanedReqJson, 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> {
+    this.validateRoutingFieldForCondition(reqJson, 'restore');
+    const targetTable = this.resolveTableForCondition(reqJson.condition!);
+
+    if (!reqJson.condition || Object.keys(reqJson.condition).length === 0) {
+      throw new Error('[ShardingByTimeCrud] restore 操作必须指定恢复条件');
+    }
+
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+    const restoreReqJson: IRequestModel = {
+      ...cleanedReqJson,
+      data: { ...cleanedReqJson.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 });
+  }
+
+  /**
+   * 插入或更新（双路由）
+   *
+   * 1. condition 路由定位查找分表
+   * 2. 检查记录是否存在
+   * 3. 存在 → UPDATE（conditionTable）
+   * 4. 不存在 → data 路由定位插入分表，INSERT（dataTable）
+   */
+  public async insertOrUpdate(reqJson: IRequestModel): Promise<CrudUpsertResult> {
+    this.validateTimeColumnForData(reqJson, 'insertOrUpdate');
+    this.validateRoutingFieldForCondition(reqJson, 'insertOrUpdate');
+
+    const conditionTable = this.resolveTableForCondition(reqJson.condition!);
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const existCtx = await this.executeOnTable(conditionTable, cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+    const isExist = existCtx.getResModelItem('is_exist') === true;
+
+    if (isExist) {
+      const updateCtx = await this.executeOnTable(conditionTable, cleanedReqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
+      const updateAffected = updateCtx.getResModel().affected;
+      return new CrudUpsertResult({ insertAffected: undefined, updateAffected, isExist: true, rawContext: updateCtx });
+    }
+
+    const dataTable = this.resolveTableForInsert(reqJson.data as Record<string, any>);
+    await this.createShardingTableIfNeeded(dataTable);
+
+    const insertCtx = await this.executeOnTable(dataTable, cleanedReqJson, KeysOfSimpleSQL.SIMPLE_INSERT);
+    const insertAffected = insertCtx.getResModel().affected;
+    return new CrudUpsertResult({ insertAffected, updateAffected: undefined, isExist: false, rawContext: insertCtx });
+  }
+
+  // ============ 查询操作 ============
+
+  public async findOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>> {
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+    const targetTables = await this.resolveFindTables(reqJson);
+
+    if (targetTables.length === 0) {
+      throw new Error('[ShardingByTimeCrud] 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, cleanedReqJson, 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) {
+        // 表不存在时跳过
+      }
+    }
+    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 cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+    const targetTables = await this.resolveFindTables(reqJson);
+
+    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, cleanedReqJson, 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 cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+    const targetTables = await this.resolveFindTables(reqJson);
+
+    if (targetTables.length === 0) {
+      return new CrudQueryListResult<T>({ rows: [], rawContext: null as any });
+    }
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY);
+      return new CrudQueryListResult<T>({ rows: ctx.getResRows() as T[], rawContext: ctx });
+    }
+
+    this.validateFindOrderBy(reqJson);
+    const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
+
+    const mergeResult = await this.merger.mergeQuery(
+      this.crudProFactory(), tablesForMerge, cleanedReqJson,
+      this.buildCfg(KeysOfSimpleSQL.SIMPLE_QUERY)
+    );
+    return new CrudQueryListResult<T>({ rows: mergeResult.rows as T[], rawContext: mergeResult.lastCtx });
+  }
+
+  public async findPage<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryPageResult<T>> {
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+    const targetTables = await this.resolveFindTables(reqJson);
+
+    if (targetTables.length === 0) {
+      throw new Error('[ShardingByTimeCrud] findPage: no matching tables found');
+    }
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
+      const pageResult = ctx.getResModelForQueryPage();
+      return new CrudQueryPageResult<T>({ rows: pageResult.rows as T[], totalCount: pageResult.total_count, rawContext: ctx });
+    }
+
+    this.validateFindOrderBy(reqJson);
+    const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
+
+    const pageResult = await this.merger.mergePageQuery(
+      this.crudProFactory(), tablesForMerge, cleanedReqJson,
+      this.buildCfg(KeysOfSimpleSQL.SIMPLE_QUERY_PAGE)
+    );
+    return new CrudQueryPageResult<T>({ rows: pageResult.rows as T[], totalCount: pageResult.total_count, rawContext: pageResult.lastCtx });
+  }
+
+  public async findCount(reqJson: IRequestModel): Promise<CrudCountResult> {
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+    const targetTables = await this.resolveFindTables(reqJson);
+
+    if (targetTables.length === 0) {
+      throw new Error('[ShardingByTimeCrud] findCount: no matching tables found');
+    }
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+      return new CrudCountResult({ count: ctx.getResModelItem('total_count') || 0, rawContext: ctx });
+    }
+
+    const countResults: Array<{ count: number; ctx: ExecuteContext | null }> = [];
+    for (const table of targetTables) {
+      countResults.push(await this.findCountFromTable(table, cleanedReqJson));
+    }
+    const totalCount = countResults.reduce((sum, r) => sum + r.count, 0);
+    const firstCtx = countResults.find(r => r.ctx !== null)?.ctx || null;
+    return new CrudCountResult({ count: totalCount, rawContext: firstCtx as any });
+  }
+
+  public async isExist(reqJson: IRequestModel): Promise<CrudExistResult> {
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+    const targetTables = await this.resolveFindTables(reqJson);
+
+    if (targetTables.length === 0) {
+      throw new Error('[ShardingByTimeCrud] isExist: no matching tables found');
+    }
+
+    if (targetTables.length === 1) {
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, 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, cleanedReqJson);
+      if (!firstCtx && result.ctx) firstCtx = result.ctx;
+      if (result.exists) { exists = true; break; }
+    }
+    return new CrudExistResult({ exists, rawContext: firstCtx as any });
+  }
+
+  // ============ 校验 ============
+
+  private validateTimeColumnForData(reqJson: IRequestModel, operation: string): void {
+    const timeColumn = this.config.timeColumn!;
+    const data = reqJson.data as Record<string, any>;
+    if (!data || data[timeColumn] === undefined) {
+      throw new Error(`[ShardingByTimeCrud] ${operation} 操作的 data 必须包含时间字段 '${timeColumn}'`);
+    }
+  }
+
+  private validateTimeColumnForBatchData(dataArray: Record<string, any>[], operation: string): void {
+    const timeColumn = this.config.timeColumn!;
+    for (let i = 0; i < dataArray.length; i++) {
+      if (!dataArray[i] || dataArray[i][timeColumn] === undefined) {
+        throw new Error(`[ShardingByTimeCrud] ${operation} 操作的 data[${i}] 必须包含时间字段 '${timeColumn}'`);
+      }
+    }
+  }
+
+  private validateRoutingFieldForCondition(reqJson: IRequestModel, operation: string): void {
+    const timeColumn = this.config.timeColumn!;
+    const condition = reqJson.condition;
+    if (!condition || !condition[timeColumn]) {
+      throw new Error(
+        `[ShardingByTimeCrud] ${operation} 操作的 condition 必须包含时间字段 '${timeColumn}'，` +
+        `用于路由到正确的分表。`
+      );
+    }
+  }
+
+  private validateFindOrderBy(reqJson: IRequestModel): void {
+    const timeColumn = this.config.timeColumn!;
+    const orderBy = reqJson.orderBy;
+
+    if (!orderBy) {
+      throw new Error(`[ShardingByTimeCrud] 多表查询必须传 orderBy 参数。期望: '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
+    }
+
+    const firstOrderBy = OrderByUtils.getFirstOrderBy(orderBy);
+    if (!firstOrderBy) {
+      throw new Error(`[ShardingByTimeCrud] orderBy 参数格式错误，无法解析`);
+    }
+    if (firstOrderBy.fieldName !== timeColumn) {
+      throw new Error(`[ShardingByTimeCrud] orderBy 首个排序字段必须为 '${timeColumn}'，当前: '${firstOrderBy.fieldName}'`);
+    }
+    const orderType = firstOrderBy.orderType.toUpperCase();
+    if (orderType !== 'ASC' && orderType !== 'DESC') {
+      throw new Error(`[ShardingByTimeCrud] orderBy 排序方向必须是 'ASC' 或 'DESC'，当前: '${firstOrderBy.orderType}'`);
+    }
+  }
+
+  private sortTablesForOrderBy(tables: string[], reqJson: IRequestModel): string[] {
+    const isAsc = OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
+    return [...tables].sort((a, b) => isAsc ? a.localeCompare(b) : b.localeCompare(a));
+  }
+
+  // ============ 时间字段智能清理（详见 TIME_COLUMN_CLEAN_SPEC.md） ============
+
+  private cleanTimeColumnForSingleTableQuery(reqJson: IRequestModel): IRequestModel {
+    const { primaryKey, timeColumn, type } = this.config;
+    if (!timeColumn || ![ShardingType.YEAR, ShardingType.MONTH, ShardingType.DAY].includes(type)) return reqJson;
+
+    const condition = reqJson.condition;
+    if (!condition || typeof condition !== 'object') return reqJson;
+
+    const timeValue = condition[timeColumn];
+    if (timeValue === undefined) return reqJson;
+
+    // 操作符表达式 → 保留，但校验精度
+    if (isOperatorExpression(timeValue)) {
+      this.validateTimeOperatorPrecision(timeValue as any, timeColumn);
+      return reqJson;
+    }
+
+    const hasPrimaryKey = primaryKey && condition[primaryKey] !== undefined;
+
+    if (typeof timeValue === 'string') {
+      const range = expandDateToRange(timeValue);
+      if (hasPrimaryKey) {
+        const { [timeColumn]: _, ...cleanedCondition } = condition;
+        return { ...reqJson, condition: cleanedCondition };
+      }
+      if (range) {
+        return { ...reqJson, condition: { ...condition, [timeColumn]: range } };
+      }
+      return reqJson;
+    }
+
+    if (hasPrimaryKey) {
+      const { [timeColumn]: _, ...cleanedCondition } = condition;
+      return { ...reqJson, condition: cleanedCondition };
+    }
+    return reqJson;
+  }
+
+  private validateTimeOperatorPrecision(operatorValue: Record<string, any>, timeColumn: string): void {
+    const PRECISION_OPERATORS = ['$gte', '$lte', '$gt', '$lt'];
+    const dateOnlyPattern = /^\d{4}-\d{1,2}-\d{1,2}$/;
+
+    for (const op of PRECISION_OPERATORS) {
+      const value = operatorValue[op];
+      if (value !== undefined && typeof value === 'string' && dateOnlyPattern.test(value)) {
+        throw new Error(
+          `[ShardingByTimeCrud] 时间字段 '${timeColumn}' 的 ${op} 值必须精确到秒，` +
+          `当前值: '${value}'。` +
+          `请使用 '${value} 23:59:59'（$lte/$lt）或 '${value} 00:00:00'（$gte/$gt），` +
+          `或直接传粒度字符串由系统自动转换范围。`
+        );
+      }
+    }
+
+    const rangeValue = operatorValue.$range;
+    if (Array.isArray(rangeValue) && rangeValue.length >= 2) {
+      for (let i = 0; i < rangeValue.length; i++) {
+        const val = rangeValue[i];
+        if (typeof val === 'string' && dateOnlyPattern.test(val)) {
+          throw new Error(
+            `[ShardingByTimeCrud] 时间字段 '${timeColumn}' 的 $range[${i}] 值必须精确到秒，` +
+            `当前值: '${val}'。请使用 '${val} ${i === 0 ? '00:00:00' : '23:59:59'}'`
+          );
+        }
+      }
+    }
+  }
+}