@nocobase/flow-engine 2.0.0-alpha.4 → 2.0.0-alpha.41

package/src/flowEngine.ts

@@ -17,6 +17,9 @@ import { FlowSettings } from './flowSettings';
 import { ErrorFlowModel, FlowModel } from './models';
 import { ReactView } from './ReactView';
 import { APIResource, FlowResource, MultiRecordResource, SingleRecordResource, SQLResource } from './resources';
+import { Emitter } from './emitter';
+import ModelOperationScheduler from './scheduler/ModelOperationScheduler';
+import type { ScheduleOptions, ScheduledCancel } from './scheduler/ModelOperationScheduler';
 import type {
   ActionDefinition,
   ApplyFlowCacheEntry,
@@ -114,6 +117,15 @@ export class FlowEngine {
 
   private _resources = new Map<string, typeof FlowResource>();
 
+  /**
+   * 引擎事件总线（目前用于模型生命周期等事件）。
+   * ViewScopedFlowEngine 持有自己的实例，实现作用域隔离。
+   */
+  public emitter: Emitter = new Emitter();
+
+  /** 调度器：仅在 View 作用域引擎本地启用；根/Block 作用域默认不持有 */
+  private _modelOperationScheduler?: ModelOperationScheduler;
+
   logger: pino.Logger;
 
   /**
@@ -130,7 +142,7 @@ export class FlowEngine {
    */
   public reactView: ReactView;
   /**
-   * Flow executor that runs flows and auto-flows.
+   * Flow executor that runs event flows.
    */
   public executor: FlowExecutor;
 
@@ -165,6 +177,35 @@ export class FlowEngine {
     this.executor = new FlowExecutor(this);
   }
 
+  /** 获取/创建当前引擎的调度器（仅在本地作用域） */
+  public getScheduler(): ModelOperationScheduler {
+    if (!this._modelOperationScheduler) {
+      this._modelOperationScheduler = new ModelOperationScheduler(this);
+    }
+    return this._modelOperationScheduler;
+  }
+
+  /** 释放并清理当前引擎本地调度器（若存在） */
+  public disposeScheduler(): void {
+    if (this._modelOperationScheduler) {
+      try {
+        this._modelOperationScheduler.dispose();
+      } finally {
+        this._modelOperationScheduler = undefined;
+      }
+    }
+  }
+
+  /** 在目标模型生命周期达成时执行操作（仅在 View 引擎本地存储计划） */
+  public scheduleModelOperation(
+    fromModelOrUid: FlowModel | string,
+    toUid: string,
+    fn: (model: FlowModel) => Promise<void> | void,
+    options?: ScheduleOptions,
+  ): ScheduledCancel {
+    return this.getScheduler().schedule(fromModelOrUid, toUid, fn, options);
+  }
+
   /** 上一个引擎（根引擎为 undefined） */
   get previousEngine(): FlowEngine | undefined {
     return this._previousEngine;
@@ -447,6 +488,12 @@ export class FlowEngine {
 
     modelInstance.onInit(options);
 
+    // 发射 created 生命周期事件
+    void this.emitter.emitAsync('model:created', {
+      uid: modelInstance.uid,
+      model: modelInstance,
+    });
+
     // 在模型实例化阶段应用 flow 级 defaultParams（仅填充缺失的 stepParams，不覆盖）
     // 不阻塞创建流程：允许 defaultParams 为异步函数
     this._applyFlowDefinitionDefaultParams(modelInstance as FlowModel).catch((err) => {
@@ -555,16 +602,32 @@ export class FlowEngine {
           if (index !== -1) {
             subModelValue.splice(index, 1);
             modelInstance.parent.emitter.emit('onSubModelRemoved', modelInstance);
+            this.emitter?.emit('model:subModel:removed', {
+              parentUid: modelInstance.parent.uid,
+              parent: modelInstance.parent,
+              model: modelInstance,
+            });
             break;
           }
         } else if (subModelValue && subModelValue === modelInstance) {
           delete modelInstance.parent.subModels[subKey];
           modelInstance.parent.emitter.emit('onSubModelRemoved', modelInstance);
+          this.emitter?.emit('model:subModel:removed', {
+            parentUid: modelInstance.parent.uid,
+            parent: modelInstance.parent,
+            model: modelInstance,
+          });
           break;
         }
       }
     }
     this._modelInstances.delete(uid);
+
+    // 发射 destroyed 生命周期事件（在移除后，但携带实例便于调度器传递；严格模式：不吞错）
+    void this.emitter.emitAsync('model:destroyed', {
+      uid,
+      model: modelInstance,
+    });
     return true;
   }
 
@@ -734,6 +797,17 @@ export class FlowEngine {
     return this.removeModel(uid);
   }
 
+  /**
+   * Duplicate a model tree via repository API.
+   * Returns the duplicated model JSON (root with subModels) or null if not available.
+   * @param {string} uid UID of the model to duplicate
+   * @returns {Promise<any | null>} Duplicated model JSON or null
+   */
+  async duplicateModel(uid: string) {
+    if (!this.ensureModelRepository()) return null;
+    return this._modelRepository.duplicate(uid);
+  }
+
   /**
    * Replace a model instance with a new instance of a class.
    * @template T New model type
@@ -803,9 +877,15 @@ export class FlowEngine {
     // 7. 触发事件以通知其他部分模型已替换
     if (currentParent) {
       currentParent.emitter.setPaused(false);
-      currentParent.parent.invalidateAutoFlowCache(true);
+      currentParent.parent.invalidateFlowCache('beforeRender', true);
       currentParent.parent?.rerender();
       currentParent.emitter.emit('onSubModelReplaced', { oldModel, newModel });
+      this.emitter?.emit('model:subModel:replaced', {
+        parentUid: currentParent.uid,
+        parent: currentParent,
+        oldModel,
+        newModel,
+      });
     }
     await newModel.save();
     return newModel;
@@ -837,7 +917,8 @@ export class FlowEngine {
         return false;
       }
 
-      const findIndex = (model: FlowModel) => subModels.findIndex((item) => item.uid === model.uid);
+      const subModelsCopy = [...subModels];
+      const findIndex = (model: FlowModel) => subModelsCopy.findIndex((item) => item.uid === model.uid);
 
       const currentIndex = findIndex(sourceModel);
       const targetIndex = findIndex(targetModel);
@@ -853,14 +934,17 @@ export class FlowEngine {
       }
 
       // 使用splice直接移动数组元素（O(n)比排序O(n log n)更快）
-      const [movedModel] = subModels.splice(currentIndex, 1);
-      subModels.splice(targetIndex, 0, movedModel);
+      const [movedModel] = subModelsCopy.splice(currentIndex, 1);
+      subModelsCopy.splice(targetIndex, 0, movedModel);
 
       // 重新分配连续的sortIndex
-      subModels.forEach((model, index) => {
+      subModelsCopy.forEach((model, index) => {
         model.sortIndex = index;
       });
 
+      // 更新父模型的subModels引用
+      sourceModel.parent.subModels[sourceModel.subKey] = subModelsCopy;
+
       return true;
     };
     move(sourceModel, targetModel);
@@ -870,6 +954,12 @@ export class FlowEngine {
     }
     // 触发事件以通知其他部分模型已移动
     sourceModel.parent.emitter.emit('onSubModelMoved', { source: sourceModel, target: targetModel });
+    this.emitter?.emit('model:subModel:moved', {
+      parentUid: sourceModel.parent?.uid,
+      parent: sourceModel.parent,
+      source: sourceModel,
+      target: targetModel,
+    });
   }
 
   /**

package/src/flowSettings.ts

@@ -29,6 +29,7 @@ import {
   resolveStepUiSchema,
   resolveUiMode,
   setupRuntimeContextSteps,
+  buildSettingsViewInputArgs,
 } from './utils';
 import { FlowStepContext } from './hooks/useFlowStep';
 
@@ -205,8 +206,7 @@ export class FlowSettings {
         Upload,
       } = await import('@formily/antd-v5');
 
-      // 单独导入 Button 组件
-      const { Button } = await import('antd');
+      const { Button, Alert } = await import('antd');
 
       // 注册基础组件
       this.components.Form = Form;
@@ -254,6 +254,7 @@ export class FlowSettings {
       this.components.Space = Space;
       this.components.Editable = Editable;
       this.components.PreviewText = PreviewText;
+      this.components.Alert = Alert;
 
       // 注册按钮组件
       this.components.Button = Button;
@@ -464,12 +465,14 @@ export class FlowSettings {
     flowEngine,
     form,
     onFormValuesChange,
+    key,
   }: {
     uiSchema: any;
     initialValues: any;
     flowEngine: any;
     form?: any;
     onFormValuesChange?: (form: any) => void;
+    key?: string;
   }): React.ReactElement {
     // 获取 scopes 和 components
     const scopes = {
@@ -496,7 +499,7 @@ export class FlowSettings {
 
     return React.createElement(
       FormProviderWithForm,
-      { form, initialValues, onFormValuesChange },
+      { form, initialValues, onFormValuesChange, key },
       React.createElement(SchemaField as any, {
         schema: compiledSchema,
         components: flowEngine?.flowSettings?.components || {},
@@ -601,7 +604,7 @@ export class FlowSettings {
         let actionDefaultParams: Record<string, any> = {};
         let uiMode;
         if (step.use) {
-          const action = (model as any).flowEngine?.getAction?.(step.use);
+          const action = model.getAction?.(step.use);
           if (action) {
             actionDefaultParams = action.defaultParams || {};
             stepTitle = stepTitle || action.title;
@@ -615,6 +618,9 @@ export class FlowSettings {
         const flowRuntimeContext = new FlowRuntimeContext(model as any, fk, 'settings');
         setupRuntimeContextSteps(flowRuntimeContext as any, flow.steps, model as any, fk);
         flowRuntimeContext.defineProperty('currentStep', { value: step });
+        flowRuntimeContext.defineMethod('getStepFormValues', (flowKey: string, stepKey: string) => {
+          return forms.get(keyOf({ flowKey, stepKey }))?.values;
+        });
 
         // 解析默认值 + 当前参数
         const modelStepParams = (model as any).getStepParams(fk, sk) || {};
@@ -764,6 +770,8 @@ export class FlowSettings {
       zIndex: 5000,
       // 允许透传其它 props（如 maskClosable、footer 等），但确保 content 由我们接管
       ...modeProps,
+      // 统一构造 settings 弹窗的 inputArgs（集合/记录/父导航/关联）
+      inputArgs: buildSettingsViewInputArgs(model as any, (modeProps as any)?.inputArgs),
       content: (currentView, viewCtx) => {
         viewCtx?.defineMethod('getStepFormValues', (flowKey: string, stepKey: string) => {
           return forms.get(keyOf({ flowKey, stepKey }))?.values;

package/src/hooks/useApplyAutoFlows.ts

@@ -35,7 +35,9 @@ export function useApplyAutoFlows(
 
   const { loading, error } = useRequest(
     async () => {
-      await model.applyAutoFlows(inputArgs);
+      if (!model) return;
+      // beforeRender 在模型层默认顺序执行并默认使用缓存（可覆盖）
+      await model.dispatchEvent('beforeRender', inputArgs);
     },
     {
       refreshDeps: [model, inputArgs],

package/src/index.ts

@@ -12,6 +12,7 @@ export * from './types';
 
 // 工具函数
 export * from './utils';
+export { compileRunJs } from './utils/jsxTransform';
 
 // 资源类
 export * from './resources';
@@ -31,8 +32,18 @@ export * from './ElementProxy';
 export * from './flowContext';
 export * from './FlowContextProvider';
 export * from './JSRunner';
-export * from './runjs-context';
+export {
+  getRunJSDocFor,
+  createJSRunnerWithVersion,
+  getRunJSScenesForModel,
+  getRunJSScenesForContext,
+} from './runjs-context/helpers';
+export { RunJSContextRegistry, getModelClassName } from './runjs-context/registry';
+export { setupRunJSContexts } from './runjs-context/setup';
+export { getSnippetBody, listSnippetsForContext } from './runjs-context/snippets';
 
 export * from './views';
 
 export * from './FlowDefinition';
+export { createViewScopedEngine } from './ViewScopedFlowEngine';
+export { createBlockScopedEngine } from './BlockScopedFlowEngine';

package/src/locale/en-US.json

@@ -23,6 +23,7 @@
   "UID copied to clipboard": "UID copied to clipboard",
   "Copy failed": "Copy failed",
   "Copy failed, please copy [{{uid}}] manually.": "Copy failed, please copy [{{uid}}] manually.",
+  "Copy failed under HTTP. Clipboard API is unavailable on non-HTTPS pages. Please copy [{{uid}}] manually.": "Copy failed under HTTP. Clipboard API is unavailable on non-HTTPS pages. Please copy [{{uid}}] manually.",
   "Confirm delete": "Confirm delete",
   "Are you sure you want to delete this item? This action cannot be undone.": "Are you sure you want to delete this item? This action cannot be undone.",
   "Delete operation failed": "Delete operation failed",
@@ -57,5 +58,6 @@
   "Name": "Name",
   "Model with ID {{uid}} not found": "Model with ID {{uid}} not found",
   "Common actions": "Common actions",
-  "This variable is not available": "This variable is not available"
-}
+  "This variable is not available": "This variable is not available",
+  "Copy popup UID": "Copy popup UID"
+}

package/src/locale/zh-CN.json

@@ -23,6 +23,7 @@
   "UID copied to clipboard": "UID 已复制到剪贴板",
   "Copy failed": "复制失败",
   "Copy failed, please copy [{{uid}}] manually.": "复制失败，请手动复制 [{{uid}}]。",
+  "Copy failed under HTTP. Clipboard API is unavailable on non-HTTPS pages. Please copy [{{uid}}] manually.": "HTTP 环境下复制失败。非 HTTPS 页面不支持剪贴板 API，请手动复制 [{{uid}}]。",
   "Confirm delete": "确认删除",
   "Are you sure you want to delete this item? This action cannot be undone.": "确定要删除此项吗？此操作不可撤销。",
   "Delete operation failed": "删除操作失败",
@@ -57,5 +58,6 @@
   "Name": "名称",
   "Model with ID {{uid}} not found": "未找到 ID 为 {{uid}} 的模型",
   "Common actions": "通用操作",
-  "This variable is not available": "此变量不可用"
-}
+  "This variable is not available": "此变量不可用",
+  "Copy popup UID": "复制弹窗 UID"
+}

package/src/models/CollectionFieldModel.tsx

@@ -9,14 +9,17 @@
 
 import { Card, Form } from 'antd';
 import _ from 'lodash';
-import React from 'react';
+import React, { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
 import { CollectionField } from '../data-source';
 import { FlowEngineContext } from '../flowContext';
+import { useFlowModel } from '../hooks';
 import { DefaultStructure } from '../types';
 import { escapeT } from '../utils';
 import { FlowModel } from './flowModel';
 
 export function FieldPlaceholder() {
+  const { t } = useTranslation();
   return (
     <Form.Item>
       <Card
@@ -27,12 +30,42 @@ export function FieldPlaceholder() {
           },
         }}
       >
-        该字段已被隐藏，你无法查看（该内容仅在激活 UI Editor 时显示）。
+        {t(
+          'This field has been hidden and you cannot view it (this content is only visible when the UI Editor is activated).',
+        )}
       </Card>
     </Form.Item>
   );
 }
 
+export function FieldDeletePlaceholder() {
+  const { t } = useTranslation();
+  const model: any = useFlowModel();
+  const blockModel = model.context.blockModel;
+  const dataSource = blockModel.collection.dataSource;
+  const collection = blockModel.collection;
+  const name = model.fieldPath;
+  const nameValue = useMemo(() => {
+    const dataSourcePrefix = `${t(dataSource.displayName || dataSource.key)} > `;
+    const collectionPrefix = collection ? `${t(collection.title) || collection.name || collection.tableName} > ` : '';
+    return `${dataSourcePrefix}${collectionPrefix}${name}`;
+  }, []);
+  return (
+    <Form.Item>
+      <div
+        style={{
+          color: 'rgba(0,0,0,0.45)',
+        }}
+      >
+        {t(`The {{type}} "{{name}}" may have been deleted. Please remove this {{blockType}}.`, {
+          type: t('Field'),
+          name: nameValue,
+          blockType: t('Field'),
+        }).replaceAll('&gt;', '>')}
+      </div>
+    </Form.Item>
+  );
+}
 export interface FieldSettingsInitParams {
   dataSourceKey: string;
   collectionName: string;
@@ -51,8 +84,12 @@ const defaultWhen = () => true;
 
 export class CollectionFieldModel<T extends DefaultStructure = DefaultStructure> extends FlowModel<T> {
   private static _bindings = new Map();
+  fieldDeleted = false;
 
   renderHiddenInConfig(): React.ReactNode | undefined {
+    if (this.fieldDeleted) {
+      return <FieldDeletePlaceholder />;
+    }
     return <FieldPlaceholder />;
   }
 
@@ -76,12 +113,14 @@ export class CollectionFieldModel<T extends DefaultStructure = DefaultStructure>
         return this.fieldPath;
       },
     });
-    this.context.blockModel.addAppends(this.fieldPath);
-    this.context.blockModel.addAppends(this.associationPathName);
+    if (this.context.blockModel) {
+      this.context.blockModel.addAppends(this.fieldPath);
+      this.context.blockModel.addAppends(this.associationPathName);
+    }
   }
 
   getFieldSettingsInitParams(): FieldSettingsInitParams {
-    return this.getStepParams('fieldSettings', 'init');
+    return this.getStepParams('fieldSettings', 'init') || {};
   }
 
   get fieldPath(): string {
@@ -103,6 +142,9 @@ export class CollectionFieldModel<T extends DefaultStructure = DefaultStructure>
   }
 
   static getBindingsByField(ctx: FlowEngineContext, collectionField: CollectionField): BindingOptions[] {
+    if (!collectionField) {
+      return;
+    }
     const interfaceName = collectionField.interface;
 
     // Check if the interface exists in the map
@@ -120,13 +162,23 @@ export class CollectionFieldModel<T extends DefaultStructure = DefaultStructure>
   static getDefaultBindingByField(
     ctx: FlowEngineContext,
     collectionField: CollectionField,
-    options: { useStrict?: boolean; fallbackToTargetTitleField?: boolean } = {},
+    options: {
+      useStrict?: boolean;
+      fallbackToTargetTitleField?: boolean;
+      targetCollectionTitleField?: CollectionField;
+    } = {},
   ): BindingOptions | null {
     if (options.fallbackToTargetTitleField) {
       const binding = this.getDefaultBindingByField(ctx, collectionField, { useStrict: true });
       if (!binding) {
-        if (collectionField.isAssociationField() && collectionField.targetCollectionTitleField) {
-          return this.getDefaultBindingByField(ctx, collectionField.targetCollectionTitleField);
+        if (
+          (collectionField.isAssociationField() && options?.targetCollectionTitleField) ||
+          collectionField.targetCollectionTitleField
+        ) {
+          return this.getDefaultBindingByField(
+            ctx,
+            options?.targetCollectionTitleField || collectionField.targetCollectionTitleField,
+          );
         }
       }
       return binding;

package/src/models/__tests__/dispatchEvent.behavior.test.ts

@@ -0,0 +1,169 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, test, expect } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { FlowModel } from '../../models/flowModel';
+
+describe('dispatchEvent behavior (defaults, parallel, errors)', () => {
+  test('non-beforeRender defaults to sequential execution and respects getEventFlows order', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    // Static flow with higher sort
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      sort: 10,
+      steps: { s: { handler: async () => void calls.push('static') } as any },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+
+    // Instance flows
+    model.registerFlow('I1', {
+      on: { eventName: 'go' },
+      sort: 0,
+      steps: { i1: { handler: async () => void calls.push('inst1') } as any },
+    });
+    model.registerFlow('I2', {
+      on: { eventName: 'go' },
+      sort: 5,
+      steps: { i2: { handler: async () => void calls.push('inst2') } as any },
+    });
+
+    // No options provided -> should default to sequential execution
+    await model.dispatchEvent('go');
+
+    // Expected order should match getEventFlows('go') order
+    const expected = model.getEventFlows('go').map((f) => f.key);
+    expect(calls).toEqual(expected.map((k) => (k === 'I1' ? 'inst1' : k === 'I2' ? 'inst2' : 'static')));
+  });
+
+  test('parallel mode (sequential=false) runs all and tolerates non-beforeRender errors', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      sort: 1,
+      steps: { s: { handler: async () => 'static-ok' } as any },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+
+    model.registerFlow('I1', {
+      on: { eventName: 'go' },
+      sort: 0,
+      steps: { i1: { handler: async () => (calls.push('inst1'), 'i1-ok') } as any },
+    });
+    model.registerFlow('I2', {
+      on: { eventName: 'go' },
+      sort: 2,
+      steps: { i2: { handler: async () => (calls.push('inst2'), 'i2-ok') } as any },
+    });
+    model.registerFlow('ERR', {
+      on: { eventName: 'go' },
+      sort: 3,
+      steps: {
+        e: {
+          handler: async () => {
+            calls.push('err');
+            throw new Error('boom');
+          },
+        } as any,
+      },
+    });
+
+    const results = await model.dispatchEvent('go', undefined, { sequential: false });
+
+    // All handlers ran; order is not guaranteed in parallel mode
+    expect(new Set(calls)).toEqual(new Set(['inst1', 'inst2', 'err']));
+    // The error flow returns undefined and is filtered out; others return stepResults objects
+    // Expect one result object per successful flow with its step key
+    expect(Array.isArray(results)).toBe(true);
+    const keys = (results as any[]).flatMap((o) => Object.keys(o));
+    expect(new Set(keys)).toEqual(new Set(['i1', 'i2', 's']));
+    const byKey = Object.assign({}, ...(results as any[]));
+    expect(byKey['i1']).toBe('i1-ok');
+    expect(byKey['i2']).toBe('i2-ok');
+    expect(byKey['s']).toBe('static-ok');
+  });
+
+  test('sequential non-beforeRender: stops subsequent flows on error', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+    const model = engine.createModel({ use: 'M' });
+
+    model.registerFlow('I1', {
+      on: { eventName: 'go' },
+      sort: 0,
+      steps: { i1: { handler: async () => void calls.push('i1') } as any },
+    });
+    model.registerFlow('ERR', {
+      on: { eventName: 'go' },
+      sort: 1,
+      steps: {
+        e: {
+          handler: async () => {
+            throw new Error('X');
+          },
+        } as any,
+      },
+    });
+    model.registerFlow('I2', {
+      on: { eventName: 'go' },
+      sort: 2,
+      steps: { i2: { handler: async () => void calls.push('i2') } as any },
+    });
+
+    await model.dispatchEvent('go', undefined, { sequential: true }).catch(() => undefined);
+    // 只应执行第一个 flow，后续被中止
+    expect(calls).toEqual(['i1']);
+  });
+
+  test('beforeRender errors are thrown (sequential default)', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+    const model = engine.createModel({ use: 'M' });
+
+    model.registerFlow('F1', {
+      on: 'beforeRender',
+      sort: 0,
+      steps: {
+        a: {
+          handler: async () => {
+            throw new Error('BR');
+          },
+        } as any,
+      },
+    });
+    model.registerFlow('F2', {
+      on: 'beforeRender',
+      sort: 1,
+      steps: { b: { handler: async () => void calls.push('b') } as any },
+    });
+
+    await expect(model.dispatchEvent('beforeRender', undefined, { useCache: false })).rejects.toThrow('BR');
+    expect(calls).toEqual([]);
+  });
+});