midway-fatcms 0.0.7 → 0.0.8

package/.qoder/skills/midway-fatcms/03-crud-sharding.md

@@ -0,0 +1,488 @@
+# ShardingCrudPro 分表操作
+
+ShardingCrudPro 提供自动路由分表的能力，支持时间分表、哈希分表、范围分表、自定义分表四种策略。
+
+## 获取实例
+
+```typescript
+import { ShardingType } from 'midway-fatcms';
+
+const sharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.MONTH,
+    baseTable: 't_order',
+    timeColumn: 'created_at',
+    autoCreateTable: true,      // 自动创建分表（可选）
+    recentTableCount: 3,        // 无时间范围时查询最近N张表（可选）
+    countCache: {               // COUNT 查询缓存（仅时间分表，可选）
+      ttlSeconds: 300,          // 缓存5分钟
+      maxSize: 1000,            // 最多缓存1000个表
+    },
+  },
+});
+```
+
+## 分表类型
+
+| 类型 | 枚举值 | 后缀示例 | 适用场景 |
+|------|--------|----------|----------|
+| 按年 | `ShardingType.YEAR` | `_2024` | 数据量适中，按年归档 |
+| 按月 | `ShardingType.MONTH` | `_202401` | 大数据量，按月分表 |
+| 按日 | `ShardingType.DAY` | `_20240115` | 超大数据量，按天分表 |
+| 范围 | `ShardingType.RANGE` | `_0`, `_1`... | 按数值范围分布 |
+| 哈希 | `ShardingType.HASH` | `_01`, `_02`... | 均匀分布数据 |
+| 自定义 | `ShardingType.CUSTOM` | 自定义 | 特殊业务规则 |
+
+## 配置选项
+
+```typescript
+interface IShardingConfig {
+  type: ShardingType;                    // 分表类型（必填）
+  baseTable: string;                     // 基础表名（必填）
+
+  // 时间分表（YEAR/MONTH/DAY）
+  timeColumn?: string;                   // 时间字段名（时间分表必填）
+  primaryKey?: string;                   // 主键字段（时间分表可选，用于清理时间精度问题）
+  recentTableCount?: number;             // 无时间条件时查询最近N张表（默认：YEAR=2, MONTH=3, DAY=7）
+  autoCreateTable?: boolean;             // 自动创建分表（默认false）
+  tableCreateOptions?: {                 // 分表创建选项
+    copyIndexes?: boolean;               // 复制原表索引
+    tableOptions?: string;             // 表选项（如MySQL引擎配置）
+  };
+
+  // 范围/哈希分表（RANGE/HASH）
+  shardingColumn?: string;               // 分表字段（RANGE/HASH必填）
+  tableCount?: number;                   // 分表数量（RANGE默认10，HASH默认16）
+
+  // COUNT 缓存（仅时间分表有效）
+  countCache?: {
+    ttlSeconds?: number;                 // 缓存有效期（秒），默认300
+    maxSize?: number;                    // 最大缓存条目，默认1000
+  };
+
+  // 自定义配置（CUSTOM）
+  customRouter?: (ctx) => string | string[];  // 自定义路由函数
+  suffixFormatter?: (suffix) => string;      // 后缀格式化函数
+}
+```
+
+## API 总览
+
+### 查询方法
+
+| 方法 | 返回类型 | 说明 |
+|------|----------|------|
+| `findOne(req)` | `CrudQueryOneResult<T>` | 查询单条（顺序查多表，找到即返回） |
+| `findUniqueOne(req)` | `CrudQueryOneResult<T>` | 唯一查询（0条返回null，多条报错） |
+| `find(req)` | `T[]` | 列表查询（多表自动合并） |
+| `findList(req)` | `CrudQueryListResult<T>` | 列表查询（带结果包装） |
+| `findPage(req)` | `CrudQueryPageResult<T>` | 分页查询（跨分表自动处理） |
+| `findCount(req)` | `CrudCountResult` | 统计总数（多表并行查询后汇总） |
+| `isExist(req)` | `CrudExistResult` | 存在性判断（多表并行，任一存在即返回true） |
+
+### 写入方法
+
+| 方法 | 返回类型 | 说明 |
+|------|----------|------|
+| `insert(req)` | `CrudWriteResult` | 插入单条（自动路由到对应分表） |
+| `batchInsert(req)` | `ShardingBatchInsertResult` | 批量插入（自动按分表分组并行写入） |
+| `update(req)` | `CrudWriteResult` | 更新（必须能确定单一目标表） |
+| `delete(req)` | `CrudWriteResult` | 删除（必须能确定单一目标表） |
+| `restore(req)` | `CrudWriteResult` | 恢复软删除记录（重置 deleted_at/deleted_by） |
+| `insertOrUpdate(req)` | `CrudUpsertResult` | 插入或更新（condition决定分表） |
+| `insertOnDuplicateUpdate(req)` | `CrudWriteResult` | 原生upsert（condition决定分表） |
+
+### 配置方法
+
+| 方法 | 返回类型 | 说明 |
+|------|----------|------|
+| `setBaseCfg(cfg)` | `this` | 设置基础配置，支持链式调用 |
+| `setEnableSoftDelete(enable)` | `this` | 设置是否启用软删除，支持链式调用 |
+| `getConfig()` | `IShardingConfig` | 获取分表配置 |
+
+## 路由规则详解
+
+分表路由核心原则：**根据操作类型决定从 `data` 还是 `condition` 中提取分表字段**。
+
+### 操作类型与字段来源对照表
+
+| 操作类型 | 字段来源 | 路由逻辑 | 说明 |
+|---------|---------|---------|------|
+| `insert` | `data[分表字段]` | 提取值 → 计算后缀 → 单表 | 插入单条数据 |
+| `batchInsert` | `data[i][分表字段]` | 每条数据单独计算分表 | 支持跨分表并行写入 |
+| `update/delete` | `condition[分表字段]` | 提取值 → 计算后缀 → 单表 | condition决定分表，data是更新内容 |
+| `insertOrUpdate` | `condition[分表字段]` | 提取值 → 计算后缀 → 单表 | condition决定分表 |
+| `insertOnDuplicateUpdate` | `condition[分表字段]` | 提取值 → 计算后缀 → 单表 | condition决定分表 |
+| `find/findPage` | `condition[分表字段]` | 时间范围 → 候选表 → 与真实表取交集 → 多表 | 自动合并多表结果 |
+| `findOne/findUniqueOne` | `condition[分表字段]` | 同 find | 顺序查询各分表 |
+| `findCount/isExist` | `condition[分表字段]` | 同 find | 多表并行查询后汇总 |
+
+### 关键结论
+
+- **插入类操作**（insert/batchInsert）：只使用 `data`，不需要传 `condition`
+- **查询类操作**（find/delete/isExist等）：只使用 `condition`，不使用 `data`
+- **更新类操作**（update/insertOrUpdate/insertOnDuplicateUpdate）：`condition` 用于路由，`data` 是更新内容
+
+## 时间分表约束
+
+### 核心原则：写操作必须包含 timeColumn
+
+时间分表根据 timeColumn 路由到正确的分表。**所有写操作（insert/update/delete/restore）必须在 data 或 condition 中提供 timeColumn 字段**，否则无法确定目标分表。
+
+### 写入校验
+
+| 操作 | 校验规则 | 错误提示 |
+|------|---------|----------|
+| `insert` | `data` 必须包含 `timeColumn` | `insert 操作的 data 必须包含时间字段 'xxx'` |
+| `batchInsert` | 每条 `data[i]` 必须包含 `timeColumn` | `batchInsert 操作的 data[i] 必须包含时间字段 'xxx'` |
+| `update` | `condition` 必须包含 `timeColumn` | `update 操作的 condition 必须包含时间字段 'xxx'` |
+| `delete` | `condition` 必须包含 `timeColumn` | `delete 操作的 condition 必须包含时间字段 'xxx'` |
+| `restore` | `condition` 必须包含 `timeColumn` | `restore 操作的 condition 必须包含时间字段 'xxx'` |
+| `insertOrUpdate` | `data` + `condition` 均须包含 `timeColumn` | 同上 |
+| `insertOnDuplicateUpdate` | `data` + `condition` 均须包含 `timeColumn` | 同上 |
+
+```typescript
+// ✅ 正确 - insert 包含时间字段
+await sharding.insert({
+  data: { order_id: '001', amount: 100, created_at: '2024-03-15' }
+});
+
+// ❌ 错误 - insert 缺少时间字段
+await sharding.insert({
+  data: { order_id: '001', amount: 100 }  // 报错：无法路由到目标分表
+});
+
+// ✅ 正确 - update 包含时间字段
+await sharding.update({
+  condition: { order_id: '001', created_at: '2024-03-15' },
+  data: { status: 'shipped' }
+});
+
+// ❌ 错误 - update 缺少时间字段
+await sharding.update({
+  condition: { order_id: '001' },  // 报错：无法路由到目标分表
+  data: { status: 'shipped' }
+});
+```
+
+### 查询约束
+
+时间分表查询（`find`/`findPage`/`findList`）在多表场景下有以下强制约束：
+
+| 约束项 | 要求 | 原因 |
+|-------|------|------|
+| **orderBy 必传** | 必须传 orderBy 参数 | 分表查询必须明确排序方式 |
+| **排序字段** | 必须为 `timeColumn DESC` 或 `timeColumn ASC` | 利用分表顺序特性，无需内存排序 |
+| **排序方向** | 支持 `DESC`（最新在前）和 `ASC`（最旧在前） | DESC时表顺序新→旧，ASC时旧→新 |
+
+```typescript
+// ✅ 正确用法
+await sharding.find({
+  condition: { status: 'pending' },
+  orderBy: 'created_at DESC',  // 必须为 timeColumn DESC/ASC
+});
+
+// ❌ 错误用法
+await sharding.find({
+  condition: { status: 'pending' },
+  orderBy: 'id DESC',  // 错误：不是时间字段
+});
+```
+
+### 时间字段智能处理
+
+时间分表中，`timeColumn` 既是路由键也是查询条件。用户传入的时间值可能精度不一致（如传 `'2024-01-15'` 但数据库存的是毫秒时间戳），直接作为 WHERE 条件可能导致匹配失败。系统会根据值类型和主键情况自动智能处理：
+
+#### 处理规则
+
+| timeColumn 值类型 | 有 primaryKey? | 操作 | 原因 |
+|-------------------|---------------|------|------|
+| 操作符表达式（$gte/$lte/$range/$in/$null 等） | 任意 | **保留** | 用户明确要按操作符查询 |
+| 精确值（string/number/boolean/Date） | 有 | **清理**（移除出 WHERE） | 主键已唯一确定行，timeColumn 仅用于路由 |
+| 日期粒度字符串（`'2024'`/`'2024-01'`/`'2024-01-15'`） | 无 | **转换为 $gte/$lte 范围** | 精确值可能精度不匹配，转为范围更安全 |
+| 其他精确值（时间戳/datetime/null等） | 无 | **保留原值** | 无法推断粒度或精度已足够 |
+
+#### 有主键 → 清理
+
+```typescript
+// 配置：{ primaryKey: 'order_id', timeColumn: 'created_at' }
+
+// 清理前
+{ 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'  ← 精准匹配
+```
+
+#### 无主键 + 日期粒度字符串 → 转换为范围
+
+```typescript
+// '2024' → 年范围
+{ status: 'paid', created_at: '2024' }
+→ { status: 'paid', created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-12-31 23:59:59' } }
+
+// '2024-01' → 月范围（闰年自动处理）
+{ status: 'paid', created_at: '2024-01' }
+→ { status: 'paid', created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
+
+// '2024-01-15' → 日范围
+{ 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' } }
+
+// '2024-01-15 10:30:00' → 精确到秒，不转换
+{ status: 'paid', created_at: '2024-01-15 10:30:00' }
+// 保留原值
+```
+
+#### 操作符表达式 → 始终保留
+
+```typescript
+// 无论有无主键，操作符表达式一律保留
+{ order_id: 'ORD001', created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-06-30 23:59:59' } }
+// 不做任何处理，SQL: WHERE order_id = 'ORD001' AND created_at >= '2024-01-01 00:00:00' AND created_at <= '2024-06-30 23:59:59'
+```
+
+适用场景：所有操作（读 + 写）的 condition 都会经过智能处理。
+
+#### ⚠️ $gte/$lte 时间精度要求
+
+当使用 `$gte`/`$lte`/`$gt`/`$lt` 操作符查询时间字段时，**值必须精确到秒**（`YYYY-MM-DD HH:mm:ss`），不允许只传日期部分。
+
+原因：MySQL 将 `'2026-04-30'` 等价于 `'2026-04-30 00:00:00'`，导致 `$lte: '2026-04-30'` 会丢失当天所有数据。
+
+```typescript
+// ✅ 正确 - 精确到秒，覆盖完整月份
+condition: { created_at: { $gte: '2026-04-01 00:00:00', $lte: '2026-04-30 23:59:59' } }
+
+// ❌ 错误 - 缺少时间部分，4月30日当天数据全部丢失
+condition: { created_at: { $gte: '2026-04-01', $lte: '2026-04-30' } }
+// 等价于 created_at <= '2026-04-30 00:00:00'，4月30日全天数据被排除
+
+// ✅ 正确 - 精确到秒，覆盖完整日期
+condition: { created_at: { $gte: '2026-04-15 00:00:00', $lte: '2026-04-15 23:59:59' } }
+```
+
+**替代方案**：如果只想查某个月/某天的数据，直接传日期粒度字符串即可，系统会自动转换为精确到秒的范围：
+
+```typescript
+// ✅ 推荐 - 直接传粒度字符串，系统自动转范围（精确到秒）
+condition: { created_at: '2026-04' }      // → { $gte: '2026-04-01 00:00:00', $lte: '2026-04-30 23:59:59' }
+condition: { created_at: '2026-04-15' }   // → { $gte: '2026-04-15 00:00:00', $lte: '2026-04-15 23:59:59' }
+condition: { created_at: '2026' }         // → { $gte: '2026-01-01 00:00:00', $lte: '2026-12-31 23:59:59' }
+```
+
+### 软删除支持
+
+ShardingCrudPro 支持软删除模式，启用后 `delete` 操作会设置 `deleted_at` 和 `deleted_by` 字段，而非物理删除：
+
+```typescript
+const sharding = this.curdProService
+  .getShardingCrud({
+    sqlDatabase: 'mydb',
+    sqlDbType: SqlDbType.mysql,
+    shardingConfig: {
+      type: ShardingType.MONTH,
+      baseTable: 't_order',
+      timeColumn: 'created_at',
+    },
+  })
+  .setEnableSoftDelete(true);
+
+// 软删除
+await sharding.delete({ condition: { id: 1, created_at: '2024-03-15' } });
+
+// 恢复软删除的记录
+await sharding.restore({ condition: { id: 1, created_at: '2024-03-15' } });
+```
+
+## 查询行为详解
+
+### 配置了 recentTableCount
+
+```typescript
+const sharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.MONTH,
+    baseTable: 't_order',
+    recentTableCount: 3,  // 最近3张表
+  },
+});
+```
+
+**行为**：从真实存在的表中取最近N张，再与查询条件取交集。
+
+| 场景 | 行为 |
+|------|------|
+| 无时间条件 | 查询最近3张真实存在的表 |
+| 有时间范围 | 与最近3张表取交集 |
+| 时间范围不在最近N张内 | 可能返回空结果 |
+
+### 未配置 recentTableCount
+
+**行为**：查询条件推导出的表与"真实存在的表"取交集，最多返回3张（按时间倒序取最新的）。
+
+| 场景 | 行为 |
+|------|------|
+| 无时间条件 | 所有真实表最多取3张 |
+| 有时间范围 | 条件推导的表与真实表取交集，最多3张 |
+| 历史数据查询 | 只要表还存在就能查到 |
+
+## 使用示例
+
+### 按月分表
+
+```typescript
+import { ShardingType } from 'midway-fatcms';
+
+const sharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.MONTH,
+    baseTable: 't_order',
+    timeColumn: 'created_at',
+    autoCreateTable: true,
+  },
+});
+
+// 插入数据 - 自动路由到 t_order_202403
+await sharding.insert({
+  data: {
+    order_id: '001',
+    amount: 100,
+    created_at: '2024-03-15',  // ← 分表字段在 data 中
+  }
+});
+
+// 批量插入 - 自动按月份分组并行写入
+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.totalAffected);  // 3
+console.log(result.tableCount);       // 3（涉及3个分表）
+
+// 分页查询 - 跨分表自动合并（必须传 orderBy）
+const page = await sharding.findPage({
+  condition: {
+    status: 'paid',
+    created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-03-31 23:59:59' }
+  },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',  // 必须传，且格式固定
+});
+console.log(page.rows, page.totalCount);
+
+// 链式配置
+const sharding2 = this.curdProService
+  .getShardingCrud({
+    sqlDatabase: 'mydb',
+    sqlDbType: SqlDbType.mysql,
+    shardingConfig: {
+      type: ShardingType.MONTH,
+      baseTable: 't_order',
+      timeColumn: 'created_at',
+    },
+  })
+  .setBaseCfg({
+    enableStandardUpdateCfg: true,
+    enableSoftDelete: true,
+  });
+```
+
+### 哈希分表
+
+```typescript
+const sharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.HASH,
+    baseTable: 't_user',
+    shardingColumn: 'user_id',
+    tableCount: 16,  // t_user_01 ~ t_user_16
+  },
+});
+
+// 插入 - 根据 user_id 哈希路由
+await sharding.insert({
+  data: { user_id: 10001, name: '张三' }  // → 路由到 t_user_05
+});
+
+// 查询 - 需要提供 user_id 用于路由
+const user = await sharding.findOne({
+  condition: { user_id: 10001 }  // 根据 user_id 确定分表
+});
+
+// 查询多用户 - 无 user_id 时扫描多个分表
+const users = await sharding.find({
+  condition: { status: 'active' },
+  orderBy: 'created_at DESC',
+});
+```
+
+## COUNT 缓存（时间分表专用）
+
+分页查询时需要先统计各分表的记录数。对于历史数据表（非当前时间周期），COUNT 值相对稳定，启用缓存可大幅提升性能。
+
+```typescript
+const sharding = this.curdProService.getShardingCrud({
+  sqlDatabase: 'mydb',
+  sqlDbType: SqlDbType.mysql,
+  shardingConfig: {
+    type: ShardingType.MONTH,
+    baseTable: 't_order',
+    timeColumn: 'created_at',
+    countCache: {
+      ttlSeconds: 300,   // 缓存5分钟
+      maxSize: 1000,     // 最多缓存1000个表的COUNT
+    },
+  },
+});
+```
+
+**缓存策略**：
+- **历史表**：启用缓存，COUNT 结果缓存 TTL 秒
+- **当前表**：实时查询，确保数据准确性
+- **LRU 淘汰**：缓存满时淘汰最久未使用的条目
+
+**效果对比**（查询2024年1-3月数据，分页导航第1-5页）：
+
+| 步骤 | 无缓存 | 有缓存（5分钟TTL） |
+|------|-------|------------------|
+| 第1页 | 查3张表 COUNT | 查3张表 COUNT |
+| 第2-5页 | 各查3张表 COUNT | 从缓存读取 |
+| **总计** | **15次 COUNT 查询** | **3次 COUNT 查询** |
+
+## 错误处理
+
+| 场景 | 错误信息 |
+|------|----------|
+| insert 缺少 timeColumn | `insert 操作的 data 必须包含时间字段 'xxx'，用于路由到正确的分表` |
+| update 缺少 timeColumn | `update 操作的 condition 必须包含时间字段 'xxx'，用于路由到正确的分表` |
+| restore 无条件 | `restore 操作必须指定恢复条件` |
+| 插入到不存在的表 | `分表 xxx 不存在，请先创建` |
+| 查询缺少 orderBy | `查询操作必须传 orderBy 参数` |
+| orderBy 字段错误 | `orderBy 首个排序字段必须为 'xxx'` |
+| CUSTOM 缺少 router | `CUSTOM 分表必须提供 customRouter 函数` |
+
+## 注意事项
+
+1. **时间分表写操作必须包含 timeColumn**：insert 的 `data` 或 update/delete 的 `condition` 中必须提供时间字段值
+2. **插入操作必须包含分表字段**：`data` 中必须有分表字段值
+3. **批量插入支持跨分表**：自动按分表分组并行写入
+4. **查询时无时间范围限制**：默认查询最近 N 张分表（YEAR=2, MONTH=3, DAY=7，可配置 `recentTableCount`）
+5. **COUNT 缓存仅对时间分表有效**：哈希/范围分表不启用缓存
+6. **时间字段智能处理**：有主键时精确值自动清理；无主键时日期粒度字符串自动转换为 $gte/$lte 范围；操作符表达式始终保留
+7. **软删除恢复**：启用 setEnableSoftDelete 后可使用 restore 方法恢复已删除记录
+8. **$gte/$lte 必须精确到秒**：使用操作符查询时间字段时值必须包含时分秒（如 `'2026-04-30 23:59:59'`），不允许只传日期部分（`'2026-04-30'`）；如需查整月/整天数据，推荐直接传粒度字符串（`'2026-04'`/`'2026-04-15'`）由系统自动转换

package/.qoder/skills/midway-fatcms/04-condition-operators.md

@@ -0,0 +1,93 @@
+# 条件操作符大全
+
+## 比较操作符
+
+| 操作符 | SQL 等价 | 示例 |
+|--------|----------|------|
+| $gt | > | { age: { $gt: 18 } } |
+| $gte | >= | { age: { $gte: 18 } } |
+| $lt | < | { age: { $lt: 60 } } |
+| $lte | <= | { age: { $lte: 60 } } |
+| $ne | != | { status: { $ne: 'deleted' } } |
+
+## 范围操作符
+
+| 操作符 | SQL 等价 | 示例 |
+|--------|----------|------|
+| $in | IN | { id: { $in: [1, 2, 3] } } |
+| $nin | NOT IN | { type: { $nin: ['test'] } } |
+| $range | BETWEEN ... AND | { amount: { $range: [100, 500] } } |
+
+## 模糊查询
+
+| 操作符 | SQL 等价 | 示例 |
+|--------|----------|------|
+| $like | LIKE 'A%'（前缀匹配） | { name: { $like: '张' } } |
+| $notLike | NOT LIKE 'A%'（不匹配前缀） | { name: { $notLike: 'test%' } } |
+| $likeInclude | LIKE '%A%'（包含匹配） | { name: { $likeInclude: '张三' } } |
+| $notLikeInclude | NOT LIKE '%A%'（不包含） | { name: { $notLikeInclude: 'test' } } |
+
+## NULL 判断
+
+| 操作符 | SQL 等价 | 示例 |
+|--------|----------|------|
+| $null | IS NULL | { deleted_at: { $null: true } } |
+| $notNull | IS NOT NULL | { phone: { $notNull: true } } |
+
+> **注意**：`$null` 和 `$notNull` 的值必须为 `true` 才生效。传 `false` 等同于未设置该条件（不会生成 IS NULL / IS NOT NULL）。
+
+## 全文搜索（MySQL）
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| $match | 全文搜索 | { content: { $match: 'keyword' } } |
+| $matchBool | 布尔全文搜索 | { content: { $matchBool: '+keyword -exclude' } } |
+
+## JSON 操作
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| $jsonArrayContains | JSON 数组包含 | { tags: { $jsonArrayContains: 'tag1' } } |
+
+## 逻辑组合
+
+```typescript
+// AND
+{ $and: [{ status: 'active' }, { age: { $gte: 18 } }] }
+
+// OR
+{ $or: [{ status: 'pending' }, { status: 'processing' }] }
+
+// AND + OR 组合
+{
+  $and: [
+    { department: 'tech' },
+    { $or: [{ level: 'senior' }, { years: { $gte: 5 } }] }
+  ]
+}
+```
+
+## 排序语法
+
+```typescript
+// 字符串格式（标准 SQL 格式）
+orderBy: 'created_at DESC'
+orderBy: 'created_at DESC, amount ASC'
+
+// 简写格式（+ 升序，- 降序）
+orderBy: 'created_at-'     // 降序
+orderBy: 'age+'            // 升序
+orderBy: 'department+,age-,created_at-'  // 多字段
+
+// 数组格式
+orderBy: [
+  { fieldName: 'department', orderType: 'ASC' },
+  { fieldName: 'created_at', orderType: 'DESC' },
+]
+
+// 混合数组
+orderBy: [
+  { fieldName: 'created_at', orderType: 'DESC' },
+  'amount+',
+]
+```