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

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

@@ -101,4 +101,29 @@ describe('parsePathnameToViewParams', () => {
     const result = parsePathnameToViewParams('///admin//xxx//tab//yyy//');
     expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }]);
   });
+
+  test('should parse filterByTk from key-value encoded segment into object', () => {
+    const kv = encodeURIComponent('id=1&tenant=ac');
+    const path = `/admin/xxx/filterbytk/${kv}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should parse filterByTk from JSON object segment', () => {
+    const json = encodeURIComponent('{"id":"1","tenant":"ac"}');
+    const path = `/admin/xxx/filterbytk/${json}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should keep non-object JSON (array/number) as string for filterByTk', () => {
+    const arr = encodeURIComponent('["a"]');
+    const num = encodeURIComponent('123');
+    const t = encodeURIComponent('true');
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${arr}`)).toEqual([
+      { viewUid: 'xxx', filterByTk: '["a"]' },
+    ]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${num}`)).toEqual([{ viewUid: 'xxx', filterByTk: '123' }]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${t}`)).toEqual([{ viewUid: 'xxx', filterByTk: 'true' }]);
+  });
 });

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

@@ -0,0 +1,38 @@
+/**
+ * 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, it, expect } from 'vitest';
+import { pruneFilter } from '../pruneFilter';
+
+describe('pruneFilter', () => {
+  it('keeps boolean false and number 0', () => {
+    const input = { a: { $eq: false }, b: { $eq: 0 } };
+    const out = pruneFilter(input);
+    expect(out).toEqual(input);
+  });
+
+  it('removes null/undefined/empty string and empty containers', () => {
+    const input = { a: null, b: undefined, c: '', d: [], e: {} } as any;
+    const out = pruneFilter(input);
+    expect(out).toBeUndefined();
+  });
+
+  it('works recursively with nested objects/arrays', () => {
+    const input = {
+      $and: [{ isRead: { $eq: false } }, { name: { $eq: '' } }, {}, [], { nested: { empty: {}, ok: 1 } }],
+    } as any;
+    const out = pruneFilter(input);
+    expect(out).toEqual({ $and: [{ isRead: { $eq: false } }, { nested: { ok: 1 } }] });
+  });
+
+  it('returns undefined for empty arrays/objects produced by pruning', () => {
+    expect(pruneFilter([null, undefined, '', [], {}] as any)).toBeUndefined();
+    expect(pruneFilter({ a: { b: '' } } as any)).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * 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 { beforeEach, describe, expect, it } from 'vitest';
+import { runjsRequireAsync } from '../runjsModuleLoader';
+import { __resetRunJSSafeGlobalsRegistryForTests, createSafeWindow } from '../safeGlobals';
+
+beforeEach(() => {
+  __resetRunJSSafeGlobalsRegistryForTests();
+});
+
+describe('runjsRequireAsync auto whitelist', () => {
+  it('should allow safeWindow to access globals introduced during requireAsync', async () => {
+    const key = '__nb_require_async_added_global__';
+    delete (window as any)[key];
+
+    const safeWin: any = createSafeWindow();
+    expect(() => safeWin[key]).toThrow(/not allowed/);
+
+    const requirejs: any = (deps: string[], onLoad: (...args: any[]) => void) => {
+      // Simulate a remote library attaching itself to the real window.
+      (window as any)[key] = { ok: true };
+      onLoad(undefined);
+    };
+
+    await runjsRequireAsync(requirejs, 'https://example.com/fake-lib.js');
+
+    expect(safeWin[key]).toEqual({ ok: true });
+
+    delete (window as any)[key];
+  });
+});

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

@@ -0,0 +1,159 @@
+/**
+ * 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, it, expect, vi } from 'vitest';
+import * as jsxTransform from '../../utils/jsxTransform';
+import { prepareRunJsCode, preprocessRunJsTemplates } from '../runjsTemplateCompat';
+
+describe('runjsTemplateCompat', () => {
+  describe('preprocessRunJsTemplates', () => {
+    it('hoists bare {{ }} placeholders into top-level resolved vars', () => {
+      const src = `const a = {{ctx.user.id}};`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`const a = __runjs_ctx_tpl_0;`);
+    });
+
+    it('replaces string literals containing {{ }} via split/join, without injecting await into nested functions', () => {
+      const src = `const s = '{{ctx.user.id}}';`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}")`);
+      expect(out).toContain(`.split("{{ctx.user.id}}").join(`);
+    });
+
+    it('does not transform arguments inside explicit ctx.resolveJsonTemplate(...) call', () => {
+      const src = `const v = await ctx.resolveJsonTemplate('{{ctx.user.id}}');\nconst s = '{{ctx.user.id}}';`;
+      const out = preprocessRunJsTemplates(src);
+      // inside call: keep raw
+      expect(out).toContain(`await ctx.resolveJsonTemplate('{{ctx.user.id}}')`);
+      // outside call: transform
+      expect(out).toContain(`__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}")`);
+    });
+
+    it('keeps template markers in comments unchanged', () => {
+      const src = `// {{ctx.user.id}}\nconst a = 1;`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toBe(src);
+    });
+
+    it('supports template literals containing {{ }}', () => {
+      const src = 'const s = `hi {{ctx.user.name}}`;';
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.name}}");`);
+      expect(out).toContain(`\`hi {{ctx.user.name}}\``);
+      expect(out).toContain(`.split("{{ctx.user.name}}").join(`);
+    });
+
+    it('does not rewrite non-ctx {{ }} patterns (e.g. JSX style object) while still rewriting ctx placeholders', () => {
+      const src = `const id = {{ctx.user.id}};\nctx.render(<div style={{ width: '100%' }} />);`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`style={{ width: '100%' }}`);
+      expect(out).not.toContain(`resolveJsonTemplate("{{ width: '100%' }}")`);
+    });
+
+    it('avoids injecting await into non-async nested function bodies', () => {
+      const src = `
+function f() {
+  return {{ctx.user.id}};
+}
+return f();
+`.trim();
+      const out = preprocessRunJsTemplates(src);
+      // The only await should be in the top-level preamble
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`return __runjs_ctx_tpl_0;`);
+      expect(out).not.toContain(`return (await ctx.resolveJsonTemplate`);
+    });
+
+    it('is tolerant to already-preprocessed code (idempotent heuristic)', () => {
+      const src =
+        `const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");\n` +
+        `const s = ("{{ctx.user.id}}").split("{{ctx.user.id}}").join(__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}"));`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toBe(src);
+    });
+
+    it('rewrites object literal string keys via computed property to keep syntax valid', () => {
+      const src = `const o = { '{{ctx.user.id}}': 1 };`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`{ [`);
+      expect(out).toContain(`]: 1 }`);
+      expect(out).toContain(`.split("{{ctx.user.id}}").join(`);
+    });
+  });
+
+  describe('prepareRunJsCode', () => {
+    it('preprocesses templates and compiles JSX', async () => {
+      const src = `
+const name = '{{ctx.user.name}}';
+ctx.render(<div className="x">{name}</div>);
+`.trim();
+      const out = await prepareRunJsCode(src, { preprocessTemplates: true });
+      expect(out).toMatch(/ctx\.React\.createElement/);
+      expect(out).toMatch(/ctx\.resolveJsonTemplate/);
+    });
+
+    it('injects ctx.libs ensure preamble for member access', async () => {
+      const src = `return ctx.libs.lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`/* __runjs_ensure_libs */`);
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for bracket access with string literal', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for object destructuring', async () => {
+      const src = `const { lodash } = ctx.libs;\nreturn lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('does not inject ctx.libs preamble when ctx.libs only appears in string/comment', async () => {
+      const src = `// ctx.libs.lodash\nconst s = "ctx.libs.lodash";\nreturn s;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).not.toContain(`__runjs_ensure_libs`);
+    });
+
+    it('is idempotent for already-prepared code', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out1 = await prepareRunJsCode(src, { preprocessTemplates: false });
+      const out2 = await prepareRunJsCode(out1, { preprocessTemplates: false });
+      expect(out2).toBe(out1);
+      expect(out2.match(/__runjs_ensure_libs/g)?.length ?? 0).toBe(1);
+    });
+
+    it('does not break JSX attribute string values when preprocessing templates', async () => {
+      const src = `ctx.render(<Input title="{{ctx.user.name}}" />);`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: true });
+      expect(out).toMatch(/ctx\.React\.createElement/);
+      expect(out).toMatch(/title:\s*\(/);
+      expect(out).toContain(`.split("{{ctx.user.name}}").join(`);
+    });
+
+    it('caches prepared code by source and preprocessTemplates option', async () => {
+      const spy = vi.spyOn(jsxTransform, 'compileRunJs');
+      const src = `/* cache-test */\nconst a = 1;\nreturn a;`;
+
+      await prepareRunJsCode(src, { preprocessTemplates: false });
+      await prepareRunJsCode(src, { preprocessTemplates: false });
+      await prepareRunJsCode(src, { preprocessTemplates: true });
+      await prepareRunJsCode(src, { preprocessTemplates: true });
+
+      expect(spy).toHaveBeenCalledTimes(2);
+      spy.mockRestore();
+    });
+  });
+});

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

@@ -7,8 +7,19 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, expect, it } from 'vitest';
-import { createSafeDocument, createSafeWindow } from '../safeGlobals';
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  __resetRunJSSafeGlobalsRegistryForTests,
+  createSafeDocument,
+  createSafeNavigator,
+  createSafeWindow,
+  registerRunJSSafeDocumentGlobals,
+  registerRunJSSafeWindowGlobals,
+} from '../safeGlobals';
+
+beforeEach(() => {
+  __resetRunJSSafeGlobalsRegistryForTests();
+});
 
 describe('safeGlobals', () => {
   it('createSafeWindow exposes only allowed globals and extras', () => {
@@ -16,14 +27,80 @@ describe('safeGlobals', () => {
     expect(typeof win.setTimeout).toBe('function');
     expect(win.console).toBeDefined();
     expect(win.foo).toBe(123);
+    expect(new win.FormData()).toBeInstanceOf(window.FormData);
+    if (typeof window.Blob !== 'undefined') {
+      expect(typeof win.Blob).toBe('function');
+      expect(new win.Blob(['x'])).toBeInstanceOf(window.Blob);
+    }
+    if (typeof window.URL !== 'undefined') {
+      expect(win.URL).toBe(window.URL);
+      expect(typeof win.URL.createObjectURL).toBe('function');
+    }
     // access to location proxy is allowed, but sensitive props throw
     expect(() => win.location.href).toThrow(/not allowed/);
   });
 
+  it('createSafeWindow allows writing new props and reading them back', () => {
+    const win: any = createSafeWindow();
+    win.someLib = { ok: true };
+    expect(win.someLib).toEqual({ ok: true });
+    expect('someLib' in win).toBe(true);
+  });
+
+  it('createSafeWindow can access dynamically registered globals from real window', () => {
+    const key = '__nb_safe_window_global__';
+    (window as any)[key] = { v: 1 };
+    registerRunJSSafeWindowGlobals([key]);
+
+    const win: any = createSafeWindow();
+    expect(win[key]).toEqual({ v: 1 });
+
+    delete (window as any)[key];
+  });
+
   it('createSafeDocument exposes whitelisted methods and extras', () => {
     const doc: any = createSafeDocument({ bar: true });
     expect(typeof doc.createElement).toBe('function');
     expect(doc.bar).toBe(true);
     expect(() => doc.cookie).toThrow(/not allowed/);
   });
+
+  it('createSafeDocument allows writing new props and reading them back', () => {
+    const doc: any = createSafeDocument();
+    doc.someLib = { ok: true };
+    expect(doc.someLib).toEqual({ ok: true });
+    expect('someLib' in doc).toBe(true);
+  });
+
+  it('createSafeDocument can access dynamically registered globals from real document', () => {
+    const key = '__nb_safe_document_global__';
+    (document as any)[key] = 123;
+    registerRunJSSafeDocumentGlobals([key]);
+
+    const doc: any = createSafeDocument();
+    expect(doc[key]).toBe(123);
+
+    delete (document as any)[key];
+  });
+
+  it('createSafeNavigator exposes limited props and guards others', () => {
+    const nav: any = createSafeNavigator();
+    // clipboard object should always exist
+    expect(typeof nav.clipboard).toBe('object');
+    // writeText may or may not exist depending on environment
+    if (typeof navigator !== 'undefined' && (navigator as any).clipboard?.writeText) {
+      expect(typeof nav.clipboard.writeText).toBe('function');
+    } else {
+      expect(typeof nav.clipboard.writeText === 'undefined' || typeof nav.clipboard.writeText === 'function').toBe(
+        true,
+      );
+    }
+    // readable properties
+    expect(() => void nav.onLine).not.toThrow();
+    expect(() => void nav.language).not.toThrow();
+    expect(() => void nav.languages).not.toThrow();
+    // blocked properties
+    expect(() => (nav as any).geolocation).toThrow(/not allowed/);
+    expect(() => (nav as any).userAgent).toThrow(/not allowed/);
+  });
 });

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

@@ -13,6 +13,7 @@ import {
   isInheritedFrom,
   resolveDefaultParams,
   resolveStepUiSchema,
+  shouldHideStepInSettings,
   FlowExitException,
   defineAction,
   compileUiSchema,
@@ -30,6 +31,7 @@ import type {
   StepDefinition,
 } from '../../types';
 import { FlowRuntimeContext } from '../../flowContext';
+import { ContextPathProxy } from '../../ContextPathProxy';
 
 // Helper functions
 const createMockFlowEngine = (): FlowEngine => {
@@ -996,26 +998,123 @@ describe('Utils', () => {
 
         consoleSpy.mockRestore();
       });
+    });
+  });
 
-      test('should handle missing getAction method', async () => {
-        // Mock a flowEngine without getAction method
-        const originalGetAction = mockModel.flowEngine.getAction;
-        mockModel.flowEngine.getAction = undefined;
+  // ==================== shouldHideStepInSettings() FUNCTION ====================
+  describe('shouldHideStepInSettings()', () => {
+    let mockFlow: any;
+    let mockStep: StepDefinition;
 
-        mockStep.use = 'testAction';
-        mockStep.uiSchema = {
-          field1: { type: 'string', title: 'Field 1' },
-        };
+    beforeEach(() => {
+      mockFlow = {
+        key: 'testFlow',
+        title: 'Test Flow',
+        steps: {},
+      };
 
-        const result = await resolveStepUiSchema(mockModel, mockFlow, mockStep);
+      mockStep = {
+        key: 'testStep',
+        handler: vi.fn(),
+      };
+    });
 
-        expect(result).toEqual({
-          field1: { type: 'string', title: 'Field 1' },
-        });
+    test('returns true when step is falsy', async () => {
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, null);
+      expect(result).toBe(true);
+    });
 
-        // Restore the original method
-        mockModel.flowEngine.getAction = originalGetAction;
-      });
+    test('respects static step.hideInSettings=true', async () => {
+      mockStep.hideInSettings = true;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(result).toBe(true);
+    });
+
+    test('respects static step.hideInSettings=false', async () => {
+      mockStep.hideInSettings = false;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(result).toBe(false);
+    });
+
+    test('falls back to action.hideInSettings when step.hideInSettings is undefined', async () => {
+      const action: ActionDefinition = {
+        name: 'testAction',
+        handler: vi.fn(),
+        hideInSettings: true,
+      } as any;
+
+      mockStep.use = 'testAction';
+      mockModel.flowEngine.getAction = vi.fn().mockReturnValue(action);
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(mockModel.flowEngine.getAction).toHaveBeenCalledWith('testAction');
+      expect(result).toBe(true);
+    });
+
+    test('prefers step.hideInSettings over action.hideInSettings', async () => {
+      const action: ActionDefinition = {
+        name: 'testAction',
+        handler: vi.fn(),
+        hideInSettings: true,
+      } as any;
+
+      mockStep.use = 'testAction';
+      mockStep.hideInSettings = false;
+      mockModel.flowEngine.getAction = vi.fn().mockReturnValue(action);
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+      expect(result).toBe(false);
+    });
+
+    test('evaluates function step.hideInSettings with FlowRuntimeContext', async () => {
+      const hideFn = vi.fn().mockResolvedValue(true);
+      mockStep.hideInSettings = hideFn as any;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+
+      expect(hideFn).toHaveBeenCalledTimes(1);
+      const ctx = hideFn.mock.calls[0][0] as FlowRuntimeContext;
+      expect(ctx).toBeInstanceOf(FlowRuntimeContext);
+      expect((ctx as any).model).toBe(mockModel);
+      expect((ctx as any).flowKey).toBe('testFlow');
+      expect((ctx as any).mode).toBe('settings');
+      expect((ctx as any).currentStep).toBeInstanceOf(ContextPathProxy);
+      expect(String((ctx as any).currentStep)).toBe('{{ctx.currentStep}}');
+      expect(result).toBe(true);
+    });
+
+    test('evaluates function action.hideInSettings when step.hideInSettings is undefined', async () => {
+      const hideFn = vi.fn().mockResolvedValue(false);
+      const action: ActionDefinition = {
+        name: 'testAction',
+        handler: vi.fn(),
+        hideInSettings: hideFn as any,
+      } as any;
+
+      mockStep.use = 'testAction';
+      mockModel.flowEngine.getAction = vi.fn().mockReturnValue(action);
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+
+      expect(hideFn).toHaveBeenCalledTimes(1);
+      const ctx = hideFn.mock.calls[0][0] as FlowRuntimeContext;
+      expect((ctx as any).currentStep).toBeInstanceOf(ContextPathProxy);
+      expect(String((ctx as any).currentStep)).toBe('{{ctx.currentStep}}');
+      expect(result).toBe(false);
+    });
+
+    test('returns false and logs warning when function hideInSettings throws', async () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const hideFn = vi.fn().mockRejectedValue(new Error('boom'));
+      mockStep.hideInSettings = hideFn as any;
+
+      const result = await shouldHideStepInSettings(mockModel, mockFlow, mockStep);
+
+      expect(consoleSpy).toHaveBeenCalled();
+      expect(result).toBe(false);
+      consoleSpy.mockRestore();
     });
   });
 });

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

@@ -11,9 +11,11 @@ import { describe, expect, it } from 'vitest';
 import {
   collectContextParamsForTemplate,
   createRecordMetaFactory,
+  createRecordResolveOnServerWithLocal,
   inferParentRecordRef,
   inferRecordRef,
 } from '../variablesParams';
+import { FlowEngine, SingleRecordResource } from '../..';
 
 describe('variablesParams helpers', () => {
   it('inferRecordRef and inferParentRecordRef from FlowContext-like object', () => {
@@ -30,6 +32,29 @@ describe('variablesParams helpers', () => {
     expect(inferParentRecordRef(ctx)).toEqual({ collection: 'posts', dataSourceKey: 'main', filterByTk: 9 });
   });
 
+  it('inferRecordRef fallback to collection.getFilterByTK when resource has no filterByTk', () => {
+    const engine = new FlowEngine();
+    const ds = engine.context.dataSourceManager.getDataSource('main')!;
+    ds.addCollection({
+      name: 'users',
+      filterTargetKey: 'id',
+      fields: [
+        { name: 'id', type: 'integer', interface: 'number' },
+        { name: 'roles', type: 'belongsToMany', target: 'roles', interface: 'm2m' },
+      ],
+    });
+    const collection = ds.getCollection('users');
+    const resource = engine.context.createResource(SingleRecordResource);
+    resource.setResourceName('main.users');
+    // 不设置 filterByTk，模拟资源无 filter 时的 fallback
+    const ctx: any = engine.context;
+    ctx.defineProperty('resource', { value: resource });
+    ctx.defineProperty('collection', { value: collection });
+    ctx.defineProperty('record', { value: { id: 5 } });
+
+    expect(inferRecordRef(ctx)).toEqual({ collection: 'users', dataSourceKey: 'main', filterByTk: 5 });
+  });
+
   it('collectContextParamsForTemplate builds input for used variables only', async () => {
     const ctx: any = {
       getPropertyOptions: (k: string) => ({
@@ -49,4 +74,99 @@ describe('variablesParams helpers', () => {
     expect(res).toHaveProperty('record');
     expect(res).not.toHaveProperty('user');
   });
+
+  it('collectContextParamsForTemplate keeps associationName/sourceId from RecordRef', async () => {
+    const ctx: any = {
+      getPropertyOptions: (k: string) => ({
+        meta:
+          k === 'popup'
+            ? async () => ({
+                type: 'object',
+                title: 'Popup',
+                buildVariablesParams: () => ({
+                  record: {
+                    collection: 'posts',
+                    dataSourceKey: 'main',
+                    filterByTk: 1,
+                    associationName: 'users.posts',
+                    sourceId: 9,
+                  },
+                }),
+              })
+            : undefined,
+      }),
+    };
+
+    const tpl = { value: '{{ ctx.popup.record.id }}' } as any;
+    const res = await collectContextParamsForTemplate(ctx, tpl);
+    expect(res?.['popup.record']).toMatchObject({
+      collection: 'posts',
+      dataSourceKey: 'main',
+      filterByTk: 1,
+      associationName: 'users.posts',
+      sourceId: 9,
+    });
+  });
+
+  it('createRecordResolveOnServerWithLocal: no local record => always use server', () => {
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => ({ name: 'posts', dataSourceKey: 'main' }) as any,
+      () => undefined,
+    );
+    expect(resolver('')).toBe(true);
+    expect(resolver('title')).toBe(true);
+    expect(resolver('author.name')).toBe(true);
+  });
+
+  it('createRecordResolveOnServerWithLocal: local record + non-association subpaths => use local', () => {
+    const collection: any = {
+      getField: (name: string) => {
+        if (name === 'id') return { name: 'id', isAssociationField: () => false };
+        if (name === 'title') return { name: 'title', isAssociationField: () => false };
+        return undefined;
+      },
+    };
+    const record = { id: 1, title: 'Hello' };
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => collection,
+      () => record,
+    );
+    expect(resolver('')).toBe(false);
+    expect(resolver('id')).toBe(false);
+    expect(resolver('title')).toBe(false);
+  });
+
+  it('createRecordResolveOnServerWithLocal: association with local value => still use local', () => {
+    const collection: any = {
+      getField: (name: string) => {
+        if (name === 'author') return { name: 'author', isAssociationField: () => true };
+        if (name === 'title') return { name: 'title', isAssociationField: () => false };
+        return undefined;
+      },
+    };
+    const record = { title: 'Hello', author: { id: 1, name: 'Alice' } };
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => collection,
+      () => record,
+    );
+    expect(resolver('author')).toBe(false);
+    expect(resolver('author.name')).toBe(false);
+  });
+
+  it('createRecordResolveOnServerWithLocal: association without local value => use server', () => {
+    const collection: any = {
+      getField: (name: string) => {
+        if (name === 'author') return { name: 'author', isAssociationField: () => true };
+        if (name === 'title') return { name: 'title', isAssociationField: () => false };
+        return undefined;
+      },
+    };
+    const record = { title: 'Hello', author: null };
+    const resolver = createRecordResolveOnServerWithLocal(
+      () => collection,
+      () => record,
+    );
+    expect(resolver('author')).toBe(true);
+    expect(resolver('author.name')).toBe(true);
+  });
 });