generator-mico-cli 0.2.28 → 0.2.29

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,10 +1,10 @@
 # 菜单权限控制
 
-> 创建时间：2026-01-24 更新时间：2026-02-08
+> 创建时间：2026-01-24 更新时间：2026-03-27（同步 `getMenuPage`：pageId 优先，path 兜底）
 
 ## 功能概述
 
-基于用户信息中的 `side_menus` 字段实现菜单和路由的白名单权限控制。非超级用户只能看到和访问 `side_menus` 中配置的菜单项，访问无权限路由时显示 403 页面。
+基于用户信息中的 **`menu_perms`**（菜单权限 code 数组，与 OpenAPI 8 `GET /user/info/` 一致）实现菜单和路由权限。非超级用户仅当 **`menu_perms` 包含对应 code** 时可见菜单项、可访问受控动态路由（`accessControlEnabled && routeKey` 时要求 `routeKey ∈ menu_perms`）。访问无权限路由时显示 403 页面。
 
 **v2 更新**：支持认证（Authentication）与授权（Authorization）分离配置，可独立控制"跳过 SSO 登录"和"跳过菜单权限校验"。
 
@@ -54,22 +54,21 @@
 │  2. 权限校验 (layouts/index.tsx)          │
 │     isNoPermissionRoute(pathname)?       │
 │     ├── 是 → 跳过权限校验                │
-│     └── 否 → 双层权限判断                │
-│              Tier 1: 页面在菜单中？       │
-│              ├── 是 → 沿用 sideMenus     │
-│              │        白名单逻辑          │
-│              └── 否 → Tier 2: 页面级权限  │
-│                       adminOnly / routeKey│
+│     └── 否 → PAGES 页面：adminOnly /      │
+│              accessControlEnabled+routeKey│
+│              与 menu_perms；无 page 时    │
+│              按菜单过滤结果兜底           │
 │              详见：路由与菜单解耦文档      │
 └──────────────────────────────────────────┘
     │
     ▼
 ┌──────────────────────────────────────────┐
 │  3. 菜单渲染 (menu/index.tsx)            │
-│     按 side_menus 过滤                   │
+│     按 menu_perms 过滤（菜单项 code       │
+│     与关联页 routeKey / nameKey 一致）    │
 │     每个菜单项独立检查 isNoPermissionRoute│
 │     ├── 匹配 → 该项始终显示              │
-│     └── 不匹配 → 按 sideMenus 白名单过滤 │
+│     └── 不匹配 → code ∈ menu_perms       │
 └──────────────────────────────────────────┘
     │
     ▼
@@ -111,23 +110,20 @@ page.accessControlEnabled === false？
     ├── 是 → 允许访问所有页面
     │
     ▼
-Tier 1: 页面在菜单中？
-    ├── 是 → 沿用菜单权限逻辑：
-    │        菜单项 adminOnly === true？
-    │        ├── 是 → 禁止访问
-    │        检查 side_menus 白名单
-    │        ├── 匹配 → 允许访问
-    │        └── 不匹配 → 显示 403
+能关联到 PAGES 页面配置？
+    ├── 是 → adminOnly === true？
+    │        ├── 是 → 403
+    │        accessControlEnabled === true？
+    │        ├── 是 → routeKey ∈ menu_perms？
+    │        │        ├── 是 → 允许
+    │        │        └── 否 → 403
+    │        └── 否 → 允许
     │
     ▼
-Tier 2: 隐藏页面（不在菜单中）
-    adminOnly === true？
-    ├── 是 → 显示 403
-    accessControlEnabled === true？
-    ├── 是 → 检查 routeKey ∈ side_menus
-    │        ├── 匹配 → 允许访问
-    │        └── 不匹配 → 显示 403
-    └── 否 → 允许访问
+路径仅在菜单路由中、无 page 元数据
+    └── 在 filterMenuItems 后的路由集中？
+         ├── 是 → 允许
+         └── 否 → 403
 ```
 
 ## 文件清单
@@ -144,7 +140,8 @@ Tier 2: 隐藏页面（不在菜单中）
 | --- | --- |
 | `src/common/menu/types.ts` | 新增 `noPermissionRouteList` 类型定义 |
 | `src/constants/index.ts` | 新增 `isNoPermissionRoute`、`getNoPermissionRouteList` 函数 |
-| `src/common/menu/parser.ts` | 新增 `filterMenuItems`、`isMenuAllowed` 等权限过滤函数 |
+| `src/common/portal-data.ts` | `getMenuPage`：pageId 优先，无匹配再用 path 与页面 route |
+| `src/common/menu/parser.ts` | `filterMenuItems`、`getMenuItemPermCode` 等，消费 `getMenuPage` |
 | `src/layouts/index.tsx` | 新增 `isForbidden` 判断，集成 `isNoPermissionRoute` |
 | `src/layouts/components/menu/index.tsx` | 集成菜单过滤，支持免权限校验路由 |
 | `src/components/MicroAppLoader/index.tsx` | 集成 `isNoPermissionRoute`，免权限路由直接加载 |
@@ -194,33 +191,43 @@ function isAuthDisabled(): boolean;
 interface MenuFilterOptions {
   /** 是否是超级用户 */
   isSuperuser?: boolean | number;
-  /** 允许访问的菜单路径列表（白名单） */
-  sideMenus?: string[];
+  /** 用户拥有的菜单权限 code（与页面 routeKey、菜单项一致） */
+  menuPerms?: string[];
 }
 ```
 
+### 菜单项如何关联到页面（与 `routeKey` / `menu_perms`）
+
+`page` 类型菜单项的权限 code 来自关联页的 **`routeKey`**（当该页 `accessControlEnabled && routeKey` 时）。关联页由 **`getMenuPage(item)`**（`src/common/portal-data.ts`）解析：
+
+1. **`pageId`**：在 `__MICO_PAGES__` 中按 `id` 查找，**命中则使用该页面**（与菜单 `path` 是否一致无关）。
+2. **`path` + 页面 `route`**：上一步无结果时，用 `findPageByPath` 将菜单 `path` 与页面 `route` 匹配（精确 + `/*` 通配）。
+
+详见 [路由与菜单解耦](./feature-路由与菜单解耦.md) 文档内「菜单项关联页面（getMenuPage）」小节。
+
 ### filterMenuItems
 
 ```typescript
 /**
- * 根据权限过滤菜单项（白名单逻辑）
+ * 根据 menu_perms 过滤菜单项
+ * - page：关联页由 getMenuPage → routeKey（需校验时）；link：nameKey
  */
-function filterMenuItems(
-  items: MenuItem[],
-  options?: MenuFilterOptions,
-  parentPath?: string,
-): MenuItem[];
+function filterMenuItems(items: MenuItem[], options?: MenuFilterOptions): MenuItem[];
 ```
 
 ### 用户信息相关字段
 
 ```typescript
 interface IUserInfo {
-  is_superuser: boolean | number;
-  /** 允许访问的菜单路径列表 */
-  side_menus: string[];
-  /** 缺失的操作权限（用于按钮级别控制，非菜单） */
-  miss_permissions: string[];
+  is_superuser: boolean;
+  menu_perms: string[];
+  button_perms: string[];
+  app_perms: string[];
+  region_perms: string[];
+  name: string;
+  user_name: string;
+  username: string;
+  // …见 src/common/auth/type.ts IUserInfo / IUserInfoApiData
 }
 ```
 
@@ -264,43 +271,41 @@ export const NO_AUTH_ROUTE_LIST: string[] = [
 export const NO_PERMISSION_ROUTE_LIST: string[] = ['/403', '/404'];
 ```
 
-### 菜单过滤结果
+### 菜单过滤结果（示意）
 
 ```
-原始菜单：
-├── 工作台           ✅ 精确匹配 "工作台"
-├── 列队管理         ✅ 前缀匹配 "列队管理.配置队列"
-│   └── 配置队列     ✅ 精确匹配 "列队管理.配置队列"
-├── 质量管理         ❌ 不在白名单
-│   └── 抽样检查     ❌ 不在白名单
-└── 权限管理         ❌ adminOnly=true，非超级用户不可见
+menu_perms 含 code "a"、"b.c"
+├── 页面菜单（routeKey=a）     ✅
+├── 页面菜单（routeKey 不在列表） ❌
+├── 分组（仅容器，有可见子项）  ✅ 作为父级保留
+└── adminOnly 菜单              ❌ 非超管
 ```
 
 ### Layout 中的权限判断
 
 ```tsx
-// layouts/index.tsx — 双层权限判断
+// layouts/index.tsx — 以 PAGES + menu_perms 为主，无 page 时菜单路由兜底
 const isForbidden = useMemo(() => {
   if (isAuthDisabled()) return false;
   if (isNoPermissionRoute(location.pathname)) return false;
-  if (!currentRoute) return false; // 非动态路由
+  if (!currentRoute) return false;
   if (isSuperuserUser(currentUser?.is_superuser)) return false;
 
-  // Tier 1: 菜单权限交叉引用
+  const page =
+    currentRoute.pageConfig ??
+    (hasPages() ? findPageByPath(getPages(), location.pathname) : undefined);
+
+  if (page) {
+    if (page.adminOnly) return true;
+    if (!page.accessControlEnabled) return false;
+    const menuPerms = currentUser?.menu_perms || [];
+    return !page.routeKey || !menuPerms.includes(page.routeKey);
+  }
+
   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;
 }, [...]);
 ```
@@ -323,6 +328,7 @@ if (!isAuthReady) {
 ```
 
 判断优先级：
+
 1. `isAuthDisabled()` — 全局关闭权限，直接放行
 2. `isPageAuthFree` — **PAGES 数据驱动**，页面 `accessControlEnabled === false` 时跳过认证和权限校验
 3. `isNoAuthRoute()` — 静态配置兜底，免认证路由（PAGES 未注入时的降级保护）
@@ -341,9 +347,9 @@ if (!isAuthReady) {
 | --- | --- | --- |
 | accessControlEnabled 统一控制 | `false` 同时跳过认证和授权 | PAGES 数据驱动，一个字段即可标记公开页面，无需重复配置 noAuthRouteList |
 | 认证与授权分离 | 两个独立配置项 | 不同场景需要不同组合，如"需要登录但不需要权限"的个人设置页 |
-| 权限模型 | 白名单 (`side_menus`) | 后端返回的 `side_menus` 是允许列表，比黑名单更安全 |
+| 权限模型 | 白名单 (`menu_perms`) | 后端返回的 code 列表为允许集合；与 `routeKey` / 菜单项一一对应 |
 | 403 处理 | 原地渲染组件 | 保持 URL 不变，用户体验更好，便于分享链接 |
-| 父级菜单显示 | 前缀匹配 | 子菜单有权限时，父级菜单需要作为容器显示 |
+| 父级菜单显示 | 子项驱动 | `group` 无独立 code，有可见子项时保留为容器 |
 | 超级用户 | 跳过所有检查 | 管理员需要完整访问权限 |
 | 免权限路由的菜单 | 按菜单项独立判断 | 每个菜单项根据自身路由是否匹配 noPermissionRouteList 独立决定显示，避免菜单随当前页面变化 |
 | 免认证路由的子应用 | 直接加载 | 不等待 currentUser，免认证路由本身不需要登录 |
@@ -370,9 +376,9 @@ if (!isAuthReady) {
 2. 检查 isNoPermissionRoute() → 在免权限列表中则允许
 3. 检查 currentRoute（PAGES 中的路由）→ 不存在则非动态路由，交给 Umi
 4. 检查 isSuperuserUser() → 超级用户放行
-5. Tier 1: 在菜单中 → 检查 allowedMenuRoutes
-6. Tier 2: 不在菜单（隐藏页面）→ 检查 adminOnly + accessControlEnabled + routeKey
-7. 都不匹配 → 放行
+5. 有 PAGES 页面元数据 → adminOnly / accessControlEnabled + routeKey ∈ menu_perms
+6. 无页面元数据但在菜单路由中 → 检查 allowedMenuRoutes（已按 menu_perms 过滤）
+7. 其他 → 放行
 ```
 
 ### 设计理由
@@ -384,15 +390,15 @@ if (!isAuthReady) {
 
 ### 影响
 
-当用户 `is_superuser=false` 且 `side_menus=[]` 时：
+当用户 `is_superuser=false` 且 `menu_perms=[]` 时：
 
-| 路由 | 结果 | 原因 |
-| --- | --- | --- |
-| `/` (Home) | ✅ 正常显示 | 静态路由，不受权限控制 |
-| `/403` | ✅ 正常显示 | 在 `noPermissionRouteList` 中 |
-| `/404` | ✅ 正常显示 | 在 `noPermissionRouteList` 中 |
-| `/user/login` | ✅ 正常显示 | 静态路由 + 在 `noAuthRouteList` 中 |
-| `/queue-management` | ❌ 显示 403 | 动态路由，无权限 |
+| 路由                | 结果        | 原因                               |
+| ------------------- | ----------- | ---------------------------------- |
+| `/` (Home)          | ✅ 正常显示 | 静态路由，不受权限控制             |
+| `/403`              | ✅ 正常显示 | 在 `noPermissionRouteList` 中      |
+| `/404`              | ✅ 正常显示 | 在 `noPermissionRouteList` 中      |
+| `/user/login`       | ✅ 正常显示 | 静态路由 + 在 `noAuthRouteList` 中 |
+| `/queue-management` | ❌ 显示 403 | 动态路由，无权限                   |
 
 ### 如需控制静态路由
 
@@ -406,11 +412,11 @@ if (!isAuthReady) {
 
 - `noAuthRouteList` 和 `noPermissionRouteList` 是独立的，需要根据场景分别配置
 - 两个列表都支持 `/*` 后缀进行前缀匹配
-- `side_menus` 为空时，非超级用户没有任何菜单权限
-- `side_menus` 格式为菜单路径，如 `"列队管理.配置队列"`
-- `miss_permissions` 用于按钮级别权限控制，不影响菜单显示
+- `menu_perms` 为空时，非超级用户没有任何菜单权限（`page`/`link` 项）
+- 菜单项权限 code 与页面 `routeKey` 一致；`page` 类型先通过 **`getMenuPage`** 得到关联页再取 `routeKey`，否则回退 `nameKey`（link）
+- `button_perms` 可用于按钮级权限（layout 侧栏不直接消费）
 - 403 页面在 Layout 内渲染，不会触发路由跳转
-- 调试时可在控制台搜索 `isForbidden (menu check)` 或 `isForbidden (hidden page` 查看权限判断日志
+- 调试时可在控制台过滤 `routePermission` 查看结构化权限日志（详见 [路由权限日志](./feature-路由权限日志.md)）
 - **常见问题**：配置了 `noAuthRouteList` 但页面仍显示 403，需同时配置 `noPermissionRouteList`
 
 ## 相关文档

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

@@ -1,10 +1,10 @@
 # 路由与菜单解耦
 
-> 创建时间：2026-02-25
+> 创建时间：2026-02-25 更新时间：2026-03-27
 
 ## 功能概述
 
-将动态路由注册与菜单导航的数据源解耦。路由注册消费 `window.__MICO_PAGES__`（页面列表），菜单栏消费 `window.__MICO_MENUS__`（菜单树）。两者独立运作，权限通过菜单交叉引用 + 页面级兜底的双层策略控制。
+将动态路由注册与菜单导航的数据源解耦。路由注册消费 `window.__MICO_PAGES__`（页面列表），菜单栏消费 `window.__MICO_MENUS__`（菜单树）。两者独立运作，**路由与侧栏权限**统一以用户信息中的 **`menu_perms`（菜单 code 列表）** 为准，与页面 **`routeKey`**、菜单项权限 code **一一对应**；无页面元数据时仍可按「菜单中是否可见」兜底。
 
 ## 技术方案
 
@@ -22,9 +22,20 @@ __MICO_PAGES__ (扁平列表，所有页面)
   └── 隐藏页面（不在菜单中显示，但路由可访问）
 
 __MICO_MENUS__ (菜单树，用于导航)
-  └── page 字段 → 引用 __MICO_PAGES__ 中的某个页面
+  └── `page` 类型项通过 pageId / path 关联到 __MICO_PAGES__（见下方「菜单项关联页面」）
 ```
 
+### 菜单项关联页面（`getMenuPage`）
+
+侧栏过滤、从菜单树提取路由（`extractRoutes`）、`routeKey` / `menu_perms` 等需要「菜单项 → 页面配置」时，统一由 `src/common/portal-data.ts` 的 **`getMenuPage(item)`** 解析：
+
+| 顺序 | 规则 | 说明 |
+| --- | --- | --- |
+| 1 | **`pageId` → `getPageById`** | 菜单项带 `pageId` 且在 `__MICO_PAGES__` 中存在对应 `id` 时，**优先使用该页面** |
+| 2 | **`path` + `findPageByPath`** | 上一步无结果时（无 `pageId`、或 id 在列表中不存在），用菜单 **`path`** 与页面 **`route`** 匹配（精确 + 最长前缀 `/*`），与路由侧解析规则一致 |
+
+仅 `type === 'page'` 的菜单项会走上述逻辑；`findPageByPath` 仅匹配 **`enabled === true`** 的页面。
+
 ### 数据流
 
 ```
@@ -35,7 +46,7 @@ Before:
 
 After:
   patchClientRoutes  ← getDynamicRoutes() → PAGES 优先，降级 MENUS
-  layouts 权限校验    ← getDynamicRoutes() + extractRoutes(MENUS) + filterMenuItems(MENUS)
+  layouts 权限校验    ← PAGES 上 routeKey ∈ menu_perms；无 page 时 allowedMenuRoutes 兜底
   菜单渲染           ← parseMenuItems(MENUS)  ← 不变
 ```
 
@@ -53,26 +64,22 @@ page.accessControlEnabled === false？
     ├── 是 → 跳过 SSO 认证 + 跳过权限校验（公开页面）
     │
     ▼
-非动态路由（不在 PAGES 中）？
+非动态路由（currentRoute 不在 PAGES 动态列表中）？
     ├── 是 → 交给 Umi 处理（404 等）
     │
     ▼
-┌─────────────────────────────────────────────┐
-│  Tier 1: 菜单权限交叉引用                    │
-│  页面在 __MICO_MENUS__ 中？                   │
-│    ├── 是 → 沿用 sideMenus 白名单逻辑        │
-│    │        在 allowedMenuRoutes 中？          │
-│    │        ├── 是 → 放行                     │
-│    │        └── 否 → 403                      │
-│    └── 否 → 进入 Tier 2                       │
-├─────────────────────────────────────────────┤
-│  Tier 2: 隐藏页面级权限                       │
-│  （仅 PAGES 数据可用时生效）                   │
-│  adminOnly: true        → 403                │
-│  accessControlEnabled: true                  │
-│    → routeKey ∈ sideMenus ? 放行 : 403       │
-│  其他                    → 放行               │
-└─────────────────────────────────────────────┘
+能解析到 PAGES 中的页面配置？
+    ├── 是 → adminOnly → 403
+    │        accessControlEnabled && routeKey
+    │          → routeKey ∈ menu_perms ? 放行 : 403
+    │        其他 → 放行
+    │
+    ▼
+路径仅在菜单路由中出现（无 page 元数据）？
+    ├── 是 → 在 filterMenuItems(menu_perms) 后的 allowedMenuRoutes 中？
+    │        ├── 是 → 放行
+    │        └── 否 → 403
+    └── 否 → 放行（非本逻辑覆盖）
 ```
 
 ### 降级策略
@@ -93,9 +100,10 @@ getDynamicRoutes():
 | 文件路径 | 修改内容 |
 | --- | --- |
 | `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/common/portal-data.ts` | `findPageByPath`、`getMenuPage`（pageId 优先，其次 path 匹配页面 route） |
+| `src/common/menu/parser.ts` | `extractRoutesFromPages`、`getDynamicRoutes`；从 portal-data 再导出 `findPageByPath`；菜单过滤与 `extractRoutes` 消费 `getMenuPage` |
 | `src/app.tsx` | `patchClientRoutes` 改为调用 `getDynamicRoutes()` |
-| `src/layouts/index.tsx` | 路由匹配改用 `allPageRoutes`；权限判断改为双层逻辑（菜单交叉引用 + 隐藏页面级兜底） |
+| `src/layouts/index.tsx` | 路由匹配 `allPageRoutes`；权限以 `menu_perms` + `routeKey` 为主，无 page 时菜单路由兜底 |
 
 ### 未修改文件
 
@@ -119,16 +127,19 @@ type PublicPageItem = Omit<
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | `accessControlEnabled` | `boolean` | 是否开启访问控制。`false` 时跳过 SSO 认证和权限校验（公开页面）；`true` 时需要登录且通过 `routeKey` 校验权限 |
-| `routeKey` | `string \| null` | 路由权限标识（用于匹配 sideMenus） |
+| `routeKey` | `string \| null` | 路由权限标识，与用户信息 `menu_perms`、菜单项权限 code 一致 |
 
-### 页面数据函数
+### 页面数据函数（`portal-data.ts` / `parser.ts`）
 
 ```typescript
 /** 获取 window.__MICO_PAGES__ */
-function getWindowPages(): PublicPageItem[];
+function getPages(): PublicPageItem[];
 
 /** 判断页面数据是否可用 */
-function hasWindowPages(): boolean;
+function hasPages(): boolean;
+
+/** 菜单项 → 关联页面：pageId 优先，无匹配再用 path 与页面 route 匹配 */
+function getMenuPage(item: MenuItem): PublicPageItem | undefined;
 
 /** 从页面数据提取路由配置 */
 function extractRoutesFromPages(pages: PublicPageItem[]): ParsedRoute[];
@@ -136,8 +147,11 @@ function extractRoutesFromPages(pages: PublicPageItem[]): ParsedRoute[];
 /** 获取动态路由（PAGES 优先，降级 MENUS） */
 function getDynamicRoutes(): ParsedRoute[];
 
-/** 根据路径查找页面配置（精确匹配 + 通配符） */
-function findPageByPath(pages: PublicPageItem[], pathname: string): PublicPageItem | undefined;
+/** 根据路径查找页面配置（精确匹配 + 最长前缀 `/*`） */
+function findPageByPath(
+  pages: PublicPageItem[],
+  pathname: string,
+): PublicPageItem | undefined;
 ```
 
 ### Window 全局变量
@@ -156,24 +170,25 @@ interface Window {
 | 决策点 | 选择 | 理由 |
 | --- | --- | --- |
 | 路由数据源 | `__MICO_PAGES__` 独立于菜单 | 页面和菜单是不同维度：页面定义"有什么路由"，菜单定义"导航怎么组织"；解耦后支持隐藏页面 |
-| 权限方案 | 菜单交叉引用 + 页面级兜底 | 菜单中的页面复用现有 sideMenus 白名单逻辑，改动最小；隐藏页面用 adminOnly + accessControlEnabled 兜底 |
+| 权限方案 | `menu_perms` + `routeKey` | 与后端新用户信息接口一致；菜单项 code 与 `menu_perms` 一一对应 |
 | 降级策略 | `getDynamicRoutes()` 自动降级 | `__MICO_PAGES__` 未注入时回退到旧行为，零配置向后兼容 |
 | PublicPageItem 定义 | `Omit<PageConfig, ...>` 派生 | 保持与 PageConfig 的类型继承关系，避免字段重复定义和类型漂移 |
 | accessControlEnabled 语义 | `false` = 公开页面（跳过认证+授权），`true` = 需要权限检查 | 一个字段统一控制 SSO 认证、权限校验、子应用加载等待，减少配置冗余 |
 | 隐藏页面权限 | 先 adminOnly 再 accessControlEnabled | adminOnly 是硬拦截，accessControlEnabled + routeKey 提供用户级粒度控制 |
+| 菜单 → 页面解析 | `pageId` 优先，再 `path` | 中台以 id 为准；路径匹配用于无 id 或 id 失效时的兜底，与 `findPageByPath` 一致 |
 
 ## 已知限制与待改进
 
-- `routeKey` 当前复用 `sideMenus` 做权限匹配，后续可能独立为专门的权限字段
-- 隐藏页面的权限控制依赖 `routeKey` 存在于 `sideMenus` 中，需要后端在下发用户权限时包含隐藏页面的 `routeKey`
+- 用户信息接口为 **`GET /user/info/`**（OpenAPI 8），与旧 `/api/user/info` 非同一后端；`fetchUserInfo` 已切换
+- 外链类型菜单项需配置 `nameKey` 作为权限 code，否则无法匹配 `menu_perms`
 
 ## 注意事项
 
 - `__MICO_PAGES__` 只包含用户在后台配置的微应用页面，404/403 等静态页面不在其中
-- `__MICO_MENUS__` 中菜单项的 `page` 字段引用的是 `__MICO_PAGES__` 中的某个页面
-- 调试时可在控制台搜索 `isForbidden (menu check)` 或 `isForbidden (hidden page` 查看权限判断日志
+- `__MICO_MENUS__` 中 `page` 类型项通过 **`pageId`**（优先）或 **`path` 与页面 `route` 匹配** 关联到 `__MICO_PAGES__` 中的页面配置
+- 调试时可在控制台过滤 `routePermission` 查看结构化权限日志（详见 [路由权限日志](./feature-路由权限日志.md)）
 
 ## 相关文档
 
 - [微前端模式](./feature-微前端模式.md) - 微应用加载机制
-- [菜单权限控制](./feature-菜单权限控制.md) - sideMenus 白名单权限逻辑
+- [菜单权限控制](./feature-菜单权限控制.md) - `menu_perms` 与菜单过滤

package/generators/micro-react/templates/apps/layout/docs/feature-/350/267/257/347/224/261/346/235/203/351/231/220/346/227/245/345/277/227.md

@@ -0,0 +1,162 @@
+# 路由权限日志
+
+> 创建时间：2026-03-27
+
+## 功能概述
+
+在 layout 中输出两类结构化开发日志，便于本地排查权限问题：
+
+1. **`routePermission`**：`BasicLayout` 中 **`isForbidden` 路由权限判定**（为何放行 / 为何 403）。
+2. **`menuFilter`**：`filterMenuItems` 中**被隐藏的菜单项**及**隐藏原因**（侧栏不可见条目）。
+
+日志均经 `layoutLogger` 输出，**仅开发环境生效**，生产构建无控制台输出。
+
+## 技术方案
+
+### 技术栈
+
+- 框架：React 18 + @umijs/max
+- 日志：`apps/layout/src/common/logger.ts` 的 `layoutLogger`（`NODE_ENV === 'development'` 时 `console.log`）
+
+### 核心实现
+
+1. 在 `BasicLayout` 的 `useMemo`（`isForbidden`）中，于各分支返回前调用 `layoutLogger.log('routePermission', payload)`。
+2. 统一使用 **`routePermission`** 作为首参，便于控制台过滤；`payload` 为结构化对象，包含 `verdict`、`reason`、`branch`（部分分支）及路径、页面上下文。
+3. **不记录**「无动态路由 `currentRoute`」与「无页面元数据且未命中菜单兜底」的常见放行路径，避免刷屏。
+4. 在 `parser.ts` 的 `filterMenuItems` 中，于菜单项被剔除时输出 **`menuFilter`**；**关闭权限**或**超级用户**时不打菜单隐藏日志（此时无实质过滤）。
+
+## 文件清单
+
+### 修改文件
+
+| 文件路径 | 说明 |
+|----------|------|
+| `apps/layout/src/layouts/index.tsx` | `isForbidden` 内各关键分支的 `routePermission` 日志 |
+| `apps/layout/src/common/menu/parser.ts` | `getMenuItemFilterOutcome`、`filterMenuItems` 内 `menuFilter` 隐藏日志 |
+
+## 日志字段说明
+
+### 通用字段
+
+| 字段 | 说明 |
+|------|------|
+| `verdict` | `skip`：跳过权限校验；`allow`：允许访问；`deny`：403 |
+| `reason` | 见下表 |
+| `pathname` | 当前 `location.pathname` |
+| `routePath` | 匹配到的动态路由 `currentRoute.path`（有 `currentRoute` 时） |
+| `userId` | `currentUser.id` |
+| `isSuperuser` | 是否超管 |
+| `menuPermsCount` | `menu_perms` 长度 |
+
+### `reason` 取值
+
+| reason | verdict | 含义 |
+|--------|---------|------|
+| `disableAuth` | skip | `__MICO_CONFIG__.disableAuth` 等效关闭权限 |
+| `noPermissionRoute` | skip | 命中免权限路由列表 |
+| `superuser` | skip | 超级用户不校验 |
+| `adminOnly` | deny | 页面 `adminOnly`，非超管 |
+| `publicPage` | allow | `accessControlEnabled === false` |
+| `accessControlNoRouteKey` | allow | 已开启访问控制但未配置 `routeKey`，不做 `menu_perms` 校验（与侧栏 `isMenuPageRequiringPermCode` 一致） |
+| `routeKeyNotInMenuPerms` | deny | `routeKey` 不在 `menu_perms` |
+| `routeKeyInMenuPerms` | allow | `routeKey` 在 `menu_perms` |
+| `notInFilteredMenuRoutes` | deny | 菜单兜底分支：过滤后路由不包含当前路径 |
+| `inFilteredMenuRoutes` | allow | 菜单兜底分支：过滤后仍包含 |
+
+### 分支字段 `branch`
+
+| branch | 含义 |
+|--------|------|
+| `pageMeta` | 已解析到 `__MICO_PAGES__` 页面配置时的 `routeKey` / `menu_perms` 判定 |
+| `menuRouteFallback` | 无页面元数据时，用「全量菜单路由 vs `filterMenuItems` 后菜单路由」比对 |
+
+### 页面元数据分支额外字段
+
+| 字段 | 说明 |
+|------|------|
+| `pageId` | 页面配置 id |
+| `routeKey` | 页面 `routeKey` |
+| `keyInMenuPerms` | `routeKey` 是否在 `menu_perms` 中（仅当需校验 `routeKey` 时输出） |
+
+### 菜单兜底分支额外字段
+
+| 字段 | 说明 |
+|------|------|
+| `inAllowed` | 当前路径是否在过滤后的允许菜单路由中 |
+
+---
+
+## 菜单过滤日志 `menuFilter`
+
+### 通用字段
+
+| 字段 | 说明 |
+|------|------|
+| `verdict` | 固定 `hidden` |
+| `reason` | 见下表 |
+| `menuId` | 菜单项 `id` |
+| `menuType` | `group` / `page` / `link` |
+| `name` | 菜单展示名（配置中的 `name`） |
+| `nameKey` | 菜单 `nameKey`（若有） |
+| `permCode` | `getMenuItemPermCode` 解析出的权限 code（可能为 `null`） |
+| `menuPermsCount` | 当前用户 `menu_perms` 长度 |
+| `path` | 菜单路由或关联页路由 |
+
+### `menuFilter.reason` 取值
+
+| reason | 含义 |
+|--------|------|
+| `adminOnly` | 菜单项 `adminOnly`，非超管不可见 |
+| `missingPermCode` | `page` 无可用 `routeKey`、`link` 无 `nameKey`，无法匹配 `menu_perms` |
+| `menuPermsEmpty` | `menu_perms` 为空数组 |
+| `permCodeNotInMenuPerms` | 权限 code 不在 `menu_perms` 中 |
+| `groupNoVisibleChildren` | 分组下子菜单全部过滤后无可见项 |
+| `allChildrenFilteredOut` | 父级单项通过（`page`/`link` 有权限），但子级全部过滤后无子项可展示 |
+
+说明：`group` 作为容器在子项仍可见时**不会**被记为 `hidden`；仅当整组被剔除时打日志。
+
+## 使用示例
+
+在浏览器控制台过滤：
+
+```text
+routePermission
+```
+
+或：
+
+```text
+menuFilter
+```
+
+或：
+
+```text
+[Layout]
+```
+
+（具体前缀以 `layoutLogger` 实现为准。）
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+|--------|------|------|
+| 日志前缀 | 固定 `'routePermission'` + 对象载荷 | 可过滤、可结构化，便于 AI/人工检索 |
+| 生产环境 | 静默 | `layoutLogger` 在 `production` 下不输出 |
+| 无 `currentRoute` 不打日志 | 跳过 | 静态路由访问频繁，避免噪音 |
+| `menuFilter` 与超管/关权限 | 不打 | 无过滤效果时无隐藏项可记 |
+
+## 已知限制与待改进
+
+- 日志仅在**开发环境**可见；线上问题需依赖 Sentry 或其它监控，不在本功能内。
+- `renderContent` 另有 `renderContent:` 日志，与 `routePermission` 独立，排查时可同时参考。
+
+## 注意事项
+
+- 权限判定逻辑以 `layouts/index.tsx` 与 [菜单权限控制](./feature-菜单权限控制.md)、[路由与菜单解耦](./feature-路由与菜单解耦.md) 为准；本文档**仅描述日志字段**，不替代权限语义说明。
+
+## 相关文档
+
+- [菜单权限控制](./feature-菜单权限控制.md)
+- [路由与菜单解耦](./feature-路由与菜单解耦.md)
+- [日志与常量](./arch-日志与常量.md)（`layoutLogger` 行为）