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

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

@@ -1,58 +1,193 @@
 # 菜单权限控制
 
-> 创建时间：2026-01-24
+> 创建时间：2026-01-24 更新时间：2026-02-08
 
 ## 功能概述
 
 基于用户信息中的 `side_menus` 字段实现菜单和路由的白名单权限控制。非超级用户只能看到和访问 `side_menus` 中配置的菜单项，访问无权限路由时显示 403 页面。
 
+**v2 更新**：支持认证（Authentication）与授权（Authorization）分离配置，可独立控制"跳过 SSO 登录"和"跳过菜单权限校验"。
+
+## 核心概念
+
+### 认证 vs 授权
+
+| 概念 | 英文           | 作用                     | 配置项                  |
+| ---- | -------------- | ------------------------ | ----------------------- |
+| 认证 | Authentication | 确认用户身份（是否登录） | `noAuthRouteList`       |
+| 授权 | Authorization  | 确认用户权限（能否访问） | `noPermissionRouteList` |
+
+### 四种路由场景
+
+| 场景 | noAuthRouteList | noPermissionRouteList | accessControlEnabled | 示例 |
+| --- | --- | --- | --- | --- |
+| 公开页面 | ✅ | ✅ | `false` | 首页、活动页 |
+| 登录后公共页面 | ❌ | ✅ | - | 个人设置、帮助中心 |
+| 需要权限的页面 | ❌ | ❌ | `true` | 后台管理、业务功能 |
+| 登录页等特殊页面 | ✅ | ✅ | `false` | /login、/403 |
+
 ## 技术方案
 
 ### 技术栈
 
 - 框架：React 18 + @umijs/max
-- UI 组件：Arco Design (Result 组件)
+- UI 组件：@mico-platform/ui (Result 组件)
 - 状态管理：Umi initialState
 
-### 核心实现
+### 权限控制流程
 
-1. 用户信息接口返回 `side_menus` 字段（白名单）
-2. `filterMenuItems` 根据白名单过滤菜单项
-3. Layout 组件对比"所有路由"和"有权限路由"判断 403
-4. 无权限时在 Layout 内直接渲染 403 组件（无跳转）
+```
+用户访问路由
+    │
+    ▼
+┌──────────────────────────────────────────────┐
+│  1. SSO 认证检查 (app.tsx)                    │
+│     isNoAuthRoute(pathname)?                 │
+│     ├── 是 → 跳过 SSO                        │
+│     page.accessControlEnabled === false?     │
+│     ├── 是 → 跳过 SSO（PAGES 数据驱动）       │
+│     └── 否 → 执行 ensureSsoSession()          │
+└──────────────────────────────────────────────┘
+    │
+    ▼
+┌──────────────────────────────────────────┐
+│  2. 权限校验 (layouts/index.tsx)          │
+│     isNoPermissionRoute(pathname)?       │
+│     ├── 是 → 跳过权限校验                │
+│     └── 否 → 双层权限判断                │
+│              Tier 1: 页面在菜单中？       │
+│              ├── 是 → 沿用 sideMenus     │
+│              │        白名单逻辑          │
+│              └── 否 → Tier 2: 页面级权限  │
+│                       adminOnly / routeKey│
+│              详见：路由与菜单解耦文档      │
+└──────────────────────────────────────────┘
+    │
+    ▼
+┌──────────────────────────────────────────┐
+│  3. 菜单渲染 (menu/index.tsx)            │
+│     按 side_menus 过滤                   │
+│     每个菜单项独立检查 isNoPermissionRoute│
+│     ├── 匹配 → 该项始终显示              │
+│     └── 不匹配 → 按 sideMenus 白名单过滤 │
+└──────────────────────────────────────────┘
+    │
+    ▼
+┌──────────────────────────────────────────────┐
+│  4. 子应用加载 (MicroAppLoader)               │
+│     page.accessControlEnabled === false?     │
+│     ├── 是 → 直接加载（PAGES 数据驱动）       │
+│     isNoAuthRoute(pathname)?                 │
+│     ├── 是 → 直接加载（静态配置兜底）         │
+│     isNoPermissionRoute(pathname)?           │
+│     ├── 是 → 直接加载                        │
+│     └── 否 → 等待 currentUser                │
+└──────────────────────────────────────────────┘
+```
 
-### 权限判断逻辑
+### 权限判断逻辑（详细）
 
 ```
 用户访问 /some-path
-    ↓
+    │
+    ▼
+是否 disableAuth === true？
+    ├── 是 → 允许所有访问（调试模式）
+    │
+    ▼
+page.accessControlEnabled === false？
+    ├── 是 → 跳过 SSO 认证 + 跳过权限校验
+    │
+    ▼
+是否在 noPermissionRouteList 中？
+    ├── 是 → 允许访问，菜单按各项独立判断
+    │
+    ▼
+是否是非动态路由（不在 PAGES 中）？
+    ├── 是 → 交给 Umi 处理（404 等静态路由）
+    │
+    ▼
 是否是超级用户？
-    ├── 是 → 允许访问所有菜单
-    └── 否 → 检查 side_menus 白名单
-              ├── 精确匹配：menuPath === side_menus[i]
-              ├── 前缀匹配：side_menus[i].startsWith(menuPath + '.')
-              └── 都不匹配 → 禁止访问，显示 403
+    ├── 是 → 允许访问所有页面
+    │
+    ▼
+Tier 1: 页面在菜单中？
+    ├── 是 → 沿用菜单权限逻辑：
+    │        菜单项 adminOnly === true？
+    │        ├── 是 → 禁止访问
+    │        检查 side_menus 白名单
+    │        ├── 匹配 → 允许访问
+    │        └── 不匹配 → 显示 403
+    │
+    ▼
+Tier 2: 隐藏页面（不在菜单中）
+    adminOnly === true？
+    ├── 是 → 显示 403
+    accessControlEnabled === true？
+    ├── 是 → 检查 routeKey ∈ side_menus
+    │        ├── 匹配 → 允许访问
+    │        └── 不匹配 → 显示 403
+    └── 否 → 允许访问
 ```
 
 ## 文件清单
 
 ### 新增文件
 
-| 文件路径 | 说明 |
-|----------|------|
+| 文件路径                  | 说明               |
+| ------------------------- | ------------------ |
 | `src/pages/403/index.tsx` | 403 无权限页面组件 |
 
 ### 修改文件
 
 | 文件路径 | 修改内容 |
-|----------|----------|
+| --- | --- |
+| `src/common/menu/types.ts` | 新增 `noPermissionRouteList` 类型定义 |
+| `src/constants/index.ts` | 新增 `isNoPermissionRoute`、`getNoPermissionRouteList` 函数 |
 | `src/common/menu/parser.ts` | 新增 `filterMenuItems`、`isMenuAllowed` 等权限过滤函数 |
-| `src/layouts/index.tsx` | 新增 `isForbidden` 判断和 403 渲染逻辑 |
-| `src/layouts/components/menu/index.tsx` | 集成菜单过滤 |
+| `src/layouts/index.tsx` | 新增 `isForbidden` 判断，集成 `isNoPermissionRoute` |
+| `src/layouts/components/menu/index.tsx` | 集成菜单过滤，支持免权限校验路由 |
+| `src/components/MicroAppLoader/index.tsx` | 集成 `isNoPermissionRoute`，免权限路由直接加载 |
+| `src/app.tsx` | SSO 认证检查，使用 `isNoAuthRoute` |
 | `config/routes.ts` | 新增 `/403` 路由 |
 
 ## API / 组件接口
 
+### Window 配置
+
+```typescript
+interface Window {
+  __MICO_CONFIG__?: {
+    /**
+     * 免认证路由列表（跳过 SSO 登录）
+     * 支持精确匹配和前缀匹配（以 /* 结尾）
+     */
+    noAuthRouteList?: string[];
+    /**
+     * 免权限校验路由列表（跳过菜单权限检查）
+     * 支持精确匹配和前缀匹配（以 /* 结尾）
+     * 注意：如果同时需要跳过 SSO，需同时配置 noAuthRouteList
+     */
+    noPermissionRouteList?: string[];
+    /** 关闭权限控制（菜单全部显示，路由不校验权限） */
+    disableAuth?: boolean;
+  };
+}
+```
+
+### 路由判断函数
+
+```typescript
+// 判断是否为免认证路由（跳过 SSO）
+function isNoAuthRoute(pathname: string): boolean;
+
+// 判断是否为免权限校验路由（跳过菜单权限检查）
+function isNoPermissionRoute(pathname: string): boolean;
+
+// 判断是否关闭权限控制
+function isAuthDisabled(): boolean;
+```
+
 ### MenuFilterOptions
 
 ```typescript
@@ -77,26 +212,6 @@ function filterMenuItems(
 ): MenuItem[];
 ```
 
-**参数说明**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| items | MenuItem[] | 是 | 原始菜单数据 |
-| options | MenuFilterOptions | 否 | 过滤选项 |
-| parentPath | string | 否 | 父级路径（递归用） |
-
-### isRouteAllowed
-
-```typescript
-/**
- * 检查路由是否允许访问
- */
-function isRouteAllowed(
-  menuPath: string,
-  options?: MenuFilterOptions,
-): boolean;
-```
-
 ### 用户信息相关字段
 
 ```typescript
@@ -111,14 +226,42 @@ interface IUserInfo {
 
 ## 使用示例
 
-### 用户信息接口返回
+### 配置免认证+免权限路由
+
+```javascript
+// config/config.dev.ts
+window.__MICO_CONFIG__ = {
+  // 免认证路由（跳过 SSO 登录）
+  noAuthRouteList: [
+    '/',
+    '/subapp',
+    '/public/*', // 前缀匹配
+  ],
+  // 免权限校验路由（跳过菜单权限检查）
+  noPermissionRouteList: [
+    '/',
+    '/subapp',
+    '/settings', // 登录后的公共页面
+  ],
+  disableAuth: false,
+};
+```
+
+### 静态配置（代码中）
 
-```json
-{
-  "is_superuser": false,
-  "side_menus": ["列队管理.配置队列", "工作台"],
-  "miss_permissions": ["列队管理.配置队列.查看"]
-}
+```typescript
+// src/constants/index.ts
+
+// 静态免认证路由（始终生效）
+export const NO_AUTH_ROUTE_LIST: string[] = [
+  '/user/login',
+  '/user/register',
+  '/403',
+  '/404',
+];
+
+// 静态免权限校验路由（始终生效）
+export const NO_PERMISSION_ROUTE_LIST: string[] = ['/403', '/404'];
 ```
 
 ### 菜单过滤结果
@@ -130,46 +273,148 @@ interface IUserInfo {
 │   └── 配置队列     ✅ 精确匹配 "列队管理.配置队列"
 ├── 质量管理         ❌ 不在白名单
 │   └── 抽样检查     ❌ 不在白名单
-└── 权限管理         ❌ 硬编码禁止（非超级用户）
+└── 权限管理         ❌ adminOnly=true，非超级用户不可见
 ```
 
 ### Layout 中的权限判断
 
 ```tsx
-// layouts/index.tsx
+// layouts/index.tsx — 双层权限判断
 const isForbidden = useMemo(() => {
-  if (currentRoute) return false; // 在有权限的路由中找到了
-  const routeInAll = findRouteByPath(allRoutes, location.pathname);
-  return !!routeInAll; // 在所有路由中存在但无权限
-}, [currentRoute, allRoutes, location.pathname]);
-
-const renderContent = () => {
-  if (isForbidden) {
-    return <ForbiddenPage />;
+  if (isAuthDisabled()) return false;
+  if (isNoPermissionRoute(location.pathname)) return false;
+  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 中的认证判断
+
+```tsx
+// components/MicroAppLoader/index.tsx
+const isAuthReady =
+  isAuthDisabled() ||
+  isPageAuthFree(location.pathname) ||
+  isNoAuthRoute(location.pathname) ||
+  isNoPermissionRoute(location.pathname) ||
+  !!initialState?.currentUser;
+
+// 未准备好时不加载子应用
+if (!isAuthReady) {
+  return; // 继续等待
+}
+```
+
+判断优先级：
+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 不变，用户体验更好，便于分享链接 |
 | 父级菜单显示 | 前缀匹配 | 子菜单有权限时，父级菜单需要作为容器显示 |
 | 超级用户 | 跳过所有检查 | 管理员需要完整访问权限 |
-| 权限管理菜单 | 硬编码禁止 | 非超级用户不应看到权限管理入口 |
+| 免权限路由的菜单 | 按菜单项独立判断 | 每个菜单项根据自身路由是否匹配 noPermissionRouteList 独立决定显示，避免菜单随当前页面变化 |
+| 免认证路由的子应用 | 直接加载 | 不等待 currentUser，免认证路由本身不需要登录 |
+| 免权限路由的子应用 | 直接加载 | 不等待 currentUser，避免加载卡住 |
+| 静态路由不受权限控制 | 默认允许访问 | 见下方"静态路由与动态路由"说明 |
+| adminOnly 判断 | 读取菜单数据字段 | 替代硬编码菜单名称匹配，由后端数据驱动，支持多语言且无需前端维护 |
+
+## 静态路由与动态路由
+
+### 定义
+
+| 类型 | 来源 | 示例 |
+| --- | --- | --- |
+| **静态路由** | 代码中定义 (`config/routes.ts`) | `/`, `/403`, `/404`, `/user/login` |
+| **动态路由** | 后端页面配置 (`window.__MICO_PAGES__`，降级 `window.__MICO_MENUS__`) | `/queue-management`, `/quality-check` |
+
+### 权限控制范围
+
+**当前设计：权限控制仅作用于动态路由，静态路由默认允许访问。**
+
+```
+权限判断逻辑（isForbidden）：
+1. 检查 isAuthDisabled() → 关闭则全部允许
+2. 检查 isNoPermissionRoute() → 在免权限列表中则允许
+3. 检查 currentRoute（PAGES 中的路由）→ 不存在则非动态路由，交给 Umi
+4. 检查 isSuperuserUser() → 超级用户放行
+5. Tier 1: 在菜单中 → 检查 allowedMenuRoutes
+6. Tier 2: 不在菜单（隐藏页面）→ 检查 adminOnly + accessControlEnabled + routeKey
+7. 都不匹配 → 放行
+```
+
+### 设计理由
+
+1. **职责分离**：静态路由是框架层面的基础设施（登录、错误页），动态路由才是业务功能
+2. **简化配置**：不需要额外配置哪些静态路由需要权限，减少出错概率
+3. **向后兼容**：现有部署无需任何改动
+4. **复杂度控制**：避免引入更多配置项增加理解成本
+
+### 影响
+
+当用户 `is_superuser=false` 且 `side_menus=[]` 时：
+
+| 路由 | 结果 | 原因 |
+| --- | --- | --- |
+| `/` (Home) | ✅ 正常显示 | 静态路由，不受权限控制 |
+| `/403` | ✅ 正常显示 | 在 `noPermissionRouteList` 中 |
+| `/404` | ✅ 正常显示 | 在 `noPermissionRouteList` 中 |
+| `/user/login` | ✅ 正常显示 | 静态路由 + 在 `noAuthRouteList` 中 |
+| `/queue-management` | ❌ 显示 403 | 动态路由，无权限 |
+
+### 如需控制静态路由
+
+如果业务上需要让某个静态路由（如 `/`）也受权限控制，有以下方案：
+
+1. **方案 A**：将该路由从静态路由改为动态路由（通过菜单配置）
+2. **方案 B**：在对应页面组件内部自行判断权限并重定向
+3. **方案 C**：扩展 `isForbidden` 逻辑（需额外开发，当前未实现）
 
 ## 注意事项
 
+- `noAuthRouteList` 和 `noPermissionRouteList` 是独立的，需要根据场景分别配置
+- 两个列表都支持 `/*` 后缀进行前缀匹配
 - `side_menus` 为空时，非超级用户没有任何菜单权限
 - `side_menus` 格式为菜单路径，如 `"列队管理.配置队列"`
 - `miss_permissions` 用于按钮级别权限控制，不影响菜单显示
 - 403 页面在 Layout 内渲染，不会触发路由跳转
-- 调试时可在控制台搜索 `isForbidden check` 查看权限判断日志
+- 调试时可在控制台搜索 `isForbidden (menu check)` 或 `isForbidden (hidden page` 查看权限判断日志
+- **常见问题**：配置了 `noAuthRouteList` 但页面仍显示 403，需同时配置 `noPermissionRouteList`
 
 ## 相关文档
 
-- [微前端模式](./feature-微前端模式.md) - 路由和菜单解析
-- [用户信息接口](./feature-用户信息接口.md) - 用户数据结构
+- [路由与菜单解耦](./feature-路由与菜单解耦.md) - 路由注册与菜单导航数据源分离、双层权限详细说明
+- [微前端模式](./feature-微前端模式.md) - 微应用加载机制
+- [日志与常量](./arch-日志与常量.md) - 常量管理

package/generators/micro-react/templates/apps/layout/docs/feature-/350/267/257/347/224/261/344/270/216/350/217/234/345/215/225/350/247/243/350/200/246.md

@@ -0,0 +1,179 @@
+# 路由与菜单解耦
+
+> 创建时间：2026-02-25
+
+## 功能概述
+
+将动态路由注册与菜单导航的数据源解耦。路由注册消费 `window.__MICO_PAGES__`（页面列表），菜单栏消费 `window.__MICO_MENUS__`（菜单树）。两者独立运作，权限通过菜单交叉引用 + 页面级兜底的双层策略控制。
+
+## 技术方案
+
+### 技术栈
+
+- 框架：React 18 + @umijs/max
+- 微前端：qiankun
+- 状态管理：Umi initialState
+
+### 数据源关系
+
+```
+__MICO_PAGES__ (扁平列表，所有页面)
+  ├── 菜单中的页面（一定能在 __MICO_MENUS__ 中找到对应菜单项）
+  └── 隐藏页面（不在菜单中显示，但路由可访问）
+
+__MICO_MENUS__ (菜单树，用于导航)
+  └── page 字段 → 引用 __MICO_PAGES__ 中的某个页面
+```
+
+### 数据流
+
+```
+Before:
+  patchClientRoutes  ← extractRoutes(MENUS)
+  layouts 权限校验    ← extractRoutes(MENUS) + filterMenuItems(MENUS)
+  菜单渲染           ← parseMenuItems(MENUS)
+
+After:
+  patchClientRoutes  ← getDynamicRoutes() → PAGES 优先，降级 MENUS
+  layouts 权限校验    ← getDynamicRoutes() + extractRoutes(MENUS) + filterMenuItems(MENUS)
+  菜单渲染           ← parseMenuItems(MENUS)  ← 不变
+```
+
+### 权限控制流程
+
+```
+用户访问路由
+    │
+    ▼
+disableAuth / noPermissionRoute / superuser？
+    ├── 是 → 放行
+    │
+    ▼
+page.accessControlEnabled === false？
+    ├── 是 → 跳过 SSO 认证 + 跳过权限校验（公开页面）
+    │
+    ▼
+非动态路由（不在 PAGES 中）？
+    ├── 是 → 交给 Umi 处理（404 等）
+    │
+    ▼
+┌─────────────────────────────────────────────┐
+│  Tier 1: 菜单权限交叉引用                    │
+│  页面在 __MICO_MENUS__ 中？                   │
+│    ├── 是 → 沿用 sideMenus 白名单逻辑        │
+│    │        在 allowedMenuRoutes 中？          │
+│    │        ├── 是 → 放行                     │
+│    │        └── 否 → 403                      │
+│    └── 否 → 进入 Tier 2                       │
+├─────────────────────────────────────────────┤
+│  Tier 2: 隐藏页面级权限                       │
+│  （仅 PAGES 数据可用时生效）                   │
+│  adminOnly: true        → 403                │
+│  accessControlEnabled: true                  │
+│    → routeKey ∈ sideMenus ? 放行 : 403       │
+│  其他                    → 放行               │
+└─────────────────────────────────────────────┘
+```
+
+### 降级策略
+
+当 `window.__MICO_PAGES__` 未注入时（如旧版部署），`getDynamicRoutes()` 自动降级到从 `window.__MICO_MENUS__` 提取路由，行为与改动前完全一致。
+
+```
+getDynamicRoutes():
+  hasWindowPages() ?
+    ├── 是 → extractRoutesFromPages(PAGES)  ← 新逻辑
+    └── 否 → extractRoutes(MENUS)           ← 旧逻辑，向后兼容
+```
+
+## 文件清单
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+| --- | --- |
+| `src/common/menu/types.ts` | `PageConfig` 新增 `accessControlEnabled`、`routeKey` 字段；新增 `PublicPageItem` 类型（`Omit<PageConfig, ...>`）；Window 声明新增 `__MICO_PAGES__` |
+| `src/common/menu/parser.ts` | 新增 `getWindowPages`、`hasWindowPages`、`extractRoutesFromPages`、`getDynamicRoutes`、`findPageByPath` 函数；导出 `isSuperuserUser` |
+| `src/app.tsx` | `patchClientRoutes` 改为调用 `getDynamicRoutes()` |
+| `src/layouts/index.tsx` | 路由匹配改用 `allPageRoutes`；权限判断改为双层逻辑（菜单交叉引用 + 隐藏页面级兜底） |
+
+### 未修改文件
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/layouts/components/menu/index.tsx` | 菜单渲染逻辑不变，继续消费 `__MICO_MENUS__` |
+
+## API / 组件接口
+
+### PublicPageItem
+
+```typescript
+type PublicPageItem = Omit<
+  PageConfig,
+  'workspaceSubdomain' | 'publishedBy' | 'versions' | 'createdAt' | 'updatedAt'
+>;
+```
+
+`PageConfig` 新增字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `accessControlEnabled` | `boolean` | 是否开启访问控制。`false` 时跳过 SSO 认证和权限校验（公开页面）；`true` 时需要登录且通过 `routeKey` 校验权限 |
+| `routeKey` | `string \| null` | 路由权限标识（用于匹配 sideMenus） |
+
+### 页面数据函数
+
+```typescript
+/** 获取 window.__MICO_PAGES__ */
+function getWindowPages(): PublicPageItem[];
+
+/** 判断页面数据是否可用 */
+function hasWindowPages(): boolean;
+
+/** 从页面数据提取路由配置 */
+function extractRoutesFromPages(pages: PublicPageItem[]): ParsedRoute[];
+
+/** 获取动态路由（PAGES 优先，降级 MENUS） */
+function getDynamicRoutes(): ParsedRoute[];
+
+/** 根据路径查找页面配置（精确匹配 + 通配符） */
+function findPageByPath(pages: PublicPageItem[], pathname: string): PublicPageItem | undefined;
+```
+
+### Window 全局变量
+
+```typescript
+interface Window {
+  /** 页面列表 — 动态路由注册的数据源 */
+  __MICO_PAGES__?: PublicPageItem[];
+  /** 菜单树 — 菜单导航的数据源 */
+  __MICO_MENUS__?: MenuItem[];
+}
+```
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| 路由数据源 | `__MICO_PAGES__` 独立于菜单 | 页面和菜单是不同维度：页面定义"有什么路由"，菜单定义"导航怎么组织"；解耦后支持隐藏页面 |
+| 权限方案 | 菜单交叉引用 + 页面级兜底 | 菜单中的页面复用现有 sideMenus 白名单逻辑，改动最小；隐藏页面用 adminOnly + accessControlEnabled 兜底 |
+| 降级策略 | `getDynamicRoutes()` 自动降级 | `__MICO_PAGES__` 未注入时回退到旧行为，零配置向后兼容 |
+| PublicPageItem 定义 | `Omit<PageConfig, ...>` 派生 | 保持与 PageConfig 的类型继承关系，避免字段重复定义和类型漂移 |
+| accessControlEnabled 语义 | `false` = 公开页面（跳过认证+授权），`true` = 需要权限检查 | 一个字段统一控制 SSO 认证、权限校验、子应用加载等待，减少配置冗余 |
+| 隐藏页面权限 | 先 adminOnly 再 accessControlEnabled | adminOnly 是硬拦截，accessControlEnabled + routeKey 提供用户级粒度控制 |
+
+## 已知限制与待改进
+
+- `routeKey` 当前复用 `sideMenus` 做权限匹配，后续可能独立为专门的权限字段
+- 隐藏页面的权限控制依赖 `routeKey` 存在于 `sideMenus` 中，需要后端在下发用户权限时包含隐藏页面的 `routeKey`
+
+## 注意事项
+
+- `__MICO_PAGES__` 只包含用户在后台配置的微应用页面，404/403 等静态页面不在其中
+- `__MICO_MENUS__` 中菜单项的 `page` 字段引用的是 `__MICO_PAGES__` 中的某个页面
+- 调试时可在控制台搜索 `isForbidden (menu check)` 或 `isForbidden (hidden page` 查看权限判断日志
+
+## 相关文档
+
+- [微前端模式](./feature-微前端模式.md) - 微应用加载机制
+- [菜单权限控制](./feature-菜单权限控制.md) - sideMenus 白名单权限逻辑