generator-mico-cli 0.2.21 → 0.2.22

package/generators/micro-react/templates/.cursor/rules/always-read-docs.mdc

@@ -20,8 +20,15 @@ docs/
 ### 2. Layout 应用文档 (`/apps/layout/docs/`)
 ```
 apps/layout/docs/
-├── feature-微前端模式.md   # qiankun 微前端架构
-└── feature-主题色切换.md   # 主题系统实现
+├── feature-微前端模式.md        # qiankun 微前端架构
+├── feature-路由与菜单解耦.md    # PAGES/MENUS 数据源分离、双层权限
+├── feature-菜单权限控制.md      # sideMenus 白名单、认证与授权分离
+├── feature-主题色切换.md        # 主题系统实现
+├── feature-404页面.md           # 404 页面
+├── arch-请求模块.md             # HTTP 请求层模块化设计
+├── arch-日志与常量.md           # Logger 工具与常量管理
+├── common-intl.md               # 国际化公共包
+└── utils-timezone.md            # 时区工具
 ```
 
 ### 3. 其他应用文档
@@ -33,8 +40,9 @@ apps/layout/docs/
 
 ### Step 1: 确认需求涉及的模块
 - 微前端相关 → 阅读 `apps/layout/docs/feature-微前端模式.md`
+- 路由/菜单/权限相关 → 阅读 `apps/layout/docs/feature-路由与菜单解耦.md` 和 `apps/layout/docs/feature-菜单权限控制.md`
 - 主题/样式相关 → 阅读 `apps/layout/docs/feature-主题色切换.md`
-- 请求/认证相关 → 阅读 `src/common/request/` 和 `src/common/auth/` 源码
+- 请求/认证相关 → 阅读 `apps/layout/docs/arch-请求模块.md` 和 `src/common/auth/` 源码
 - 菜单相关 → 阅读 `src/common/menu/` 源码
 
 ### Step 2: 查找相关文档
@@ -54,9 +62,11 @@ find . -name "*.md" -type f | grep -v node_modules
 | 需求类型 | 必读文档 |
 |---------|---------|
 | 新建子应用 | `apps/layout/docs/feature-微前端模式.md` |
+| 路由/页面配置 | `apps/layout/docs/feature-路由与菜单解耦.md` |
+| 权限控制 | `apps/layout/docs/feature-菜单权限控制.md` |
 | 主题适配 | `apps/layout/docs/feature-主题色切换.md` |
 | 提交代码 | `docs/commit-message.md` |
-| API 请求 | `src/common/request/index.ts` 源码注释 |
+| API 请求 | `apps/layout/docs/arch-请求模块.md` |
 | 认证登录 | `src/common/auth/` 目录源码 |
 | 菜单配置 | `src/common/menu/types.ts` 类型定义 |
 

package/generators/micro-react/templates/.cursor/rules/layout-app.mdc

@@ -63,24 +63,27 @@ apps/layout/
 const BasicLayout: React.FC = () => {
   const location = useLocation();
 
-  // 解析路由配置
-  const routes = useMemo(() => {
-    const menus = getWindowMenus();
-    return extractRoutes(menus);
+  // 所有页面路由（优先 PAGES，降级 MENUS）— 用于路由匹配和渲染
+  const allPageRoutes = useMemo(() => {
+    return getDynamicRoutes();
   }, []);
 
-  // 查找当前路由配置
+  // 菜单路由（从 MENUS）— 用于权限交叉引用
+  const allMenuRoutes = useMemo(() => {
+    return extractRoutes(getMenus());
+  }, []);
+
+  // 当前路由配置（从所有页面路由中查找）
   const currentRoute = useMemo(() => {
-    return findRouteByPath(routes, location.pathname);
-  }, [routes, location.pathname]);
+    return findRouteByPath(allPageRoutes, location.pathname);
+  }, [allPageRoutes, location.pathname]);
 
   // 渲染页面内容
   const renderContent = () => {
-    // 微应用类型使用 MicroAppLoader
     if (currentRoute?.loadType === 'microapp' && currentRoute.entry) {
-      return <MicroAppLoader entry={currentRoute.entry} name={currentRoute.path} />;
+      const appName = getAppNameFromEntry(currentRoute.entry);
+      return <MicroAppLoader entry={currentRoute.entry} name={appName} />;
     }
-    // 内部路由使用 Outlet
     return <Outlet />;
   };
 
@@ -98,28 +101,36 @@ const BasicLayout: React.FC = () => {
 };
 ```
 
-### 2. 菜单系统 (common/menu/)
+### 2. 全局数据源 (common/portal-data.ts) + 菜单系统 (common/menu/)
 
 ```typescript
-// 获取菜单数据
-const menus = getWindowMenus();
+// 获取页面列表 (window.__MICO_PAGES__)
+const pages = getPages();
+
+// 获取菜单树 (window.__MICO_MENUS__)
+const menus = getMenus();
 
-// 提取路由配置
-const routes = extractRoutes(menus);
+// 从页面列表提取动态路由（优先数据源）
+const routes = getDynamicRoutes();
 
-// 解析菜单项
+// 从菜单树提取路由（用于权限交叉引用）
+const menuRoutes = extractRoutes(menus);
+
+// 解析菜单项（用于侧边栏渲染）
 const menuItems = parseMenuItems(menus);
 
 // 查找当前路由
 const currentRoute = findRouteByPath(routes, pathname);
+
+// 通过 pageId 查找页面（O(1)）
+const page = getPageById(pageId);
 ```
 
 ### 3. 动态路由 (app.tsx)
 
 ```typescript
 export function patchClientRoutes({ routes }: { routes: any[] }) {
-  const menus = getWindowMenus();
-  const dynamicRoutes = extractRoutes(menus);
+  const dynamicRoutes = getDynamicRoutes(); // 从 __MICO_PAGES__ 获取
 
   const rootRoute = routes.find((r) => r.path === '/');
   dynamicRoutes.forEach((route) => {
@@ -128,9 +139,7 @@ export function patchClientRoutes({ routes }: { routes: any[] }) {
       name: route.name,
       meta: {
         loadType: route.loadType,
-        htmlUrl: route.htmlUrl,
-        jsUrls: route.jsUrls,
-        cssUrls: route.cssUrls,
+        entry: route.entry,
       },
     });
   });
@@ -265,8 +274,9 @@ const { collapsed } = useModel('global');
 
 ## 注意事项
 
-1. **菜单数据来源**: 通过 `window.__MICO_MENUS__` 注入
-2. **路由动态生成**: 在 `patchClientRoutes` 中根据菜单生成路由
-3. **微应用判断**: 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
-4. **主题初始化**: 在 `app.tsx` 中调用 `initTheme()` 避免闪烁
-5. **认证共享**: 子应用使用主应用传递的 `request` 实例
+1. **数据来源**: 页面列表通过 `window.__MICO_PAGES__` 注入，菜单树通过 `window.__MICO_MENUS__` 注入
+2. **路由动态生成**: 在 `patchClientRoutes` 中优先从 `__MICO_PAGES__` 生成路由
+3. **权限交叉引用**: 菜单路由（`__MICO_MENUS__`）用于权限判断，页面路由（`__MICO_PAGES__`）用于渲染
+4. **微应用判断**: 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
+5. **主题初始化**: 在 `app.tsx` 中调用 `initTheme()` 避免闪烁
+6. **认证共享**: 子应用使用主应用传递的 `request` 实例

package/generators/micro-react/templates/.cursor/rules/project-overview.mdc

@@ -61,15 +61,16 @@ alwaysApply: true
 - **关键文件**:
   - `src/layouts/index.tsx` - 主布局组件
   - `src/components/MicroAppLoader/` - 微应用加载器
-  - `src/common/menu/parser.ts` - 菜单解析与路由提取
+  - `src/common/menu/parser.ts` - 菜单解析、页面数据提取与路由生成
   - `src/common/request/index.ts` - 统一请求封装
   - `src/hooks/useTheme.ts` - 主题管理 Hook
 
 ### 2. 微前端架构
-- 菜单数据通过 `window.__MICO_MENUS__` 注入
+- 路由注册优先使用 `window.__MICO_PAGES__`（页面列表），无数据时降级到 `window.__MICO_MENUS__`（菜单树）
 - 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
 - 使用 `loadMicroApp` API 动态挂载子应用
 - 子应用共享主应用的 `request` 实例
+- 权限通过菜单交叉引用 + 页面级兜底的双层策略控制
 
 ### 3. 主题系统
 - 支持亮色/暗黑主题切换
@@ -123,6 +124,8 @@ Jenkins 根据环境执行 `CICD/` 下的构建脚本：
 ## 相关文档
 
 - [微前端模式](mdc:apps/layout/docs/feature-微前端模式.md)
+- [路由与菜单解耦](mdc:apps/layout/docs/feature-路由与菜单解耦.md)
+- [菜单权限控制](mdc:apps/layout/docs/feature-菜单权限控制.md)
 - [主题色切换](mdc:apps/layout/docs/feature-主题色切换.md)
 - [提交规范](mdc:docs/commit-message.md)
 - [部署说明](mdc:deployDesc.md)

package/generators/micro-react/templates/CLAUDE.md

@@ -108,8 +108,8 @@ Logger 工具在 `src/common/logger.ts`，常量定义在 `src/constants/index.t
 ### 认证模块
 认证逻辑在 `src/common/auth/`，核心文件 `auth-manager.ts` 管理 Token 存储和用户信息。SSO 登录在 `getInitialState()` 中完成，确保 UI 渲染前认证已就绪。
 
-### 菜单系统
-菜单解析与类型定义在 `src/common/menu/`。
+### 菜单与路由系统
+菜单解析与类型定义在 `src/common/menu/`。路由注册消费 `window.__MICO_PAGES__`（页面列表），菜单栏消费 `window.__MICO_MENUS__`（菜单树），两者解耦运作。权限通过菜单交叉引用 + 页面级兜底的双层策略控制。详见 [路由与菜单解耦](./apps/layout/docs/feature-路由与菜单解耦.md) 和 [菜单权限控制](./apps/layout/docs/feature-菜单权限控制.md)。
 
 ### 微前端
 layout 应用作为 qiankun 主应用，子应用通过 Umi 配置中的 qiankun 配置注册。详见 [微前端模式](./apps/layout/docs/feature-微前端模式.md)。
@@ -121,6 +121,8 @@ layout 应用作为 qiankun 主应用，子应用通过 Umi 配置中的 qiankun
 | [README.md](./README.md) | 项目入口、技术栈、常用命令 |
 | [提交规范](./docs/commit-message.md) | Git Commit 详细规范 |
 | [微前端模式](./apps/layout/docs/feature-微前端模式.md) | qiankun 架构、MicroAppLoader、子应用配置 |
+| [路由与菜单解耦](./apps/layout/docs/feature-路由与菜单解耦.md) | PAGES/MENUS 数据源分离、双层权限控制 |
+| [菜单权限控制](./apps/layout/docs/feature-菜单权限控制.md) | sideMenus 白名单、认证与授权分离 |
 | [主题色切换](./apps/layout/docs/feature-主题色切换.md) | useTheme Hook、CSS 变量系统 |
 | [请求模块架构](./apps/layout/docs/arch-请求模块.md) | HTTP 请求层模块化设计 |
 | [日志与常量](./apps/layout/docs/arch-日志与常量.md) | Logger 工具与常量管理 |

package/generators/micro-react/templates/apps/layout/config/config.dev.ts

@@ -4,6 +4,7 @@ import { defineConfig } from '@umijs/max';
 
 
 import mockMenus from '../mock/menus';
+import mockPages from '../mock/pages';
 
 const config: ReturnType<typeof defineConfig> = {
   publicPath: '/',
@@ -16,18 +17,21 @@ const config: ReturnType<typeof defineConfig> = {
     {
       content: `
         window.__MICO_MENUS__ = ${JSON.stringify(mockMenus)};
+        window.__MICO_PAGES__ = ${JSON.stringify(mockPages)};
         window.__MICO_CONFIG__ = {
           appName: '<%= projectName %>',
+          title: '测试样例',
+          logo: '',
           apiBaseUrl: '',
           defaultPath: '',
           // 免认证路由（跳过 SSO 登录），支持 /* 前缀匹配
           // noAuthRouteList: ['/*'],
           // 免权限校验路由（跳过菜单权限检查）
-          // noPermissionRouteList: ['/task-query/*'],
+          noPermissionRouteList: [],
           // 不显示布局的路由（全屏页面）
-          // noLayoutRouteList: ['/task-query/*'],
+          // noLayoutRouteList: [],
           // 关闭权限控制（调试用）
-          disableAuth: true,
+          disableAuth: false,
         };
       `,
     },

package/generators/micro-react/templates/apps/layout/config/routes.ts

@@ -5,11 +5,6 @@
  * @note Umi Max 会自动使用 src/layouts/index.tsx 作为全局布局，无需显式配置
  */
 export default [
-  {
-    path: '/user/login',
-    component: './User/Login',
-    name: '登录',
-  },
   {
     path: '/',
     component: './Home',

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

@@ -18,8 +18,8 @@
 
 ### 核心实现
 
-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()` 清理子应用
@@ -334,6 +334,7 @@ const config: ReturnType<typeof defineConfig> = {
   externals: {
     react: 'window.React',
     'react-dom': 'window.ReactDOM',
+    'react-dom/client': 'window.ReactDOMClient',
     '@mico-platform/ui': 'window.micoUI',
   },
 };
@@ -421,6 +422,8 @@ export default function HomePage() {
 
 ## 相关文档
 
+- [路由与菜单解耦](./feature-路由与菜单解耦.md) - 路由注册与菜单导航数据源分离
+- [菜单权限控制](./feature-菜单权限控制.md) - sideMenus 白名单权限逻辑
 - [主题色切换](./feature-主题色切换.md) - 主题系统实现与子应用适配
 - [请求模块架构](./arch-请求模块.md) - HTTP 请求层模块化设计
 - [日志与常量](./arch-日志与常量.md) - Logger 工具与常量管理

package/generators/micro-react/templates/apps/layout/docs/feature-/350/217/234/345/215/225/346/235/203/351/231/220/346/216/247/345/210/266.md

@@ -19,12 +19,12 @@
 
 ### 四种路由场景
 
-| 场景 | noAuthRouteList | noPermissionRouteList | 示例 |
-| --- | --- | --- | --- |
-| 公开页面 | ✅ | ✅ | 首页、活动页 |
-| 登录后公共页面 | ❌ | ✅ | 个人设置、帮助中心 |
-| 需要权限的页面 | ❌ | ❌ | 后台管理、业务功能 |
-| 登录页等特殊页面 | ✅ | ✅ | /user/login、/403 |
+| 场景 | noAuthRouteList | noPermissionRouteList | accessControlEnabled | 示例 |
+| --- | --- | --- | --- | --- |
+| 公开页面 | ✅ | ✅ | `false` | 首页、活动页 |
+| 登录后公共页面 | ❌ | ✅ | - | 个人设置、帮助中心 |
+| 需要权限的页面 | ❌ | ❌ | `true` | 后台管理、业务功能 |
+| 登录页等特殊页面 | ✅ | ✅ | `false` | /login、/403 |
 
 ## 技术方案
 
@@ -40,22 +40,28 @@
 用户访问路由
     │
     ▼
-┌─────────────────────────────────┐
-│  1. SSO 认证检查 (app.tsx)       │
-│     isNoAuthRoute(pathname)?    │
-│     ├── 是 → 跳过 SSO           │
-│     └── 否 → 执行 ensureSsoSession()
-└─────────────────────────────────┘
+┌──────────────────────────────────────────────┐
+│  1. SSO 认证检查 (app.tsx)                    │
+│     isNoAuthRoute(pathname)?                 │
+│     ├── 是 → 跳过 SSO                        │
+│     page.accessControlEnabled === false?     │
+│     ├── 是 → 跳过 SSO（PAGES 数据驱动）       │
+│     └── 否 → 执行 ensureSsoSession()          │
+└──────────────────────────────────────────────┘
     │
     ▼
-┌─────────────────────────────────┐
-│  2. 权限校验 (layouts/index.tsx) │
-│     isNoPermissionRoute(pathname)?
-│     ├── 是 → 跳过权限校验        │
-│     └── 否 → 检查 side_menus    │
-│              ├── 有权限 → 正常渲染
-│              └── 无权限 → 显示 403
-└─────────────────────────────────┘
+┌──────────────────────────────────────────┐
+│  2. 权限校验 (layouts/index.tsx)          │
+│     isNoPermissionRoute(pathname)?       │
+│     ├── 是 → 跳过权限校验                │
+│     └── 否 → 双层权限判断                │
+│              Tier 1: 页面在菜单中？       │
+│              ├── 是 → 沿用 sideMenus     │
+│              │        白名单逻辑          │
+│              └── 否 → Tier 2: 页面级权限  │
+│                       adminOnly / routeKey│
+│              详见：路由与菜单解耦文档      │
+└──────────────────────────────────────────┘
     │
     ▼
 ┌─────────────────────────────────┐
@@ -66,12 +72,16 @@
 └─────────────────────────────────┘
     │
     ▼
-┌─────────────────────────────────┐
-│  4. 子应用加载 (MicroAppLoader)  │
-│     isNoPermissionRoute(pathname)?
-│     ├── 是 → 直接加载           │
-│     └── 否 → 等待 currentUser   │
-└─────────────────────────────────┘
+┌──────────────────────────────────────────────┐
+│  4. 子应用加载 (MicroAppLoader)               │
+│     page.accessControlEnabled === false?     │
+│     ├── 是 → 直接加载（PAGES 数据驱动）       │
+│     isNoAuthRoute(pathname)?                 │
+│     ├── 是 → 直接加载（静态配置兜底）         │
+│     isNoPermissionRoute(pathname)?           │
+│     ├── 是 → 直接加载                        │
+│     └── 否 → 等待 currentUser                │
+└──────────────────────────────────────────────┘
 ```
 
 ### 权限判断逻辑（详细）
@@ -84,22 +94,39 @@
     ├── 是 → 允许所有访问（调试模式）
     │
     ▼
+page.accessControlEnabled === false？
+    ├── 是 → 跳过 SSO 认证 + 跳过权限校验
+    │
+    ▼
 是否在 noPermissionRouteList 中？
     ├── 是 → 允许访问，显示全部菜单
     │
     ▼
+是否是非动态路由（不在 PAGES 中）？
+    ├── 是 → 交给 Umi 处理（404 等静态路由）
+    │
+    ▼
 是否是超级用户？
-    ├── 是 → 允许访问所有菜单
+    ├── 是 → 允许访问所有页面
     │
     ▼
-菜单项 adminOnly === true？
-    ├── 是 → 禁止访问（仅超级管理员可见）
+Tier 1: 页面在菜单中？
+    ├── 是 → 沿用菜单权限逻辑：
+    │        菜单项 adminOnly === true？
+    │        ├── 是 → 禁止访问
+    │        检查 side_menus 白名单
+    │        ├── 匹配 → 允许访问
+    │        └── 不匹配 → 显示 403
     │
     ▼
-检查 side_menus 白名单
-    ├── 精确匹配：menuPath === side_menus[i]
-    ├── 前缀匹配：side_menus[i].startsWith(menuPath + '.')
-    └── 都不匹配 → 禁止访问，显示 403
+Tier 2: 隐藏页面（不在菜单中）
+    adminOnly === true？
+    ├── 是 → 显示 403
+    accessControlEnabled === true？
+    ├── 是 → 检查 routeKey ∈ side_menus
+    │        ├── 匹配 → 允许访问
+    │        └── 不匹配 → 显示 403
+    └── 否 → 允许访问
 ```
 
 ## 文件清单
@@ -251,18 +278,30 @@ export const NO_PERMISSION_ROUTE_LIST: string[] = ['/403', '/404'];
 ### Layout 中的权限判断
 
 ```tsx
-// layouts/index.tsx
+// layouts/index.tsx — 双层权限判断
 const isForbidden = useMemo(() => {
-  // 关闭权限控制时，不校验权限
   if (isAuthDisabled()) return false;
-  // 免权限校验路由，不检查菜单权限
   if (isNoPermissionRoute(location.pathname)) return false;
-  // 如果在有权限的路由中找到了，说明有权限
-  if (currentRoute) return false;
-  // 在所有路由中存在但无权限
-  const routeInAll = findRouteByPath(allRoutes, location.pathname);
-  return !!routeInAll;
-}, [currentRoute, allRoutes, location.pathname]);
+  if (!currentRoute) return false; // 非动态路由
+  if (isSuperuserUser(currentUser?.is_superuser)) return false;
+
+  // Tier 1: 菜单权限交叉引用
+  const inAllMenu = findRouteByPath(allMenuRoutes, location.pathname);
+  if (inAllMenu) {
+    return !findRouteByPath(allowedMenuRoutes, location.pathname);
+  }
+
+  // Tier 2: 隐藏页面级权限
+  if (!hasWindowPages()) return false;
+  const page = findPageByPath(getWindowPages(), location.pathname);
+  if (!page) return false;
+  if (page.adminOnly) return true;
+  if (page.accessControlEnabled) {
+    const sideMenus = (currentUser?.side_menus || []) as string[];
+    return !page.routeKey || !sideMenus.includes(page.routeKey);
+  }
+  return false;
+}, [...]);
 ```
 
 ### MicroAppLoader 中的认证判断
@@ -271,6 +310,8 @@ const isForbidden = useMemo(() => {
 // components/MicroAppLoader/index.tsx
 const isAuthReady =
   isAuthDisabled() ||
+  isPageAuthFree(location.pathname) ||
+  isNoAuthRoute(location.pathname) ||
   isNoPermissionRoute(location.pathname) ||
   !!initialState?.currentUser;
 
@@ -280,16 +321,31 @@ if (!isAuthReady) {
 }
 ```
 
+判断优先级：
+1. `isAuthDisabled()` — 全局关闭权限，直接放行
+2. `isPageAuthFree` — **PAGES 数据驱动**，页面 `accessControlEnabled === false` 时跳过认证和权限校验
+3. `isNoAuthRoute()` — 静态配置兜底，免认证路由（PAGES 未注入时的降级保护）
+4. `isNoPermissionRoute()` — 免权限路由（如 403/404），无需等待 currentUser
+5. `!!initialState?.currentUser` — 已登录，有用户信息
+
+**注意**：`accessControlEnabled === false` 同时影响三个阶段：
+
+- SSO 认证（`app.tsx`）：跳过 `ensureSsoSession()` 和 `handleAuthFailureRedirect()`
+- 权限校验（`layouts/index.tsx`）：Tier 2 隐藏页面默认放行
+- 子应用加载（`MicroAppLoader`）：不等待 currentUser 直接加载
+
 ## 设计决策
 
 | 决策点 | 选择 | 理由 |
 | --- | --- | --- |
+| accessControlEnabled 统一控制 | `false` 同时跳过认证和授权 | PAGES 数据驱动，一个字段即可标记公开页面，无需重复配置 noAuthRouteList |
 | 认证与授权分离 | 两个独立配置项 | 不同场景需要不同组合，如"需要登录但不需要权限"的个人设置页 |
 | 权限模型 | 白名单 (`side_menus`) | 后端返回的 `side_menus` 是允许列表，比黑名单更安全 |
 | 403 处理 | 原地渲染组件 | 保持 URL 不变，用户体验更好，便于分享链接 |
 | 父级菜单显示 | 前缀匹配 | 子菜单有权限时，父级菜单需要作为容器显示 |
 | 超级用户 | 跳过所有检查 | 管理员需要完整访问权限 |
 | 免权限路由的菜单 | 显示全部 | 用户访问公开页面时应能看到所有导航选项 |
+| 免认证路由的子应用 | 直接加载 | 不等待 currentUser，免认证路由本身不需要登录 |
 | 免权限路由的子应用 | 直接加载 | 不等待 currentUser，避免加载卡住 |
 | 静态路由不受权限控制 | 默认允许访问 | 见下方"静态路由与动态路由"说明 |
 | adminOnly 判断 | 读取菜单数据字段 | 替代硬编码菜单名称匹配，由后端数据驱动，支持多语言且无需前端维护 |
@@ -301,7 +357,7 @@ if (!isAuthReady) {
 | 类型 | 来源 | 示例 |
 | --- | --- | --- |
 | **静态路由** | 代码中定义 (`config/routes.ts`) | `/`, `/403`, `/404`, `/user/login` |
-| **动态路由** | 后端菜单配置 (`window.__MICO_MENUS__`) | `/queue-management`, `/quality-check` |
+| **动态路由** | 后端页面配置 (`window.__MICO_PAGES__`，降级 `window.__MICO_MENUS__`) | `/queue-management`, `/quality-check` |
 
 ### 权限控制范围
 
@@ -311,9 +367,11 @@ if (!isAuthReady) {
 权限判断逻辑（isForbidden）：
 1. 检查 isAuthDisabled() → 关闭则全部允许
 2. 检查 isNoPermissionRoute() → 在免权限列表中则允许
-3. 检查 currentRoute（有权限路由） → 找到则允许
-4. 检查 routeInAll（所有动态路由） → 存在则返回 403
-5. 都不匹配 → 交给 Umi 处理（静态路由走这里）
+3. 检查 currentRoute（PAGES 中的路由）→ 不存在则非动态路由，交给 Umi
+4. 检查 isSuperuserUser() → 超级用户放行
+5. Tier 1: 在菜单中 → 检查 allowedMenuRoutes
+6. Tier 2: 不在菜单（隐藏页面）→ 检查 adminOnly + accessControlEnabled + routeKey
+7. 都不匹配 → 放行
 ```
 
 ### 设计理由
@@ -351,10 +409,11 @@ if (!isAuthReady) {
 - `side_menus` 格式为菜单路径，如 `"列队管理.配置队列"`
 - `miss_permissions` 用于按钮级别权限控制，不影响菜单显示
 - 403 页面在 Layout 内渲染，不会触发路由跳转
-- 调试时可在控制台搜索 `isForbidden check` 查看权限判断日志
+- 调试时可在控制台搜索 `isForbidden (menu check)` 或 `isForbidden (hidden page` 查看权限判断日志
 - **常见问题**：配置了 `noAuthRouteList` 但页面仍显示 403，需同时配置 `noPermissionRouteList`
 
 ## 相关文档
 
-- [微前端模式](./feature-微前端模式.md) - 路由和菜单解析
+- [路由与菜单解耦](./feature-路由与菜单解耦.md) - 路由注册与菜单导航数据源分离、双层权限详细说明
+- [微前端模式](./feature-微前端模式.md) - 微应用加载机制
 - [日志与常量](./arch-日志与常量.md) - 常量管理