generator-mico-cli 0.1.20 → 0.1.21

package/generators/micro-react/templates/apps/layout/src/app.tsx

@@ -1,18 +1,92 @@
-import { history } from '@umijs/max';
+import { history, type RequestConfig } from '@umijs/max';
+import { prefetchApps } from 'qiankun';
+import { errorConfig } from './requestErrorConfig';
 // 解决「React19 中无法使用 Message/Notification」的问题。 @see https://github.com/arco-design/arco-design/issues/2900#issuecomment-2796571653
 import * as arco from '@arco-design/web-react';
 import '@arco-design/web-react/dist/css/arco.css';
 import '@arco-design/web-react/es/_util/react-19-adapter';
 import React from 'react';
-import ReactDOM from 'react-dom';
+import ReactDOM from 'react-dom/client';
 
 import { getAuthInfo } from './common/auth/tool';
-import { ROUTES } from './common/constants';
+import { NO_AUTH_ROUTE_LIST } from './constants';
 import { extractRoutes, getWindowMenus } from './common/menu';
+import {
+  clearMicroAppProps,
+  type IMicroAppProps,
+  setMicroAppProps,
+} from './common/micro';
 import { initTheme } from './common/theme';
 import MicroAppLoader from './components/MicroAppLoader';
 import './global.less';
 
+// ==================== 微应用预加载 ====================
+// 预加载所有微应用资源，避免快速切换时的竞态条件
+// 当资源已预加载时，loadMicroApp 的异步加载会快速完成，减少容器不存在的错误
+
+/**
+ * 是否启用微应用预加载
+ * - 可通过 URL 参数 ?prefetch=false 禁用（方便调试加载时序问题）
+ * - 可通过 localStorage.setItem('DISABLE_MICRO_APP_PREFETCH', 'true') 禁用
+ * - 默认启用
+ */
+const isPrefetchEnabled = (): boolean => {
+  if (typeof window === 'undefined') return false;
+
+  // URL 参数优先级最高
+  const urlParams = new URLSearchParams(window.location.search);
+  const prefetchParam = urlParams.get('prefetch');
+  if (prefetchParam === 'false') {
+    console.log('[App] Prefetch disabled via URL parameter');
+    return false;
+  }
+
+  // localStorage 开关
+  if (localStorage.getItem('DISABLE_MICRO_APP_PREFETCH') === 'true') {
+    console.log('[App] Prefetch disabled via localStorage');
+    return false;
+  }
+
+  return true;
+};
+
+const prefetchMicroApps = () => {
+  if (!isPrefetchEnabled()) {
+    return;
+  }
+
+  try {
+    const menus = getWindowMenus();
+    const routes = extractRoutes(menus);
+
+    // 筛选出所有微应用路由
+    const microApps = routes
+      .filter((route) => route.loadType === 'microapp' && route.entry)
+      .map((route) => ({
+        name: route.path,
+        entry: route.entry!,
+      }));
+
+    if (microApps.length > 0) {
+      console.log('[App] Prefetching micro apps:', microApps);
+      prefetchApps(microApps);
+    }
+  } catch (error) {
+    console.warn('[App] Failed to prefetch micro apps:', error);
+  }
+};
+
+// 在页面加载后预加载微应用
+if (typeof window !== 'undefined') {
+  // 使用 requestIdleCallback 在浏览器空闲时预加载，避免影响首屏渲染
+  if ('requestIdleCallback' in window) {
+    window.requestIdleCallback(() => prefetchMicroApps(), { timeout: 3000 });
+  } else {
+    // 降级方案：延迟 1 秒后预加载
+    setTimeout(prefetchMicroApps, 1000);
+  }
+}
+
 // ==================== 微前端共享依赖 ====================
 // 将公共库暴露到 window，供子应用复用，避免重复打包
 // 子应用通过 externals 配置引用这些全局变量
@@ -30,20 +104,20 @@ initTheme();
  * @see https://umijs.org/docs/api/runtime-config#getinitialstate
  */
 export async function getInitialState(): Promise<{
-  currentUser?: {
-    name: string;
-    avatar: string;
-    userid: string;
-    status: string;
-  };
+  // FIXME: 待修改类型
+  settings?: any;
+  currentUser?: any;
   loading?: boolean;
   fetchUserInfo?: () => Promise<void>;
 }> {
   const fetchUserInfo = async () => {};
-
   // 如果不是登录页面，执行
   const { location } = history;
-  if (!ROUTES.NO_AUTH_ROUTES.includes(location.pathname)) {
+  if (
+    !NO_AUTH_ROUTE_LIST.includes(
+      location.pathname,
+    )
+  ) {
     const authInfo = getAuthInfo();
     const currentUser = {
       name: authInfo.nickname || '未知用户',
@@ -51,7 +125,6 @@ export async function getInitialState(): Promise<{
         authInfo.avatar ||
         'https://gw.alipayobjects.com/zos/antfincdn/XAosXuNZyF/BiazfanxmamNRoxxVxka.png',
       userid: authInfo.uid,
-      status: 'UNKNOWN',
     };
     return {
       fetchUserInfo,
@@ -63,6 +136,17 @@ export async function getInitialState(): Promise<{
   };
 }
 
+/**
+ * @name request 配置，可以配置错误处理
+ * 它基于 axios 和 ahooks 的 useRequest 提供了一套统一的网络请求和错误处理方案。
+ * @doc https://umijs.org/docs/max/request#配置
+ */
+export const request: RequestConfig = {
+  // 在开发环境下使用本地 mock，生产环境使用实际 API
+  baseURL: '',
+  ...errorConfig,
+};
+
 /**
  * Umi 路由类型定义
  */
@@ -84,9 +168,14 @@ export function patchClientRoutes({ routes }: { routes: UmiRoute[] }) {
   const menus = getWindowMenus();
   const dynamicRoutes = extractRoutes(menus);
 
-  // 找到根路由
+  console.log('[app.tsx] patchClientRoutes:', { menus, dynamicRoutes, routes });
+
+  // 找到根路由（全局布局）
   const rootRoute = routes.find((r) => r.path === '/');
-  if (!rootRoute) return;
+  if (!rootRoute) {
+    console.warn('[app.tsx] Root route not found');
+    return;
+  }
 
   // 为每个动态路由添加配置
   dynamicRoutes.forEach((route) => {
@@ -121,3 +210,39 @@ export function patchClientRoutes({ routes }: { routes: UmiRoute[] }) {
     });
   });
 }
+
+/**
+ * @name qiankun 微前端子应用生命周期
+ * @description 当应用作为 qiankun 子应用运行时，这些生命周期会被调用
+ * @doc https://umijs.org/docs/max/micro-frontend#子应用配置
+ */
+export const qiankun = {
+  /** 子应用加载前 */
+  async bootstrap() {
+    console.log('[micro-app] conversation bootstrap');
+  },
+
+  /** 子应用挂载时，接收主应用传递的 props */
+  async mount(props: IMicroAppProps) {
+    console.log('[micro-app] conversation mount, props:', props);
+
+    // 存储主应用传递的 props（认证信息、API 地址、回调函数等）
+    setMicroAppProps(props);
+  },
+
+  /** 子应用卸载时 */
+  async unmount() {
+    console.log('[micro-app] conversation unmount');
+    // 清理存储的 props 数据
+    clearMicroAppProps();
+  },
+
+  /** 子应用更新时（可选） */
+  async update(props: IMicroAppProps) {
+    console.log('[micro-app] conversation update, props:', props);
+    // 更新时重新存储 props
+    if (props) {
+      setMicroAppProps(props);
+    }
+  },
+};

package/generators/micro-react/templates/apps/layout/src/common/auth/type.ts

@@ -4,3 +4,6 @@ export const REFRESH_TOKEN_KEY = 'refresh';
 export const AVATAR = 'avatar';
 export const NICKNAME = 'nickname';
 export const UID = 'uid';
+
+/** 微应用模式下主应用传递的环境标识 */
+export const MICRO_ENV_KEY = 'micro_env';

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

@@ -0,0 +1,365 @@
+/**
+ * 微前端环境检测和 Props 管理工具
+ */
+
+import { setAuthInfo } from '@/common/auth/tool';
+import {
+  MICRO_ENV_KEY,
+} from '@/common/auth/type';
+import { getFromStorage, removeStorage, setStorage } from '@/common/helpers';
+import { useEffect, useState } from 'react';
+import type {
+  IConversationTab,
+  IHostCallbacks,
+  IMicroAppError,
+  IMicroAppProps,
+  IMicroAppState,
+  IRequestHeaders,
+  MicroAppErrorSource,
+} from './types';
+import { EMicroAppErrorStatus } from './types';
+
+// 导出类型
+export { EMicroAppErrorStatus } from './types';
+export type {
+  IConversationTab,
+  IHostCallbacks,
+  IMicroAppError,
+  IMicroAppProps,
+  IMicroAppState,
+  IRequestHeaders,
+  ISharedServices,
+  MicroAppErrorSource,
+} from './types';
+
+declare global {
+  interface Window {
+    /** qiankun 注入的全局变量，表示当前运行在 qiankun 子应用环境中 */
+    __POWERED_BY_QIANKUN__?: boolean;
+  }
+}
+
+// ============================================
+// 环境检测
+// ============================================
+
+/**
+ * 是否为微应用构建模式
+ * 通过 pnpm start:micro 或 pnpm build:micro 构建时为 true
+ *
+ * 注意：process.env.MICRO_APP 在编译时会被 UmiJS define 替换为字面量 true/false
+ */
+export const isMicroBuild = (): boolean => {
+  // 编译时 define 替换，类型断言避免 TS 报错
+  return (process.env.MICRO_APP as unknown) === true;
+};
+
+/**
+ * 是否运行在 qiankun 主应用中（被 qiankun 加载）
+ * 只有被 qiankun 主应用加载时才为 true
+ */
+export const isQiankunEnv = (): boolean => {
+  return window.__POWERED_BY_QIANKUN__ === true;
+};
+
+/**
+ * 是否为微应用模式（构建或运行时）
+ * - 通过微应用配置构建（isMicroBuild）
+ * - 或被 qiankun 主应用加载（isQiankunEnv）
+ */
+export const isMicroApp = (): boolean => {
+  return isMicroBuild() || isQiankunEnv();
+};
+
+/**
+ * 获取微应用运行模式
+ */
+export type MicroAppMode = 'standalone' | 'qiankun' | 'main-app';
+
+export const getMicroAppMode = (): MicroAppMode => {
+  if (isQiankunEnv()) {
+    return 'qiankun'; // 被 qiankun 主应用加载
+  }
+  if (isMicroBuild()) {
+    return 'standalone'; // 微应用独立运行
+  }
+  return 'main-app'; // 主应用模式
+};
+
+// ============================================
+// Props 存储管理
+// ============================================
+
+/** 模块内存状态（存储不可序列化的数据） */
+let microAppState: IMicroAppState = {};
+
+/** 微应用 props 是否已接收（mount 是否已被调用） */
+let microAppPropsReceived = false;
+
+/** 微应用就绪状态变更的监听器集合 */
+const readyListeners = new Set<() => void>();
+
+/**
+ * 订阅微应用就绪状态变更
+ * @returns 取消订阅函数
+ */
+export const subscribeMicroAppReady = (listener: () => void): (() => void) => {
+  readyListeners.add(listener);
+  return () => readyListeners.delete(listener);
+};
+
+/**
+ * 通知所有监听器微应用已就绪
+ */
+const notifyMicroAppReady = (): void => {
+  readyListeners.forEach((listener) => {
+    listener();
+  });
+};
+
+/** 微应用模式下添加到 body 的 class 名称，用于样式区分 */
+export const MICRO_APP_BODY_CLASS = 'micro-app-mode';
+
+/**
+ * 存储主应用传递的 props
+ * - 认证信息存储到 localStorage
+ * - 回调函数等存储到模块内存
+ */
+export const setMicroAppProps = (props: IMicroAppProps): void => {
+  console.log('[micro-app] setMicroAppProps:', props);
+
+  // 标记 props 已接收
+  microAppPropsReceived = true;
+
+  // 给 body 添加微应用标识 class，用于样式区分
+  document.body.classList.add(MICRO_APP_BODY_CLASS);
+
+  // 通知监听器微应用已就绪
+  notifyMicroAppReady();
+
+  // 1. 存储认证信息到 localStorage（复用现有的 setAuthInfo）
+  setAuthInfo({
+    token: props.authToken || '',
+    wsToken: props.wsToken || '',
+    uid: props.uid || '',
+    avatar: props.avatar || '',
+    nickname: props.nickname || '',
+    refreshToken: '', // 主应用模式下不需要 refreshToken
+  });
+
+  // 2. 存储环境标识到 localStorage（用于环境判断）
+  if (props.env) {
+    setStorage(MICRO_ENV_KEY, props.env);
+  }
+
+  // 4. 存储不可序列化的数据到模块内存
+  microAppState = {
+    hostCallbacks: props.appConfig?.props?.fromHost,
+    conversationTabs: props.appConfig?.props?.conversation_tabs,
+    requestHeaders: props.requestHeaders,
+    services: props.services,
+    rawProps: props,
+  };
+
+  // 5. 日志输出自定义请求头配置
+  if (props.requestHeaders && Object.keys(props.requestHeaders).length > 0) {
+    console.log(
+      '[setMicroAppProps] requestHeaders:',
+      Object.keys(props.requestHeaders),
+    );
+  }
+};
+
+/**
+ * 清理存储的 props 数据
+ */
+export const clearMicroAppProps = (): void => {
+  console.log('[micro-app] clearMicroAppProps');
+
+  // 重置 props 接收标记
+  microAppPropsReceived = false;
+
+  // 移除 body 上的微应用标识 class
+  document.body.classList.remove(MICRO_APP_BODY_CLASS);
+
+  // 清理 localStorage 中的微应用特有数据
+  removeStorage(MICRO_ENV_KEY);
+
+  // 清理模块内存状态
+  microAppState = {};
+};
+
+/**
+ * 获取模块内存中的微应用状态
+ */
+export const getMicroAppState = (): IMicroAppState => {
+  return microAppState;
+};
+
+/**
+ * 获取主应用传递的回调函数
+ */
+export const getHostCallbacks = (): IHostCallbacks => {
+  return microAppState.hostCallbacks || {};
+};
+
+/**
+ * 获取会话 Tab 配置
+ */
+export const getConversationTabs = (): IConversationTab[] | undefined => {
+  return microAppState.conversationTabs;
+};
+
+/**
+ * 获取主应用传入的自定义请求头
+ * 用于在 HTTP 请求时自动注入额外的 headers
+ */
+export const getRequestHeaders = (): IRequestHeaders | undefined => {
+  return microAppState.requestHeaders;
+};
+
+/**
+ * 获取主应用共享服务
+ * 子应用可以直接使用这些服务，无需重复初始化
+ */
+export const getSharedServices = (): IMicroAppState['services'] => {
+  return microAppState.services;
+};
+
+/**
+ * 获取存储的环境标识
+ */
+export const getMicroEnv = (): string | null => {
+  return getFromStorage(MICRO_ENV_KEY);
+};
+
+/**
+ * 微应用是否已初始化完成（props 已接收）
+ * 用于判断是否应该跳过某些请求
+ *
+ * - 非微应用模式：始终返回 true（无需等待初始化）
+ * - 微应用模式：返回 props 是否已接收
+ */
+export const isMicroAppReady = (): boolean => {
+  // 非微应用模式，无需等待初始化
+  if (!isMicroApp()) {
+    return true;
+  }
+  // 微应用模式，检查 props 是否已接收
+  return microAppPropsReceived;
+};
+
+// ============================================
+// React Hooks
+// ============================================
+
+/**
+ * React Hook: 订阅微应用就绪状态
+ * 当微应用 props 接收后会触发组件重新渲染
+ *
+ * @returns 微应用是否已就绪
+ */
+export const useMicroAppReady = (): boolean => {
+  const initialReady = isMicroAppReady();
+  console.log(
+    '[useMicroAppReady] initial check:',
+    'isMicroApp=',
+    isMicroApp(),
+    'propsReceived=',
+    microAppPropsReceived,
+    'ready=',
+    initialReady,
+  );
+
+  const [ready, setReady] = useState(initialReady);
+
+  useEffect(() => {
+    // 如果已就绪，无需订阅
+    if (ready) {
+      return;
+    }
+
+    console.log('[useMicroAppReady] subscribing to ready state changes');
+    // 订阅就绪状态变更
+    const unsubscribe = subscribeMicroAppReady(() => {
+      const newReady = isMicroAppReady();
+      console.log('[useMicroAppReady] ready state changed:', newReady);
+      setReady(newReady);
+    });
+
+    return unsubscribe;
+  }, [ready]);
+
+  return ready;
+};
+
+// ============================================
+// 错误通知
+// ============================================
+
+/**
+ * 通知主应用发生错误
+ * 仅在微应用模式下且主应用提供了 onError 回调时才会调用
+ *
+ * @param error 错误信息
+ * @returns 是否成功通知（false 表示非微应用模式或主应用未提供回调）
+ */
+export const notifyHostError = (error: IMicroAppError): boolean => {
+  // 非微应用模式，不通知
+  if (!isMicroApp()) {
+    return false;
+  }
+
+  const callbacks = getHostCallbacks();
+  if (!callbacks.onError) {
+    return false;
+  }
+
+  // 先打印日志，再调用回调（避免回调抛错导致日志丢失）
+  console.log('[micro-app] notifyHostError:', error);
+
+  try {
+    callbacks.onError(error);
+    return true;
+  } catch (err) {
+    console.error('[micro-app] onError callback failed:', err);
+    return false;
+  }
+};
+
+/**
+ * 创建鉴权失败错误
+ * @param message 错误消息
+ * @param code 原始错误码
+ * @param source 错误来源
+ */
+export const createAuthError = (
+  message: string,
+  code?: number | string,
+  source?: MicroAppErrorSource,
+): IMicroAppError => ({
+  status: EMicroAppErrorStatus.AUTH_FAILURE,
+  message,
+  source,
+  code,
+});
+
+/**
+ * 创建业务错误
+ * @param message 错误消息
+ * @param code 原始错误码
+ * @param source 错误来源
+ * @param details 额外详情
+ */
+export const createBusinessError = (
+  message: string,
+  code?: number | string,
+  source?: MicroAppErrorSource,
+  details?: Record<string, unknown>,
+): IMicroAppError => ({
+  status: EMicroAppErrorStatus.BUSINESS_ERROR,
+  message,
+  source,
+  code,
+  details,
+});

package/generators/micro-react/templates/apps/layout/src/common/micro/types.ts

@@ -0,0 +1,184 @@
+/**
+ * 微前端 Props 类型定义
+ * 主应用通过 qiankun 传递给子应用的配置数据
+ */
+
+/**
+ * 微应用错误状态码
+ * - 1: 鉴权失败（token 无效/过期），需要主应用重新获取 token
+ * - 2: 业务错误（参数错误、逻辑拒绝、网络超时、权限不足等）
+ */
+export enum EMicroAppErrorStatus {
+  /** 鉴权失败，需重获 token */
+  AUTH_FAILURE = 1,
+  /** 业务错误 */
+  BUSINESS_ERROR = 2,
+}
+
+/**
+ * 错误来源
+ */
+export type MicroAppErrorSource = 'websocket' | 'http';
+
+/**
+ * 微应用错误信息
+ * 用于通知主应用子应用内部发生的错误
+ */
+export interface IMicroAppError {
+  /** 错误状态码 */
+  status: EMicroAppErrorStatus;
+  /** 错误消息 */
+  message: string;
+  /** 错误来源 */
+  source?: MicroAppErrorSource;
+  /** 原始错误码（如 HTTP 状态码、WebSocket 错误码等） */
+  code?: number | string;
+  /** 额外的错误详情 */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * 主应用回调函数
+ */
+export interface IHostCallbacks {
+  /** 点击会话时的回调 */
+  onClickConversation?: (conversation: unknown) => void;
+  /** 子应用内部错误回调，用于通知主应用进行统一处理 */
+  onError?: (error: IMicroAppError) => void;
+  /** 其他回调可按需扩展 */
+  [key: string]: ((...args: any[]) => void) | undefined;
+}
+
+/**
+ * 会话 Tab 配置
+ */
+export interface IConversationTab {
+  /** Tab 唯一标识，同时用于关联接口的 status 参数 */
+  key: string;
+  /** Tab 显示标题 */
+  title: string;
+  /** 是否显示数量 */
+  showCount?: boolean;
+}
+
+/**
+ * 子应用配置
+ */
+export interface IAppConfig {
+  /** 子应用名称 */
+  name: string;
+  /** 子应用自定义配置 */
+  props?: {
+    /** 主应用回调函数 */
+    fromHost?: IHostCallbacks;
+    /** 会话 Tab 配置 */
+    conversation_tabs?: IConversationTab[];
+    /** 其他配置可按需扩展 */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * API 端点配置
+ * 主应用可以传入自定义的 API 端点路径
+ */
+export interface IApiEndpoints {
+  /** OSS 文件上传签名 URL */
+  ossSignUrl?: string;
+}
+
+/**
+ * 主应用共享服务
+ * 包含请求服务和 WebSocket 服务
+ */
+export interface ISharedServices {
+  /** HTTP 请求服务 */
+  request: {
+    request: <T = any>(
+      url: string,
+      options?: Record<string, any>,
+    ) => Promise<T>;
+  };
+
+  /** WebSocket 服务 */
+  websocket: Record<string, (...args: any[]) => any>;
+}
+
+/**
+ * 自定义请求头配置
+ * 主应用可以传入额外的请求头，会在每次 HTTP 请求时自动注入
+ */
+export type IRequestHeaders = Record<string, string>;
+
+/**
+ * 主应用传递给微应用的 Props
+ */
+export interface IMicroAppProps {
+  /** 子应用路由基础路径 */
+  base?: string;
+  /** 环境标识（testing/production） */
+  env?: string;
+  /** 业务类型（crm/cs），决定布局配置 */
+  businessType?: string;
+  /** HTTP 请求的鉴权 token */
+  authToken?: string;
+  /** CDN 文件的前缀 host */
+  filehost?: string;
+  /** WebSocket 建立连接的 Authorization */
+  wsToken?: string;
+  /** 用户头像 URL */
+  avatar?: string;
+  /** 当前客服 ID */
+  uid?: string;
+  /** 当前客服昵称 */
+  nickname?: string;
+  /**
+   * API 基础 URL
+   * @example 'https://dashboard-api-test.micoplatform.com'
+   */
+  apiBaseUrl?: string;
+  /**
+   * API 代理路径前缀
+   * @example '/proxy/mibot_svr'
+   */
+  proxyPath?: string;
+  /**
+   * 自定义 API 端点路径
+   * 如果 CRM 使用不同的端点路径，可通过此字段配置
+   */
+  apiEndpoints?: IApiEndpoints;
+  /**
+   * 自定义请求头
+   * 主应用传入的额外请求头，会在每次 HTTP 请求时自动注入
+   * @example { 'X-Custom-Header': 'value', 'X-Tenant-Id': '123' }
+   */
+  requestHeaders?: IRequestHeaders;
+  /** 子应用配置 */
+  appConfig?: IAppConfig;
+  /** qiankun 注入的容器元素 */
+  container?: HTMLElement;
+  /**
+   * 主应用共享服务
+   * 包含 HTTP 请求服务和 WebSocket 服务
+   * 子应用可以直接使用这些服务，无需重复初始化
+   */
+  services?: ISharedServices;
+  /** 其他扩展字段 */
+  [key: string]: unknown;
+}
+
+/**
+ * 存储在内存中的子应用配置（不可序列化的部分）
+ */
+export interface IMicroAppState {
+  /** 主应用回调函数 */
+  hostCallbacks?: IHostCallbacks;
+  /** 会话 Tab 配置 */
+  conversationTabs?: IConversationTab[];
+  /** 主应用传入的自定义请求头 */
+  requestHeaders?: IRequestHeaders;
+  /** 主应用共享服务 */
+  services?: ISharedServices;
+  /** 原始 props（用于调试） */
+  rawProps?: IMicroAppProps;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generator-mico-cli",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Yeoman generator for Mico CLI projects",
   "keywords": [
     "yeoman-generator",