generator-mico-cli 0.2.21 → 0.2.22

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/mock/menus.ts

@@ -6,171 +6,116 @@
  * - id: 菜单唯一标识
  * - name: 菜单名称
  * - type: 'page' | 'group' (page: 页面, group: 分组)
- * - path: 路由路径 (group 类型为 null)
+ * - path: 路由路径 (type=page 时与 PAGES 中的 route 一致, group 类型为 null)
  * - icon: 图标名称
  * - enabled: 是否启用
  * - sortOrder: 排序权重
- * - pageId: 关联的页面 ID
- * - page: 页面配置 (微前端入口)
- *   - htmlUrl: 子应用入口地址
- *   - jsUrls: 额外 JS 资源
- *   - cssUrls: 额外 CSS 资源
+ * - pageId: 关联的页面 ID (通过 pageId 与 __MICO_PAGES__ 关联)
  * - children: 子菜单数组
  */
 
-import type { MenuItem, PageConfig } from '@/common/menu/types';
+import type { MenuItem } from '@/common/menu/types';
 
-/** Mock 页面配置 - 只需要核心字段 */
-type MockPageConfig = Pick<PageConfig,
-  | 'id' | 'name' | 'route' | 'enabled' | 'htmlUrl' | 'jsUrls' | 'cssUrls'
-  | 'adminOnly'
->;
-
-/** Mock 菜单项 - page 字段使用简化类型，包含多语言字段 */
-type MockMenuItem = Omit<MenuItem, 'page' | 'children'> & {
-  page: MockPageConfig | null;
+/** Mock 菜单项 */
+type MockMenuItem = Omit<MenuItem, 'children'> & {
   children: MockMenuItem[];
-  /** 英文名称（用于英文环境权限匹配） */
-  nameEn?: string;
-  /** 菜单唯一标识符（用于权限匹配的兜底） */
-  nameKey?: string;
 };
 
 const mockMenus: MockMenuItem[] = [
   {
-    "id": 1,
-    "name": "首页",
-    "nameEn": "Home",
-    "nameKey": "cs_web_menu_home",
-    "type": "page",
-    "path": null,
-    "icon": "Home",
-    "enabled": true,
-    "sortOrder": 0,
-    "pageId": 1,
-    "page": {
-      "id": 1,
-      "name": "home",
-      "route": "/",
-      "enabled": true,
-      "htmlUrl": "",
-      "jsUrls": [],
-      "cssUrls": []
-    },
-    "children": []
+    id: 1,
+    name: '首页',
+    nameEn: 'Home',
+    nameKey: 'cs_web_menu_home',
+    type: 'page',
+    path: '/',
+    icon: 'Home',
+    enabled: true,
+    sortOrder: 0,
+    pageId: 1,
+    children: [],
   },
   {
-    "id": 2,
-    "name": "示例模块",
-    "nameEn": "Example Module",
-    "nameKey": "cs_web_menu_example_module",
-    "type": "group",
-    "path": null,
-    "icon": "List",
-    "enabled": true,
-    "sortOrder": 1,
-    "pageId": null,
-    "page": null,
-    "children": [
+    id: 2,
+    name: '示例模块',
+    nameEn: 'Example Module',
+    nameKey: 'cs_web_menu_example_module',
+    type: 'group',
+    path: null,
+    icon: 'List',
+    enabled: true,
+    sortOrder: 1,
+    pageId: null,
+    children: [
       {
-        "id": 3,
-        "name": "示例页面",
-        "nameEn": "Example Page",
-        "nameKey": "cs_web_menu_example_page",
-        "type": "page",
-        "path": "/example/page",
-        "icon": "File",
-        "enabled": true,
-        "sortOrder": 1,
-        "pageId": 45,
-        "page": {
-          "id": 45,
-          "name": "example-page",
-          "route": "/example/page",
-          "enabled": true,
-          "htmlUrl": "",
-          "jsUrls": [],
-          "cssUrls": []
-        },
-        "children": []
-      }
-    ]
+        id: 3,
+        name: '示例页面',
+        nameEn: 'Example Page',
+        nameKey: 'cs_web_menu_example_page',
+        type: 'page',
+        path: '/example/page',
+        icon: 'File',
+        enabled: true,
+        sortOrder: 1,
+        pageId: 45,
+        children: [],
+      },
+    ],
   },
   {
-    "id": 5,
-    "name": "微应用示例",
-    "nameEn": "Microapp Example",
-    "nameKey": "cs_web_menu_microapp_example",
-    "type": "group",
-    "path": null,
-    "icon": "Apps",
-    "enabled": true,
-    "sortOrder": 2,
-    "pageId": null,
-    "page": null,
-    "children": [
+    id: 5,
+    name: '微应用示例',
+    nameEn: 'Microapp Example',
+    nameKey: 'cs_web_menu_microapp_example',
+    type: 'group',
+    path: null,
+    icon: 'Apps',
+    enabled: true,
+    sortOrder: 2,
+    pageId: null,
+    children: [
       {
-        "id": 6,
-        "name": "子应用页面",
-        "nameEn": "Subapp Page",
-        "nameKey": "cs_web_menu_subapp_page",
-        "type": "page",
-        "path": null,
-        "icon": "Desktop",
-        "enabled": true,
-        "sortOrder": 1,
-        "pageId": 55,
-        "page": {
-          "id": 55,
-          "name": "subapp-example",
-          "route": "/subapp",
-          "enabled": true,
-          "htmlUrl": "//localhost:8010",
-          "jsUrls": [],
-          "cssUrls": []
-        },
-        "children": []
-      }
-    ]
+        id: 6,
+        name: '子应用页面',
+        nameEn: 'Subapp Page',
+        nameKey: 'cs_web_menu_subapp_page',
+        type: 'page',
+        path: '/subapp/*',
+        icon: 'Desktop',
+        enabled: true,
+        sortOrder: 1,
+        pageId: 55,
+        children: [],
+      },
+    ],
   },
   {
-    "id": 7,
-    "name": "外部链接",
-    "nameEn": "External Link",
-    "nameKey": "cs_web_menu_external_link",
-    "type": "link",
-    "path": "https://github.com",
-    "icon": "Link",
-    "enabled": true,
-    "sortOrder": 3,
-    "pageId": null,
-    "page": null,
-    "children": []
+    id: 7,
+    name: '外部链接',
+    nameEn: 'External Link',
+    nameKey: 'cs_web_menu_external_link',
+    type: 'link',
+    path: 'https://github.com',
+    icon: 'Link',
+    enabled: true,
+    sortOrder: 3,
+    pageId: null,
+    children: [],
   },
   {
-    "id": 8,
-    "name": "权限管理",
-    "nameEn": "Permission Management",
-    "nameKey": "cs_web_menu_permission_management",
-    "type": "page",
-    "path": "/permission",
-    "icon": "Permission",
-    "enabled": true,
-    "sortOrder": 3,
-    "pageId": null,
-    "adminOnly": true,
-    "page": {
-      "id": 8,
-      "name": "permission",
-      "route": "/permission",
-      "enabled": true,
-      "adminOnly": true,
-      "htmlUrl": "https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.1/permission/index.html",
-      "jsUrls": [],
-      "cssUrls": []
-    },
-    "children": []
-  }
-]
+    id: 8,
+    name: '权限管理',
+    nameEn: 'Permission Management',
+    nameKey: 'cs_web_menu_permission_management',
+    type: 'page',
+    path: '/permission',
+    icon: 'Permission',
+    enabled: true,
+    sortOrder: 3,
+    pageId: null,
+    adminOnly: true,
+    children: [],
+  },
+];
 
 export default mockMenus;

package/generators/micro-react/templates/apps/layout/mock/pages.ts

@@ -0,0 +1,83 @@
+/**
+ * Mock 页面数据
+ * 用于开发环境测试，模拟 window.__MICO_PAGES__ 数据
+ *
+ * 页面结构说明:
+ * - id: 页面唯一标识
+ * - name: 页面名称
+ * - route: 路由路径
+ * - htmlUrl: 微应用 HTML 入口 URL
+ * - jsUrls: 额外 JS 资源
+ * - cssUrls: 额外 CSS 资源
+ * - prefixPath: 路由前缀路径
+ * - routeMode: 路由匹配模式 (prefix | exact)
+ * - enabled: 是否启用
+ * - accessControlEnabled: 是否开启权限控制
+ * - adminOnly: 是否仅超级管理员可见
+ * - routeKey: 路由权限标识
+ * - mainDocumentId: 关联的主文档 ID
+ * - version: 当前版本号
+ */
+
+import type { PublicPageItem } from '@/common/menu/types';
+
+const mockPages: PublicPageItem[] = [
+  {
+    id: 125,
+    name: '登录页',
+    nameEn: 'Login',
+    nameKey: 'page.user.login',
+    route: '/user/login',
+    htmlUrl:
+      'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.2/login/index.html',
+    jsUrls: [],
+    cssUrls: [],
+    prefixPath: '/user',
+    routeMode: 'exact',
+    enabled: true,
+    accessControlEnabled: false,
+    adminOnly: false,
+    routeKey: null,
+    mainDocumentId: 59,
+    version: 'v2026.02.26-04.21-000',
+  },
+  {
+    id: 124,
+    name: '权限管理',
+    nameEn: 'Permission Management',
+    nameKey: 'page.permission',
+    route: '/permission',
+    htmlUrl:
+      'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.1/permission/index.html',
+    jsUrls: [],
+    cssUrls: [],
+    prefixPath: '',
+    routeMode: 'prefix',
+    enabled: true,
+    accessControlEnabled: true,
+    adminOnly: true,
+    routeKey: null,
+    mainDocumentId: 59,
+    version: 'v2026.02.26-04.13-419',
+  },
+  {
+    id: 115,
+    name: '兜底',
+    nameEn: 'Fallback',
+    nameKey: 'page.fallback',
+    route: '/*',
+    htmlUrl: '',
+    jsUrls: [],
+    cssUrls: [],
+    prefixPath: '',
+    routeMode: 'prefix',
+    enabled: true,
+    accessControlEnabled: false,
+    adminOnly: false,
+    routeKey: null,
+    mainDocumentId: 59,
+    version: 'v2026.01.26-14.25-095',
+  },
+];
+
+export default mockPages;

package/generators/micro-react/templates/apps/layout/src/app.tsx

@@ -4,12 +4,13 @@ import { errorConfig } from './requestErrorConfig';
 // 将 @mico-platform/ui 暴露到 window，供子应用 externals 使用
 import * as micoUI from '@mico-platform/ui';
 import React from 'react';
-import ReactDOM from 'react-dom/client';
+import ReactDOM from 'react-dom';
+import ReactDOMClient from 'react-dom/client';
 
 import { getStoredAuthToken } from './common/auth/auth-manager';
 import type { IUserInfo } from './common/auth/type';
 import { fetchUserInfo } from './services/user';
-import { extractRoutes, getWindowMenus } from './common/menu';
+import { getDynamicRoutes, isPageAuthFree } from './common/menu';
 import {
   clearMicroAppProps,
   type IMicroAppProps,
@@ -23,6 +24,7 @@ import { initTheme } from './common/theme';
 import MicroAppLoader from './components/MicroAppLoader';
 import { isNoAuthRoute } from '@/constants';
 import { getCurrentLocale } from '@/common/locale';
+import '@mico-platform/theme/dist/css/theme.css';
 import './global.less';
 
 // ==================== qiankun 全局错误处理 ====================
@@ -86,6 +88,7 @@ if (typeof window !== 'undefined') {
   const win = window as unknown as Record<string, unknown>;
   win.React = React;
   win.ReactDOM = ReactDOM;
+  win.ReactDOMClient = ReactDOMClient;
   win.micoUI = micoUI;
 }
 
@@ -127,9 +130,10 @@ export async function getInitialState(): Promise<{
 
   const { location } = history;
   const noAuthRoute = isNoAuthRoute(location.pathname);
+  const skipAuth = noAuthRoute || isPageAuthFree(location.pathname);
 
   // 非免认证路由：走 SSO 流程
-  if (!noAuthRoute) {
+  if (!skipAuth) {
     await ensureSsoSession();
   }
 
@@ -145,7 +149,7 @@ export async function getInitialState(): Promise<{
   }
 
   // 非免认证路由且没有 token，跳转到 SSO 登录
-  if (!noAuthRoute) {
+  if (!skipAuth) {
     handleAuthFailureRedirect();
     // 返回空状态，页面会被重定向
     return {
@@ -182,15 +186,13 @@ interface UmiRoute {
 
 /**
  * @name 动态路由配置
- * 从 window.__MICO_MENUS__ 获取菜单数据，生成动态路由
+ * 优先从 window.__MICO_PAGES__ 获取页面数据，无数据时降级到 window.__MICO_MENUS__
  * @doc https://umijs.org/docs/max/router#%E5%8A%A8%E6%80%81%E8%B7%AF%E7%94%B1
  */
 export function patchClientRoutes({ routes }: { routes: UmiRoute[] }) {
-  const menus = getWindowMenus();
-  const dynamicRoutes = extractRoutes(menus);
+  const dynamicRoutes = getDynamicRoutes();
 
   console.log('[app.tsx] patchClientRoutes:', {
-    menus,
     dynamicRoutes,
     routes,
   });