midway-fatcms 0.0.4 → 0.0.6

package/dist/libs/crud-pro/README.md

@@ -0,0 +1,809 @@
+# CrudPro 使用指南
+
+CrudPro 是一个功能强大的 CRUD 操作库，支持多种数据库（MySQL、PostgreSQL、SQL Server），提供了配置化的 SQL 执行方式，包括简单 SQL 模式和自定义 SQL 模式。
+
+## 目录
+
+- [快速开始](#快速开始)
+- [核心概念](#核心概念)
+- [配置详解](#配置详解)
+- [使用示例](#使用示例)
+- [高级特性](#高级特性)
+- [API 参考](#api-参考)
+
+## 快速开始
+
+### 1. 基础初始化
+
+```typescript
+import { CrudPro } from './CrudPro';
+import { Transaction } from './models/Transaction';
+import { IConnectionPool } from './interfaces';
+
+// 创建 CrudPro 实例
+const crudPro = new CrudPro();
+
+// 设置事务管理器
+const transaction = new Transaction();
+crudPro.transaction = transaction;
+
+// 设置日志器
+const logger = {
+  info: (msg: any, ...args: any[]) => console.log('[INFO]', msg, ...args),
+  debug: (msg: any, ...args: any[]) => console.log('[DEBUG]', msg, ...args),
+  error: (msg: any, ...args: any[]) => console.error('[ERROR]', msg, ...args),
+  warn: (msg: any, ...args: any[]) => console.warn('[WARN]', msg, ...args),
+};
+crudPro.logger = logger;
+
+// 设置访问者信息（用于权限校验）
+const visitor = {
+  isLogin: true,
+  isSuperAdmin: false,
+  accountId: 'user123',
+  nickName: '张三',
+  roleCodes: ['admin', 'editor'],
+  functionCodes: ['user:create', 'user:read'],
+};
+crudPro.visitor = visitor;
+```
+
+### 2. 执行第一个查询
+
+```typescript
+import { IRequestModel, IRequestCfgModel } from './interfaces';
+
+// 请求参数
+const reqJson: IRequestModel = {
+  method: 'user.getList', // 非必须，executeCrudByCfg 会使用 cfgJson.method
+  columns: 'id,name,email',
+  condition: { status: 1 },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at-',
+};
+
+// 配置（可以从数据库读取）
+const cfgJson: IRequestCfgModel = {
+  method: 'user.getList',
+  sqlTable: 'sys_user',
+  sqlDatabase: 'default_db',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_PAGE, // 使用简单分页查询
+};
+
+// 执行
+const result = await crudPro.executeCrudByCfg(reqJson, cfgJson);
+console.log(result.getResRows()); // 获取查询结果
+```
+
+## 核心概念
+
+### 执行流程
+
+```
+1. 接收请求 (RequestModel)
+   ↓
+2. 加载配置 (RequestCfgModel)
+   ↓
+3. 字段过滤 (filterDataByTableMeta)      ← 根据表结构过滤不存在的字段
+   ↓
+4. 数据类型转换 (convertDataTypeByTableMeta) ← 根据表结构字段类型自动转换
+   ↓
+5. 数据校验 (validateByAllow/rejectCfg/validateCfg)
+   ↓
+6. 权限校验 (validateByAuthCfg)
+   ↓
+7. 默认值设置 (updateByCfg)
+   ↓
+8. 生成 SQL (generateSQLList)
+   ↓
+9. 执行 SQL (executeSQLList)
+   ↓
+10. 返回结果 (ExecuteContext)
+```
+
+### 简单 SQL 类型 (sqlSimpleName)
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| `SIMPLE_QUERY` | 简单查询 | 列表查询 |
+| `SIMPLE_QUERY_ONE` | 查询单条 | 详情查询 |
+| `SIMPLE_QUERY_PAGE` | 分页查询 | 分页列表 |
+| `SIMPLE_QUERY_COUNT` | 查询数量 | 统计总数 |
+| `SIMPLE_QUERY_EXIST` | 判断存在 | 存在性检查 |
+| `SIMPLE_UPDATE` | 更新操作 | 修改数据 |
+| `SIMPLE_INSERT` | 插入操作 | 新增单条 |
+| `SIMPLE_BATCH_INSERT` | 批量插入 | 批量新增 |
+| `SIMPLE_DELETE` | 删除操作 | 删除数据 |
+| `SIMPLE_INSERT_ON_DUPLICATE_UPDATE` | 插入或更新 | MySQL 特有 |
+| `SIMPLE_INSERT_OR_UPDATE` | 插入或更新 | PostgreSQL/SQL Server |
+| `CUSTOM` | 自定义 SQL | 复杂查询 |
+
+### 查询条件操作符
+
+支持 MongoDB 风格的查询条件：
+
+```typescript
+const condition = {
+  // 基础等于
+  status: 1,
+
+  // 比较操作
+  age: { $gt: 18 },           // 大于
+  score: { $gte: 60 },        // 大于等于
+  price: { $lt: 100 },        // 小于
+  count: { $lte: 10 },        // 小于等于
+  type: { $ne: 'deleted' },   // 不等于
+
+  // 范围查询
+  id: { $in: [1, 2, 3] },           // IN
+  code: { $nin: ['a', 'b'] },       // NOT IN
+  amount: { $range: [100, 200] },   // BETWEEN
+
+  // 模糊查询
+  name: { $like: '张' },            // 前缀匹配 (张%)
+  title: { $likeInclude: '文章' },   // 包含匹配 (%文章%)
+
+  // NULL 判断
+  deleted_at: { $null: true },      // IS NULL
+  updated_at: { $notNull: true },   // IS NOT NULL
+
+  // 逻辑组合
+  $or: [
+    { name: { $like: '张' } },
+    { name: { $like: '李' } },
+  ],
+};
+```
+
+## 配置详解
+
+### 请求配置 (IRequestCfgModel)
+
+```typescript
+interface IRequestCfgModel {
+  method: string;                    // 方法标识（必填）
+  sqlTable?: string;                 // 表名
+  sqlSchema?: string;                // Schema（PostgreSQL/SQL Server）
+  sqlDatabase?: string;              // 数据库名
+  sqlDbType?: 'mysql' | 'postgres' | 'sqlserver';
+
+  // 执行模式（二选一，sqlCfgList 优先级更高）
+  sqlSimpleName?: KeysOfSimpleSQL;   // 简单 SQL 类型
+  sqlCfgList?: ISqlCfgModel[];       // 自定义 SQL 列表
+
+  // 事务控制
+  transactionEnable?: boolean;       // 是否开启事务
+  transactionIsolation?: number;     // 事务隔离级别
+
+  // 数据操作配置
+  uniqueColumn?: string[];         // 唯一键列（用于 UPSERT）
+  updateCfg?: Record<string, IFuncCfgModel>;    // 字段默认值配置
+  allowCfg?: Record<string, string[]>;          // 允许修改的字段
+  rejectCfg?: Record<string, string[]>;         // 拒绝修改的字段
+  validateCfg?: Record<string, IValidatorCfgItem[]>; // 字段校验规则
+
+  // 权限配置
+  authType?: 'free' | 'login' | 'byRoleCode' | 'byFuncCode';
+  authConfig?: string | string[];    // 角色码或功能点码
+}
+```
+
+### 自定义 SQL 配置 (ISqlCfgModel)
+
+```typescript
+interface ISqlCfgModel {
+  resName?: string;                  // 结果名称
+  resPicker?: string;                // 结果提取器
+
+  // 表配置
+  sqlTable?: string;
+  sqlSchema?: string;
+  sqlDatabase?: string;
+  sqlDbType?: SqlDbType;
+  columns?: string | string[];
+  columnsRelation?: ColumnRelation[];
+
+  // SQL 配置
+  originSql?: string;                // 原始 SQL（含占位符）
+  executeSql?: string;              // 可执行 SQL
+  executeSqlArgs?: any[];           // SQL 参数
+  isNativeSQL?: boolean;            // 是否原生 SQL
+
+  // 执行控制
+  validate?: IFuncCfgModel;         // 前置校验
+  executeWhen?: IFuncCfgModel;      // 执行条件
+}
+```
+
+### SQL 占位符
+
+```sql
+-- 表名占位符
+SELECT * FROM @@table WHERE id = 1
+
+-- 列名占位符
+SELECT @@columns FROM @@table
+
+-- 条件占位符
+SELECT * FROM @@table WHERE @@asWhere:condition
+
+-- 更新占位符
+UPDATE @@table SET @@asUpdate:data WHERE id = @@condition.id
+
+-- 插入占位符
+INSERT INTO @@table (@@asInsertKeys:data) VALUES (@@asInsertValues:data)
+
+-- 批量插入
+INSERT INTO @@table (@@asBatchInsertKeys:data) VALUES @@asBatchInsertValues:data
+
+-- 分页和排序
+SELECT * FROM @@table @@asWhere:condition @@orderBys @@offsetLimit
+
+-- 从请求中取单个值
+SELECT * FROM @@table WHERE id = @@data.id
+SELECT * FROM @@table WHERE status = @@condition.status
+
+-- 从结果中提取值（多 SQL 场景）
+SELECT * FROM @@table WHERE id = @@pickResAsNumber:rows[0].id
+SELECT * FROM @@table WHERE name = @@pickResAsString:row.name
+
+```
+
+## @@function 说明
+
+@@function 不是执行数据库的内置函数，而是执行CrudProExecuteFuncService提供的内置函数。完整的内置函数列表和用法请参考 [README_FUNC.md](./README_FUNC.md)。
+
+
+## 使用示例
+
+### 示例 1：简单分页查询
+
+```typescript
+// 配置
+const cfgJson: IRequestCfgModel = {
+  method: 'article.list',
+  sqlTable: 'article',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_PAGE,
+};
+
+// 请求
+const reqJson: IRequestModel = {
+  method: 'article.list', // 非必须，executeCrudByCfg 会使用 cfgJson.method
+  columns: 'id,title,content,author_id,created_at',
+  condition: {
+    status: 1,
+    category_id: { $in: [1, 2, 3] },
+    created_at: { $gte: '2024-01-01' },
+  },
+  pageNo: 1,
+  pageSize: 20,
+  orderBy: 'created_at-',
+};
+
+const ctx = await crudPro.executeCrudByCfg(reqJson, cfgJson);
+const { rows, total_count } = ctx.getResModelForQueryPage();
+```
+
+### 示例 2：单条数据插入
+
+```typescript
+// 配置：带默认值和字段白名单
+const cfgJson: IRequestCfgModel = {
+  method: 'user.create', // 非必须，此处仅用于打印日志或调试跟踪记录
+  sqlTable: 'sys_user',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT,
+  sqlDatabase: 'default_db',
+  allowCfg: {
+    data: ['name', 'email', 'phone', 'status'], // 只允许这些字段
+  },
+  updateCfg: {
+    'data.created_at': { functionName: 'getCurrentTimeString' },    // 设置创建时间
+    'data.created_by': { context: 'visitor.accountId' }, // 设置创建人
+  },
+  validateCfg: {
+    'data.name': ['required', 'string', 'length:2,50'],
+    'data.email': ['required', 'email'],
+    'data.phone': ['phone:cn'],
+  },
+};
+
+// 请求
+const reqJson: IRequestModel = {
+  method: 'user.create', // 非必须，executeCrudByCfg 会使用 cfgJson.method
+  data: {
+    name: '张三',
+    email: 'zhangsan@example.com',
+    phone: '13800138000',
+    status: 1,
+  },
+};
+
+const ctx = await crudPro.executeCrudByCfg(reqJson, cfgJson);
+console.log('插入结果:', ctx.getResModel().affected);
+```
+
+### 示例 3：批量插入
+
+```typescript
+const cfgJson: IRequestCfgModel = {
+  method: 'log.batchCreate',
+  sqlTable: 'operation_log',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_BATCH_INSERT,
+};
+
+const reqJson: IRequestModel = {
+  method: 'log.batchCreate', // 非必须，executeCrudByCfg 会使用 cfgJson.method
+  data: [
+    { action: 'login', user_id: '1', created_at: new Date() },
+    { action: 'logout', user_id: '1', created_at: new Date() },
+    { action: 'login', user_id: '2', created_at: new Date() },
+  ],
+};
+
+const ctx = await crudPro.executeCrudByCfg(reqJson, cfgJson);
+```
+
+### 示例 4：带事务的多 SQL 操作
+
+```typescript
+const cfgJson: IRequestCfgModel = {
+  method: 'order.create',
+  sqlTable: 'orders',
+  transactionEnable: true, // 开启事务
+  functionCfg: {
+    uuid: { functionName: 'uuid' }
+  },
+  sqlCfgList: [
+    // 第一步：插入订单
+    {
+      resName: 'order',
+      resPicker: KeysOfSqlResPicker.UPDATE_RESULT,
+      sqlTable: 'orders',
+      originSql: `INSERT INTO @@table (order_no, user_id, amount, status)
+                  VALUES (@@function:uuid(), @@data.user_id, @@data.amount, 0)`,
+    },
+    // 第二步：插入订单明细
+    {
+      resName: 'items',
+      sqlTable: 'order_items',
+      resPicker: null, // INSERT、UPDATE语句自动使用：KeysOfSqlResPicker.UPDATE_RESULT
+      originSql: `INSERT INTO @@table (order_id, product_id, quantity, price)
+                  VALUES (@@pickResAsString:order.insertId, @@data.product_id, @@data.quantity, @@data.price)`,
+    },
+    // 第三步：扣减库存
+    {
+      resName: 'stockResult',
+      sqlTable: 'product_stock',
+      originSql: `UPDATE @@table
+                  SET stock = stock - @@data.quantity
+                  WHERE product_id = @@data.product_id`,
+    },
+  ],
+};
+
+const reqJson: IRequestModel = {
+  method: 'order.create', // 非必须，executeCrudByCfg 会使用 cfgJson.method
+  data: {
+    user_id: 'user123',
+    amount: 199.99,
+    product_id: 'prod456',
+    quantity: 2,
+    price: 99.99,
+  },
+};
+
+const ctx = await crudPro.executeCrudByCfg(reqJson, cfgJson);
+console.log('订单创建成功:', ctx.getResModelItem('order'));
+```
+
+### 示例 5：权限控制
+
+```typescript
+// 登录即可访问
+const cfg1: IRequestCfgModel = {
+  method: 'user.profile',
+  sqlTable: 'sys_user',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_ONE,
+  authType: 'login',
+};
+
+// 需要特定角色
+const cfg2: IRequestCfgModel = {
+  method: 'admin.userList',
+  sqlTable: 'sys_user',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_PAGE,
+  authType: 'byRoleCode',
+  authConfig: 'admin', // 或 ['admin', 'super_admin']
+};
+
+// 需要特定功能点
+const cfg3: IRequestCfgModel = {
+  method: 'user.delete',
+  sqlTable: 'sys_user',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_DELETE,
+  authType: 'byFuncCode',
+  authConfig: 'user:delete',
+};
+```
+
+### 示例 6：直接执行 SQL
+
+```typescript
+import { ISqlCfgModel } from './interfaces';
+
+// 框架自动转换占位符（? → $1/$2 或 @fatcms_ms1/@fatcms_ms2）
+// 自动转换虽然方便，但当 SQL 中包含非参数绑定的问号（如正则表达式、字符串常量中的 ?）时会被误替换，
+// 此时需使用 isNativeSQL: true 并手写数据库原生占位符，详见示例 6b
+const sqlCfg: ISqlCfgModel = {
+  sqlTable: 'sys_user',
+  sqlDatabase: 'default_db',
+  executeSql: 'SELECT * FROM sys_user WHERE status = ? AND created_at > ?',
+  executeSqlArgs: [1, '2024-01-01'],
+};
+
+const result = await crudPro.executeSQL(sqlCfg);
+console.log(result);
+```
+
+### 示例 6b：原生 SQL 模式（isNativeSQL）
+
+当 `isNativeSQL: true` 时，框架不转换占位符，SQL 按原样发送到数据库驱动。
+
+```typescript
+// PostgreSQL：直接使用 $1、$2 占位符
+const pgSqlCfg: ISqlCfgModel = {
+  isNativeSQL: true,
+  sqlDatabase: 'default_db',
+  executeSql: 'SELECT * FROM sys_user WHERE status = $1 AND created_at > $2',
+  executeSqlArgs: [1, '2024-01-01'],
+};
+
+// SQL Server：直接使用 @param 占位符
+const mssqlSqlCfg: ISqlCfgModel = {
+  isNativeSQL: true,
+  sqlDatabase: 'default_db',
+  executeSql: 'SELECT * FROM sys_user WHERE status = @p1 AND created_at > @p2',
+  executeSqlArgs: [1, '2024-01-01'],
+};
+
+const result = await crudPro.executeSQL(pgSqlCfg);
+```
+
+### 示例 7：从数据库加载配置
+
+```typescript
+// 假设数据库中已存储了配置
+const reqJson: IRequestModel = {
+  method: 'article.list', // 通过 method 查找配置
+  condition: { status: 1 },
+  pageNo: 1,
+  pageSize: 10,
+};
+
+// 从数据库加载配置并执行（启用缓存）
+const ctx = await crudPro.executeCrud(reqJson, true);
+```
+
+## 高级特性
+
+### 1. 字段校验规则
+
+```typescript
+const validateCfg = {
+  'data.name': [
+    'required',                 // 必填
+    'string',                   // 字符串类型
+    'length:2,50',             // 长度 2-50
+    'name',                     // 必须是合法标识符
+  ],
+  'data.email': [
+    'required',
+    'email',                    // 邮箱格式
+  ],
+  'data.age': [
+    'integer',                  // 整数
+    'scale:[0,150]',           // 范围 0-150
+  ],
+  'data.status': [
+    'enum:0,1,2',              // 枚举值
+  ],
+  'data.phone': [
+    'phone:cn',                // 中国手机号
+  ],
+  'data.birthday': [
+    'moment:YYYY-MM-DD',       // 日期格式
+  ],
+  'data.remark': [
+    (value: string) => {        // 自定义校验函数
+      if (value && value.length > 500) {
+        throw { code: 'REMARK_TOO_LONG', message: '备注不能超过500字' };
+      }
+    },
+  ],
+};
+```
+
+### 2. 字段默认值设置（强制使用更新后的值，避免非法数据）
+
+```typescript
+const updateCfg = {
+  // 常量值
+  'data.status': { const: 1 },
+  'data.version': { constNumber: 1 },
+  'data.is_deleted': { constBool: false },
+
+  // 从上下文取值
+  'data.created_by': { context: 'visitor.accountId' },
+  'data.updated_by': { context: 'visitor.nickName' },
+
+  // 函数调用（uuid 为内置函数，generateOrderNo 需自定义注册， 参考README_FUNC.md）
+  'data.id': { functionName: 'uuid' },
+  'data.order_no': { functionName: 'generateOrderNo', functionParams: ['PRE'] },
+
+  // 表达式执行（使用 EJS 模板语法，上下文变量为 reqModel / resModel / currentValue）
+  'data.full_name': { executeExpressReturnString: '<%= reqModel.data.first_name %> <%= reqModel.data.last_name %>' },
+};
+```
+
+### 3. 关联查询（columnsRelation）
+
+> `columnsRelation` 的关联数据填充在应用服务层实现（`src/service/curd/`），不在 crud-pro 库内。
+> 完整文档请参考 [src/service/curd/README.md](../../service/curd/README.md)。
+
+
+### 4. 排序语法
+
+```typescript
+// 标准 SQL 格式
+orderBy: 'created_at DESC, amount ASC'
+
+// 简写格式（+ 升序，- 降序）
+orderBy: 'created_at-, amount+'
+orderBy: 'name, age-' // 默认升序
+
+// 数组格式（字符串 + 对象混合）
+orderBy: [
+  'order_id',
+  { fieldName: 'created_at', orderType: 'desc' },
+  'amount+',
+]
+```
+
+### 5. 分页方式
+
+```typescript
+// 方式 1：使用 pageNo/pageSize
+const req1: IRequestModel = {
+  pageNo: 2,      // 第 2 页
+  pageSize: 20,   // 每页 20 条
+};
+
+// 方式 2：使用 limit/offset
+const req2: IRequestModel = {
+  limit: 20,
+  offset: 20,     // 跳过 20 条
+};
+```
+
+### 6. 数据类型自动转换
+
+CrudPro 在执行 INSERT/UPDATE 操作前，会根据表结构字段类型自动转换数据格式，确保数据与数据库方言兼容。
+
+#### PostgreSQL ARRAY 类型
+
+PostgreSQL 的 ARRAY 字段要求使用数组字面量语法 `{"a","b","c"}`，而前端/Node.js 层通常传递 JSON 格式 `["a","b","c"]`。CrudPro 会自动完成转换：
+
+```typescript
+// 无需手动处理，CrudPro 自动转换
+const cfgJson: IRequestCfgModel = {
+  method: 'article.create',
+  sqlTable: 'article',
+  sqlDatabase: 'my_pg_db',
+  sqlDbType: SqlDbType.postgres,
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT,
+};
+
+// 前端传入 JSON 数组
+const reqJson: IRequestModel = {
+  data: {
+    title: '文章标题',
+    tags: ['技术', '前端', 'React'],      // JSON 数组 → 自动转为 {"技术","前端","React"}
+    categories: '[1,2,3]',                  // JSON 字符串 → 自动转为 {"1","2","3"}
+  },
+};
+
+// 执行后，tags 和 categories 字段会自动转为 PG 数组字面量格式
+```
+
+**支持的转换：**
+
+| 源数据格式 | 转换结果 | 说明 |
+|-----------|---------|------|
+| `["a","b","c"]` | `{"a","b","c"}` | 字符串数组：双引号包裹 |
+| `[1,2,3]` | `{1,2,3}` | 数字数组：不加引号 |
+| `[true,false]` | `{t,f}` | 布尔数组：转为 t/f |
+| `[1,null,3]` | `{1,NULL,3}` | 含 null：输出 NULL |
+| `[]` | `{}` | 空数组 |
+| `['he"llo']` | `{"he\"llo"}` | 特殊字符自动转义 |
+| `'[1,2,3]'` | `{1,2,3}` | JSON 字符串自动解析后转换 |
+
+**适用操作：**
+
+- `SIMPLE_INSERT`
+- `SIMPLE_UPDATE`
+- `SIMPLE_INSERT_ON_DUPLICATE_UPDATE`
+- `SIMPLE_INSERT_OR_UPDATE`
+- `SIMPLE_BATCH_INSERT`（批量插入时逐行转换）
+
+> 此功能仅对 PostgreSQL 生效，MySQL 和 SQL Server 不需要此转换。
+> 转换依赖 `getTableMeta()` 获取表字段类型信息，已复用缓存机制，不会产生额外查询开销。
+
+## API 参考
+
+### CrudPro 类
+
+#### 属性设置
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `transaction` | `Transaction` | 是 | 事务管理器 |
+| `logger` | `ILogger` | 是 | 日志器 |
+| `visitor` | `IVisitor` | 是 | 访问者信息 |
+| `contextFunc` | `IExecuteContextFunc` | 否 | 上下文函数扩展 |
+| `contextCfg` | `ICrudProCfg` | 否 | 全局配置 |
+
+#### 核心方法
+
+##### `executeCrudByCfg(reqJson, cfgJson)`
+
+核心执行方法，通过配置执行 CRUD 操作。
+
+```typescript
+public async executeCrudByCfg(
+  reqJson: IRequestModel,
+  cfgJson: IRequestCfgModel
+): Promise<ExecuteContext>
+```
+
+**参数：**
+- `reqJson`: 请求参数
+- `cfgJson`: 执行配置
+
+**返回：** `ExecuteContext` - 执行上下文，包含结果数据
+
+---
+
+##### `executeCrud(reqJson, isEnableCache)`
+
+从数据库加载配置并执行。
+
+```typescript
+public async executeCrud(
+  reqJson: IRequestModel,
+  isEnableCache: boolean
+): Promise<ExecuteContext>
+```
+
+**参数：**
+- `reqJson`: 请求参数（必须包含 `method`）
+- `isEnableCache`: 是否启用配置缓存
+
+---
+
+##### `executeSQL(sqlCfgModel)`
+
+直接执行 SQL。
+
+```typescript
+public async executeSQL(sqlCfgModel: ISqlCfgModel): Promise<any>
+```
+
+---
+
+##### `getCachedCfgByMethod(method, isEnableCache)`
+
+从缓存或数据库获取配置。
+
+```typescript
+public async getCachedCfgByMethod(
+  method: string,
+  isEnableCache: boolean
+): Promise<IRequestCfgModel>
+```
+
+---
+
+##### `getAllTableInfos(query, options?)`
+
+获取数据库中的所有表信息。
+
+```typescript
+public async getAllTableInfos(
+  query: ITableNamesQuery,
+  options?: ITableNamesOptions
+): Promise<ITableListResult>
+```
+
+### ExecuteContext 结果处理
+
+| 方法 | 说明 |
+|------|------|
+| `getResRows()` | 获取查询结果数组 |
+| `getOneObj()` | 获取单条结果（key 为 'row'） |
+| `getResModelItem(name)` | 获取指定名称的结果 |
+| `getResModelItemLodash(name)` | 支持路径获取（如 'rows[0].id'） |
+| `getResModelForQueryPage()` | 获取分页查询结果（含 total_count） |
+| `getResMessage()` | 获取执行消息 |
+
+### 全局配置 (ICrudProCfg)
+
+```typescript
+interface ICrudProCfg {
+  sysDatabaseName?: string;        // 默认：fatcms
+  sysDatabaseDbType?: SqlDbType;   // 默认：mysql
+  methodsTableName?: string;       // 默认：sys_crud_methods
+  methodsCacheTime?: number;       // 默认：60000 (毫秒)
+  dictItemTableName?: string;      // 默认：sys_data_dict_item
+  sysConfigTableName?: string;     // 默认：sys_configs
+  tableMetaCacheTime?: number;     // 表结构缓存时间
+}
+```
+
+## 异常处理
+
+CrudPro 使用 `CommonException` 抛出异常，可通过 `code` 字段识别错误类型：
+
+```typescript
+try {
+  await crudPro.executeCrudByCfg(reqJson, cfgJson);
+} catch (e) {
+  if (e instanceof CommonException) {
+    console.log('错误码:', e.code);
+    console.log('错误消息:', e.message);
+
+    // 常见错误码处理
+    switch (e.code) {
+      case 'NO_AUTH':
+        // 权限不足
+        break;
+      case 'NOT_LOGIN':
+        // 未登录
+        break;
+      case 'CFG_NOT_FOUND':
+        // 配置不存在
+        break;
+      case 'VALIDATE_EXCEPTION':
+        // 数据校验失败
+        break;
+      case 'RUN_SQL_EXCEPTION_ER_DUP_ENTRY':
+        // 数据重复
+        break;
+    }
+  }
+}
+```
+
+### 常见错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| `NO_AUTH` | 没有权限 |
+| `NOT_LOGIN` | 未登录 |
+| `CFG_NOT_FOUND` | 配置不存在 |
+| `CFG_METHOD_EMPTY` | 方法名为空 |
+| `VALIDATE_EXCEPTION` | 数据校验失败 |
+| `VALIDATE_ALLOW_ERR` | 包含不允许的字段 |
+| `VALIDATE_REJECT_ERR` | 包含被拒绝的字段 |
+| `RUN_SQL_EXCEPTION_ER_DUP_ENTRY` | 数据重复 |
+| `RUN_SQL_EXCEPTION_ER_NO_SUCH_TABLE` | 表不存在 |
+
+## 最佳实践
+
+1. **配置管理**：将常用配置存储到数据库，通过 `method` 动态加载
+2. **缓存策略**：生产环境启用配置缓存，减少数据库查询
+3. **权限控制**：合理使用 `authType` 和 `authConfig` 保护接口
+4. **字段过滤**：使用 `allowCfg` 和 `rejectCfg` 控制可操作的字段
+5. **数据校验**：配置 `validateCfg` 确保数据有效性
+6. **事务管理**：多 SQL 操作开启 `transactionEnable` 保证数据一致性
+7. **日志记录**：实现 `ILogger` 接口记录执行日志