@nocobase/flow-engine 2.0.0-alpha.4 → 2.0.0-alpha.41

package/src/flowContext.ts

@@ -11,14 +11,17 @@ import { ISchema } from '@formily/json-schema';
 import { observable } from '@formily/reactive';
 import { APIClient } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
-import * as antd from 'antd';
 import { MessageInstance } from 'antd/es/message/interface';
+import * as antd from 'antd';
+import * as antdIcons from '@ant-design/icons';
 import type { HookAPI } from 'antd/es/modal/useModal';
 import { NotificationInstance } from 'antd/es/notification/interface';
 import _ from 'lodash';
 import pino from 'pino';
 import qs from 'qs';
 import React, { createRef } from 'react';
+import * as ReactDOMClient from 'react-dom/client';
+import { ElementProxy } from './ElementProxy';
 import type { Location } from 'react-router-dom';
 import { ACL } from './acl/Acl';
 import { ContextPathProxy } from './ContextPathProxy';
@@ -26,21 +29,11 @@ import { DataSource, DataSourceManager } from './data-source';
 import { FlowEngine } from './flowEngine';
 import { FlowI18n } from './flowI18n';
 import { JSRunner, JSRunnerOptions } from './JSRunner';
-import { createJSRunnerWithVersion } from './runjs-context';
-import { FlowModel, ForkFlowModel } from './models';
-import {
-  APIResource,
-  BaseRecordResource,
-  FlowResource,
-  FlowSQLRepository,
-  MultiRecordResource,
-  SingleRecordResource,
-  SQLResource,
-} from './resources';
+import type { FlowModel } from './models/flowModel';
+import type { ForkFlowModel } from './models/forkFlowModel';
+import { FlowResource, FlowSQLRepository } from './resources';
 import type { ActionDefinition, EventDefinition, ResourceType } from './types';
 import {
-  createSafeDocument,
-  createSafeWindow,
   escapeT,
   extractPropertyPath,
   extractUsedVariablePaths,
@@ -53,6 +46,9 @@ import { enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
 import { buildServerContextParams as _buildServerContextParams } from './utils/serverContextParams';
 import { FlowView, FlowViewer } from './views/FlowView';
+import { RunJSContextRegistry, getModelClassName } from './runjs-context/registry';
+import { createEphemeralContext } from './utils/createEphemeralContext';
+import dayjs from 'dayjs';
 
 // Helper: detect a RecordRef-like object
 function isRecordRefLike(val: any): boolean {
@@ -142,6 +138,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 = {
@@ -892,46 +892,19 @@ export class FlowContext {
   }
 }
 
-export class FlowRunjsContext extends FlowContext {
-  constructor(delegate: FlowContext) {
-    super();
-    this.addDelegate(delegate);
-    // Expose React and antd only within runjs context
-    // This keeps the scope minimal while enabling React/AntD rendering in scripts
-    this.defineProperty('React', { value: React });
-    this.defineProperty('antd', { value: antd });
-    this.defineMethod(
-      'dispatchModelEvent',
-      async (modelOrUid: FlowModel | string, eventName: string, inputArgs?: Record<string, any>) => {
-        let model: FlowModel | null = null;
-        if (typeof modelOrUid === 'string') {
-          model = await this.engine.loadModel({ uid: modelOrUid });
-        } else if (modelOrUid instanceof FlowModel) {
-          model = modelOrUid;
-        }
-        if (model) {
-          model.context.addDelegate(this);
-          model.dispatchEvent(eventName, { navigation: false, ...this.model?.['getInputArgs']?.(), ...inputArgs });
-        } else {
-          this.message.error(this.t('Model with ID {{uid}} not found', { uid: modelOrUid }));
-        }
-      },
-    );
-  }
-}
-
 class BaseFlowEngineContext extends FlowContext {
   declare router: Router;
   declare dataSourceManager: DataSourceManager;
   declare requireAsync: (url: string) => Promise<any>;
+  declare importAsync: (url: string) => Promise<any>;
   declare createJSRunner: (options?: JSRunnerOptions) => JSRunner;
+  declare pageInfo: { version?: 'v1' | 'v2' };
   /**
    * @deprecated use `resolveJsonTemplate` instead
    */
   declare renderJson: (template: JSONValue) => Promise<any>;
   declare resolveJsonTemplate: (template: JSONValue) => Promise<any>;
   declare runjs: (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<any>;
-  declare copyToClipboard: (text: string) => Promise<void>;
   declare getAction: <TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>(
     name: string,
   ) => ActionDefinition<TModel, TCtx> | undefined;
@@ -1005,10 +978,10 @@ export class FlowEngineContext extends BaseFlowEngineContext {
     });
     this.defineMethod('runjs', async (code, variables, options?: JSRunnerOptions) => {
       const mergedGlobals = { ...(options?.globals || {}), ...(variables || {}) };
-      const runner = this.createJSRunner({
+      const runner = (await (this as any).createJSRunner({
         ...(options || {}),
         globals: mergedGlobals,
-      });
+      })) as JSRunner;
       return runner.run(code);
     });
     this.defineMethod('renderJson', function (template: any) {
@@ -1090,6 +1063,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>, {
@@ -1218,50 +1202,60 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         );
       });
     });
-    this.defineMethod('createJSRunner', function (options?: JSRunnerOptions) {
-      // return createJSRunnerWithVersion.call(this, options as any);
-      const runCtx = new FlowRunjsContext(this.createProxy());
-      return new JSRunner({
-        ...options,
-        globals: {
-          ctx: runCtx,
-          window: createSafeWindow(),
-          document: createSafeDocument(),
-          ...options?.globals,
-        },
-      });
-    });
-    // 复制文本到剪贴板（优先使用 Clipboard API，降级到 execCommand）
-    this.defineMethod('copyToClipboard', async (text: string) => {
-      const content = String(text ?? '');
-      try {
-        if (typeof navigator !== 'undefined' && navigator.clipboard && navigator.clipboard.writeText) {
-          await navigator.clipboard.writeText(content);
-          return;
-        }
-      } catch (e) {
-        // 忽略，尝试降级方案
+    // 动态按 URL 加载 ESM 模块
+    // - 使用 Vite / Webpack ignore 注释，避免被预打包或重写
+    // - 返回模块命名空间对象（包含 default 与命名导出）
+    this.defineMethod('importAsync', async (url: string) => {
+      if (!url || typeof url !== 'string') {
+        throw new Error('invalid url');
       }
-
-      // 降级方案：创建临时 textarea + execCommand('copy')
-      return new Promise<void>((resolve, reject) => {
+      const u = url.trim();
+      const g = globalThis as any;
+      g.__nocobaseImportAsyncCache = g.__nocobaseImportAsyncCache || new Map<string, Promise<any>>();
+      const cache: Map<string, Promise<any>> = g.__nocobaseImportAsyncCache;
+      if (cache.has(u)) return cache.get(u)!;
+      // 尝试使用原生 dynamic import（加上 vite/webpack 的 ignore 注释）
+      const nativeImport = () => import(/* @vite-ignore */ /* webpackIgnore: true */ u);
+      // 兜底方案：通过 eval 在运行时构造 import，避免被打包器接管
+      const evalImport = () => {
+        const importer = (0, eval)('u => import(u)');
+        return importer(u);
+      };
+      const p = (async () => {
         try {
-          const ta = document.createElement('textarea');
-          ta.value = content;
-          ta.setAttribute('readonly', '');
-          ta.style.position = 'fixed';
-          ta.style.top = '-9999px';
-          document.body.appendChild(ta);
-          ta.focus();
-          ta.select();
-          const ok = document.execCommand('copy');
-          document.body.removeChild(ta);
-          if (ok) resolve();
-          else reject(new Error('execCommand copy failed'));
-        } catch (err) {
-          reject(err);
+          return await nativeImport();
+        } catch (err: any) {
+          // 常见于打包产物仍然拦截了 dynamic import 或开发态插件未识别 ignore 注释
+          try {
+            return await evalImport();
+          } catch (err2) {
+            throw err2 || err;
+          }
         }
-      });
+      })();
+      cache.set(u, p);
+      return p;
+    });
+    this.defineMethod('createJSRunner', async function (options?: JSRunnerOptions) {
+      try {
+        const mod: any = await import('./runjs-context/setup');
+        if (typeof mod?.setupRunJSContexts === 'function') await mod.setupRunJSContexts();
+      } catch (_) {
+        // ignore if setup is not available
+      }
+      const version = (options?.version as any) || 'v1';
+      const modelClass = getModelClassName(this);
+      const Ctor =
+        (RunJSContextRegistry.resolve(version, modelClass) as any) ||
+        (RunJSContextRegistry.resolve(version, '*') as any) ||
+        FlowRunJSContext;
+      let runCtx: any;
+      if (Ctor) {
+        runCtx = new Ctor(this);
+      }
+      const globals: Record<string, any> = { ctx: runCtx, ...(options?.globals || {}) };
+      const { timeoutMs } = options || {};
+      return new JSRunner({ globals, timeoutMs });
     });
     // Helper: build server contextParams for variables:resolve
     this.defineMethod('buildServerContextParams', function (this: BaseFlowEngineContext, input?: any) {
@@ -1332,7 +1326,8 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       'runAction',
       async function (this: BaseFlowEngineContext, actionName: string, params?: Record<string, any>) {
         const def = this.engine.getAction<FlowModel, FlowEngineContext>(actionName);
-        const ctx = this.createProxy() as unknown as FlowEngineContext;
+        // 使用“临时作用域”上下文，避免将临时定义污染到引擎级上下文，并在创建时应用定义
+        const ctx = await createEphemeralContext(this as unknown as FlowEngineContext, def);
         if (!def) {
           throw new Error(`Action '${actionName}' not found.`);
         }
@@ -1346,7 +1341,7 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         }
         if (!useRawParams) {
           // 先服务端解析，再前端补齐
-          combinedParams = await (ctx as any).resolveJsonTemplate(combinedParams);
+          combinedParams = await ctx.resolveJsonTemplate(combinedParams);
         }
 
         if (!def.handler) {
@@ -1369,12 +1364,25 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         context: this.createProxy(),
       });
     });
+    // Provide useResource in base engine context so RunJS can call it directly
+    this.defineMethod(
+      'useResource',
+      function (
+        this: BaseFlowEngineContext,
+        className: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource',
+      ) {
+        if (this.has('resource')) return;
+        this.defineProperty('resource', {
+          get: () => this.createResource(className),
+        });
+      },
+    );
   }
 }
 
 export class FlowModelContext extends BaseFlowModelContext {
   constructor(model: FlowModel) {
-    if (!(model instanceof FlowModel)) {
+    if (!model || typeof model !== 'object') {
       throw new Error('Invalid FlowModel instance');
     }
     super();
@@ -1383,7 +1391,7 @@ export class FlowModelContext extends BaseFlowModelContext {
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
     this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = this.createJSRunner({
+      const runner = await this.createJSRunner({
         globals: variables,
         version: options?.version,
       });
@@ -1417,21 +1425,24 @@ export class FlowModelContext extends BaseFlowModelContext {
           stepParams: {
             popupSettings: {
               openView: {
-                ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName']),
+                // 持久化首次传入的关键展示/数据参数，供后续路由与再次打开复用
+                ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName', 'mode', 'size']),
               },
             },
           },
         });
         await model.save();
       }
-      if (model.getStepParams('popupSettings')?.openView?.dataSourceKey) {
-        model.setStepParams('popupSettings', {
-          openView: {
-            ...model.getStepParams('popupSettings')?.openView,
-            ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName']),
-          },
-        });
-        await model.save();
+      // 若已存在 openView 配置，则按需合并更新（仅覆盖本次显式传入的字段）
+      if (model.getStepParams('popupSettings')?.openView) {
+        const prevOpenView = model.getStepParams('popupSettings')?.openView || {};
+        const incoming = _.pick(opts, ['dataSourceKey', 'collectionName', 'associationName', 'mode', 'size']);
+        const nextOpenView = { ...prevOpenView, ...incoming };
+        // 仅当有变更时才保存，避免不必要的写入
+        if (!_.isEqual(prevOpenView, nextOpenView)) {
+          model.setStepParams('popupSettings', { openView: nextOpenView });
+          await model.save();
+        }
       }
 
       // 路由层级的 viewUid：优先使用 routeViewUid（仅用于路由展示）；
@@ -1477,7 +1488,8 @@ export class FlowModelContext extends BaseFlowModelContext {
       'runAction',
       async function (this: BaseFlowModelContext, actionName: string, params?: Record<string, any>) {
         const def = this.model.getAction<FlowModel, FlowModelContext>(actionName);
-        const ctx = this.createProxy() as unknown as FlowModelContext;
+        // 使用“临时作用域”上下文，避免将临时定义污染到模型级上下文，并在创建时应用定义
+        const ctx = await createEphemeralContext(this as unknown as FlowModelContext, def);
         if (!def) {
           throw new Error(`Action '${actionName}' not found.`);
         }
@@ -1490,7 +1502,7 @@ export class FlowModelContext extends BaseFlowModelContext {
           useRawParams = await useRawParams(ctx);
         }
         if (!useRawParams) {
-          combinedParams = await (ctx as any).resolveJsonTemplate(combinedParams);
+          combinedParams = await ctx.resolveJsonTemplate(combinedParams);
         }
 
         if (!def.handler) {
@@ -1507,7 +1519,7 @@ export class FlowForkModelContext extends BaseFlowModelContext {
     public master: FlowModel,
     public fork: ForkFlowModel,
   ) {
-    if (!(master instanceof FlowModel)) {
+    if (!master || typeof master !== 'object') {
       throw new Error('Invalid FlowModel instance');
     }
     super();
@@ -1527,7 +1539,7 @@ export class FlowForkModelContext extends BaseFlowModelContext {
       },
     });
     this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = this.createJSRunner({
+      const runner = await this.createJSRunner({
         globals: variables,
         version: options?.version,
       });
@@ -1588,7 +1600,7 @@ export class FlowRuntimeContext<
       this.engine.reactView.onRefReady(ref, cb, timeout);
     });
     this.defineMethod('runjs', async (code, variables, options?: { version?: string }) => {
-      const runner = this.createJSRunner({
+      const runner = await this.createJSRunner({
         globals: variables,
         version: options?.version,
       });
@@ -1641,3 +1653,190 @@ export class FlowRuntimeContext<
 
 // 类型别名，方便使用
 export type FlowSettingsContext<TModel extends FlowModel = FlowModel> = FlowRuntimeContext<TModel, 'settings'>;
+
+export type RunJSDocCompletionDoc = {
+  insertText?: string;
+};
+
+export type RunJSDocPropertyDoc =
+  | string
+  | {
+      description?: string;
+      detail?: string;
+      type?: string;
+      examples?: string[];
+      completion?: RunJSDocCompletionDoc;
+      properties?: Record<string, RunJSDocPropertyDoc>;
+    };
+
+export type RunJSDocMethodDoc =
+  | string
+  | {
+      description?: string;
+      detail?: string;
+      examples?: string[];
+      completion?: RunJSDocCompletionDoc;
+    };
+
+export type RunJSDocMeta = {
+  label?: string;
+  properties?: Record<string, RunJSDocPropertyDoc>;
+  methods?: Record<string, RunJSDocMethodDoc>;
+  snippets?: Record<string, any>;
+};
+
+const __runjsClassDefaultMeta = new WeakMap<Function, RunJSDocMeta>();
+const __runjsClassLocaleMeta = new WeakMap<Function, Map<string, RunJSDocMeta>>();
+const __runjsDocCache = new WeakMap<Function, Map<string, RunJSDocMeta>>();
+
+function __runjsDeepMerge(base: any, patch: any) {
+  if (patch === null) return undefined;
+  if (Array.isArray(base) || Array.isArray(patch) || typeof base !== 'object' || typeof patch !== 'object') {
+    return patch ?? base;
+  }
+  const out: any = { ...base };
+  for (const k of Object.keys(patch)) {
+    const v = __runjsDeepMerge(base?.[k], patch[k]);
+    if (typeof v === 'undefined') delete out[k];
+    else out[k] = v;
+  }
+  return out;
+}
+export class FlowRunJSContext extends FlowContext {
+  constructor(delegate: FlowContext) {
+    super();
+    this.addDelegate(delegate);
+    this.defineProperty('React', { value: React });
+    this.defineProperty('antd', { value: antd });
+    this.defineProperty('dayjs', { value: dayjs });
+    // 为 JS 运行时代码提供带有 antd/App/ConfigProvider 包裹的 React 根
+    // 保持与 ReactDOMClient 接口一致，优先覆盖 createRoot，其余方法透传
+    const ReactDOMShim: any = {
+      ...ReactDOMClient,
+      createRoot: (container: Element | DocumentFragment, options?: any) => {
+        // 兼容 ElementProxy：若传入的是代理对象，取其底层原生元素
+        const realContainer: any = (container as any)?.__el || container;
+        // 使用引擎自带的 reactView.createRoot，以继承应用内的 ConfigProvider/App 上下文与主题
+        return this.engine.reactView.createRoot(realContainer as HTMLElement, options);
+      },
+    };
+    this.defineProperty('ReactDOM', { value: ReactDOMShim });
+
+    // 为第三方/通用库提供统一命名空间：ctx.libs
+    // - 新增库应优先挂载到 ctx.libs.xxx
+    // - 同时保留顶层别名（如 ctx.React / ctx.antd），以兼容历史代码
+    const libs = Object.freeze({
+      React,
+      ReactDOM: ReactDOMShim,
+      antd,
+      dayjs,
+      antdIcons,
+    });
+    this.defineProperty('libs', { value: libs });
+
+    // Convenience: ctx.render(<App />[, container])
+    // - container defaults to ctx.element if available
+    // - internally uses engine.reactView.createRoot to inherit app context
+    // - caches root per container via global WeakMap
+    this.defineMethod(
+      'render',
+      function (
+        this: any,
+        vnode: React.ReactElement | Node | DocumentFragment | string,
+        container?: Element | DocumentFragment,
+      ) {
+        const el = (container as any) || (this.element as any);
+        if (!el) throw new Error('ctx.render: container not provided and ctx.element is not available');
+        const containerEl: any = (el as any)?.__el || el; // unwrap ElementProxy
+        const globalRef: any = globalThis as any;
+        globalRef.__nbRunjsRoots = globalRef.__nbRunjsRoots || new WeakMap<any, any>();
+        const rootMap: WeakMap<any, any> = globalRef.__nbRunjsRoots;
+
+        // If vnode is string (HTML), unmount react root and set sanitized HTML
+        if (typeof vnode === 'string') {
+          const existingRoot = rootMap.get(containerEl);
+          if (existingRoot && typeof existingRoot.unmount === 'function') {
+            try {
+              existingRoot.unmount();
+            } finally {
+              rootMap.delete(containerEl);
+            }
+          }
+          const proxy: any = new ElementProxy(containerEl);
+          proxy.innerHTML = String(vnode ?? '');
+          return null;
+        }
+
+        // If vnode is a DOM Node or DocumentFragment, unmount and replace content
+        if (
+          vnode &&
+          (vnode as any).nodeType &&
+          ((vnode as any).nodeType === 1 || (vnode as any).nodeType === 3 || (vnode as any).nodeType === 11)
+        ) {
+          const existingRoot = rootMap.get(containerEl);
+          if (existingRoot && typeof existingRoot.unmount === 'function') {
+            try {
+              existingRoot.unmount();
+            } finally {
+              rootMap.delete(containerEl);
+            }
+          }
+          while (containerEl.firstChild) containerEl.removeChild(containerEl.firstChild);
+          containerEl.appendChild(vnode as any);
+          return null;
+        }
+
+        let root = rootMap.get(containerEl);
+        if (!root) {
+          root = this.ReactDOM.createRoot(containerEl);
+          rootMap.set(containerEl, root);
+        }
+        root.render(vnode as any);
+        return root;
+      },
+    );
+  }
+  static define(meta: RunJSDocMeta, options?: { locale?: string }) {
+    const locale = options?.locale;
+    if (locale) {
+      const map = __runjsClassLocaleMeta.get(this) || new Map<string, RunJSDocMeta>();
+      const prev = map.get(locale) || {};
+      map.set(locale, __runjsDeepMerge(prev, meta));
+      __runjsClassLocaleMeta.set(this, map);
+    } else {
+      const prev = __runjsClassDefaultMeta.get(this) || {};
+      __runjsClassDefaultMeta.set(this, __runjsDeepMerge(prev, meta));
+    }
+    __runjsDocCache.delete(this);
+  }
+  static getDoc(locale?: string): RunJSDocMeta {
+    const self = this as any as Function;
+    let cacheForClass = __runjsDocCache.get(self);
+    const cacheKey = String(locale || 'default');
+    if (cacheForClass && cacheForClass.has(cacheKey)) return cacheForClass.get(cacheKey)!;
+    const chain: Function[] = [];
+    let cur: any = self;
+    while (cur && cur.prototype) {
+      chain.unshift(cur);
+      cur = Object.getPrototypeOf(cur);
+    }
+    let merged: RunJSDocMeta = {};
+    for (const cls of chain) {
+      merged = __runjsDeepMerge(merged, __runjsClassDefaultMeta.get(cls) || {});
+    }
+    if (locale) {
+      for (const cls of chain) {
+        const lmap = __runjsClassLocaleMeta.get(cls);
+        if (lmap && lmap.has(locale)) {
+          merged = __runjsDeepMerge(merged, lmap.get(locale));
+        }
+      }
+    }
+    if (!cacheForClass) {
+      cacheForClass = new Map<string, RunJSDocMeta>();
+      __runjsDocCache.set(self, cacheForClass);
+    }
+    cacheForClass.set(cacheKey, merged);
+    return merged;
+  }
+}