midway-fatcms 0.0.7 → 0.0.8

package/.qoder/skills/midway-fatcms/05-configuration.md

@@ -0,0 +1,290 @@
+# 配置模型与返回类型
+
+## 请求参数结构
+
+```typescript
+interface IRequestModel {
+  method?: string;
+  condition?: IRequestCondition;   // 查询条件（支持比较操作符、逻辑组合）
+  data?: Record<string, any> | any[];  // 单条或批量插入/更新的数据
+  pageNo?: number;
+  pageSize?: number;
+  orderBy?: string | IOrderByItem[];
+  columns?: string | string[];
+}
+```
+
+### 条件类型定义
+
+```typescript
+type IBasicType = boolean | string | number;
+
+// 比较操作符条件
+interface ICompareCondition {
+  $ne?: IBasicType;                    // 不等于
+  $lt?: IBasicType;                    // 小于
+  $lte?: IBasicType;                   // 小于或等于
+  $gt?: IBasicType;                    // 大于
+  $gte?: IBasicType;                   // 大于或等于
+  $in?: IBasicType[];                  // 在集合中
+  $nin?: IBasicType[];                 // 不在集合中
+  $range?: [number, number];           // BETWEEN ... AND
+  $like?: string;                      // 前缀匹配 A%
+  $notLike?: string;                   // 非前缀匹配
+  $likeInclude?: string;               // 包含匹配 %A%
+  $notLikeInclude?: string;            // 不包含匹配
+  $match?: string;                     // MySQL 全文索引
+  $matchBool?: string | boolean;       // MySQL 布尔全文索引
+  $null?: boolean;                     // IS NULL（仅 true 生效）
+  $notNull?: boolean;                  // IS NOT NULL（仅 true 生效）
+  $jsonArrayContains?: string;         // JSON 数组包含
+}
+
+// 逻辑操作符条件
+interface ILogicalCondition {
+  $or?: IRequestCondition[];           // 逻辑或
+  $and?: IRequestCondition[];          // 逻辑与
+}
+
+// 查询条件类型（字段值匹配 + 比较操作符 + 逻辑组合）
+interface IRequestCondition extends Record<string, IBasicType | ICompareCondition | ILogicalCondition | IRequestCondition[] | undefined>, ILogicalCondition {
+}
+```
+
+## SQL 操作类型
+
+```typescript
+enum KeysOfSimpleSQL {
+  SIMPLE_QUERY           // SELECT 带条件
+  SIMPLE_QUERY_ONE       // SELECT ... LIMIT 1
+  SIMPLE_QUERY_PAGE      // 分页查询
+  SIMPLE_QUERY_COUNT     // COUNT 查询
+  SIMPLE_QUERY_EXIST     // EXISTS 查询
+  SIMPLE_INSERT          // 插入单条
+  SIMPLE_BATCH_INSERT    // 批量插入
+  SIMPLE_UPDATE          // 更新
+  SIMPLE_DELETE          // 删除
+  SIMPLE_INSERT_OR_UPDATE  // 先查再插/更
+  SIMPLE_INSERT_ON_DUPLICATE_UPDATE  // 原生 upsert
+}
+```
+
+## 返回类型
+
+```typescript
+// 写操作
+interface CrudWriteResult {
+  affectedRows: number;
+  insertId?: string | number;
+}
+
+// 单条查询
+interface CrudQueryOneResult<T> {
+  row: T | null;
+  found: boolean;
+}
+
+// 列表查询
+interface CrudQueryListResult<T> {
+  rows: T[];
+  count: number;
+}
+
+// 分页查询
+interface CrudQueryPageResult<T> {
+  rows: T[];
+  totalCount: number;
+  count: number;
+}
+
+// 存在性
+interface CrudExistResult {
+  exists: boolean;
+}
+
+// Upsert
+interface CrudUpsertResult {
+  insertAffected?: { affectedRows: number; insertId?: number };
+  updateAffected?: { affectedRows: number };
+  isExist: boolean;
+}
+```
+
+## 关联配置（columnsRelation）
+
+`columnsRelation` 用于配置关联数据填充，实现字典翻译、用户信息填充等功能。
+
+```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 - 数据字典
+
+从 `sys_data_dict_item` 表查询字典数据，按 `dict_code` + `value` 匹配。
+
+```typescript
+{
+  relatedType: 'dict',
+  relatedCode: 'OrderStatusEnum',  // 字典编码
+  sourceColumn: 'status',           // 结果行中的 status 字段值作为字典 value
+  targetColumns: [
+    { from: 'label', to: 'status_text' },    // 字典 label → status_text
+    { from: 'color', to: 'status_color' },  // 字典 color → status_color
+  ],
+}
+```
+
+#### sysCfgEnum - 系统配置枚举
+
+从 `sys_configs` 表查询配置，按 `code` 列作为唯一键匹配。
+
+```typescript
+{
+  relatedType: 'sysCfgEnum',
+  relatedCode: 'OrderStatus',      // 配置 code
+  sourceColumn: 'order_status',
+  targetColumns: [
+    { from: 'label', to: 'order_status_info.label' },
+    { from: 'style', to: 'order_status_info.style' },
+  ],
+}
+```
+
+#### accountBasic - 用户账号信息
+
+根据 `sourceColumn` 中的用户 ID，查询用户基本信息（昵称、头像等）。
+
+```typescript
+{
+  relatedType: 'accountBasic',
+  sourceColumn: 'created_by',      // 用户 ID 字段
+  targetColumns: [],               // 空数组使用默认映射
+}
+// 自动填充字段：created_by_nickname, created_by_avatar, created_by_account_type
+```
+
+**用户 ID 适配**：支持数字、字符串、JSON 数组等多种 ID 格式，自动转换。
+
+#### workbenchBasic - 工作台站点信息
+
+根据 `workbench_code` 查询站点信息。
+
+```typescript
+{
+  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
+{
+  relatedType: 'workbenchBasic',
+  sourceColumn: 'workbench_code_array',
+  targetColumns: [
+    { from: 'workbench_domain', to: 'workbench_info_array[$ARRAY_INDEX].workbench_domain' },
+  ],
+}
+```
+
+#### linkToCustom - 自定义表关联
+
+关联任意自定义表，需在 `sys_configs` 中配置关联规则。
+
+```typescript
+{
+  relatedType: 'linkToCustom',
+  relatedCode: 'categoryLinkConfig',  // 关联配置编码
+  sourceColumn: 'category_id',
+  targetColumns: [],                    // 使用配置中的默认映射
+}
+```
+
+### 使用示例
+
+```typescript
+const cfgModel = {
+  method: 'order.list',
+  sqlTable: 't_order',
+  sqlSimpleName: 'SIMPLE_QUERY_PAGE',
+  columnsRelation: [
+    // 订单状态字典翻译
+    {
+      relatedType: 'dict',
+      relatedCode: 'OrderStatusEnum',
+      sourceColumn: 'status',
+      targetColumns: [{ from: 'label', to: 'status_text' }],
+    },
+    // 创建者信息填充
+    {
+      relatedType: 'accountBasic',
+      sourceColumn: 'created_by',
+      targetColumns: [],  // 使用默认映射
+    },
+    // 所属站点信息
+    {
+      relatedType: 'workbenchBasic',
+      sourceColumn: 'workbench_code',
+      targetColumns: [
+        { from: 'workbench_name', to: 'site_name' },
+      ],
+    },
+  ],
+};
+
+const ctx = await this.curdMixService.executeCrudByCfg(
+  { condition: {}, pageNo: 1, pageSize: 10, orderBy: 'created_at DESC' },
+  cfgModel
+);
+
+const { rows } = ctx.getResModelForQueryPage();
+// rows 自动包含 status_text、created_by_nickname、site_name 等字段
+```
+
+### 独立关联填充
+
+对已有数据（如从缓存获取的）执行关联填充：
+
+```typescript
+await this.curdMixService.linkColumnRelationDatas(rows, {
+  columnsRelations: [
+    {
+      relatedType: 'dict',
+      relatedCode: 'OrderStatusEnum',
+      sourceColumn: 'status',
+      targetColumns: [{ from: 'label', to: 'status_text' }],
+    },
+  ],
+});
+// rows 中的每行自动追加 status_text 字段
+```
+
+## 标准字段
+
+```typescript
+interface StandardDataModel {
+  deleted_at?: number;
+  deleted_by?: string;
+  created_by?: string;
+  created_at?: number;
+  modified_by?: string;
+  modified_at?: number;
+}
+```

package/.qoder/skills/midway-fatcms/06-builtin-functions.md

@@ -0,0 +1,241 @@
+# 内置函数参考
+
+CrudPro 的 `IFuncCfgModel` 支持 `functionName` 方式调用内置函数。内置函数由四个工具类注册：`DateTimeUtils`、`CompareUtils`、`MixinUtils`、`TypeUtils`。
+
+## 调用方式
+
+### 无参调用
+
+```typescript
+'data.created_at': { functionName: 'getCurrentTimeString' }
+```
+
+### 带参调用
+
+```typescript
+'data.order_date': { 
+  functionName: 'getCurrentDateFormat', 
+  functionParams: ['YYYYMMDD'] 
+}
+```
+
+`functionParams` 支持嵌套 `IFuncCfgModel`：
+
+```typescript
+{
+  functionName: 'eq',
+  functionParams: [
+    { contextAsBool: 'res.is_exist' },
+    { constBool: false }
+  ]
+}
+```
+
+---
+
+## DateTimeUtils — 日期时间
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `getCurrentTimeStampMs` | 无 | `number` | 当前时间戳（毫秒） |
+| `getCurrentTimeStampSecond` | 无 | `number` | 当前时间戳（秒） |
+| `getCurrentTimeString` | 无 | `string` | `YYYY-MM-DD HH:mm:ss` |
+| `getCurrentDateFormat` | `format: string` | `string` | 按格式返回当前时间 |
+| `getYesterdayDateFormat` | `format: string` | `string` | 按格式返回昨天时间 |
+
+```typescript
+updateCfg: {
+  'data.created_at': { functionName: 'getCurrentTimeString' },
+  'data.created_ts': { functionName: 'getCurrentTimeStampMs' },
+  'data.order_date': { 
+    functionName: 'getCurrentDateFormat', 
+    functionParams: ['YYYYMMDD'] 
+  },
+  'data.yesterday': { 
+    functionName: 'getYesterdayDateFormat', 
+    functionParams: ['YYYY-MM-DD'] 
+  },
+}
+```
+
+---
+
+## CompareUtils — 比较运算
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `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
+// executeWhen：仅当 is_exist 为 false 时执行
+executeWhen: {
+  functionName: 'eq',
+  functionParams: [{ contextAsBool: 'res.is_exist' }, { constBool: false }]
+}
+
+// validate：确保数量大于 0
+validate: {
+  functionName: 'gt',
+  functionParams: [{ context: '$current' }, { constNumber: 0 }],
+  message: '数量必须大于0'
+}
+```
+
+---
+
+## MixinUtils — 通用工具
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `isNil` | `obj` | `boolean` | 是否为 null/undefined |
+| `isNotNil` | `obj` | `boolean` | 不为 null 且不为 undefined |
+| `isEmpty` | `obj` | `boolean` | 是否为空（null/空字符串/空数组/空对象） |
+| `isNotEmpty` | `obj` | `boolean` | 是否非空 |
+| `equals` | `a, b` | `boolean` | 严格相等（`===`） |
+| `equalsIgnoreCase` | `str1, str2` | `boolean` | 忽略大小写比较 |
+| `startsWith` | `str1, str2` | `boolean` | 字符串前缀判断 |
+| `selectNotEmpty` | `a, b` | `any` | 返回第一个非空值 |
+| `hasAny` | `a[], b[]` | `boolean` | A 是否包含 B 中任意元素 |
+| `parseValueByType` | `value, type` | `any` | 按类型转换（string/number/boolean/array/JSONObject） |
+| `sleepMs` | `ms` | `Promise` | 延时等待 |
+| `uuid` | 无 | `string` | UUID v4 |
+| `generateSnowflakeId` | `machineId?` | `string` | 雪花ID（64位整数字符串） |
+
+```typescript
+updateCfg: {
+  // UUID v4
+  'data.id': { functionName: 'uuid' },
+
+  // 雪花ID（时间有序）
+  'data.order_id': { functionName: 'generateSnowflakeId' },
+
+  // 雪花ID + 机器ID（多实例部署）
+  'data.trace_id': { 
+    functionName: 'generateSnowflakeId', 
+    functionParams: [1]  // 0-1023
+  },
+}
+```
+
+> **雪花ID machineId 优先级**：函数参数 > 环境变量 `SNOWFLAKE_MACHINE_ID` > `process.pid` 低10位
+
+---
+
+## TypeUtils — 类型判断
+
+| 函数名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `isBasicType` | `value` | `boolean` | 基础类型（boolean/string/number/null） |
+| `isBoolean` | `value` | `boolean` | 布尔值 |
+| `isString` | `value` | `boolean` | 字符串 |
+| `isInteger` | `value` | `boolean` | 整数 |
+| `isNumber` | `value` | `boolean` | 数字 |
+| `isNumeric` | `value` | `boolean` | 数字或可转换数字的字符串 |
+| `isValidName` | `value` | `boolean` | 合法命名（字母开头，字母/数字/下划线） |
+| `isChinesePhone` | `value` | `boolean` | 中文手机号 |
+| `isEmailStrValid` | `value` | `boolean` | 合法邮箱地址 |
+| `pickNumber` | `s: string` | `number | null` | 从字符串提取数字 |
+
+---
+
+## 上下文取值
+
+```typescript
+updateCfg: {
+  'data.created_by': { context: 'visitor.accountId' },
+  'data.created_nickname': { context: 'visitor.nickName' },
+  'data.created_avatar': { context: 'visitor.avatar' },
+  'data.workbench_code': { context: 'workbenchCode' },
+}
+```
+
+**常用上下文路径：**
+
+| 路径 | 说明 |
+|------|------|
+| `visitor.accountId` | 当前用户ID |
+| `visitor.nickName` | 当前用户昵称 |
+| `visitor.avatar` | 当前用户头像 |
+| `visitor.accountType` | 用户类型 |
+| `workbenchCode` | 当前工作台编码 |
+
+---
+
+## 校验器
+
+| 校验器 | 说明 |
+|--------|------|
+| `required` | 必填 |
+| `string` | 字符串 |
+| `number` | 数字 |
+| `integer` | 整数 |
+| `boolean` | 布尔值 |
+| `email` | 邮箱格式 |
+| `phone:cn` | 中国手机号 |
+| `array` | 数组 |
+| `array:string` | 字符串数组 |
+| `array:number` | 数字数组 |
+| `length:1,50` | 长度范围 |
+| `scale:[1,3]` | 数值范围 |
+
+```typescript
+validateCfg: {
+  'data.name': ['required', 'string', 'length:2,50'],
+  'data.email': ['required', 'email'],
+  'data.age': ['integer', 'scale:[0,150]'],
+  'data.phone': ['phone:cn'],
+}
+```
+
+---
+
+## 自定义函数扩展
+
+继承 `BaseExecuteContextFunc`，覆写 `getFunctionMap()`：
+
+```typescript
+import { BaseExecuteContextFunc } from 'midway-fatcms';
+
+class MyContextFunc extends BaseExecuteContextFunc {
+  getFunctionMap(): any {
+    return {
+      // 无参函数
+      generateOrderNo: (prefix: string) => {
+        return prefix + Date.now().toString(36).toUpperCase();
+      },
+
+      // 带参函数
+      formatAmount: (amount: number, currency: string) => {
+        return currency + ' ' + amount.toFixed(2);
+      },
+
+      // 访问上下文（必须用普通 function，不能用箭头函数）
+      getVisitorName: function(this: any) {
+        return this.reqModel?.visitor?.nickName || 'anonymous';
+      },
+    };
+  }
+}
+```
+
+**使用自定义函数：**
+
+```typescript
+const cfgJson = {
+  method: 'order.create',
+  sqlSimpleName: 'SIMPLE_INSERT',
+  updateCfg: {
+    'data.order_no': { 
+      functionName: 'generateOrderNo', 
+      functionParams: ['ORD'] 
+    },
+  },
+};
+```
+
+> **注意**：自定义函数优先级高于内置函数，可覆盖同名内置函数。