midway-fatcms 0.0.7 → 0.0.8

package/src/libs/crud-pro/README_FUNC.md

@@ -1,193 +0,0 @@
-# CrudPro 内置函数参考
-
-CrudPro 的 `IFuncCfgModel` 支持 `functionName` 方式调用内置函数。内置函数由四个工具类注册：`DateTimeUtils`、`CompareUtils`、`MixinUtils`、`TypeUtils`。
-
-> 源码位置：`src/libs/crud-pro/services/CrudProServiceBase.ts` → `createBuildInExecuteFuncMap()`
-
-## 调用方式
-
-`functionName` 是 `IFuncCfgModel` 的属性之一，可在 `updateCfg`、`validateCfg`、`executeWhen`、`validate` 等配置中使用。
-
-### 无参调用
-
-```typescript
-'data.created_at': { functionName: 'getCurrentTimeString' }
-```
-
-### 带参调用
-
-```typescript
-'data.order_date': { functionName: 'getCurrentDateFormat', functionParams: ['YYYYMMDD'] }
-```
-
-`functionParams` 中的每个元素可以是基础类型（string / number / boolean），也可以嵌套 `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: any, b: any` | `boolean` | 相等比较（`==`，兼容类型转换） |
-| `ne` | `a: any, b: any` | `boolean` | 不相等 |
-| `gt` | `a: any, b: any` | `boolean` | 大于 |
-| `gte` | `a: any, b: any` | `boolean` | 大于等于 |
-| `lt` | `a: any, b: any` | `boolean` | 小于 |
-| `lte` | `a: any, b: any` | `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: any` | `boolean` | 是否为 null 或 undefined |
-| `isNotNil` | `obj: any` | `boolean` | 不为 null 且不为 undefined |
-| `isEmpty` | `obj: any` | `boolean` | 是否为空（null / undefined / 空字符串 / 空数组 / 空对象） |
-| `isNotEmpty` | `obj: any` | `boolean` | 是否非空 |
-| `equals` | `obj1: any, obj2: any` | `boolean` | 严格相等（`===`） |
-| `equalsIgnoreCase` | `str1: string, str2: string` | `boolean` | 忽略大小写比较字符串 |
-| `startsWith` | `str1: string, str2: string` | `boolean` | 字符串前缀判断 |
-| `isValidFieldName` | `s: string` | `boolean` | 合法字段名（字母开头，仅含字母/数字/下划线） |
-| `selectNotEmpty` | `a: any, b: any` | `any` | 返回第一个非空值 |
-| `hasAny` | `a: string[], b: string[]` | `boolean` | 集合 A 是否包含集合 B 中的任意元素 |
-| `parseValueByType` | `value: any, targetType: string` | `any` | 按类型转换值（string / number / boolean / array / JSONObject） |
-| `sleepMs` | `ms: number` | `Promise` | 延时等待 |
-| `uuid` | 无 | `string` | 生成 UUID v4（优先 `crypto.getRandomValues`，降级 `Math.random`） |
-| `generateSnowflakeId` | `machineId?: number` | `string` | 生成雪花ID（64位整数字符串） |
-
-**uuid 和雪花ID 示例：**
-
-```typescript
-updateCfg: {
-  // UUID v4：适合需要标准唯一标识的场景
-  'data.id': { functionName: 'uuid' },
-
-  // 雪花ID：适合需要趋势递增、时间有序的场景
-  'data.order_id': { functionName: 'generateSnowflakeId' },
-
-  // 雪花ID：指定机器ID（0-1023），多实例部署时区分
-  'data.trace_id': { functionName: 'generateSnowflakeId', functionParams: [1] },
-}
-```
-
-> **雪花ID machineId 获取优先级**：函数参数 > 环境变量 `SNOWFLAKE_MACHINE_ID` > `process.pid` 低10位。多实例部署时建议设置环境变量 `SNOWFLAKE_MACHINE_ID` 为 0-1023 的唯一值。
-
-## TypeUtils — 类型判断
-
-| 函数名 | 参数 | 返回值 | 说明 |
-|--------|------|--------|------|
-| `isBasicType` | `value: any` | `boolean` | 基础类型（boolean / string / number / null） |
-| `isBoolean` | `value: any` | `boolean` | 布尔值 |
-| `isString` | `value: any` | `boolean` | 字符串 |
-| `isInteger` | `value: any` | `boolean` | 整数 |
-| `isNumber` | `value: any` | `boolean` | 数字 |
-| `isNumeric` | `value: any` | `boolean` | 数字或可转换数字的字符串 |
-| `isValidName` | `value: any` | `boolean` | 合法命名（字母开头，字母/数字/下划线） |
-| `isChinesePhone` | `value: string` | `boolean` | 中文手机号 |
-| `isEmailStrValid` | `value: string` | `boolean` | 合法邮箱地址 |
-| `pickNumber` | `s: string` | `number \| null` | 从字符串中提取数字部分 |
-
-## 自定义函数扩展
-
-除内置函数外，可通过覆写 `IExecuteContextFunc.getFunctionMap()` 注册自定义函数。
-
-函数查找顺序：`getFunctionMap()` → `buildInExecuteFuncMap`（内置函数），自定义函数优先级更高，可覆盖内置函数。
-
-### 注册方式
-
-继承 `BaseExecuteContextFunc`，覆写 `getFunctionMap()` 方法返回函数映射表：
-
-```typescript
-import { BaseExecuteContextFunc } from './libs/crud-pro/models/ExecuteContextFunc';
-
-class MyContextFunc extends BaseExecuteContextFunc {
-
-  // 覆写此方法，返回自定义函数映射表
-  getFunctionMap(): any {
-    return {
-      // 无参函数
-      generateOrderNo: (prefix: string) => {
-        return prefix + Date.now().toString(36).toUpperCase();
-      },
-
-      // 带参函数：参数来自 functionParams 配置
-      formatAmount: (amount: number, currency: string) => {
-        return currency + ' ' + amount.toFixed(2);
-      },
-
-      // 可访问 FuncContext 的函数（通过 this 关键字）
-      getVisitorName: function(this: any) {
-        return this.reqModel?.visitor?.nickName || 'anonymous';
-      },
-    };
-  }
-}
-
-// 创建 CrudPro 实例时注入
-const crudPro = new CrudPro();
-crudPro.contextFunc = new MyContextFunc(/* 构造参数 */);
-```
-
-### 在配置中使用
-
-注册后即可在 `updateCfg`、`validateCfg`、`functionCfg` 等场景中通过 `functionName` 调用：
-
-```typescript
-const cfgJson: IRequestCfgModel = {
-  method: 'order.create',
-  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_INSERT,
-  updateCfg: {
-    'data.order_no': { functionName: 'generateOrderNo', functionParams: ['PRE'] },
-  },
-};
-```
-
-> **注意**：`functionParams` 中配置的参数会按顺序传入函数。如果函数需要访问 `FuncContext`（如 `reqModel`、`resModel`、`currentValue`），
-> 需使用普通 `function`（非箭头函数）并通过 `this` 访问，框架会以 `func.apply(funcContext, params)` 方式调用。
-
-> **注意**：`generateOrderNo` 等并非内置函数，需通过 `contextFunc` 扩展注册后才可使用，否则运行时抛出 `RUN_FUNCTION_NOT_FOUND` 异常。