@nocobase/flow-engine 2.0.0-alpha.7 → 2.0.0-alpha.71

package/src/models/forkFlowModel.ts

@@ -12,6 +12,7 @@ import { FlowForkModelContext, FlowModelContext } from '../flowContext';
 import type { IModelComponentProps } from '../types';
 import { FlowModel } from './flowModel';
 import { FlowEngine } from '../flowEngine';
+import { uid } from 'uid/secure';
 
 /**
  * ForkFlowModel 作为 FlowModel 的独立实例：
@@ -38,7 +39,7 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   private disposed = false;
 
   /** fork 在 master.forks 中的索引 */
-  public readonly forkId: number;
+  public readonly forkId: string;
 
   /** 需要与 master 共享的属性列表 */
   private static readonly SHARED_PROPERTIES = ['stepParams', 'sortIndex'];
@@ -67,12 +68,12 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   // 不需要定义自己的属性了，现在是SHARED_PROPERTIES中指定的少数几个属性，所有属性设置时会自动添加自己的fork内的独有属性
   #flowContext: FlowModelContext;
 
-  constructor(master: TMaster, initialProps: IModelComponentProps = {}, forkId = 0) {
+  constructor(master: TMaster, initialProps: IModelComponentProps = {}, forkId?: string) {
     void this.localProperties; // 避免 IDE 提示 unused
     this.master = master;
     this.uid = master.uid;
     this.localProps = { ...initialProps };
-    this.forkId = forkId;
+    this.forkId = forkId || uid();
     this.hidden = this.master.hidden;
 
     define(this, {
@@ -206,6 +207,13 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
     }
   }
 
+  /**
+   * 清理局部 props，仅影响当前 fork
+   */
+  clearProps() {
+    return (this.localProps = {});
+  }
+
   /**
    * render 依旧使用 master 的方法，但合并后的 props 需要透传
    */
@@ -224,10 +232,10 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   }
 
   /**
-   * 自动流程缓存的作用域标识（fork 专用）。
+   * 事件缓存的作用域标识（fork 专用）。
    */
-  public getAutoFlowCacheScope(): string {
-    return String(this.forkId);
+  public getFlowCacheScope(eventName: string): string {
+    return `${String(eventName)}:${String(this.forkId)}`;
   }
 
   // onUnmount() {
@@ -250,9 +258,41 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   dispose() {
     if (this.disposed) return;
     this.disposed = true;
+    // 统一按事件缓存命名规则清理当前 fork 的所有缓存项（覆盖所有事件）
+    try {
+      const cache = this.flowEngine?.applyFlowCache;
+      if (cache && cache.size > 0) {
+        const uidSuffixes = [`:${this.uid}`, `-${this.uid}`];
+        const forkIdColon = `:${this.forkId}:`;
+        const forkIdHyphen = `-${this.forkId}-`;
+
+        for (const key of cache.keys()) {
+          // 事件缓存统一以 event: 或 event- 开头
+          const isEventCache = key.startsWith('event:') || key.startsWith('event-');
+          if (!isEventCache) continue;
+
+          // 仅删除当前 fork + 当前 uid 的键
+          const endMatches = uidSuffixes.some((s) => key.endsWith(s));
+          if (!endMatches) continue;
+
+          // 限定在去除 uid 后缀的范围内匹配 forkId 片段，避免误伤
+          let trimmed = key;
+          for (const suf of uidSuffixes) {
+            if (trimmed.endsWith(suf)) {
+              trimmed = trimmed.slice(0, -suf.length);
+              break;
+            }
+          }
+          if (trimmed.includes(forkIdColon) || trimmed.includes(forkIdHyphen)) {
+            cache.delete(key);
+          }
+        }
+      }
+    } catch {
+      // 忽略清理阶段异常，避免影响后续释放
+    }
+
     if (this.master && (this.master as any).forks) {
-      const forkCacheKey = FlowEngine.generateApplyFlowCacheKey(`${this.forkId}`, 'all', this.uid);
-      this.flowEngine.applyFlowCache.delete(forkCacheKey);
       (this.master as any).forks.delete(this as any);
     }
     // 从 master 的 forkCache 中移除自己

package/src/provider.tsx

@@ -22,7 +22,7 @@ interface FlowEngineProviderProps {
 
 const FlowEngineReactContext = createContext<FlowEngine | null>(null);
 
-export const FlowEngineProvider: React.FC<FlowEngineProviderProps> = (props) => {
+export const FlowEngineProvider: React.FC<FlowEngineProviderProps> = React.memo((props) => {
   const { engine, children } = props;
   if (!engine) {
     throw new Error('FlowEngineProvider must be supplied with an engine.');
@@ -32,7 +32,9 @@ export const FlowEngineProvider: React.FC<FlowEngineProviderProps> = (props) =>
       <FlowContextProvider context={engine.context}>{children}</FlowContextProvider>
     </FlowEngineReactContext.Provider>
   );
-};
+});
+
+FlowEngineProvider.displayName = 'FlowEngineProvider';
 
 export const FlowEngineGlobalsContextProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const { modal, message, notification } = App.useApp();
@@ -56,41 +58,43 @@ export const FlowEngineGlobalsContextProvider: React.FC<{ children: React.ReactN
       cache: false,
       get: (ctx) => new FlowViewer(ctx, { drawer, embed, popover, dialog }),
     });
-    // 将 themeToken 定义为 observable, 使组件能够响应主题的变更
-    engine.context.defineProperty('themeToken', {
-      get: () => token,
-      observable: true,
-      cache: true,
-    });
     for (const item of Object.entries(context)) {
       const [key, value] = item;
       if (value) {
         engine.context.defineProperty(key, { value });
       }
     }
+    // 将 themeToken 定义为 observable, 使组件能够响应主题的变更
+    // NOTE: 必须在 antdConfig 写入后再更新 themeToken；否则会读取到旧 antdConfig 的值。
+    engine.context.defineProperty('themeToken', {
+      get: () => token,
+      observable: true,
+      cache: true,
+    });
     engine.reactView.refresh();
   }, [engine, drawer, modal, message, notification, config, popover, token, dialog, embed]);
 
   return (
-    <>
+    <ConfigProvider {...config} locale={engine.context.locales?.antd} popupMatchSelectWidth={false}>
       {children}
       {contextHolder as any}
       {popoverContextHolder as any}
       {pageContextHolder as any}
       {dialogContextHolder as any}
       {/* The modal context is provided by App.useApp() */}
-    </>
+    </ConfigProvider>
   );
 };
-
-export const useFlowEngine = (): FlowEngine => {
+// 不 throw Error 怎么处理？
+export const useFlowEngine = ({ throwError = true } = {}): FlowEngine => {
   const context = useContext(FlowEngineReactContext);
-  if (!context) {
+  if (!context && throwError) {
     // This error should ideally not be hit if FlowEngineProvider is used correctly at the root
     // and always supplied with an engine.
-    throw new Error(
+    console.warn(
       'useFlowEngine must be used within a FlowEngineProvider, and FlowEngineProvider must be supplied with an engine.',
     );
+    return;
   }
   return context;
 };

package/src/reactive/__tests__/observer.test.tsx

@@ -0,0 +1,211 @@
+/**
+ * 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 React from 'react';
+import { render, screen, act } from '@testing-library/react';
+import { observer } from '../observer';
+import { useFlowContext } from '../../FlowContextProvider';
+import { observable } from '@formily/reactive';
+import { vi } from 'vitest';
+import { sleep } from '@nocobase/test/client';
+
+// Mock useFlowContext
+vi.mock('../../FlowContextProvider', async () => {
+  const actual = await vi.importActual('../../FlowContextProvider');
+  return {
+    ...actual,
+    useFlowContext: vi.fn(),
+  };
+});
+
+describe('observer', () => {
+  beforeEach(() => {
+    (useFlowContext as any).mockReturnValue({});
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should render component', () => {
+    const Component = observer(() => <div>Hello World</div>);
+    render(<Component />);
+    expect(screen.getByText('Hello World')).toBeInTheDocument();
+  });
+
+  it('should update when observable changes', async () => {
+    const model = observable({ count: 0 });
+    const Component = observer(() => <div>Count: {model.count}</div>);
+    render(<Component />);
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+    act(() => {
+      model.count++;
+    });
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+  });
+
+  it('should delay update when pageActive is false', async () => {
+    const model = observable({ count: 0 });
+    const pageActive = observable.ref(false);
+    const tabActive = observable.ref(true);
+
+    const context = {
+      pageActive: pageActive,
+      tabActive: tabActive,
+    };
+
+    (useFlowContext as any).mockReturnValue(context);
+
+    const Component = observer(() => <div>Count: {model.count}</div>);
+
+    render(<Component />);
+
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+    // Update model, but pageActive is false
+    act(() => {
+      model.count++;
+    });
+
+    await sleep(30);
+
+    // Should not update yet
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+    expect(screen.queryByText('Count: 1')).not.toBeInTheDocument();
+
+    // Now make pageActive true
+    act(() => {
+      pageActive.value = true;
+    });
+
+    await sleep(30);
+
+    // Should update now
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+  });
+
+  it('should delay update when tabActive is false', async () => {
+    const model = observable({ count: 0 });
+    const pageActive = observable.ref(true);
+    const tabActive = observable.ref(false);
+
+    const context = {
+      pageActive: pageActive,
+      tabActive: tabActive,
+    };
+
+    (useFlowContext as any).mockReturnValue(context);
+
+    const Component = observer(() => <div>Count: {model.count}</div>);
+
+    render(<Component />);
+
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+    // Update model, but tabActive is false
+    act(() => {
+      model.count++;
+    });
+
+    await sleep(30);
+
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+    expect(screen.queryByText('Count: 1')).not.toBeInTheDocument();
+
+    // Now make tabActive true
+    act(() => {
+      tabActive.value = true;
+    });
+
+    await sleep(30);
+
+    // Should update now
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+  });
+
+  it('should update immediately when pageActive and tabActive are true', async () => {
+    const model = observable({ count: 0 });
+    const pageActive = observable.ref(true);
+    const tabActive = observable.ref(true);
+
+    const context = {
+      pageActive: pageActive,
+      tabActive: tabActive,
+    };
+
+    (useFlowContext as any).mockReturnValue(context);
+
+    const Component = observer(() => <div>Count: {model.count}</div>);
+
+    render(<Component />);
+
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+    act(() => {
+      model.count++;
+    });
+
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+  });
+
+  it('should handle undefined tabActive as true (backward compatibility or default)', async () => {
+    const model = observable({ count: 0 });
+    const pageActive = observable.ref(true);
+    // tabActive is undefined in context
+
+    const context = {
+      pageActive: pageActive,
+    };
+
+    (useFlowContext as any).mockReturnValue(context);
+
+    const Component = observer(() => <div>Count: {model.count}</div>);
+
+    render(<Component />);
+
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+    act(() => {
+      model.count++;
+    });
+
+    await sleep(30);
+
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+  });
+
+  it('should respect view inputArgs for initial check', async () => {
+    const model = observable({ count: 0 });
+
+    const context = {
+      view: {
+        inputArgs: { pageActive: false },
+      },
+    };
+
+    (useFlowContext as any).mockReturnValue(context);
+
+    const Component = observer(() => <div>Count: {model.count}</div>);
+
+    render(<Component />);
+
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+    act(() => {
+      model.count++;
+    });
+
+    await sleep(30);
+
+    // Should NOT update because pageActive is false (from view.inputArgs)
+    expect(screen.getByText('Count: 0')).toBeInTheDocument();
+    expect(screen.queryByText('Count: 1')).not.toBeInTheDocument();
+  });
+});

package/src/reactive/index.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+
+export * from '@formily/reactive';
+export { observer, getPageActive } from './observer';

package/src/reactive/observer.tsx

@@ -0,0 +1,101 @@
+/**
+ * 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 { observer as originalObserver, IObserverOptions, ReactFC } from '@formily/reactive-react';
+import React, { useMemo, useEffect, useRef } from 'react';
+import { useFlowContext } from '../FlowContextProvider';
+import { autorun } from '@formily/reactive';
+import { FlowEngineContext } from '..';
+
+type ObserverComponentProps<P, Options extends IObserverOptions> = Options extends {
+  forwardRef: true;
+}
+  ? P & {
+      ref?: 'ref' extends keyof P ? P['ref'] : React.RefAttributes<any>;
+    }
+  : React.PropsWithoutRef<P>;
+
+export const observer = <P, Options extends IObserverOptions = IObserverOptions>(
+  Component: ReactFC<P>,
+  options?: Options,
+): React.MemoExoticComponent<ReactFC<ObserverComponentProps<P, Options>>> => {
+  const ComponentWithDefaultScheduler = React.memo((props: any) => {
+    const ctx = useFlowContext();
+    const ctxRef = useRef(ctx);
+    ctxRef.current = ctx;
+
+    // Store the pending disposer to avoid creating multiple listeners
+    const pendingDisposerRef = useRef<(() => void) | null>(null);
+
+    // Cleanup on unmount
+    useEffect(() => {
+      return () => {
+        if (pendingDisposerRef.current) {
+          pendingDisposerRef.current();
+          pendingDisposerRef.current = null;
+        }
+      };
+    }, []);
+
+    const ObservedComponent = useMemo(
+      () =>
+        originalObserver(Component, {
+          scheduler(updater) {
+            const pageActive = getPageActive(ctxRef.current);
+            const tabActive = ctxRef.current?.tabActive?.value;
+
+            if (pageActive === false || tabActive === false) {
+              // Avoid stack overflow
+              setTimeout(() => {
+                // If there is already a pending updater, do nothing
+                if (pendingDisposerRef.current) {
+                  return;
+                }
+
+                // Delay the update until the page and tab become active
+                const disposer = autorun(() => {
+                  if (
+                    ctxRef.current?.pageActive?.value &&
+                    (ctxRef.current?.tabActive?.value === true || ctxRef.current?.tabActive?.value === undefined)
+                  ) {
+                    updater();
+                    disposer?.();
+                    pendingDisposerRef.current = null;
+                  }
+                });
+                pendingDisposerRef.current = disposer;
+              });
+              return;
+            }
+
+            // If we are updating immediately, clear any pending disposer
+            if (pendingDisposerRef.current) {
+              pendingDisposerRef.current();
+              pendingDisposerRef.current = null;
+            }
+
+            updater();
+          },
+          ...options,
+        }),
+      [],
+    );
+    return <ObservedComponent {...props} />;
+  });
+
+  ComponentWithDefaultScheduler.displayName = `ComponentWithDefaultScheduler`;
+
+  return ComponentWithDefaultScheduler as React.MemoExoticComponent<ReactFC<ObserverComponentProps<P, Options>>>;
+};
+
+export function getPageActive(context: FlowEngineContext): boolean | undefined {
+  return typeof context?.pageActive?.value === 'boolean'
+    ? context?.pageActive?.value
+    : context?.view?.inputArgs.pageActive;
+}

package/src/resources/__tests__/multiRecordResource.test.ts

@@ -0,0 +1,44 @@
+/**
+ * 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, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { MultiRecordResource } from '../multiRecordResource';
+
+function createMultiRecordResource() {
+  const engine = new FlowEngine();
+  return engine.createResource(MultiRecordResource);
+}
+
+describe('MultiRecordResource - refresh', () => {
+  it('should coalesce multiple refresh calls and settle all awaiters', async () => {
+    vi.useFakeTimers();
+    try {
+      const r = createMultiRecordResource();
+      const api = {
+        request: vi.fn().mockResolvedValue({
+          data: { data: [], meta: { count: 0, page: 1, pageSize: 20 } },
+        }),
+      };
+
+      r.setAPIClient(api as any);
+      r.setResourceName('posts');
+
+      const p1 = r.refresh();
+      const p2 = r.refresh();
+
+      await vi.runAllTimersAsync();
+      await expect(p1).resolves.toBeUndefined();
+      await expect(p2).resolves.toBeUndefined();
+      expect(api.request).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/resources/__tests__/sqlResource.test.ts

@@ -0,0 +1,60 @@
+/**
+ * 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, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { SQLResource } from '../sqlResource';
+
+function createSQLResource() {
+  const engine = new FlowEngine();
+  return engine.createResource(SQLResource);
+}
+
+describe('SQLResource - refresh', () => {
+  it('should coalesce multiple refresh calls and settle all awaiters', async () => {
+    vi.useFakeTimers();
+    try {
+      const r = createSQLResource();
+      const run = vi.fn().mockResolvedValue({ data: { ok: 1 }, meta: { page: 1 } });
+      (r as any).run = run;
+
+      const p1 = r.refresh();
+      const p2 = r.refresh();
+
+      await vi.runAllTimersAsync();
+      await expect(p1).resolves.toBeUndefined();
+      await expect(p2).resolves.toBeUndefined();
+      expect(run).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('should reject all awaiters on failure', async () => {
+    vi.useFakeTimers();
+    try {
+      const r = createSQLResource();
+      const run = vi.fn().mockRejectedValue(new Error('boom'));
+      (r as any).run = run;
+
+      const p1 = r.refresh();
+      const p2 = r.refresh();
+
+      // Attach handlers before timers run to avoid unhandled rejection warnings.
+      const e1 = expect(p1).rejects.toThrow('boom');
+      const e2 = expect(p2).rejects.toThrow('boom');
+      await vi.runAllTimersAsync();
+      await e1;
+      await e2;
+      expect(run).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/resources/baseRecordResource.ts

@@ -12,6 +12,7 @@ import _ from 'lodash';
 import { APIResource } from './apiResource';
 import { FilterItem } from './filterItem';
 import { ResourceError } from './flowResource';
+import { DATA_SOURCE_DIRTY_EVENT } from '../views/viewEvents';
 
 export abstract class BaseRecordResource<TData = any> extends APIResource<TData> {
   protected resourceName: string;
@@ -95,6 +96,7 @@ export abstract class BaseRecordResource<TData = any> extends APIResource<TData>
   }
 
   async runAction<TData = any, TMeta = any>(action: string, options: any) {
+    const { rawResponse, ...rest } = options;
     const config = this.mergeRequestConfig(
       _.omit(this.request, ['params', 'data', 'method']),
       {
@@ -102,14 +104,18 @@ export abstract class BaseRecordResource<TData = any> extends APIResource<TData>
         url: this.buildURL(action),
       },
       this.runActionOptions?.[action],
-      options,
+      rest,
     );
     if (['create', 'update', 'firstOrCreate', 'updateOrCreate'].includes(action)) {
       config.params = config.params || {};
       config.params.updateAssociationValues = this.getUpdateAssociationValues();
     }
     try {
-      const { data } = await this.api.request(config);
+      const response = await this.api.request(config);
+      if (rawResponse) {
+        return response;
+      }
+      const { data } = response;
       if (!data?.data) {
         return data;
       }
@@ -131,6 +137,36 @@ export abstract class BaseRecordResource<TData = any> extends APIResource<TData>
     return this.resourceName;
   }
 
+  /**
+   * Mark current resource as dirty on the root FlowEngine.
+   * Used to coordinate "refresh on active" across view stacks.
+   */
+  protected markDataSourceDirty(resourceName?: string) {
+    const engine = this.context.engine;
+    if (!engine) return;
+
+    const dataSourceKey = this.getDataSourceKey() || 'main';
+    const resName = resourceName || this.getResourceName();
+    if (!resName) return;
+
+    const affectedResourceNames = new Set<string>([String(resName)]);
+    // Optional safety: association resources like "users.profile" may impact parent collection views.
+    if (typeof resName === 'string' && resName.includes('.')) {
+      affectedResourceNames.add(resName.split('.')[0]);
+    }
+
+    for (const name of affectedResourceNames) {
+      engine.markDataSourceDirty(dataSourceKey, name);
+    }
+
+    // Signal current view to re-evaluate dirty blocks (e.g., same-view sibling refresh).
+    // This is emitted on the *current* engine emitter (view-scoped) so it won't affect other views.
+    engine.emitter?.emit?.(DATA_SOURCE_DIRTY_EVENT, {
+      dataSourceKey,
+      resourceNames: Array.from(affectedResourceNames),
+    });
+  }
+
   setSourceId(sourceId: string | number) {
     this.sourceId = sourceId;
     return this;
@@ -227,8 +263,15 @@ export abstract class BaseRecordResource<TData = any> extends APIResource<TData>
     return this;
   }
 
+  jsonStringify(value: any): string {
+    if (value !== null && typeof value === 'object') {
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+
   setFilterByTk(filterByTk: any) {
-    return this.addRequestParameter('filterByTk', filterByTk);
+    return this.addRequestParameter('filterByTk', this.jsonStringify(filterByTk));
   }
 
   getFilterByTk(): any {