@nocobase/flow-engine 2.0.0-alpha.2

package/src/flowEngine.ts

@@ -0,0 +1,905 @@
+/**
+ * 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 { observable } from '@formily/reactive';
+import _ from 'lodash';
+import pino from 'pino';
+import { EngineActionRegistry } from './action-registry/EngineActionRegistry';
+import { EngineEventRegistry } from './event-registry/EngineEventRegistry';
+import { FlowExecutor } from './executor/FlowExecutor';
+import { FlowContext, FlowEngineContext, FlowRuntimeContext } from './flowContext';
+import { FlowSettings } from './flowSettings';
+import { ErrorFlowModel, FlowModel } from './models';
+import { ReactView } from './ReactView';
+import { APIResource, FlowResource, MultiRecordResource, SingleRecordResource, SQLResource } from './resources';
+import type {
+  ActionDefinition,
+  ApplyFlowCacheEntry,
+  CreateModelOptions,
+  EventDefinition,
+  FlowModelOptions,
+  IFlowModelRepository,
+  ModelConstructor,
+  PersistOptions,
+  ResourceType,
+} from './types';
+import { isInheritedFrom } from './utils';
+
+/**
+ * FlowEngine is the core class of the flow engine, responsible for managing flow models, actions, model repository, and more.
+ * It provides capabilities for registering, creating, finding, persisting, replacing, and moving models.
+ * Supports flow definitions, action definitions, model class inheritance and filtering.
+ * Integrates FlowEngineContext, FlowSettings, and ReactView for context, configuration, and view rendering.
+ *
+ * Main features:
+ * - Register, get, and find model classes and model instances
+ * - Register and get action definitions
+ * - Persist and query models via the model repository
+ * - Register flow definitions
+ * - Create, find, replace, move, and destroy model instances
+ * - Support for model class inheritance and filtering
+ * - Internationalization support
+ * - Integration with React view rendering
+ *
+ * @example
+ * const engine = new FlowEngine();
+ * engine.registerModels({ MyModel });
+ * engine.setModelRepository(new MyRepository());
+ * const model = engine.createModel({ use: 'MyModel', uid: 'xxx' });
+ */
+export class FlowEngine {
+  /**
+   * Global action registry
+   */
+  private _actionRegistry = new EngineActionRegistry();
+
+  /**
+   * Global event registry
+   */
+  private _eventRegistry = new EngineEventRegistry();
+
+  /**
+   * Registered model classes.
+   * Key is the model class name, value is the model class constructor.
+   * @private
+   */
+  private _modelClasses: Map<string, ModelConstructor> = observable.shallow(new Map());
+
+  /**
+   * Created model instances.
+   * Key is the model instance UID, value is the model instance object.
+   * @private
+   */
+  private _modelInstances: Map<string, any> = new Map();
+
+  /**
+   * The current model repository instance, implements IFlowModelRepository.
+   * Used for model persistence and queries.
+   * @private
+   */
+  private _modelRepository: IFlowModelRepository | null = null;
+
+  /**
+   * Flow application cache.
+   * Key is the cache key, value is ApplyFlowCacheEntry.
+   * @private
+   */
+  private _applyFlowCache = new Map<string, ApplyFlowCacheEntry>();
+
+  /**
+   * Model saving state tracking.
+   * Key is the model UID, value is the save promise.
+   * @private
+   */
+  private _savingModels = new Map<string, Promise<any>>();
+
+  /**
+   * Flow engine context object.
+   * @private
+   */
+  private _flowContext: FlowEngineContext;
+
+  /**
+   * 视图作用域引擎的栈式链表指针。
+   * - previousEngine：打开当前视图的上一个引擎
+   * - nextEngine：在当前之上的下一个引擎
+   */
+  private _previousEngine?: FlowEngine;
+  private _nextEngine?: FlowEngine;
+
+  private _resources = new Map<string, typeof FlowResource>();
+
+  logger: pino.Logger;
+
+  /**
+   * Flow settings, including components and form scopes.
+   * @public
+   */
+  public flowSettings: FlowSettings;
+
+  /**
+   * Experimental API: Integrates React view rendering capability into FlowEngine.
+   * This property may change or be removed in the future. Use with caution.
+   * @experimental
+   * @public
+   */
+  public reactView: ReactView;
+  /**
+   * Flow executor that runs flows and auto-flows.
+   */
+  public executor: FlowExecutor;
+
+  /**
+   * Constructor. Initializes React view, registers default model and form scopes.
+   */
+  constructor() {
+    this.reactView = new ReactView(this);
+    this.flowSettings = new FlowSettings(this);
+    this.flowSettings.registerScopes({ t: this.translate.bind(this) });
+    this.registerModels({ FlowModel }); // 会造成循环依赖问题，移除掉
+    this.registerResources({
+      FlowResource,
+      SQLResource,
+      APIResource,
+      SingleRecordResource,
+      MultiRecordResource,
+    });
+    this.logger = pino({
+      level: 'trace',
+      browser: {
+        write: {
+          fatal: (o) => console.trace(o),
+          error: (o) => console.error(o),
+          warn: (o) => console.warn(o),
+          info: (o) => console.info(o),
+          debug: (o) => console.debug(o),
+          trace: (o) => console.trace(o),
+        },
+      },
+    });
+    this.executor = new FlowExecutor(this);
+  }
+
+  /** 上一个引擎（根引擎为 undefined） */
+  get previousEngine(): FlowEngine | undefined {
+    return this._previousEngine;
+  }
+  /** 下一个引擎（若存在） */
+  get nextEngine(): FlowEngine | undefined {
+    return this._nextEngine;
+  }
+
+  /**
+   * 将当前引擎链接到 prev 之后（用于视图打开时形成栈关系）。
+   */
+  public linkAfter(engine: FlowEngine): void {
+    // 找到栈底
+    let prev: FlowEngine = engine;
+    while (prev._nextEngine) prev = prev._nextEngine;
+    this._previousEngine = prev;
+    if (prev) {
+      prev._nextEngine = this;
+    }
+  }
+
+  /**
+   * 将当前引擎从栈中移除并修复相邻指针（用于视图关闭时）。
+   */
+  public unlinkFromStack(): void {
+    const prev = this._previousEngine;
+    const next = this._nextEngine;
+    if (prev) {
+      prev._nextEngine = undefined;
+    }
+  }
+
+  // （已移除）getModelGlobal/forEachModelGlobal/getAllModelsGlobal：不再维护冗余全局遍历 API
+
+  /**
+   * Get the flow engine context object.
+   * @returns {FlowEngineContext} Flow engine context
+   */
+  get context() {
+    if (!this._flowContext) {
+      this._flowContext = new FlowEngineContext(this);
+    }
+    return this._flowContext;
+  }
+
+  get dataSourceManager() {
+    return this.context.dataSourceManager;
+  }
+
+  /**
+   * Get the flow application cache.
+   * @returns {Map<string, ApplyFlowCacheEntry>} Flow application cache map
+   * @internal
+   */
+  get applyFlowCache() {
+    return this._applyFlowCache;
+  }
+
+  /**
+   * Set the model repository for persisting and querying model instances.
+   * If a model repository was already set, it will be overwritten and a warning will be printed.
+   * @param {IFlowModelRepository} modelRepository The model repository instance implementing IFlowModelRepository.
+   * @example
+   * flowEngine.setModelRepository(new MyFlowModelRepository());
+   */
+  setModelRepository(modelRepository: IFlowModelRepository) {
+    if (this._modelRepository) {
+      console.warn('FlowEngine: Model repository is already set and will be overwritten.');
+    }
+    this._modelRepository = modelRepository;
+  }
+
+  get modelRepository(): IFlowModelRepository | null {
+    return this._modelRepository;
+  }
+
+  /**
+   * Internationalization translation method, calls the context's t method.
+   * @param {string} keyOrTemplate Translation key or template string
+   * @param {any} [options] Optional parameters
+   * @returns {string} Translated string
+   */
+  translate(keyOrTemplate: string, options?: any): string {
+    return this.context.t(keyOrTemplate, options);
+  }
+
+  /**
+   * Register multiple actions.
+   * @param {Record<string, ActionDefinition>} actions Action definition object collection
+   */
+  registerActions(actions: Record<string, ActionDefinition>): void {
+    this._actionRegistry.registerActions(actions);
+  }
+
+  /**
+   * Get a registered action definition.
+   * @template TModel Specific FlowModel subclass type
+   * @param {string} name Action name
+   * @returns {ActionDefinition<TModel> | undefined} Action definition, or undefined if not found
+   */
+  public getAction<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowRuntimeContext<TModel>>(
+    name: string,
+  ): ActionDefinition<TModel, TCtx> | undefined {
+    return this._actionRegistry.getAction<TModel, TCtx>(name);
+  }
+
+  /**
+   * Get all registered global actions.
+   * Returns a new Map to avoid external mutation of internal state.
+   */
+  public getActions<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowRuntimeContext<TModel>>(): Map<
+    string,
+    ActionDefinition<TModel, TCtx>
+  > {
+    return this._actionRegistry.getActions<TModel, TCtx>();
+  }
+
+  /**
+   * Register multiple events.
+   */
+  registerEvents(events: Record<string, EventDefinition>): void {
+    this._eventRegistry.registerEvents(events);
+  }
+
+  /**
+   * Get a registered event definition.
+   */
+  public getEvent<TModel extends FlowModel = FlowModel>(name: string): EventDefinition<TModel> | undefined {
+    return this._eventRegistry.getEvent<TModel>(name);
+  }
+
+  /**
+   * Get all registered global events.
+   */
+  public getEvents<TModel extends FlowModel = FlowModel>(): Map<string, EventDefinition<TModel>> {
+    return this._eventRegistry.getEvents<TModel>();
+  }
+
+  /**
+   * Register a single model class.
+   * @param {string} name Model class name
+   * @param {ModelConstructor} modelClass Model class constructor
+   * @private
+   */
+  #registerModel(name: string, modelClass: ModelConstructor): void {
+    if (this._modelClasses.has(name)) {
+      console.warn(`FlowEngine: Model class with name '${name}' is already registered and will be overwritten.`);
+    }
+    Object.defineProperty(modelClass, 'name', { value: name });
+    this._modelClasses.set(name, modelClass);
+  }
+
+  /**
+   * Register multiple model classes.
+   * @param {Record<string, ModelConstructor>} models Model class map, key is model name, value is model constructor
+   * @returns {void}
+   * @example
+   * flowEngine.registerModels({ UserModel, OrderModel });
+   */
+  public registerModels(models: Record<string, ModelConstructor | typeof FlowModel<any>>) {
+    for (const [name, modelClass] of Object.entries(models)) {
+      this.#registerModel(name, modelClass);
+    }
+  }
+
+  registerResources(resources: Record<string, any>) {
+    for (const [name, resourceClass] of Object.entries(resources)) {
+      this._resources.set(name, resourceClass);
+    }
+  }
+
+  createResource<T = FlowResource>(resourceType: ResourceType<T>, options?: { context?: FlowContext }): T {
+    if (typeof resourceType === 'string') {
+      const ResourceClass = this._resources.get(resourceType);
+      if (!ResourceClass) {
+        throw new Error(`Resource class '${resourceType}' not found. Please register it first.`);
+      }
+      return new ResourceClass((options?.context as any) || this.context) as T;
+    }
+    const R = resourceType;
+    return new R(options?.context || this.context) as T;
+  }
+
+  /**
+   * Get all registered model classes.
+   * @returns {Map<string, ModelConstructor>} Model class map
+   */
+  getModelClasses() {
+    return this._modelClasses;
+  }
+
+  /**
+   * Get a registered model class (constructor).
+   * @param {string} name Model class name
+   * @returns {ModelConstructor | undefined} Model constructor, or undefined if not found
+   */
+  public getModelClass(name: string): ModelConstructor | undefined {
+    return this._modelClasses.get(name);
+  }
+
+  /**
+   * Find a registered model class by predicate.
+   * @param predicate Callback function, arguments are (name, ModelClass), returns true if matched
+   * @returns {[string, ModelConstructor] | undefined} Matched model class and name
+   */
+  public findModelClass(
+    predicate: (name: string, ModelClass: ModelConstructor) => boolean,
+  ): [string, ModelConstructor] | undefined {
+    for (const [name, ModelClass] of this._modelClasses) {
+      if (predicate(name, ModelClass)) {
+        return [name, ModelClass];
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Filter model classes by base class (supports multi-level inheritance), with optional custom filter.
+   * @param {string | ModelConstructor} baseClass Base class name or constructor
+   * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+   * @returns {Map<string, ModelConstructor>} Model classes inherited from base class and passed the filter
+   */
+  public getSubclassesOf(
+    baseClass: string | ModelConstructor,
+    filter?: (ModelClass: ModelConstructor, className: string) => boolean,
+  ): Map<string, ModelConstructor> {
+    const parentModelClass = typeof baseClass === 'string' ? this.getModelClass(baseClass) : baseClass;
+    const result = new Map<string, ModelConstructor>();
+    if (!parentModelClass) return result;
+    for (const [className, ModelClass] of this._modelClasses) {
+      if (isInheritedFrom(ModelClass, parentModelClass)) {
+        if (!filter || filter(ModelClass, className)) {
+          result.set(className, ModelClass);
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Create and register a model instance.
+   * If an instance with the same UID exists, returns the existing instance.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {CreateModelOptions} options Model creation options
+   * @returns {T} Created model instance
+   */
+  public createModel<T extends FlowModel = FlowModel>(
+    options: CreateModelOptions,
+    extra?: { delegateToParent?: boolean; delegate?: FlowContext },
+  ): T {
+    const { parentId, uid, use: modelClassName, subModels } = options;
+    const ModelClass = typeof modelClassName === 'string' ? this.getModelClass(modelClassName) : modelClassName;
+
+    if (uid && this._modelInstances.has(uid)) {
+      return this._modelInstances.get(uid) as T;
+    }
+
+    let modelInstance: T | ErrorFlowModel;
+
+    if (!ModelClass) {
+      modelInstance = new ErrorFlowModel({ ...options, flowEngine: this } as any);
+      modelInstance.setErrorMessage(`Model class '${modelClassName}' not found. Please register it first.`);
+    } else {
+      modelInstance = new (ModelClass as ModelConstructor<T>)({ ...options, flowEngine: this } as any);
+    }
+
+    if (extra?.delegate) {
+      modelInstance.context.addDelegate(extra.delegate);
+    }
+
+    if (parentId && this._modelInstances.has(parentId)) {
+      modelInstance.setParent(this._modelInstances.get(parentId));
+      if (extra?.delegateToParent === false) {
+        modelInstance.removeParentDelegate();
+      }
+    }
+
+    this._modelInstances.set(modelInstance.uid, modelInstance);
+
+    modelInstance.onInit(options);
+
+    // 在模型实例化阶段应用 flow 级 defaultParams（仅填充缺失的 stepParams，不覆盖）
+    // 不阻塞创建流程：允许 defaultParams 为异步函数
+    this._applyFlowDefinitionDefaultParams(modelInstance as FlowModel).catch((err) => {
+      console.warn('FlowEngine: apply flow defaultParams failed:', err);
+    });
+
+    modelInstance._createSubModels(options.subModels);
+
+    return modelInstance as T;
+  }
+
+  /**
+   * 尝试应用当前模型可用 flow 的 defaultParams（如果存在）到 model.stepParams。
+   * 仅对尚未存在的步骤参数进行填充，不覆盖已有值。
+   */
+  async _applyFlowDefinitionDefaultParams(model: FlowModel) {
+    try {
+      const flows = model.getFlows();
+      if (!flows || flows.size === 0) return;
+      const ctx = model.context;
+      for (const [flowKey, flowDef] of flows.entries()) {
+        const dp = flowDef.defaultParams;
+        if (!dp) continue;
+
+        let resolved: any;
+        try {
+          resolved = typeof dp === 'function' ? await dp(ctx) : dp;
+        } catch (e) {
+          console.warn(`FlowEngine: resolve defaultParams of flow '${flowKey}' failed:`, e);
+          continue;
+        }
+
+        if (!resolved || typeof resolved !== 'object') continue;
+
+        // 仅支持：返回当前 flow 的步骤对象 { [stepKey]: params }
+        const stepsMap = (flowDef as any).getSteps?.() as Map<string, any> | undefined;
+        const stepKeys = stepsMap ? Array.from(stepsMap.keys()) : Object.keys(flowDef.steps || {});
+        const entries = Object.entries(resolved).filter(([k]) => stepKeys.includes(k));
+        if (entries.length === 0) continue;
+
+        for (const [stepKey, params] of entries) {
+          const exists = model.getStepParams(flowKey, stepKey as string);
+          if (exists === undefined && params && typeof params === 'object') {
+            model.setStepParams(flowKey, stepKey as string, params as any);
+          }
+        }
+      }
+    } catch (error) {
+      console.warn('FlowEngine: apply flow defaultParams error:', error);
+    }
+  }
+
+  /**
+   * Get a model instance by UID.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {string} uid Model instance UID
+   * @returns {T | undefined} Model instance, or undefined if not found
+   */
+  public getModel<T extends FlowModel = FlowModel>(uid: string, global?: boolean): T | undefined {
+    // 默认仅在当前引擎查找；只有当 global === true 时才跨视图栈查找
+    if (!global) {
+      return this._modelInstances.get(uid) as T | undefined;
+    }
+    // 跨视图栈查找：按视图栈从栈顶到根逐个查找
+    // 1) 找到栈顶引擎
+    let top: FlowEngine = this;
+    while (top.nextEngine) top = top.nextEngine;
+    // 2) 从栈顶向下查找，命中即返回
+    let eng: FlowEngine | undefined = top;
+    while (eng) {
+      const found = eng._modelInstances.get(uid) as T | undefined;
+      if (found) return found;
+      eng = eng.previousEngine;
+    }
+    return undefined;
+  }
+
+  /**
+   * Iterate all registered model instances.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {(model: T) => void} callback Callback function
+   */
+  forEachModel<T extends FlowModel = FlowModel>(callback: (model: T) => void): void {
+    this._modelInstances.forEach(callback);
+  }
+
+  /**
+   * Remove a local model instance.
+   * @param {string} uid UID of the model instance to destroy
+   * @returns {boolean} Returns true if successfully destroyed, false otherwise (e.g. instance does not exist)
+   */
+  public removeModel(uid: string): boolean {
+    if (!this._modelInstances.has(uid)) {
+      console.warn(`FlowEngine: Model with UID '${uid}' does not exist.`);
+      return false;
+    }
+    const modelInstance = this._modelInstances.get(uid) as FlowModel;
+    modelInstance.clearForks();
+    // 从父模型中移除当前模型的引用
+    if (modelInstance.parent?.subModels) {
+      for (const subKey in modelInstance.parent.subModels) {
+        const subModelValue = modelInstance.parent.subModels[subKey];
+
+        if (Array.isArray(subModelValue)) {
+          const index = subModelValue.findIndex((subModel) => subModel == modelInstance);
+          if (index !== -1) {
+            subModelValue.splice(index, 1);
+            modelInstance.parent.emitter.emit('onSubModelRemoved', modelInstance);
+            break;
+          }
+        } else if (subModelValue && subModelValue === modelInstance) {
+          delete modelInstance.parent.subModels[subKey];
+          modelInstance.parent.emitter.emit('onSubModelRemoved', modelInstance);
+          break;
+        }
+      }
+    }
+    this._modelInstances.delete(uid);
+    return true;
+  }
+
+  /**
+   * Check if the model repository is set.
+   * @returns {boolean} Returns true if set, false otherwise.
+   * @private
+   */
+  private ensureModelRepository(): boolean {
+    if (!this._modelRepository) {
+      // 不抛错，直接返回 false
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Load a model instance (prefers local, falls back to repository).
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {any} options Load options
+   * @returns {Promise<T | null>} Loaded model instance or null
+   */
+  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 data = await this._modelRepository.findOne(options);
+    return data?.uid ? this.createModel<T>(data as any) : null;
+  }
+
+  /**
+   * Find a sub-model by parent model ID and subKey.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {string} parentId Parent model UID
+   * @param {string} subKey Sub-model key
+   * @returns {T | null} Found sub-model or null
+   */
+  findModelByParentId<T extends FlowModel = FlowModel>(parentId: string, subKey: string): T | null {
+    if (parentId && this._modelInstances.has(parentId)) {
+      const parentModel = this._modelInstances.get(parentId) as FlowModel;
+      if (parentModel && parentModel.subModels[subKey]) {
+        const subModels = parentModel.subModels[subKey];
+        if (Array.isArray(subModels)) {
+          return subModels[0] as T; // 返回第一个子模型
+        } else {
+          return subModels as T;
+        }
+      }
+    }
+  }
+
+  /**
+   * Load or create a model instance.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {any} options Load or create options
+   * @returns {Promise<T | null>} Model instance or null
+   */
+  async loadOrCreateModel<T extends FlowModel = FlowModel>(
+    options,
+    extra?: {
+      delegateToParent?: boolean;
+      delegate?: FlowContext;
+    },
+  ): Promise<T | null> {
+    if (!this.ensureModelRepository()) return;
+    const { uid, parentId, subKey } = options;
+    if (uid && this._modelInstances.has(uid)) {
+      return this._modelInstances.get(uid) as T;
+    }
+    const m = this.findModelByParentId<T>(parentId, subKey);
+    if (m) {
+      return m;
+    }
+    const data = await this._modelRepository.findOne(options);
+    let model: T | null = null;
+    if (data?.uid) {
+      model = this.createModel<T>(data as any, extra);
+    } else {
+      model = this.createModel<T>(options, extra);
+      await model.save();
+    }
+    if (model.parent) {
+      const subModel = model.parent.findSubModel(model.subKey, (m) => {
+        return m.uid === model.uid;
+      });
+      if (subModel) {
+        return model;
+      }
+      if (model.subType === 'array') {
+        model.parent.addSubModel(model.subKey, model);
+      } else {
+        model.parent.setSubModel(model.subKey, model);
+      }
+    }
+    return model;
+  }
+
+  /**
+   * Persist and save a model instance.
+   * Prevents concurrent saves of the same model by tracking save operations.
+   * If a model is already being saved, subsequent calls will wait for the existing save to complete.
+   *
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {T} model Model instance to save
+   * @param {object} [options] Save options
+   * @param {boolean} [options.onlyStepParams] Whether to save only step parameters
+   * @returns {Promise<any>} Repository save result
+   */
+  async saveModel<T extends FlowModel = FlowModel>(model: T, options?: { onlyStepParams?: boolean }): Promise<any> {
+    if (!this.ensureModelRepository()) return;
+
+    const modelUid = model.uid;
+
+    // 如果这个 model 正在保存中，返回现有的保存 Promise
+    if (this._savingModels.has(modelUid)) {
+      this.logger.debug(`Model ${modelUid} is already being saved, waiting for existing save operation`);
+      return await this._savingModels.get(modelUid);
+    }
+
+    // 创建保存 Promise 并添加到追踪 Map 中
+    const savePromise = this._performModelSave(model, options);
+    this._savingModels.set(modelUid, savePromise);
+
+    try {
+      const result = await savePromise;
+      return result;
+    } finally {
+      // 无论成功还是失败，都要清除保存状态
+      this._savingModels.delete(modelUid);
+    }
+  }
+
+  /**
+   * Perform the actual model save operation.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {T} model Model instance to save
+   * @param {object} [options] Save options
+   * @returns {Promise<any>} Repository save result
+   * @private
+   */
+  async _performModelSave<T extends FlowModel = FlowModel>(
+    model: T,
+    options?: { onlyStepParams?: boolean },
+  ): Promise<any> {
+    this.logger.debug(`Starting save operation for model ${model.uid}`);
+    try {
+      const result = await this._modelRepository.save(model, options);
+      this.logger.debug(`Successfully saved model ${model.uid}`);
+      return result;
+    } catch (error) {
+      this.logger.error(`Failed to save model ${model.uid}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Destroy a model instance (persistently delete and remove local instance).
+   * @param {string} uid UID of the model to destroy
+   * @returns {Promise<boolean>} Whether destroyed successfully
+   */
+  async destroyModel(uid: string) {
+    if (this.ensureModelRepository()) {
+      await this._modelRepository.destroy(uid);
+    }
+    return this.removeModel(uid);
+  }
+
+  /**
+   * Replace a model instance with a new instance of a class.
+   * @template T New model type
+   * @param {string} uid UID of the model to replace
+   * @param {Partial<FlowModelOptions> | ((oldModel: FlowModel) => Partial<FlowModelOptions>)} [optionsOrFn]
+   *        Options for creating the new model, supports two forms:
+   *        1. Pass options directly
+   *        2. Pass a function that receives current options and returns new options
+   * @returns {Promise<T | null>} Newly created model instance
+   */
+  async replaceModel<T extends FlowModel = FlowModel>(
+    uid: string,
+    optionsOrFn?: Partial<FlowModelOptions> | ((currentOptions: FlowModelOptions) => Partial<FlowModelOptions>),
+  ): Promise<T | null> {
+    const oldModel = this.getModel(uid);
+    if (!oldModel) {
+      console.warn(`FlowEngine: Cannot replace model. Model with UID '${uid}' not found.`);
+      return null;
+    }
+
+    // 1. 保存当前模型的关键信息
+    const currentParent = oldModel.parent;
+    const currentSubKey = oldModel.subKey;
+    const currentSubType = oldModel.subType;
+    const currentOptions = oldModel.serialize();
+
+    // 2. 确定新的选项
+    let userOptions: Partial<FlowModelOptions>;
+
+    if (typeof optionsOrFn === 'function') {
+      // 函数模式：传入当前options，获取新的options
+      userOptions = optionsOrFn(oldModel as any);
+    } else {
+      // 对象模式：直接使用提供的options替换
+      userOptions = optionsOrFn || {};
+    }
+
+    // 3. 合并用户选项和关键属性
+    const newOptions = {
+      ..._.omit(currentOptions, ['subModels']),
+      ...userOptions,
+    } as CreateModelOptions;
+
+    // 暂停父模型的事件触发,
+    // TODO: find a better way to do this
+    if (currentParent) {
+      currentParent.emitter.setPaused(true);
+    }
+
+    // 4. 销毁当前模型（这会处理所有清理工作：持久化删除、内存清理、父模型引用等）
+    await oldModel.destroy();
+
+    // 5. 使用createModel创建新的模型实例
+    const newModel = this.createModel<T>(newOptions);
+
+    // 6. 如果有父模型，将新模型添加到父模型的subModels中
+    if (currentParent && currentSubKey) {
+      if (currentSubType === 'array') {
+        // 对于数组类型，使用addSubModel方法
+        currentParent.addSubModel(currentSubKey, newModel);
+      } else {
+        // 对于对象类型，使用setSubModel方法
+        currentParent.setSubModel(currentSubKey, newModel);
+      }
+    }
+
+    // 7. 触发事件以通知其他部分模型已替换
+    if (currentParent) {
+      currentParent.emitter.setPaused(false);
+      currentParent.parent.invalidateAutoFlowCache(true);
+      currentParent.parent?.rerender();
+      currentParent.emitter.emit('onSubModelReplaced', { oldModel, newModel });
+    }
+    await newModel.save();
+    return newModel;
+  }
+
+  /**
+   * Move a model instance within its parent model.
+   * @param {any} sourceId Source model UID
+   * @param {any} targetId Target model UID
+   * @returns {Promise<void>} No return value
+   */
+  async moveModel(sourceId: any, targetId: any, options?: PersistOptions): Promise<void> {
+    const sourceModel = this.getModel(sourceId);
+    const targetModel = this.getModel(targetId);
+    if (!sourceModel || !targetModel) {
+      console.warn(`FlowEngine: Cannot move model. Source or target model not found.`);
+      return;
+    }
+    const move = (sourceModel: FlowModel, targetModel: FlowModel) => {
+      if (!sourceModel.parent || !targetModel.parent || sourceModel.parent !== targetModel.parent) {
+        console.error('FlowModel.moveTo: Both models must have the same parent to perform move operation.');
+        return false;
+      }
+
+      const subModels = sourceModel.parent.subModels[sourceModel.subKey];
+
+      if (!subModels || !Array.isArray(subModels)) {
+        console.error('FlowModel.moveTo: Parent subModels must be an array to perform move operation.');
+        return false;
+      }
+
+      const findIndex = (model: FlowModel) => subModels.findIndex((item) => item.uid === model.uid);
+
+      const currentIndex = findIndex(sourceModel);
+      const targetIndex = findIndex(targetModel);
+
+      if (currentIndex === -1 || targetIndex === -1) {
+        console.error('FlowModel.moveTo: Current or target model not found in parent subModels.');
+        return false;
+      }
+
+      if (currentIndex === targetIndex) {
+        console.warn('FlowModel.moveTo: Current model is already at the target position. No action taken.');
+        return false;
+      }
+
+      // 使用splice直接移动数组元素（O(n)比排序O(n log n)更快）
+      const [movedModel] = subModels.splice(currentIndex, 1);
+      subModels.splice(targetIndex, 0, movedModel);
+
+      // 重新分配连续的sortIndex
+      subModels.forEach((model, index) => {
+        model.sortIndex = index;
+      });
+
+      return true;
+    };
+    move(sourceModel, targetModel);
+    if (options?.persist !== false && this.ensureModelRepository()) {
+      const position = sourceModel.sortIndex - targetModel.sortIndex > 0 ? 'after' : 'before';
+      await this._modelRepository.move(sourceId, targetId, position);
+    }
+    // 触发事件以通知其他部分模型已移动
+    sourceModel.parent.emitter.emit('onSubModelMoved', { source: sourceModel, target: targetModel });
+  }
+
+  /**
+   * Filter model classes by parent class (supports multi-level inheritance).
+   * @param {string | ModelConstructor} parentClass Parent class name or constructor
+   * @returns {Map<string, ModelConstructor>} Model classes inherited from the specified parent class
+   */
+  public filterModelClassByParent(parentClass: string | ModelConstructor) {
+    const parentModelClass = typeof parentClass === 'string' ? this.getModelClass(parentClass) : parentClass;
+    if (!parentModelClass) {
+      return new Map();
+    }
+    const modelClasses = new Map<string, ModelConstructor>();
+    for (const [className, ModelClass] of this._modelClasses) {
+      if (isInheritedFrom(ModelClass, parentModelClass)) {
+        modelClasses.set(className, ModelClass);
+      }
+    }
+    return modelClasses;
+  }
+
+  /**
+   * Generate a unique key for the flow application cache.
+   * @param {string} prefix Prefix
+   * @param {string} flowKey Flow key
+   * @param {string} modelUid Model UID
+   * @returns {string} Unique cache key
+   * @internal
+   */
+  static generateApplyFlowCacheKey(prefix: string, flowKey: string, modelUid: string): string {
+    return `${prefix}:${flowKey}:${modelUid}`;
+  }
+}