@nocobase/flow-engine 2.0.60 → 2.0.61

package/src/__tests__/viewScopedFlowEngine.test.ts

@@ -18,6 +18,33 @@ import { APIClient as SDKApiClient } from '@nocobase/sdk';
 import { FlowEngine } from '../flowEngine';
 import { createViewScopedEngine } from '../ViewScopedFlowEngine';
 import { FlowModel } from '../models';
+import type { IFlowModelRepository } from '../types';
+
+const clone = <T>(value: T): T => (value == null ? value : JSON.parse(JSON.stringify(value)));
+
+class DirtyPageRepository implements IFlowModelRepository<FlowModel> {
+  public findOneCalls = 0;
+  public data: Record<string, any> | null = null;
+
+  async findOne(): Promise<Record<string, any> | null> {
+    this.findOneCalls += 1;
+    return clone(this.data);
+  }
+
+  async save(model: FlowModel): Promise<Record<string, any>> {
+    return model.serialize();
+  }
+
+  async destroy(): Promise<boolean> {
+    return true;
+  }
+
+  async move(): Promise<void> {}
+
+  async duplicate(): Promise<Record<string, any> | null> {
+    return null;
+  }
+}
 
 describe('ViewScopedFlowEngine', () => {
   it('shares global actions/events and model classes with parent', async () => {
@@ -307,4 +334,110 @@ describe('ViewScopedFlowEngine', () => {
     expect(result).not.toBeNull();
     expect(result?.uid).toBe('child-normal');
   });
+
+  it('reloads a dirty loaded page from repository and replaces stale parent reference', async () => {
+    const root = new FlowEngine();
+    const repository = new DirtyPageRepository();
+    root.setModelRepository(repository);
+
+    class ParentModel extends FlowModel {}
+    class PageModel extends FlowModel {}
+    class BlockModel extends FlowModel {}
+    root.registerModels({ ParentModel, PageModel, BlockModel });
+
+    const parent = root.createModel<ParentModel>({ use: 'ParentModel', uid: 'popup-action' });
+    const oldScoped = createViewScopedEngine(root);
+    const stalePage = oldScoped.createModel<PageModel>({
+      use: 'PageModel',
+      uid: 'popup-page',
+      parentId: parent.uid,
+      subKey: 'page',
+      subType: 'object',
+      subModels: {
+        items: [{ use: 'BlockModel', uid: 'stale-block' }],
+      },
+    });
+    const staleBlock = stalePage.findSubModel('items' as any, (item) => item.uid === 'stale-block') as FlowModel;
+    parent.setSubModel('page', stalePage);
+    oldScoped.unlinkFromStack();
+
+    repository.data = {
+      use: 'PageModel',
+      uid: 'popup-page',
+      parentId: parent.uid,
+      subKey: 'page',
+      subType: 'object',
+      subModels: {
+        items: [{ use: 'BlockModel', uid: 'fresh-block' }],
+      },
+    };
+
+    root.flowSettings.enable();
+    await staleBlock.saveStepParams();
+    root.flowSettings.disable();
+    repository.findOneCalls = 0;
+
+    const runtimeScoped = createViewScopedEngine(root);
+    const loaded = await runtimeScoped.loadOrCreateModel<PageModel>({
+      async: true,
+      parentId: parent.uid,
+      subKey: 'page',
+      subType: 'object',
+      use: 'PageModel',
+    });
+
+    expect(repository.findOneCalls).toBe(1);
+    expect(loaded).not.toBe(stalePage);
+    expect((parent.subModels as any).page).toBe(loaded);
+    expect(loaded?.mapSubModels('items' as any, (item) => item.uid)).toEqual(['fresh-block']);
+
+    repository.findOneCalls = 0;
+    const nextRuntimeScoped = createViewScopedEngine(root);
+    const loadedAgain = await nextRuntimeScoped.loadOrCreateModel<PageModel>({
+      async: true,
+      parentId: parent.uid,
+      subKey: 'page',
+      subType: 'object',
+      use: 'PageModel',
+    });
+
+    expect(repository.findOneCalls).toBe(0);
+    expect(loadedAgain?.uid).toBe('popup-page');
+  });
+
+  it('does not bypass loaded page cache after a non-config save', async () => {
+    const root = new FlowEngine();
+    const repository = new DirtyPageRepository();
+    root.setModelRepository(repository);
+
+    class ParentModel extends FlowModel {}
+    class PageModel extends FlowModel {}
+    root.registerModels({ ParentModel, PageModel });
+
+    const parent = root.createModel<ParentModel>({ use: 'ParentModel', uid: 'normal-parent' });
+    const stalePage = root.createModel<PageModel>({
+      use: 'PageModel',
+      uid: 'normal-page',
+      parentId: parent.uid,
+      subKey: 'page',
+      subType: 'object',
+    });
+    parent.setSubModel('page', stalePage);
+
+    root.flowSettings.disable();
+    await root.saveModel(stalePage);
+    repository.findOneCalls = 0;
+
+    const runtimeScoped = createViewScopedEngine(root);
+    const loaded = await runtimeScoped.loadOrCreateModel<PageModel>({
+      async: true,
+      parentId: parent.uid,
+      subKey: 'page',
+      subType: 'object',
+      use: 'PageModel',
+    });
+
+    expect(repository.findOneCalls).toBe(0);
+    expect(loaded?.uid).toBe('normal-page');
+  });
 });

package/src/components/settings/wrappers/contextual/DefaultSettingsIcon.tsx

@@ -234,8 +234,18 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
   // 当模型发生子模型替换/增删等变化时，强制刷新菜单数据
   const [refreshTick, setRefreshTick] = useState(0);
   const [extraMenuItems, setExtraMenuItems] = useState<FlowModelExtraMenuItem[]>([]);
+  const [extraMenuItemsLoaded, setExtraMenuItemsLoaded] = useState(false);
   const [configurableFlowsAndSteps, setConfigurableFlowsAndSteps] = useState<FlowInfo[]>([]);
   const [isLoading, setIsLoading] = useState(true);
+  const commonExtras = useMemo(
+    () => extraMenuItems.filter((it) => it.group === 'common-actions').sort((a, b) => (a.sort ?? 0) - (b.sort ?? 0)),
+    [extraMenuItems],
+  );
+  const hasCommonActions = showCopyUidButton || showDeleteButton || commonExtras.length > 0;
+  const shouldDeferConfigLoading = flattenSubMenus && menuLevels > 1 && hasCommonActions;
+  const shouldWaitForCommonActionProbe =
+    flattenSubMenus && menuLevels > 1 && !showCopyUidButton && !showDeleteButton && !extraMenuItemsLoaded;
+  const canRenderIcon = hasCommonActions || (!isLoading && configurableFlowsAndSteps.length > 0);
   const closeDropdown = useCallback(() => {
     setVisible(false);
     onDropdownVisibleChange?.(false);
@@ -274,26 +284,30 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
   useEffect(() => {
     let mounted = true;
     const loadExtras = async () => {
-      const allExtras: FlowModelExtraMenuItem[] = [];
-      const modelsToProcess: Array<{ model: FlowModel; modelKey?: string }> = [];
-      walkSubModels(model, { maxDepth: menuLevels, arrayLimit: 50, mode: 'stack' }, (targetModel, { modelKey }) => {
-        modelsToProcess.push({ model: targetModel, modelKey });
-      });
+      setExtraMenuItemsLoaded(false);
+      try {
+        const allExtras: FlowModelExtraMenuItem[] = [];
+        const modelsToProcess: Array<{ model: FlowModel; modelKey?: string }> = [];
+        walkSubModels(model, { maxDepth: menuLevels, arrayLimit: 50, mode: 'stack' }, (targetModel, { modelKey }) => {
+          modelsToProcess.push({ model: targetModel, modelKey });
+        });
 
-      for (const { model: targetModel, modelKey } of modelsToProcess) {
-        const Cls = targetModel.constructor as typeof FlowModel;
-        const extras = await Cls.getExtraMenuItems?.(targetModel, t);
-        if (extras?.length) {
-          allExtras.push(
-            ...extras.map((item) => ({
-              ...item,
-              key: modelKey ? `${modelKey}:${item.key}` : item.key,
-            })),
-          );
+        for (const { model: targetModel, modelKey } of modelsToProcess) {
+          const Cls = targetModel.constructor as typeof FlowModel;
+          const extras = await Cls.getExtraMenuItems?.(targetModel, t);
+          if (extras?.length) {
+            allExtras.push(
+              ...extras.map((item) => ({
+                ...item,
+                key: modelKey ? `${modelKey}:${item.key}` : item.key,
+              })),
+            );
+          }
         }
-      }
 
-      if (mounted) {
+        if (!mounted) {
+          return;
+        }
         const seen = new Set<string>();
         const dedupedExtras = allExtras.filter((item) => {
           if (seen.has(`${item.key}`)) {
@@ -303,16 +317,22 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
           return true;
         });
         setExtraMenuItems(dedupedExtras);
+      } catch (error) {
+        console.error('Failed to load extra menu items:', error);
+        if (mounted) {
+          setExtraMenuItems([]);
+        }
+      } finally {
+        if (mounted) {
+          setExtraMenuItemsLoaded(true);
+        }
       }
     };
-    // 避免 effect 触发 setState 导致循环：仅在 visible 打开时加载一次，关闭后仍保留结果
-    if (visible) {
-      loadExtras();
-    }
+    loadExtras();
     return () => {
       mounted = false;
     };
-  }, [model, menuLevels, t, refreshTick, visible]);
+  }, [model, menuLevels, t, refreshTick]);
 
   // 统一的复制 UID 方法
   const copyUidToClipboard = useCallback(
@@ -599,7 +619,7 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
         return [];
       }
     },
-    [],
+    [t],
   );
 
   // 获取可配置的flows和steps
@@ -642,21 +662,50 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
   }, [model, menuLevels, refreshTick]);
 
   useEffect(() => {
+    let mounted = true;
     const loadConfigurableFlowsAndSteps = async () => {
       setIsLoading(true);
+      if (shouldDeferConfigLoading) {
+        setConfigurableFlowsAndSteps([]);
+      }
       try {
         const flows = await getConfigurableFlowsAndSteps();
-        setConfigurableFlowsAndSteps(flows);
+        if (mounted) {
+          setConfigurableFlowsAndSteps(flows);
+        }
       } catch (error) {
         console.error('Failed to load configurable flows and steps:', error);
-        setConfigurableFlowsAndSteps([]);
+        if (mounted) {
+          setConfigurableFlowsAndSteps([]);
+        }
       } finally {
-        setIsLoading(false);
+        if (mounted) {
+          setIsLoading(false);
+        }
       }
     };
 
+    if (shouldWaitForCommonActionProbe) {
+      setConfigurableFlowsAndSteps([]);
+      setIsLoading(false);
+      return () => {
+        mounted = false;
+      };
+    }
+
+    if (!visible && shouldDeferConfigLoading) {
+      setConfigurableFlowsAndSteps([]);
+      setIsLoading(false);
+      return () => {
+        mounted = false;
+      };
+    }
+
     loadConfigurableFlowsAndSteps();
-  }, [getConfigurableFlowsAndSteps, refreshTick]);
+    return () => {
+      mounted = false;
+    };
+  }, [getConfigurableFlowsAndSteps, refreshTick, shouldDeferConfigLoading, shouldWaitForCommonActionProbe, visible]);
 
   // 构建菜单项，包含错误处理和记忆化
   const menuItems = useMemo((): NonNullable<MenuProps['items']> => {
@@ -823,16 +872,12 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
     }
 
     return items;
-  }, [configurableFlowsAndSteps, disabledIconColor, flattenSubMenus, t]);
+  }, [configurableFlowsAndSteps, disabledIconColor, flattenSubMenus, message, model, t]);
 
   // 向菜单项添加额外按钮
   const finalMenuItems = useMemo((): NonNullable<MenuProps['items']> => {
     const items = [...menuItems];
 
-    const commonExtras = extraMenuItems
-      .filter((it) => it.group === 'common-actions')
-      .sort((a, b) => (a.sort ?? 0) - (b.sort ?? 0));
-
     if (showCopyUidButton || showDeleteButton || commonExtras.length > 0) {
       items.push({
         type: 'divider',
@@ -867,12 +912,9 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
     }
 
     return items;
-  }, [menuItems, showCopyUidButton, showDeleteButton, model.uid, model.destroy, t, extraMenuItems]);
-
-  // 如果正在加载或没有可配置的flows且不显示删除按钮和复制UID按钮，不显示菜单
-  const hasExtras = extraMenuItems.some((it) => it.group === 'common-actions');
+  }, [menuItems, showCopyUidButton, showDeleteButton, commonExtras, model.uid, model.destroy, t]);
 
-  if (isLoading || (configurableFlowsAndSteps.length === 0 && !showDeleteButton && !showCopyUidButton && !hasExtras)) {
+  if (!canRenderIcon) {
     return null;
   }
 

package/src/components/settings/wrappers/contextual/__tests__/DefaultSettingsIcon.test.tsx

@@ -141,6 +141,86 @@ describe('DefaultSettingsIcon - only static flows are shown', () => {
     vi.clearAllMocks();
   });
 
+  it('defers nested configurable step resolution and clears stale config while closed', async () => {
+    class TestFlowModel extends FlowModel {}
+
+    const engine = new FlowEngine();
+    const model = new TestFlowModel({ uid: 'model-lazy-settings', flowEngine: engine });
+    const hideInSettings = vi.fn((ctx) => !!ctx.getStepParams('general')?.hidden);
+    const uiSchema = vi.fn(() => ({
+      field: { type: 'string', 'x-component': 'Input' },
+    }));
+
+    TestFlowModel.registerFlow({
+      key: 'lazyFlow',
+      title: 'Lazy Flow',
+      steps: {
+        general: {
+          title: 'General',
+          hideInSettings,
+          uiSchema,
+        },
+      },
+    });
+
+    const { getByLabelText } = render(
+      React.createElement(
+        ConfigProvider as any,
+        null,
+        React.createElement(
+          App as any,
+          null,
+          React.createElement(DefaultSettingsIcon as any, { model, menuLevels: 2 }),
+        ),
+      ),
+    );
+
+    expect(getByLabelText('flows-settings')).toBeTruthy();
+    expect(hideInSettings).not.toHaveBeenCalled();
+    expect(uiSchema).not.toHaveBeenCalled();
+
+    await act(async () => {
+      (globalThis as any).__lastDropdownOnOpenChange?.(true, { source: 'trigger' });
+    });
+
+    await waitFor(() => {
+      expect(hideInSettings).toHaveBeenCalledTimes(1);
+      expect(uiSchema).toHaveBeenCalledTimes(1);
+      const menu = (globalThis as any).__lastDropdownMenu;
+      const items = (menu?.items || []) as any[];
+      expect(items.some((it) => String(it.key || '') === 'lazyFlow:general')).toBe(true);
+    });
+
+    await act(async () => {
+      (globalThis as any).__lastDropdownOnOpenChange?.(false, { source: 'trigger' });
+    });
+
+    await waitFor(() => {
+      const menu = (globalThis as any).__lastDropdownMenu;
+      const items = (menu?.items || []) as any[];
+      expect(items.some((it) => String(it.key || '') === 'lazyFlow:general')).toBe(false);
+    });
+
+    await act(async () => {
+      model.setStepParams('lazyFlow', 'general', { hidden: true });
+    });
+
+    expect(hideInSettings).toHaveBeenCalledTimes(1);
+    expect(uiSchema).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      (globalThis as any).__lastDropdownOnOpenChange?.(true, { source: 'trigger' });
+    });
+
+    await waitFor(() => {
+      expect(hideInSettings).toHaveBeenCalledTimes(2);
+      const menu = (globalThis as any).__lastDropdownMenu;
+      const items = (menu?.items || []) as any[];
+      expect(items.some((it) => String(it.key || '') === 'lazyFlow:general')).toBe(false);
+    });
+    expect(uiSchema).toHaveBeenCalledTimes(1);
+  });
+
   it('excludes instance (dynamic) flows from the settings menu', async () => {
     class TestFlowModel extends FlowModel {}
 
@@ -612,7 +692,7 @@ describe('DefaultSettingsIcon - only static flows are shown', () => {
       const items = (menu?.items || []) as any[];
       const subMenu = items.find((it) => Array.isArray(it?.children));
       expect(subMenu).toBeTruthy();
-      expect(subMenu!.children.some((it: any) => String(it.key).startsWith('items[0]:childFlow:cstep'))).toBe(true);
+      expect(subMenu?.children.some((it: any) => String(it.key).startsWith('items[0]:childFlow:cstep'))).toBe(true);
     });
   });
 
@@ -716,6 +796,10 @@ describe('DefaultSettingsIcon - only static flows are shown', () => {
       ),
     );
 
+    await act(async () => {
+      (globalThis as any).__lastDropdownOnOpenChange?.(true, { source: 'trigger' });
+    });
+
     await waitFor(() => {
       const menu = (globalThis as any).__lastDropdownMenu;
       expect(menu).toBeTruthy();
@@ -809,4 +893,67 @@ describe('DefaultSettingsIcon - extra menu items', () => {
       dispose?.();
     }
   });
+
+  it('uses common extra actions to defer nested configurable step resolution', async () => {
+    const onClick = vi.fn();
+
+    class TestFlowModel extends FlowModel {}
+    const dispose = TestFlowModel.registerExtraMenuItems({
+      group: 'common-actions',
+      sort: 10,
+      items: [{ key: 'extra-action', label: 'Extra Action', onClick }],
+    });
+
+    const engine = new FlowEngine();
+    const model = new TestFlowModel({ uid: 'm-extra-lazy', flowEngine: engine });
+    const uiSchema = vi.fn(() => ({
+      f: { type: 'string', 'x-component': 'Input' },
+    }));
+
+    TestFlowModel.registerFlow({
+      key: 'flow',
+      title: 'Flow',
+      steps: { s: { title: 'S', uiSchema } },
+    });
+
+    try {
+      const { getByLabelText } = render(
+        React.createElement(
+          ConfigProvider as any,
+          null,
+          React.createElement(
+            App as any,
+            null,
+            React.createElement(DefaultSettingsIcon as any, {
+              model,
+              menuLevels: 2,
+              showCopyUidButton: false,
+              showDeleteButton: false,
+            }),
+          ),
+        ),
+      );
+
+      await waitFor(() => {
+        expect(getByLabelText('flows-settings')).toBeTruthy();
+        const menu = (globalThis as any).__lastDropdownMenu;
+        const items = (menu?.items || []) as any[];
+        expect(items.some((it) => String(it.key || '') === 'extra-action')).toBe(true);
+      });
+      expect(uiSchema).not.toHaveBeenCalled();
+
+      await act(async () => {
+        (globalThis as any).__lastDropdownOnOpenChange?.(true, { source: 'trigger' });
+      });
+
+      await waitFor(() => {
+        expect(uiSchema).toHaveBeenCalledTimes(1);
+        const menu = (globalThis as any).__lastDropdownMenu;
+        const items = (menu?.items || []) as any[];
+        expect(items.some((it) => String(it.key || '') === 'flow:s')).toBe(true);
+      });
+    } finally {
+      dispose?.();
+    }
+  });
 });

package/src/flowContext.ts

@@ -400,6 +400,10 @@ export type FlowContextGetApiInfosOptions = {
    * RunJS 文档版本（默认 v1）。
    */
   version?: RunJSVersion;
+  /**
+   * Include editor completion metadata. Defaults to false so API-doc callers keep the compact public shape.
+   */
+  includeCompletion?: boolean;
 };
 
 export type FlowContextGetVarInfosOptions = {
@@ -704,10 +708,11 @@ export class FlowContext {
    * - 输出仅来自 RunJS doc 与 defineProperty/defineMethod 的 info
    * - 不读取/展开 PropertyMeta（变量结构）
    * - 不自动展开深层 properties
-   * - 不返回自动补全字段（例如 completion）
+   * - 默认不返回自动补全字段（例如 completion），传入 includeCompletion=true 时返回
    */
   async getApiInfos(options: FlowContextGetApiInfosOptions = {}): Promise<Record<string, FlowContextApiInfo>> {
     const version = (options.version as RunJSVersion) || ('v1' as RunJSVersion);
+    const includeCompletion = !!options.includeCompletion;
     const evalCtx = this.createProxy();
 
     const isPrivateKey = (key: string) => typeof key === 'string' && key.startsWith('_');
@@ -759,7 +764,14 @@ export class FlowContext {
       const src = toDocObject(obj);
       if (!src) return {};
       const out: any = {};
-      for (const k of ['description', 'examples', 'ref', 'params', 'returns']) {
+      for (const k of [
+        'description',
+        'examples',
+        ...(includeCompletion ? ['completion'] : []),
+        'ref',
+        'params',
+        'returns',
+      ]) {
         const v = (src as any)[k];
         if (typeof v !== 'undefined') out[k] = v;
       }
@@ -773,7 +785,17 @@ export class FlowContext {
       const src = toDocObject(obj);
       if (!src) return {};
       const out: any = {};
-      for (const k of ['title', 'type', 'interface', 'description', 'examples', 'ref', 'params', 'returns']) {
+      for (const k of [
+        'title',
+        'type',
+        'interface',
+        'description',
+        'examples',
+        ...(includeCompletion ? ['completion'] : []),
+        'ref',
+        'params',
+        'returns',
+      ]) {
         const v = (src as any)[k];
         if (typeof v !== 'undefined') out[k] = v;
       }
@@ -872,7 +894,7 @@ export class FlowContext {
       node = { ...node, ...pickPropertyInfo(docObj) };
       node = { ...node, ...pickPropertyInfo(infoObj) };
       delete (node as any).properties;
-      delete (node as any).completion;
+      if (!includeCompletion) delete (node as any).completion;
       if (!Object.keys(node).length) continue;
       const outKey = mapDocKeyToApiKey(key, docNode);
       // Avoid exposing ctx.React/ctx.ReactDOM/ctx.antd in api docs when mapping to ctx.libs.*.
@@ -890,7 +912,7 @@ export class FlowContext {
       node = { ...node, ...pickMethodInfo(docObj) };
       node = { ...node, ...pickMethodInfo(info) };
       delete (node as any).properties;
-      delete (node as any).completion;
+      if (!includeCompletion) delete (node as any).completion;
       if (!Object.keys(node).length) continue;
       node.type = 'function';
 
@@ -913,7 +935,7 @@ export class FlowContext {
         let node: FlowContextApiInfo = {};
         node = { ...node, ...pickPropertyInfo(childObj) };
         delete (node as any).properties;
-        delete (node as any).completion;
+        if (!includeCompletion) delete (node as any).completion;
         if (!node.description || !String(node.description).trim()) continue;
         out[outKey] = node;
       }
@@ -3073,6 +3095,17 @@ class BaseFlowEngineContext extends FlowContext {
         const jsCode = await prepareRunJsCode(String(code ?? ''), { preprocessTemplates: shouldPreprocessTemplates });
         return runner.run(jsCode);
       },
+      {
+        description: 'Execute a RunJS code string in the current Flow context.',
+        detail: '(code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<RunJSResult>',
+        params: [
+          { name: 'code', type: 'string', description: 'RunJS code to execute.' },
+          { name: 'variables', type: 'Record<string, any>', optional: true, description: 'Additional globals.' },
+          { name: 'options', type: 'JSRunnerOptions', optional: true, description: 'Runner options.' },
+        ],
+        returns: { type: 'Promise<{ success: boolean; value?: any; error?: any; timeout?: boolean }>' },
+        completion: { insertText: `await ctx.runjs('return 1')` },
+      },
     );
   }
 }
@@ -3922,6 +3955,7 @@ export type FlowSettingsContext<TModel extends FlowModel = FlowModel> = FlowRunt
 
 export type RunJSDocCompletionDoc = {
   insertText?: string;
+  requires?: Array<'element'>;
 };
 
 export type RunJSDocHiddenDoc = boolean | ((ctx: any) => boolean | Promise<boolean>);