midway-fatcms 0.0.7 → 0.0.9

package/src/service/curd/README.md

@@ -1,1100 +0,0 @@
-# Curd 服务层
-
-Curd 服务层在 CrudPro 库之上封装了**自动上下文注入、标准字段填充、软删除、快捷 CRUD、分表入口和关联数据填充**能力，是业务代码操作数据库的唯一入口。
-
-> CrudPro 库本身的使用指南见 [libs/crud-pro/README.md](../../libs/crud-pro/README.md)，分表路由逻辑见 [libs/crud-sharding/ROUTING_LOGIC.md](../../libs/crud-sharding/ROUTING_LOGIC.md)。
-
-## 架构总览
-
-```
-业务代码
-  │
-  ├── CurdMixService（协调入口，CurdProService + 关联数据填充）
-  │     ├── CurdMixByDictService         → relatedType: 'dict'
-  │     ├── CurdMixBySysConfigService    → relatedType: 'sysCfgEnum'
-  │     ├── CurdMixByAccountService      → relatedType: 'accountBasic'
-  │     ├── CurdMixByWorkbenchService    → relatedType: 'workbenchBasic'
-  │     └── CurdMixByLinkToCustomService → relatedType: 'linkToCustom'
-  │
-  └── CurdProService（核心封装层）
-        ├── CrudProQuick      → 快捷 CRUD（链式调用）
-        ├── ShardingCrudPro   → 分表 CRUD
-        ├── fixCfgModel()     → 标准字段自动填充
-        └── fixSoftDelete()   → 软删除处理
-```
-
-核心工具：`CurdMixUtils` 提供 `copyColumnRelationToRow`、`forEachRowAndColumnsRelation` 等通用方法。
-
-## 服务层 vs CrudPro 库
-
-| 能力 | CrudPro 库 | Curd 服务层 |
-|------|-----------|------------|
-| SQL 生成与执行 | ✅ | 透传 |
-| 事务 / 连接管理 | 需手动注入 | 自动从 Midway Context 注入 |
-| visitor（当前用户）| 需手动设置 | 自动从 userSession 转换 |
-| 标准字段自动填充 | 需手动配置 updateCfg | `fixCfgModel` 自动注入 |
-| 软删除 | 无 | `fixSoftDelete` 自动处理 |
-| 快捷 CRUD | 无 | `CrudProQuick` |
-| 分表 CRUD | `ShardingCrudPro` 类 | `getShardingCrud()` 工厂方法 |
-| 关联数据填充 | columnsRelation 定义 | `CurdMixService` 自动执行 |
-| 自定义 SQL 执行 | `executeSQL` | 透传 |
-
-## CurdProService
-
-Midway `@Provide()` 服务，自动注入 `ctx`、数据库配置和全局配置。
-
-### 自动上下文注入
-
-每次调用 `getCrudPro()` 创建实例时，自动完成：
-
-- **visitor**：从 `ctx.userSession` 提取用户信息（accountId、nickName、roleCodes、functionCodes、workbenchCode 等）
-- **transaction**：从 `ctx.transaction` 获取事务管理器（需配合 `tx.middleware`）
-- **logger**：使用 `BaseService.getContextLogger()`
-- **contextCfg**：从全局配置注入系统数据库名/类型
-- **contextFunc**：`MyContextFunc` 根据数据库名从 Midway Config 中获取连接池
-
-### 核心方法
-
-| 方法 | 说明 |
-|------|------|
-| `executeCrudByCfg(reqJson, cfgModel)` | 带标准字段填充 + 软删除的 CRUD 执行 |
-| `executeCrud(reqJson)` | 从数据库加载配置并执行（method 必填） |
-| `executeSQL(sqlCfgModel)` | 直接执行 SQL |
-| `getQuickCrud(db, dbType, table?)` | 获取 CrudProQuick 实例 |
-| `getShardingCrud(db, dbType, config)` | 获取 ShardingCrudPro 实例 |
-| `getCachedCfgByMethod(method)` | 从缓存加载配置 |
-| `getAllTableInfos(query, options?)` | 获取表结构信息 |
-
-## CrudProQuick
-
-面向业务代码的快捷 CRUD 工具，省去手动组装 `cfgModel` 的步骤。所有方法自动继承 `CurdProService` 的上下文（visitor、事务、软删除、标准字段填充等）。
-
-### 获取实例
-
-```typescript
-import { SqlDbType } from '@/libs/crud-pro/models/keys';
-
-// 方式1：通过 CurdProService（推荐）
-const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_user');
-
-// 方式2：通过 CurdMixService（兼容旧版本）
-const quick = curdMixService.getBbUtil('mydb', SqlDbType.mysql, 't_user');
-
-// sqlTable 可在构造时指定，也可在每次调用时覆盖
-const quick2 = curdProService.getQuickCrud('mydb', SqlDbType.mysql);
-const users = await quick2.getList({ condition: { status: 1 } }, 't_user');
-```
-
-### 基础配置
-
-#### setBaseCfgModel
-
-通过 `setBaseCfgModel` 可设置公共配置，后续所有操作自动携带：
-
-```typescript
-const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_order');
-
-// 设置公共配置
-quick.setBaseCfgModel({
-  maxLimit: 50000,                    // 最大查询限制
-  enableStandardUpdateCfg: true,      // 启用标准字段自动填充
-  enableSoftDelete: true,             // 启用软删除
-  enableStandardUpdateCfgCondition: true, // 查询条件自动注入 created_by
-});
-
-// 后续所有操作都会自动携带这些配置
-```
-
-### API 分类一览
-
-#### 查询类方法
-
-| 方法 | 返回类型 | 说明 |
-|------|----------|------|
-| `getList(reqJson, sqlTable?)` | `any[]` | 列表查询 |
-| `getListPage(reqJson, sqlTable?)` | `ResModelPageQuery` | 分页查询（含 total_count） |
-| `getUniqueOne(reqJson, sqlTable?)` | `any \| null` | 期望唯一一条，0条返回null，多条报错 |
-| `getOne(reqJson, sqlTable?)` | `any` | 获取第一条（已废弃，建议用 getUniqueOne） |
-| `isExist(reqJson, sqlTable?)` | `boolean` | 存在性判断（比 COUNT 高效） |
-| `getTotalCount(reqJson, sqlTable?)` | `number` | 统计总数 |
-
-#### 写入类方法
-
-| 方法 | 返回类型 | 说明 |
-|------|----------|------|
-| `insertObject(reqJson, sqlTable?)` | `ResModelAffected` | 插入单条 |
-| `batchInsert(reqJson, sqlTable?)` | `ResModelAffected` | 批量插入（推荐大数据量使用） |
-| `updateObject(reqJson, sqlTable?)` | `ResModelAffected` | 更新 |
-| `insertOrUpdate(reqJson, sqlTable?)` | `ResModelStandard` | 先查询存在性，再决定插入或更新 |
-| `insertOnDuplicate(reqJson, uniqueColumn?, sqlTable?)` | `ResModelAffected` | 原生 upsert（效率更高） |
-| `deleteObject(reqJson, sqlTable?)` | `ResModelAffected` | 删除（受软删除配置影响） |
-
-#### 原生 SQL 方法
-
-| 方法 | 返回类型 | 说明 |
-|------|----------|------|
-| `executeSQL(sql, args?)` | `any` | 框架封装的 SQL 执行（参数绑定） |
-| `executeNativeSQL<T>(sql, args?)` | `T` | 原生 SQL 执行，不做额外处理 |
-
-### 请求参数结构
-
-所有查询/写入方法都接受 `IRequestModel` 作为参数：
-
-```typescript
-interface IRequestModel {
-  condition?: Record<string, any>;     // 查询/更新/删除条件
-  data?: Record<string, any> | Record<string, any>[];  // 插入/更新数据
-  pageNo?: number;                      // 页码（从1开始）
-  pageSize?: number;                    // 每页条数
-  orderBy?: string | OrderByItem[];   // 排序规则
-  columns?: string[];                   // 指定返回列（默认全返回）
-}
-```
-
-### 条件查询详解
-
-#### 基础条件（自动转 $eq）
-
-```typescript
-// 简单等值条件 - 自动转换为 $eq
-const users = await quick.getList({
-  condition: { status: 'active', age: 18 }
-});
-// 等价于: WHERE status = 'active' AND age = 18
-```
-
-#### 操作符条件
-
-```typescript
-// 比较操作符
-const users = await quick.getList({
-  condition: {
-    age: { $gt: 18, $lt: 60 },           // 大于且小于
-    score: { $gte: 60 },                 // 大于等于
-    level: { $lte: 10 },                 // 小于等于
-    status: { $ne: 'deleted' },          // 不等于
-  }
-});
-
-// 范围操作符
-const orders = await quick.getList({
-  condition: {
-    id: { $in: [1, 2, 3, 4, 5] },        // IN 查询
-    type: { $nin: ['test', 'draft'] },   // NOT IN 查询
-    amount: { $between: [100, 500] },   // BETWEEN 查询
-    name: { $like: '%张三%' },           // LIKE 模糊查询
-  }
-});
-
-// NULL 判断
-const users = await quick.getList({
-  condition: {
-    deleted_at: { $isNull: true },      // IS NULL
-    phone: { $isNotNull: true },         // IS NOT NULL
-  }
-});
-```
-
-#### 组合条件
-
-```typescript
-// AND 条件（默认）
-const users = await quick.getList({
-  condition: {
-    $and: [
-      { status: 'active' },
-      { age: { $gte: 18 } },
-    ]
-  }
-});
-
-// OR 条件
-const users = await quick.getList({
-  condition: {
-    $or: [
-      { status: 'pending' },
-      { status: 'processing' },
-    ]
-  }
-});
-
-// AND + OR 组合
-const users = await quick.getList({
-  condition: {
-    $and: [
-      { department: 'tech' },
-      {
-        $or: [
-          { level: 'senior' },
-          { years: { $gte: 5 } },
-        ]
-      }
-    ]
-  }
-});
-// 等价于: WHERE department = 'tech' AND (level = 'senior' OR years >= 5)
-```
-
-### 排序规则
-
-```typescript
-// 字符串语法（推荐）
-const users = await quick.getList({
-  condition: { status: 'active' },
-  orderBy: 'created_at-',    // 降序（后缀 - 表示 DESC）
-});
-
-const users2 = await quick.getList({
-  condition: { status: 'active' },
-  orderBy: 'age+',           // 升序（后缀 + 表示 ASC，可省略）
-});
-
-// 多字段排序
-const users3 = await quick.getList({
-  condition: { status: 'active' },
-  orderBy: 'department+,age-,created_at-',
-  // 等价于: ORDER BY department ASC, age DESC, created_at DESC
-});
-
-// 对象数组语法
-const users4 = await quick.getList({
-  condition: { status: 'active' },
-  orderBy: [
-    { fieldName: 'department', orderType: 'ASC' },
-    { fieldName: 'created_at', orderType: 'DESC' },
-  ]
-});
-```
-
-### 完整使用示例
-
-#### 1. 查询操作
-
-```typescript
-const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_user');
-
-// 基础查询
-const users = await quick.getList({
-  condition: { status: 'active' }
-});
-
-// 条件 + 排序 + 指定字段
-const users = await quick.getList({
-  condition: {
-    status: 'active',
-    age: { $gte: 18, $lte: 60 },
-  },
-  orderBy: 'created_at-',
-  columns: ['id', 'name', 'email'],  // 只返回指定字段
-});
-
-// 分页查询
-const page = await quick.getListPage({
-  condition: { status: 'active' },
-  pageNo: 1,
-  pageSize: 20,
-  orderBy: 'created_at-',
-});
-console.log(page.rows);        // 当前页数据
-console.log(page.total_count); // 总记录数
-
-// 唯一查询（期望结果只有0或1条）
-const user = await quick.getUniqueOne({
-  condition: { email: 'user@example.com' }
-});
-// 0条返回 null，多条抛出异常
-
-// 存在性判断（比 COUNT 查询更高效）
-const exists = await quick.isExist({
-  condition: { phone: '13800138000' }
-});
-
-// 统计总数
-const count = await quick.getTotalCount({
-  condition: { status: 'active' }
-});
-```
-
-#### 2. 写入操作
-
-```typescript
-// 插入单条
-const result = await quick.insertObject({
-  data: {
-    name: '张三',
-    email: 'zhangsan@example.com',
-    status: 'active',
-    // 如果启用 enableStandardUpdateCfg，会自动填充 created_by 等字段
-  }
-});
-console.log(result.affectedRows);  // 1
-console.log(result.insertId);        // 自增ID
-
-// 批量插入（效率远高于循环单条插入）
-const result = await quick.batchInsert({
-  data: [
-    { name: '张三', email: 'zs@example.com' },
-    { name: '李四', email: 'ls@example.com' },
-    { name: '王五', email: 'ww@example.com' },
-  ]
-});
-console.log(result.affectedRows);  // 3
-
-// 更新（注意：必须带 condition，否则可能全表更新）
-const result = await quick.updateObject({
-  condition: { id: 1 },               // WHERE id = 1
-  data: {
-    name: '张三丰',
-    updated_at: new Date(),
-    // 如果启用 enableStandardUpdateCfg，会自动填充 modified_by 等字段
-  }
-});
-console.log(result.affectedRows);  // 1
-
-// 插入或更新（先查询存在性）
-const result = await quick.insertOrUpdate({
-  condition: { email: 'zhangsan@example.com' },  // 查询条件
-  data: {
-    name: '张三',
-    email: 'zhangsan@example.com',
-    age: 25,
-  }
-});
-// 如果不存在：执行 INSERT
-// 如果存在：执行 UPDATE（用 data 更新匹配的记录）
-
-// 原生 upsert（MySQL: ON DUPLICATE KEY UPDATE）
-const result = await quick.insertOnDuplicate(
-  {
-    data: {
-      id: 1,
-      name: '张三',
-      count: 1,
-    }
-  },
-  ['id'],  // 唯一列（PostgreSQL/SQL Server 必需）
-);
-// 如果唯一键冲突，执行 UPDATE，否则执行 INSERT
-// MySQL 可省略 uniqueColumn，依赖表的唯一索引
-
-// 删除（受软删除配置影响）
-const result = await quick.deleteObject({
-  condition: { id: 1 }
-});
-// 如果 enableSoftDelete = true，实际执行 UPDATE 设置 deleted_at
-// 如果 enableSoftDelete = false，执行物理 DELETE
-```
-
-#### 3. 原生 SQL 执行
-
-```typescript
-import { NativeSqlSelectResult, NativeSqlResultMySQL } from '@/libs/crud-pro/models/ResModel';
-
-// 执行框架封装的 SQL（带参数绑定、日志等）
-const rows = await quick.executeSQL(
-  'SELECT * FROM t_user WHERE status = ? AND created_at > ?',
-  ['active', '2024-01-01']
-);
-
-// 执行原生 SQL（最小封装，返回数据库驱动原始结果）
-
-// SELECT 查询
-const users = await quick.executeNativeSQL<{id: number; name: string}[]>(
-  'SELECT id, name FROM t_user WHERE age > ? ORDER BY id DESC LIMIT 10',
-  [18]
-);
-
-// MySQL INSERT/UPDATE/DELETE
-const result = await quick.executeNativeSQL<NativeSqlResultMySQL>(
-  'INSERT INTO t_user (name, age) VALUES (?, ?)',
-  ['张三', 20]
-);
-console.log(result.insertId);      // 自增ID
-console.log(result.affectedRows);  // 影响行数
-console.log(result.changedRows);   // 实际修改行数（MySQL特有）
-```
-
-#### 4. 动态表名切换
-
-```typescript
-// 构造时不指定表名
-const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql);
-
-// 每次调用时指定表名
-const users = await quick.getList(
-  { condition: { status: 'active' } },
-  't_user'  // 第二个参数为表名
-);
-
-const orders = await quick.getList(
-  { condition: { status: 'paid' } },
-  't_order'
-);
-```
-
-### 高级配置组合示例
-
-```typescript
-const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_article');
-
-// 组合配置：软删除 + 标准字段填充 + 数据权限
-quick.setBaseCfgModel({
-  maxLimit: 10000,
-  enableSoftDelete: true,              // 软删除
-  enableStandardUpdateCfg: true,         // 自动填充 created_by/modified_by
-  enableStandardUpdateCfgCondition: ['by'], // 查询条件自动注入 created_by = 当前用户ID
-});
-
-// 此时：
-// - insert: 自动填充 created_by 和 deleted_at = 0
-// - update: 自动填充 modified_by，条件自动加 created_by = 当前用户ID
-// - delete: 实际执行 UPDATE 设置 deleted_at 和 deleted_by
-// - query: 自动追加 condition.deleted_at = 0
-// - 查询条件: 自动追加 created_by = 当前用户ID（只能查自己的数据）
-```
-
-## IRequestCfgModel2 扩展配置
-
-服务层在 CrudPro 的 `IRequestCfgModel` 基础上扩展了 `IRequestCfgModel2`：
-
-```typescript
-interface IRequestCfgModel2 extends IRequestCfgModel {
-  enableStandardUpdateCfg?: boolean | string[];       // 标准字段自动填充
-  enableStandardUpdateCfgCondition?: boolean | string[]; // condition 中的标准字段填充
-  enableSoftDelete?: boolean;                          // 启用软删除
-}
-```
-
-### enableStandardUpdateCfg
-
-控制 `fixCfgModel` 是否自动向 `updateCfg` 注入标准字段。
-
-| 值 | 行为 |
-|----|------|
-| `undefined` / `true` | 默认行为：insert/update 自动填充 `created_by`、`modified_by` 等 |
-| `false` | 完全关闭标准字段自动填充 |
-| `string[]` | 指定要填充的字段后缀，如 `['by']` 只填充 `created_by`/`modified_by` |
-| `['null']` | 等同于空数组，不填充任何字段 |
-
-### enableStandardUpdateCfgCondition
-
-控制查询/删除条件中是否自动注入 `created_by` 等字段，实现"只能查自己数据"的效果。
-
-| 值 | 行为 |
-|----|------|
-| `undefined` / `false` | 不在 condition 中注入 |
-| `string[]` | 指定字段后缀，如 `['by']` 自动注入 `condition.created_by = 当前用户ID` |
-| `['null']` | 不注入 |
-
-### 各操作类型自动填充规则
-
-| 操作类型 | data 字段 | condition 字段 |
-|---------|-----------|---------------|
-| INSERT | `created_by`, `created_avatar`, `created_nickname`, `created_account_type` | — |
-| UPDATE | `modified_by`, `modified_avatar`, `modified_nickname`, `modified_account_type` | `created_by`, `created_account_type`（限制只改自己的） |
-| DELETE | — | `created_by`, `created_account_type`（限制只删自己的） |
-| INSERT_OR_UPDATE / INSERT_ON_DUPLICATE_UPDATE | `created_*` + `modified_*` | `created_by`, `created_account_type` |
-| QUERY / QUERY_PAGE / QUERY_ONE | — | 由 `enableStandardUpdateCfgCondition` 控制 |
-
-> 上述 `created_by` / `modified_by` 取自 `visitor.accountId`，其余字段取自 visitor 对应属性。
-
-## 软删除
-
-当 `cfgModel.enableSoftDelete = true` 时，`fixSoftDelete` 自动改写操作行为：
-
-| 操作 | 原始行为 | 软删除行为 |
-|------|---------|-----------|
-| INSERT | 正常插入 | 自动设置 `data.deleted_at = 0` |
-| DELETE | 物理删除 | 改为 UPDATE：设置 `deleted_at = 当前时间戳`、`deleted_by = 当前用户ID` |
-| QUERY / QUERY_ONE / QUERY_PAGE | 正常查询 | 自动追加 `condition.deleted_at = 0` |
-
-**前提**：表必须包含 `deleted_at`（number 类型）和 `deleted_by`（string 类型）字段。
-
-```typescript
-// 启用软删除
-const cfgModel: IRequestCfgModel2 = {
-  method: 'article.delete',
-  sqlTable: 'article',
-  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_DELETE,
-  enableSoftDelete: true,
-};
-
-// 实际执行：UPDATE article SET deleted_at=1712851200000, deleted_by='user123' WHERE id=1
-```
-
-## 分表 CRUD 入口
-
-通过 `CurdProService.getShardingCrud()` 获取分表操作器：
-
-```typescript
-import { ShardingType } from '@/libs/crud-sharding';
-
-const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.MONTH,
-  baseTable: 't_order',
-  timeColumn: 'created_at',
-  countCache: { ttlSeconds: 300 },
-});
-
-// 后续调用 sharding.insert / query / queryPage 等
-// 路由逻辑详见 libs/crud-sharding/ROUTING_LOGIC.md
-```
-
-### ShardingCrudPro 完整使用指南
-
-#### 获取实例
-
-```typescript
-import { ShardingType } from '@/libs/crud-sharding';
-
-// 方式1：通过 CurdProService 获取（推荐）
-const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.MONTH,      // 按月分表
-  baseTable: 't_order',          // 基础表名
-  timeColumn: 'created_at',      // 时间字段（时间分表必填）
-  autoCreateTable: true,         // 自动创建分表（可选）
-  countCache: {                  // COUNT 查询缓存（可选）
-    ttlSeconds: 300,
-    maxSize: 1000,
-  },
-});
-
-// 方式2：通过 CurdMixService 获取
-const sharding = curdMixService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.HASH,
-  baseTable: 't_user',
-  shardingColumn: 'user_id',     // 分表字段（HASH/RANGE 必填）
-  tableCount: 16,                // 分表数量
-});
-```
-
-#### 支持的分表策略
-
-| 策略 | 枚举值 | 说明 | 示例 |
-|------|--------|------|------|
-| 按年分表 | `ShardingType.YEAR` | 按年份分表 | `order_2024`, `order_2025` |
-| 按月分表 | `ShardingType.MONTH` | 按月份分表 | `order_202401`, `order_202402` |
-| 按日分表 | `ShardingType.DAY` | 按日期分表 | `order_20240101` |
-| 按范围分表 | `ShardingType.RANGE` | 按数值范围分表 | `user_0` ~ `user_99` |
-| 按哈希分表 | `ShardingType.HASH` | 按哈希值分表 | `order_01` ~ `order_16` |
-| 自定义分表 | `ShardingType.CUSTOM` | 自定义路由规则 | 自定义函数决定 |
-
-#### 配置选项详解
-
-```typescript
-interface IShardingConfig {
-  type: ShardingType;                    // 分表类型（必填）
-  baseTable: string;                     // 基础表名（必填）
-  timeColumn?: string;                   // 时间字段（时间分表必填）
-  shardingColumn?: string;               // 分表字段（HASH/RANGE 必填）
-  tableCount?: number;                   // 分表数量（HASH/RANGE，默认 16/10）
-  autoCreateTable?: boolean;             // 自动创建分表（默认 false）
-  tableCreateOptions?: {                 // 分表创建选项
-    copyIndexes?: boolean;               // 是否复制索引（默认 false）
-    ignoreForeignKeys?: boolean;         // 是否忽略外键（默认 true）
-    tableOptions?: string;               // 表选项（如 MySQL 引擎配置）
-  };
-  countCache?: {                         // COUNT 查询缓存（时间分表）
-    ttlSeconds?: number;                 // 缓存有效期（默认 300 秒）
-    maxSize?: number;                    // 最大缓存条目（默认 1000）
-  };
-  recentTableCount?: number;             // 查询无时间范围时返回最近 N 个分表
-  customRouter?: (ctx) => string | string[];  // 自定义路由函数（CUSTOM 类型）
-  suffixFormatter?: (suffix) => string;  // 自定义后缀格式化
-}
-```
-
-#### API 一览
-
-| 方法 | 返回类型 | 说明 |
-|------|----------|------|
-| `setBaseCfg(cfg)` | `this` | 设置基础配置，支持链式调用 |
-| `getConfig()` | `IShardingConfig` | 获取分表配置 |
-| `insert(reqJson)` | `ExecuteContext` | 插入单条数据（自动路由） |
-| `batchInsert(reqJson)` | `IShardingSmartBatchInsertResult` | 批量插入（支持跨分表） |
-| `update(reqJson)` | `ExecuteContext` | 更新数据 |
-| `delete(reqJson)` | `ExecuteContext` | 删除数据 |
-| `insertOrUpdate(reqJson)` | `ExecuteContext` | 插入或更新 |
-| `insertOnDuplicateUpdate(reqJson)` | `ExecuteContext` | 原生 upsert |
-| `queryOne(reqJson)` | `any \| null` | 查询单条 |
-| `query(reqJson)` | `any[]` | 列表查询（多表自动合并） |
-| `queryPage(reqJson)` | `IShardingPageQueryResult` | 分页查询（跨分表分页） |
-| `queryCount(reqJson)` | `number` | 统计总数 |
-| `isExist(reqJson)` | `boolean` | 存在性判断 |
-
-#### 使用示例
-
-##### 1. 时间分表（按月）
-
-```typescript
-const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.MONTH,
-  baseTable: 't_order',
-  timeColumn: 'created_at',
-  autoCreateTable: true,
-});
-
-// 插入数据 - 自动路由到对应月份分表
-await sharding.insert({
-  data: {
-    order_id: 'ORD001',
-    amount: 100,
-    created_at: '2024-03-15 10:00:00',  // -> 路由到 t_order_202403
-  },
-});
-
-// 批量插入 - 自动分组并行插入
-const result = await sharding.batchInsert({
-  data: [
-    { order_id: '001', amount: 100, created_at: '2024-01-15' },  // -> t_order_202401
-    { order_id: '002', amount: 200, created_at: '2024-01-20' },  // -> t_order_202401
-    { order_id: '003', amount: 150, created_at: '2024-02-10' },  // -> t_order_202402
-    { order_id: '004', amount: 300, created_at: '2024-03-05' },  // -> t_order_202403
-  ],
-});
-console.log(result.totalAffected);    // 4
-console.log(result.tableCount);       // 3（涉及3个分表）
-console.log(result.tableResults);     // 各分表插入详情
-
-// 更新数据 - 需要包含时间字段用于路由
-await sharding.update({
-  condition: { order_id: 'ORD001', created_at: '2024-03-15' },
-  data: { amount: 200 },
-});
-
-// 列表查询 - 自动合并多表结果（必须传 orderBy）
-const orders = await sharding.query({
-  condition: {
-    status: 'paid',
-    created_at: { $gte: '2024-01-01', $lte: '2024-03-31' },  // 时间范围自动路由
-  },
-  orderBy: 'created_at DESC',  // 必须传，且格式固定为 timeColumn DESC
-});
-
-// 分页查询 - 跨分表分页自动处理
-const page = await sharding.queryPage({
-  condition: { status: 'paid' },
-  pageNo: 1,
-  pageSize: 10,
-  orderBy: 'created_at DESC',  // 必须传
-});
-console.log(page.rows, page.total_count);
-
-// 查询总数 - 并行查询各分表后汇总
-const count = await sharding.queryCount({
-  condition: { status: 'paid' },
-});
-
-// 查询单条 - 按顺序查询各分表，找到即返回
-const order = await sharding.queryOne({
-  condition: { order_id: 'ORD001' },
-});
-
-// 存在性判断 - 并行查询各分表
-const exists = await sharding.isExist({
-  condition: { order_id: 'ORD001' },
-});
-```
-
-##### 2. 哈希分表
-
-```typescript
-const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.HASH,
-  baseTable: 't_user',
-  shardingColumn: 'user_id',
-  tableCount: 16,
-  autoCreateTable: true,
-});
-
-// 插入 - 根据 user_id 哈希值路由
-await sharding.insert({
-  data: { user_id: 10001, name: '张三' },  // -> 路由到 t_user_05
-});
-
-// 查询 - 需要提供分表字段用于路由
-const user = await sharding.queryOne({
-  condition: { user_id: 10001 },  // 根据 user_id 确定分表
-});
-
-// 查询多表 - 不带分表字段时可能查询多个分表
-const users = await sharding.query({
-  condition: { status: 'active' },  // 无 user_id，可能扫描多个分表
-  orderBy: 'created_at DESC',
-});
-```
-
-##### 3. 范围分表
-
-```typescript
-const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.RANGE,
-  baseTable: 't_log',
-  shardingColumn: 'log_id',
-  tableCount: 100,
-});
-
-// log_id 1-9999 路由到 t_log_0，10000-19999 路由到 t_log_1，以此类推
-await sharding.insert({
-  data: { log_id: 15000, content: 'xxx' },  // -> 路由到 t_log_1
-});
-```
-
-##### 4. 自定义分表规则
-
-```typescript
-const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
-  type: ShardingType.CUSTOM,
-  baseTable: 't_data',
-  customRouter: (context) => {
-    const { data, condition, config } = context;
-    // 自定义路由逻辑
-    const tenantId = data?.tenant_id || condition?.tenant_id;
-    return `t_data_${tenantId}`;  // 按租户ID分表
-  },
-});
-```
-
-##### 5. 链式配置
-
-```typescript
-const sharding = curdProService
-  .getShardingCrud('mydb', SqlDbType.mysql, {
-    type: ShardingType.MONTH,
-    baseTable: 't_order',
-    timeColumn: 'created_at',
-  })
-  .setBaseCfg({
-    enableStandardUpdateCfg: true,
-    enableSoftDelete: true,
-  });
-```
-
-#### 重要约束
-
-**时间分表查询约束：**
-- 列表查询 (`query`) 和分页查询 (`queryPage`) 必须传 `orderBy` 参数
-- `orderBy` 格式必须固定为 `'{timeColumn} DESC'`，如 `'created_at DESC'`
-- 这是分表合并算法的要求：按时间倒序的表顺序 + 倒序排序的数据 = 无需内存排序直接合并
-
-```typescript
-// 正确
-await sharding.query({
-  condition: { status: 'paid' },
-  orderBy: 'created_at DESC',  // 符合约束
-});
-
-// 错误 - 缺少 orderBy
-await sharding.query({
-  condition: { status: 'paid' },
-});
-
-// 错误 - 排序方向错误
-await sharding.query({
-  condition: { status: 'paid' },
-  orderBy: 'created_at ASC',
-});
-```
-
-**写操作路由约束：**
-- `insert` 必须在 `data` 中包含 `timeColumn`（时间分表）或 `shardingColumn`（HASH/RANGE）
-- `update`/`delete` 必须在 `condition` 中包含分表字段，或提供足够的时间范围确定单一分表
-
-```typescript
-// 正确 - 数据包含时间字段
-await sharding.insert({
-  data: { order_id: '001', created_at: '2024-03-15' },
-});
-
-// 错误 - 缺少时间字段，无法路由
-await sharding.insert({
-  data: { order_id: '001' },  // 报错：无法确定目标分表
-});
-```
-
-## CurdMixService
-
-### 关联数据填充执行流程
-
-1. `CurdMixService.executeCrudByCfg()` → 调用 `prepare()` 注册 5 个处理器
-2. CrudPro 执行 SQL，返回 `ExecuteContext`
-3. `MyContextFunc.afterExecuteSQLList()` 遍历所有处理器：
-   - `handleExecuteContextPrepare()` — 预加载关联数据
-   - `handleExecuteContext()` — 遍历每行，按 `sourceColumn` 取值查关联数据，通过 `targetColumns` 映射写回
-
-### linkColumnRelationDatas
-
-独立于 CRUD 操作，直接对已有数据行执行关联填充。适用于数据来自缓存、外部接口或其他非 CurdMixService 渠道，但仍需要字典翻译、用户信息等关联数据的场景。
-
-> ⚠️ 该方法会**原地修改** `rows` 数组中的对象，不会返回新数组。
-
-#### 方法签名
-
-```typescript
-linkColumnRelationDatas(rows: any[], param: ILinkColumnRelationParam): Promise<void>
-```
-
-#### 参数接口
-
-```typescript
-interface ILinkColumnRelationParam {
-  columnsRelations: ColumnRelation[];  // 关联配置数组
-}
-```
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `rows` | `any[]` | 待填充的数据行数组；为空或非数组时直接返回 |
-| `param.columnsRelations` | `ColumnRelation[]` | 关联规则配置，与 CRUD 配置中的 `columnsRelation` 格式一致 |
-
-#### 基础用法
-
-```typescript
-// 场景：从缓存或其他来源获取了数据行，仍需要关联填充
-const rows = [...]; // 任意来源的数据行
-
-await curdMixService.linkColumnRelationDatas(rows, {
-  columnsRelations: [
-    {
-      relatedType: 'dict',
-      relatedCode: 'SexEnum',
-      sourceColumn: 'sex',
-      targetColumns: [{ from: 'label', to: 'sex_text' }],
-    },
-  ],
-});
-// rows 中的每行会原地追加 sex_text 字段
-```
-
-#### 多关联类型组合
-
-```typescript
-const rows = await redisCache.get('order_list');
-
-await curdMixService.linkColumnRelationDatas(rows, {
-  columnsRelations: [
-    // 字典翻译
-    {
-      relatedType: 'dict',
-      relatedCode: 'OrderStatus',
-      sourceColumn: 'status',
-      targetColumns: [
-        { from: 'label', to: 'status_text' },
-        { from: 'color', to: 'status_color' },
-      ],
-    },
-    // 系统配置枚举
-    {
-      relatedType: 'sysCfgEnum',
-      relatedCode: 'PayMethod',
-      sourceColumn: 'pay_method',
-      targetColumns: [
-        { from: 'label', to: 'pay_method_info.label' },
-        { from: 'style', to: 'pay_method_info.style' },
-      ],
-    },
-    // 用户信息填充
-    {
-      relatedType: 'accountBasic',
-      sourceColumn: 'created_by',
-      targetColumns: [],  // 空 = 使用默认映射
-    },
-    // 工作台信息
-    {
-      relatedType: 'workbenchBasic',
-      sourceColumn: 'workbench_code',
-      targetColumns: [
-        { from: 'workbench_domain', to: 'workbench_info.workbench_domain' },
-        { from: 'workbench_name', to: 'workbench_info.workbench_name' },
-      ],
-    },
-  ],
-});
-```
-
-#### 与 CrudProQuick 配合使用
-
-```typescript
-const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_order');
-
-// 先用 CrudProQuick 获取原始数据（不带关联）
-const rows = await quick.getList({
-  condition: { status: 'paid' },
-});
-
-// 再用 linkColumnRelationDatas 补充关联数据
-await curdMixService.linkColumnRelationDatas(rows, {
-  columnsRelations: [
-    {
-      relatedType: 'dict',
-      relatedCode: 'OrderStatus',
-      sourceColumn: 'status',
-      targetColumns: [{ from: 'label', to: 'status_text' }],
-    },
-    {
-      relatedType: 'accountBasic',
-      sourceColumn: 'created_by',
-      targetColumns: [],
-    },
-  ],
-});
-```
-
-> **提示**：如果 CRUD 操作本身就需要关联填充，建议直接使用 `CurdMixService.executeCrudByCfg()` 配置 `columnsRelation`，一步完成查询和填充。`linkColumnRelationDatas` 适用于数据已存在的二次填充场景。
-
-## ColumnRelation 配置
-
-```typescript
-interface ColumnRelation {
-  relatedType: any;            // 关联类型
-  relatedCode?: string;        // 关联编码（dict/sysCfgEnum/linkToCustom 时必填）
-  sourceColumn: string;        // 从结果行中取值的字段名
-  targetColumns?: CopyAttr[];  // 映射规则，[{ from: 'label', to: 'sex_text' }]
-}
-
-interface CopyAttr {
-  from: string;  // 关联数据中的字段名，支持 '*' 表示整体赋值
-  to: string;    // 写入结果行的目标路径（支持嵌套，如 'user_info.name'）
-}
-```
-
-## 关联类型
-
-### dict — 数据字典
-
-从 `sys_data_dict_item` 表查询字典数据，按 `dict_code` + `value` 匹配。
-
-```typescript
-const cfgJson: IRequestCfgModel = {
-  method: 'user.list',
-  sqlTable: 'sys_user',
-  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY,
-  columnsRelation: [
-    {
-      relatedType: 'dict',
-      relatedCode: 'SexEnum',        // 字典编码
-      sourceColumn: 'sex',           // 结果行中的 sex 字段值作为字典 value
-      targetColumns: [
-        { from: 'label', to: 'sex_text' },  // 字典 label → sex_text
-      ],
-    },
-    {
-      relatedType: 'dict',
-      relatedCode: 'StatusEnum',
-      sourceColumn: 'status',
-      targetColumns: [
-        { from: 'label', to: 'status_text' },
-        { from: 'color', to: 'status_color' },
-      ],
-    },
-  ],
-};
-```
-
-### sysCfgEnum — 系统配置枚举
-
-从 `sys_configs` 表查询配置，按 `code` 列作为唯一键匹配。
-
-```typescript
-columnsRelation: [
-  {
-    relatedType: 'sysCfgEnum',
-    relatedCode: 'OrderStatus',
-    sourceColumn: 'order_status',
-    targetColumns: [
-      { from: 'label', to: 'order_status_info.label' },
-      { from: 'style', to: 'order_status_info.style' },
-    ],
-  },
-]
-```
-
-### accountBasic — 用户账号信息
-
-根据 `sourceColumn` 中的用户 ID，查询用户基本信息（昵称、头像等）。
-
-```typescript
-columnsRelation: [
-  {
-    relatedType: 'accountBasic',
-    sourceColumn: 'created_by',      // 用户 ID 字段
-    targetColumns: [],               // 空 = 使用默认映射
-  },
-]
-```
-
-**用户 ID 适配**：支持数字、字符串、JSON 数组等多种 ID 格式，自动通过 `toFatcmsUserAccountId` 转换。
-
-### workbenchBasic — 工作台站点信息
-
-根据 `workbench_code` 查询站点信息。
-
-```typescript
-columnsRelation: [
-  {
-    relatedType: 'workbenchBasic',
-    sourceColumn: 'workbench_code',
-    targetColumns: [
-      { from: 'workbench_domain', to: 'workbench_info.workbench_domain' },
-      { from: 'workbench_name', to: 'workbench_info.workbench_name' },
-    ],
-  },
-]
-```
-
-支持数组字段（如 `workbench_code_array`），目标路径使用 `$ARRAY_INDEX` 占位符：
-
-```typescript
-columnsRelation: [
-  {
-    relatedType: 'workbenchBasic',
-    sourceColumn: 'workbench_code_array',
-    targetColumns: [
-      { from: 'workbench_domain', to: 'workbench_info_array[$ARRAY_INDEX].workbench_domain' },
-      { from: 'workbench_name', to: 'workbench_info_array[$ARRAY_INDEX].workbench_name' },
-    ],
-  },
-]
-```
-
-### linkToCustom — 自定义表关联
-
-关联任意自定义表，需在 `sys_configs` 中配置关联规则。
-
-```typescript
-columnsRelation: [
-  {
-    relatedType: 'linkToCustom',
-    relatedCode: 'categoryLinkConfig',  // 关联配置编码
-    sourceColumn: 'category_id',
-    targetColumns: [],                  // 使用配置中的默认映射
-  },
-]
-```
-
-## 标准表字段
-
-推荐业务表包含以下标准字段，以配合服务层的自动填充和软删除机制：
-
-**常用字段（6 个）**：`deleted_at`、`deleted_by`、`created_by`、`created_at`、`modified_by`、`modified_at`
-
-**完整字段（12 个）**：在常用字段基础上增加 `created_account_type`、`created_avatar`、`created_nickname`、`modified_account_type`、`modified_avatar`、`modified_nickname`
-
-类型定义位于 `@/models/StandardColumns`：
-
-```typescript
-import { StandardDataModel, FullStandardDataModel, NotDeletedCondition } from '@/models/StandardColumns';
-
-// 定义业务表数据类型
-interface OrderEntity {
-  id: number;
-  order_no: string;
-  amount: number;
-}
-type Order = StandardDataModel<OrderEntity>;       // 自动包含 6 个标准字段
-type OrderFull = FullStandardDataModel<OrderEntity>; // 自动包含 12 个标准字段
-
-// 未删除查询条件
-const condition = { ...NotDeletedCondition, status: 1 };
-// 等价于 { deleted_at: 0, status: 1 }
-```