generator-mico-cli 0.2.2 → 0.2.5

package/generators/micro-react/templates/apps/layout/src/components/MicroAppLoader/micro-app-manager.ts

@@ -0,0 +1,511 @@
+/**
+ * 微应用管理器 v10
+ *
+ * 核心设计：
+ * 1. 稳定容器：容器在 body 中创建，不受 React 生命周期影响
+ * 2. 容器移动：激活时移到目标元素内，停用时移回 body 隐藏
+ * 3. 实例缓存：每个 entry 只 loadMicroApp 一次，复用实例
+ * 4. 自动路由守卫：由 route-guard.ts 自动检测用户意图，无需手动标记
+ *
+ * v10 改进（相比 v9）：
+ * - 移除手动 setUserIntent 机制，改为自动检测用户交互
+ * - 业务代码无需感知路由守卫，可使用任意常规路由跳转方式
+ * - 路由守卫逻辑抽离到独立模块 route-guard.ts
+ */
+
+import type { MicroApp } from 'qiankun';
+import { loadMicroApp } from 'qiankun';
+import { microAppLogger } from '@/common/logger';
+// 导入路由守卫（会自动初始化）
+import { refreshUserIntent, setUserIntent } from '@/common/route-guard';
+
+// 导入低优先级预加载函数
+import { markAppAsPrefetched, prefetchMicroAppsLowPriority } from '@/common/micro-prefetch';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+export interface MicroAppConfig {
+  name: string;
+  entry: string;
+  /** 目标挂载位置（用于移动容器） */
+  target: HTMLElement;
+  props: Record<string, unknown>;
+}
+
+export interface MicroAppState {
+  loading: boolean;
+  error: string | null;
+  mounted: boolean;
+}
+
+type StateChangeCallback = (state: MicroAppState) => void;
+
+type ManagerState = 'idle' | 'loading' | 'mounted';
+
+interface AppInstance {
+  microApp: MicroApp;
+  container: HTMLElement;
+  entry: string;
+  /** qiankun 实例名称（可能与缓存 key 不同，用于避免重复加载问题） */
+  qiankunName: string;
+}
+
+// ============================================================================
+// 常量
+// ============================================================================
+
+const LOAD_TIMEOUT = 30000;
+const MOUNT_TIMEOUT = 30000;
+const UNMOUNT_TIMEOUT = 10000;
+
+const CSS_CLASS = {
+  base: 'micro-app-stable-container',
+  hidden: 'micro-app-stable-container--hidden',
+  active: 'micro-app-stable-container--active',
+} as const;
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+
+function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  message: string,
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => {
+      setTimeout(() => reject(new Error(message)), ms);
+    }),
+  ]);
+}
+
+function createStableContainer(appName: string): HTMLElement {
+  const container = document.createElement('div');
+  container.id = `micro-app-stable-${appName}`;
+  container.className = `${CSS_CLASS.base} ${CSS_CLASS.hidden}`;
+  container.style.cssText = 'display: none; position: absolute; left: -9999px;';
+  document.body.appendChild(container);
+  return container;
+}
+
+function activateContainer(container: HTMLElement, target: HTMLElement): void {
+  target.appendChild(container);
+  container.classList.remove(CSS_CLASS.hidden);
+  container.classList.add(CSS_CLASS.active);
+  container.style.cssText = 'display: block; width: 100%; height: 100%;';
+}
+
+function deactivateContainer(container: HTMLElement): void {
+  document.body.appendChild(container);
+  container.classList.remove(CSS_CLASS.active);
+  container.classList.add(CSS_CLASS.hidden);
+  container.style.cssText = 'display: none; position: absolute; left: -9999px;';
+}
+
+// ============================================================================
+// MicroAppManager 类
+// ============================================================================
+
+class MicroAppManager {
+  private static instance: MicroAppManager;
+
+  /** 当前状态 */
+  private state: ManagerState = 'idle';
+
+  /** 已加载的应用实例缓存 */
+  private appCache = new Map<string, AppInstance>();
+
+  /** 当前激活的应用名称 */
+  private currentAppName: string | null = null;
+
+  /** 待处理的请求 */
+  private pendingRequest: MicroAppConfig | null = null;
+
+  /** 状态变化回调 */
+  private stateCallback: StateChangeCallback | null = null;
+
+  /** 操作序列号（用于检测过期操作） */
+  private operationSeq = 0;
+
+  private constructor() {
+    // 路由守卫已在 route-guard.ts 中自动初始化
+    microAppLogger.log('MicroAppManager initialized');
+  }
+
+  static getInstance(): MicroAppManager {
+    if (!MicroAppManager.instance) {
+      MicroAppManager.instance = new MicroAppManager();
+    }
+    return MicroAppManager.instance;
+  }
+
+  // ==========================================================================
+  // 公开 API
+  // ==========================================================================
+
+  setStateCallback(callback: StateChangeCallback | null): void {
+    console.log('🔍[路由调试] setStateCallback', { hasCallback: !!callback });
+    this.stateCallback = callback;
+  }
+
+  /**
+   * 切换到指定的微应用
+   */
+  switchTo(config: MicroAppConfig): void {
+    microAppLogger.log('switchTo:', config.name, {
+      current: this.currentAppName,
+      state: this.state,
+    });
+
+    // 设置/刷新路由意图，确保在整个加载过程中拦截子应用的非预期路由操作
+    // 使用当前 URL pathname 作为意图路径
+    setUserIntent(window.location.pathname);
+
+    // 如果是当前已激活的应用，只更新 props
+    if (this.state === 'mounted' && this.currentAppName === config.name) {
+      microAppLogger.log('Already mounted, updating props only');
+      const cached = this.appCache.get(config.name);
+      if (cached && cached.microApp.getStatus() === 'MOUNTED') {
+        cached.microApp.update?.(config.props);
+        if (cached.container.parentElement !== config.target) {
+          activateContainer(cached.container, config.target);
+        }
+        // 通知组件当前状态（重要：组件可能在 cleanup 后重新挂载，需要同步状态）
+        this.updateState({ loading: false, error: null, mounted: true });
+      }
+      return;
+    }
+
+    // 保存请求
+    this.pendingRequest = config;
+
+    // 根据状态处理
+    if (this.state === 'idle') {
+      this.processRequest();
+    } else if (this.state === 'mounted') {
+      this.updateState({ loading: true, error: null, mounted: false });
+      this.deactivateCurrentAndProcess();
+    } else {
+      // loading 状态，等待完成后处理
+      microAppLogger.log('Busy, request queued');
+      this.updateState({ loading: true, error: null, mounted: false });
+    }
+  }
+
+  updateProps(props: Record<string, unknown>): void {
+    if (this.currentAppName && this.state === 'mounted') {
+      const cached = this.appCache.get(this.currentAppName);
+      if (cached && cached.microApp.getStatus() === 'MOUNTED') {
+        cached.microApp.update?.(props);
+      }
+    }
+  }
+
+  cancel(): void {
+    microAppLogger.log('cancel');
+    this.pendingRequest = null;
+  }
+
+  async clearCache(): Promise<void> {
+    microAppLogger.log('Clearing cache');
+    for (const [name, instance] of this.appCache) {
+      try {
+        await this.safeUnmount(instance.microApp);
+        instance.container.remove();
+      } catch (err) {
+        microAppLogger.warn('Clear cache error for', name, err);
+      }
+    }
+    this.appCache.clear();
+    this.currentAppName = null;
+    this.state = 'idle';
+  }
+
+  getDebugInfo(): object {
+    return {
+      state: this.state,
+      currentAppName: this.currentAppName,
+      pendingRequest: this.pendingRequest?.name ?? null,
+      cacheSize: this.appCache.size,
+      cachedApps: Array.from(this.appCache.entries()).map(([name, inst]) => ({
+        name,
+        qiankunName: inst.qiankunName,
+        entry: inst.entry,
+        status: inst.microApp.getStatus(),
+      })),
+    };
+  }
+
+  // ==========================================================================
+  // 私有方法
+  // ==========================================================================
+
+  private updateState(state: MicroAppState): void {
+    console.log('🔍[路由调试] updateState', { state, hasCallback: !!this.stateCallback });
+    this.stateCallback?.(state);
+  }
+
+  private shouldAbort(currentName: string, mySeq: number): boolean {
+    if (mySeq !== this.operationSeq) {
+      return true;
+    }
+    if (this.pendingRequest && this.pendingRequest.name !== currentName) {
+      return true;
+    }
+    return false;
+  }
+
+  private async processRequest(): Promise<void> {
+    const request = this.pendingRequest;
+    this.pendingRequest = null;
+
+    if (!request) {
+      microAppLogger.log('No pending request');
+      return;
+    }
+
+    const mySeq = ++this.operationSeq;
+    console.log('🔍[路由调试] processRequest 开始', { name: request.name, seq: mySeq });
+
+    // 刷新意图，确保在整个加载过程中意图保持有效
+    refreshUserIntent();
+
+    this.state = 'loading';
+    this.updateState({ loading: true, error: null, mounted: false });
+
+    try {
+
+      if (this.shouldAbort(request.name, mySeq)) {
+        console.log('🔍[路由调试] ⚠️ Aborted before load', { name: request.name, mySeq, operationSeq: this.operationSeq });
+        this.state = 'idle';
+        if (this.pendingRequest) this.processRequest();
+        return;
+      }
+
+      let appInstance = this.appCache.get(request.name);
+
+      if (appInstance) {
+        // 复用已有实例
+        console.log('🔍[路由调试] 复用缓存实例', { name: request.name, status: appInstance.microApp.getStatus() });
+
+        // 刷新意图
+        refreshUserIntent();
+
+        if (this.shouldAbort(request.name, mySeq)) {
+          console.log('🔍[路由调试] ⚠️ Aborted (cached) before activate', { name: request.name });
+          this.state = 'idle';
+          if (this.pendingRequest) this.processRequest();
+          return;
+        }
+
+        activateContainer(appInstance.container, request.target);
+
+        const status = appInstance.microApp.getStatus();
+        console.log('🔍[路由调试] 缓存实例状态', { name: request.name, qiankunName: appInstance.qiankunName, status });
+
+        // 根据状态决定如何挂载
+        if (status === 'BOOTSTRAPPING') {
+          // 实例在 loadPromise 后被缓存，但还未完成 mount
+          // 需要等待 mountPromise 完成
+          console.log('🔍[路由调试] 等待缓存实例 mountPromise...', { name: request.name });
+          await withTimeout(appInstance.microApp.mountPromise, MOUNT_TIMEOUT, '子应用挂载超时');
+          console.log('🔍[路由调试] 缓存实例 mountPromise 完成', { name: request.name, status: appInstance.microApp.getStatus() });
+          // 重要：mount 完成后立即更新 props，确保子应用使用最新的 routePath
+          // qiankun 的 mount() 使用的是创建实例时的原始 props，可能包含过期的 routePath
+          appInstance.microApp.update?.(request.props);
+          console.log('🔍[路由调试] 缓存实例 props 已更新（BOOTSTRAPPING 后）', { name: request.name });
+        } else if (status === 'NOT_MOUNTED') {
+          // 实例之前被 unmount 过，需要重新 mount
+          console.log('🔍[路由调试] 开始 mount 缓存实例', { name: request.name });
+          await withTimeout(appInstance.microApp.mount(), MOUNT_TIMEOUT, '子应用挂载超时');
+          console.log('🔍[路由调试] 缓存实例 mount 完成', { name: request.name, status: appInstance.microApp.getStatus() });
+          // 重要：mount 完成后立即更新 props，确保子应用使用最新的 routePath
+          // qiankun 的 mount() 使用的是创建实例时的原始 props，可能包含过期的 routePath
+          appInstance.microApp.update?.(request.props);
+          console.log('🔍[路由调试] 缓存实例 props 已更新（NOT_MOUNTED 后）', { name: request.name });
+        }
+        // 如果 status === 'MOUNTED'，则无需操作（已在 switchTo 入口处处理）
+
+        // 刷新意图，保护 mount 成功后的短暂窗口期
+        refreshUserIntent();
+
+        if (this.shouldAbort(request.name, mySeq)) {
+          console.log('🔍[路由调试] ⚠️ Aborted (cached) after mount', { name: request.name });
+          await this.safeUnmount(appInstance.microApp);
+          deactivateContainer(appInstance.container);
+          this.state = 'idle';
+          if (this.pendingRequest) this.processRequest();
+          return;
+        }
+
+        this.currentAppName = request.name;
+        this.state = 'mounted';
+        // 不立即清除意图，让它自然过期（5秒）
+        // 这样可以防止被 abort 的子应用在后台执行时修改路由
+        console.log('🔍[路由调试] ✅ 缓存实例挂载成功', { name: request.name, qiankunName: appInstance.qiankunName, status: appInstance.microApp.getStatus() });
+        this.updateState({ loading: false, error: null, mounted: true });
+
+        // 挂载成功后，标记当前应用已加载，并触发其他应用的低优先级预加载
+        markAppAsPrefetched(request.entry);
+        prefetchMicroAppsLowPriority(request.entry);
+
+      } else {
+        // 创建新实例
+        // 使用唯一的 qiankun 实例名称，避免 qiankun 内部状态冲突
+        // 当应用被 abort 后重新加载时，qiankun 可能仍保留旧的内部状态
+        // 使用时间戳后缀确保每次 loadMicroApp 都是全新的实例
+        const qiankunName = `${request.name}__${Date.now()}`;
+        console.log('🔍[路由调试] 创建新实例', { name: request.name, qiankunName });
+
+        if (this.shouldAbort(request.name, mySeq)) {
+          this.state = 'idle';
+          if (this.pendingRequest) this.processRequest();
+          return;
+        }
+
+        const container = createStableContainer(qiankunName);
+        activateContainer(container, request.target);
+
+        console.log('🔍[路由调试] 调用 loadMicroApp', { name: request.name, qiankunName, entry: request.entry });
+        const microApp = loadMicroApp(
+          {
+            name: qiankunName,
+            entry: request.entry,
+            container,
+            props: request.props,
+          },
+          {
+            sandbox: { strictStyleIsolation: false, experimentalStyleIsolation: true },
+          },
+        );
+
+        console.log('🔍[路由调试] 等待 loadPromise...', { name: request.name });
+        await withTimeout(microApp.loadPromise, LOAD_TIMEOUT, '子应用资源加载超时');
+        console.log('🔍[路由调试] loadPromise 完成', { name: request.name, status: microApp.getStatus() });
+
+        // 刷新意图，继续保护后续操作
+        refreshUserIntent();
+
+        // loadPromise 完成后立即缓存实例
+        // 即使后续被 abort，下次也能复用此实例，避免创建多个实例导致重复请求
+        appInstance = { microApp, container, entry: request.entry, qiankunName };
+        this.appCache.set(request.name, appInstance);
+        console.log('🔍[路由调试] 实例已缓存（loadPromise 后）', { name: request.name, qiankunName });
+
+        if (this.shouldAbort(request.name, mySeq)) {
+          console.log('🔍[路由调试] ⚠️ Aborted after loadPromise', { name: request.name, mySeq, operationSeq: this.operationSeq });
+          // 不销毁实例，只是 deactivate 容器，实例保留在缓存中供下次复用
+          deactivateContainer(container);
+          this.state = 'idle';
+          if (this.pendingRequest) this.processRequest();
+          return;
+        }
+
+        console.log('🔍[路由调试] 等待 mountPromise...', { name: request.name, qiankunName, status: microApp.getStatus() });
+        await withTimeout(microApp.mountPromise, MOUNT_TIMEOUT, '子应用挂载超时');
+        console.log('🔍[路由调试] mountPromise 完成', { name: request.name, qiankunName, status: microApp.getStatus() });
+
+        // 重要：mount 完成后调用 update，触发子应用的路由同步
+        // 由于子应用 mount 生命周期不再调用 syncRoute，需要通过 update 来同步路由
+        microApp.update?.(request.props);
+        console.log('🔍[路由调试] 新实例 props 已更新', { name: request.name });
+
+        // 刷新意图，保护 mount 成功后的短暂窗口期
+        refreshUserIntent();
+
+        if (this.shouldAbort(request.name, mySeq)) {
+          console.log('🔍[路由调试] ⚠️ Aborted after mountPromise', { name: request.name, mySeq, operationSeq: this.operationSeq });
+          // 实例已在 loadPromise 后缓存，这里只需 unmount 和 deactivate
+          await this.safeUnmount(microApp);
+          deactivateContainer(container);
+          this.state = 'idle';
+          if (this.pendingRequest) this.processRequest();
+          return;
+        }
+
+        // 实例已在 loadPromise 后缓存，这里不需要重复缓存
+
+        this.currentAppName = request.name;
+        this.state = 'mounted';
+        // 不立即清除意图，让它自然过期（5秒）
+        // 这样可以防止被 abort 的子应用在后台执行时修改路由
+        console.log('🔍[路由调试] ✅ 新实例挂载成功', { name: request.name, qiankunName, status: microApp.getStatus() });
+        this.updateState({ loading: false, error: null, mounted: true });
+
+        // 挂载成功后，标记当前应用已加载，并触发其他应用的低优先级预加载
+        markAppAsPrefetched(request.entry);
+        prefetchMicroAppsLowPriority(request.entry);
+      }
+
+      if (this.pendingRequest) {
+        this.deactivateCurrentAndProcess();
+      }
+
+    } catch (err) {
+      microAppLogger.error('Error:', err);
+
+      if (mySeq !== this.operationSeq) return;
+
+      this.state = 'idle';
+      this.currentAppName = null;
+
+      if (this.pendingRequest) {
+        this.processRequest();
+      } else {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        this.updateState({
+          loading: false,
+          error: message.includes('Failed to fetch')
+            ? '无法连接到子应用服务，请检查子应用是否已启动'
+            : message,
+          mounted: false,
+        });
+      }
+    }
+  }
+
+  private async deactivateCurrentAndProcess(): Promise<void> {
+    if (!this.currentAppName) {
+      this.state = 'idle';
+      this.processRequest();
+      return;
+    }
+
+    const appInstance = this.appCache.get(this.currentAppName);
+    microAppLogger.log('Deactivating:', this.currentAppName);
+
+    if (appInstance) {
+      try {
+        await this.safeUnmount(appInstance.microApp);
+        deactivateContainer(appInstance.container);
+      } catch (err) {
+        microAppLogger.warn('Deactivate error:', err);
+      }
+    }
+
+    this.currentAppName = null;
+    this.state = 'idle';
+    this.processRequest();
+  }
+
+  private async safeUnmount(microApp: MicroApp): Promise<void> {
+    try {
+      if (microApp.getStatus() === 'MOUNTED') {
+        await withTimeout(microApp.unmount(), UNMOUNT_TIMEOUT, 'Unmount timeout');
+      }
+    } catch (err) {
+      microAppLogger.warn('safeUnmount error:', err);
+    }
+  }
+}
+
+export const microAppManager = MicroAppManager.getInstance();
+
+// 暴露到 window 供调试
+if (typeof window !== 'undefined') {
+  (window as unknown as Record<string, unknown>).__MICRO_APP_MANAGER__ = microAppManager;
+}

package/generators/micro-react/templates/apps/layout/src/constants/index.ts

@@ -1,15 +1,74 @@
-export const DEFAULT_NAME = 'Umi Max';
+/**
+ * 应用常量定义
+ */
 
 /**
- * 无需认证的路由路径
+ * 路由路径常量
  */
-export const NO_AUTH_ROUTES = {
+export const ROUTES = {
+  /** 登录页 */
   LOGIN: '/user/login',
+  /** 注册页 */
+  REGISTER: '/user/register',
+  /** 注册结果页 */
+  REGISTER_RESULT: '/user/register-result',
+  /** 403 无权限页 */
   FORBIDDEN: '/403',
+  /** 404 未找到页 */
   NOT_FOUND: '/404',
 } as const;
 
 /**
  * 无需认证的路由列表
  */
-export const NO_AUTH_ROUTE_LIST = Object.values(NO_AUTH_ROUTES);
+export const NO_AUTH_ROUTE_LIST: string[] = [
+  ROUTES.LOGIN,
+  ROUTES.REGISTER,
+  ROUTES.REGISTER_RESULT,
+  ROUTES.FORBIDDEN,
+  ROUTES.NOT_FOUND,
+];
+
+/**
+ * 主题相关常量
+ */
+export const THEME = {
+  /** localStorage 存储键 */
+  STORAGE_KEY: 'audit-center-theme',
+  /** 默认主题 */
+  DEFAULT: 'light' as const,
+  /** 可选主题值 */
+  VALUES: ['light', 'dark'] as const,
+} as const;
+
+/**
+ * 时区相关常量
+ */
+export const TIMEZONE = {
+  /** localStorage 存储键（IANA 时区，如 Asia/Shanghai） */
+  STORAGE_KEY: 'audit-center-timezone',
+  /** localStorage 存储键（用于展示的地区/名称，可选） */
+  REGION_STORAGE_KEY: 'audit-center-timezone-region',
+} as const;
+
+/**
+ * 在线状态相关常量
+ */
+export const PRESENCE = {
+  /** localStorage 存储键 */
+  STORAGE_KEY: 'audit-center-presence-status',
+} as const;
+
+/**
+ * 存储键常量
+ */
+export const STORAGE_KEYS = {
+  APP_INFO: 'appInfo',
+  IS_SUPERUSER: 'is_superuser',
+  GROUPS: 'groups',
+} as const;
+
+/**
+ * OSS 上传目录分类
+ */
+export type TDirCategory = number;

package/generators/micro-react/templates/apps/layout/src/hooks/useRoutePermissionRefresh.ts

@@ -1,6 +1,5 @@
 import { useLocation, useModel } from '@umijs/max';
-import debounce from 'lodash-es/debounce';
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { layoutLogger } from '@/common/logger';
 import { NO_AUTH_ROUTE_LIST } from '@/constants';
 
@@ -21,49 +20,53 @@ export function useRoutePermissionRefresh() {
 
   const isFirstRender = useRef(true);
   const prevPathRef = useRef(location.pathname);
-  // 使用 ref 持久化 refresh，避免 debounce 实例重建
   const refreshRef = useRef(refresh);
+  const timerRef = useRef<ReturnType<typeof setTimeout>>();
   refreshRef.current = refresh;
 
-  const debouncedRefresh = useMemo(
-    () =>
-      debounce(async (pathname: string) => {
-        layoutLogger.log('Route changed, refreshing user info:', pathname);
-        try {
-          await refreshRef.current?.();
-        } finally {
-          setIsRefreshing(false);
-        }
-      }, 300),
-    [],
-  );
-
   useEffect(() => {
-    // 跳过首次渲染（getInitialState 已经获取过用户信息）
+    // 跳过首次渲染
     if (isFirstRender.current) {
       isFirstRender.current = false;
       return;
     }
 
-    // 只有路径真正变化时才刷新（避免 search/hash 变化触发）
+    // 路径未变化
     if (prevPathRef.current === location.pathname) {
       return;
     }
+
     prevPathRef.current = location.pathname;
 
-    // 免认证路由不需要刷新用户信息
+    // 免认证路由不需要刷新
     if (NO_AUTH_ROUTE_LIST.includes(location.pathname)) {
       return;
     }
 
-    // 立即设置 loading 状态，阻止页面渲染和业务请求
+    // 清除之前的定时器
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+    }
+
     setIsRefreshing(true);
-    debouncedRefresh(location.pathname);
+    layoutLogger.log('Route changed, scheduling user info refresh:', location.pathname);
+
+    // 防抖 300ms
+    timerRef.current = setTimeout(async () => {
+      try {
+        await refreshRef.current?.();
+        layoutLogger.log('User info refreshed');
+      } finally {
+        setIsRefreshing(false);
+      }
+    }, 300);
 
     return () => {
-      debouncedRefresh.cancel();
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
     };
-  }, [location.pathname, debouncedRefresh]);
+  }, [location.pathname]);
 
   return { isRefreshing };
 }