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

package/src/flowEngine.ts

@@ -17,6 +17,9 @@ import { FlowSettings } from './flowSettings';
 import { ErrorFlowModel, FlowModel } from './models';
 import { ReactView } from './ReactView';
 import { APIResource, FlowResource, MultiRecordResource, SingleRecordResource, SQLResource } from './resources';
+import { Emitter } from './emitter';
+import ModelOperationScheduler from './scheduler/ModelOperationScheduler';
+import type { ScheduleOptions, ScheduledCancel } from './scheduler/ModelOperationScheduler';
 import type {
   ActionDefinition,
   ApplyFlowCacheEntry,
@@ -27,6 +30,8 @@ import type {
   ModelConstructor,
   PersistOptions,
   ResourceType,
+  RegisteredModelClassName,
+  ResolveUseResult,
 } from './types';
 import { isInheritedFrom } from './utils';
 
@@ -114,6 +119,27 @@ export class FlowEngine {
 
   private _resources = new Map<string, typeof FlowResource>();
 
+  /**
+   * Data change registry used to coordinate "refresh on active" across view-scoped engines.
+   *
+   * Keyed by: dataSourceKey -> resourceName -> version.
+   * - mark: increments version
+   * - get: returns current version (default 0)
+   *
+   * NOTE: ViewScopedFlowEngine proxies delegate non-local fields/methods to parents, so this
+   * registry naturally lives on the root engine instance and is shared across the whole view stack.
+   */
+  private _dataSourceDirtyVersions: Map<string, Map<string, number>> = new Map();
+
+  /**
+   * 引擎事件总线（目前用于模型生命周期等事件）。
+   * ViewScopedFlowEngine 持有自己的实例，实现作用域隔离。
+   */
+  public emitter: Emitter = new Emitter();
+
+  /** 调度器：仅在 View 作用域引擎本地启用；根/Block 作用域默认不持有 */
+  private _modelOperationScheduler?: ModelOperationScheduler;
+
   logger: pino.Logger;
 
   /**
@@ -130,7 +156,7 @@ export class FlowEngine {
    */
   public reactView: ReactView;
   /**
-   * Flow executor that runs flows and auto-flows.
+   * Flow executor that runs event flows.
    */
   public executor: FlowExecutor;
 
@@ -165,6 +191,64 @@ export class FlowEngine {
     this.executor = new FlowExecutor(this);
   }
 
+  /** 获取/创建当前引擎的调度器（仅在本地作用域） */
+  public getScheduler(): ModelOperationScheduler {
+    if (!this._modelOperationScheduler) {
+      this._modelOperationScheduler = new ModelOperationScheduler(this);
+    }
+    return this._modelOperationScheduler;
+  }
+
+  /** 释放并清理当前引擎本地调度器（若存在） */
+  public disposeScheduler(): void {
+    if (this._modelOperationScheduler) {
+      try {
+        this._modelOperationScheduler.dispose();
+      } finally {
+        this._modelOperationScheduler = undefined;
+      }
+    }
+  }
+
+  /**
+   * Mark a data source resource as "dirty" (changed).
+   * This is used by data blocks to decide whether to refresh when a view becomes active.
+   */
+  public markDataSourceDirty(dataSourceKey: string, resourceName: string): number {
+    const dsKey = String(dataSourceKey || 'main');
+    const resName = String(resourceName || '');
+    if (!resName) return this.getDataSourceDirtyVersion(dsKey, resName);
+
+    const ds = this._dataSourceDirtyVersions.get(dsKey) || new Map<string, number>();
+    if (!this._dataSourceDirtyVersions.has(dsKey)) {
+      this._dataSourceDirtyVersions.set(dsKey, ds);
+    }
+    const next = (ds.get(resName) || 0) + 1;
+    ds.set(resName, next);
+    return next;
+  }
+
+  /**
+   * Get current dirty version for a data source resource.
+   * Returns 0 when no writes have been recorded.
+   */
+  public getDataSourceDirtyVersion(dataSourceKey: string, resourceName: string): number {
+    const dsKey = String(dataSourceKey || 'main');
+    const resName = String(resourceName || '');
+    if (!resName) return 0;
+    return this._dataSourceDirtyVersions.get(dsKey)?.get(resName) || 0;
+  }
+
+  /** 在目标模型生命周期达成时执行操作（仅在 View 引擎本地存储计划） */
+  public scheduleModelOperation(
+    fromModelOrUid: FlowModel | string,
+    toUid: string,
+    fn: (model: FlowModel) => Promise<void> | void,
+    options?: ScheduleOptions,
+  ): ScheduledCancel {
+    return this.getScheduler().schedule(fromModelOrUid, toUid, fn, options);
+  }
+
   /** 上一个引擎（根引擎为 undefined） */
   get previousEngine(): FlowEngine | undefined {
     return this._previousEngine;
@@ -417,7 +501,14 @@ export class FlowEngine {
     extra?: { delegateToParent?: boolean; delegate?: FlowContext },
   ): T {
     const { parentId, uid, use: modelClassName, subModels } = options;
-    const ModelClass = typeof modelClassName === 'string' ? this.getModelClass(modelClassName) : modelClassName;
+    const parentModel = parentId
+      ? ((this.getModel(parentId) || this.previousEngine?.getModel(parentId)) as FlowModel | undefined)
+      : undefined;
+    const ModelClass = this._resolveModelClass(
+      typeof modelClassName === 'string' ? this.getModelClass(modelClassName) : modelClassName,
+      options,
+      parentModel,
+    );
 
     if (uid && this._modelInstances.has(uid)) {
       return this._modelInstances.get(uid) as T;
@@ -436,8 +527,8 @@ export class FlowEngine {
       modelInstance.context.addDelegate(extra.delegate);
     }
 
-    if (parentId && this._modelInstances.has(parentId)) {
-      modelInstance.setParent(this._modelInstances.get(parentId));
+    if (parentModel) {
+      modelInstance.setParent(parentModel);
       if (extra?.delegateToParent === false) {
         modelInstance.removeParentDelegate();
       }
@@ -447,6 +538,12 @@ export class FlowEngine {
 
     modelInstance.onInit(options);
 
+    // 发射 created 生命周期事件
+    void this.emitter.emitAsync('model:created', {
+      uid: modelInstance.uid,
+      model: modelInstance,
+    });
+
     // 在模型实例化阶段应用 flow 级 defaultParams（仅填充缺失的 stepParams，不覆盖）
     // 不阻塞创建流程：允许 defaultParams 为异步函数
     this._applyFlowDefinitionDefaultParams(modelInstance as FlowModel).catch((err) => {
@@ -458,6 +555,67 @@ export class FlowEngine {
     return modelInstance as T;
   }
 
+  /**
+   * 按类上的 resolveUse 链路解析最终用于实例化的模型类。
+   * 允许模型类根据上下文动态指定实际使用的类，支持多级 resolveUse。
+   */
+  private _resolveModelClass(
+    initial: ModelConstructor | undefined,
+    options: CreateModelOptions,
+    parent?: FlowModel,
+  ): ModelConstructor | undefined {
+    const normalize = (
+      resolved: ResolveUseResult | void,
+    ): { target?: RegisteredModelClassName | ModelConstructor; stop?: boolean } => {
+      if (!resolved) return {};
+      if (typeof resolved === 'object' && 'use' in resolved) {
+        return { target: resolved.use, stop: !!resolved.stop };
+      }
+      return { target: resolved as any, stop: false };
+    };
+
+    let current = initial;
+    const visited = new Set<ModelConstructor>();
+
+    while (current) {
+      if (visited.has(current)) {
+        console.warn(`FlowEngine: resolveUse circular reference detected on '${current.name}'.`);
+        break;
+      }
+      visited.add(current);
+
+      const resolver = (current as any)?.resolveUse as
+        | ((opts: CreateModelOptions, engine: FlowEngine, parent?: FlowModel) => ResolveUseResult | void)
+        | undefined;
+      if (typeof resolver !== 'function') {
+        break;
+      }
+
+      const { target, stop } = normalize(resolver(options, this, parent));
+      if (!target || target === current) {
+        break;
+      }
+
+      let next: ModelConstructor | undefined;
+      if (typeof target === 'string') {
+        next = this.getModelClass(target);
+        if (!next) {
+          console.warn(`FlowEngine: resolveUse returned '${target}' but no model is registered under that name.`);
+          return undefined;
+        }
+      } else {
+        next = target;
+      }
+
+      current = next;
+      if (stop) {
+        break;
+      }
+    }
+
+    return current;
+  }
+
   /**
    * 尝试应用当前模型可用 flow 的 defaultParams（如果存在）到 model.stepParams。
    * 仅对尚未存在的步骤参数进行填充，不覆盖已有值。
@@ -544,6 +702,8 @@ export class FlowEngine {
       return false;
     }
     const modelInstance = this._modelInstances.get(uid) as FlowModel;
+    // Ensure any cached beforeRender results tied to this uid are cleared before removal.
+    modelInstance.invalidateFlowCache(undefined, true);
     modelInstance.clearForks();
     // 从父模型中移除当前模型的引用
     if (modelInstance.parent?.subModels) {
@@ -555,19 +715,73 @@ export class FlowEngine {
           if (index !== -1) {
             subModelValue.splice(index, 1);
             modelInstance.parent.emitter.emit('onSubModelRemoved', modelInstance);
+            this.emitter?.emit('model:subModel:removed', {
+              parentUid: modelInstance.parent.uid,
+              parent: modelInstance.parent,
+              model: modelInstance,
+            });
             break;
           }
         } else if (subModelValue && subModelValue === modelInstance) {
           delete modelInstance.parent.subModels[subKey];
           modelInstance.parent.emitter.emit('onSubModelRemoved', modelInstance);
+          this.emitter?.emit('model:subModel:removed', {
+            parentUid: modelInstance.parent.uid,
+            parent: modelInstance.parent,
+            model: modelInstance,
+          });
           break;
         }
       }
     }
     this._modelInstances.delete(uid);
+
+    // 发射 destroyed 生命周期事件（在移除后，但携带实例便于调度器传递；严格模式：不吞错）
+    void this.emitter.emitAsync('model:destroyed', {
+      uid,
+      model: modelInstance,
+    });
     return true;
   }
 
+  /**
+   * Remove a local model instance and all its sub-models recursively.
+   * @param {string} uid UID of the model instance to destroy
+   * @returns {boolean} Returns true if successfully destroyed, false otherwise
+   */
+  public removeModelWithSubModels(uid: string): boolean {
+    const model = this.getModel(uid);
+    if (!model) {
+      return false;
+    }
+
+    const collectDescendants = (m: FlowModel, acc: FlowModel[]) => {
+      if (m.subModels) {
+        for (const key in m.subModels) {
+          const sub = m.subModels[key];
+          if (Array.isArray(sub)) {
+            [...sub].forEach((s) => collectDescendants(s, acc));
+          } else if (sub) {
+            collectDescendants(sub, acc);
+          }
+        }
+      }
+      acc.push(m);
+    };
+
+    const allModels: FlowModel[] = [];
+    collectDescendants(model, allModels);
+
+    let success = true;
+    for (const m of allModels) {
+      if (!this.removeModel(m.uid)) {
+        success = false;
+      }
+    }
+
+    return success;
+  }
+
   /**
    * Check if the model repository is set.
    * @returns {boolean} Returns true if set, false otherwise.
@@ -581,6 +795,110 @@ export class FlowEngine {
     return true;
   }
 
+  /**
+   * Try to locate a model instance in previous engines (view stack) by uid.
+   * This is mainly used by view-scoped engines to reuse already-loaded model trees
+   * (e.g. models created from local JSON) without hitting the repository.
+   */
+  private findModelInPreviousEngines<T extends FlowModel = FlowModel>(uid: string): T | undefined {
+    let eng = this.previousEngine;
+    while (eng) {
+      const found = eng.getModel<T>(uid);
+      if (found) return found;
+      eng = eng.previousEngine;
+    }
+    return undefined;
+  }
+
+  /**
+   * Try to locate a sub-model in previous engines (view stack) by (parentId, subKey).
+   */
+  private findSubModelInPreviousEngines<T extends FlowModel = FlowModel>(
+    parentId: string,
+    subKey: string,
+  ): { parent: FlowModel; model: T } | undefined {
+    let eng = this.previousEngine;
+    while (eng) {
+      const parent = eng.getModel<FlowModel>(parentId);
+      if (parent) {
+        const sub = (parent.subModels as any)?.[subKey];
+        if (sub) {
+          const model = Array.isArray(sub) ? (sub[0] as T) : (sub as T);
+          if (model) return { parent, model };
+        }
+      }
+      eng = eng.previousEngine;
+    }
+    return undefined;
+  }
+
+  /**
+   * Hydrate a model into current engine from an already-existing model instance in previous engines.
+   * - Avoids repository requests when the model tree is already present in memory.
+   */
+  private hydrateModelFromPreviousEngines<T extends FlowModel = FlowModel>(
+    options: any,
+    extra?: { delegateToParent?: boolean; delegate?: FlowContext },
+  ): T | null {
+    const uid = options?.uid;
+    const parentId = options?.parentId;
+    const subKey = options?.subKey;
+
+    // 1) Prefer exact uid match when provided.
+    if (uid && !this._modelInstances.has(uid)) {
+      const existing = this.findModelInPreviousEngines<T>(uid);
+      if (existing?.context.flowSettingsEnabled) {
+        // 如果模型实例启用 flowSettingsEnabled，直接返回 null, 避免旧数据
+        return null;
+      }
+      if (existing) {
+        const data = existing.serialize();
+        return this.createModel<T>(data as any, extra);
+      }
+    }
+
+    // 2) Parent/subKey lookup (common for pages/popups).
+    if (parentId && subKey) {
+      const found = this.findSubModelInPreviousEngines<T>(parentId, subKey);
+      if (!found || found.parent.context.flowSettingsEnabled) return null;
+
+      const { parent: parentFromPrev, model: modelFromPrev } = found;
+      // Ensure the parent shell exists in current engine so findModelByParentId can work locally.
+      let localParent = this.getModel<FlowModel>(parentId);
+      if (!localParent) {
+        const parentData = parentFromPrev.serialize();
+        delete (parentData as any).subModels;
+        localParent = this.createModel<FlowModel>(parentData as any, extra);
+      }
+      // Create (or reuse) the sub-model instance in current engine.
+      const modelData = modelFromPrev.serialize();
+      const localModel = this.createModel<T>(modelData as any, extra);
+
+      // Mount under local parent if not mounted yet (so later lookups by parentId/subKey won't hit repo).
+      const mounted = (localParent.subModels as any)?.[subKey];
+      if (Array.isArray(mounted)) {
+        const exists = mounted.some((m) => m?.uid === (localModel as any)?.uid);
+        if (!exists) {
+          localParent.addSubModel(subKey, localModel as any);
+        }
+      } else if (mounted instanceof FlowModel) {
+        // Keep existing instance when uid matches; otherwise, replace.
+        if (mounted.uid !== (localModel as any)?.uid) {
+          localParent.setSubModel(subKey, localModel as any);
+        }
+      } else {
+        if ((localModel as any)?.subType === 'array') {
+          localParent.addSubModel(subKey, localModel as any);
+        } else {
+          localParent.setSubModel(subKey, localModel as any);
+        }
+      }
+      return localModel;
+    }
+
+    return null;
+  }
+
   /**
    * Load a model instance (prefers local, falls back to repository).
    * @template T FlowModel subclass type, defaults to FlowModel.
@@ -589,12 +907,26 @@ export class FlowEngine {
    */
   async loadModel<T extends FlowModel = FlowModel>(options): Promise<T | null> {
     if (!this.ensureModelRepository()) return;
-    const model = this.findModelByParentId(options.parentId, options.subKey);
-    if (model) {
-      return model as T;
+    const refresh = !!options?.refresh;
+    if (!refresh) {
+      const model = this.findModelByParentId(options.parentId, options.subKey);
+      if (model) {
+        return model as T;
+      }
+      const hydrated = this.hydrateModelFromPreviousEngines<T>(options);
+      if (hydrated) {
+        return hydrated as T;
+      }
     }
     const data = await this._modelRepository.findOne(options);
-    return data?.uid ? this.createModel<T>(data as any) : null;
+    if (!data?.uid) return null;
+    if (refresh) {
+      const existing = this.getModel(data.uid);
+      if (existing) {
+        this.removeModelWithSubModels(existing.uid);
+      }
+    }
+    return this.createModel<T>(data as any);
   }
 
   /**
@@ -640,6 +972,12 @@ export class FlowEngine {
     if (m) {
       return m;
     }
+
+    const hydrated = this.hydrateModelFromPreviousEngines<T>(options, extra);
+    if (hydrated) {
+      return hydrated;
+    }
+
     const data = await this._modelRepository.findOne(options);
     let model: T | null = null;
     if (data?.uid) {
@@ -731,7 +1069,24 @@ export class FlowEngine {
     if (this.ensureModelRepository()) {
       await this._modelRepository.destroy(uid);
     }
-    return this.removeModel(uid);
+
+    const modelInstance = this._modelInstances.get(uid) as FlowModel;
+    const parent = modelInstance?.parent;
+    const result = this.removeModel(uid);
+    parent && parent.emitter.emit('onSubModelDestroyed', modelInstance);
+
+    return result;
+  }
+
+  /**
+   * Duplicate a model tree via repository API.
+   * Returns the duplicated model JSON (root with subModels) or null if not available.
+   * @param {string} uid UID of the model to duplicate
+   * @returns {Promise<any | null>} Duplicated model JSON or null
+   */
+  async duplicateModel(uid: string) {
+    if (!this.ensureModelRepository()) return null;
+    return this._modelRepository.duplicate(uid);
   }
 
   /**
@@ -803,9 +1158,15 @@ export class FlowEngine {
     // 7. 触发事件以通知其他部分模型已替换
     if (currentParent) {
       currentParent.emitter.setPaused(false);
-      currentParent.parent.invalidateAutoFlowCache(true);
+      currentParent.parent.invalidateFlowCache('beforeRender', true);
       currentParent.parent?.rerender();
       currentParent.emitter.emit('onSubModelReplaced', { oldModel, newModel });
+      this.emitter?.emit('model:subModel:replaced', {
+        parentUid: currentParent.uid,
+        parent: currentParent,
+        oldModel,
+        newModel,
+      });
     }
     await newModel.save();
     return newModel;
@@ -837,7 +1198,8 @@ export class FlowEngine {
         return false;
       }
 
-      const findIndex = (model: FlowModel) => subModels.findIndex((item) => item.uid === model.uid);
+      const subModelsCopy = [...subModels];
+      const findIndex = (model: FlowModel) => subModelsCopy.findIndex((item) => item.uid === model.uid);
 
       const currentIndex = findIndex(sourceModel);
       const targetIndex = findIndex(targetModel);
@@ -853,14 +1215,17 @@ export class FlowEngine {
       }
 
       // 使用splice直接移动数组元素（O(n)比排序O(n log n)更快）
-      const [movedModel] = subModels.splice(currentIndex, 1);
-      subModels.splice(targetIndex, 0, movedModel);
+      const [movedModel] = subModelsCopy.splice(currentIndex, 1);
+      subModelsCopy.splice(targetIndex, 0, movedModel);
 
       // 重新分配连续的sortIndex
-      subModels.forEach((model, index) => {
+      subModelsCopy.forEach((model, index) => {
         model.sortIndex = index;
       });
 
+      // 更新父模型的 subModels 引用，确保拖拽后仍为可观察数组
+      subModels.splice(0, subModels.length, ...subModelsCopy);
+
       return true;
     };
     move(sourceModel, targetModel);
@@ -870,6 +1235,12 @@ export class FlowEngine {
     }
     // 触发事件以通知其他部分模型已移动
     sourceModel.parent.emitter.emit('onSubModelMoved', { source: sourceModel, target: targetModel });
+    this.emitter?.emit('model:subModel:moved', {
+      parentUid: sourceModel.parent?.uid,
+      parent: sourceModel.parent,
+      source: sourceModel,
+      target: targetModel,
+    });
   }
 
   /**