generator-mico-cli 0.2.1 → 0.2.2-8.beta.1

package/generators/micro-react/templates/apps/layout/docs/feat-/346/236/204/345/273/272define/344/270/216/345/205/215/350/256/244/350/257/201/345/210/235/345/247/213/346/200/201.md

@@ -0,0 +1,44 @@
+# 构建 define 精简与免认证页初始态
+
+> 创建时间：2026-03-24
+
+## 功能概述
+
+1. **Umi `define`**：不再通过构建期注入 `process.env.EXTERNAL_LOGIN_PATH`（本模板从未注入 `APP_ID`）；SSO 外跳等依赖运行时 `window.__MICO_CONFIG__`。
+2. **`getInitialState`**：免认证路由下即使本地仍有 token，也不请求用户信息接口，减少无效调用。
+
+## 技术方案
+
+### 开发环境
+
+`config/config.dev.ts` 的 `headScripts` 中 `window.__MICO_CONFIG__` 增加 **`externalLoginPath`**（模板默认为占位 URL，生成项目后请按实际 IdP 修改）。
+
+`define` 仅保留 `NODE_ENV`、`API_BASE_URL`、`LOGIN_ENDPOINT`、`REFRESH_ENDPOINT`。
+
+### 生产 / 测试构建
+
+`config.prod.ts`、`config.prod.development.ts`、`config.prod.testing.ts` 的 `define` 中同样**不包含** `EXTERNAL_LOGIN_PATH`，由部署时注入的 `__MICO_CONFIG__.externalLoginPath`（或 `__MICO_WORKSPACE__.casServerLoginUrl`）提供。
+
+### 初始态
+
+`src/app.tsx` 中仅在 `getStoredAuthToken() && !skipAuth` 时调用 `fetchUserInfoFn()`；`skipAuth = isNoAuthRoute || isPageAuthFree`。
+
+## 文件清单
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `config/config.dev.ts` | `__MICO_CONFIG__.externalLoginPath`；移除 `EXTERNAL_LOGIN_PATH` define |
+| `config/config.prod.ts` | 移除 `EXTERNAL_LOGIN_PATH` define |
+| `config/config.prod.development.ts` | 同上 |
+| `config/config.prod.testing.ts` | 同上 |
+| `src/app.tsx` | `fetchUserInfo` 条件增加 `!skipAuth` |
+
+## 部署注意
+
+- 生产 HTML 或网关需保证 `window.__MICO_CONFIG__` 含 **`appId`**、**`externalLoginPath`**（或与现有网关字段对齐），否则代理前缀、SSO 外跳可能异常。
+- 详见 `src/common/request/config.ts` 中 `buildDefaultClientOptions` 的解析顺序。
+
+## 相关文档
+
+- [fix-SSO无限重定向](./fix-SSO无限重定向.md)
+- [arch-请求模块](./arch-请求模块.md)

package/generators/micro-react/templates/apps/layout/docs/feature-404/351/241/265/351/235/242.md

@@ -0,0 +1,103 @@
+# 404 页面
+
+> 创建时间：2025-01-27
+
+## 功能概述
+
+当用户访问不存在的路由时，展示 404 页面并提供导航选项，支持返回上页或跳转至第一个有权限访问的路由。
+
+## 技术方案
+
+### 技术栈
+
+- 框架：React 18 + @umijs/max
+- UI 组件：@mico-platform/ui `Result`、`Button`、`Space`
+- 路由：React Router 6 通配符路由
+
+### 核心实现
+
+1. 使用 Umi 路由通配符 `/*` 捕获所有未匹配的路径
+2. 复用 403 页面的布局风格，保持 UI 一致性
+3. 动态计算第一个可访问路由：从菜单数据中提取路由，根据用户权限过滤后返回首个有效路径
+
+## 文件清单
+
+### 新增文件
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/pages/404/index.tsx` | 404 页面组件 |
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+| --- | --- |
+| `config/routes.ts` | 添加通配符路由 `/*` |
+
+## API / 组件接口
+
+### NotFoundPage
+
+无外部 Props，使用 Umi 全局状态获取用户信息。
+
+### getFirstAvailablePath
+
+```typescript
+/**
+ * 获取第一个可访问的路由路径
+ */
+const getFirstAvailablePath = (filterOptions: MenuFilterOptions): string;
+```
+
+**逻辑说明**：
+
+1. 从 `window.__MICO_MENUS__` 获取菜单数据
+2. 根据 `disableAuth` 配置决定是否过滤权限
+3. 调用 `filterMenuItems` 过滤无权限菜单
+4. 调用 `extractRoutes` 提取路由列表
+5. 返回第一个路由的 `path`，若无则返回 `/`
+
+## 路由配置
+
+```typescript
+// config/routes.ts
+{
+  path: '/*',
+  component: './404',
+  name: '页面不存在',
+}
+```
+
+通配符路由放在路由配置末尾，匹配所有未被其他路由匹配的路径。
+
+## 使用示例
+
+用户访问 `/non-existent-page` 时：
+
+1. 路由系统无法匹配到具体路由
+2. 通配符路由 `/*` 生效
+3. 渲染 404 页面，显示两个按钮：
+   - **返回上页**：调用 `history.back()`
+   - **前往首页**：跳转至第一个有权限的路由
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| UI 组件 | @mico-platform/ui Result | 与 403 页面保持一致，复用现有组件库 |
+| 首页跳转逻辑 | 动态获取第一个可访问路由 | 适应动态菜单配置，不硬编码路径 |
+| 权限过滤 | 复用 filterMenuItems | 与菜单权限逻辑保持一致 |
+
+## 相关文件
+
+| 文件 | 说明 |
+| --- | --- |
+| `src/pages/403/index.tsx` | 403 页面，UI 风格参考 |
+| `src/common/menu/parser.ts` | 菜单解析工具函数 |
+| `src/constants/index.ts` | `isAuthDisabled` 权限控制函数 |
+
+## 注意事项
+
+- 通配符路由必须放在路由配置最后，否则会提前匹配
+- 动态路由（从 `window.__MICO_MENUS__` 注入）的 404 场景由 `layouts/index.tsx` 处理
+- 此 404 页面主要处理静态路由未匹配的情况

package/generators/micro-react/templates/apps/layout/docs/feature-/344/270/273/351/242/230/350/211/262/345/210/207/346/215/242.md

@@ -11,7 +11,7 @@ Layout 应用支持亮色/暗黑主题切换，通过 CSS 变量实现运行时
 ### 技术栈
 
 - 框架：React 18 + UmiJS 4
-- UI 组件：Arco Design
+- UI 组件：@mico-platform/ui
 - 样式：Less + CSS Variables
 - 状态管理：React Hooks + localStorage
 
@@ -19,7 +19,7 @@ Layout 应用支持亮色/暗黑主题切换，通过 CSS 变量实现运行时
 
 采用双属性主题系统：
 
-1. `arco-theme` 属性控制 Arco Design 组件主题
+1. `arco-theme` 属性控制 @mico-platform/ui 组件主题（基于 Arco）
 2. `data-theme` 属性控制自定义 CSS 变量
 
 两个属性都设置在 `body` 元素上，确保选择器正确匹配。Less 变量引用 CSS 变量，实现编译时类型安全和运行时动态切换。
@@ -28,22 +28,19 @@ Layout 应用支持亮色/暗黑主题切换，通过 CSS 变量实现运行时
 
 ### 主题系统核心文件
 
-主题变量统一定义在 `packages/shared-styles/` 共享包中：
+主题变量由 `@mico-platform/theme` 包提供，主应用与子应用通过该包获取 CSS 变量与 Less 变量：
 
-| 文件路径                                              | 说明                           |
-| ----------------------------------------------------- | ------------------------------ |
-| `packages/shared-styles/themes/normal/custom-var.less` | 亮色主题 CSS 变量定义          |
-| `packages/shared-styles/themes/dark/custom-var.less`   | 暗黑主题 CSS 变量定义          |
-| `packages/shared-styles/arco-override.less`            | Arco Design 变量覆盖映射       |
-| `packages/shared-styles/variables.less`                | Less 变量定义（引用 CSS 变量） |
-| `packages/shared-styles/index.less`                    | 入口文件，导入全部（主应用用） |
-| `packages/shared-styles/variables-only.less`           | 仅 Less 变量（子应用用）       |
+| 入口/子路径                    | 说明                           |
+| ------------------------------ | ------------------------------ |
+| `@mico-platform/theme`         | 主入口，CSS 变量 + Less 变量   |
+| `@mico-platform/theme/variables` | 仅 Less 变量（子应用用） |
+| `@mico-platform/theme/theme-inject`   | 子应用独立运行时注入主题 |
 
 ### Layout 应用文件
 
 | 文件路径                     | 说明                                      |
 | ---------------------------- | ----------------------------------------- |
-| `src/global.less`            | 导入 `<%= packageScope %>/shared-styles` 共享包 |
+| `src/global.less`            | 导入 `@mico-platform/theme`               |
 | `src/common/theme.ts`        | 主题切换逻辑（`applyTheme`、`initTheme`） |
 | `src/hooks/useTheme.ts`      | 主题管理 Hook                             |
 
@@ -82,7 +79,7 @@ const { theme, isDark, toggleTheme, setTheme } = useTheme();
 
 ### 主要颜色变量
 
-> 完整变量列表请参考 [shared-styles 包文档](../../../packages/shared-styles/README.md#主要变量)
+> 完整变量列表请参考 @mico-platform/theme 包文档
 
 | 分类   | 变量                                    |
 | ------ | --------------------------------------- |
@@ -129,7 +126,7 @@ const ThemeToggle: React.FC = () => {
 ### 常量定义
 
 ```typescript
-// src/common/constants.ts
+// src/constants/index.ts
 export const THEME = {
   STORAGE_KEY: '<%= ProjectName %>-theme',
   DEFAULT: 'light' as const,
@@ -151,8 +148,8 @@ export const THEME = {
 
 ```less
 // apps/[子应用]/src/global.less
-@import '<%= packageScope %>/shared-styles/variables-only';
-// 不要使用 @import '<%= packageScope %>/shared-styles'（会包含 CSS 变量定义）
+@import '@mico-platform/theme/variables';
+// 主应用已注入 CSS 变量时，子应用仅需 Less 变量
 ```
 
 #### 2. app.tsx - 开发环境条件注入
@@ -195,24 +192,24 @@ wc -c apps/[子应用]/dist/umi.css
 # 期望：< 500 字节
 ```
 
-### Arco Design 组件主题适配
+### @mico-platform/ui 组件主题适配
 
-子应用使用 Arco Design 组件时，组件样式会自动跟随主应用的主题切换。
+子应用使用 @mico-platform/ui 组件时，组件样式会自动跟随主应用的主题切换。
 
 #### 原理
 
-1. 主应用加载 Arco Design 并暴露到 `window.arco`
-2. 主应用的 `arco.css` 包含 `arco-theme` 属性选择器
+1. 主应用加载 @mico-platform/ui 并暴露到 `window.micoUI`
+2. 主应用的样式包含 `arco-theme` 属性选择器（基于 Arco）
 3. 主应用切换主题时设置 `body[arco-theme="dark"]`
-4. 子应用的 Arco 组件（来自 window.arco）自动应用暗色样式
+4. 子应用的 UI 组件（来自 window.micoUI）自动应用暗色样式
 
-#### 子应用使用 Arco Design
+#### 子应用使用 @mico-platform/ui
 
 > 详细配置请参考 [微前端模式 - 依赖共享机制](./feature-微前端模式.md#依赖共享机制)
 
 ```tsx
-// 子应用可以直接使用 Arco Design 组件
-import { Button, Card, Message, Tag } from '@arco-design/web-react';
+// 子应用可以直接使用 @mico-platform/ui 组件
+import { Button, Card, Message, Tag } from '@mico-platform/ui';
 
 export default function Page() {
   return (
@@ -224,11 +221,10 @@ export default function Page() {
 }
 ```
 
-**注意**：子应用需要配置 `externals` 将 Arco Design 排除打包，详见 [微前端模式文档](./feature-微前端模式.md#依赖共享机制)。
+**注意**：子应用需要配置 `externals` 将 @mico-platform/ui 排除打包，详见 [微前端模式文档](./feature-微前端模式.md#依赖共享机制)。
 
 ## 相关文档
 
 - [微前端模式](./feature-微前端模式.md) - qiankun 微前端架构与依赖共享
 - [日志与常量](./arch-日志与常量.md) - Logger 工具与常量管理（含 THEME 常量）
-- [shared-styles 包](../../../packages/shared-styles/README.md) - 共享样式包使用指南
 - [提交规范](../../../docs/commit-message.md) - Git Commit 规范

package/generators/micro-react/templates/apps/layout/docs/feature-/345/276/256/345/211/215/347/253/257/346/250/241/345/274/217.md

@@ -1,6 +1,7 @@
 # 微前端模式
 
 > 创建时间：2025-12-26
+> 更新时间：2025-03-20（MicroAppLoader 增加 base 与 normalizeMicroAppBase）
 
 ## 功能概述
 
@@ -12,13 +13,13 @@
 
 - 框架：React 18 + @umijs/max
 - 微前端：qiankun (通过 @umijs/max 内置插件)
-- UI 组件：Arco Design
+- UI 组件：@mico-platform/ui
 - 路由：React Router 6
 
 ### 核心实现
 
-1. 主应用通过 `window.__MICO_MENUS__` 获取菜单配置
-2. 解析菜单时根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
+1. 主应用优先通过 `window.__MICO_PAGES__` 获取页面配置，无数据时降级到 `window.__MICO_MENUS__`（详见 [路由与菜单解耦](./feature-路由与菜单解耦.md)）
+2. 解析页面时根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
 3. 路由匹配时，微应用类型使用 `MicroAppLoader` 组件加载
 4. `MicroAppLoader` 使用 qiankun 的 `loadMicroApp` API 动态挂载子应用
 5. 组件卸载时自动调用 `unmount()` 清理子应用
@@ -27,14 +28,16 @@
 
 ### 核心文件
 
-| 文件路径                                   | 说明                       |
-| ------------------------------------------ | -------------------------- |
-| `src/components/MicroAppLoader/index.tsx`  | qiankun 微应用加载器组件   |
-| `src/components/MicroAppLoader/index.less` | 加载器样式                 |
-| `src/common/menu/parser.ts`                | 菜单解析，包含加载类型判断 |
-| `src/common/menu/types.ts`                 | 类型定义                   |
-| `src/layouts/index.tsx`                    | 主布局，集成微应用渲染     |
-| `config/config.ts`                         | qiankun master 配置        |
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/components/MicroAppLoader/index.tsx` | qiankun 微应用加载器组件 |
+| `src/components/MicroAppLoader/micro-app-manager.ts` | 微应用管理器（单例），稳定容器 + 实例缓存 + 操作序列号 |
+| `src/components/MicroAppLoader/index.less` | 加载器样式 |
+| `src/common/menu/parser.ts` | 菜单解析，包含加载类型判断 |
+| `src/common/menu/types.ts` | 类型定义 |
+| `src/layouts/index.tsx` | 主布局，集成微应用渲染 |
+| `src/app.tsx` | qiankun 全局错误处理 |
+| `config/config.ts` | qiankun master 配置 |
 
 ## API / 组件接口
 
@@ -42,6 +45,8 @@
 
 ```typescript
 interface MicroAppLoaderProps {
+  /** 微应用在主应用中的挂载路径前缀（来自 ParsedRoute.base / 页面配置 base），经 normalizeMicroAppBase 后传给子应用 */
+  base: string;
   /** 微应用入口 URL */
   entry: string;
   /** 微应用名称 */
@@ -57,17 +62,53 @@ interface MicroAppLoaderProps {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
+| base | string | 是 | 挂载路径前缀；经 `normalizeMicroAppBase` 后作为子应用 `props.base` |
 | entry | string | 是 | qiankun 入口 URL (htmlUrl 或 jsUrls[0]) |
 | name | string | 是 | 微应用唯一标识 |
 | displayName | string | 否 | 显示名称，用于加载提示 |
 | routePath | string | 否 | 当前路由路径，用于子应用内部路由切换 |
 
+### MicroAppLoader 路由与 base
+
+主应用为微应用补充 **挂载前缀 `base`**，便于子应用对齐 basename、publicPath、内部路由等与路径相关的逻辑；**是否与免鉴权配置做前缀匹配**以当前实现为准（见下「加载门控」）。
+
+#### `base` 与 `routePath` 的区别
+
+| 字段 | 含义 |
+| --- | --- |
+| **base** | 该微应用在主应用中的**挂载前缀**，来自中台 **`page.base`**，解析为 **`ParsedRoute.base`**（缺省时解析为 **`'/'`**）；可与动态路由 **`path`** 不同（如 `path` 为 `/subapp/*` 时 `base` 可为 `/subapp`）。 |
+| **routePath** | 当前激活的**完整路由路径**，随浏览器 URL 变化，用于通知子应用做**内部路由同步**。 |
+
+`routePath` 在布局内为 **`currentRoute.path`**。`base` 在 **`patchClientRoutes`** 与布局内均为 **`route.base` / `currentRoute.base`**。**`name`** 在布局侧常为基于 **`entry`** 的 **`getAppNameFromEntry`**，与 **`base`** 来源不同，需注意。
+
+#### `normalizeMicroAppBase`
+
+组件内导出工具函数（见 `MicroAppLoader/index.tsx`）：
+
+```typescript
+export const normalizeMicroAppBase = (path: string): string =>
+  path.replace(/\/+$/, '').replace(/\*+$/, '');
+```
+
+含义：先去掉末尾 `/`，再去掉末尾 `*`（兼容路由表中的 `/foo/*` 等写法）。**传给子应用的 `props.base` 为规范化后的字符串**。
+
+#### 调用处传参
+
+| 位置 | 说明 |
+| --- | --- |
+| `src/app.tsx` `patchClientRoutes` | 动态注册微应用路由时：`React.createElement(MicroAppLoader, { entry, name: route.path, base: route.base, ... })` |
+| `src/layouts/index.tsx` | 布局内渲染：`<MicroAppLoader base={currentRoute.base} routePath={currentRoute.path} ... />` |
+
+#### 加载门控（认证）
+
+微应用开始执行 `switchTo` / 挂载前，需 **`isAuthReady`**（`isAuthDisabled`、`isPageAuthFree`、`isNoAuthRoute(location.pathname)`、`isNoPermissionRoute(location.pathname)` 或已存在 `currentUser` 等，见组件内实现）。**当前以浏览器 `location.pathname` 与全局常量为准**，未单独使用 `base` 与 `window.__MICO_CONFIG__.noAuthRouteList` 做前缀匹配。
+
 ### MicroAppProps (传递给子应用)
 
 ```typescript
 interface MicroAppProps {
   /** 主应用标识 */
-  mainApp: 'portal-web';
+  mainApp: '<%= projectName %>';
   /** 运行环境 */
   env: 'development' | 'testing' | 'production';
   /** 认证 token */
@@ -84,6 +125,8 @@ interface MicroAppProps {
   timezone: string;
   /** 在线状态 */
   presenceStatus: string;
+  /** 挂载路径前缀（为 `normalizeMicroAppBase(MicroAppLoader.base)`） */
+  base: string;
   /** 当前路由路径 */
   routePath?: string;
   /** 共享的 request 实例，子应用可直接使用 */
@@ -122,6 +165,8 @@ export async function update(props: MicroAppProps) {
 ```typescript
 interface ParsedRoute {
   path: string;
+  /** 微应用挂载前缀（来自 page.base，解析缺省为 '/'） */
+  base: string;
   name: string;
   icon: string;
   /** 加载类型: internal(内部路由) | microapp(qiankun微应用) */
@@ -139,6 +184,8 @@ interface PageConfig {
   id: number;
   name: string;
   route: string;
+  /** 微应用挂载前缀（可与 route 不同） */
+  base: string;
   enabled: boolean;
   /** 微应用 HTML 入口 URL (优先使用) */
   htmlUrl: string | null;
@@ -208,7 +255,12 @@ const menus: MenuItem[] = [
 const renderContent = () => {
   if (currentRoute?.loadType === 'microapp' && currentRoute.entry) {
     return (
-      <MicroAppLoader entry={currentRoute.entry} name={currentRoute.name} />
+      <MicroAppLoader
+        entry={currentRoute.entry}
+        name={currentRoute.name}
+        base={currentRoute.base}
+        routePath={currentRoute.path}
+      />
     );
   }
   return <Outlet />;
@@ -253,9 +305,9 @@ export const getRequest = () => mainAppProps?.request;
 
 ### 问题背景
 
-如果子应用直接安装 React、Arco Design 等大型库，会导致：
+如果子应用直接安装 React、@mico-platform/ui 等大型库，会导致：
 
-1. **包体积重复**：React (~140KB) + Arco Design (~800KB) 被打包多次
+1. **包体积重复**：React (~140KB) + UI 库 (~800KB) 被打包多次
 2. **样式冲突**：多份 CSS 可能互相覆盖
 3. **React 实例问题**：可能出现 "Invalid hook call" 错误
 
@@ -267,8 +319,8 @@ export const getRequest = () => mainAppProps?.request;
 ┌─────────────────────────────────────────────────────────────┐
 │  主应用 (layout)                                            │
 │  ┌─────────────────────────────────────────────────────────┐│
-│  │ 1. 打包并加载 React、ReactDOM、Arco Design              ││
-│  │ 2. 暴露到 window.React / window.ReactDOM / window.arco  ││
+│  │ 1. 打包并加载 React、ReactDOM、@mico-platform/ui        ││
+│  │ 2. 暴露到 window.React / window.ReactDOM / window.micoUI ││
 │  └─────────────────────────────────────────────────────────┘│
 │                           ↓ 共享                            │
 │  ┌─────────────────────────────────────────────────────────┐│
@@ -286,7 +338,7 @@ export const getRequest = () => mainAppProps?.request;
 
 ```typescript
 // apps/layout/src/app.tsx
-import * as arco from '@arco-design/web-react';
+import * as micoUI from '@mico-platform/ui';
 import React from 'react';
 import ReactDOM from 'react-dom';
 
@@ -294,7 +346,7 @@ import ReactDOM from 'react-dom';
 if (typeof window !== 'undefined') {
   (window as any).React = React;
   (window as any).ReactDOM = ReactDOM;
-  (window as any).arco = arco;
+  (window as any).micoUI = micoUI;
 }
 ```
 
@@ -331,7 +383,7 @@ const config: ReturnType<typeof defineConfig> = {
   externals: {
     react: 'window.React',
     'react-dom': 'window.ReactDOM',
-    '@arco-design/web-react': 'window.arco',
+    '@mico-platform/ui': 'window.micoUI',
   },
 };
 
@@ -359,23 +411,23 @@ export default defineConfig(config);
 
 #### 3. package.json - 开发依赖
 
-将 Arco Design 放在 `devDependencies`（用于类型提示和开发），生产环境从主应用获取：
+将 @mico-platform/ui 放在 `devDependencies`（用于类型提示和开发），生产环境从主应用获取。版本由生成器在创建子应用时从 npm 解析为当时最新版本（不使用 `latest` 标签）：
 
 ```json
 {
   "devDependencies": {
-    "@arco-design/web-react": "^2.66.6"
+    "@mico-platform/ui": "^x.x.x"
   }
 }
 ```
 
-### 子应用使用 Arco Design
+### 子应用使用 @mico-platform/ui
 
-配置完成后，子应用可以正常导入和使用 Arco Design 组件：
+配置完成后，子应用可以正常导入和使用 UI 组件：
 
 ```tsx
 // apps/[子应用]/src/pages/index.tsx
-import { Button, Card, Message, Tag } from '@arco-design/web-react';
+import { Button, Card, Message, Tag } from '@mico-platform/ui';
 
 export default function HomePage() {
   return (
@@ -393,7 +445,7 @@ export default function HomePage() {
 
 | 配置方式           | 子应用 JS 体积 | 说明                     |
 | ------------------ | -------------- | ------------------------ |
-| 直接安装依赖       | ~1.2MB         | 包含 React + Arco Design |
+| 直接安装依赖       | ~1.2MB         | 包含 React + @mico-platform/ui |
 | **externals 共享** | **~50KB**      | 仅业务代码               |
 
 ### 运行环境说明
@@ -414,14 +466,15 @@ export default function HomePage() {
 - 组件会在 `entry` 或 `name` 变化时重新加载微应用
 - 加载失败会显示错误信息，便于调试
 - **子应用应使用主应用传递的 `request` 实例**，确保认证 token 和拦截器一致
-- **子应用使用 externals 共享依赖**，避免重复打包 React 和 Arco Design
+- **子应用使用 externals 共享依赖**，避免重复打包 React 和 @mico-platform/ui
 
 ## 相关文档
 
+- [路由与菜单解耦](./feature-路由与菜单解耦.md) - 路由注册与菜单导航数据源分离
+- [菜单权限控制](./feature-菜单权限控制.md) - sideMenus 白名单权限逻辑
 - [主题色切换](./feature-主题色切换.md) - 主题系统实现与子应用适配
 - [请求模块架构](./arch-请求模块.md) - HTTP 请求层模块化设计
 - [日志与常量](./arch-日志与常量.md) - Logger 工具与常量管理
-- [shared-styles 包](../../../packages/shared-styles/README.md) - 共享样式包使用指南
 - [提交规范](../../../docs/commit-message.md) - Git Commit 规范
 
 ## 加载类型判断逻辑
@@ -430,3 +483,107 @@ export default function HomePage() {
 有 htmlUrl 或 jsUrls  →  microapp (使用 qiankun 加载)
 无 htmlUrl 且无 jsUrls →  internal (使用 Outlet 渲染)
 ```
+
+## 加载健壮性机制
+
+> 更新于 2025-01-25
+
+### 解决的问题
+
+| 原问题 | 风险 | 修复方案 |
+|--------|------|----------|
+| 无全局错误处理，子应用异常可能导致页面崩溃 | 高 | 添加 `addGlobalUncaughtErrorHandler` |
+| unmount 使用 rAF 时序不可靠 | 高 | 使用 `queueMicrotask` |
+| 同名应用并发加载可能冲突 | 高 | 会话 ID 锁 + `waitForUnmount` |
+| unmount 可能永久卡死 | 中 | 10 秒超时机制 |
+| 加载期间 Props 变化被跳过 | 中 | 加载完成后重新同步 Props |
+
+### 全局错误处理
+
+在 `src/app.tsx` 中注册 qiankun 全局错误处理器，捕获子应用运行时未捕获的异常：
+
+```typescript
+import { addGlobalUncaughtErrorHandler } from 'qiankun';
+
+addGlobalUncaughtErrorHandler((event: Event | string) => {
+  // 捕获子应用 JS 运行时错误
+  // 捕获子应用生命周期钩子异常
+  // 捕获资源加载失败
+  console.error('[qiankun] Global uncaught error:', event);
+});
+```
+
+### MicroAppManager API (micro-app-manager.ts)
+
+`MicroAppManager` 是单例类，管理微应用的加载、缓存、切换和卸载：
+
+```typescript
+interface MicroAppConfig {
+  name: string;
+  entry: string;
+  target: HTMLElement;       // 目标挂载位置
+  props: Record<string, unknown>;
+}
+
+interface MicroAppState {
+  loading: boolean;
+  error: string | null;
+  mounted: boolean;
+}
+
+const manager = microAppManager; // 单例，导出即用
+
+/** 切换到指定微应用（已挂载则仅更新 props） */
+manager.switchTo(config: MicroAppConfig): void;
+
+/** 更新当前已挂载微应用的 props */
+manager.updateProps(props: Record<string, unknown>): void;
+
+/** 取消待处理的请求 */
+manager.cancel(): void;
+
+/** 清除所有缓存实例 */
+manager.clearCache(): Promise<void>;
+
+/** 获取调试信息 */
+manager.getDebugInfo(): object;
+
+/** 设置状态变化回调 */
+manager.setStateCallback(callback: StateChangeCallback | null): void;
+```
+
+### 核心设计
+
+1. **稳定容器**：容器在 `document.body` 中创建，激活时移到目标元素内，停用时移回 body 隐藏，不受 React 生命周期影响
+2. **实例缓存**：每个 entry 只 `loadMicroApp` 一次，后续切换复用已有实例（mount/unmount）
+3. **操作序列号**：通过递增的 `operationSeq` 检测过期操作，替代旧的会话 ID 机制
+4. **自动路由守卫**：由独立的 `route-guard.ts` 自动检测用户意图，业务代码无需感知
+
+### 快速切换时序
+
+```
+场景：A → B → A 快速切换
+
+switchTo(A)：operationSeq=1，开始 loadMicroApp
+  ↓
+switchTo(B)：operationSeq=2，A 的 pendingRequest 被替换
+  ↓
+A 的 processRequest 在异步步骤中检测 shouldAbort(mySeq=1) → true
+  ↓
+A 等待 mountPromise 完成后执行 safeUnmount，容器移回 body
+  ↓
+B 开始 processRequest，检查缓存 → 无缓存 → loadMicroApp
+  ↓
+B 加载完成后同步最新 Props（locale/timezone/routePath 等）
+```
+
+### 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| 容器策略 | 稳定容器（body 中创建，移动挂载） | 不受 React 生命周期影响，避免容器被意外销毁 |
+| 并发控制 | 操作序列号 + pendingRequest 队列 | 简单高效，新请求自动覆盖旧请求 |
+| 实例缓存 | loadPromise 完成后立即缓存 | 即使被 abort 也可复用，避免重复加载 |
+| unmount 安全 | 等待 mountPromise 完成后再 unmount | 避免 single-spa error #32 |
+| 超时保护 | load 30s / mount 30s / unmount 10s | 平衡等待时间与异常检测速度 |
+| Props 同步 | mount 完成后立即 safeUpdate | 确保加载期间的变化不丢失 |