midway-fatcms 0.0.7 → 0.0.9

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

@@ -36,3 +36,51 @@ export declare function getCurrentSuffix(shardingType: ShardingType | undefined)
  * @returns 是否为当前表
  */
 export declare function isCurrentTable(tableName: string, baseTable: string, shardingType: ShardingType | undefined): boolean;
+/**
+ * 日期字符串的粒度类型
+ */
+export declare type DateStringGranularity = 'year' | 'month' | 'day' | 'datetime' | null;
+/**
+ * 判断日期字符串的粒度
+ *
+ * 根据字符串格式推断精度：
+ * - 4位纯年：'2024' → 'year'
+ * - 7位年-月：'2024-01' → 'month'
+ * - 10位年-月-日：'2024-01-15' → 'day'
+ * - 带时分秒：'2024-01-15 10:30:00' → 'datetime'（精度已足够，不需要转换）
+ *
+ * @param value 待判断的值
+ * @returns 粒度类型，非日期字符串返回 null
+ */
+export declare function detectDateStringGranularity(value: string): DateStringGranularity;
+/**
+ * 判断值是否为时间操作符表达式（ICompareCondition / ILogicalCondition）
+ *
+ * 排除 Date 对象后，typeof === 'object' 且非 null 即为操作符表达式。
+ * 判断优先级：`value instanceof Date` → 先于 `typeof === 'object'` 判断。
+ *
+ * @param value 待判断的值
+ * @returns 是否为操作符表达式
+ */
+export declare function isOperatorExpression(value: unknown): boolean;
+/**
+ * 将日期字符串按粒度转换为 $gte/$lte 范围表达式
+ *
+ * 仅对 year/month/day 粒度的字符串进行转换，
+ * datetime 粒度和非日期字符串不转换返回 null。
+ * 闰年2月自动处理（28/29天）。
+ *
+ * @param value 日期字符串
+ * @returns 范围表达式对象，不需要转换时返回 null
+ *
+ * @example
+ * expandDateToRange('2024')
+ * // → { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' }
+ *
+ * expandDateToRange('2024-01')
+ * // → { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' }
+ *
+ * expandDateToRange('2024-01-15')
+ * // → { $gte: '2024-01-15 00:00:00', $lte: '2024-01-15 23:59:59' }
+ */
+export declare function expandDateToRange(value: string): Record<string, string> | null;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isCurrentTable = exports.getCurrentSuffix = exports.getTimeSuffix = exports.shardingTypeToGranularity = void 0;
+exports.expandDateToRange = exports.isOperatorExpression = exports.detectDateStringGranularity = exports.isCurrentTable = exports.getCurrentSuffix = exports.getTimeSuffix = exports.shardingTypeToGranularity = void 0;
 const ShardingConfig_1 = require("./ShardingConfig");
 /**
  * 将 ShardingType 转换为时间粒度
@@ -75,3 +75,124 @@ function isCurrentTable(tableName, baseTable, shardingType) {
     return tableName === expectedTableName;
 }
 exports.isCurrentTable = isCurrentTable;
+/**
+ * 判断日期字符串的粒度
+ *
+ * 根据字符串格式推断精度：
+ * - 4位纯年：'2024' → 'year'
+ * - 7位年-月：'2024-01' → 'month'
+ * - 10位年-月-日：'2024-01-15' → 'day'
+ * - 带时分秒：'2024-01-15 10:30:00' → 'datetime'（精度已足够，不需要转换）
+ *
+ * @param value 待判断的值
+ * @returns 粒度类型，非日期字符串返回 null
+ */
+function detectDateStringGranularity(value) {
+    const trimmed = value.trim();
+    // 4位纯年：'2024'
+    if (/^\d{4}$/.test(trimmed)) {
+        return 'year';
+    }
+    // 7位年-月：'2024-01'
+    if (/^\d{4}-\d{2}$/.test(trimmed)) {
+        return 'month';
+    }
+    // 10位年-月-日：'2024-01-15'
+    if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+        return 'day';
+    }
+    // 带时分秒的完整时间字符串（精度已足够，不需要转换）
+    if (/^\d{4}-\d{2}-\d{2}[T ]\d{1,2}/.test(trimmed)) {
+        return 'datetime';
+    }
+    return null;
+}
+exports.detectDateStringGranularity = detectDateStringGranularity;
+/**
+ * 判断值是否为时间操作符表达式（ICompareCondition / ILogicalCondition）
+ *
+ * 排除 Date 对象后，typeof === 'object' 且非 null 即为操作符表达式。
+ * 判断优先级：`value instanceof Date` → 先于 `typeof === 'object'` 判断。
+ *
+ * @param value 待判断的值
+ * @returns 是否为操作符表达式
+ */
+function isOperatorExpression(value) {
+    // Date 对象是精确值，不是操作符
+    if (value instanceof Date) {
+        return false;
+    }
+    // 非-null 对象视为操作符表达式（如 { $gte: ... }, { $or: ... }）
+    return typeof value === 'object' && value !== null && Object.keys(value).length > 0;
+}
+exports.isOperatorExpression = isOperatorExpression;
+/**
+ * 获取指定年月的最后一天日期
+ *
+ * @param year 年份
+ * @param month 月份（1-12）
+ * @returns 最后一天的日号（28/29/30/31）
+ */
+function getLastDayOfMonth(year, month) {
+    // new Date(year, month, 0) 返回上个月最后一天
+    return new Date(year, month, 0).getDate();
+}
+/**
+ * 将日期字符串按粒度转换为 $gte/$lte 范围表达式
+ *
+ * 仅对 year/month/day 粒度的字符串进行转换，
+ * datetime 粒度和非日期字符串不转换返回 null。
+ * 闰年2月自动处理（28/29天）。
+ *
+ * @param value 日期字符串
+ * @returns 范围表达式对象，不需要转换时返回 null
+ *
+ * @example
+ * expandDateToRange('2024')
+ * // → { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' }
+ *
+ * expandDateToRange('2024-01')
+ * // → { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' }
+ *
+ * expandDateToRange('2024-01-15')
+ * // → { $gte: '2024-01-15 00:00:00', $lte: '2024-01-15 23:59:59' }
+ */
+function expandDateToRange(value) {
+    const granularity = detectDateStringGranularity(value);
+    if (!granularity || granularity === 'datetime') {
+        return null;
+    }
+    const trimmed = value.trim();
+    switch (granularity) {
+        case 'year': {
+            // '2024' → 2024-01-01 ~ 2024-12-31
+            const year = parseInt(trimmed, 10);
+            return {
+                $gte: `${year}-01-01 00:00:00`,
+                $lte: `${year}-12-31 23:59:59`,
+            };
+        }
+        case 'month': {
+            // '2024-01' → 2024-01-01 ~ 2024-01-31
+            const [yearStr, monthStr] = trimmed.split('-');
+            const year = parseInt(yearStr, 10);
+            const month = parseInt(monthStr, 10);
+            const lastDay = getLastDayOfMonth(year, month);
+            const monthPadded = monthStr.padStart(2, '0');
+            return {
+                $gte: `${year}-${monthPadded}-01 00:00:00`,
+                $lte: `${year}-${monthPadded}-${String(lastDay).padStart(2, '0')} 23:59:59`,
+            };
+        }
+        case 'day': {
+            // '2024-01-15' → 2024-01-15 00:00:00 ~ 2024-01-15 23:59:59
+            return {
+                $gte: `${trimmed} 00:00:00`,
+                $lte: `${trimmed} 23:59:59`,
+            };
+        }
+        default:
+            return null;
+    }
+}
+exports.expandDateToRange = expandDateToRange;

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

@@ -0,0 +1,488 @@
+# 时间字段清理与转换场景说明
+
+## 背景
+
+时间分表（YEAR/MONTH/DAY）中，`timeColumn` 既是路由键也是查询条件。
+用户传入的时间值可能精度不一致（如传 `'2024-01-15'` 但数据库存的是 `1705276800000` 毫秒时间戳），
+直接作为 WHERE 条件会导致匹配失败。
+
+## 校验与清理的职责分离
+
+时间分表的 condition 处理分为两个独立阶段，由不同函数负责：
+
+### 阶段1：校验（validateRoutingFieldForCondition）
+
+**职责**：确保写操作的 condition 包含时间字段，用于路由定位分表。
+
+**适用操作**：update / delete / restore / insertOrUpdate
+
+**校验规则**：
+- condition 中必须存在 timeColumn 字段（值不能为 falsy）
+- 不存在则抛出错误，给出明确提示
+- 查询操作（find*）不校验，允许回退到 recentTableCount
+
+```typescript
+// 校验通过：timeColumn 存在
+{ order_id: 'ORD001', created_at: '2024-01-15' }  // ✅
+{ order_id: 'ORD001', created_at: { $gte: '2024-01' } }  // ✅
+
+// 校验失败：timeColumn 不存在
+{ order_id: 'ORD001' }  // ❌ 抛出错误
+```
+
+### 阶段2：清理/转换（cleanTimeColumnForSingleTableQuery）
+
+**职责**：在校验通过后，根据值类型和主键情况，智能处理 timeColumn。
+
+**适用操作**：所有操作（读 + 写），在校验之后执行。
+
+**处理规则**：按下方「核心规则」和「判断流程图」执行。
+
+### 执行顺序
+
+```
+写操作请求
+  │
+  ├─ 1. validateRoutingFieldForCondition（校验 timeColumn 存在）
+  │     └─ 不存在 → 抛出错误，终止
+  │
+  └─ 2. cleanTimeColumnForSingleTableQuery（智能处理 timeColumn）
+        ├─ 有主键 + 精确值 → 清理
+        ├─ 无主键 + 日期粒度字符串 → 转换为范围
+        └─ 其他 → 保留原值
+
+读操作请求
+  │
+  └─ 1. cleanTimeColumnForSingleTableQuery（智能处理 timeColumn）
+        （读操作不校验，允许无 timeColumn）
+```
+
+## 核心规则
+
+### 规则1：精确时间 + 有主键 → 清理
+
+主键已唯一确定行，timeColumn 仅用于路由，从 WHERE 中移除。
+
+```typescript
+// 配置：{ primaryKey: 'order_id', timeColumn: 'created_at', type: MONTH }
+
+// 清理前
+{ order_id: 'ORD001', created_at: '2024-01-15' }
+// SQL: WHERE order_id = 'ORD001' AND created_at = '2024-01-15'  ← 精度可能不匹配
+
+// 清理后
+{ order_id: 'ORD001' }
+// SQL: WHERE order_id = 'ORD001'  ✅
+```
+
+### 规则2：精确时间 + 有主键 + 时间是操作符 → 保留
+
+用户明确要按时间操作符查询，不做任何处理。
+
+```typescript
+// $gte/$lte 范围 → 保留
+{ order_id: 'ORD001', created_at: { $gte: '2024-01-01', $lte: '2024-06-30' } }
+// SQL: WHERE order_id = 'ORD001' AND created_at >= '2024-01-01' AND created_at <= '2024-06-30'  ✅
+
+// $range → 保留
+{ order_id: 'ORD001', created_at: { $range: ['2024-01-01', '2024-06-30'] } }
+// SQL: WHERE order_id = 'ORD001' AND created_at BETWEEN '2024-01-01' AND '2024-06-30'  ✅
+
+// $in → 保留
+{ order_id: 'ORD001', created_at: { $in: ['2024-01-15', '2024-02-20'] } }
+// SQL: WHERE order_id = 'ORD001' AND created_at IN ('2024-01-15', '2024-02-20')  ✅
+
+// $null → 保留
+{ order_id: 'ORD001', created_at: { $null: true } }
+// SQL: WHERE order_id = 'ORD001' AND created_at IS NULL  ✅
+
+// $notNull → 保留
+{ order_id: 'ORD001', created_at: { $notNull: true } }
+// SQL: WHERE order_id = 'ORD001' AND created_at IS NOT NULL  ✅
+
+// $ne → 保留
+{ order_id: 'ORD001', created_at: { $ne: '2024-01-15' } }
+// SQL: WHERE order_id = 'ORD001' AND created_at != '2024-01-15'  ✅
+```
+
+### 规则3：精确时间 + 无主键 → 转换为范围查询
+
+无主键时，timeColumn 必须参与 WHERE。但精确值可能精度不匹配，
+需要将日期字符串转换为对应粒度的 `$gte`/`$lte` 范围。
+
+#### 3a. 年粒度字符串 → 年范围
+
+```typescript
+// 配置：{ timeColumn: 'created_at', type: MONTH }
+
+// 转换前
+{ status: 'paid', created_at: '2024' }
+
+// 转换后
+{ status: 'paid', created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' } }
+// SQL: WHERE status = 'paid' AND created_at >= '2024-01-01 00:00:00' AND created_at <= '2024-12-31 23:59:59'  ✅
+
+// 路由：根据范围定位 t_order_202401 ~ t_order_202412
+```
+
+#### 3b. 月粒度字符串 → 月范围
+
+```typescript
+// 配置：{ timeColumn: 'created_at', type: MONTH }
+
+// 转换前
+{ status: 'paid', created_at: '2024-01' }
+
+// 转换后
+{ status: 'paid', created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
+// SQL: WHERE status = 'paid' AND created_at >= '2024-01-01 00:00:00' AND created_at <= '2024-01-31 23:59:59'  ✅
+
+// 路由：定位 t_order_202401
+```
+
+#### 3c. 日粒度字符串 → 日范围
+
+```typescript
+// 配置：{ timeColumn: 'created_at', type: MONTH }
+
+// 转换前
+{ status: 'paid', created_at: '2024-01-15' }
+
+// 转换后
+{ status: 'paid', created_at: { $gte: '2024-01-15 00:00:00', $lte: '2024-01-15 23:59:59' } }
+// SQL: WHERE status = 'paid' AND created_at >= '2024-01-15 00:00:00' AND created_at <= '2024-01-15 23:59:59'  ✅
+
+// 路由：定位 t_order_202401
+```
+
+#### 3d. 带时分秒的字符串 → 不转换
+
+```typescript
+// 精确到秒的时间字符串，精度已足够，不转换
+{ status: 'paid', created_at: '2024-01-15 10:30:00' }
+// 不转换，直接用于 WHERE
+// SQL: WHERE status = 'paid' AND created_at = '2024-01-15 10:30:00'  ✅
+
+// 带毫秒的时间戳数字，精度已足够，不转换
+{ status: 'paid', created_at: 1705305000000 }
+// 不转换，直接用于 WHERE
+// SQL: WHERE status = 'paid' AND created_at = 1705305000000  ✅
+```
+
+### 规则4：精确时间 + 无主键 + 时间是不可转换的精确值 → 不转换
+
+数值型时间戳（非日期字符串）无法判断粒度，不做转换。
+
+```typescript
+// 数值型时间戳：无法推断粒度，保留原值
+{ status: 'paid', created_at: 1705276800000 }
+// 不转换，直接 WHERE
+// SQL: WHERE status = 'paid' AND created_at = 1705276800000
+
+// 但如果有主键，则清理
+{ order_id: 'ORD001', created_at: 1705276800000 }
+// → 清理为 { order_id: 'ORD001' }
+```
+
+### 规则5：操作符时间 → 始终保留
+
+无论有没有主键，操作符表达式一律保留在 WHERE 中。
+
+```typescript
+// 无主键 + 操作符
+{ status: 'paid', created_at: { $gte: '2024-01-01', $lte: '2024-06-30' } }
+// 保留，不做任何处理  ✅
+
+// 无主键 + $range
+{ status: 'paid', created_at: { $range: ['2024-01-01', '2024-06-30'] } }
+// 保留  ✅
+
+// 无主键 + $null
+{ status: 'paid', created_at: { $null: true } }
+// 保留  ✅
+```
+
+## 转换逻辑总结
+
+### 判断日期字符串粒度
+
+```
+'2024'            → 4位纯年     → 年范围
+'2024-01'         → 7位年-月    → 月范围
+'2024-01-15'      → 10位年-月-日 → 日范围
+'2024-01-15 10'   → 带时        → 日范围（补齐到秒）
+'2024-01-15 10:30'→ 带时分      → 日范围（补齐到秒）
+'2024-01-15 10:30:00' → 精确到秒 → 不转换
+1705276800000     → number      → 不转换（无法推断粒度）
+new Date(...)     → Date对象   → 不转换（精确到毫秒，视为精确值）
+```
+
+### 转换规则表
+
+| 条件 | timeColumn 值类型 | 有主键? | 操作 |
+|------|-------------------|---------|------|
+| 1 | string 精确值（年/月/日粒度） | ✅ | 清理（从 WHERE 移除） |
+| 2 | string 精确值（年/月/日粒度） | ❌ | 转换为 $gte/$lte 范围 |
+| 3 | string 精确值（精确到秒） | ✅ | 清理 |
+| 4 | string 精确值（精确到秒） | ❌ | 不转换，保留原值 |
+| 5 | number 精确值 | ✅ | 清理 |
+| 6 | number 精确值 | ❌ | 不转换，保留原值 |
+| 7 | Date 对象 | ✅ | 清理（精确到毫秒，视为精确值） |
+| 8 | Date 对象 | ❌ | 不转换，保留原值（精度已足够） |
+| 9 | ICompareCondition（$gte等） | 任意 | 保留，不做处理 |
+| 10 | ICompareCondition（$null等） | 任意 | 保留，不做处理 |
+
+## 各分表类型的转换示例
+
+### YEAR 分表
+
+```typescript
+// 配置：{ type: YEAR, timeColumn: 'created_at' }
+
+// '2024' → 年范围
+{ created_at: '2024' }
+→ { created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' } }
+// 路由：t_log_2024
+
+// '2024-06' → 月范围
+{ created_at: '2024-06' }
+→ { created_at: { $gte: '2024-06-01 00:00:00', $lte: '2024-06-30 23:59:59' } }
+// 路由：t_log_2024
+
+// '2024-06-15' → 日范围
+{ created_at: '2024-06-15' }
+→ { created_at: { $gte: '2024-06-15 00:00:00', $lte: '2024-06-15 23:59:59' } }
+// 路由：t_log_2024
+```
+
+### MONTH 分表
+
+```typescript
+// 配置：{ type: MONTH, timeColumn: 'created_at' }
+
+// '2024' → 年范围（跨12张表）
+{ created_at: '2024' }
+→ { created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' } }
+// 路由：t_order_202401 ~ t_order_202412
+
+// '2024-01' → 月范围
+{ created_at: '2024-01' }
+→ { created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
+// 路由：t_order_202401
+
+// '2024-01-15' → 日范围
+{ created_at: '2024-01-15' }
+→ { created_at: { $gte: '2024-01-15 00:00:00', $lte: '2024-01-15 23:59:59' } }
+// 路由：t_order_202401
+```
+
+### DAY 分表
+
+```typescript
+// 配置：{ type: DAY, timeColumn: 'access_time' }
+
+// '2024' → 年范围（跨365张表）
+{ access_time: '2024' }
+→ { access_time: { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' } }
+// 路由：t_access_20240101 ~ t_access_20241231
+
+// '2024-01' → 月范围（跨31张表）
+{ access_time: '2024-01' }
+→ { access_time: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
+// 路由：t_access_20240101 ~ t_access_20240131
+
+// '2024-01-15' → 日范围
+{ access_time: '2024-01-15' }
+→ { access_time: { $gte: '2024-01-15 00:00:00', $lte: '2024-01-15 23:59:59' } }
+// 路由：t_access_20240115
+```
+
+## 特殊边界场景
+
+### 闰年2月
+
+```typescript
+// 2024 是闰年
+{ created_at: '2024-02' }
+→ { created_at: { $gte: '2024-02-01 00:00:00', $lte: '2024-02-29 23:59:59' } }
+// ✅ 2月有29天
+
+// 2023 不是闰年
+{ created_at: '2023-02' }
+→ { created_at: { $gte: '2023-02-01 00:00:00', $lte: '2023-02-28 23:59:59' } }
+// ✅ 2月有28天
+```
+
+### 主键 + 日期粒度字符串 → 清理即可
+
+```typescript
+// 有主键时，日期粒度字符串也直接清理，不需要转换
+// 因为主键已唯一确定行，timeColumn 仅用于路由
+
+{ order_id: 'ORD001', created_at: '2024' }
+→ { order_id: 'ORD001' }  // 清理，不需要转换为范围
+
+{ order_id: 'ORD001', created_at: '2024-01' }
+→ { order_id: 'ORD001' }  // 清理
+
+{ order_id: 'ORD001', created_at: '2024-01-15' }
+→ { order_id: 'ORD001' }  // 清理
+```
+
+### 组合条件
+
+```typescript
+// 多个普通条件 + 日期粒度字符串
+{ status: 'paid', region: 'CN', created_at: '2024-01' }
+→ { status: 'paid', region: 'CN', created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
+// SQL: WHERE status = 'paid' AND region = 'CN' AND created_at >= '2024-01-01 00:00:00' AND created_at <= '2024-01-31 23:59:59'  ✅
+
+// 主键 + 其他条件 + 日期粒度字符串 → 只清理 timeColumn
+{ order_id: 'ORD001', status: 'paid', created_at: '2024-01-15' }
+→ { order_id: 'ORD001', status: 'paid' }
+// SQL: WHERE order_id = 'ORD001' AND status = 'paid'  ✅
+```
+
+### Date 对象
+
+JavaScript 的 `Date` 对象 `typeof` 是 `'object'`，但不是 `ICompareCondition`，需要优先识别。
+
+判断优先级：`value instanceof Date` → 先于 `typeof === 'object'` 判断。
+
+```typescript
+// Date 对象精确到毫秒，不存在粒度转换问题
+
+// 有主键 → 清理
+{ order_id: 'ORD001', created_at: new Date('2024-01-15T10:30:00') }
+→ { order_id: 'ORD001' }  // 清理
+
+// 无主键 → 保留原值（精度已足够，不需要转换）
+{ status: 'paid', created_at: new Date('2024-01-15T10:30:00') }
+// 不转换，保留原值
+// SQL: WHERE status = 'paid' AND created_at = '2024-01-15 10:30:00.000'  ✅
+```
+
+> **注意**：通过 HTTP API 传参时，Date 对象会被 JSON 序列化为字符串，
+> 只有在代码中直接调用（如测试代码、定时任务）时才会传入 Date 对象。
+
+### timeColumn 本身是唯一条件
+
+```typescript
+// 只有日期粒度字符串 → 转换
+{ created_at: '2024-01' }
+→ { created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
+// ✅ 既能路由到正确分表，又能精确 WHERE
+
+// 只有精确到秒 → 不转换
+{ created_at: '2024-01-15 10:30:00' }
+// 不转换，保留原值
+```
+
+## 非法/边界值处理
+
+### null 值
+
+`typeof null === 'object'`，但 null 不是操作符表达式，也不是合法的时间值。
+
+```typescript
+// 误用：想查 NULL 应该用 { $null: true }
+{ status: 'paid', created_at: null }
+// → 不清理、不转换，保留原值
+// SQL: WHERE status = 'paid' AND created_at = NULL  ← 通常匹配不到数据
+
+// 正确写法
+{ status: 'paid', created_at: { $null: true } }
+// → 操作符表达式，保留
+// SQL: WHERE status = 'paid' AND created_at IS NULL  ✅
+```
+
+判断逻辑：`isOperatorExpression` 通过 `value !== null` 排除 null，null 被视为非操作符。
+后续由于 null 不是 string/number/boolean/Date，不会命中任何清理或转换规则，保留原值。
+
+### 空字符串
+
+不匹配任何日期格式，不转换也不清理。
+
+```typescript
+{ status: 'paid', created_at: '' }
+// → 不清理、不转换，保留原值
+// SQL: WHERE status = 'paid' AND created_at = ''  ← 匹配不到数据，但不会报错
+```
+
+### 数组值
+
+`typeof [] === 'object'`，会被误判为操作符表达式而保留，但这不是合法的 condition 值。
+
+```typescript
+// 非法值，不应使用
+{ status: 'paid', created_at: ['2024-01', '2024-02'] }
+// → 被当作操作符表达式保留，但 SQL 生成可能出错
+
+// 正确写法：用 $in
+{ status: 'paid', created_at: { $in: ['2024-01-01', '2024-02-01'] } }
+```
+
+### primaryKey 值为操作符
+
+当 primaryKey 的值是操作符表达式（如 `$in`）时，仍触发 timeColumn 清理。
+因为 primaryKey 的作用是判断"是否有字段能辅助定位行"，而非"是否能唯一确定一行"。
+
+```typescript
+// primaryKey 使用 $in
+{ order_id: { $in: ['ORD001', 'ORD002'] }, created_at: '2024-01-15' }
+→ { order_id: { $in: ['ORD001', 'ORD002'] } }  // 清理 created_at
+// SQL: WHERE order_id IN ('ORD001', 'ORD002')  ✅
+// created_at 已通过路由定位到 t_order_202401，不需要在 WHERE 中
+```
+
+## 写操作安全性
+
+无主键写操作（update/delete）中，日期粒度字符串被转换为范围后，
+可能影响大量数据，需调用方自行保证条件精确性。
+
+```typescript
+// ⚠️ 无主键删除 + 日期粒度字符串 → 转换为范围，可能删除大量数据
+await sharding.delete({
+  condition: { created_at: '2024-01' }
+});
+// 转换后: { created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
+// SQL: DELETE FROM t_order_202401 WHERE created_at >= '2024-01-01 00:00:00' AND created_at <= '2024-01-31 23:59:59'
+// ⚠️ 会删除整个1月份的所有数据！
+
+// ✅ 推荐：写操作尽量使用主键
+await sharding.delete({
+  condition: { order_id: 'ORD001', created_at: '2024-01-15' }
+});
+// 清理后: { order_id: 'ORD001' }
+// SQL: DELETE FROM t_order_202401 WHERE order_id = 'ORD001'  ✅ 精确删除
+```
+
+## 判断流程图
+
+```
+timeColumn 值在 condition 中
+│
+├─ 值为 undefined → 不处理
+│
+├─ 值 instanceof Date → 精确值（毫秒精度）
+│   ├─ 有 primaryKey → 清理
+│   └─ 无 primaryKey → 保留原值
+│
+├─ typeof === 'object' 且不为 null 且不为 Date → 操作符表达式 → 保留
+│
+├─ typeof === 'number' → 精确值（时间戳）
+│   ├─ 有 primaryKey → 清理
+│   └─ 无 primaryKey → 保留原值（无法推断粒度）
+│
+├─ typeof === 'boolean' → 精确值
+│   ├─ 有 primaryKey → 清理
+│   └─ 无 primaryKey → 保留原值
+│
+└─ typeof === 'string' → 检测日期粒度
+    ├─ 年/月/日粒度（'2024', '2024-01', '2024-01-15'）
+    │   ├─ 有 primaryKey → 清理
+    │   └─ 无 primaryKey → 转换为 $gte/$lte 范围
+    └─ datetime 粒度 或 不匹配任何格式
+        ├─ 有 primaryKey → 清理
+        └─ 无 primaryKey → 保留原值
+```