@nocobase/flow-engine 2.1.0-beta.37 → 2.1.0-beta.38

package/src/flowEngine.ts

@@ -39,6 +39,8 @@ import type {
 } from './types';
 import { isInheritedFrom } from './utils';
 
+const getFlowEngineLoggerLevel = () => (process.env.NODE_ENV === 'production' ? 'warn' : 'trace');
+
 /**
  * FlowEngine is the core class of the flow engine, responsible for managing flow models, actions, model repository, and more.
  * It provides capabilities for registering, creating, finding, persisting, replacing, and moving models.
@@ -213,7 +215,7 @@ export class FlowEngine {
       MultiRecordResource,
     });
     this.logger = pino({
-      level: 'trace',
+      level: getFlowEngineLoggerLevel(),
       browser: {
         write: {
           fatal: (o) => console.trace(o),
@@ -1009,7 +1011,6 @@ export class FlowEngine {
 
     while (current) {
       if (visited.has(current)) {
-        console.warn(`FlowEngine: resolveUse circular reference detected on '${current.name}'.`);
         break;
       }
       visited.add(current);
@@ -1128,7 +1129,7 @@ export class FlowEngine {
    */
   public removeModel(uid: string): boolean {
     if (!this._modelInstances.has(uid)) {
-      console.warn(`FlowEngine: Model with UID '${uid}' does not exist.`);
+      this.logger.debug(`FlowEngine: Model with UID '${uid}' does not exist.`);
       return false;
     }
     const modelInstance = this._modelInstances.get(uid) as FlowModel;

package/src/models/__tests__/flowEngine.resolveUse.test.ts

@@ -61,21 +61,6 @@ describe('FlowEngine.createModel resolveUse hook', () => {
     expect(warnSpy).not.toHaveBeenCalled();
   });
 
-  test('should break resolveUse on circular reference and warn', () => {
-    class LoopModel extends FlowModel {
-      static resolveUse() {
-        return 'LoopModel';
-      }
-    }
-
-    engine.registerModels({ LoopModel });
-
-    const model = engine.createModel({ use: 'LoopModel', uid: 'loop-model', flowEngine: engine });
-
-    expect(model).toBeInstanceOf(LoopModel);
-    expect(warnSpy).toHaveBeenCalled();
-  });
-
   test('should fall back to ErrorFlowModel when resolveUse returns unregistered name', () => {
     class MissingTargetEntry extends FlowModel {
       static resolveUse() {

package/src/models/__tests__/flowModel.test.ts

@@ -370,15 +370,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        const result = await model.applyFlow('exitFlow');
-
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should handle ctx.exit() as FlowExitAllException in beforeRender dispatch', async () => {
@@ -474,15 +476,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-        const result = await model.applyFlow('exitFlow');
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should propagate step execution errors', async () => {
@@ -796,7 +800,7 @@ describe('FlowModel', () => {
         const eventFlow = createEventFlowDefinition('testEvent');
         TestFlowModel.registerFlow(eventFlow);
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.dispatchEvent('testEvent', { data: 'payload' });
@@ -804,7 +808,7 @@ describe('FlowModel', () => {
           // Use a more reliable approach than arbitrary timeout
           await new Promise((resolve) => setTimeout(resolve, 0));
 
-          expect(consoleSpy).toHaveBeenCalledWith(
+          expect(loggerSpy).toHaveBeenCalledWith(
             expect.stringContaining('[FlowModel] dispatchEvent: uid=test-model-uid, event=testEvent'),
           );
           expect(eventFlow.steps.eventStep.handler).toHaveBeenCalledWith(
@@ -814,7 +818,7 @@ describe('FlowModel', () => {
             expect.any(Object),
           );
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
@@ -1625,7 +1629,7 @@ describe('FlowModel', () => {
         fork1.dispose = vi.fn();
         fork2.dispose = vi.fn();
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
@@ -1634,19 +1638,19 @@ describe('FlowModel', () => {
           expect(fork2.dispose).toHaveBeenCalled();
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
       test('should handle empty forks collection when clearing', () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
 
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1774,7 +1778,7 @@ describe('FlowModel', () => {
       test('should clean up resources on remove', () => {
         model.createFork();
         model.createFork();
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         // Mock removeModel to simulate proper fork cleanup
         flowEngine.removeModel = vi.fn().mockImplementation(() => {
@@ -1791,7 +1795,7 @@ describe('FlowModel', () => {
           expect(model.forks.size).toBe(0);
           expect(flowEngine.removeModel).toHaveBeenCalledWith(model.uid);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1868,17 +1872,12 @@ describe('FlowModel', () => {
       });
 
       test('should rerender triggers beforeRender without cache', async () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
         model.dispatchEvent = vi.fn().mockResolvedValue(undefined) as any;
 
-        try {
-          await expect(model.rerender()).resolves.not.toThrow();
-          expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
-            useCache: false,
-          });
-        } finally {
-          consoleSpy.mockRestore();
-        }
+        await expect(model.rerender()).resolves.not.toThrow();
+        expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
+          useCache: false,
+        });
       });
     });
 
@@ -2918,7 +2917,7 @@ describe('FlowModel', () => {
   describe('Edge Cases & Error Handling', () => {
     test('should handle model destruction gracefully', () => {
       const model = new FlowModel(modelOptions);
-      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
       model.createFork();
       model.setProps({ testProp: 'value' });
@@ -2926,7 +2925,7 @@ describe('FlowModel', () => {
       try {
         expect(() => model.remove()).not.toThrow();
       } finally {
-        consoleSpy.mockRestore();
+        loggerSpy.mockRestore();
       }
     });
 

package/src/models/flowModel.tsx

@@ -823,7 +823,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     }
     const isFork = (this as any).isFork === true;
     const target = this;
-    console.log(
+    currentFlowEngine.logger.debug(
       `[FlowModel] applyFlow: uid=${this.uid}, flowKey=${flowKey}, isFork=${isFork}, cleanRun=${
         this.cleanRun
       }, targetIsFork=${(target as any)?.isFork === true}`,
@@ -843,7 +843,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     }
     const isFork = (this as any).isFork === true;
     const target = this;
-    console.log(
+    currentFlowEngine.logger.debug(
       `[FlowModel] dispatchEvent: uid=${this.uid}, event=${eventName}, isFork=${isFork}, cleanRun=${
         this.cleanRun
       }, targetIsFork=${(target as any)?.isFork === true}`,
@@ -1379,7 +1379,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
   }
 
   clearForks() {
-    console.log(`FlowModel ${this.uid} clearing all forks.`);
+    this.flowEngine.logger.debug(`FlowModel ${this.uid} clearing all forks.`);
     // 主动使所有 fork 失效
     if (this.forks?.size) {
       this.forks.forEach((fork) => fork.dispose());

package/src/utils/__tests__/parsePathnameToViewParams.test.ts

@@ -102,6 +102,27 @@ describe('parsePathnameToViewParams', () => {
     expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }]);
   });
 
+  test('should parse custom root prefix', () => {
+    const result = parsePathnameToViewParams('/embed/xxx/tab/yyy/view/zzz', { rootPrefix: 'embed' });
+    expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should parse pathname by basePath', () => {
+    const result = parsePathnameToViewParams('/embed/xxx/tab/yyy/view/zzz', { basePath: '/embed' });
+    expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should parse pathname by nested basePath', () => {
+    const result = parsePathnameToViewParams('/admin/settings/public-forms/xxx/view/zzz', {
+      basePath: '/admin/settings/public-forms',
+    });
+    expect(result).toEqual([{ viewUid: 'xxx' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should keep admin as default root prefix', () => {
+    expect(parsePathnameToViewParams('/embed/xxx')).toEqual([]);
+  });
+
   test('should parse filterByTk from key-value encoded segment into object', () => {
     const kv = encodeURIComponent('id=1&tenant=ac');
     const path = `/admin/xxx/filterbytk/${kv}`;

package/src/utils/parsePathnameToViewParams.ts

@@ -18,6 +18,35 @@ export interface ViewParam {
   sourceId?: string;
 }
 
+export interface ParsePathnameToViewParamsOptions {
+  rootPrefix?: string;
+  basePath?: string;
+}
+
+const normalizePathname = (pathname: string) => {
+  if (!pathname || pathname === '/') {
+    return '/';
+  }
+  return `/${pathname.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+};
+
+const normalizeBasePath = (basePath: string) => `/${basePath.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+
+const stripBasePath = (pathname: string, basePath: string) => {
+  const normalizedPathname = normalizePathname(pathname);
+  const normalizedBasePath = normalizeBasePath(basePath);
+
+  if (normalizedPathname === normalizedBasePath) {
+    return '';
+  }
+
+  if (normalizedPathname.startsWith(`${normalizedBasePath}/`)) {
+    return normalizedPathname.slice(normalizedBasePath.length + 1);
+  }
+
+  return '';
+};
+
 /**
  * 解析路径名为视图参数数组
  *
@@ -33,15 +62,21 @@ export interface ViewParam {
  * parsePathnameToViewParams('/admin/xxx/view/yyy') // [{ viewUid: 'xxx' }, { viewUid: 'yyy' }]
  * ```
  */
-export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
+export const parsePathnameToViewParams = (
+  pathname: string,
+  options: ParsePathnameToViewParamsOptions = {},
+): ViewParam[] => {
   if (!pathname || pathname === '/') {
     return [];
   }
 
+  const rootPrefix = options.rootPrefix || 'admin';
+  const relativePath = options.basePath ? stripBasePath(pathname, options.basePath) : '';
+
   // 移除开头的斜杠并分割路径
-  const segments = pathname.replace(/^\/+/, '').split('/').filter(Boolean);
+  const segments = (options.basePath ? relativePath : pathname).replace(/^\/+/, '').split('/').filter(Boolean);
 
-  if (segments.length < 2) {
+  if (segments.length < (options.basePath ? 1 : 2)) {
     return [];
   }
 
@@ -49,11 +84,16 @@ export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
   let currentView: ViewParam | null = null;
   let i = 0;
 
+  if (options.basePath) {
+    currentView = { viewUid: segments[0] };
+    i = 1;
+  }
+
   while (i < segments.length) {
     const segment = segments[i];
 
-    // 处理 admin 或 view 关键字
-    if (segment === 'admin' || segment === 'view') {
+    // 处理布局根前缀或 view 关键字
+    if (segment === rootPrefix || segment === 'view') {
       // 如果有当前视图，先保存到结果中
       if (currentView) {
         result.push(currentView);

package/src/views/ViewNavigation.ts

@@ -13,6 +13,16 @@ import { ViewParam as SharedViewParam } from '../utils';
 
 type ViewParams = Omit<SharedViewParam, 'viewUid'> & { viewUid?: string };
 
+export interface GeneratePathnameFromViewParamsOptions {
+  prefix?: string;
+  basePath?: string;
+}
+
+export interface ViewNavigationOptions {
+  basePath?: string;
+  layoutBasePath?: string;
+}
+
 function encodeFilterByTk(val: SharedViewParam['filterByTk']): string {
   if (val === undefined || val === null) return '';
   // 1.x 兼容：对象按 key1=v1&key2=v2 拼接后整体 encodeURIComponent
@@ -30,6 +40,11 @@ function hasUsableSourceId(sourceId: unknown): sourceId is string | number {
   return sourceId !== undefined && sourceId !== null && String(sourceId) !== '';
 }
 
+function normalizeBasePath(basePath?: string) {
+  const value = basePath || '/admin';
+  return `/${value.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+}
+
 /**
  * 将 ViewParam 数组转换为 pathname
  *
@@ -43,12 +58,17 @@ function hasUsableSourceId(sourceId: unknown): sourceId is string | number {
  * generatePathnameFromViewParams([{ viewUid: 'xxx' }, { viewUid: 'yyy' }]) // '/admin/xxx/view/yyy'
  * ```
  */
-export function generatePathnameFromViewParams(viewParams: ViewParams[]): string {
+export function generatePathnameFromViewParams(
+  viewParams: ViewParams[],
+  options: GeneratePathnameFromViewParamsOptions = {},
+): string {
+  const basePath = normalizeBasePath(options.basePath || options.prefix);
+
   if (!viewParams || viewParams.length === 0) {
-    return '/admin';
+    return basePath;
   }
 
-  const segments = ['admin'];
+  const segments = basePath.replace(/^\/+/, '').split('/').filter(Boolean);
 
   viewParams.forEach((viewParam, index) => {
     // 如果不是第一个视图，添加 'view' 关键字
@@ -81,10 +101,12 @@ export class ViewNavigation {
   viewStack: ReadonlyArray<ViewParams>; // 只能通过 setViewStack 修改
   ctx: FlowEngineContext;
   viewParams: ViewParams;
+  private readonly basePath?: string;
 
-  constructor(ctx: FlowEngineContext, viewParams: ViewParams[]) {
+  constructor(ctx: FlowEngineContext, viewParams: ViewParams[], options: ViewNavigationOptions = {}) {
     this.setViewStack(viewParams);
     this.ctx = ctx;
+    this.basePath = options.basePath || options.layoutBasePath;
 
     define(this, {
       viewParams: observable,
@@ -106,7 +128,7 @@ export class ViewNavigation {
     });
 
     // 2. 根据 viewStack 生成新的 pathname
-    const newPathname = generatePathnameFromViewParams(newViewStack);
+    const newPathname = generatePathnameFromViewParams(newViewStack, { basePath: this.getLayoutBasePath() });
 
     // 3. 触发一次跳转。使用 replace 的方式
     this.ctx.router.navigate(newPathname, { replace: true });
@@ -115,7 +137,9 @@ export class ViewNavigation {
   navigateTo(viewParam: ViewParams, opts?: { replace?: boolean; state?: any }) {
     // 1. 基于当前 viewStack 生成一个 pathname
     // 2. 将当前传入的参数转为 path string
-    const newViewPathname = generatePathnameFromViewParams([...this.viewStack, viewParam]);
+    const newViewPathname = generatePathnameFromViewParams([...this.viewStack, viewParam], {
+      basePath: this.getLayoutBasePath(),
+    });
 
     // 3. 与 pathname 拼接成新的 pathname（这里直接使用新生成的 pathname）
     const newPathname = newViewPathname;
@@ -126,7 +150,16 @@ export class ViewNavigation {
 
   back() {
     const prevStack = this.viewStack.slice(0, -1);
-    const prevPath = generatePathnameFromViewParams(prevStack);
+    const prevPath = generatePathnameFromViewParams(prevStack, { basePath: this.getLayoutBasePath() });
     this.ctx.router.navigate(prevPath, { replace: true });
   }
+
+  private getLayoutBasePath() {
+    const routePath = (this.ctx as any).layout?.routePath;
+    return (
+      this.basePath ||
+      (this.ctx as any).layoutRoute?.basePathname ||
+      (routePath?.startsWith('/') ? routePath : '/admin')
+    );
+  }
 }

package/src/views/__tests__/ViewNavigation.test.ts

@@ -146,6 +146,47 @@ describe('ViewNavigation', () => {
 
       expect(mockCtx.router.navigate).toHaveBeenCalledWith('/admin', { replace: true });
     });
+
+    it('should use explicit basePath when navigating back', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }], { basePath: '/embed' });
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/embed', { replace: true });
+    });
+
+    it('should use layout route basePathname when explicit basePath is absent', () => {
+      mockCtx.layoutRoute = {
+        basePathname: '/mobile',
+      };
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/mobile', { replace: true });
+    });
+
+    it('should fall back to layout routePath when explicit basePath is absent', () => {
+      mockCtx.layout = {
+        routePath: '/mobile',
+      };
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/mobile', { replace: true });
+    });
+
+    it('should ignore relative layout routePath when runtime basePathname is absent', () => {
+      mockCtx.layout = {
+        routePath: 'public-forms',
+      };
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/admin', { replace: true });
+    });
   });
 });
 
@@ -160,6 +201,17 @@ describe('generatePathnameFromViewParams', () => {
     expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }])).toBe('/admin/xxx');
   });
 
+  it('should generate path with custom prefix', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }], { basePath: '/embed' })).toBe('/embed/xxx');
+    expect(generatePathnameFromViewParams([], { basePath: '/embed' })).toBe('/embed');
+  });
+
+  it('should generate path with nested basePath', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }], { basePath: '/admin/settings/public-forms' })).toBe(
+      '/admin/settings/public-forms/xxx',
+    );
+  });
+
   it('should generate view with tab', () => {
     expect(generatePathnameFromViewParams([{ viewUid: 'xxx', tabUid: 'yyy' }])).toBe('/admin/xxx/tab/yyy');
   });

package/src/views/__tests__/inheritLayoutContext.test.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 } from 'vitest';
+import { FlowContext } from '../../flowContext';
+import { inheritLayoutContextForDetachedView } from '../inheritLayoutContext';
+
+describe('inheritLayoutContextForDetachedView', () => {
+  it('inherits layout context for detached view contexts', () => {
+    const sourceContext = new FlowContext();
+    const engineContext = new FlowContext();
+    const layoutContext = new FlowContext();
+    const viewContext = new FlowContext();
+
+    engineContext.defineProperty('skipAclCheck', { value: false });
+    layoutContext.defineProperty('skipAclCheck', { value: true });
+    sourceContext.defineProperty('engine', {
+      value: {
+        context: engineContext,
+      },
+    });
+    sourceContext.defineProperty('layoutContext', { value: layoutContext });
+
+    viewContext.addDelegate(engineContext);
+    inheritLayoutContextForDetachedView(viewContext, sourceContext);
+
+    expect(viewContext.skipAclCheck).toBe(true);
+  });
+
+  it('does nothing when source context has no layout context', () => {
+    const sourceContext = new FlowContext();
+    const engineContext = new FlowContext();
+    const viewContext = new FlowContext();
+
+    engineContext.defineProperty('skipAclCheck', { value: false });
+    sourceContext.defineProperty('engine', {
+      value: {
+        context: engineContext,
+      },
+    });
+
+    viewContext.addDelegate(engineContext);
+    inheritLayoutContextForDetachedView(viewContext, sourceContext);
+
+    expect(viewContext.skipAclCheck).toBe(false);
+  });
+});