midway-fatcms 0.0.4 → 0.0.6

package/dist/libs/crud-sharding/ROUTING_LOGIC.md

@@ -0,0 +1,944 @@
+# 分表 CRUD 使用指南
+
+ShardingCrudPro 提供时间、范围、哈希、自定义四种分表策略，支持跨分表查询与自动合并分页。
+
+> 在服务层通过 `curdProService.getShardingCrud()` 获取实例，底层 CrudPro 用法见 [crud-pro/README.md](../crud-pro/README.md)。
+
+## 快速开始
+
+```typescript
+import { ShardingType } from '@/libs/crud-sharding';
+
+// 1. 获取分表操作器
+const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  timeColumn: 'created_at',
+});
+
+// 2. 插入（自动路由到 t_order_202403）
+await sharding.insert({
+  data: { order_id: '001', amount: 100, created_at: '2024-03-15' }
+});
+
+// 3. 分页查询（自动跨表合并）
+const result = await sharding.queryPage({
+  condition: { status: 'completed' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+```
+
+## 配置参考
+
+```typescript
+interface IShardingConfig {
+  type: ShardingType;           // 分表类型（YEAR/MONTH/DAY/RANGE/HASH/CUSTOM）
+  baseTable: string;            // 基础表名
+
+  // 时间分表
+  timeColumn?: string;          // 时间字段名（默认 created_at）
+  recentTableCount?: number;    // 无时间条件时查询最近N张表（默认3）
+
+  // 范围/哈希分表
+  shardingColumn?: string;      // 分表字段名
+  tableCount?: number;          // 分表数量（默认10）
+
+  // COUNT 缓存（仅时间分表有效）
+  countCache?: {
+    ttlSeconds?: number;        // 缓存有效期（秒），默认300
+    maxSize?: number;           // 最大缓存条目数，默认1000
+  };
+
+  // 自定义配置
+  customRouter?: Function;      // CUSTOM 类型的自定义路由函数
+  suffixFormatter?: Function;   // 后缀格式化函数
+}
+```
+
+## 一、路由策略总览
+
+分表路由的核心逻辑：**根据操作类型决定从 `data` 还是 `condition` 中提取分表字段**。
+
+| 操作类型 | 实际使用的字段 | 路由依据 | 字段提取逻辑 | 说明 |
+|---------|--------------|---------|-------------|------|
+| `insert` | `data` | `reqJson.data` | `data[分表字段]` | 插入单条数据 |
+| `batchInsert` | `data` (数组) | `reqJson.data` | `data[i][分表字段]` | 智能批量插入，支持跨分表 |
+| `update` | `condition` + `data` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表，data是更新内容 |
+| `delete` | `condition` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表 |
+| `insertOrUpdate` | `condition` + `data` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表，**注意：data中的分表字段可能与condition指向不同分表** |
+| `insertOnDuplicateUpdate` | `condition` + `data` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表，**注意：data中的分表字段可能与condition指向不同分表** |
+| `queryOne` | `condition` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表 |
+| `query` | `condition` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表，**必须传 orderBy** |
+| `queryPage` | `condition` + 分页 | `reqJson.condition` | `condition[分表字段]` | 条件决定分表，**必须传 orderBy** |
+| `queryCount` | `condition` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表 |
+| `isExist` | `condition` | `reqJson.condition` | `condition[分表字段]` | 条件决定分表 |
+
+### 关键结论
+
+- **插入类操作**（insert/batchInsert）：只使用 `data`，不使用 `condition`
+- **查询类操作**（query/delete/isExist等）：只使用 `condition`，不使用 `data`
+- **更新类操作**（update/insertOrUpdate/insertOnDuplicateUpdate）：`condition` 用于路由，`data` 是更新内容
+
+## 二、查询能力边界
+
+### 2.1 使用约束
+
+时间分表查询（`query`/`queryPage`）有以下强制约束：
+
+| 约束项 | 要求 | 原因 |
+|-------|------|------|
+| **orderBy 必传** | 必须传 orderBy 参数 | 分表查询必须明确排序方式 |
+| **排序字段** | 必须为 `timeColumn DESC` 或 `timeColumn ASC`（如 `created_at DESC` / `created_at ASC`） | 利用分表顺序特性，无需内存排序 |
+| **排序方向** | 支持 `DESC`（最新在前）和 `ASC`（最旧在前） | DESC 时表顺序 新→旧，ASC 时表顺序 旧→新 |
+
+### 2.2 不支持的场景
+
+以下场景会直接抛出异常：
+
+```typescript
+// ❌ 缺少 orderBy
+await sharding.query({ condition: { status: 'pending' } });
+// Error: [ShardingCrudPro] 查询操作必须传 orderBy 参数。期望值: 'created_at DESC' 或 'created_at ASC'
+
+// ❌ 排序字段错误
+await sharding.query({ 
+  condition: { status: 'pending' }, 
+  orderBy: 'id DESC' 
+});
+// Error: [ShardingCrudPro] orderBy 参数必须是 'created_at DESC' 或 'created_at ASC'，当前值: 'id DESC'
+```
+
+### 2.3 正确用法
+
+```typescript
+// ✅ 字符串格式 - DESC（最新在前）
+await sharding.query({ 
+  condition: { status: 'pending' }, 
+  orderBy: 'created_at DESC'
+});
+
+// ✅ 字符串格式 - ASC（最旧在前）
+await sharding.query({ 
+  condition: { status: 'pending' }, 
+  orderBy: 'created_at ASC'
+});
+
+// ✅ 数组格式（单个排序字段）
+await sharding.query({ 
+  condition: { status: 'pending' }, 
+  orderBy: [{ fieldName: 'created_at', orderType: 'DESC' }]
+});
+
+// ✅ 数组格式（多字段排序，首字段必须为 timeColumn DESC/ASC）
+await sharding.query({ 
+  condition: { status: 'pending' }, 
+  orderBy: ['created_at DESC', 'id ASC']
+});
+
+// ✅ 分页查询
+const result = await sharding.queryPage({
+  condition: { status: 'pending' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC'  // 或 'created_at ASC'
+});
+```
+
+### 2.4 性能优化原理
+
+在 `orderBy = timeColumn DESC/ASC` 约束下：
+
+1. **表顺序保证**：ShardingRouter 返回的表顺序为 **新→旧**，ASC 时由 ShardingCrudPro 反转为 **旧→新**
+2. **无需内存排序**：每表内部按 `timeColumn DESC/ASC` 排序后，直接拼接即正确顺序
+3. **直接定位目标表**：根据各表 count 累计值，直接跳过无关表，只查询包含目标数据的表
+4. **精确表内偏移**：计算目标表内的 offset 和 limit，避免取多余数据
+
+```
+查询请求：pageNo=100, pageSize=10
+表顺序：[t_order_202403, t_order_202402, t_order_202401]
+         ↓ 最新表    ↓ 次新表    ↓ 最旧表
+
+执行流程：
+1. 统计各表数量：[5, 20, 1000]
+2. 累计计算：[5, 25, 1025]
+3. 目标范围：第 990~1000 条
+4. 定位：202403 累计5 < 990，跳过；202402 累计25 < 990，跳过
+5. 命中：202401 累计1025 >= 990
+   - 表内偏移 innerOffset = 990 - 25 = 965
+   - 取条数 innerLimit = 1000 - 990 = 10
+6. 只查 202401 一张表：OFFSET 965 LIMIT 10
+```
+
+## 三、各操作的路由规则
+
+### 写操作（insert/update/delete）
+
+写操作必须路由到**单一目标表**，无法确定时抛出异常。
+
+| 操作 | 字段来源 | 路由方式 | 备注 |
+|------|---------|---------|------|
+| `insert` | `data[分表字段]` | 提取值 → 计算后缀 | 分表字段必须在 data 中 |
+| `batchInsert` | `data[i][分表字段]` | 每条数据单独计算 | 自动按分表分组，支持跨分表并行写入 |
+| `update` | `condition[分表字段]` | 提取值 → 计算后缀 | condition 决定分表，data 是更新内容 |
+| `delete` | `condition[分表字段]` | 提取值 → 计算后缀 | condition 决定分表 |
+| `insertOrUpdate` | `condition[分表字段]` | 提取值 → 计算后缀 | condition 决定分表 |
+| `insertOnDuplicateUpdate` | `condition[分表字段]` | 提取值 → 计算后缀 | condition 决定分表 |
+
+> **注意**：`insertOrUpdate`/`insertOnDuplicateUpdate` 使用 `condition` 路由，如果 `data` 中的分表字段指向不同分表，可能导致数据插入位置不符合预期。
+
+### 查询操作（query/queryOne/queryPage/queryCount/isExist）
+
+查询操作可路由到**多个分表**，结果由 ShardingMerger 自动合并。
+
+- 自动过滤不存在的表
+- 支持跨分表分页、排序
+- 时间分表：根据 condition 中的时间范围生成候选表，与真实存在的表取交集
+- 范围/哈希分表：condition 中有分表字段值 → 路由到单表；无 → 查询所有分表
+
+### 各分表策略路由差异
+
+**时间分表（YEAR/MONTH/DAY）**：
+
+| 操作 | 路由逻辑 |
+|------|---------|
+| insert/batchInsert | 从 data 提取时间 → 计算后缀 → 单表 |
+| update/delete | 从 condition 提取时间 → 计算后缀 → 单表 |
+| query 系列 | 从 condition 提取时间范围 → 生成候选表 → 与真实表取交集 → 多表 |
+
+查询时无法确定时间范围，默认返回最近N个分表（年3个/月12个/日7个）。
+
+**范围分表（RANGE）**：
+
+- 数值字段：`Math.abs(value) % tableCount`
+- 非数值字段：`Math.abs(hash(String(value))) % tableCount`
+
+**哈希分表（HASH）**：
+
+- 使用 djb2 哈希算法：`Math.abs(simpleHash(String(value))) % tableCount`
+- 后缀零填充：`String(index).padStart(2, '0')`
+
+**自定义分表（CUSTOM）**：
+
+- 调用用户提供的 `customRouter` 函数，完全自定义路由逻辑
+
+### batchInsert 跨分表
+
+`batchInsert` 为每条数据单独计算目标分表，自动按分表分组后并行写入：
+
+```typescript
+const result = await sharding.batchInsert({
+  data: [
+    { order_id: '001', created_at: '2024-01-15' },  // → t_order_202401
+    { order_id: '002', created_at: '2024-02-10' },  // → t_order_202402
+    { order_id: '003', created_at: '2024-03-05' },  // → t_order_202403
+  ]
+});
+console.log(result.tableCount);    // 3（跨3张分表）
+console.log(result.totalAffected); // 3
+```
+
+### 注意事项
+
+1. **插入类操作只使用 data**：`insert`/`batchInsert` 只需要在 `data` 中包含分表字段，不需要传 `condition`
+2. **查询类操作只使用 condition**：`query`/`delete`/`isExist` 等只需要在 `condition` 中包含分表字段，不需要传 `data`
+3. **更新类操作需要同时传 condition 和 data**：`condition` 用于路由，`data` 是更新内容
+4. **batchInsert 支持跨分表**：`batchInsert` 会自动按分表分组，支持数据分布在不同分表的场景
+5. **查询的时间范围限制**：时间分表查询时，如果无法确定时间范围，默认只查询最近N个分表（避免全表扫描）
+
+## 四、使用示例
+
+### 4.1 插入数据（只传 data）
+
+```typescript
+const sharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  timeColumn: 'created_at',
+});
+
+// 路由到 t_order_202403
+await sharding.insert({
+  data: { 
+    order_id: '001', 
+    amount: 100, 
+    created_at: '2024-03-15'  // ← 分表字段必须在 data 中
+  }
+  // 注意：insert 操作不需要传 condition
+});
+```
+
+### 4.2 更新数据
+
+```typescript
+// 路由到 t_order_202403
+await sharding.update({
+  condition: { 
+    created_at: '2024-03-15'  // ← 分表字段在 condition 中（用于路由）
+  },
+  data: { amount: 200 }  // ← 更新内容（不参与路由）
+});
+```
+
+### 4.3 删除数据
+
+```typescript
+// 路由到 t_order_202403
+await sharding.delete({
+  condition: { 
+    created_at: '2024-03-15'  // ← 分表字段在 condition 中
+  }
+  // 注意：delete 操作不需要传 data
+});
+```
+
+### 4.4 查询数据
+
+```typescript
+// 查询 t_order_202401, t_order_202402, t_order_202403
+const orders = await sharding.query({
+  condition: { 
+    created_at: { 
+      $gte: '2024-01-01', 
+      $lte: '2024-03-31'  // ← 分表字段范围在 condition 中
+    } 
+  }
+});
+```
+
+### 4.5 批量插入
+
+```typescript
+// 数据自动分组到不同分表
+const result = await sharding.batchInsert({
+  data: [
+    { order_id: '001', created_at: '2024-01-15' },  // → t_order_202401
+    { order_id: '002', created_at: '2024-02-10' },  // → t_order_202402
+    { order_id: '003', created_at: '2024-03-05' },  // → t_order_202403
+  ]
+  // 注意：batchInsert 只需要传 data
+});
+
+console.log(result.tableCount);  // 3
+console.log(result.totalAffected);  // 3
+```
+
+### 4.6 分页查询
+
+```typescript
+// 场景1：基础分页查询（单表）
+const result = await sharding.queryPage({
+  condition: { status: 'completed' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',  // 必须传，且必须为 timeColumn DESC
+});
+console.log(result.rows);        // 10条记录
+console.log(result.total_count); // 符合条件的总数
+
+// 场景2：跨多表分页查询（自动合并）
+// 假设存在表：t_order_202401(50条), t_order_202402(80条), t_order_202403(30条)
+// 查询第2页，每页20条（全局第21-40条）
+const result2 = await sharding.queryPage({
+  condition: {
+    created_at: { $gte: '2024-01-01', $lte: '2024-03-31' },
+    status: 'pending'
+  },
+  pageNo: 2,
+  pageSize: 20,
+  orderBy: 'created_at DESC',
+});
+// 执行过程：
+// 1. 统计各表数量：[50, 80, 30]，累计：[50, 130, 160]
+// 2. 目标范围：第21-40条（全局偏移20，取20条）
+// 3. 定位：202401累计50 >= 21? 是，命中202401
+// 4. 202401表内偏移：21 - 1 = 20（从第21条开始，即偏移20），取20条
+// 结果仅包含202401的数据，无需跨表合并
+
+// 场景3：大数据量分页（第100页）
+const result3 = await sharding.queryPage({
+  condition: { created_at: { $gte: '2024-01-01' } },
+  pageNo: 100,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+// 自动定位到包含第990-1000条数据的分表，只查询必要的表
+
+// 场景4：带列筛选的分页
+const result4 = await sharding.queryPage({
+  condition: { status: 'paid' },
+  columns: ['order_id', 'amount', 'created_at'],  // 只返回指定列
+  pageNo: 1,
+  pageSize: 5,
+  orderBy: 'created_at DESC',
+});
+
+// 场景5：最后一页（数据不足pageSize）
+const lastPage = await sharding.queryPage({
+  condition: {},
+  pageNo: 999,  // 超出实际页数
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+// 返回空数组：lastPage.rows = [], lastPage.total_count = 实际总数
+
+// 场景6：orderBy 数组格式（基础）
+const result6 = await sharding.queryPage({
+  condition: { status: 'completed' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: [{ fieldName: 'created_at', orderType: 'desc' }],  // 单个排序字段
+});
+
+// 场景7：orderBy 数组格式（多字段排序）
+// 首个字段必须是 timeColumn DESC，后续可附加次级排序
+const result7 = await sharding.queryPage({
+  condition: { type: 'order' },
+  pageNo: 1,
+  pageSize: 20,
+  orderBy: [
+    { fieldName: 'created_at', orderType: 'desc' },  // 主排序：时间倒序（必须）
+    { fieldName: 'order_id', orderType: 'asc' }      // 次排序：订单号正序
+  ],
+});
+// 说明：分表顺序已由 created_at DESC 保证，order_id 排序在单表内生效
+// 最终结果按分表顺序拼接，每表内部按 (created_at DESC, order_id ASC) 排序
+
+// 场景8：orderBy 数组格式（混合字符串和对象）
+// 数组中字符串会被自动转为对象：'amount' → { fieldName: 'amount', orderType: 'asc' }
+const result8 = await sharding.queryPage({
+  condition: { user_id: 'U123' },
+  pageNo: 2,
+  pageSize: 15,
+  orderBy: [
+    { fieldName: 'created_at', orderType: 'desc' },  // 对象格式
+    'amount'  // 字符串格式，自动转为 { fieldName: 'amount', orderType: 'asc' }
+  ],
+});
+
+// 场景9：orderBy 字符串简写格式（+/- 后缀）
+const result9 = await sharding.queryPage({
+  condition: { category: 'electronics' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at-,amount+,order_id'  // created_at降序, amount升序, order_id升序(默认)
+});
+
+// 场景10：orderBy 字符串标准格式（空格分隔）
+const result10 = await sharding.queryPage({
+  condition: { status: 'paid' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC, amount ASC'  // 标准 SQL 格式
+});
+
+// 场景11：配置了 recentTableCount 的分页（只在最近N张表中查询）
+// 配置：recentTableCount: 3，存在表：[202401, 202402, 202403, 202404, 202405]
+// 无时间条件时，只取最近3张：202403, 202404, 202405
+const result11 = await sharding.queryPage({
+  condition: { status: 'completed' },  // 无时间条件
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+// 行为：仅在 202403, 202404, 202405 三张表中分页，忽略更早的表
+// 如果这3张表总共只有25条数据，查询第3页(pageNo=3, offset=20)只能返回5条
+
+// 场景12：未配置 recentTableCount 的分页（默认最多3张表）
+// 配置：未设置 recentTableCount，存在表：[202401, 202402, 202403, 202404, 202405]
+// 无时间条件时，所有真实表取交集后最多取3张（按时间倒序取最新的3张）
+const result12 = await sharding.queryPage({
+  condition: { status: 'completed' },  // 无时间条件
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+// 行为：与场景11类似，默认也是取最近3张表（202403, 202404, 202405）
+// 区别在于：recentTableCount 显式配置时，会严格限制只查这N张表
+
+// 场景13：配置 recentTableCount 但时间条件超出范围
+// 配置：recentTableCount: 3，最近3张：[202403, 202404, 202405]
+// 查询条件指定了 202401 的时间范围
+const result13 = await sharding.queryPage({
+  condition: {
+    created_at: { $gte: '2024-01-01', $lte: '2024-01-31' },  // 202401月份
+    status: 'pending'
+  },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+// 行为：recentTableCount 限制与查询条件取交集
+// 最近3张 [202403, 202404, 202405] 与 202401 无交集
+// 结果：查询不到任何表，返回空结果
+
+// 场景14：未配置 recentTableCount 时时间条件与真实表取交集
+// 配置：未设置 recentTableCount，存在表：[202403, 202404, 202405]（假设202401已删除）
+// 查询条件指定了包含 202401-202405 的时间范围
+const result14 = await sharding.queryPage({
+  condition: {
+    created_at: { $gte: '2024-01-01', $lte: '2024-05-31' },  // 1-5月
+    status: 'pending'
+  },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+// 行为：查询条件推导出的表 [202401, 202402, 202403, 202404, 202405]
+// 与真实存在的表 [202403, 202404, 202405] 取交集
+// 最终查询：202403, 202404, 202405（共3张，未超过上限）
+```
+
+## 五、时间分表查询行为
+
+**核心原则：** 根据是否配置 `recentTableCount` 决定查询行为
+
+| 配置 | 行为 |
+|------|------|
+| 配置了 `recentTableCount` | 从真实存在的表中取最近N张，再与查询条件取交集 |
+| 未配置 `recentTableCount` | 所有真实存在的表与查询条件取交集，最多返回3张 |
+
+**核心差异总结：**
+
+- **配置了 `recentTableCount`**：先确定"最近N张表"，再与查询条件取交集。如果查询的时间范围不在最近N张内，可能查不到数据。
+
+- **未配置 `recentTableCount`**：查询条件推导出的表与"真实存在的表"取交集，最多返回3张（按时间倒序取最新的）。即使查询的是历史数据，只要表还存在就能查到。
+
+### 5.1 配置了 recentTableCount
+
+```typescript
+const sharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  recentTableCount: 3,  // 最近3张表
+});
+
+// 场景1：无时间条件，查询最近3张真实存在的表
+// 假设真实存在的表：t_order_202401 ~ t_order_202604（20几个表）
+// 实际查询：t_order_202602, t_order_202603, t_order_202604（按时间倒序）
+await sharding.query({ condition: { status: 'pending' } });
+
+// 场景2：有时间范围，与最近3张取交集
+// 假设真实存在的表：t_order_202401 ~ t_order_202604（20几个表）
+// 最近3张：t_order_202602, t_order_202603, t_order_202604
+// 查询范围：2024-01 ~ 2024-03（对应 t_order_202401, t_order_202402, t_order_202403）
+// 实际查询：返回空（无交集）
+await sharding.query({
+  condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } }
+});
+
+// 场景3：有时间范围，与最近3张有交集
+// 假设真实存在的表：t_order_202401 ~ t_order_202604（20几个表）
+// 最近3张：t_order_202602, t_order_202603, t_order_202604
+// 查询范围：2024-02 ~ 2024-06（对应 t_order_202402 ~ t_order_202406）
+// 实际查询：t_order_202602, t_order_202603, t_order_202604（交集）
+await sharding.query({
+  condition: { created_at: { $gte: '2024-02-01', $lte: '2024-06-30' } }
+});
+
+// 场景4：单一时间值，与最近3张取交集
+// 假设真实存在的表：t_order_202401 ~ t_order_202604（20几个表）
+// 最近3张：t_order_202602, t_order_202603, t_order_202604
+// 查询：2024-03-15（对应 t_order_202403）
+// 实际查询：返回空（不在最近3张中）
+await sharding.query({
+  condition: { created_at: '2024-03-15' }
+});
+```
+
+### 5.2 未配置 recentTableCount
+
+```typescript
+const sharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  // 未配置 recentTableCount
+});
+
+// 场景1：无时间条件，所有真实表最多取3张
+// 假设真实存在的表：t_order_202401 ~ t_order_202604（20几个表）
+// 实际查询：t_order_202602, t_order_202603, t_order_202604（最后3张）
+await sharding.query({ condition: { status: 'pending' } });
+
+// 场景2：有时间范围，所有真实表与条件取交集，最多3张
+// 假设真实存在的表：t_order_202401 ~ t_order_202604（20几个表）
+// 查询范围：2024-01 ~ 2024-06（对应 t_order_202401 ~ t_order_202406）
+// 实际查询：t_order_202404, t_order_202405, t_order_202406（交集后取3张）
+await sharding.query({
+  condition: { created_at: { $gte: '2024-01-01', $lte: '2024-06-30' } }
+});
+
+// 场景3：有时间范围，交集不足3张
+// 假设真实存在的表：t_order_202401, t_order_202402, t_order_202403, t_order_202604
+// 查询范围：2024-01 ~ 2024-03（对应 t_order_202401 ~ t_order_202403）
+// 实际查询：t_order_202403, t_order_202402, t_order_202401（交集后3张）
+await sharding.query({
+  condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } }
+});
+```
+
+## 六、表存在性检查
+
+### 6.1 查询时的表存在性过滤
+
+所有查询操作（`query`/`queryOne`/`queryPage`/`queryCount`/`isExist`）都会自动过滤掉不存在的表：
+
+```typescript
+// 假设数据库中只存在 t_order_202403, t_order_202404
+// 但路由计算返回了 t_order_202401 ~ t_order_202404
+
+const orders = await sharding.query({
+  condition: { created_at: { $gte: '2024-01-01', $lte: '2024-04-30' } }
+});
+
+// 实际只查询存在的表：t_order_202403, t_order_202404
+// 不存在的表会被自动过滤，不会报错
+```
+
+### 6.2 插入时的表存在性检查
+
+插入操作（`insert`/`batchInsert`）会先检查目标表是否存在：
+
+```typescript
+// 路由到 t_order_202405，但该表不存在
+try {
+  await sharding.insert({
+    data: { order_id: '001', created_at: '2024-05-15' }
+  });
+} catch (e) {
+  // 抛出异常：分表 t_order_202405 不存在，请先创建
+}
+```
+
+**注意：** 自动创建分表功能暂未实现，需要预先创建好分表。
+
+## 七、完整路由场景对照表
+
+### 7.1 时间分表（YEAR/MONTH/DAY）
+
+| 操作 | 字段来源 | 路由逻辑 | 表存在性处理 | 返回 |
+|-----|---------|---------|-------------|------|
+| `insert` | `data[timeColumn]` | 提取时间 → 计算后缀 | 检查存在性，不存在报错 | 单表 |
+| `batchInsert` | `data[i][timeColumn]` | 每条数据计算分表 | 检查存在性，不存在报错 | 多表（按表分组，支持跨分表） |
+| `update` | `condition[timeColumn]` | 提取时间 → 计算后缀 | 不检查，表不存在时数据库报错 | 单表 |
+| `delete` | `condition[timeColumn]` | 提取时间 → 计算后缀 | 不检查，表不存在时数据库报错 | 单表 |
+| `insertOrUpdate` | `condition[timeColumn]` | 提取时间 → 计算后缀 | 不检查 | 单表 |
+| `insertOnDuplicateUpdate` | `condition[timeColumn]` | 提取时间 → 计算后缀 | 不检查 | 单表 |
+| `query` | `condition[timeColumn]` | 与真实存在的表取交集 | 过滤不存在的表 | 多表 |
+| `queryOne` | `condition[timeColumn]` | 同 query | 过滤不存在的表 | 多表（顺序查） |
+| `queryPage` | `condition[timeColumn]` | 同 query | 过滤不存在的表 | 多表 |
+| `queryCount` | `condition[timeColumn]` | 同 query | 过滤不存在的表 | 多表（结果求和） |
+| `isExist` | `condition[timeColumn]` | 同 query | 过滤不存在的表 | 多表（任一为true） |
+
+### 7.2 范围分表（RANGE）
+
+| 操作 | 字段来源 | 路由逻辑 | 表存在性处理 | 返回 |
+|-----|---------|---------|-------------|------|
+| `insert` | `data[shardingColumn]` | value % tableCount | 检查存在性，不存在报错 | 单表 |
+| `batchInsert` | `data[i][shardingColumn]` | 每条数据计算分表 | 检查存在性，不存在报错 | 多表（按表分组，支持跨分表） |
+| `update` | `condition[shardingColumn]` | value % tableCount | 不检查，表不存在时数据库报错 | 单表 |
+| `delete` | `condition[shardingColumn]` | value % tableCount | 不检查，表不存在时数据库报错 | 单表 |
+| `insertOrUpdate` | `condition[shardingColumn]` | value % tableCount | 不检查 | 单表 |
+| `insertOnDuplicateUpdate` | `condition[shardingColumn]` | value % tableCount | 不检查 | 单表 |
+| `query` | `condition[shardingColumn]` | 有值→单表；无→所有分表 | 过滤不存在的表 | 单表/多表 |
+| `queryOne` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+| `queryPage` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+| `queryCount` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+| `isExist` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+
+### 7.3 哈希分表（HASH）
+
+| 操作 | 字段来源 | 路由逻辑 | 表存在性处理 | 返回 |
+|-----|---------|---------|-------------|------|
+| `insert` | `data[shardingColumn]` | hash(value) % tableCount | 检查存在性，不存在报错 | 单表 |
+| `batchInsert` | `data[i][shardingColumn]` | 每条数据计算分表 | 检查存在性，不存在报错 | 多表（按表分组，支持跨分表） |
+| `update` | `condition[shardingColumn]` | hash(value) % tableCount | 不检查，表不存在时数据库报错 | 单表 |
+| `delete` | `condition[shardingColumn]` | hash(value) % tableCount | 不检查，表不存在时数据库报错 | 单表 |
+| `insertOrUpdate` | `condition[shardingColumn]` | hash(value) % tableCount | 不检查 | 单表 |
+| `insertOnDuplicateUpdate` | `condition[shardingColumn]` | hash(value) % tableCount | 不检查 | 单表 |
+| `query` | `condition[shardingColumn]` | 有值→单表；无→所有分表 | 过滤不存在的表 | 单表/多表 |
+| `queryOne` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+| `queryPage` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+| `queryCount` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+| `isExist` | `condition[shardingColumn]` | 同 query | 过滤不存在的表 | 单表/多表 |
+
+### 7.4 自定义分表（CUSTOM）
+
+| 操作 | 字段来源 | 路由逻辑 | 表存在性处理 | 返回 |
+|-----|---------|---------|-------------|------|
+| `insert` | `data` | 调用 customRouter | 检查存在性，不存在报错 | 单表 |
+| `batchInsert` | `data[i]` | 每条数据调用 customRouter | 检查存在性，不存在报错 | 多表（按表分组，支持跨分表） |
+| `update` | `condition` | 调用 customRouter | 不检查，表不存在时数据库报错 | 单表 |
+| `delete` | `condition` | 调用 customRouter | 不检查，表不存在时数据库报错 | 单表 |
+| `insertOrUpdate` | `condition` | 调用 customRouter | 不检查 | 单表 |
+| `insertOnDuplicateUpdate` | `condition` | 调用 customRouter | 不检查 | 单表 |
+| `query` | `condition` | 调用 customRouter | 过滤不存在的表 | 单表/多表 |
+| `queryOne` | `condition` | 调用 customRouter | 过滤不存在的表 | 单表/多表 |
+| `queryPage` | `condition` | 调用 customRouter | 过滤不存在的表 | 单表/多表 |
+| `queryCount` | `condition` | 调用 customRouter | 过滤不存在的表 | 单表/多表 |
+| `isExist` | `condition` | 调用 customRouter | 过滤不存在的表 | 单表/多表 |
+
+## 八、错误处理与边界情况
+
+### 8.1 路由失败的情况
+
+| 场景 | 错误信息 | 说明 |
+|-----|---------|------|
+| insert 缺少分表字段 | `insert 操作无法从 data 中获取分表字段 xxx 的值` | data 中必须包含 timeColumn/shardingColumn |
+| update 缺少分表字段 | `查询/更新/删除操作无法从 condition 中获取分表字段 xxx 的值` | condition 中必须包含分表字段 |
+| 插入到不存在的表 | `分表 xxx 不存在，请先创建` | 需要预先创建分表 |
+| CUSTOM 缺少 router | `CUSTOM 分表必须提供 customRouter 函数` | 配置中必须提供 customRouter |
+
+### 8.2 边界情况处理
+
+```typescript
+// 情况1：查询时所有候选表都不存在
+const orders = await sharding.query({
+  condition: { created_at: { $gte: '2020-01-01', $lte: '2020-12-31' } }  // 这些表都不存在
+});
+// 返回空数组 []，不会报错
+
+// 情况2：没有真实存在的表
+const sharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_new_table',  // 没有任何分表
+});
+const orders = await sharding.query({ condition: {} });
+// 返回空数组 []，不会报错
+
+// 情况3：时间范围超大（超过100个分表）
+const orders = await sharding.query({
+  condition: { created_at: { $gte: '2020-01-01', $lte: '2025-12-31' } }  // 超过100个月
+});
+// 最多返回100个分表，避免性能问题
+```
+
+## 九、性能优化
+
+### 9.1 COUNT 查询缓存（时间分表专用）
+
+分页查询时需要先统计各分表的记录数，对于历史数据表（非当前月/日/年），COUNT 值相对稳定，可以启用缓存减少数据库查询。
+
+**核心设计原则：**
+- **历史表启用缓存**：非当前时间周期的表 COUNT 结果会被缓存
+- **当前表实时查询**：当前月/日/年的表始终实时查询，确保数据准确性
+- **LRU 淘汰机制**：缓存满时自动淘汰最久未使用的条目
+- **TTL 过期机制**：缓存有有效期，过期后自动重新查询
+
+**使用示例：**
+
+```typescript
+const sharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  timeColumn: 'created_at',
+  countCache: {
+    ttlSeconds: 300,   // 缓存5分钟
+    maxSize: 1000,     // 最多缓存1000个表的COUNT
+  },
+});
+
+// 第一次查询 202401、202402、202403 的 COUNT，会写入缓存
+const result1 = await sharding.queryPage({
+  condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+
+// 第二次查询相同范围，202401/202402/202403 的 COUNT 从缓存读取
+// 202404（当前月）如果有数据，仍然实时查询
+const result2 = await sharding.queryPage({
+  condition: { created_at: { $gte: '2024-01-01', $lte: '2024-04-30' } },
+  pageNo: 2,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+```
+
+**缓存命中率分析：**
+
+| 场景 | 缓存效果 |
+|------|---------|
+| 历史数据分页导航（第1页→第10页）| 高，COUNT 相同直接复用 |
+| 不同时间范围查询 | 中，重叠部分复用 |
+| 实时数据查询（当前月）| 无缓存，确保实时性 |
+| 带复杂条件的查询 | 不同条件独立缓存 |
+
+**注意事项：**
+- 仅对 `YEAR`/`MONTH`/`DAY` 时间分表类型有效
+- 缓存键包含表名+条件哈希，不同条件独立缓存
+- 可通过 `sharding['merger']['countCache']?.clear()` 手动清空缓存
+
+### 9.2 缓存实现原理
+
+#### 如何判断"当前表"
+
+缓存系统根据分表类型和当前时间自动识别"当前表"：
+
+| 分表类型 | 当前表示例（假设今天2024-04-10）| 缓存策略 |
+|---------|------------------------------|---------|
+| YEAR | t_order_2024 | 不缓存 |
+| MONTH | t_order_202404 | 不缓存 |
+| DAY | t_order_20240410 | 不缓存 |
+| 历史表 | t_order_202403, t_order_202402... | 启用缓存 |
+
+**判断逻辑：**
+```typescript
+// 根据分表类型计算当前后缀
+const now = new Date();
+
+// YEAR: "2024"
+// MONTH: "202404"
+// DAY: "20240410"
+const currentSuffix = getCurrentSuffix(now);
+const expectedTable = `${baseTable}_${currentSuffix}`;
+
+// 如果是当前表，实时查询；否则使用缓存
+const isCurrent = (tableName === expectedTable);
+```
+
+#### 缓存键设计
+
+缓存键由两部分组成，确保不同表、不同条件独立存储：
+
+```
+缓存键 = 表名 + "#" + 条件哈希
+
+示例：
+- t_order_202401#*                         // 无条件查询
+- t_order_202401#a1b2c3d4                 // condition: { status: 'completed' }
+- t_order_202401#x9y8z7w6                 // condition: { status: 'pending', type: 'order' }
+```
+
+**条件哈希算法：**
+1. 对 condition 对象按键排序后 JSON 序列化
+2. 使用 djb2 哈希算法生成 32 位整数
+3. 转为 36 进制字符串压缩存储
+
+```typescript
+function shardingHashCondition(condition: object): string {
+  const sorted = sortKeys(condition);
+  const str = JSON.stringify(sorted);
+  
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash) + str.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(36);
+}
+```
+
+#### LRU 淘汰机制
+
+当缓存条目数达到上限（默认1000）时，自动淘汰最久未使用的条目：
+
+```typescript
+// Map 保持插入顺序，第一个元素就是最久未使用的
+const firstKey = this.cache.keys().next().value;
+this.cache.delete(firstKey);
+```
+
+**访问更新策略：**
+- 缓存命中时：删除旧条目，重新插入（移到末尾）
+- 缓存未命中时：直接插入新条目
+- 淘汰时：删除 Map 头部（最久未使用）
+
+#### TTL 过期机制
+
+每个缓存条目记录缓存时间，查询时检查是否过期：
+
+```typescript
+interface CacheEntry {
+  count: number;        // 缓存的 COUNT 值
+  cachedAt: number;     // 缓存时间戳（毫秒）
+  key: string;          // 缓存键
+}
+
+// 查询时检查
+const entry = cache.get(key);
+if (Date.now() - entry.cachedAt > ttlMs) {
+  cache.delete(key);   // 过期删除
+  return undefined;    // 返回未命中
+}
+```
+
+### 9.3 缓存效果对比
+
+**场景：查询2024年1-3月数据，分页导航第1-5页**
+
+| 步骤 | 无缓存 | 有缓存（5分钟TTL）| 说明 |
+|------|-------|------------------|------|
+| 第1页 | 查3张表 COUNT | 查3张表 COUNT | 首次查询，无缓存 |
+| 第2页 | 查3张表 COUNT | 从缓存读取 | 历史表 COUNT 未变 |
+| 第3页 | 查3张表 COUNT | 从缓存读取 | 历史表 COUNT 未变 |
+| 第4页 | 查3张表 COUNT | 从缓存读取 | 历史表 COUNT 未变 |
+| 第5页 | 查3张表 COUNT | 从缓存读取 | 历史表 COUNT 未变 |
+| **总计** | **15次 COUNT 查询** | **3次 COUNT 查询** | **节省80%查询** |
+
+### 9.4 高级配置示例
+
+```typescript
+// 高频读场景：长缓存时间 + 大容量
+const readHeavySharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  timeColumn: 'created_at',
+  countCache: {
+    ttlSeconds: 1800,   // 30分钟，历史数据很少变化
+    maxSize: 5000,      // 缓存5000个表的COUNT
+  },
+});
+
+// 实时性要求高：短缓存时间 + 小容量
+const nearRealTimeSharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  timeColumn: 'created_at',
+  countCache: {
+    ttlSeconds: 60,     // 1分钟，快速刷新
+    maxSize: 100,       // 只缓存最近查询的表
+  },
+});
+
+// 不启用缓存（实时性最高）
+const noCacheSharding = new ShardingCrudPro(crudPro, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  timeColumn: 'created_at',
+  // 不配置 countCache
+});
+```
+
+## 十、公共工具函数
+
+分表模块提供以下工具函数，可用于自定义逻辑：
+
+```typescript
+import {
+  getTimeSuffix,        // 获取日期的时间后缀
+  getCurrentSuffix,     // 获取当前时间后缀
+  isCurrentTable,       // 判断是否为当前表
+  shardingTypeToGranularity,  // 分表类型转时间粒度
+} from '@/libs/crud-sharding';
+
+// 获取任意日期的时间后缀
+const suffix1 = getTimeSuffix(new Date('2024-03-15'), 'month');  // "202403"
+const suffix2 = getTimeSuffix(new Date('2024-03-15'), 'day');    // "20240315"
+
+// 获取当前时间后缀（根据分表类型）
+const currentSuffix = getCurrentSuffix(ShardingType.MONTH);  // 如 "202404"
+
+// 判断表名是否为当前表
+const isCurrent = isCurrentTable('t_order_202404', 't_order', ShardingType.MONTH);
+```
+
+**函数签名：**
+
+| 函数 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `getTimeSuffix(date, granularity)` | `Date`, `'year'\|'month'\|'day'` | `string` | 获取日期对应的时间后缀 |
+| `getCurrentSuffix(shardingType)` | `ShardingType` | `string` | 获取当前时间周期的后缀 |
+| `isCurrentTable(table, baseTable, type)` | `string`, `string`, `ShardingType` | `boolean` | 判断是否为当前表 |
+| `shardingTypeToGranularity(type)` | `ShardingType` | `ShardingTimeGranularity\|undefined` | 分表类型转时间粒度 |