midway-fatcms 0.0.5 → 0.0.7

package/.qoder/skills/midway-fatcms-crud/reference.md

@@ -0,0 +1,568 @@
+# midway-fatcms 完整参考手册
+
+## CrudProQuick API 参考
+
+### 查询类方法
+
+| 方法 | 参数 | 返回类型 | 说明 |
+|------|------|----------|------|
+| `getList(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `any[]` | 列表查询 |
+| `getListPage(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `ResModelPageQuery` | 分页查询（含 total_count） |
+| `getUniqueOne(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `any \| null` | 期望唯一一条，0条返回null，多条报错 |
+| `getOne(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `any` | 获取第一条（已废弃，建议用 getUniqueOne） |
+| `isExist(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `boolean` | 存在性判断（比 COUNT 高效） |
+| `getTotalCount(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `number` | 统计总数 |
+
+### 写入类方法
+
+| 方法 | 参数 | 返回类型 | 说明 |
+|------|------|----------|------|
+| `insertObject(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `ResModelAffected` | 插入单条 |
+| `batchInsert(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `ResModelAffected` | 批量插入 |
+| `updateObject(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `ResModelAffected` | 更新 |
+| `insertOrUpdate(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `ResModelStandard` | 先查询存在性，再决定插入或更新 |
+| `insertOnDuplicate(reqJson, uniqueColumn?, sqlTable?)` | `IRequestModel`, `string[]?`, `string?` | `ResModelAffected` | 原生 upsert（MySQL: ON DUPLICATE KEY UPDATE） |
+| `deleteObject(reqJson, sqlTable?)` | `IRequestModel`, `string?` | `ResModelAffected` | 删除（受软删除配置影响） |
+
+### 原生 SQL 方法
+
+| 方法 | 参数 | 返回类型 | 说明 |
+|------|------|----------|------|
+| `executeSQL(sql, args?)` | `string`, `any[]?` | `any` | 框架封装的 SQL 执行（带参数绑定） |
+| `executeNativeSQL<T>(sql, args?)` | `string`, `any[]?` | `T` | 原生 SQL 执行，不做额外处理 |
+
+## 请求参数结构 (IRequestModel)
+
+```typescript
+interface IRequestModel {
+  method?: string;                      // Config 方法名
+  condition?: Record<string, any>;      // 查询/更新/删除条件
+  data?: Record<string, any> | Record<string, any>[];  // 插入/更新数据
+  pageNo?: number;                      // 页码（从1开始）
+  pageSize?: number;                    // 每页条数
+  orderBy?: string | OrderByItem[];    // 排序规则
+  columns?: string | string[];          // 指定返回列
+  limit?: number;
+  offset?: number;
+}
+```
+
+## 条件操作符详解
+
+### 比较操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$gt` | 大于 | `{ age: { $gt: 18 } }` |
+| `$gte` | 大于等于 | `{ score: { $gte: 60 } }` |
+| `$lt` | 小于 | `{ price: { $lt: 100 } }` |
+| `$lte` | 小于等于 | `{ count: { $lte: 10 } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'deleted' } }` |
+| `$eq` | 等于（显式） | `{ status: { $eq: 'active' } }` |
+
+### 范围操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$in` | IN 查询 | `{ id: { $in: [1, 2, 3] } }` |
+| `$nin` | NOT IN | `{ type: { $nin: ['test'] } }` |
+| `$between` / `$range` | BETWEEN | `{ amount: { $between: [100, 500] } }` |
+
+### 模糊查询
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$like` | 前缀匹配 LIKE 'A%' | `{ name: { $like: '张' } }` |
+| `$notLike` | 非前缀匹配 | `{ name: { $notLike: 'test' } }` |
+| `$likeInclude` | 包含匹配 LIKE '%A%' | `{ name: { $likeInclude: '张三' } }` |
+| `$notLikeInclude` | 不包含匹配 | `{ name: { $notLikeInclude: 'test' } }` |
+
+### NULL 判断
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$isNull` / `$null` | IS NULL | `{ deleted_at: { $isNull: true } }` |
+| `$isNotNull` / `$notNull` | IS NOT NULL | `{ phone: { $isNotNull: true } }` |
+
+### 全文搜索
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$match` | MySQL 全文搜索 | `{ content: { $match: 'keyword' } }` |
+| `$matchBool` | MySQL 布尔全文搜索 | `{ 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
+const condition = {
+  status: 'active',
+  age: { $gte: 18, $lte: 60 },
+  name: { $likeInclude: '张' },
+  $or: [
+    { department: { $in: ['tech', 'product'] } },
+    { level: { $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+',
+]
+```
+
+## ShardingCrudPro 分表配置
+
+### 分表类型
+
+| 类型 | 枚举值 | 说明 | 示例 |
+|------|--------|------|------|
+| 按年 | `ShardingType.YEAR` | 按年份分表 | `order_2024` |
+| 按月 | `ShardingType.MONTH` | 按月份分表 | `order_202401` |
+| 按日 | `ShardingType.DAY` | 按日期分表 | `order_20240101` |
+| 范围 | `ShardingType.RANGE` | 按数值范围 | `user_0` ~ `user_99` |
+| 哈希 | `ShardingType.HASH` | 按哈希值 | `order_01` ~ `order_16` |
+| 自定义 | `ShardingType.CUSTOM` | 自定义规则 | 自定义函数决定 |
+
+### IShardingConfig 配置项
+
+```typescript
+interface IShardingConfig {
+  type: ShardingType;                    // 分表类型（必填）
+  baseTable: string;                     // 基础表名（必填）
+
+  // 时间分表
+  timeColumn?: string;                   // 时间字段（时间分表必填）
+  recentTableCount?: number;             // 无时间范围时查询最近N个分表
+  autoCreateTable?: boolean;             // 自动创建分表（默认 false）
+  tableCreateOptions?: IShardingTableCreateOptions;
+
+  // 范围/哈希分表
+  shardingColumn?: string;               // 分表字段（HASH/RANGE必填）
+  tableCount?: number;                   // 分表数量（默认 RANGE=10, HASH=16）
+
+  // COUNT 缓存（仅时间分表）
+  countCache?: {
+    ttlSeconds?: number;                 // 缓存有效期（默认300秒）
+    maxSize?: number;                    // 最大缓存条目（默认1000）
+  };
+
+  // 自定义配置
+  customRouter?: (ctx) => string | string[];  // 自定义路由函数
+  suffixFormatter?: (suffix) => string;      // 自定义后缀格式化
+}
+
+interface IShardingTableCreateOptions {
+  copyIndexes?: boolean;                 // 复制原表索引
+  tableOptions?: string;                 // 表选项（如 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4'）
+}
+
+interface IShardingSmartBatchInsertResult {
+  totalAffected: number;
+  tableResults: Array<{ table: string; affected: number; rowCount: number }>;
+  tableCount: number;
+  success: boolean;
+  errors: Array<{ table: string; error: Error }>;
+}
+```
+
+### ShardingCrudPro API
+
+| 方法 | 参数 | 返回类型 | 说明 |
+|------|------|----------|------|
+| `setBaseCfg(cfg)` | `IRequestCfgModel2` | `this` | 设置基础配置 |
+| `insert(reqJson)` | `IRequestModel` | `ExecuteContext` | 插入单条 |
+| `batchInsert(reqJson)` | `IRequestModel` | `IShardingSmartBatchInsertResult` | 批量插入 |
+| `update(reqJson)` | `IRequestModel` | `ExecuteContext` | 更新 |
+| `delete(reqJson)` | `IRequestModel` | `ExecuteContext` | 删除 |
+| `insertOrUpdate(reqJson)` | `IRequestModel` | `ExecuteContext` | 插入或更新 |
+| `insertOnDuplicateUpdate(reqJson)` | `IRequestModel` | `ExecuteContext` | 原生 upsert |
+| `queryOne(reqJson)` | `IRequestModel` | `any \| null` | 查询单条 |
+| `query(reqJson)` | `IRequestModel` | `any[]` | 列表查询 |
+| `queryPage(reqJson)` | `IRequestModel` | `IShardingPageQueryResult` | 分页查询 |
+| `queryCount(reqJson)` | `IRequestModel` | `number` | 统计总数 |
+| `isExist(reqJson)` | `IRequestModel` | `boolean` | 存在性判断 |
+
+## 配置模型 (IRequestCfgModel)
+
+```typescript
+interface IRequestCfgModel {
+  method?: string;                       // 方法标识
+  sqlTable?: string;                     // 目标表名
+  sqlSchema?: string;                    // Schema（可选）
+  sqlDatabase?: string;                  // 数据库名（用于选择连接）
+  sqlDbType?: SqlDbType;                 // 'mysql' | 'postgres' | 'sqlserver'
+  maxLimit?: number;                     // 最大返回行数
+  columns?: string | string[];           // 选择列
+  columnsRelation?: ColumnRelation[];    // 数据关联配置
+  sqlSimpleName?: KeysOfSimpleSQL;       // 简单 SQL 模式
+  sqlCfgList?: ISqlCfgModel[];           // 自定义 SQL 列表（高优先级）
+  uniqueColumn?: string[];               // 用于 insertOnDuplicate
+  updateCfg?: Record<string, IFuncCfgModel>;    // 自动字段更新
+  allowCfg?: Record<string, string[]>;          // 字段白名单
+  rejectCfg?: Record<string, string[]>;          // 字段黑名单
+  validateCfg?: Record<string, IValidatorCfgItem[]>;  // 校验规则
+  authType?: KeysOfAuthType;             // 权限类型
+  authConfig?: string | string[];        // 权限配置
+  transactionEnable?: boolean;           // 启用事务
+  transactionIsolation?: number;         // 事务隔离级别
+}
+
+interface IRequestCfgModel2 extends IRequestCfgModel {
+  enableStandardUpdateCfg?: boolean | string[];       // 默认 true
+  enableStandardUpdateCfgCondition?: boolean | string[];  // 默认 false
+  enableSoftDelete?: boolean;            // 软删除支持
+}
+```
+
+### KeysOfSimpleSQL（SQL 操作类型）
+
+| 值 | 说明 |
+|----|------|
+| `SIMPLE_QUERY` | SELECT 带条件，不分页 |
+| `SIMPLE_QUERY_ONE` | SELECT ... LIMIT 1 |
+| `SIMPLE_QUERY_PAGE` | SELECT 带分页（pageNo + pageSize）|
+| `SIMPLE_QUERY_COUNT` | SELECT COUNT(*) |
+| `SIMPLE_QUERY_EXIST` | SELECT EXISTS |
+| `SIMPLE_INSERT` | INSERT 单行 |
+| `SIMPLE_BATCH_INSERT` | INSERT 多行 |
+| `SIMPLE_UPDATE` | UPDATE 带条件 |
+| `SIMPLE_DELETE` | DELETE 带条件 |
+| `SIMPLE_INSERT_OR_UPDATE` | 查询后插入或更新（2条 SQL）|
+| `SIMPLE_INSERT_ON_DUPLICATE_UPDATE` | 原生 upsert（1条 SQL）|
+
+### SqlDbType
+
+```typescript
+enum SqlDbType {
+  mysql = 'mysql',
+  postgres = 'postgres',
+  sqlserver = 'sqlserver',
+}
+```
+
+### Auth Types（权限类型）
+
+```typescript
+enum KeysOfAuthType {
+  free = 'free',                    // 无需权限
+  login = 'login',                // 需要登录
+  byRoleCode = 'byRoleCode',      // 角色权限
+  byFuncCode = 'byFuncCode',      // 功能码权限
+}
+```
+
+### Validators（校验器）
+
+| 校验器 | 说明 |
+|--------|------|
+| `required` | 必填 |
+| `string` | 必须是字符串 |
+| `number` | 必须是数字 |
+| `integer` | 必须是整数 |
+| `boolean` | 必须是布尔值 |
+| `email` | 邮箱格式 |
+| `array` | 必须是数组 |
+| `array:string` | 字符串数组 |
+| `array:number` | 数字数组 |
+| `phone:cn` | 中国手机号（11位）|
+| `moment:FORMAT` | 日期/时间格式验证 |
+| `scale:[1,3]` | 数值范围检查 |
+| `length:1,5` | 字符串长度范围 |
+| `regexp:[a-zA-Z]` | 正则匹配 |
+| `enum:1,2,3` | 枚举值检查 |
+
+## 关联数据填充 (columnsRelation)
+
+### ColumnRelation 结构
+
+```typescript
+interface ColumnRelation {
+  relatedType: 'dict' | 'sysCfgEnum' | 'accountBasic' | 'workbenchBasic' | 'linkToCustom';
+  relatedCode?: string;        // 关联编码（dict/sysCfgEnum/linkToCustom 时必填）
+  sourceColumn: string;        // 从结果行中取值的字段名
+  targetColumns?: CopyAttr[];  // 映射规则
+}
+
+interface CopyAttr {
+  from: string;  // 关联数据中的字段名，支持 '*' 表示整体赋值
+  to: string;    // 写入结果行的目标路径（支持嵌套，如 'user_info.name'）
+}
+```
+
+### 关联类型详解
+
+#### dict - 数据字典
+
+```typescript
+{
+  relatedType: 'dict',
+  relatedCode: 'SexEnum',        // 字典编码
+  sourceColumn: 'sex',           // 结果行中的 sex 字段值作为字典 value
+  targetColumns: [
+    { from: 'label', to: 'sex_text' },
+    { from: 'color', to: 'sex_color' },
+  ],
+}
+```
+
+#### sysCfgEnum - 系统配置枚举
+
+```typescript
+{
+  relatedType: 'sysCfgEnum',
+  relatedCode: 'OrderStatus',
+  sourceColumn: 'order_status',
+  targetColumns: [
+    { from: 'label', to: 'order_status_info.label' },
+    { from: 'style', to: 'order_status_info.style' },
+  ],
+}
+```
+
+#### accountBasic - 用户账号信息
+
+```typescript
+{
+  relatedType: 'accountBasic',
+  sourceColumn: 'created_by',    // 用户 ID 字段
+  targetColumns: [],             // 空数组使用默认映射
+}
+// 自动填充字段：created_by_nickname, created_by_avatar, created_by_account_type
+```
+
+#### workbenchBasic - 工作台站点信息
+
+```typescript
+{
+  relatedType: 'workbenchBasic',
+  sourceColumn: 'workbench_code',
+  targetColumns: [
+    { from: 'workbench_domain', to: 'workbench_info.workbench_domain' },
+    { from: 'workbench_name', to: 'workbench_info.workbench_name' },
+  ],
+}
+```
+
+#### linkToCustom - 自定义表关联
+
+```typescript
+{
+  relatedType: 'linkToCustom',
+  relatedCode: 'categoryLinkConfig',  // 关联配置编码（在 sys_configs 中配置）
+  sourceColumn: 'category_id',
+  targetColumns: [],                    // 使用配置中的默认映射
+}
+```
+
+## 自定义 SQL 配置 (ISqlCfgModel)
+
+```typescript
+interface ISqlCfgModel {
+  resName?: string;              // 结果名
+  resPicker?: string;            // 结果选择表达式
+  originSql?: string;            // 带特殊占位符的 SQL
+  executeSql?: string;           // 可执行 SQL（用 ? 作为参数）
+  executeSqlArgs?: any[];        // SQL 参数
+  isNativeSQL?: boolean;         // 跳过框架处理
+  crudType?: string;
+  validate?: IFuncCfgModel;      // 执行前校验
+  executeWhen?: IFuncCfgModel;   // 条件执行
+}
+```
+
+### SQL 占位符 (originSql)
+
+| 占位符 | 说明 |
+|--------|------|
+| `@@columns` | 展开为列列表 |
+| `@@table` | 展开为表名 |
+| `@@offsetLimit` | 展开为 LIMIT/OFFSET |
+| `@@orderBys` | 展开为 ORDER BY 子句 |
+| `@@asWhere:fieldName` | 从字段展开为 WHERE 子句 |
+| `@@asUpdate:fieldName` | 从字段展开为 SET 子句 |
+| `@@asInsertKeys:fieldName` | 展开为 INSERT 列名 |
+| `@@asInsertValues:fieldName` | 展开为 INSERT 值 |
+| `@@asBatchInsertKeys:fieldName` | 批量 INSERT 列 |
+| `@@asBatchInsertValues:fieldName` | 批量 INSERT 值 |
+| `@@data.attrName` | 从 data 获取单个值 |
+| `@@condition.attrName` | 从 condition 获取单个值 |
+| `@@pickResAsNumber:expression` | 选择结果为数字 |
+| `@@pickResAsString:expression` | 选择结果为字符串 |
+| `@@function:funcName` | 执行函数 |
+
+## 标准表字段
+
+推荐业务表包含以下标准字段：
+
+**常用字段（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`
+
+### TypeScript 类型定义
+
+```typescript
+import { StandardDataModel, FullStandardDataModel, NotDeletedCondition } from 'midway-fatcms';
+
+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 }
+```
+
+## 响应模型
+
+```typescript
+interface ResModelAffected {
+  insertId?: string | number;
+  affectedRows: number;
+}
+
+interface ResModelPageQuery {
+  rows: Record<string, any>[];
+  total_count: number;
+}
+
+interface ResModelStandard {
+  row?: Record<string, any>;
+  rows?: Record<string, any>[];
+  total_count?: number;
+  is_exist?: boolean;
+  affected?: ResModelAffected;
+  insert_affected?: ResModelAffected;
+  update_affected?: ResModelAffected;
+}
+```
+
+## 内置函数 (IFuncCfgModel)
+
+在 `updateCfg` 中可用的内置函数：
+
+### 日期时间函数
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `getCurrentTimeStampMs` | 无 | `number` | 当前时间戳（毫秒）|
+| `getCurrentTimeStampSecond` | 无 | `number` | 当前时间戳（秒）|
+| `getCurrentTimeString` | 无 | `string` | 当前时间 `YYYY-MM-DD HH:mm:ss` |
+| `getCurrentDateFormat` | `format: string` | `string` | 按指定格式返回当前时间 |
+| `getYesterdayDateFormat` | `format: string` | `string` | 按指定格式返回昨天时间 |
+
+### 通用工具函数
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `uuid` | 无 | `string` | 生成 UUID v4 |
+| `generateSnowflakeId` | `machineId?: number` | `string` | 生成雪花ID |
+| `isNil` | `obj: any` | `boolean` | 是否为 null/undefined |
+| `isNotNil` | `obj: any` | `boolean` | 不为 null 且不为 undefined |
+| `isEmpty` | `obj: any` | `boolean` | 是否为空 |
+| `isNotEmpty` | `obj: any` | `boolean` | 是否非空 |
+
+### 比较函数
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `eq` | `a, b` | `boolean` | 相等比较 |
+| `ne` | `a, b` | `boolean` | 不相等 |
+| `gt` | `a, b` | `boolean` | 大于 |
+| `gte` | `a, b` | `boolean` | 大于等于 |
+| `lt` | `a, b` | `boolean` | 小于 |
+| `lte` | `a, b` | `boolean` | 小于等于 |
+
+### 使用示例
+
+```typescript
+updateCfg: {
+  // 设置当前时间
+  'data.created_at': { functionName: 'getCurrentTimeString' },
+
+  // 设置时间戳
+  'data.created_ts': { functionName: 'getCurrentTimeStampMs' },
+
+  // 生成 UUID
+  'data.id': { functionName: 'uuid' },
+
+  // 生成雪花ID
+  'data.order_id': { functionName: 'generateSnowflakeId' },
+
+  // 带参数的函数
+  'data.order_date': { functionName: 'getCurrentDateFormat', functionParams: ['YYYYMMDD'] },
+}
+```
+
+## CurdMixService vs CurdProService 方法映射
+
+| CurdMixService | CurdProService | 说明 |
+|----------------|----------------|------|
+| `executeCrudByCfg(req, cfg)` | `executeCrudByCfg(req, cfg)` | Mix 增加数据关联填充 |
+| `executeCrud(req)` | `executeCrud(req)` | Mix 增加数据关联填充 |
+| `getBbUtil(db, type, table)` | `getQuickCrud(db, type, table)` | 功能相同，Mix 自动准备处理器 |
+| `executeSQL(sqlCfg)` | `executeSQL(sqlCfg)` | 直接 SQL 执行 |
+| `getCachedCfgByMethod(m)` | `getCachedCfgByMethod(m)` | 获取缓存配置 |
+| `getAllTableInfos(q, o)` | `getAllTableInfos(q, o)` | 列出数据库表 |
+| `linkColumnRelationDatas(r, p)` | *(不可用)* | 为已有数据填充关联数据 |
+
+## 错误码参考
+
+| 错误码 | 说明 |
+|--------|------|
+| `NO_AUTH` | 没有权限 |
+| `NOT_LOGIN` | 未登录 |
+| `CFG_NOT_FOUND` | 配置不存在 |
+| `VALIDATE_EXCEPTION` | 数据校验失败 |
+| `RUN_SQL_EXCEPTION_ER_DUP_ENTRY` | 数据重复 |
+| `RUN_SQL_EXCEPTION_ER_NO_SUCH_TABLE` | 表不存在 |
+| `RUN_FUNCTION_NOT_FOUND` | 函数未找到 |
+| `SHARDING_COLUMN_MISSING` | 缺少分表字段 |