generator-mico-cli 0.1.29 → 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

@@ -0,0 +1,420 @@
+# 菜单权限控制
+
+> 创建时间：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 组件：@mico-platform/ui (Result 组件)
+- 状态管理：Umi initialState
+
+### 权限控制流程
+
+```
+用户访问路由
+    │
+    ▼
+┌──────────────────────────────────────────────┐
+│  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 等静态路由）
+    │
+    ▼
+是否是超级用户？
+    ├── 是 → 允许访问所有页面
+    │
+    ▼
+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` 判断，集成 `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
+interface MenuFilterOptions {
+  /** 是否是超级用户 */
+  isSuperuser?: boolean | number;
+  /** 允许访问的菜单路径列表（白名单） */
+  sideMenus?: string[];
+}
+```
+
+### filterMenuItems
+
+```typescript
+/**
+ * 根据权限过滤菜单项（白名单逻辑）
+ */
+function filterMenuItems(
+  items: MenuItem[],
+  options?: MenuFilterOptions,
+  parentPath?: string,
+): MenuItem[];
+```
+
+### 用户信息相关字段
+
+```typescript
+interface IUserInfo {
+  is_superuser: boolean | number;
+  /** 允许访问的菜单路径列表 */
+  side_menus: string[];
+  /** 缺失的操作权限（用于按钮级别控制，非菜单） */
+  miss_permissions: string[];
+}
+```
+
+## 使用示例
+
+### 配置免认证+免权限路由
+
+```javascript
+// config/config.dev.ts
+window.__MICO_CONFIG__ = {
+  // 免认证路由（跳过 SSO 登录）
+  noAuthRouteList: [
+    '/',
+    '/subapp',
+    '/public/*', // 前缀匹配
+  ],
+  // 免权限校验路由（跳过菜单权限检查）
+  noPermissionRouteList: [
+    '/',
+    '/subapp',
+    '/settings', // 登录后的公共页面
+  ],
+  disableAuth: false,
+};
+```
+
+### 静态配置（代码中）
+
+```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'];
+```
+
+### 菜单过滤结果
+
+```
+原始菜单：
+├── 工作台           ✅ 精确匹配 "工作台"
+├── 列队管理         ✅ 前缀匹配 "列队管理.配置队列"
+│   └── 配置队列     ✅ 精确匹配 "列队管理.配置队列"
+├── 质量管理         ❌ 不在白名单
+│   └── 抽样检查     ❌ 不在白名单
+└── 权限管理         ❌ adminOnly=true，非超级用户不可见
+```
+
+### Layout 中的权限判断
+
+```tsx
+// layouts/index.tsx — 双层权限判断
+const isForbidden = useMemo(() => {
+  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 (menu check)` 或 `isForbidden (hidden page` 查看权限判断日志
+- **常见问题**：配置了 `noAuthRouteList` 但页面仍显示 403，需同时配置 `noPermissionRouteList`
+
+## 相关文档
+
+- [路由与菜单解耦](./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 白名单权限逻辑

package/generators/micro-react/templates/apps/layout/docs/fix-SSO/346/227/240/351/231/220/351/207/215/345/256/232/345/220/221.md

@@ -0,0 +1,88 @@
+# 修复 SSO 无限重定向循环
+
+> 创建时间：2026-03-12
+
+## 功能概述
+
+修复 SSO 登录流程中 `redirect_count` 防护机制被过早清除，导致 `fetchUserInfo` 返回 401 时可能触发无限 SSO 重定向循环的问题。
+
+## 问题分析
+
+### 原始流程（存在缺陷）
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 立即删除 redirect_count        ← 问题根因
+  → fetchUserInfo() 返回 401
+  → refreshAuthToken() 失败
+  → handleAuthFailureRedirect() 检查 redirect_count = 0（已被删除）
+  → 允许重定向 → 跳转 SSO
+  → SSO 自动登录回跳 → 重复以上流程 → 无限循环
+```
+
+### 根因
+
+`ensureSsoSession()` 在 ticket 换取 token 成功后**立即删除** URL 中的 `redirect_count` 参数，但后续的 `fetchUserInfo` 尚未执行。当 `fetchUserInfo` 返回 401 且 token 刷新失败时，`handleAuthFailureRedirect()` 因检测不到 `redirect_count` 而误判为首次重定向，触发循环。
+
+## 技术方案
+
+### 核心思路
+
+将 `redirect_count` 的清除时机从"SSO ticket 换 token 成功后"延后到"整个认证流程（SSO + fetchUserInfo）完全成功后"。
+
+### 修复后流程
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 保留 redirect_count              ← 修复点
+  → fetchUserInfo() 返回 401
+  → refreshAuthToken() 失败
+  → handleAuthFailureRedirect() 检查 redirect_count = 1
+  → 已达最大重定向次数 → 停止重定向 ✅
+```
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 保留 redirect_count
+  → fetchUserInfo() 成功
+  → clearRedirectCount() 清除 redirect_count ✅
+```
+
+## 文件清单
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+| --- | --- |
+| `src/common/request/sso.ts` | 移除 `ensureSsoSession` 中过早删除 `redirect_count` 的逻辑；新增 `clearRedirectCount()` 函数 |
+| `src/app.tsx` | 导入 `clearRedirectCount`，在 `fetchUserInfo` 成功后调用 |
+
+## API / 组件接口
+
+### clearRedirectCount
+
+```typescript
+export const clearRedirectCount = (): void
+```
+
+清除 URL 中的 `redirect_count` 参数。仅在整个认证流程完全成功后调用。
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| redirect_count 清除时机 | 延后到 fetchUserInfo 成功后 | 最小改动，不改变现有 URL 参数机制，仅调整调用时序 |
+| clearRedirectCount 放置位置 | `sso.ts` | 与 `handleAuthFailureRedirect` 同属 SSO 模块，保持内聚 |
+
+## 注意事项
+
+- `handleAuthFailureRedirect` 可能在 `request/index.ts`（refresh 失败时）和 `app.tsx`（fetchUserInfo 返回 null 时）被双重调用，但修复后两处检查到 `redirect_count >= 1` 均会停止重定向，不影响正确性
+- `redirect_count` 最大值为 1，即只允许一次自动 SSO 重定向尝试
+
+## 相关文档
+
+- [请求模块架构](./arch-请求模块.md)
+- [菜单权限控制](./feature-菜单权限控制.md)