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

package/src/utils/associationObjectVariable.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 _ from 'lodash';
+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
+ * @param valueAccessor 可选，本地值访问器。若本地已存在目标子路径的值，则认为无需走后端，优先使用本地值。
+ * @returns `(subPath) => boolean` 判断是否需要服务端解析
+ */
+export function createAssociationSubpathResolver(
+  collectionAccessor: () => Collection | null,
+  valueAccessor?: () => unknown,
+): (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);
+    const isAssoc = !!field?.isAssociationField();
+    if (!isAssoc) return false;
+
+    // 可选：本地优先。当提供 valueAccessor 时，若本地已有该子路径值，则不走后端
+    if (typeof valueAccessor === 'function') {
+      const local = valueAccessor();
+      if (local && typeof local === 'object') {
+        const v = _.get(local as Record<string, unknown>, p);
+        if (typeof v !== 'undefined') return false;
+      }
+    }
+
+    return true;
+  };
+}
+
+/**
+ * 构建“对象类变量”的 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, true);
+  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/createCollectionContextMeta.ts

@@ -17,7 +17,7 @@ const NUMERIC_FIELD_TYPES = ['integer', 'float', 'double', 'decimal'] as const;
 /**
  * 创建字段的完整元数据（统一处理关联和非关联字段）
  */
-function createFieldMetadata(field: CollectionField) {
+function createFieldMetadata(field: CollectionField, includeNonFilterable?: boolean) {
   const baseProperties = createMetaBaseProperties(field);
 
   if (field.isAssociationField()) {
@@ -36,7 +36,9 @@ function createFieldMetadata(field: CollectionField) {
       properties: async () => {
         const subProperties: Record<string, any> = {};
         targetCollection.fields.forEach((subField) => {
-          subProperties[subField.name] = createFieldMetadata(subField);
+          if (includeNonFilterable || subField.filterable) {
+            subProperties[subField.name] = createFieldMetadata(subField, includeNonFilterable);
+          }
         });
         return subProperties;
       },
@@ -86,6 +88,7 @@ function createMetaBaseProperties(field: CollectionField) {
   return {
     title: field.title || field.name,
     interface: field.interface,
+    options: field.options,
     uiSchema: field.uiSchema || {},
   };
 }
@@ -93,6 +96,7 @@ function createMetaBaseProperties(field: CollectionField) {
 export function createCollectionContextMeta(
   collectionOrFactory: Collection | (() => Collection | null),
   title?: string,
+  includeNonFilterable?: boolean,
 ): PropertyMetaFactory {
   const metaFn: PropertyMetaFactory = async () => {
     const collection = typeof collectionOrFactory === 'function' ? collectionOrFactory() : collectionOrFactory;
@@ -110,7 +114,9 @@ export function createCollectionContextMeta(
 
         // 添加所有字段
         collection.fields.forEach((field) => {
-          properties[field.name] = createFieldMetadata(field);
+          if (includeNonFilterable || field.filterable) {
+            properties[field.name] = createFieldMetadata(field, includeNonFilterable);
+          }
         });
 
         return properties;

package/src/utils/createEphemeralContext.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 { FlowContext } from '../flowContext';
+import type { ActionDefinition } from '../types';
+import type { PropertyOptions } from '../flowContext';
+
+// 临时上下文：
+// - 读：优先从 scoped（临时定义）读取，兜底 parent；
+// - 写：统一写入 parent（不污染 scoped）；
+// - 注入：create 阶段 define* 写入 scoped；运行阶段 define* 写入 parent。
+type ContextDefsLike<TCtx extends FlowContext> =
+  | Partial<Pick<ActionDefinition<any, TCtx>, 'defineProperties' | 'defineMethods'>>
+  | null
+  | undefined;
+
+export async function createEphemeralContext<TCtx extends FlowContext>(
+  parent: TCtx,
+  contextDefs?: ContextDefsLike<TCtx>,
+): Promise<TCtx> {
+  // 若未提供任何上下文定义，直接复用父级上下文，避免不必要的代理包装
+  if (contextDefs == null || (!contextDefs.defineProperties && !contextDefs.defineMethods)) {
+    return parent;
+  }
+  // 1) 创建一个新的 FlowContext，专门承载“临时定义”（defineProperty/defineMethod）
+  const scoped = new FlowContext();
+  // 2) 读取优先：先从 scoped 自身取（_props/_methods），否则委托到 parent（仅 _props/_methods）
+  scoped.addDelegate(parent);
+
+  // 3) 先创建 scoped 的代理，用于注入阶段（define* 直达 scoped；读写行为与最终代理一致）
+  const scopedProxy = scoped.createProxy();
+  const scopedObj = scopedProxy as unknown as object;
+  const parentObj = parent as unknown as object;
+  const getFromParent = (key: PropertyKey) => {
+    const val = Reflect.get(parentObj, key, parentObj);
+    return typeof val === 'function' ? (val as Function).bind(parent) : val;
+  };
+  const hasInScopedOrParent = (key: PropertyKey) =>
+    key === 'defineProperty' || key === 'defineMethod' || Reflect.has(scopedObj, key) || Reflect.has(parentObj, key);
+  const injectionProxy = new Proxy(scopedProxy as TCtx, {
+    get(_t, key: PropertyKey, receiver) {
+      if (typeof key === 'string') {
+        // 注入阶段：允许在 defLike 的函数体中调用 ctx.defineProperty/defineMethod 写入 scoped
+        if (key === 'defineProperty') {
+          return (propKey: string, options: any) => (scoped as FlowContext).defineProperty(propKey, options);
+        }
+        if (key === 'defineMethod') {
+          return (name: string, fn: any, des?: string) => (scoped as FlowContext).defineMethod(name, fn, des);
+        }
+        if (Reflect.has(scopedObj, key)) {
+          return Reflect.get(scopedObj, key, receiver);
+        }
+        return getFromParent(key);
+      }
+      return Reflect.get(scopedObj, key, receiver);
+    },
+    set(_t, key: PropertyKey, value: unknown) {
+      return Reflect.set(parentObj, key, value);
+    },
+    has(_t, key: PropertyKey) {
+      return hasInScopedOrParent(key);
+    },
+    getOwnPropertyDescriptor(_t, key: PropertyKey) {
+      return Object.getOwnPropertyDescriptor(scopedObj, key) || Object.getOwnPropertyDescriptor(parentObj, key);
+    },
+  });
+
+  // 如果提供了 contextDefs，则在创建时即注入定义，便于外部更简洁地使用
+  if (contextDefs) {
+    const defs = Array.isArray(contextDefs) ? contextDefs : [contextDefs];
+    for (const defLike of defs) {
+      if (!defLike) continue;
+      // 1) defineProperties -> 写入到 scoped（避免污染父级）
+      const dp = (defLike as any).defineProperties;
+      if (dp) {
+        const raw = typeof dp === 'function' ? await dp(injectionProxy as TCtx) : dp;
+        if (!raw || typeof raw !== 'object') {
+          throw new TypeError('defineProperties must return an object of PropertyOptions');
+        }
+        const propsDef = raw as Record<string, PropertyOptions>;
+        for (const [key, options] of Object.entries(propsDef)) {
+          if (!options || typeof options !== 'object') {
+            throw new TypeError(`defineProperties['${key}'] must be a PropertyOptions object`);
+          }
+          // 直接在 scoped 上定义，确保仅限本次临时作用域
+          (scoped as FlowContext).defineProperty(key, options);
+        }
+      }
+      // 2) defineMethods -> 写入到 scoped（避免污染父级）
+      const dm = (defLike as any).defineMethods;
+      if (dm) {
+        const raw = typeof dm === 'function' ? await dm(injectionProxy as TCtx) : dm;
+        if (!raw || typeof raw !== 'object') {
+          throw new TypeError('defineMethods must return an object of functions');
+        }
+        const methodsDef = raw as Record<string, (this: TCtx, ...args: any[]) => any>;
+        for (const [key, fn] of Object.entries(methodsDef)) {
+          if (typeof fn !== 'function') {
+            throw new TypeError(`defineMethods['${key}'] must be a function`);
+          }
+          (scoped as FlowContext).defineMethod(key, fn as any);
+        }
+      }
+    }
+  }
+
+  // 4) 创建最终对外代理：读取优先 scoped，兜底父级，且后续 define* 写入父级
+  const outerProxy = new Proxy(scopedProxy as TCtx, {
+    get(_t, key: PropertyKey, receiver) {
+      if (typeof key === 'string') {
+        if (key === 'defineProperty') {
+          return (propKey: string, options: any) => (parent as FlowContext).defineProperty(propKey, options);
+        }
+        if (key === 'defineMethod') {
+          return (name: string, fn: any, des?: string) => (parent as FlowContext).defineMethod(name, fn, des);
+        }
+        if (Reflect.has(scopedObj, key)) {
+          return Reflect.get(scopedObj, key, receiver);
+        }
+        return getFromParent(key);
+      }
+      return Reflect.get(scopedObj, key, receiver);
+    },
+    set(_t, key: PropertyKey, value: unknown) {
+      return Reflect.set(parentObj, key, value);
+    },
+    has(_t, key: PropertyKey) {
+      return hasInScopedOrParent(key);
+    },
+    getOwnPropertyDescriptor(_t, key: PropertyKey) {
+      return Object.getOwnPropertyDescriptor(scopedObj, key) || Object.getOwnPropertyDescriptor(parentObj, key);
+    },
+  });
+
+  return outerProxy as TCtx;
+}

package/src/utils/flows.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { FlowDefinition } from '../FlowDefinition';
+
+export const isBeforeRenderFlow = (flow: FlowDefinition): boolean => {
+  if (typeof flow.on === 'string') {
+    return flow.on === 'beforeRender';
+  }
+  if (typeof flow.on === 'object') {
+    return flow.on.eventName === 'beforeRender';
+  }
+  if (!flow.on && flow.manual !== true) {
+    return true;
+  }
+  return false;
+};

package/src/utils/index.ts

@@ -34,21 +34,22 @@ export { isInheritedFrom } from './inheritance';
 export { resolveCreateModelOptions, resolveDefaultParams, resolveExpressions } from './params-resolvers';
 
 // Schema 工具
-export { compileUiSchema, resolveStepUiSchema, resolveUiMode } from './schema-utils';
+export { compileUiSchema, resolveStepUiSchema, resolveUiMode, shouldHideStepInSettings } from './schema-utils';
 
 // Runtime Context Steps 设置
 export { setupRuntimeContextSteps } from './setupRuntimeContextSteps';
 
 // Record Proxy 工具
 export { createCollectionContextMeta } from './createCollectionContextMeta';
+export { createAssociationAwareObjectMetaFactory, createAssociationSubpathResolver } from './associationObjectVariable';
 export {
   buildRecordMeta,
   collectContextParamsForTemplate,
   createCurrentRecordMetaFactory,
+  createRecordResolveOnServerWithLocal,
   createRecordMetaFactory,
   extractUsedVariableNames,
   extractUsedVariablePaths,
-  inferParentRecordRef,
   inferRecordRef,
   type RecordParamsBuilder,
 } from './variablesParams';
@@ -60,4 +61,17 @@ export { clearAutoFlowError, getAutoFlowError, setAutoFlowError, type AutoFlowEr
 export { parsePathnameToViewParams, type ViewParam } from './parsePathnameToViewParams';
 
 // 安全全局对象（window/document）
-export { createSafeDocument, createSafeWindow } from './safeGlobals';
+export { createSafeDocument, createSafeWindow, createSafeNavigator } from './safeGlobals';
+
+// RunJS 代码兼容预处理（{{ }}）与 JSX 编译
+export { prepareRunJsCode, preprocessRunJsTemplates } from './runjsTemplateCompat';
+
+// Ephemeral context helper（用于临时注入属性/方法，避免污染父级 ctx）
+export { createEphemeralContext } from './createEphemeralContext';
+
+// Filter helpers
+export { pruneFilter } from './pruneFilter';
+export { isBeforeRenderFlow } from './flows';
+
+// Module URL resolver
+export { resolveModuleUrl, isCssFile } from './resolveModuleUrl';

package/src/utils/jsxTransform.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+
+/**
+ * Lightweight JSX -> JS compiler for RunJS user code.
+ * - Uses sucrase via dynamic import (lazy; avoids static cycles and cost when not needed)
+ * - Maps JSX to ctx.React.createElement / ctx.React.Fragment so no global React is required
+ * - If sucrase is unavailable or transform throws, returns original code as graceful fallback
+ */
+export async function compileRunJs(code: string): Promise<string> {
+  // Fast path: cheap heuristic to skip import if no JSX likely present
+  // (not strict; still safe because we fall back to transform if dynamic import is cheap)
+  const maybeJSX = /<[A-Za-z]|<\//.test(code);
+  if (!maybeJSX) return code;
+
+  try {
+    const mod: any = await import('sucrase');
+    const transform = mod?.transform || mod?.default?.transform;
+    if (typeof transform !== 'function') return code;
+    const res = transform(code, {
+      transforms: ['jsx'],
+      jsxPragma: 'ctx.React.createElement',
+      jsxFragmentPragma: 'ctx.React.Fragment',
+      // Keep ES syntax as-is; JSRunner runs in modern engines
+      disableESTransforms: true,
+      production: true,
+    });
+    return (res && (res.code || res?.output)) ?? code;
+  } catch (_e) {
+    // Fallback: return original code if transform fails
+    return code;
+  }
+}

package/src/utils/params-resolvers.ts

@@ -7,9 +7,9 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
+import { getValuesByPath } from '@nocobase/shared';
 import _ from 'lodash';
 import { FlowContext, FlowModelContext, FlowRuntimeContext } from '../flowContext';
-import { getValuesByPath } from '@nocobase/utils/client';
 import type { FlowModel } from '../models';
 import type { ServerContextParams } from './serverContextParams';
 
@@ -409,8 +409,13 @@ export async function preprocessExpression(expression: string, ctx: FlowContext)
 async function compileExpression<TModel extends FlowModel = FlowModel>(expression: string, ctx: FlowContext) {
   // 仅点号路径匹配：ctx.a.b.c（不支持括号/函数/索引），用于数组聚合取值
   const matchDotOnly = (expr: string): string | null => {
-    const m = expr.trim().match(/^ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)*)$/);
-    return m ? m[1] : null;
+    // 顶层变量名仍使用 JS 标识符规则（与 ctx.defineProperty 保持一致）；
+    // 子路径允许包含 '-'（例如 formValues.oho-test.o2m-users）。
+    const m = expr
+      .trim()
+      .match(/^ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\.([a-zA-Z_$][a-zA-Z0-9_$-]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$-]*)*))?$/);
+    if (!m) return null;
+    return m[2] ? `${m[1]}.${m[2]}` : m[1];
   };
 
   // 基于 getValuesByPath 的聚合取值：支持数组扁平化，仅支持 '.' 访问
@@ -423,6 +428,20 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
     return getValuesByPath(base as object, segs.join('.'));
   };
 
+  const resolveInnerExpression = async (innerExpr: string): Promise<any> => {
+    const dotPath = matchDotOnly(innerExpr);
+    if (dotPath) {
+      const resolved = await resolveDotOnlyPath(dotPath);
+      // 当 dotPath 含 '-' 时可能与减号运算符存在歧义，例如：ctx.aa.bb-ctx.cc。
+      // 若按 path 解析未取到值，则回退到 JS 表达式解析，尽量保持兼容。
+      if (resolved === undefined && dotPath.includes('-')) {
+        return await processExpression(innerExpr, ctx);
+      }
+      return resolved;
+    }
+    return await processExpression(innerExpr, ctx);
+  };
+
   /**
    * 单个表达式模式匹配
    *
@@ -440,14 +459,10 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
    * ✅ "{{ctx.user}}"            -> 捕获: "ctx.user"
    * ❌ "Hello {{ ctx.user }}"    -> 不匹配（不是纯表达式）
    */
-  const singleMatch = expression.match(/^\{\{\s*(.+)\s*\}\}$/);
+  const singleMatch = expression.match(/^\s*\{\{\s*([^{}]+?)\s*\}\}\s*$/);
   if (singleMatch) {
     const inner = singleMatch[1];
-    const dotPath = matchDotOnly(inner);
-    if (dotPath) {
-      return await resolveDotOnlyPath(dotPath);
-    }
-    return await processExpression(inner, ctx);
+    return await resolveInnerExpression(inner);
   }
 
   /**
@@ -470,8 +485,7 @@ async function compileExpression<TModel extends FlowModel = FlowModel>(expressio
   let result = expression;
 
   for (const [fullMatch, innerExpr] of matches) {
-    const dotPath = matchDotOnly(innerExpr);
-    const value = dotPath ? await resolveDotOnlyPath(dotPath) : await processExpression(innerExpr, ctx);
+    const value = await resolveInnerExpression(innerExpr);
     if (value !== undefined) {
       const replacement = typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
       result = result.replace(fullMatch, replacement);

package/src/utils/parsePathnameToViewParams.ts

@@ -13,7 +13,7 @@ export interface ViewParam {
   /** 标签页唯一标识符 */
   tabUid?: string;
   /** 弹窗记录的 id */
-  filterByTk?: string;
+  filterByTk?: string | Record<string, string | number>;
   /** source Id */
   sourceId?: string;
 }
@@ -70,17 +70,61 @@ export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
     }
     // 处理参数
     else if (currentView && i + 1 < segments.length) {
-      const value = segments[i + 1];
+      const rawValue = segments[i + 1];
+      // 尝试对路径段进行解码
+      let decoded: string = rawValue;
+      try {
+        decoded = decodeURIComponent(rawValue);
+      } catch (_) {
+        // ignore
+      }
 
       switch (segment) {
         case 'tab':
-          currentView.tabUid = value;
+          // tab/sourceId 仅作为字符串处理
+          currentView.tabUid = decoded;
           break;
-        case 'filterbytk':
-          currentView.filterByTk = value;
+        case 'filterbytk': {
+          // 仅在 filterByTk 分支支持对象/JSON/键值对解析
+          const parseKeyValuePairs = (s: string): Record<string, string | number> => {
+            const obj: Record<string, string | number> = {};
+            s.split('&').forEach((pair) => {
+              const [k, v = ''] = pair.split('=');
+              if (!k) return;
+              try {
+                const key = decodeURIComponent(k);
+                const val = decodeURIComponent(v);
+                obj[key] = val;
+              } catch (_) {
+                obj[k] = v;
+              }
+            });
+            return obj;
+          };
+
+          let parsed: string | Record<string, string | number> = decoded;
+          if (decoded && (decoded.startsWith('{') || decoded.startsWith('['))) {
+            try {
+              const maybe = JSON.parse(decoded);
+              if (maybe && typeof maybe === 'object' && !Array.isArray(maybe)) {
+                parsed = maybe as Record<string, string | number>;
+              } else {
+                // 非对象 JSON（如数组/数字）按字符串保留
+                parsed = decoded;
+              }
+            } catch (_) {
+              // 解析失败，按字符串保留
+              parsed = decoded;
+            }
+          } else if (decoded && decoded.includes('=') && decoded.includes('&')) {
+            // 形如 a=b&c=d 的整体段
+            parsed = parseKeyValuePairs(decoded);
+          }
+          currentView.filterByTk = parsed;
           break;
+        }
         case 'sourceid':
-          currentView.sourceId = value;
+          currentView.sourceId = decoded;
           break;
         default:
           // 未知参数，跳过

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;
+}