midway-fatcms 0.0.8 → 0.0.9

package/dist/libs/crud-sharding/ShardingByKeyCrud.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingByKeyCrud = void 0;
+const ShardingBase_1 = require("./ShardingBase");
+const ShardingByCustomCrud_1 = require("./ShardingByCustomCrud");
+/**
+ * 键值分表 CRUD
+ *
+ * 字段原值即表后缀，一值一表。
+ * 表名格式：baseTable_{shardingColumn值}（如 t_log_east, t_log_west）
+ *
+ * 内部委托 ShardingByCustomCrud 实现所有 CRUD 操作，
+ * 通过 customRouter 实现键值路由逻辑。
+ *
+ * 规范：所有操作必须提供 shardingColumn，否则抛出异常。
+ *
+ * 特性：
+ * - 路由：shardingColumn 的原始值直接作为表后缀
+ * - 不预定义 keyValues，表按需动态创建
+ * - insertOrUpdate：统一由 condition 路由定位分表
+ */
+class ShardingByKeyCrud extends ShardingBase_1.ShardingBase {
+    constructor(crudProFactory, config) {
+        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) => {
+            const formatted = fmt ? fmt(suffix) : suffix;
+            return `${baseTable}_${formatted}`;
+        };
+        const customRouter = (ctx) => {
+            var _a, _b;
+            // 根据操作类型确定字段来源：insert 类从 data，其余从 condition
+            const fromData = ShardingBase_1.ShardingBase.isInsertPhase(ctx);
+            const val = fromData ? (_a = ctx.data) === null || _a === void 0 ? void 0 : _a[col] : (_b = ctx.condition) === null || _b === void 0 ? void 0 : _b[col];
+            if (val != null && val !== '' && val !== undefined) {
+                return formatTable(String(val));
+            }
+            ;
+            throw new Error(`[ShardingByKeyCrud] ${fromData ? 'data' : 'condition'} 必须包含分表字段 '${col}'`);
+        };
+        this.delegate = new ShardingByCustomCrud_1.ShardingByCustomCrud(crudProFactory, { ...config, customRouter });
+    }
+    // ============ 状态同步 ============
+    setBaseCfg(cfg) {
+        super.setBaseCfg(cfg);
+        this.delegate.setBaseCfg(cfg);
+        return this;
+    }
+    setEnableSoftDelete(enable) {
+        super.setEnableSoftDelete(enable);
+        this.delegate.setEnableSoftDelete(enable);
+        return this;
+    }
+    // ============ CRUD 方法：全部委托 ============
+    insert(r) { return this.delegate.insert(r); }
+    batchInsert(r) { return this.delegate.batchInsert(r); }
+    update(r) { return this.delegate.update(r); }
+    delete(r) { return this.delegate.delete(r); }
+    restore(r) { return this.delegate.restore(r); }
+    insertOrUpdate(r) { return this.delegate.insertOrUpdate(r); }
+    findOne(r) { return this.delegate.findOne(r); }
+    findUniqueOne(r) { return this.delegate.findUniqueOne(r); }
+    findList(r) { return this.delegate.findList(r); }
+    findPage(r) { return this.delegate.findPage(r); }
+    findCount(r) { return this.delegate.findCount(r); }
+    isExist(r) { return this.delegate.isExist(r); }
+}
+exports.ShardingByKeyCrud = ShardingByKeyCrud;

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

@@ -0,0 +1,66 @@
+import { IRequestModel } from '../../libs/crud-pro/interfaces';
+import { IShardingConfig, 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
+ *
+ * 支持 YEAR / MONTH / DAY 三种时间粒度分表。
+ * 路由规则：根据 timeColumn 的值计算时间后缀，定位到对应分表。
+ *
+ * 特性：
+ * - 插入：data 中的 timeColumn 决定目标分表
+ * - 更新/删除：condition 中的 timeColumn 定位分表
+ * - 查询：时间范围条件交叉过滤候选表，无条件时回退到 recentTableCount
+ * - insertOrUpdate：condition 路由查找，data 路由插入（双路由）
+ * - 智能清理：timeColumn 在有主键时仅用于路由，不参与 WHERE 条件
+ * - COUNT 缓存：历史表缓存，当前表实时查
+ * - orderBy 约束：多表查询必须以 timeColumn 排序
+ */
+export declare class ShardingByTimeCrud extends ShardingBase {
+    private readonly merger;
+    private readonly granularity;
+    constructor(crudProFactory: CrudProFactory, config: IShardingConfig);
+    private typeToGranularity;
+    /** 从 data 中提取时间字段，计算目标分表名 */
+    private resolveTableForInsert;
+    /** 从 condition 中提取时间字段，计算目标分表名（单表） */
+    private resolveTableForCondition;
+    /** 解析查询目标表列表 */
+    private resolveFindTables;
+    private intersectWithCondition;
+    private intersectTablesByTimeRange;
+    private extractTimeRange;
+    private tryExtractTimeFromCondition;
+    private sortTablesByTimeDesc;
+    private getDefaultRecentCount;
+    private formatTableName;
+    insert(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    batchInsert(reqJson: IRequestModel): Promise<ShardingBatchInsertResult>;
+    update(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    delete(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    restore(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    /**
+     * 插入或更新（双路由）
+     *
+     * 1. condition 路由定位查找分表
+     * 2. 检查记录是否存在
+     * 3. 存在 → UPDATE（conditionTable）
+     * 4. 不存在 → data 路由定位插入分表，INSERT（dataTable）
+     */
+    insertOrUpdate(reqJson: IRequestModel): Promise<CrudUpsertResult>;
+    findOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
+    findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
+    findList<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryListResult<T>>;
+    findPage<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryPageResult<T>>;
+    findCount(reqJson: IRequestModel): Promise<CrudCountResult>;
+    isExist(reqJson: IRequestModel): Promise<CrudExistResult>;
+    private validateTimeColumnForData;
+    private validateTimeColumnForBatchData;
+    private validateRoutingFieldForCondition;
+    private validateFindOrderBy;
+    private sortTablesForOrderBy;
+    private cleanTimeColumnForSingleTableQuery;
+    private validateTimeOperatorPrecision;
+}

package/dist/libs/crud-sharding/ShardingByTimeCrud.js

@@ -0,0 +1,524 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingByTimeCrud = void 0;
+const moment = require("moment");
+const OrderByUtils_1 = require("../../libs/crud-pro/utils/OrderByUtils");
+const keys_1 = require("../../libs/crud-pro/models/keys");
+const ShardingConfig_1 = require("./ShardingConfig");
+const ShardingBase_1 = require("./ShardingBase");
+const ShardingMerger_1 = require("./ShardingMerger");
+const ShardingCountCache_1 = require("./ShardingCountCache");
+const CrudResult_1 = require("../../libs/crud-pro/models/CrudResult");
+const ShardingResult_1 = require("./ShardingResult");
+const ShardingUtils_1 = require("./ShardingUtils");
+/**
+ * 时间分表 CRUD
+ *
+ * 支持 YEAR / MONTH / DAY 三种时间粒度分表。
+ * 路由规则：根据 timeColumn 的值计算时间后缀，定位到对应分表。
+ *
+ * 特性：
+ * - 插入：data 中的 timeColumn 决定目标分表
+ * - 更新/删除：condition 中的 timeColumn 定位分表
+ * - 查询：时间范围条件交叉过滤候选表，无条件时回退到 recentTableCount
+ * - insertOrUpdate：condition 路由查找，data 路由插入（双路由）
+ * - 智能清理：timeColumn 在有主键时仅用于路由，不参与 WHERE 条件
+ * - COUNT 缓存：历史表缓存，当前表实时查
+ * - orderBy 约束：多表查询必须以 timeColumn 排序
+ */
+class ShardingByTimeCrud extends ShardingBase_1.ShardingBase {
+    constructor(crudProFactory, config) {
+        super(crudProFactory, config);
+        // 校验
+        if (!config.timeColumn) {
+            throw new Error('[ShardingByTimeCrud] 时间分表必须显式指定 timeColumn 字段');
+        }
+        this.granularity = this.typeToGranularity(config.type);
+        this.merger = new ShardingMerger_1.ShardingMerger();
+        // 初始化 COUNT 缓存
+        if (config.countCache) {
+            const countCache = new ShardingCountCache_1.ShardingCountCache(config.type, config.baseTable, config.countCache.ttlSeconds, config.countCache.maxSize);
+            this.merger.setCountCache(countCache);
+        }
+    }
+    // ============ 路由 ============
+    typeToGranularity(type) {
+        switch (type) {
+            case ShardingConfig_1.ShardingType.YEAR: return 'year';
+            case ShardingConfig_1.ShardingType.MONTH: return 'month';
+            case ShardingConfig_1.ShardingType.DAY: return 'day';
+            default: throw new Error(`[ShardingByTimeCrud] 不支持的分表类型: ${type}`);
+        }
+    }
+    /** 从 data 中提取时间字段，计算目标分表名 */
+    resolveTableForInsert(data) {
+        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 = (0, ShardingUtils_1.getTimeSuffix)(m.toDate(), this.granularity);
+        return this.formatTableName(suffix);
+    }
+    /** 从 condition 中提取时间字段，计算目标分表名（单表） */
+    resolveTableForCondition(condition) {
+        const timeColumn = this.config.timeColumn;
+        const timeValue = condition[timeColumn];
+        if (timeValue === undefined || timeValue === null) {
+            throw new Error(`[ShardingByTimeCrud] 写操作的 condition 必须包含时间字段 '${timeColumn}'，` +
+                `用于路由到正确的分表。`);
+        }
+        // 如果是操作符表达式（$gte/$lte），尝试提取范围的 start
+        if ((0, ShardingUtils_1.isOperatorExpression)(timeValue)) {
+            const range = this.extractTimeRange(condition);
+            if (range) {
+                const suffix = (0, ShardingUtils_1.getTimeSuffix)(range.start, this.granularity);
+                return this.formatTableName(suffix);
+            }
+        }
+        const m = moment(timeValue);
+        if (!m.isValid()) {
+            throw new Error(`[ShardingByTimeCrud] 无法解析时间值: ${timeValue}`);
+        }
+        const suffix = (0, ShardingUtils_1.getTimeSuffix)(m.toDate(), this.granularity);
+        return this.formatTableName(suffix);
+    }
+    /** 解析查询目标表列表 */
+    async resolveFindTables(reqJson) {
+        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);
+    }
+    intersectWithCondition(tables, condition) {
+        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 = (0, ShardingUtils_1.getTimeSuffix)(singleTimeValue, this.granularity);
+            const targetTable = this.formatTableName(suffix);
+            return tables.includes(targetTable) ? [targetTable] : [];
+        }
+        // condition 存在但不包含时间字段，返回所有表（降序）
+        return this.sortTablesByTimeDesc(tables);
+    }
+    intersectTablesByTimeRange(tables, timeRange) {
+        const startSuffix = (0, ShardingUtils_1.getTimeSuffix)(timeRange.start, this.granularity);
+        const endSuffix = (0, ShardingUtils_1.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;
+        }));
+    }
+    extractTimeRange(condition) {
+        var _a, _b;
+        const colCond = condition[this.config.timeColumn];
+        if (!colCond || typeof colCond !== 'object')
+            return null;
+        const start = (_a = colCond.$gte) !== null && _a !== void 0 ? _a : colCond.$gt;
+        const end = (_b = colCond.$lte) !== null && _b !== void 0 ? _b : 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;
+    }
+    tryExtractTimeFromCondition(condition) {
+        const value = condition[this.config.timeColumn];
+        if (value === undefined || value === null)
+            return null;
+        const m = moment(value);
+        return m.isValid() ? m.toDate() : null;
+    }
+    sortTablesByTimeDesc(tables) {
+        return [...tables].sort((a, b) => b.localeCompare(a));
+    }
+    getDefaultRecentCount() {
+        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;
+        }
+    }
+    formatTableName(suffix) {
+        const formattedSuffix = this.config.suffixFormatter ? this.config.suffixFormatter(suffix) : suffix;
+        return `${this.config.baseTable}_${formattedSuffix}`;
+    }
+    // ============ 写操作 ============
+    async insert(reqJson) {
+        this.validateTimeColumnForData(reqJson, 'insert');
+        const targetTable = this.resolveTableForInsert(reqJson.data);
+        await this.createShardingTableIfNeeded(targetTable);
+        const ctx = await this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+    }
+    async batchInsert(reqJson) {
+        var _a, _b;
+        const dataArray = reqJson.data;
+        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();
+        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 = [];
+        let lastContext = null;
+        for (const [table, items] of groupedData.entries()) {
+            try {
+                const ctx = await this.executeOnTable(table, { data: items }, keys_1.KeysOfSimpleSQL.SIMPLE_BATCH_INSERT);
+                lastContext = ctx;
+                results.push({ table, affected: ((_a = ctx.getResModelItem('affected')) === null || _a === void 0 ? void 0 : _a.affectedRows) || items.length, rowCount: items.length, error: null, context: ctx });
+            }
+            catch (e) {
+                results.push({ table, affected: 0, rowCount: items.length, error: e, 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 || ((_b = results.find(r => r.context)) === null || _b === void 0 ? void 0 : _b.context);
+        if (!finalContext)
+            throw new Error('[ShardingByTimeCrud] batchInsert failed - no successful inserts');
+        return new ShardingResult_1.ShardingBatchInsertResult({ totalAffected, tableResults, tableCount: groupedData.size, success: errors.length === 0, errors, lastContext: finalContext });
+    }
+    async update(reqJson) {
+        this.validateRoutingFieldForCondition(reqJson, 'update');
+        const targetTable = this.resolveTableForCondition(reqJson.condition);
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const ctx = await this.executeOnTable(targetTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+    }
+    async delete(reqJson) {
+        this.validateRoutingFieldForCondition(reqJson, 'delete');
+        const targetTable = this.resolveTableForCondition(reqJson.condition);
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const ctx = await this.executeOnTable(targetTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_DELETE);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+    }
+    async restore(reqJson) {
+        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 = {
+            ...cleanedReqJson,
+            data: { ...cleanedReqJson.data, deleted_at: 0, deleted_by: '' },
+        };
+        const ctx = await this.executeOnTable(targetTable, restoreReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.CrudWriteResult({ affectedRows: affected.affectedRows, insertId: affected.insertId, rawContext: ctx });
+    }
+    /**
+     * 插入或更新（双路由）
+     *
+     * 1. condition 路由定位查找分表
+     * 2. 检查记录是否存在
+     * 3. 存在 → UPDATE（conditionTable）
+     * 4. 不存在 → data 路由定位插入分表，INSERT（dataTable）
+     */
+    async insertOrUpdate(reqJson) {
+        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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+        const isExist = existCtx.getResModelItem('is_exist') === true;
+        if (isExist) {
+            const updateCtx = await this.executeOnTable(conditionTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE);
+            const updateAffected = updateCtx.getResModel().affected;
+            return new CrudResult_1.CrudUpsertResult({ insertAffected: undefined, updateAffected, isExist: true, rawContext: updateCtx });
+        }
+        const dataTable = this.resolveTableForInsert(reqJson.data);
+        await this.createShardingTableIfNeeded(dataTable);
+        const insertCtx = await this.executeOnTable(dataTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT);
+        const insertAffected = insertCtx.getResModel().affected;
+        return new CrudResult_1.CrudUpsertResult({ insertAffected, updateAffected: undefined, isExist: false, rawContext: insertCtx });
+    }
+    // ============ 查询操作 ============
+    async findOne(reqJson) {
+        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 = null;
+        let lastTable;
+        for (const table of targetTables) {
+            try {
+                const ctx = await this.executeOnTable(table, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
+                lastCtx = ctx;
+                lastTable = table;
+                const row = ctx.getOneObj();
+                if (row) {
+                    return new CrudResult_1.CrudQueryOneResult({ row: row, rawContext: ctx, debugInfo: this.buildDebugInfo(table, reqJson.condition), fromTable: table });
+                }
+            }
+            catch (e) {
+                // 表不存在时跳过
+            }
+        }
+        return new CrudResult_1.CrudQueryOneResult({ row: null, rawContext: lastCtx, debugInfo: this.buildDebugInfo(targetTables[0], reqJson.condition), fromTable: lastTable });
+    }
+    async findUniqueOne(reqJson) {
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
+        if (targetTables.length === 0) {
+            return new CrudResult_1.CrudQueryOneResult({ row: null, rawContext: null, debugInfo: this.buildDebugInfo(undefined, reqJson.condition), fromTable: null });
+        }
+        const allRows = [];
+        const foundTables = [];
+        let firstCtx = null;
+        for (const table of targetTables) {
+            try {
+                const ctx = await this.executeOnTable(table, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY, { maxLimit: 2 });
+                if (!firstCtx)
+                    firstCtx = ctx;
+                const rows = ctx.getResRows();
+                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 CrudResult_1.CrudQueryOneResult({
+            row: allRows[0] || null, rawContext: firstCtx,
+            debugInfo: this.buildDebugInfo(fromTable || targetTables[0], reqJson.condition),
+            fromTable: fromTable || targetTables[0],
+        });
+    }
+    async findList(reqJson) {
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
+        if (targetTables.length === 0) {
+            return new CrudResult_1.CrudQueryListResult({ rows: [], rawContext: null });
+        }
+        if (targetTables.length === 1) {
+            const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY);
+            return new CrudResult_1.CrudQueryListResult({ rows: ctx.getResRows(), rawContext: ctx });
+        }
+        this.validateFindOrderBy(reqJson);
+        const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
+        const mergeResult = await this.merger.mergeQuery(this.crudProFactory(), tablesForMerge, cleanedReqJson, this.buildCfg(keys_1.KeysOfSimpleSQL.SIMPLE_QUERY));
+        return new CrudResult_1.CrudQueryListResult({ rows: mergeResult.rows, rawContext: mergeResult.lastCtx });
+    }
+    async findPage(reqJson) {
+        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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
+            const pageResult = ctx.getResModelForQueryPage();
+            return new CrudResult_1.CrudQueryPageResult({ rows: pageResult.rows, 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(keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_PAGE));
+        return new CrudResult_1.CrudQueryPageResult({ rows: pageResult.rows, totalCount: pageResult.total_count, rawContext: pageResult.lastCtx });
+    }
+    async findCount(reqJson) {
+        var _a;
+        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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+            return new CrudResult_1.CrudCountResult({ count: ctx.getResModelItem('total_count') || 0, rawContext: ctx });
+        }
+        const countResults = [];
+        for (const table of targetTables) {
+            countResults.push(await this.findCountFromTable(table, cleanedReqJson));
+        }
+        const totalCount = countResults.reduce((sum, r) => sum + r.count, 0);
+        const firstCtx = ((_a = countResults.find(r => r.ctx !== null)) === null || _a === void 0 ? void 0 : _a.ctx) || null;
+        return new CrudResult_1.CrudCountResult({ count: totalCount, rawContext: firstCtx });
+    }
+    async isExist(reqJson) {
+        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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+            return new CrudResult_1.CrudExistResult({ exists: ctx.getResModelItem('is_exist') === true, rawContext: ctx });
+        }
+        let exists = false;
+        let firstCtx = 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 CrudResult_1.CrudExistResult({ exists, rawContext: firstCtx });
+    }
+    // ============ 校验 ============
+    validateTimeColumnForData(reqJson, operation) {
+        const timeColumn = this.config.timeColumn;
+        const data = reqJson.data;
+        if (!data || data[timeColumn] === undefined) {
+            throw new Error(`[ShardingByTimeCrud] ${operation} 操作的 data 必须包含时间字段 '${timeColumn}'`);
+        }
+    }
+    validateTimeColumnForBatchData(dataArray, operation) {
+        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}'`);
+            }
+        }
+    }
+    validateRoutingFieldForCondition(reqJson, operation) {
+        const timeColumn = this.config.timeColumn;
+        const condition = reqJson.condition;
+        if (!condition || !condition[timeColumn]) {
+            throw new Error(`[ShardingByTimeCrud] ${operation} 操作的 condition 必须包含时间字段 '${timeColumn}'，` +
+                `用于路由到正确的分表。`);
+        }
+    }
+    validateFindOrderBy(reqJson) {
+        const timeColumn = this.config.timeColumn;
+        const orderBy = reqJson.orderBy;
+        if (!orderBy) {
+            throw new Error(`[ShardingByTimeCrud] 多表查询必须传 orderBy 参数。期望: '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
+        }
+        const firstOrderBy = OrderByUtils_1.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}'`);
+        }
+    }
+    sortTablesForOrderBy(tables, reqJson) {
+        const isAsc = OrderByUtils_1.OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
+        return [...tables].sort((a, b) => isAsc ? a.localeCompare(b) : b.localeCompare(a));
+    }
+    // ============ 时间字段智能清理（详见 TIME_COLUMN_CLEAN_SPEC.md） ============
+    cleanTimeColumnForSingleTableQuery(reqJson) {
+        const { primaryKey, timeColumn, type } = this.config;
+        if (!timeColumn || ![ShardingConfig_1.ShardingType.YEAR, ShardingConfig_1.ShardingType.MONTH, ShardingConfig_1.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 ((0, ShardingUtils_1.isOperatorExpression)(timeValue)) {
+            this.validateTimeOperatorPrecision(timeValue, timeColumn);
+            return reqJson;
+        }
+        const hasPrimaryKey = primaryKey && condition[primaryKey] !== undefined;
+        if (typeof timeValue === 'string') {
+            const range = (0, ShardingUtils_1.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;
+    }
+    validateTimeOperatorPrecision(operatorValue, timeColumn) {
+        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'}'`);
+                }
+            }
+        }
+    }
+}
+exports.ShardingByTimeCrud = ShardingByTimeCrud;