@nocobase/flow-engine 2.1.0-alpha.4 → 2.1.0-alpha.45

package/src/flowEngine.ts

@@ -24,7 +24,11 @@ import type {
   ActionDefinition,
   ApplyFlowCacheEntry,
   CreateModelOptions,
+  EnsureBatchResult,
   EventDefinition,
+  FlowModelLoaderEntry,
+  FlowModelLoaderInputMap,
+  FlowModelLoaderResult,
   FlowModelOptions,
   IFlowModelRepository,
   ModelConstructor,
@@ -35,6 +39,8 @@ import type {
 } from './types';
 import { isInheritedFrom } from './utils';
 
+const getFlowEngineLoggerLevel = () => (process.env.NODE_ENV === 'production' ? 'warn' : 'trace');
+
 /**
  * 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.
@@ -75,6 +81,32 @@ export class FlowEngine {
    */
   private _modelClasses: Map<string, ModelConstructor> = observable.shallow(new Map());
 
+  /**
+   * Registered model entries.
+   * Key is the model class name, value is the model loader entry.
+   * @private
+   */
+  private _modelLoaders: Map<string, FlowModelLoaderEntry> = new Map();
+
+  /**
+   * In-flight model loading promises.
+   * Key is the model class name, value is the loading promise.
+   * @private
+   */
+  private _loadingModelPromises: Map<string, Promise<ModelConstructor | null>> = new Map();
+
+  /**
+   * Whether model-loader preload has completed in this session.
+   * @private
+   */
+  private _modelLoadersPreloaded = false;
+
+  /**
+   * In-flight model-loader preload promise.
+   * @private
+   */
+  private _modelLoadersPreloadPromise?: Promise<EnsureBatchResult>;
+
   /**
    * Created model instances.
    * Key is the model instance UID, value is the model instance object.
@@ -117,6 +149,13 @@ export class FlowEngine {
   private _previousEngine?: FlowEngine;
   private _nextEngine?: FlowEngine;
 
+  /**
+   * 视图销毁回调。由 useDrawer / useDialog 在创建弹窗视图时注册，
+   * 供外部（如 afterSuccess）通过引擎栈遍历来关闭多层弹窗。
+   * embed 视图（usePage）不注册此回调，因此 destroyView() 会自然跳过。
+   */
+  private _destroyView?: () => void;
+
   private _resources = new Map<string, typeof FlowResource>();
 
   /**
@@ -176,7 +215,7 @@ export class FlowEngine {
       MultiRecordResource,
     });
     this.logger = pino({
-      level: 'trace',
+      level: getFlowEngineLoggerLevel(),
       browser: {
         write: {
           fatal: (o) => console.trace(o),
@@ -282,6 +321,28 @@ export class FlowEngine {
     }
   }
 
+  /**
+   * 注册视图销毁回调（由 useDrawer / useDialog 调用）。
+   */
+  public setDestroyView(fn: () => void): void {
+    this._destroyView = fn;
+  }
+
+  /**
+   * 关闭当前引擎关联的弹窗视图。
+   * 路由触发的弹窗会先 navigation.back() 清理 URL，再 destroy() 移除元素；
+   * 非路由弹窗直接 destroy()。
+   * embed 视图不注册回调，调用时返回 false 自动跳过。
+   * @returns 是否成功执行
+   */
+  public destroyView(): boolean {
+    if (this._destroyView) {
+      this._destroyView();
+      return true;
+    }
+    return false;
+  }
+
   // （已移除）getModelGlobal/forEachModelGlobal/getAllModelsGlobal：不再维护冗余全局遍历 API
 
   /**
@@ -395,6 +456,13 @@ export class FlowEngine {
    * @private
    */
   #registerModel(name: string, modelClass: ModelConstructor): void {
+    return this._registerModel(name, modelClass);
+  }
+
+  /**
+   * for proxy instance, the #registerModel can't be called.
+   */
+  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.`);
     }
@@ -415,6 +483,306 @@ export class FlowEngine {
     }
   }
 
+  /**
+   * Register multiple model loader entries.
+   * The `extends` field declares parent class(es) for async subclass discovery via `getSubclassesOfAsync`.
+   * It accepts `string | ModelConstructor | (string | ModelConstructor)[]` and is normalized to `string[]` internally.
+   * @param {FlowModelLoaderInputMap} loaders Model loader input map
+   * @returns {void}
+   * @example
+   * flowEngine.registerModelLoaders({
+   *   DemoModel: {
+   *     extends: 'BaseModel',
+   *     loader: () => import('./models/DemoModel'),
+   *   },
+   * });
+   */
+  public registerModelLoaders(loaders: FlowModelLoaderInputMap): void {
+    let changed = false;
+    for (const [name, input] of Object.entries(loaders)) {
+      if (this._modelLoaders.has(name)) {
+        console.warn(`FlowEngine: Model loader with name '${name}' is already registered and will be overwritten.`);
+      }
+      const entry: FlowModelLoaderEntry = {
+        loader: input.loader,
+      };
+      if (input.extends != null) {
+        const raw = Array.isArray(input.extends) ? input.extends : [input.extends];
+        entry.extends = raw.map((item) => (typeof item === 'string' ? item : item.name));
+      }
+      this._modelLoaders.set(name, entry);
+      changed = true;
+    }
+    if (changed) {
+      this._modelLoadersPreloaded = false;
+      this._modelLoadersPreloadPromise = undefined;
+    }
+  }
+
+  /**
+   * Get a registered model class (constructor) asynchronously.
+   * This will first ensure the model loader entry is resolved.
+   * @param {string} name Model class name
+   * @returns {Promise<ModelConstructor | undefined>} Model constructor, or undefined if not found
+   */
+  public async getModelClassAsync(name: string): Promise<ModelConstructor | undefined> {
+    await this.ensureModel(name);
+    return this.getModelClass(name);
+  }
+
+  /**
+   * Get all registered model classes asynchronously.
+   * This will first ensure all registered model loader entries are resolved.
+   * @returns {Promise<Map<string, ModelConstructor>>} Model class map
+   */
+  public async getModelClassesAsync(): Promise<Map<string, ModelConstructor>> {
+    await this.ensureModels(Array.from(this._modelLoaders.keys()));
+    return this.getModelClasses();
+  }
+
+  /**
+   * Create and register a model instance asynchronously.
+   * This will first ensure all string-based model references in the model tree are resolved.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {CreateModelOptions} options Model creation options
+   * @returns {Promise<T>} Created model instance
+   */
+  public async createModelAsync<T extends FlowModel = FlowModel>(
+    options: CreateModelOptions,
+    extra?: { delegateToParent?: boolean; delegate?: FlowContext },
+  ): Promise<T> {
+    await this.resolveModelTree(options);
+    return this.createModel<T>(options, extra);
+  }
+
+  /**
+   * Normalize a loader result into a model constructor.
+   * @param {string} name Model class name
+   * @param {FlowModelLoaderResult} loaded Loader result
+   * @returns {ModelConstructor | null} Normalized model constructor
+   * @private
+   */
+  private normalizeModelLoaderResult(name: string, loaded: FlowModelLoaderResult): ModelConstructor | null {
+    if (typeof loaded === 'function') {
+      return loaded as ModelConstructor;
+    }
+    if (loaded && typeof loaded === 'object') {
+      const defaultExport = loaded.default;
+      if (typeof defaultExport === 'function') {
+        return defaultExport as ModelConstructor;
+      }
+      const namedExport = loaded[name];
+      if (typeof namedExport === 'function') {
+        return namedExport as ModelConstructor;
+      }
+    }
+    console.warn(`FlowEngine: model loader for '${name}' did not resolve to a valid model constructor.`);
+    return null;
+  }
+
+  /**
+   * Collect string-based model names from a model tree.
+   * @param {unknown} data Model tree data
+   * @param {Set<string>} names Model name set
+   * @private
+   */
+  private collectModelNamesFromTree(data: unknown, names: Set<string>): void {
+    if (!data || typeof data !== 'object') {
+      return;
+    }
+    if (Array.isArray(data)) {
+      data.forEach((item) => this.collectModelNamesFromTree(item, names));
+      return;
+    }
+
+    const tree = data as Record<string, any>;
+    if (typeof tree.use === 'string') {
+      names.add(tree.use);
+    }
+
+    const subModels = tree.subModels;
+    if (!subModels || typeof subModels !== 'object') {
+      return;
+    }
+
+    Object.values(subModels).forEach((value) => {
+      this.collectModelNamesFromTree(value, names);
+    });
+  }
+
+  /**
+   * Collect additional model names from object-form meta.createModelOptions defaults.
+   * @param {ModelConstructor} modelClass Model class constructor
+   * @param {Set<string>} names Model name set
+   * @private
+   */
+  private collectModelNamesFromMetaDefaults(modelClass: ModelConstructor, names: Set<string>): void {
+    const metaCreate = (modelClass as typeof FlowModel).meta?.createModelOptions;
+    if (metaCreate && typeof metaCreate === 'object') {
+      this.collectModelNamesFromTree(metaCreate, names);
+    }
+  }
+
+  /**
+   * Ensure a single model class is available.
+   * @param {string} name Model class name
+   * @returns {Promise<ModelConstructor | null>} Model constructor or null when resolution fails
+   * @private
+   */
+  private async ensureModel(name: string): Promise<ModelConstructor | null> {
+    const existing = this._modelClasses.get(name);
+    if (existing) {
+      return existing;
+    }
+
+    const inflight = this._loadingModelPromises.get(name);
+    if (inflight) {
+      return inflight;
+    }
+
+    const entry = this._modelLoaders.get(name);
+    if (!entry) {
+      console.warn(`FlowEngine: Model entry '${name}' not found. Falling back to ErrorFlowModel when needed.`);
+      return null;
+    }
+
+    const promise = (async () => {
+      try {
+        const loaded = await entry.loader();
+        const modelClass = this.normalizeModelLoaderResult(name, loaded);
+        if (!modelClass) {
+          return null;
+        }
+        // 这里拿到的 this 是 Proxy(FlowEngine) 而不是原始的 FlowEngine，无法直接调用 #registerModel
+        this._registerModel(name, modelClass);
+        return modelClass;
+      } catch (error) {
+        console.warn(`FlowEngine: Failed to load model '${name}'. Falling back to ErrorFlowModel when needed.`, error);
+        return null;
+      } finally {
+        this._loadingModelPromises.delete(name);
+      }
+    })();
+
+    this._loadingModelPromises.set(name, promise);
+    return promise;
+  }
+
+  /**
+   * Ensure multiple model classes are available.
+   * @param {string[]} names Model class names
+   * @returns {Promise<EnsureBatchResult>} Batch ensure result
+   * @private
+   */
+  private async ensureModels(names: string[]): Promise<EnsureBatchResult> {
+    const requested = Array.from(new Set(names.filter((name): name is string => !!name)));
+    const loaded: string[] = [];
+    const failed: EnsureBatchResult['failed'] = [];
+
+    const results = await Promise.all(
+      requested.map(async (name) => {
+        const modelClass = await this.ensureModel(name);
+        return { name, modelClass };
+      }),
+    );
+
+    results.forEach(({ name, modelClass }) => {
+      if (modelClass) {
+        loaded.push(name);
+      } else {
+        failed.push({ name });
+      }
+    });
+
+    return { requested, loaded, failed };
+  }
+
+  /**
+   * Resolve all unresolved string-based model references in a model tree before synchronous creation begins.
+   *
+   * Use this when you already have a model tree object, such as repository-returned data or resolved
+   * `createModelOptions`, and you need to ensure every string `use` in that tree has been loaded and
+   * registered into `_modelClasses` before calling `createModel()`.
+   *
+   * @param {unknown} data Model tree data
+   * @returns {Promise<EnsureBatchResult>} Batch ensure result
+   */
+  public async resolveModelTree(data: unknown): Promise<EnsureBatchResult> {
+    const requested = new Set<string>();
+    const loaded = new Set<string>();
+    const failed = new Map<string, { name: string; error?: unknown }>();
+    const processed = new Set<string>();
+    const pending = new Set<string>();
+
+    this.collectModelNamesFromTree(data, pending);
+
+    while (pending.size > 0) {
+      const batch = Array.from(pending).filter((name) => !processed.has(name));
+      pending.clear();
+      if (batch.length === 0) {
+        break;
+      }
+
+      batch.forEach((name) => requested.add(name));
+      const result = await this.ensureModels(batch);
+
+      result.loaded.forEach((name) => {
+        processed.add(name);
+        loaded.add(name);
+        const modelClass = this.getModelClass(name);
+        if (modelClass) {
+          const discovered = new Set<string>();
+          this.collectModelNamesFromMetaDefaults(modelClass, discovered);
+          discovered.forEach((discoveredName) => {
+            if (!processed.has(discoveredName)) {
+              pending.add(discoveredName);
+            }
+          });
+        }
+      });
+
+      result.failed.forEach((item) => {
+        processed.add(item.name);
+        failed.set(item.name, item);
+      });
+    }
+
+    return {
+      requested: Array.from(requested),
+      loaded: Array.from(loaded),
+      failed: Array.from(failed.values()),
+    };
+  }
+
+  /**
+   * Preload all currently registered unresolved model loaders.
+   *
+   * This method is intended for flow-settings/discovery style entry points that need registered model
+   * classes to exist before UI is rendered, without requiring callers to know which specific models
+   * will be touched next.
+   *
+   * @returns {Promise<EnsureBatchResult>} Batch ensure result
+   */
+  public async preloadModelLoaders(): Promise<EnsureBatchResult> {
+    const unresolved = Array.from(this._modelLoaders.keys()).filter((name) => !this._modelClasses.has(name));
+    if (unresolved.length === 0) {
+      this._modelLoadersPreloaded = true;
+      return { requested: [], loaded: [], failed: [] };
+    }
+    if (this._modelLoadersPreloadPromise) {
+      return this._modelLoadersPreloadPromise;
+    }
+
+    this._modelLoadersPreloadPromise = (async () => {
+      const result = await this.ensureModels(unresolved);
+      this._modelLoadersPreloaded = result.failed.length === 0;
+      this._modelLoadersPreloadPromise = undefined;
+      return result;
+    })();
+
+    return this._modelLoadersPreloadPromise;
+  }
+
   registerResources(resources: Record<string, any>) {
     for (const [name, resourceClass] of Object.entries(resources)) {
       this._resources.set(name, resourceClass);
@@ -489,6 +857,70 @@ export class FlowEngine {
     return result;
   }
 
+  /**
+   * Asynchronously get all subclasses of a base class, including those registered via model loaders.
+   * Merges results from already-loaded classes (_modelClasses) and async loader entries with matching `extends` declarations.
+   * Loader-resolved classes are validated with `isInheritedFrom`; mismatches are warned and excluded.
+   * @param {string | ModelConstructor} baseClass Base class name or constructor
+   * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+   * @returns {Promise<Map<string, ModelConstructor>>} Model classes that are subclasses of the base class
+   */
+  public async getSubclassesOfAsync(
+    baseClass: string | ModelConstructor,
+    filter?: (ModelClass: ModelConstructor, className: string) => boolean,
+  ): Promise<Map<string, ModelConstructor>> {
+    const baseClassName = typeof baseClass === 'string' ? baseClass : baseClass.name;
+
+    // If baseClass is a string and not yet loaded, try to resolve it first
+    let parentModelClass: ModelConstructor | undefined;
+    if (typeof baseClass === 'string') {
+      if (!this.getModelClass(baseClass)) {
+        await this.ensureModel(baseClass);
+      }
+      parentModelClass = this.getModelClass(baseClass);
+    } else {
+      parentModelClass = baseClass;
+    }
+
+    if (!parentModelClass) {
+      return new Map();
+    }
+
+    // Step 1: Collect already-loaded subclasses from _modelClasses
+    const result = this.getSubclassesOf(parentModelClass, filter);
+
+    // Step 2: Find unloaded loaders whose extends includes baseClassName
+    const loaderCandidates: string[] = [];
+    for (const [name, entry] of this._modelLoaders) {
+      if (result.has(name) || this._modelClasses.has(name)) continue;
+      if (entry.extends?.includes(baseClassName)) {
+        loaderCandidates.push(name);
+      }
+    }
+
+    // Step 3: Resolve all matching loaders
+    if (loaderCandidates.length > 0) {
+      await this.ensureModels(loaderCandidates);
+    }
+
+    // Step 4: Validate resolved classes and add to result
+    for (const name of loaderCandidates) {
+      const ModelClass = this._modelClasses.get(name);
+      if (!ModelClass) continue;
+      if (!isInheritedFrom(ModelClass, parentModelClass)) {
+        console.warn(
+          `FlowEngine: Model '${name}' declares extends '${baseClassName}' but does not actually inherit from it. Skipping.`,
+        );
+        continue;
+      }
+      if (!filter || filter(ModelClass, name)) {
+        result.set(name, ModelClass);
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Create and register a model instance.
    * If an instance with the same UID exists, returns the existing instance.
@@ -579,7 +1011,6 @@ export class FlowEngine {
 
     while (current) {
       if (visited.has(current)) {
-        console.warn(`FlowEngine: resolveUse circular reference detected on '${current.name}'.`);
         break;
       }
       visited.add(current);
@@ -698,7 +1129,7 @@ export class FlowEngine {
    */
   public removeModel(uid: string): boolean {
     if (!this._modelInstances.has(uid)) {
-      console.warn(`FlowEngine: Model with UID '${uid}' does not exist.`);
+      this.logger.debug(`FlowEngine: Model with UID '${uid}' does not exist.`);
       return false;
     }
     const modelInstance = this._modelInstances.get(uid) as FlowModel;
@@ -836,10 +1267,10 @@ export class FlowEngine {
    * 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>(
+  private async hydrateModelFromPreviousEngines<T extends FlowModel = FlowModel>(
     options: any,
     extra?: { delegateToParent?: boolean; delegate?: FlowContext },
-  ): T | null {
+  ): Promise<T | null> {
     const uid = options?.uid;
     const parentId = options?.parentId;
     const subKey = options?.subKey;
@@ -853,7 +1284,7 @@ export class FlowEngine {
       }
       if (existing) {
         const data = existing.serialize();
-        return this.createModel<T>(data as any, extra);
+        return this.createModelAsync<T>(data as any, extra);
       }
     }
 
@@ -868,11 +1299,11 @@ export class FlowEngine {
       if (!localParent) {
         const parentData = parentFromPrev.serialize();
         delete (parentData as any).subModels;
-        localParent = this.createModel<FlowModel>(parentData as any, extra);
+        localParent = await this.createModelAsync<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);
+      const localModel = await this.createModelAsync<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];
@@ -913,20 +1344,21 @@ export class FlowEngine {
       if (model) {
         return model as T;
       }
-      const hydrated = this.hydrateModelFromPreviousEngines<T>(options);
+      const hydrated = await this.hydrateModelFromPreviousEngines<T>(options);
       if (hydrated) {
         return hydrated as T;
       }
     }
     const data = await this._modelRepository.findOne(options);
     if (!data?.uid) return null;
+    await this.resolveModelTree(data);
     if (refresh) {
       const existing = this.getModel(data.uid);
       if (existing) {
         this.removeModelWithSubModels(existing.uid);
       }
     }
-    return this.createModel<T>(data as any);
+    return this.createModelAsync<T>(data as any);
   }
 
   /**
@@ -959,6 +1391,7 @@ export class FlowEngine {
   async loadOrCreateModel<T extends FlowModel = FlowModel>(
     options,
     extra?: {
+      skipSave?: boolean;
       delegateToParent?: boolean;
       delegate?: FlowContext;
     },
@@ -973,7 +1406,7 @@ export class FlowEngine {
       return m;
     }
 
-    const hydrated = this.hydrateModelFromPreviousEngines<T>(options, extra);
+    const hydrated = await this.hydrateModelFromPreviousEngines<T>(options, extra);
     if (hydrated) {
       return hydrated;
     }
@@ -981,10 +1414,12 @@ export class FlowEngine {
     const data = await this._modelRepository.findOne(options);
     let model: T | null = null;
     if (data?.uid) {
-      model = this.createModel<T>(data as any, extra);
+      model = await this.createModelAsync<T>(data as any, extra);
     } else {
-      model = this.createModel<T>(options, extra);
-      await model.save();
+      model = await this.createModelAsync<T>(options, extra);
+      if (!extra?.skipSave) {
+        await model.save();
+      }
     }
     if (model.parent) {
       const subModel = model.parent.findSubModel(model.subKey, (m) => {

package/src/flowI18n.ts

@@ -52,7 +52,8 @@ export class FlowI18n {
    */
   private translateKey(key: string, options?: any): string {
     if (this.context?.i18n?.t) {
-      return this.context.i18n.t(key, options);
+      const translated = this.context.i18n.t(key, options);
+      return translated == null || translated === '' ? key : translated;
     }
     // 如果没有翻译函数，返回原始键值
     return key;