@nocobase/flow-engine 2.0.0-alpha.63 → 2.0.0-alpha.65

package/src/executor/FlowExecutor.ts

@@ -17,10 +17,20 @@ import { FlowExitException, resolveDefaultParams } from '../utils';
 import { FlowExitAllException } from '../utils/exceptions';
 import { setupRuntimeContextSteps } from '../utils/setupRuntimeContextSteps';
 import { createEphemeralContext } from '../utils/createEphemeralContext';
+import type { ScheduledCancel } from '../scheduler/ModelOperationScheduler';
 
 export class FlowExecutor {
   constructor(private readonly engine: FlowEngine) {}
 
+  private async emitModelEventIf(
+    eventName: string | undefined,
+    topic: string,
+    payload: Record<string, any>,
+  ): Promise<void> {
+    if (!eventName) return;
+    await this.engine.emitter.emitAsync(`model:event:${eventName}:${topic}`, payload);
+  }
+
   /** Cache wrapper for applyFlow cache lifecycle */
   private async withApplyFlowCache<T>(cacheKey: string | null, executor: () => Promise<T>): Promise<T> {
     if (!cacheKey || !this.engine) return await executor();
@@ -57,7 +67,13 @@ export class FlowExecutor {
   /**
    * Execute a single flow on model.
    */
-  async runFlow(model: FlowModel, flowKey: string, inputArgs?: Record<string, any>, runId?: string): Promise<any> {
+  async runFlow(
+    model: FlowModel,
+    flowKey: string,
+    inputArgs?: Record<string, any>,
+    runId?: string,
+    eventName?: string,
+  ): Promise<any> {
     const flow = model.getFlow(flowKey);
 
     if (!flow) {
@@ -99,6 +115,16 @@ export class FlowExecutor {
     setupRuntimeContextSteps(flowContext, stepDefs, model, flowKey);
     const stepsRuntime = flowContext.steps as Record<string, { params: any; uiSchema?: any; result?: any }>;
 
+    const flowEventBasePayload = {
+      uid: model.uid,
+      model,
+      runId: flowContext.runId,
+      inputArgs,
+      flowKey,
+    };
+
+    await this.emitModelEventIf(eventName, `flow:${flowKey}:start`, flowEventBasePayload);
+
     for (const [stepKey, step] of Object.entries(stepDefs) as [string, StepDefinition][]) {
       // Resolve handler and params
       let handler: ActionDefinition<FlowModel, FlowRuntimeContext>['handler'] | undefined;
@@ -156,6 +182,11 @@ export class FlowExecutor {
           );
           continue;
         }
+
+        await this.emitModelEventIf(eventName, `flow:${flowKey}:step:${stepKey}:start`, {
+          ...flowEventBasePayload,
+          stepKey,
+        });
         const currentStepResult = handler(runtimeCtx, combinedParams);
         const isAwait = step.isAwait !== false;
         lastResult = isAwait ? await currentStepResult : currentStepResult;
@@ -163,15 +194,47 @@ export class FlowExecutor {
         // Store step result and update context
         stepResults[stepKey] = lastResult;
         stepsRuntime[stepKey].result = stepResults[stepKey];
+        await this.emitModelEventIf(eventName, `flow:${flowKey}:step:${stepKey}:end`, {
+          ...flowEventBasePayload,
+          result: lastResult,
+          stepKey,
+        });
       } catch (error) {
+        if (!(error instanceof FlowExitException) && !(error instanceof FlowExitAllException)) {
+          await this.emitModelEventIf(eventName, `flow:${flowKey}:step:${stepKey}:error`, {
+            ...flowEventBasePayload,
+            error,
+            stepKey,
+          });
+        }
         if (error instanceof FlowExitException) {
           flowContext.logger.info(`[FlowEngine] ${error.message}`);
+          await this.emitModelEventIf(eventName, `flow:${flowKey}:step:${stepKey}:end`, {
+            ...flowEventBasePayload,
+            stepKey,
+          });
+          await this.emitModelEventIf(eventName, `flow:${flowKey}:end`, {
+            ...flowEventBasePayload,
+            result: stepResults,
+          });
           return Promise.resolve(stepResults);
         }
         if (error instanceof FlowExitAllException) {
           flowContext.logger.info(`[FlowEngine] ${error.message}`);
+          await this.emitModelEventIf(eventName, `flow:${flowKey}:step:${stepKey}:end`, {
+            ...flowEventBasePayload,
+            stepKey,
+          });
+          await this.emitModelEventIf(eventName, `flow:${flowKey}:end`, {
+            ...flowEventBasePayload,
+            result: error,
+          });
           return Promise.resolve(error);
         }
+        await this.emitModelEventIf(eventName, `flow:${flowKey}:error`, {
+          ...flowEventBasePayload,
+          error,
+        });
         flowContext.logger.error(
           { err: error },
           `BaseModel.applyFlow: Error executing step '${stepKey}' in flow '${flowKey}':`,
@@ -179,11 +242,13 @@ export class FlowExecutor {
         return Promise.reject(error);
       }
     }
+    await this.emitModelEventIf(eventName, `flow:${flowKey}:end`, {
+      ...flowEventBasePayload,
+      result: stepResults,
+    });
     return Promise.resolve(stepResults);
   }
 
-  // runAutoFlows 已移除：统一通过 dispatchEvent('beforeRender') + useCache 控制
-
   /**
    * Dispatch an event to flows bound via flow.on and execute them.
    */
@@ -202,14 +267,15 @@ export class FlowExecutor {
 
     const runId = `${model.uid}-${eventName}-${Date.now()}`;
     const logger = model.context.logger;
+    const eventBasePayload = {
+      uid: model.uid,
+      model,
+      runId,
+      inputArgs,
+    };
 
     try {
-      await this.engine.emitter.emitAsync(`model:event:${eventName}:start`, {
-        uid: model.uid,
-        model,
-        runId,
-        inputArgs,
-      });
+      await this.emitModelEventIf(eventName, 'start', eventBasePayload);
       await model.onDispatchEventStart?.(eventName, options, inputArgs);
     } catch (err) {
       if (isBeforeRender && err instanceof FlowExitException) {
@@ -237,11 +303,25 @@ export class FlowExecutor {
           return false;
         });
 
+    // 路由系统的“重放打开视图”会再次 dispatchEvent('click')，但这不应重复触发用户配置的动态事件流。
+    // 约定：由路由重放触发时，会在 inputArgs 中携带 triggerByRouter: true
+    const isRouterReplayClick = eventName === 'click' && inputArgs?.triggerByRouter === true;
+    const flowsToRun = isRouterReplayClick
+      ? flows.filter((flow) => {
+          const reg = flow['flowRegistry'] as any;
+          const type = reg?.constructor?._type as 'instance' | 'global' | undefined;
+          return type !== 'instance';
+        })
+      : flows;
+
+    // 记录本次 dispatchEvent 内注册的调度任务，用于在结束/错误后兜底清理未触发的任务
+    const scheduledCancels: ScheduledCancel[] = [];
+
     // 组装执行函数（返回值用于缓存；beforeRender 返回 results:any[]，其它返回 true）
     const execute = async () => {
       if (sequential) {
         // 顺序执行：动态流（实例级）优先，其次静态流；各自组内再按 sort 升序，最后保持原始顺序稳定
-        const flowsWithIndex = flows.map((f, i) => ({ f, i }));
+        const flowsWithIndex = flowsToRun.map((f, i) => ({ f, i }));
         const ordered = flowsWithIndex
           .slice()
           .sort((a, b) => {
@@ -259,12 +339,103 @@ export class FlowExecutor {
           })
           .map((x) => x.f);
         const results: any[] = [];
+
+        // 预处理：当事件流配置了 on.phase 时，将其执行移动到指定节点，并从“立即执行列表”中移除
+        const staticFlowsByKey = new Map(
+          ordered
+            .filter((f) => {
+              const reg = f['flowRegistry'] as any;
+              const type = reg?.constructor?._type as 'instance' | 'global' | undefined;
+              return type !== 'instance';
+            })
+            .map((f) => [f.key, f] as const),
+        );
+        const scheduled = new Set<string>();
+        const scheduleGroups = new Map<string, Array<{ flow: any; order: number }>>();
+        ordered.forEach((flow, indexInOrdered) => {
+          const on = flow.on;
+          const onObj = typeof on === 'object' ? (on as any) : undefined;
+          if (!onObj) return;
+
+          const phase: any = onObj.phase;
+          const flowKey: any = onObj.flowKey;
+          const stepKey: any = onObj.stepKey;
+
+          // 默认：beforeAllFlows（保持现有行为）
+          if (!phase || phase === 'beforeAllFlows') return;
+
+          let whenKey: string | null = null;
+          if (phase === 'afterAllFlows') {
+            whenKey = `event:${eventName}:end`;
+          } else if (phase === 'beforeFlow' || phase === 'afterFlow') {
+            if (!flowKey) {
+              // 配置不完整：降级到“全部静态流之后”
+              whenKey = `event:${eventName}:end`;
+            } else {
+              const anchorFlow = staticFlowsByKey.get(String(flowKey));
+              if (anchorFlow) {
+                const anchorPhase = phase === 'beforeFlow' ? 'start' : 'end';
+                whenKey = `event:${eventName}:flow:${String(flowKey)}:${anchorPhase}`;
+              } else {
+                // 锚点不存在（flow 被删除或覆盖等）：降级到“全部静态流之后”
+                whenKey = `event:${eventName}:end`;
+              }
+            }
+          } else if (phase === 'beforeStep' || phase === 'afterStep') {
+            if (!flowKey || !stepKey) {
+              // 配置不完整：降级到“全部静态流之后”
+              whenKey = `event:${eventName}:end`;
+            } else {
+              const anchorFlow = staticFlowsByKey.get(String(flowKey));
+              const anchorStepExists = !!anchorFlow?.hasStep?.(String(stepKey));
+              if (anchorFlow && anchorStepExists) {
+                const anchorPhase = phase === 'beforeStep' ? 'start' : 'end';
+                whenKey = `event:${eventName}:flow:${String(flowKey)}:step:${String(stepKey)}:${anchorPhase}`;
+              } else {
+                // 锚点不存在（flow/step 被删除或覆盖等）：降级到“全部静态流之后”
+                whenKey = `event:${eventName}:end`;
+              }
+            }
+          } else {
+            // 未知 phase：忽略
+            return;
+          }
+
+          if (!whenKey) return;
+          scheduled.add(flow.key);
+          const list = scheduleGroups.get(whenKey) || [];
+          list.push({ flow, order: indexInOrdered });
+          scheduleGroups.set(whenKey, list);
+        });
+
+        // 注册调度（同锚点按 flow.sort 升序；sort 相同保持稳定顺序）
+        for (const [whenKey, list] of scheduleGroups.entries()) {
+          const sorted = list.slice().sort((a, b) => {
+            const sa = a.flow.sort ?? 0;
+            const sb = b.flow.sort ?? 0;
+            if (sa !== sb) return sa - sb;
+            return a.order - b.order;
+          });
+          for (const it of sorted) {
+            const cancel = model.scheduleModelOperation(
+              model.uid,
+              async (m) => {
+                const res = await this.runFlow(m, it.flow.key, inputArgs, runId, eventName);
+                results.push(res);
+              },
+              { when: whenKey as any },
+            );
+            scheduledCancels.push(cancel);
+          }
+        }
+
         for (const flow of ordered) {
+          if (scheduled.has(flow.key)) continue;
           try {
             logger.debug(
               `BaseModel '${model.uid}' dispatching event '${eventName}' to flow '${flow.key}' (sequential).`,
             );
-            const result = await this.runFlow(model, flow.key, inputArgs, runId);
+            const result = await this.runFlow(model, flow.key, inputArgs, runId, eventName);
             if (result instanceof FlowExitAllException) {
               logger.debug(`[FlowEngine.dispatchEvent] ${result.message}`);
               break; // 终止后续
@@ -283,10 +454,10 @@ export class FlowExecutor {
 
       // 并行
       const results = await Promise.all(
-        flows.map(async (flow) => {
+        flowsToRun.map(async (flow) => {
           logger.debug(`BaseModel '${model.uid}' dispatching event '${eventName}' to flow '${flow.key}'.`);
           try {
-            return await this.runFlow(model, flow.key, inputArgs, runId);
+            return await this.runFlow(model, flow.key, inputArgs, runId, eventName);
           } catch (error) {
             logger.error(
               { err: error },
@@ -318,11 +489,8 @@ export class FlowExecutor {
       } catch (hookErr) {
         logger.error({ err: hookErr }, `BaseModel.dispatchEvent: End hook error for event '${eventName}'`);
       }
-      await this.engine.emitter.emitAsync(`model:event:${eventName}:end`, {
-        uid: model.uid,
-        model,
-        runId,
-        inputArgs,
+      await this.emitModelEventIf(eventName, 'end', {
+        ...eventBasePayload,
         result,
       });
       return result;
@@ -337,14 +505,16 @@ export class FlowExecutor {
         { err: error },
         `BaseModel.dispatchEvent: Error executing event '${eventName}' for model '${model.uid}':`,
       );
-      await this.engine.emitter.emitAsync(`model:event:${eventName}:error`, {
-        uid: model.uid,
-        model,
-        runId,
-        inputArgs,
+      await this.emitModelEventIf(eventName, 'error', {
+        ...eventBasePayload,
         error,
       });
       if (throwOnError) throw error;
+    } finally {
+      // 清理未触发的调度任务，避免跨事件/跨 runId 残留导致意外执行
+      for (const cancel of scheduledCancels) {
+        cancel();
+      }
     }
   }
 }

package/src/executor/__tests__/flowExecutor.test.ts

@@ -139,6 +139,72 @@ describe('FlowExecutor', () => {
     expect(submitHandler).not.toHaveBeenCalled();
   });
 
+  it("dispatchEvent('click') skips instance flows when triggerByRouter is true", async () => {
+    class MyModel extends FlowModel {}
+
+    const globalHandler = vi.fn().mockResolvedValue('global-ok');
+    MyModel.registerFlow('globalClick', {
+      on: 'click',
+      steps: {
+        s: { handler: globalHandler },
+      },
+    });
+
+    const instanceHandler = vi.fn().mockResolvedValue('instance-ok');
+    const model = new MyModel({
+      uid: 'm-click-router-replay',
+      flowEngine: engine,
+      flowRegistry: {
+        instanceClick: {
+          on: 'click',
+          steps: {
+            s: { handler: instanceHandler },
+          },
+        },
+      },
+      stepParams: {},
+      subModels: {},
+    } as FlowModelOptions);
+
+    await engine.executor.dispatchEvent(model, 'click', { triggerByRouter: true }, { sequential: true });
+
+    expect(globalHandler).toHaveBeenCalledTimes(1);
+    expect(instanceHandler).not.toHaveBeenCalled();
+  });
+
+  it("dispatchEvent('click') keeps instance flows when triggerByRouter is not true", async () => {
+    class MyModel extends FlowModel {}
+
+    const globalHandler = vi.fn().mockResolvedValue('global-ok');
+    MyModel.registerFlow('globalClick', {
+      on: 'click',
+      steps: {
+        s: { handler: globalHandler },
+      },
+    });
+
+    const instanceHandler = vi.fn().mockResolvedValue('instance-ok');
+    const model = new MyModel({
+      uid: 'm-click-normal',
+      flowEngine: engine,
+      flowRegistry: {
+        instanceClick: {
+          on: 'click',
+          steps: {
+            s: { handler: instanceHandler },
+          },
+        },
+      },
+      stepParams: {},
+      subModels: {},
+    } as FlowModelOptions);
+
+    await engine.executor.dispatchEvent(model, 'click', { triggerByRouter: false }, { sequential: true });
+
+    expect(globalHandler).toHaveBeenCalledTimes(1);
+    expect(instanceHandler).toHaveBeenCalledTimes(1);
+  });
+
   it('dispatchEvent default parallel does not stop on exitAll', async () => {
     const calls: string[] = [];
     const mkFlow = (key: string, opts?: { exitAll?: boolean }) => ({

package/src/flowContext.ts

@@ -45,6 +45,7 @@ import { FlowExitAllException } from './utils/exceptions';
 import { enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
 import { buildServerContextParams as _buildServerContextParams } from './utils/serverContextParams';
+import { inferRecordRef } from './utils/variablesParams';
 import { FlowView, FlowViewer } from './views/FlowView';
 import { RunJSContextRegistry, getModelClassName } from './runjs-context/registry';
 import { createEphemeralContext } from './utils/createEphemeralContext';
@@ -71,6 +72,61 @@ function filterBuilderOutputByPaths(built: any, neededPaths: string[]): any {
   return undefined;
 }
 
+// Helper: extract top-level segment of a subpath (e.g. 'a.b' -> 'a', 'tags[0].name' -> 'tags')
+function topLevelOf(subPath: string): string | undefined {
+  if (!subPath) return undefined;
+  const m = String(subPath).match(/^([^.[]+)/);
+  return m?.[1];
+}
+
+// Helper: infer selects (fields/appends) from usage paths (mirrors server-side inferSelectsFromUsage)
+function inferSelectsFromUsage(paths: string[] = []): { generatedAppends?: string[]; generatedFields?: string[] } {
+  if (!Array.isArray(paths) || paths.length === 0) {
+    return { generatedAppends: undefined, generatedFields: undefined };
+  }
+
+  const appendSet = new Set<string>();
+  const fieldSet = new Set<string>();
+
+  const normalizePath = (raw: string): string => {
+    if (!raw) return '';
+    let s = String(raw);
+    // remove numeric indexes like [0]
+    s = s.replace(/\[(?:\d+)\]/g, '');
+    // normalize string indexes like ["name"] / ['name'] into .name
+    s = s.replace(/\[(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')\]/g, (_m, g1, g2) => `.${(g1 || g2) as string}`);
+    s = s.replace(/\.\.+/g, '.');
+    s = s.replace(/^\./, '').replace(/\.$/, '');
+    return s;
+  };
+
+  for (let path of paths) {
+    if (!path) continue;
+    // drop leading numeric index like [0].name
+    while (/^\[(\d+)\](\.|$)/.test(path)) {
+      path = path.replace(/^\[(\d+)\]\.?/, '');
+    }
+    const norm = normalizePath(path);
+    if (!norm) continue;
+    const segments = norm.split('.').filter(Boolean);
+    if (segments.length === 0) continue;
+
+    if (segments.length === 1) {
+      fieldSet.add(segments[0]);
+      continue;
+    }
+
+    for (let i = 0; i < segments.length - 1; i++) {
+      appendSet.add(segments.slice(0, i + 1).join('.'));
+    }
+    fieldSet.add(segments.join('.'));
+  }
+
+  const generatedAppends = appendSet.size ? Array.from(appendSet) : undefined;
+  const generatedFields = fieldSet.size ? Array.from(fieldSet) : undefined;
+  return { generatedAppends, generatedFields };
+}
+
 type Getter<T = any> = (ctx: FlowContext) => T | Promise<T>;
 
 export interface MetaTreeNode {
@@ -1030,6 +1086,22 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       const needServer = Object.keys(serverVarPaths).length > 0;
       let serverResolved = template;
       if (needServer) {
+        const inferRecordRefWithMeta = (ctx: any): RecordRef | undefined => {
+          const ref = inferRecordRef(ctx as any);
+          if (ref) return ref as RecordRef;
+          try {
+            const tk = ctx?.resource?.getMeta?.('currentFilterByTk');
+            if (typeof tk === 'undefined' || tk === null) return undefined;
+            const collection =
+              ctx?.collection?.name || ctx?.resource?.getResourceName?.()?.split?.('.')?.slice?.(-1)?.[0];
+            if (!collection) return undefined;
+            const dataSourceKey = ctx?.collection?.dataSourceKey || ctx?.resource?.getDataSourceKey?.();
+            return { collection, dataSourceKey, filterByTk: tk } as RecordRef;
+          } catch (_) {
+            return undefined;
+          }
+        };
+
         const collectFromMeta = async (): Promise<Record<string, any>> => {
           const out: Record<string, any> = {};
           try {
@@ -1069,7 +1141,62 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         };
 
         const inputFromMeta = await collectFromMeta();
-        const autoInput = { ...inputFromMeta };
+        const autoInput = { ...inputFromMeta } as Record<string, any>;
+
+        // Special-case: formValues
+        // If server needs to resolve some formValues paths but meta params only cover association anchors
+        // (e.g. formValues.customer) and some top-level paths are missing (e.g. formValues.status),
+        // inject a top-level record anchor (formValues -> { collection, filterByTk, fields/appends }) so server can fetch DB values.
+        // This anchor MUST be selective (fields/appends derived from serverVarPaths['formValues']) to avoid server overriding
+        // client-only values for configured form fields in the same template.
+        try {
+          const varName = 'formValues';
+          const neededPaths = serverVarPaths[varName] || [];
+          if (neededPaths.length) {
+            const requiredTop = new Set<string>();
+            for (const p of neededPaths) {
+              const top = topLevelOf(p);
+              if (top) requiredTop.add(top);
+            }
+            const metaOut = inputFromMeta?.[varName];
+            const builtTop = new Set<string>();
+            if (metaOut && typeof metaOut === 'object' && !Array.isArray(metaOut) && !isRecordRefLike(metaOut)) {
+              Object.keys(metaOut).forEach((k) => builtTop.add(k));
+            }
+
+            const missing = [...requiredTop].filter((k) => !builtTop.has(k));
+            if (missing.length) {
+              const ref = inferRecordRefWithMeta(this);
+              if (ref) {
+                const { generatedFields, generatedAppends } = inferSelectsFromUsage(neededPaths);
+                const recordRef: RecordRef = {
+                  ...ref,
+                  fields: generatedFields,
+                  appends: generatedAppends,
+                };
+
+                // Preserve existing association anchors by lifting them to dotted keys before overwriting formValues
+                const existing = autoInput[varName];
+                if (
+                  existing &&
+                  typeof existing === 'object' &&
+                  !Array.isArray(existing) &&
+                  !isRecordRefLike(existing)
+                ) {
+                  for (const [k, v] of Object.entries(existing)) {
+                    autoInput[`${varName}.${k}`] = v;
+                  }
+                  delete autoInput[varName];
+                }
+
+                autoInput[varName] = recordRef;
+              }
+            }
+          }
+        } catch (_) {
+          // ignore
+        }
+
         const autoContextParams = Object.keys(autoInput).length
           ? _buildServerContextParams(this, autoInput)
           : undefined;