@nocobase/flow-engine 2.0.0-alpha.32 → 2.0.0-alpha.34

package/lib/components/variables/VariableInput.js

@@ -144,7 +144,7 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
   }, [currentMetaTreeNode, innerValue, resolvedMetaTree, resolvePathFromValue]);
   (0, import_react.useEffect)(() => {
     const restoreFromValue = /* @__PURE__ */ __name(async () => {
-      if (!Array.isArray(resolvedMetaTree) || !value) return;
+      if (!Array.isArray(resolvedMetaTree) || value == null) return;
       if (currentMetaTreeNode) {
         return;
       }
@@ -197,7 +197,7 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
   }, [renderInputComponent, resolvedMetaTreeNode, innerValue]);
   (0, import_react.useEffect)(() => {
     if (!resolvedMetaTreeNode) return;
-    if (!Array.isArray(resolvedMetaTree) || !innerValue) return;
+    if (!Array.isArray(resolvedMetaTree) || innerValue == null) return;
     const finalValue = (resolveValueFromPath == null ? void 0 : resolveValueFromPath(resolvedMetaTreeNode)) || innerValue;
     emitChange(finalValue, resolvedMetaTreeNode);
     setCurrentMetaTreeNode(resolvedMetaTreeNode);
@@ -265,7 +265,7 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
   }, [restProps]);
   const inputProps = (0, import_react.useMemo)(() => {
     const baseProps = {
-      value: innerValue || "",
+      value: innerValue ?? "",
       onChange: handleInputChange,
       disabled
     };

package/lib/flowContext.d.ts

@@ -72,6 +72,7 @@ export interface PropertyOptions {
     observable?: boolean;
     meta?: PropertyMetaOrFactory;
     resolveOnServer?: boolean | ((subPath: string) => boolean);
+    serverOnlyWhenContextParams?: boolean;
 }
 type RouteOptions = {
     name?: string;

package/lib/flowContext.js

@@ -772,6 +772,16 @@ const _FlowEngineContext = class _FlowEngineContext extends BaseFlowEngineContex
         const inputFromMeta = await collectFromMeta();
         const autoInput = { ...inputFromMeta };
         const autoContextParams = Object.keys(autoInput).length ? (0, import_serverContextParams.buildServerContextParams)(this, autoInput) : void 0;
+        if (!autoContextParams) {
+          const keys = Object.keys(serverVarPaths);
+          const allOptional = keys.length > 0 && keys.every((k) => {
+            var _a2;
+            return (_a2 = this.getPropertyOptions(k)) == null ? void 0 : _a2.serverOnlyWhenContextParams;
+          });
+          if (allOptional) {
+            return (0, import_utils.resolveExpressions)(template, this);
+          }
+        }
         if (this.api) {
           try {
             serverResolved = await (0, import_params_resolvers.enqueueVariablesResolve)(this, {

package/lib/models/forkFlowModel.d.ts

@@ -58,6 +58,10 @@ export declare class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
      * 修改局部 props，仅影响当前 fork
      */
     setProps(key: string | IModelComponentProps, value?: any): void;
+    /**
+     * 清理局部 props，仅影响当前 fork
+     */
+    clearProps(): {};
     /**
      * render 依旧使用 master 的方法，但合并后的 props 需要透传
      */

package/lib/models/forkFlowModel.js

@@ -179,6 +179,12 @@ const _ForkFlowModel = class _ForkFlowModel {
       this.localProps = { ...this.localProps, ...key };
     }
   }
+  /**
+   * 清理局部 props，仅影响当前 fork
+   */
+  clearProps() {
+    return this.localProps = {};
+  }
   /**
    * render 依旧使用 master 的方法，但合并后的 props 需要透传
    */

package/lib/resources/multiRecordResource.js

@@ -178,6 +178,11 @@ const _MultiRecordResource = class _MultiRecordResource extends import_baseRecor
       options
     );
     await this.runAction("destroy", config);
+    const currentPage = this.getPage();
+    const lastPage = Math.ceil((this.getCount() - import_lodash.default.castArray(filterByTk).length) / this.getPageSize());
+    if (currentPage > lastPage) {
+      this.setPage(lastPage);
+    }
     await this.refresh();
   }
   setItem(index, newDataItem) {

package/lib/utils/associationObjectVariable.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 type { Collection } from '../data-source';
+import type { FlowContext, PropertyMetaFactory } from '../flowContext';
+/**
+ * 创建一个用于“对象类变量”（如 formValues / currentObject）的 `resolveOnServer` 判定函数。
+ * 仅当访问路径以“关联字段名”开头（且继续访问其子属性）时，返回 true 交由服务端解析；
+ * 否则在前端解析即可。
+ *
+ * @param collectionAccessor 返回当前对象所在collection
+ * @returns `(subPath) => boolean` 判断是否需要服务端解析
+ */
+export declare function createAssociationSubpathResolver(collectionAccessor: () => Collection | null): (subPath: string) => boolean;
+/**
+ * 构建“对象类变量”的 PropertyMetaFactory：
+ * - 暴露集合字段结构（通过 createCollectionContextMeta）用于变量选择器；
+ * - 提供 buildVariablesParams：基于对象当前值，收集所有“已选择的关联字段”
+ *   以便服务端在 variables:resolve 时按需补全关联数据。
+ *
+ * @param collectionAccessor 获取集合对象，用于字段/元信息来源
+ * @param title 变量组标题（用于 UI 展示）
+ * @param valueAccessor 获取当前对象值（如 ctx.form.getFieldsValue() / ctx.currentObject）
+ * @returns PropertyMetaFactory
+ */
+export declare function createAssociationAwareObjectMetaFactory(collectionAccessor: () => Collection | null, title: string, valueAccessor: (ctx: FlowContext) => any): PropertyMetaFactory;

package/lib/utils/associationObjectVariable.js

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var associationObjectVariable_exports = {};
+__export(associationObjectVariable_exports, {
+  createAssociationAwareObjectMetaFactory: () => createAssociationAwareObjectMetaFactory,
+  createAssociationSubpathResolver: () => createAssociationSubpathResolver
+});
+module.exports = __toCommonJS(associationObjectVariable_exports);
+var import_createCollectionContextMeta = require("./createCollectionContextMeta");
+function baseFieldNameOf(subPath) {
+  if (!subPath) return void 0;
+  const m = subPath.match(/^([^.[]+)/);
+  return m == null ? void 0 : m[1];
+}
+__name(baseFieldNameOf, "baseFieldNameOf");
+function findFieldByName(collection, name) {
+  var _a;
+  if (!collection || !name) return void 0;
+  const direct = collection.getField(name);
+  if (direct) return direct;
+  const fields = ((_a = collection.getFields) == null ? void 0 : _a.call(collection)) || [];
+  return fields.find((f) => f.name === name);
+}
+__name(findFieldByName, "findFieldByName");
+function toFilterByTk(value, primaryKey) {
+  if (value == null) return void 0;
+  if (Array.isArray(primaryKey)) {
+    if (typeof value !== "object" || !value) return void 0;
+    const out = {};
+    for (const k of primaryKey) {
+      const v = value[k];
+      if (typeof v === "undefined" || v === null) return void 0;
+      out[k] = v;
+    }
+    return out;
+  }
+  if (typeof value === "string" || typeof value === "number") return value;
+  if (typeof value === "object") {
+    return value[primaryKey];
+  }
+  return void 0;
+}
+__name(toFilterByTk, "toFilterByTk");
+function createAssociationSubpathResolver(collectionAccessor) {
+  return (p) => {
+    if (!p || !p.includes(".")) return false;
+    const base = baseFieldNameOf(p);
+    if (!base) return false;
+    const collection = collectionAccessor();
+    const field = findFieldByName(collection, base);
+    return !!(field == null ? void 0 : field.isAssociationField());
+  };
+}
+__name(createAssociationSubpathResolver, "createAssociationSubpathResolver");
+function createAssociationAwareObjectMetaFactory(collectionAccessor, title, valueAccessor) {
+  const baseFactory = (0, import_createCollectionContextMeta.createCollectionContextMeta)(collectionAccessor, title);
+  const factory = /* @__PURE__ */ __name(async () => {
+    const base = await baseFactory();
+    if (!base) return null;
+    const meta = {
+      ...base,
+      buildVariablesParams: /* @__PURE__ */ __name((ctx) => {
+        var _a;
+        const collection = collectionAccessor();
+        const obj = valueAccessor(ctx);
+        if (!collection || !obj || typeof obj !== "object") return {};
+        const params = {};
+        const fields = ((_a = collection.getFields) == null ? void 0 : _a.call(collection)) || [];
+        for (const field of fields) {
+          const name = field.name;
+          if (!name) continue;
+          if (!field.isAssociationField()) continue;
+          const target = field.target;
+          const targetCollection = field.targetCollection;
+          if (!target || !targetCollection) continue;
+          const primaryKey = targetCollection.filterTargetKey;
+          const associationValue = obj[name];
+          if (associationValue == null) continue;
+          if (Array.isArray(associationValue)) {
+            const ids = associationValue.map((item) => toFilterByTk(item, primaryKey)).filter((v) => v != null);
+            if (ids.length) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: ids
+              };
+            }
+          } else {
+            const id = toFilterByTk(associationValue, primaryKey);
+            if (id != null) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: id
+              };
+            }
+          }
+        }
+        return params;
+      }, "buildVariablesParams")
+    };
+    return meta;
+  }, "factory");
+  factory.title = title;
+  return factory;
+}
+__name(createAssociationAwareObjectMetaFactory, "createAssociationAwareObjectMetaFactory");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAssociationAwareObjectMetaFactory,
+  createAssociationSubpathResolver
+});

package/lib/utils/index.d.ts

@@ -15,9 +15,11 @@ export { resolveCreateModelOptions, resolveDefaultParams, resolveExpressions } f
 export { compileUiSchema, resolveStepUiSchema, resolveUiMode } from './schema-utils';
 export { setupRuntimeContextSteps } from './setupRuntimeContextSteps';
 export { createCollectionContextMeta } from './createCollectionContextMeta';
+export { createAssociationAwareObjectMetaFactory, createAssociationSubpathResolver } from './associationObjectVariable';
 export { buildRecordMeta, collectContextParamsForTemplate, createCurrentRecordMetaFactory, createRecordMetaFactory, extractUsedVariableNames, extractUsedVariablePaths, inferRecordRef, type RecordParamsBuilder, } from './variablesParams';
 export { extractPropertyPath, formatPathToVariable, isVariableExpression } from './context';
 export { clearAutoFlowError, getAutoFlowError, setAutoFlowError, type AutoFlowError } from './autoFlowError';
 export { parsePathnameToViewParams, type ViewParam } from './parsePathnameToViewParams';
 export { buildSettingsViewInputArgs } from './buildSettingsViewInputArgs';
 export { createSafeDocument, createSafeWindow, createSafeNavigator } from './safeGlobals';
+export { pruneFilter } from './pruneFilter';

package/lib/utils/index.js

@@ -36,6 +36,8 @@ __export(utils_exports, {
   clearAutoFlowError: () => import_autoFlowError.clearAutoFlowError,
   collectContextParamsForTemplate: () => import_variablesParams.collectContextParamsForTemplate,
   compileUiSchema: () => import_schema_utils.compileUiSchema,
+  createAssociationAwareObjectMetaFactory: () => import_associationObjectVariable.createAssociationAwareObjectMetaFactory,
+  createAssociationSubpathResolver: () => import_associationObjectVariable.createAssociationSubpathResolver,
   createCollectionContextMeta: () => import_createCollectionContextMeta.createCollectionContextMeta,
   createCurrentRecordMetaFactory: () => import_variablesParams.createCurrentRecordMetaFactory,
   createRecordMetaFactory: () => import_variablesParams.createRecordMetaFactory,
@@ -54,6 +56,7 @@ __export(utils_exports, {
   isInheritedFrom: () => import_inheritance.isInheritedFrom,
   isVariableExpression: () => import_context.isVariableExpression,
   parsePathnameToViewParams: () => import_parsePathnameToViewParams.parsePathnameToViewParams,
+  pruneFilter: () => import_pruneFilter.pruneFilter,
   resolveCreateModelOptions: () => import_params_resolvers.resolveCreateModelOptions,
   resolveDefaultParams: () => import_params_resolvers.resolveDefaultParams,
   resolveExpressions: () => import_params_resolvers.resolveExpressions,
@@ -73,12 +76,14 @@ var import_params_resolvers = require("./params-resolvers");
 var import_schema_utils = require("./schema-utils");
 var import_setupRuntimeContextSteps = require("./setupRuntimeContextSteps");
 var import_createCollectionContextMeta = require("./createCollectionContextMeta");
+var import_associationObjectVariable = require("./associationObjectVariable");
 var import_variablesParams = require("./variablesParams");
 var import_context = require("./context");
 var import_autoFlowError = require("./autoFlowError");
 var import_parsePathnameToViewParams = require("./parsePathnameToViewParams");
 var import_buildSettingsViewInputArgs = require("./buildSettingsViewInputArgs");
 var import_safeGlobals = require("./safeGlobals");
+var import_pruneFilter = require("./pruneFilter");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BLOCK_GROUP_CONFIGS,
@@ -91,6 +96,8 @@ var import_safeGlobals = require("./safeGlobals");
   clearAutoFlowError,
   collectContextParamsForTemplate,
   compileUiSchema,
+  createAssociationAwareObjectMetaFactory,
+  createAssociationSubpathResolver,
   createCollectionContextMeta,
   createCurrentRecordMetaFactory,
   createRecordMetaFactory,
@@ -109,6 +116,7 @@ var import_safeGlobals = require("./safeGlobals");
   isInheritedFrom,
   isVariableExpression,
   parsePathnameToViewParams,
+  pruneFilter,
   resolveCreateModelOptions,
   resolveDefaultParams,
   resolveExpressions,

package/lib/utils/pruneFilter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+/**
+ * 递归清理筛选对象中的“空值”。
+ *
+ * 规则：
+ * - 移除：`null`、`undefined`、空字符串 `''`、空数组 `[]`、空对象 `{}`；
+ * - 保留：`false`、`0` 等有意义的“假值”。
+ *
+ * 注意：当清理后整体变为空结构时，返回 `undefined`，用于表示无需下发该条件。
+ *
+ * @param input 任意筛选对象/数组/原始值
+ * @returns 清理后的对象；若为空则返回 `undefined`
+ */
+export declare function pruneFilter<T = any>(input: T): T | undefined;

package/lib/utils/pruneFilter.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pruneFilter_exports = {};
+__export(pruneFilter_exports, {
+  pruneFilter: () => pruneFilter
+});
+module.exports = __toCommonJS(pruneFilter_exports);
+function pruneFilter(input) {
+  if (Array.isArray(input)) {
+    const arr = input.map((v) => pruneFilter(v)).filter((v) => v !== void 0);
+    return arr.length ? arr : void 0;
+  }
+  if (input && typeof input === "object") {
+    const out = {};
+    Object.keys(input).forEach((k) => {
+      const v = pruneFilter(input[k]);
+      if (v !== void 0) out[k] = v;
+    });
+    return Object.keys(out).length ? out : void 0;
+  }
+  return input === null || input === void 0 || typeof input === "string" && input === "" ? void 0 : input;
+}
+__name(pruneFilter, "pruneFilter");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  pruneFilter
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.0.0-alpha.32",
+  "version": "2.0.0-alpha.34",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,8 +8,8 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.0.0-alpha.32",
-    "@nocobase/shared": "2.0.0-alpha.32",
+    "@nocobase/sdk": "2.0.0-alpha.34",
+    "@nocobase/shared": "2.0.0-alpha.34",
     "ahooks": "^3.7.2",
     "dompurify": "^3.0.2",
     "lodash": "^4.x",
@@ -35,5 +35,5 @@
   ],
   "author": "NocoBase Team",
   "license": "AGPL-3.0",
-  "gitHead": "50bb60d2f42e0fc2c1cd1eee397f9c0da94084df"
+  "gitHead": "d7bda14bac775be7ef207cb25986511740b2ed70"
 }

package/src/__tests__/flowContext.test.ts

@@ -1282,6 +1282,58 @@ describe('FlowContext resolveOnServer selective server resolution', () => {
     // server was called
     expect(api.request).toHaveBeenCalledTimes(1);
   });
+
+  it('skips server call when all vars require contextParams but none provided', async () => {
+    const engine = new FlowEngine();
+    const api = { request: vi.fn() } as any;
+    engine.context.defineProperty('api', { value: api });
+
+    engine.context.defineProperty('foo', {
+      value: { a: 1 },
+      resolveOnServer: true,
+      serverOnlyWhenContextParams: true,
+      meta: async () => ({
+        type: 'object',
+        title: 'Foo',
+        // no buildVariablesParams -> empty contextParams
+      }),
+    });
+
+    const tpl = { a: '{{ ctx.foo.a }}' } as any;
+    const out = await (engine.context as any).resolveJsonTemplate(tpl);
+    expect(out).toEqual({ a: 1 });
+    // skipped server, because all server vars (only foo) require contextParams but none present
+    expect(api.request).not.toHaveBeenCalled();
+  });
+
+  it('still calls server when at least one var has contextParams (even if others require contextParams but none)', async () => {
+    const engine = new FlowEngine();
+    const api = { request: vi.fn(async () => ({ data: { ok: true } })) } as any;
+    engine.context.defineProperty('api', { value: api });
+
+    // foo: requires contextParams but none will be provided
+    engine.context.defineProperty('foo', {
+      value: { a: 1 },
+      resolveOnServer: true,
+      serverOnlyWhenContextParams: true,
+      meta: async () => ({ type: 'object', title: 'Foo' }),
+    });
+
+    // user: provides contextParams via builder
+    engine.context.defineProperty('user', {
+      value: { id: 9 },
+      resolveOnServer: true,
+      meta: async () => ({
+        type: 'object',
+        title: 'User',
+        buildVariablesParams: () => ({ collection: 'users', filterByTk: 9, dataSourceKey: 'main' }),
+      }),
+    });
+
+    const tpl = { a: '{{ ctx.foo.a }}', u: '{{ ctx.user.id }}' } as any;
+    await (engine.context as any).resolveJsonTemplate(tpl);
+    expect(api.request).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe('FlowContext.getPropertyOptions()', () => {

package/src/__tests__/objectVariable.test.ts

@@ -0,0 +1,403 @@
+/**
+ * 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 { FlowContext } from '../flowContext';
+import { FlowEngine } from '../flowEngine';
+import {
+  createAssociationAwareObjectMetaFactory,
+  createAssociationSubpathResolver,
+} from '../utils/associationObjectVariable';
+
+function setupEngineWithCollections() {
+  const engine = new FlowEngine();
+  const ds = engine.context.dataSourceManager.getDataSource('main');
+
+  // 真实集合定义，确保 targetCollection / filterTargetKey 等行为一致
+  ds.addCollection({
+    name: 'users',
+    filterTargetKey: 'id',
+    fields: [
+      { name: 'id', type: 'integer', interface: 'number' },
+      { name: 'name', type: 'string', interface: 'text' },
+    ],
+  });
+  ds.addCollection({
+    name: 'tags',
+    filterTargetKey: 'id',
+    fields: [
+      { name: 'id', type: 'integer', interface: 'number' },
+      { name: 'name', type: 'string', interface: 'text' },
+    ],
+  });
+  ds.addCollection({
+    name: 'posts',
+    filterTargetKey: 'id',
+    fields: [
+      { name: 'title', type: 'string', interface: 'text' },
+      { name: 'author', type: 'belongsTo', target: 'users', interface: 'm2o' },
+      { name: 'tags', type: 'belongsToMany', target: 'tags', interface: 'm2m' },
+    ],
+  });
+
+  return { engine, ds, collection: ds.getCollection('posts') } as const;
+}
+
+describe('objectVariable utilities', () => {
+  it('createAssociationSubpathResolver should detect association subpaths', () => {
+    const { collection } = setupEngineWithCollections();
+    const resolver = createAssociationSubpathResolver(() => collection);
+    expect(resolver('author.name')).toBe(true);
+    expect(resolver('tags[0].name')).toBe(true);
+    expect(resolver('title')).toBe(false);
+    expect(resolver('title.length')).toBe(false);
+    expect(resolver('unknown.name')).toBe(false);
+  });
+
+  it('createAssociationAwareObjectMetaFactory should build params for toOne/toMany', async () => {
+    const { collection } = setupEngineWithCollections();
+
+    const obj1 = { title: 'hello', author: 1 };
+    const metaFactory1 = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj1,
+    );
+    const meta1 = await metaFactory1();
+    const ctx1 = new FlowContext();
+    const params1 = await (meta1 as any).buildVariablesParams(ctx1);
+    expect(params1).toEqual({
+      author: { collection: 'users', dataSourceKey: 'main', filterByTk: 1 },
+    });
+
+    const obj2 = { author: { id: 2 }, tags: [{ id: 11 }, { id: 12 }] };
+    const metaFactory2 = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj2,
+    );
+    const meta2 = await metaFactory2();
+    const ctx2 = new FlowContext();
+    const params2 = await (meta2 as any).buildVariablesParams(ctx2);
+    expect(params2).toEqual({
+      author: { collection: 'users', dataSourceKey: 'main', filterByTk: 2 },
+      tags: { collection: 'tags', dataSourceKey: 'main', filterByTk: [11, 12] },
+    });
+  });
+
+  it('integrates with FlowContext.resolveJsonTemplate to call variables:resolve with flattened contextParams', async () => {
+    const { engine, collection } = setupEngineWithCollections();
+    const obj = { author: 1 };
+    const ctx = engine.context as any;
+
+    // Provide API stub to intercept variables:resolve
+    const calls: any[] = [];
+    (ctx as any).api = {
+      request: vi.fn(async ({ url, data, method }) => {
+        calls.push({ url, data, method });
+        const batch = (data?.values?.batch as any[]) || [];
+        const results = batch.map((it) => ({ id: it.id, data: it.template }));
+        return { data: { data: { results } } };
+      }),
+    };
+
+    // Define object-like variable
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    ctx.defineProperty('obj', {
+      get: () => obj,
+      cache: false,
+      meta: metaFactory,
+      resolveOnServer: createAssociationSubpathResolver(() => collection),
+      serverOnlyWhenContextParams: true,
+    });
+
+    const template = { x: '{{ ctx.obj.author.name }}' } as any;
+    await (ctx as any).resolveJsonTemplate(template);
+
+    // Assert variables:resolve was called with proper flattened contextParams
+    expect((ctx as any).api.request).toHaveBeenCalled();
+    const call = calls.find((c) => c.url === 'variables:resolve');
+    expect(call).toBeTruthy();
+    const batch0 = call.data?.values?.batch?.[0];
+    expect(batch0?.contextParams).toBeTruthy();
+    // Flattened key should be 'obj.author'
+    const cp = batch0.contextParams as Record<string, any>;
+    const keys = Object.keys(cp || {});
+    expect(keys).toContain('obj.author');
+    expect(cp['obj.author']).toMatchObject({ collection: 'users', filterByTk: 1 });
+  });
+
+  it('does not call server when only non-association fields are referenced', async () => {
+    const { engine, collection } = setupEngineWithCollections();
+    const obj = { title: 'hello', author: 1 };
+    const ctx = engine.context as any;
+
+    (ctx as any).api = { request: vi.fn() };
+
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    ctx.defineProperty('obj', {
+      get: () => obj,
+      cache: false,
+      meta: metaFactory,
+      resolveOnServer: createAssociationSubpathResolver(() => collection),
+      serverOnlyWhenContextParams: true,
+    });
+
+    const template = { x: '{{ ctx.obj.title }}' } as any;
+    const resolved = await (ctx as any).resolveJsonTemplate(template);
+    expect(resolved).toEqual({ x: 'hello' });
+    expect((ctx as any).api.request).not.toHaveBeenCalled();
+  });
+
+  it('buildVariablesParams merges ids and objects in toMany and filters falsy', async () => {
+    const { collection } = setupEngineWithCollections();
+    const obj = { tags: [11, { id: 12 }, {}, null, undefined, { id: null }] };
+    const mf = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    const meta = await mf();
+    const ctx = new FlowContext();
+    const params = await (meta as any).buildVariablesParams(ctx);
+    expect(params).toMatchObject({ tags: { collection: 'tags', filterByTk: [11, 12] } });
+  });
+
+  it('supports custom primary key via filterTargetKey', async () => {
+    const engine = new FlowEngine();
+    const ds = engine.context.dataSourceManager.getDataSource('main');
+    ds.addCollection({
+      name: 'profiles',
+      filterTargetKey: 'uuid',
+      fields: [
+        { name: 'uuid', type: 'string', interface: 'text' },
+        { name: 'name', type: 'string', interface: 'text' },
+      ],
+    });
+    ds.addCollection({
+      name: 'articles',
+      filterTargetKey: 'id',
+      fields: [
+        { name: 'id', type: 'integer', interface: 'number' },
+        { name: 'editor', type: 'belongsTo', target: 'profiles', interface: 'm2o' },
+      ],
+    });
+    const collection = ds.getCollection('articles');
+    const obj = { editor: { uuid: 'p-1' } };
+    const mf = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    const meta = await mf();
+    const ctx = new FlowContext();
+    const params = await (meta as any).buildVariablesParams(ctx);
+    expect(params).toMatchObject({ editor: { collection: 'profiles', filterByTk: 'p-1' } });
+  });
+
+  it('supports composite primary key via filterTargetKey array (toOne/toMany)', async () => {
+    const engine = new FlowEngine();
+    const ds = engine.context.dataSourceManager.getDataSource('main');
+    ds.addCollection({
+      name: 'composites',
+      filterTargetKey: ['country', 'code'],
+      fields: [
+        { name: 'country', type: 'string', interface: 'text' },
+        { name: 'code', type: 'string', interface: 'text' },
+        { name: 'name', type: 'string', interface: 'text' },
+      ],
+    });
+    ds.addCollection({
+      name: 'items',
+      filterTargetKey: 'id',
+      fields: [
+        { name: 'id', type: 'integer', interface: 'number' },
+        { name: 'ref', type: 'belongsTo', target: 'composites', interface: 'm2o' },
+        { name: 'refs', type: 'belongsToMany', target: 'composites', interface: 'm2m' },
+      ],
+    });
+    const collection = ds.getCollection('items');
+
+    // toOne
+    const obj1 = { ref: { country: 'US', code: '001', name: 'United States' } };
+    const mf1 = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj1,
+    );
+    const meta1 = await mf1();
+    const ctx1 = new FlowContext();
+    const params1 = await (meta1 as any).buildVariablesParams(ctx1);
+    expect(params1).toMatchObject({
+      ref: { collection: 'composites', filterByTk: { country: 'US', code: '001' } },
+    });
+
+    // toMany with mixed valid/invalid entries
+    const obj2 = {
+      refs: [
+        { country: 'CN', code: '086' },
+        { country: 'JP' }, // missing code => ignored
+        'raw', // unsupported raw value for composite => ignored
+      ],
+    };
+    const mf2 = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj2,
+    );
+    const meta2 = await mf2();
+    const ctx2 = new FlowContext();
+    const params2 = await (meta2 as any).buildVariablesParams(ctx2);
+    expect(params2).toMatchObject({
+      refs: { collection: 'composites', filterByTk: [{ country: 'CN', code: '086' }] },
+    });
+  });
+
+  it('ignores incomplete composite key values when building params', async () => {
+    const engine = new FlowEngine();
+    const ds = engine.context.dataSourceManager.getDataSource('main');
+    ds.addCollection({
+      name: 'dept',
+      filterTargetKey: ['org', 'id'],
+      fields: [
+        { name: 'org', type: 'string', interface: 'text' },
+        { name: 'id', type: 'string', interface: 'text' },
+      ],
+    });
+    ds.addCollection({
+      name: 'employees',
+      filterTargetKey: 'id',
+      fields: [
+        { name: 'id', type: 'integer', interface: 'number' },
+        { name: 'department', type: 'belongsTo', target: 'dept', interface: 'm2o' },
+      ],
+    });
+    const collection = ds.getCollection('employees');
+    const obj = { department: { org: 'HQ' } }; // missing id
+    const mf = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    const meta = await mf();
+    const ctx = new FlowContext();
+    const params = await (meta as any).buildVariablesParams(ctx);
+    expect(params).toEqual({});
+  });
+
+  it('contextParams only includes used association subpaths (filters out unused)', async () => {
+    const { engine, collection } = setupEngineWithCollections();
+    const obj = { author: 1, tags: [11, 12] };
+    const ctx = engine.context as any;
+    const calls: any[] = [];
+    (ctx as any).api = {
+      request: vi.fn(async ({ url, data, method }) => {
+        calls.push({ url, data, method });
+        const batch = (data?.values?.batch as any[]) || [];
+        const results = batch.map((it) => ({ id: it.id, data: it.template }));
+        return { data: { data: { results } } };
+      }),
+    };
+
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    ctx.defineProperty('obj', {
+      get: () => obj,
+      cache: false,
+      meta: metaFactory,
+      resolveOnServer: createAssociationSubpathResolver(() => collection),
+      serverOnlyWhenContextParams: true,
+    });
+
+    // 仅引用 author 子属性，不使用 tags
+    const template = { a: '{{ ctx.obj.author.name }}' } as any;
+    await (ctx as any).resolveJsonTemplate(template);
+
+    const call = calls.find((c) => c.url === 'variables:resolve');
+    expect(call).toBeTruthy();
+    const cp = call.data?.values?.batch?.[0]?.contextParams as Record<string, any>;
+    const keys = Object.keys(cp || {});
+    expect(keys).toContain('obj.author');
+    expect(keys).not.toContain('obj.tags');
+  });
+
+  it('bracket without dot does not call server (tags[0])', async () => {
+    const { engine, collection } = setupEngineWithCollections();
+    const obj = { tags: [11, 12] };
+    const ctx = engine.context as any;
+    (ctx as any).api = { request: vi.fn() };
+
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    ctx.defineProperty('obj', {
+      get: () => obj,
+      cache: false,
+      meta: metaFactory,
+      resolveOnServer: createAssociationSubpathResolver(() => collection),
+      serverOnlyWhenContextParams: true,
+    });
+
+    const template = { t0: '{{ ctx.obj.tags[0] }}' } as any;
+    const resolved = await (ctx as any).resolveJsonTemplate(template);
+    expect(resolved).toEqual({ t0: 11 });
+    expect((ctx as any).api.request).not.toHaveBeenCalled();
+  });
+
+  it('no association values => buildVariablesParams returns empty object', async () => {
+    const { collection } = setupEngineWithCollections();
+    const obj = { title: 'hello' };
+    const mf = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    const meta = await mf();
+    const ctx = new FlowContext();
+    const params = await (meta as any).buildVariablesParams(ctx);
+    expect(params).toEqual({});
+  });
+
+  it('top-level association value (no dot) does not call server', async () => {
+    const { engine, collection } = setupEngineWithCollections();
+    const obj = { author: 7 };
+    const ctx = engine.context as any;
+    (ctx as any).api = { request: vi.fn() };
+
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+    ctx.defineProperty('obj', {
+      get: () => obj,
+      cache: false,
+      meta: metaFactory,
+      resolveOnServer: createAssociationSubpathResolver(() => collection),
+    });
+
+    const template = { a: '{{ ctx.obj.author }}' } as any;
+    const resolved = await (ctx as any).resolveJsonTemplate(template);
+    expect(resolved).toEqual({ a: 7 });
+    expect((ctx as any).api.request).not.toHaveBeenCalled();
+  });
+});

package/src/components/variables/VariableInput.tsx

@@ -139,7 +139,7 @@ const VariableInputComponent: React.FC<VariableInputProps> = ({
   // 当 value 存在但 currentMetaTreeNode 还未恢复，尝试按路径逐级加载（支持 children 为函数的场景）
   useEffect(() => {
     const restoreFromValue = async () => {
-      if (!Array.isArray(resolvedMetaTree) || !value) return;
+      if (!Array.isArray(resolvedMetaTree) || value == null) return;
 
       // 若已存在且路径匹配，跳过
       if (currentMetaTreeNode) {
@@ -203,7 +203,7 @@ const VariableInputComponent: React.FC<VariableInputProps> = ({
 
   useEffect(() => {
     if (!resolvedMetaTreeNode) return;
-    if (!Array.isArray(resolvedMetaTree) || !innerValue) return;
+    if (!Array.isArray(resolvedMetaTree) || innerValue == null) return;
     const finalValue = resolveValueFromPath?.(resolvedMetaTreeNode) || innerValue;
     emitChange(finalValue, resolvedMetaTreeNode);
     setCurrentMetaTreeNode(resolvedMetaTreeNode);
@@ -286,7 +286,7 @@ const VariableInputComponent: React.FC<VariableInputProps> = ({
 
   const inputProps = useMemo(() => {
     const baseProps = {
-      value: innerValue || '',
+      value: innerValue ?? '',
       onChange: handleInputChange,
       disabled,
     };

package/src/flowContext.ts

@@ -136,6 +136,10 @@ export interface PropertyOptions {
   // - boolean: true 表示整个顶层变量交给服务端；false 表示仅前端解析
   // - function: 根据子路径决定是否交给服务端（子路径示例：'record.roles[0].name'、'id'、''）
   resolveOnServer?: boolean | ((subPath: string) => boolean);
+  // 优化：当需要服务端解析但本属性在 buildVariablesParams 返回空时，是否跳过调用服务端。
+  // - 典型场景：formValues / currentObject 仅在“已选关联值”存在时才需要服务端；否则没有必要请求。
+  // - 默认 false：保持兼容，其他变量即使没有 contextParams 也可选择调用服务端。
+  serverOnlyWhenContextParams?: boolean;
 }
 
 type RouteOptions = {
@@ -1056,6 +1060,17 @@ export class FlowEngineContext extends BaseFlowEngineContext {
           ? _buildServerContextParams(this, autoInput)
           : undefined;
 
+        // 优化：若所有需要服务端解析的变量都声明了 “仅当有 contextParams 时才请求服务端”，
+        // 且本次未能构建出任何 contextParams，则跳过服务端请求，回退到前端解析。
+        if (!autoContextParams) {
+          const keys = Object.keys(serverVarPaths);
+          const allOptional =
+            keys.length > 0 && keys.every((k) => this.getPropertyOptions(k)?.serverOnlyWhenContextParams);
+          if (allOptional) {
+            return resolveExpressions(template, this);
+          }
+        }
+
         if (this.api) {
           try {
             serverResolved = await enqueueVariablesResolve(this as FlowRuntimeContext<FlowModel>, {

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

@@ -423,6 +423,24 @@ describe('ForkFlowModel', () => {
       });
     });
 
+    test('should clear local props with clearProps', () => {
+      const masterProps = { master: 'value', conflict: 'master' };
+      mockMaster.getProps = vi.fn(() => masterProps);
+
+      // 先设置一些本地属性
+      fork.setProps({ local: 'v', conflict: 'local' });
+      expect(fork.localProps).toEqual({ initial: 'value', local: 'v', conflict: 'local' });
+
+      // 调用 clearProps，应当返回一个空对象
+      const result = (fork as any).clearProps();
+      expect(result).toStrictEqual({});
+      expect(fork.localProps).toStrictEqual({});
+
+      // 清空后，合并的 props 应回退为仅 master 的 props
+      expect(fork.getProps()).toEqual(masterProps);
+      expect(fork.props).toEqual(masterProps);
+    });
+
     test('should get merged props from master and local', () => {
       const masterProps = { master: 'value', shared: 'master' };
       const localProps = { local: 'value', shared: 'local' };

package/src/models/forkFlowModel.ts

@@ -207,6 +207,13 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
     }
   }
 
+  /**
+   * 清理局部 props，仅影响当前 fork
+   */
+  clearProps() {
+    return (this.localProps = {});
+  }
+
   /**
    * render 依旧使用 master 的方法，但合并后的 props 需要透传
    */

package/src/resources/multiRecordResource.ts

@@ -168,6 +168,11 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
       options,
     );
     await this.runAction('destroy', config);
+    const currentPage = this.getPage();
+    const lastPage = Math.ceil((this.getCount() - _.castArray(filterByTk).length) / this.getPageSize());
+    if (currentPage > lastPage) {
+      this.setPage(lastPage);
+    }
     await this.refresh();
   }
 

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/associationObjectVariable.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 type { Collection, CollectionField } from '../data-source';
+import type { FlowContext, PropertyMeta, PropertyMetaFactory } from '../flowContext';
+import { createCollectionContextMeta } from './createCollectionContextMeta';
+
+/**
+ * 提取变量子路径的顶层字段名。
+ * 例如：
+ * - 'author.name'  => 'author'
+ * - 'tags[0].name' => 'tags'
+ *
+ * @param subPath 变量在对象中的子路径字符串
+ * @returns 顶层字段名，找不到时返回 undefined
+ */
+function baseFieldNameOf(subPath: string): string | undefined {
+  if (!subPath) return undefined;
+  const m = subPath.match(/^([^.[]+)/);
+  return m?.[1];
+}
+
+/**
+ * 在集合中根据字段名查找字段定义，兼容 getField/getFields 两种方式。
+ *
+ * @param collection 集合对象
+ * @param name 字段名
+ * @returns 匹配的字段定义，找不到时返回 undefined
+ */
+function findFieldByName(collection: Collection | null | undefined, name?: string): CollectionField | undefined {
+  if (!collection || !name) return undefined;
+  const direct = collection.getField(name);
+  if (direct) return direct;
+  const fields = collection.getFields?.() || [];
+  return fields.find((f) => f.name === name);
+}
+
+/**
+ * 从值中提取主键：
+ * - 支持主键原始值（string/number）
+ * - 支持对象（按主键名取值）
+ *
+ * @param value 字段当前值
+ * @param primaryKey 主键字段名
+ * @returns 解析出的主键值，无法解析时返回 undefined
+ */
+function toFilterByTk(value: unknown, primaryKey: string | string[]) {
+  if (value == null) return undefined;
+  if (Array.isArray(primaryKey)) {
+    if (typeof value !== 'object' || !value) return undefined;
+    const out: Record<string, any> = {};
+    for (const k of primaryKey) {
+      const v = (value as any)[k];
+      if (typeof v === 'undefined' || v === null) return undefined;
+      out[k] = v;
+    }
+    return out;
+  }
+  if (typeof value === 'string' || typeof value === 'number') return value;
+  if (typeof value === 'object') {
+    return (value as any)[primaryKey];
+  }
+  return undefined;
+}
+
+/**
+ * 创建一个用于“对象类变量”（如 formValues / currentObject）的 `resolveOnServer` 判定函数。
+ * 仅当访问路径以“关联字段名”开头（且继续访问其子属性）时，返回 true 交由服务端解析；
+ * 否则在前端解析即可。
+ *
+ * @param collectionAccessor 返回当前对象所在collection
+ * @returns `(subPath) => boolean` 判断是否需要服务端解析
+ */
+export function createAssociationSubpathResolver(
+  collectionAccessor: () => Collection | null,
+): (subPath: string) => boolean {
+  return (p: string) => {
+    if (!p || !p.includes('.')) return false; // 只在访问子属性时才需要后端
+    const base = baseFieldNameOf(p);
+    if (!base) return false;
+    const collection = collectionAccessor();
+    const field = findFieldByName(collection, base);
+    return !!field?.isAssociationField();
+  };
+}
+
+/**
+ * 构建“对象类变量”的 PropertyMetaFactory：
+ * - 暴露集合字段结构（通过 createCollectionContextMeta）用于变量选择器；
+ * - 提供 buildVariablesParams：基于对象当前值，收集所有“已选择的关联字段”
+ *   以便服务端在 variables:resolve 时按需补全关联数据。
+ *
+ * @param collectionAccessor 获取集合对象，用于字段/元信息来源
+ * @param title 变量组标题（用于 UI 展示）
+ * @param valueAccessor 获取当前对象值（如 ctx.form.getFieldsValue() / ctx.currentObject）
+ * @returns PropertyMetaFactory
+ */
+export function createAssociationAwareObjectMetaFactory(
+  collectionAccessor: () => Collection | null,
+  title: string,
+  valueAccessor: (ctx: FlowContext) => any,
+): PropertyMetaFactory {
+  const baseFactory = createCollectionContextMeta(collectionAccessor, title);
+  const factory: PropertyMetaFactory = async () => {
+    const base = (await baseFactory()) as PropertyMeta | null;
+    if (!base) return null;
+
+    const meta: PropertyMeta = {
+      ...base,
+      buildVariablesParams: (ctx: FlowContext) => {
+        const collection = collectionAccessor();
+        const obj = valueAccessor(ctx);
+        if (!collection || !obj || typeof obj !== 'object') return {};
+        const params: Record<string, any> = {};
+
+        const fields: CollectionField[] = collection.getFields?.() || [];
+        for (const field of fields) {
+          const name = field.name as string | undefined;
+          if (!name) continue;
+          if (!field.isAssociationField()) continue;
+          const target = field.target as string | undefined;
+          const targetCollection = field.targetCollection;
+          if (!target || !targetCollection) continue;
+          const primaryKey = targetCollection.filterTargetKey as string | string[];
+
+          const associationValue = (obj as any)[name];
+          if (associationValue == null) continue;
+
+          if (Array.isArray(associationValue)) {
+            const ids = associationValue.map((item) => toFilterByTk(item, primaryKey)).filter((v) => v != null);
+            if (ids.length) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: ids,
+              };
+            }
+          } else {
+            const id = toFilterByTk(associationValue, primaryKey);
+            if (id != null) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: id,
+              };
+            }
+          }
+        }
+
+        return params;
+      },
+    };
+
+    return meta;
+  };
+  factory.title = title;
+  return factory;
+}

package/src/utils/index.ts

@@ -41,6 +41,7 @@ export { setupRuntimeContextSteps } from './setupRuntimeContextSteps';
 
 // Record Proxy 工具
 export { createCollectionContextMeta } from './createCollectionContextMeta';
+export { createAssociationAwareObjectMetaFactory, createAssociationSubpathResolver } from './associationObjectVariable';
 export {
   buildRecordMeta,
   collectContextParamsForTemplate,
@@ -61,3 +62,6 @@ export { buildSettingsViewInputArgs } from './buildSettingsViewInputArgs';
 
 // 安全全局对象（window/document）
 export { createSafeDocument, createSafeWindow, createSafeNavigator } from './safeGlobals';
+
+// Filter helpers
+export { pruneFilter } from './pruneFilter';

package/src/utils/pruneFilter.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+
+/**
+ * 递归清理筛选对象中的“空值”。
+ *
+ * 规则：
+ * - 移除：`null`、`undefined`、空字符串 `''`、空数组 `[]`、空对象 `{}`；
+ * - 保留：`false`、`0` 等有意义的“假值”。
+ *
+ * 注意：当清理后整体变为空结构时，返回 `undefined`，用于表示无需下发该条件。
+ *
+ * @param input 任意筛选对象/数组/原始值
+ * @returns 清理后的对象；若为空则返回 `undefined`
+ */
+export function pruneFilter<T = any>(input: T): T | undefined {
+  // Arrays: prune items and drop empty arrays
+  if (Array.isArray(input)) {
+    const arr = (input as unknown[]).map((v) => pruneFilter(v)).filter((v) => v !== undefined);
+    return (arr.length ? (arr as unknown as T) : undefined) as any;
+  }
+
+  // Objects: prune properties and drop empty objects
+  if (input && typeof input === 'object') {
+    const out: Record<string, any> = {};
+    Object.keys(input as Record<string, any>).forEach((k) => {
+      const v = pruneFilter((input as any)[k]);
+      if (v !== undefined) out[k] = v;
+    });
+    return (Object.keys(out).length ? (out as unknown as T) : undefined) as any;
+  }
+
+  // Primitives: keep false/0; drop null/undefined/''
+  return input === null || input === undefined || (typeof input === 'string' && input === '') ? undefined : input;
+}