generator-mico-cli 0.2.28 → 0.2.30

package/generators/micro-react/templates/apps/layout/docs/feature-PermissionFilter/346/214/211/351/222/256/346/235/203/351/231/220.md

@@ -0,0 +1,116 @@
+# PermissionFilter 按钮权限
+
+> 创建时间：2025-03-27
+
+## 功能概述
+
+`PermissionFilter` 用于按**按钮级权限**控制 UI 是否渲染：传入权限标识 `permissionKey`，仅当当前用户具备该权限（或为超级用户）时渲染 `children`，否则渲染可选的 `fallback`。
+
+- **主应用（layout）**：权限数据来自 `fetchUserInfo` 返回的用户信息字段 `button_perms`、`is_superuser`（与 `initialState.currentUser` 一致）。
+- **子应用**：不直接请求用户接口，权限列表由主应用通过 qiankun 注入到子应用 props，与主应用同一套 `button_perms` 语义。
+
+与侧栏菜单使用的 `menu_perms` / `routeKey` 不同，`button_perms` 面向页面内按钮、操作入口等细粒度控制。详见 [菜单权限控制](./feature-菜单权限控制.md) 中对 `button_perms` 的说明。
+
+## 技术方案
+
+### 技术栈
+
+- React 18 + TypeScript
+- 主应用：`useModel('@@initialState')` 读取 `currentUser`
+- 子应用：`@/common/mainApp` 的 `useMainAppProps()`（内部 `useSyncExternalStore`，随 qiankun `update` 刷新）
+
+### 主应用数据流
+
+1. `GET /user/info/`（`services/user.ts` → `fetchUserInfo`）返回 `button_perms: string[]`、`is_superuser`。
+2. `getInitialState`（`app.tsx`）在有 **token** 时拉取用户信息；免认证页同样需要 `currentUser` 时，逻辑为「有 token 即请求」，避免免认证页面无 `currentUser` 导致按钮权限恒为无权限。
+3. `MicroAppLoader` 将 `button_perms`、`is_superuser` 放入传给子应用的 qiankun props，子应用 `setMainAppProps` 后可供 `PermissionFilter` 使用。
+
+### 子应用数据流
+
+1. 主应用 `MicroAppLoader` 构建 props 时写入 `button_perms`、`is_superuser`。
+2. 子应用 `app.tsx` 中 qiankun `mount` / `update` 调用 `setMainAppProps(props)`。
+3. `PermissionFilter` 通过 `useMainAppProps()` 订阅 props 变化；独立运行子应用时无主应用 props，默认视为无对应按钮权限（走 `fallback`）。
+
+### 权限判定规则
+
+1. `permissionKey` 为空或仅空白：视为**无权限**。
+2. `is_superuser` 为真（含与现有 parser 一致的 `1`）：视为**有全部按钮权限**（与 `isSuperuserUser` 行为一致）。
+3. 否则：`button_perms.includes(permissionKey)` 为真则有权限。
+
+## 文件清单
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/components/PermissionFilter/index.tsx` | 主应用组件 |
+| `src/components/MicroAppLoader/index.tsx` | 向子应用注入 `button_perms`、`is_superuser` |
+| `src/services/user.ts` | `fetchUserInfo` 规范化 `button_perms` |
+| `src/app.tsx` | `getInitialState` 拉取 `currentUser` |
+
+子应用：
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/components/PermissionFilter/index.tsx` | 子应用组件（基于 `useMainAppProps`） |
+| `src/common/mainApp.ts` | qiankun props、`useMainAppProps`、`subscribeMainAppProps` |
+
+## API / 组件接口
+
+### Props（主应用与子应用一致）
+
+```typescript
+interface IPermissionFilterProps {
+  /** 按钮/操作权限标识，需在用户 button_perms 中命中 */
+  permissionKey: string;
+  children?: React.ReactNode;
+  /** 无权限时渲染；默认 null */
+  fallback?: React.ReactNode;
+}
+```
+
+## 使用示例
+
+### 主应用
+
+```tsx
+import PermissionFilter from '@/components/PermissionFilter';
+
+<PermissionFilter
+  permissionKey="cs_web_btn_export"
+  fallback={<span>无权限</span>}
+>
+  <Button type="primary">导出</Button>
+</PermissionFilter>
+```
+
+首页示例见 `src/pages/Home/index.tsx`；本地 Mock 可在 `mock/api.mock.ts` 的 `GET /user/info/` 响应 `data.button_perms` 中加入对应字符串。
+
+### 子应用
+
+```tsx
+import PermissionFilter from '@/components/PermissionFilter';
+
+<PermissionFilter
+  permissionKey="cs_web_btn_subapp_demo"
+  fallback={<Alert type="warning" content="无权限" />}
+>
+  <Button type="primary">操作</Button>
+</PermissionFilter>
+```
+
+示例见子应用 `src/pages/index.tsx`。嵌入主应用时，主应用用户信息中的 `button_perms` 需包含该 key；**独立运行**子应用时通常始终为无权限。
+
+## Mock / 联调说明
+
+- 主应用 Mock：`mock/api.mock.ts` 中 `button_perms` 数组需包含你在页面中使用的 `permissionKey`。
+- 若页面在配置中为**免认证**（`accessControlEnabled: false`），仍依赖「有 token 时拉取用户信息」才能在主应用侧得到 `button_perms`；请确认 `app.tsx` 中 `getInitialState` 与当前模板一致。
+
+## 注意事项
+
+- 权限标识由后端/配置约定，需与 `button_perms` 中字符串完全一致（区分大小写）。
+- 子应用请勿自行缓存过期的 `button_perms`；以 qiankun 传入的最新 props 为准（已用 `useMainAppProps` 订阅 `update`）。
+
+## 相关文档
+
+- [微前端模式](./feature-微前端模式.md)（MicroAppLoader、子应用加载）
+- [菜单权限控制](./feature-菜单权限控制.md)（`menu_perms` 与 `button_perms` 分工）
+- [路由与菜单解耦](./feature-路由与菜单解耦.md)

package/generators/micro-react/templates/apps/layout/docs/feature-/345/233/275/351/231/205/345/214/226.md

@@ -0,0 +1,121 @@
+# 国际化（common-intl 与 Umi 兜底）
+
+> 创建时间：2026-04-07
+
+## 功能概述
+
+layout 主应用通过 **`<%= packageScope %>/common-intl`**（`packages/common-intl` 中转包）绑定中台 **`tag`**，在 **`app.tsx`** 中 **`configureLocale`** 与 Umi **`umi_locale`** 对齐；当 **`window.__MICO_CONFIG__.intl` 或 `commonIntl`** 含有效 **`tag`、`app_name`** 时视为启用中台，首屏在 **`render`** 中 **`fetchMultilingualData`**。业务侧统一使用 **`useLayoutIntl()`**：**`i18n` 优先**，与 `defaultMessage` 比较后未命中则 **Umi `formatMessage`**（`src/locales/*`）。未启用中台时 **仅 Umi**。
+
+## 技术方案
+
+### 技术栈
+
+- Umi 4 `@umijs/max`：`locale` 运行时、`export const locale`、`useIntl`
+- `<%= packageScope %>/common-intl`：`configureLocale`、`fetchMultilingualData`、`i18n`、`intl`（包内 `initIntl`）
+- 门控与类型：`src/common/intl/intlRuntime.ts`、`types.ts`
+
+### 核心实现
+
+1. **`app.tsx`**：最早 **`configureLocale({ getLocale, setLocale })`**，与 **`getCurrentLocale`** / **`setLocaleToStorage`**（`src/common/locale.ts`）及 **`localeMapping`** 一致；**`export const locale`** 供 Umi 插件；**`render`** 仅在 **`isCommonIntlEnabled()`** 为真时调用 **`fetchMultilingualData`**（`request`、`Message`、`lang`、`LOCALE_REQUEST_URL`）。
+2. **`useLayoutIntl.ts`**：读取 **`isCommonIntlEnabled()`**；启用时 **`i18n({ key, defaultMessage })`**，否则直接 **`useIntl().formatMessage`**；兜底规则与 **`defaultMessage`**、Umi 结果比较（同子应用 **`useSubappIntl`** 策略）。
+3. **全局暴露**：**`window.CommonIntl`** 指向包模块，供子应用 **externals** 复用。
+4. **包内实现**：**`packages/common-intl/src/intl.ts`** 中 **`initIntl`** 合并 **`__MICO_CONFIG__`** 与默认 tag，详见包 README。
+
+## 文件清单（相对 `apps/layout`）
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/common/intl/useLayoutIntl.ts` | 页面统一 Hook |
+| `src/common/intl/intlRuntime.ts` | `isCommonIntlEnabled`、`getCommonIntlConfig` |
+| `src/common/intl/localeMapping.ts` | Umi locale ↔ `ILang` |
+| `src/common/intl/types.ts` | `IMicoConfigCommonIntl` |
+| `src/common/intl/index.ts` | 导出 `useLayoutIntl`、`intl`、`isCommonIntlEnabled` 等 |
+| `src/common/locale.ts` | URL / storage / 浏览器语言（与 Umi 一致） |
+| `src/app.tsx` | `configureLocale`、`locale`、`render`、**`window.CommonIntl`** |
+| `config/config.ts` | `locale` 插件（`default`、`antd: false`、`baseNavigator: false`） |
+| `src/locales/zh-CN.ts`、`en-US.ts` | Umi 兜底文案 |
+| `src/pages/Home/index.tsx` | 国际化用法示例（可选参考） |
+
+## API / 组件接口
+
+### `useLayoutIntl`
+
+```typescript
+const {
+  formatMessage,       // 与 useIntl 相同 descriptor / values 签名
+  commonIntlEnabled,   // 是否启用中台（有效 tag + app_name）
+  locale,              // 当前 Umi 风格 locale（getCurrentLocale）
+  intl,                // 包内便捷对象，仅 commonIntlEnabled 为 true 时非 undefined
+} = useLayoutIntl();
+```
+
+### `window.__MICO_CONFIG__.intl` / `commonIntl`
+
+二者取其一（见 `intlRuntime`），字段含义一致：
+
+| 字段 | 说明 |
+| --- | --- |
+| `tag` | 多语言中台 tag（必填） |
+| `app_name` | 中台应用名（必填） |
+| `indexedDBParams` | 可选本地缓存参数 |
+
+## 使用示例
+
+**运行时注入（示例）：**
+
+```javascript
+window.__MICO_CONFIG__ = {
+  commonIntl: {
+    tag: 'cs_fe_pc',
+    app_name: 'middle',
+    indexedDBParams: { dbName: 'mico_cs_web_i18n_db' },
+  },
+};
+```
+
+**页面：**
+
+```tsx
+import { useLayoutIntl } from '@/common/intl';
+
+const { formatMessage, commonIntlEnabled, locale } = useLayoutIntl();
+
+return (
+  <span>
+    {formatMessage({ id: 'page.home.title', defaultMessage: '首页' })}
+  </span>
+);
+```
+
+**包内预置文案（中台 key 亦可走 `i18n`）：**
+
+```tsx
+import { intl } from '@/common/intl';
+
+intl.common_hello();
+```
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| 门控 | `intl` 与 `commonIntl` 字段兼容 | 与注入脚本、历史配置一致 |
+| 首屏拉取 | 仅 `isCommonIntlEnabled()` 时 `render` 内 fetch | 未配置中台时不阻塞首屏 |
+| 合并策略 | `i18n` 与 Umi 二选一兜底 | 与微前端子应用 `useSubappIntl` 对齐，便于维护 |
+
+## 已知限制与待改进
+
+- **`LOCALE_REQUEST_URL`** 未配置时，行为依赖上游 **`fetchMultilingualData`** 实现。
+- 中台文案与 **`src/locales`** 的 key 需自行约定，避免重复 id 语义冲突。
+
+## 注意事项
+
+- 修改语言时请走与 **`getCurrentLocale`** / **`setLocaleToStorage`** 一致的入口，避免与 **`configureLocale`** 脱节。
+- 子应用不复制上述 **`render`** 逻辑时，嵌入主应用后通常仍依赖主应用已加载的 **`CommonIntl`**；独立运行子应用需自行 **`render` + fetch**（见子应用模板文档）。
+
+## 相关文档
+
+- [packages/common-intl README](../../../../packages/common-intl/README.md)
+- [Layout 国际化（CLI 仓库总览）](../../../../../../docs/feat-layout-国际化翻译.md)
+- [子应用国际化（模板内说明）](../../../../../subapp-react/templates/homepage/docs/feature-国际化.md)
+- [微前端模式](./feature-微前端模式.md)（主应用暴露 `CommonIntl`）

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

@@ -136,6 +136,14 @@ interface MicroAppProps {
 
 **说明**：子应用在 `mount` 生命周期中通过 `props` 接收这些数据。
 
+### 国际化（common-intl）
+
+- **共享文案（默认）**：主应用在 `render` 中拉取中台后，子应用 `import { intl } from '<%= packageScope %>/common-intl'` 即可（与主应用同一默认 tag），详见 `packages/common-intl/README.md`。
+- **不同 tag**：上游支持多次 `initIntl`，子应用可对同一依赖再绑定一套 tag 并在子应用 `render` 中拉取；或直连 `@common-web/common-intl`，见 README「不同 tag」。
+- **可选模板层**：若子应用需 `formatMessage` 式 API 与 Umi 兜底，见仓库 `docs/feat-subapp-国际化翻译.md`（生成项目根目录文档以实际为准）。
+
+主应用 **不向** 子应用 props 传递 `commonIntl`；子应用 **locale** 以 props 与主应用对齐（见上表 `locale`）。
+
 ### 子应用 Props 更新机制
 
 主应用通过 qiankun 的 `update()` 方法实时通知子应用状态变化，无需重新加载：

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`
 
 ## 相关文档