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

package/generators/micro-react/index.js

@@ -9,7 +9,10 @@ const {
   collectFiles,
   transformDestPath,
   isTemplateFile,
-  setupErrorHandlers
+  getPackageVersionsParallel,
+  setupErrorHandlers,
+  createLogger,
+  loadMicorc,
 } = require('../../lib/utils');
 
 const IGNORE_LIST = require('./ignore-list.json');
@@ -20,61 +23,98 @@ setupErrorHandlers();
 module.exports = class extends Generator {
   initializing() {
     this.projectRoot = process.cwd();
+    this.logger = createLogger(this);
 
-    // 检查当前目录是否已是一个 monorepo
+    // 检查 dry-run 模式
+    this.isDryRun = this.options.dryRun || process.env.MICO_DRY_RUN === '1';
+
+    // 加载 .micorc 配置
+    const { config: rcConfig, configPath } = loadMicorc(this.projectRoot);
+    this.rcConfig = rcConfig;
+    if (configPath) {
+      this.logger.verbose('Loaded config from:', configPath);
+      this.logger.verbose('Config:', JSON.stringify(rcConfig, null, 2));
+    }
+
+    // 检查当前目录是否已是一个 monorepo（--force 跳过此检查）
     const workspaceFile = path.join(this.projectRoot, 'pnpm-workspace.yaml');
-    if (fs.existsSync(workspaceFile)) {
+    if (fs.existsSync(workspaceFile) && !this.options.force) {
       console.error('');
       console.error('❌ Error: Current directory is already a monorepo.');
       console.error('');
       console.error('   A pnpm-workspace.yaml file already exists.');
-      console.error('   Please run this command in an empty directory or specify a new project name.');
+      console.error(
+        '   Please run this command in an empty directory or specify a new project name.',
+      );
       console.error('');
       console.error('   Usage:');
       console.error('     mkdir my-project && cd my-project');
       console.error('     mico create micro-react');
       console.error('');
+      console.error('   To regenerate in an existing monorepo, use --force:');
+      console.error('     mico create micro-react --force');
+      console.error('');
       process.exit(1);
     }
   }
 
   async prompting() {
     try {
+      // 使用 .micorc 中的值作为默认值
+      const rc = this.rcConfig || {};
+
       this.answers = await this.prompt([
         {
           type: 'input',
           name: 'projectName',
           message: 'Project name',
-          default: path.basename(this.projectRoot),
+          default: rc.projectName || path.basename(this.projectRoot),
           filter: (input) => toKebab(input),
           validate: (input) => {
             const value = toKebab(input);
             if (!value) return 'Project name is required';
             return true;
-          }
+          },
         },
         {
           type: 'input',
           name: 'packageScope',
           message: 'Package scope (e.g., @my-project)',
-          default: (answers) => `@${toKebab(answers.projectName)}`,
+          default: (answers) => rc.packageScope || `@${toKebab(answers.projectName)}`,
           validate: (input) => {
             if (!input) return 'Package scope is required';
-            if (!input.startsWith('@')) return 'Package scope must start with @';
+            if (!input.startsWith('@'))
+              return 'Package scope must start with @';
             return true;
-          }
+          },
+        },
+        {
+          type: 'input',
+          name: 'cdnPrefix',
+          message: `CDN path prefix (用于区分不同业务线的 CDN 目录)
+   示例：CDN 完整路径 = https://cdn.example.com/<prefix>/<projectName>/<version>/
+   - 留空: https://cdn.example.com/my-project/1.0.0/
+   - 输入 "portal": https://cdn.example.com/portal/my-project/1.0.0/
+   - 输入 "admin/v2": https://cdn.example.com/admin/v2/my-project/1.0.0/
+   Prefix`,
+          default: rc.cdnPrefix || '',
+          filter: (input) => {
+            // 移除首尾斜杠，规范化路径
+            return input.trim().replace(/^\/+|\/+$/g, '');
+          },
         },
         {
           type: 'input',
           name: 'author',
           message: 'Author',
-          default: 'Your Name <email@example.com>'
-        }
+          default: rc.author || 'Your Name <email@example.com>',
+        },
       ]);
 
       this.projectName = toKebab(this.answers.projectName);
       this.ProjectName = toPascal(this.projectName);
       this.packageScope = this.answers.packageScope;
+      this.cdnPrefix = this.answers.cdnPrefix;
       this.author = this.answers.author;
       this.templateDir = this.templatePath();
       this.destDir = this.projectRoot;
@@ -87,7 +127,7 @@ module.exports = class extends Generator {
     }
   }
 
-  writing() {
+  async writing() {
     try {
       if (!fs.existsSync(this.templateDir)) {
         console.error('');
@@ -97,14 +137,50 @@ module.exports = class extends Generator {
         process.exit(1);
       }
 
+      this.logger.verbose('Template directory:', this.templateDir);
+      this.logger.verbose('Destination directory:', this.destDir);
+
+      // 在 mico_cli 根目录执行 npm view，以使用该目录 .npmrc 中的 Nexus 认证
+      const cliRoot = path.resolve(__dirname, '../..');
+      this.logger.verbose('Fetching latest package versions (parallel)...');
+
+      // 并行获取版本
+      const versions = await getPackageVersionsParallel(
+        [
+          { name: '@mico-platform/ui', fallback: '1.0.0' },
+          { name: '@mico-platform/theme', fallback: '1.0.0' },
+        ],
+        8000,
+        cliRoot,
+      );
+
+      const micoUiVer = versions['@mico-platform/ui'];
+      const themeVer = versions['@mico-platform/theme'];
+
+      this.logger.verbose('@mico-platform/ui version:', micoUiVer);
+      this.logger.verbose('@mico-platform/theme version:', themeVer);
+
+      // 构建 CDN 路径片段：如果有 prefix 则加上斜杠前缀，否则为空
+      const cdnPrefixPath = this.cdnPrefix ? `${this.cdnPrefix}/` : '';
+
       const templateData = {
         projectName: this.projectName,
         ProjectName: this.ProjectName,
         packageScope: this.packageScope,
-        author: this.author
+        author: this.author,
+        micoUiVersion: `^${micoUiVer}`,
+        themeVersion: `^${themeVer}`,
+        cdnPrefix: this.cdnPrefix,
+        cdnPrefixPath, // 用于拼接路径，已包含尾部斜杠
       };
 
-      const files = collectFiles(this.templateDir, this.templateDir, IGNORE_LIST);
+      this.logger.verbose('Template data:', JSON.stringify(templateData, null, 2));
+
+      const files = collectFiles(
+        this.templateDir,
+        this.templateDir,
+        IGNORE_LIST,
+      );
 
       if (files.length === 0) {
         console.error('');
@@ -114,22 +190,72 @@ module.exports = class extends Generator {
         process.exit(1);
       }
 
+      // Dry-run 模式：只列出文件，不实际创建
+      if (this.isDryRun) {
+        this.log('');
+        this.log('\x1b[33m📋 Dry run mode - no files will be created\x1b[0m');
+        this.log('');
+        this.log(`   Project: ${this.projectName}`);
+        this.log(`   Scope: ${this.packageScope}`);
+        this.log(`   Destination: ${this.destDir}`);
+        this.log('');
+        this.log('   Would create the following files:');
+        this.log('');
+
+        let templateCount = 0;
+        let copyCount = 0;
+
+        for (const relPath of files) {
+          const destRelPath = transformDestPath(relPath);
+          const isTemplate = isTemplateFile(relPath);
+          const tag = isTemplate ? '\x1b[32m[tpl]\x1b[0m' : '\x1b[36m[cpy]\x1b[0m';
+          this.log(`   ${tag} ${destRelPath}`);
+
+          if (isTemplate) {
+            templateCount++;
+          } else {
+            copyCount++;
+          }
+        }
+
+        this.log('');
+        this.log(`   Total: ${files.length} files (${templateCount} templates, ${copyCount} static)`);
+        this.log('');
+        this.log('   Run without --dry-run to actually create these files.');
+        this.log('');
+
+        // 设置标记以跳过后续阶段
+        this._skipInstall = true;
+        return;
+      }
+
       this.log('');
       this.log(`📦 Creating project: ${this.projectName}`);
       this.log(`   Scope: ${this.packageScope}`);
       this.log('');
 
+      this.logger.verbose(`Processing ${files.length} files...`);
+
+      let templateCount = 0;
+      let copyCount = 0;
+
       for (const relPath of files) {
         const srcPath = path.join(this.templateDir, relPath);
         const destRelPath = transformDestPath(relPath);
         const destPath = path.join(this.destDir, destRelPath);
 
         if (isTemplateFile(relPath)) {
+          this.logger.file('template', destRelPath);
           this.fs.copyTpl(srcPath, destPath, templateData);
+          templateCount++;
         } else {
+          this.logger.file('copy', destRelPath);
           this.fs.copy(srcPath, destPath);
+          copyCount++;
         }
       }
+
+      this.logger.verbose(`Processed: ${templateCount} templates, ${copyCount} copied`);
     } catch (error) {
       console.error('');
       console.error('❌ Error during file generation:');
@@ -139,15 +265,71 @@ module.exports = class extends Generator {
     }
   }
 
+  install() {
+    // 跳过 dry-run 模式
+    if (this._skipInstall) return;
+
+    // 检查并初始化 git
+    const gitDir = path.join(this.destDir, '.git');
+    if (!fs.existsSync(gitDir)) {
+      this.log('');
+      this.log('🔧 初始化 Git 仓库...');
+      this.spawnCommandSync('git', ['init'], {
+        cwd: this.destDir,
+      });
+    }
+
+    this.log('');
+    this.log('📦 正在安装依赖...');
+    try {
+      this.spawnCommandSync('pnpm', ['install'], {
+        cwd: this.destDir,
+      });
+    } catch (e) {
+      this._installFailed = true;
+      this.log('');
+      this.log('⚠️  依赖安装失败，但项目文件已全部生成。');
+      this.logger.verbose('Install error:', e.message);
+      return;
+    }
+
+    // 依赖安装成功后，格式化生成的文件以消除风格差异
+    const layoutDir = path.join(this.destDir, 'apps/layout');
+    if (fs.existsSync(path.join(layoutDir, '.prettierrc'))) {
+      this.log('');
+      this.log('🎨 格式化生成的文件...');
+      try {
+        this.spawnCommandSync('pnpm', ['-C', 'apps/layout', 'format'], {
+          cwd: this.destDir,
+        });
+      } catch (e) {
+        this.logger.verbose('Formatting failed (non-critical):', e.message);
+      }
+    }
+  }
+
   end() {
+    // 跳过 dry-run 模式
+    if (this._skipInstall) return;
+
     this.log('');
-    this.log('✅ 项目创建成功！');
+
+    if (this._installFailed) {
+      this.log('⚠️  项目文件已创建，但依赖安装未完成。');
+      this.log('');
+      this.log('   请手动安装依赖:');
+      this.log('');
+      this.log('   pnpm install');
+      this.log('');
+      this.log('   如果安装仍然失败，可尝试:');
+      this.log('   pnpm install --network-concurrency 4');
+    } else {
+      this.log('✅ 项目创建成功！');
+    }
+
     this.log('');
     this.log('   后续步骤:');
     this.log('');
-    this.log('   # 安装依赖');
-    this.log('   pnpm install');
-    this.log('');
     this.log('   # 启动开发服务器');
     this.log('   pnpm dev');
     this.log('');

package/generators/micro-react/meta.json

@@ -0,0 +1,13 @@
+{
+  "name": "micro-react",
+  "description": "创建基于 qiankun 的微前端 Monorepo 项目",
+  "usage": "mkdir my-project && cd my-project && mico create micro-react",
+  "features": [
+    "Turborepo + pnpm Workspace",
+    "qiankun 微前端架构",
+    "Arco Design + Tailwind CSS",
+    "主题切换、国际化、认证模块",
+    "可配置 CDN 路径前缀（支持多业务线隔离）",
+    "Sentry 错误监控与 SourceMap 上传"
+  ]
+}

package/generators/micro-react/templates/.commitlintrc.js

@@ -2,5 +2,6 @@ module.exports = {
   extends: ['@commitlint/config-conventional'],
   rules: {
     'header-max-length': [0, 'always', 10000],
+    'body-max-line-length': [0, 'always', Infinity],
   },
 };

package/generators/micro-react/templates/.cursor/rules/always-read-docs.mdc

@@ -20,8 +20,15 @@ docs/
 ### 2. Layout 应用文档 (`/apps/layout/docs/`)
 ```
 apps/layout/docs/
-├── feature-微前端模式.md   # qiankun 微前端架构
-└── feature-主题色切换.md   # 主题系统实现
+├── feature-微前端模式.md        # qiankun 微前端架构
+├── feature-路由与菜单解耦.md    # PAGES/MENUS 数据源分离、双层权限
+├── feature-菜单权限控制.md      # sideMenus 白名单、认证与授权分离
+├── feature-主题色切换.md        # 主题系统实现
+├── feature-404页面.md           # 404 页面
+├── arch-请求模块.md             # HTTP 请求层模块化设计
+├── arch-日志与常量.md           # Logger 工具与常量管理
+├── common-intl.md               # 国际化公共包
+└── utils-timezone.md            # 时区工具
 ```
 
 ### 3. 其他应用文档
@@ -33,8 +40,9 @@ apps/layout/docs/
 
 ### Step 1: 确认需求涉及的模块
 - 微前端相关 → 阅读 `apps/layout/docs/feature-微前端模式.md`
+- 路由/菜单/权限相关 → 阅读 `apps/layout/docs/feature-路由与菜单解耦.md` 和 `apps/layout/docs/feature-菜单权限控制.md`
 - 主题/样式相关 → 阅读 `apps/layout/docs/feature-主题色切换.md`
-- 请求/认证相关 → 阅读 `src/common/request/` 和 `src/common/auth/` 源码
+- 请求/认证相关 → 阅读 `apps/layout/docs/arch-请求模块.md` 和 `src/common/auth/` 源码
 - 菜单相关 → 阅读 `src/common/menu/` 源码
 
 ### Step 2: 查找相关文档
@@ -54,9 +62,11 @@ find . -name "*.md" -type f | grep -v node_modules
 | 需求类型 | 必读文档 |
 |---------|---------|
 | 新建子应用 | `apps/layout/docs/feature-微前端模式.md` |
+| 路由/页面配置 | `apps/layout/docs/feature-路由与菜单解耦.md` |
+| 权限控制 | `apps/layout/docs/feature-菜单权限控制.md` |
 | 主题适配 | `apps/layout/docs/feature-主题色切换.md` |
 | 提交代码 | `docs/commit-message.md` |
-| API 请求 | `src/common/request/index.ts` 源码注释 |
+| API 请求 | `apps/layout/docs/arch-请求模块.md` |
 | 认证登录 | `src/common/auth/` 目录源码 |
 | 菜单配置 | `src/common/menu/types.ts` 类型定义 |
 

package/generators/micro-react/templates/.cursor/rules/cicd-deploy.mdc

@@ -21,7 +21,7 @@ globs: ["CICD/**", "deployDesc.md"]
 │                              ↓                                   │
 │  ┌─────────────────────────────────────────────────────────────┐│
 │  │  构建产物：dist/{app}/                                       ││
-│  │  上传 CDN：cdn-portal[-env].micoplatform.com/<%= projectName %>/   ││
+│  │  上传 CDN：cdn-portal[-env].micoplatform.com/<%= cdnPrefixPath %><%= projectName %>/   ││
 │  └─────────────────────────────────────────────────────────────┘│
 └─────────────────────────────────────────────────────────────────┘
 ```
@@ -51,7 +51,7 @@ pnpm install
 VERSION=$(node -p "require('./package.json').version")
 
 # 3. 设置 CDN 路径
-export CDN_PUBLIC_PATH="https://cdn-portal[-env].micoplatform.com/<%= projectName %>/${VERSION}/"
+export CDN_PUBLIC_PATH="https://cdn-portal[-env].micoplatform.com/<%= cdnPrefixPath %><%= projectName %>/${VERSION}/"
 
 # 4. 执行构建
 pnpm run build:[environment]
@@ -78,12 +78,14 @@ echo "VERSION=$VERSION" > .env_x_<%= projectName %>
 ### CDN 路径结构
 ```
 cdn-portal.micoplatform.com/
-└── <%= projectName %>/
-    └── {version}/
-        └── dist/
-            ├── layout/      # 主应用
-            ├── homepage/    # 子应用
-            └── ...
+<% if (cdnPrefix) { %>└── <%= cdnPrefix %>/
+    └── <%= projectName %>/
+<% } else { %>└── <%= projectName %>/
+<% } %>        └── {version}/
+            └── dist/
+                ├── layout/      # 主应用
+                ├── homepage/    # 子应用
+                └── ...
 ```
 
 ## 环境变量

package/generators/micro-react/templates/.cursor/rules/coding-conventions.mdc

@@ -168,7 +168,7 @@ import React, { useState, useEffect } from 'react';
 import { useLocation } from '@umijs/max';
 
 // 2. 第三方库
-import { Button, Modal } from '@arco-design/web-react';
+import { Button, Modal } from '@mico-platform/ui';
 import dayjs from 'dayjs';
 
 // 3. 项目内部模块（使用 @ 别名）

package/generators/micro-react/templates/.cursor/rules/development-guide.mdc

@@ -179,8 +179,7 @@ document.body.setAttribute('data-theme', 'dark');
 ### 文件位置
 ```
 apps/layout/mock/
-├── menus.json         # 菜单数据
-├── menus.ts           # 菜单数据处理
+├── menus.ts           # 菜单 Mock 数据（带类型）
 └── user.mock.ts       # 用户相关 Mock API
 ```
 
@@ -274,7 +273,7 @@ sh CICD/start_prod.sh
 
 构建产物上传到 CDN：
 ```
-cdn-portal[-env].micoplatform.com/<%= projectName %>/{version}/dist/{app}/
+cdn-portal[-env].micoplatform.com/<%= cdnPrefixPath %><%= projectName %>/{version}/dist/{app}/
 ```
 
 - `version`：`package.json` 的 version 字段
@@ -290,6 +289,6 @@ cdn-portal[-env].micoplatform.com/<%= projectName %>/{version}/dist/{app}/
 ## 相关链接
 
 - [UmiJS 文档](https://umijs.org/)
-- [Arco Design](https://arco.design/)
+- [@mico-platform/ui](hhttps://mico-ui.micoportal-test.com/react/docs/start)
 - [qiankun 文档](https://qiankun.umijs.org/)
 - [Turborepo 文档](https://turbo.build/repo)

package/generators/micro-react/templates/.cursor/rules/layout-app.mdc

@@ -52,10 +52,7 @@ apps/layout/
     ├── services/              # API 服务
     ├── models/                # Umi Model
     ├── locales/               # 国际化
-    └── styles/                # 主题样式
-        ├── themes/            # 主题变量
-        ├── variables.less     # Less 变量
-        └── arco-override.less # Arco 覆盖
+    └── styles/                # 主题样式（变量来自 @mico-platform/theme）
 ```
 
 ## 核心模块
@@ -66,24 +63,27 @@ apps/layout/
 const BasicLayout: React.FC = () => {
   const location = useLocation();
 
-  // 解析路由配置
-  const routes = useMemo(() => {
-    const menus = getWindowMenus();
-    return extractRoutes(menus);
+  // 所有页面路由（优先 PAGES，降级 MENUS）— 用于路由匹配和渲染
+  const allPageRoutes = useMemo(() => {
+    return getDynamicRoutes();
   }, []);
 
-  // 查找当前路由配置
+  // 菜单路由（从 MENUS）— 用于权限交叉引用
+  const allMenuRoutes = useMemo(() => {
+    return extractRoutes(getMenus());
+  }, []);
+
+  // 当前路由配置（从所有页面路由中查找）
   const currentRoute = useMemo(() => {
-    return findRouteByPath(routes, location.pathname);
-  }, [routes, location.pathname]);
+    return findRouteByPath(allPageRoutes, location.pathname);
+  }, [allPageRoutes, location.pathname]);
 
   // 渲染页面内容
   const renderContent = () => {
-    // 微应用类型使用 MicroAppLoader
     if (currentRoute?.loadType === 'microapp' && currentRoute.entry) {
-      return <MicroAppLoader entry={currentRoute.entry} name={currentRoute.path} />;
+      const appName = getAppNameFromEntry(currentRoute.entry);
+      return <MicroAppLoader entry={currentRoute.entry} name={appName} />;
     }
-    // 内部路由使用 Outlet
     return <Outlet />;
   };
 
@@ -101,28 +101,36 @@ const BasicLayout: React.FC = () => {
 };
 ```
 
-### 2. 菜单系统 (common/menu/)
+### 2. 全局数据源 (common/portal-data.ts) + 菜单系统 (common/menu/)
 
 ```typescript
-// 获取菜单数据
-const menus = getWindowMenus();
+// 获取页面列表 (window.__MICO_PAGES__)
+const pages = getPages();
+
+// 获取菜单树 (window.__MICO_MENUS__)
+const menus = getMenus();
 
-// 提取路由配置
-const routes = extractRoutes(menus);
+// 从页面列表提取动态路由（优先数据源）
+const routes = getDynamicRoutes();
 
-// 解析菜单项
+// 从菜单树提取路由（用于权限交叉引用）
+const menuRoutes = extractRoutes(menus);
+
+// 解析菜单项（用于侧边栏渲染）
 const menuItems = parseMenuItems(menus);
 
 // 查找当前路由
 const currentRoute = findRouteByPath(routes, pathname);
+
+// 通过 pageId 查找页面（O(1)）
+const page = getPageById(pageId);
 ```
 
 ### 3. 动态路由 (app.tsx)
 
 ```typescript
 export function patchClientRoutes({ routes }: { routes: any[] }) {
-  const menus = getWindowMenus();
-  const dynamicRoutes = extractRoutes(menus);
+  const dynamicRoutes = getDynamicRoutes(); // 从 __MICO_PAGES__ 获取
 
   const rootRoute = routes.find((r) => r.path === '/');
   dynamicRoutes.forEach((route) => {
@@ -131,9 +139,7 @@ export function patchClientRoutes({ routes }: { routes: any[] }) {
       name: route.name,
       meta: {
         loadType: route.loadType,
-        htmlUrl: route.htmlUrl,
-        jsUrls: route.jsUrls,
-        cssUrls: route.cssUrls,
+        entry: route.entry,
       },
     });
   });
@@ -206,7 +212,7 @@ const { isAuthenticated, user, logout } = useAuth();
 ### 主题变量引入
 ```less
 // 在组件样式中使用
-@import '<%= packageScope %>/shared-styles/variables-only';
+@import '@mico-platform/theme/variables';
 
 .my-component {
   background: @color-fill-1;
@@ -268,8 +274,9 @@ const { collapsed } = useModel('global');
 
 ## 注意事项
 
-1. **菜单数据来源**: 通过 `window.__MICO_MENUS__` 注入
-2. **路由动态生成**: 在 `patchClientRoutes` 中根据菜单生成路由
-3. **微应用判断**: 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
-4. **主题初始化**: 在 `app.tsx` 中调用 `initTheme()` 避免闪烁
-5. **认证共享**: 子应用使用主应用传递的 `request` 实例
+1. **数据来源**: 页面列表通过 `window.__MICO_PAGES__` 注入，菜单树通过 `window.__MICO_MENUS__` 注入
+2. **路由动态生成**: 在 `patchClientRoutes` 中优先从 `__MICO_PAGES__` 生成路由
+3. **权限交叉引用**: 菜单路由（`__MICO_MENUS__`）用于权限判断，页面路由（`__MICO_PAGES__`）用于渲染
+4. **微应用判断**: 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
+5. **主题初始化**: 在 `app.tsx` 中调用 `initTheme()` 避免闪烁
+6. **认证共享**: 子应用使用主应用传递的 `request` 实例

package/generators/micro-react/templates/.cursor/rules/project-overview.mdc

@@ -16,7 +16,7 @@ alwaysApply: true
 | **Monorepo** | Turborepo + pnpm Workspace |
 | **前端框架** | UmiJS 4 (@umijs/max)、React 18、TypeScript |
 | **微前端** | qiankun |
-| **UI 组件** | Arco Design Web |
+| **UI 组件** | @mico-platform/ui |
 | **样式方案** | Tailwind CSS + Less + CSS Variables |
 | **代码规范** | ESLint、Stylelint、Husky、Commitlint |
 
@@ -61,20 +61,21 @@ alwaysApply: true
 - **关键文件**:
   - `src/layouts/index.tsx` - 主布局组件
   - `src/components/MicroAppLoader/` - 微应用加载器
-  - `src/common/menu/parser.ts` - 菜单解析与路由提取
+  - `src/common/menu/parser.ts` - 菜单解析、页面数据提取与路由生成
   - `src/common/request/index.ts` - 统一请求封装
   - `src/hooks/useTheme.ts` - 主题管理 Hook
 
 ### 2. 微前端架构
-- 菜单数据通过 `window.__MICO_MENUS__` 注入
+- 路由注册优先使用 `window.__MICO_PAGES__`（页面列表），无数据时降级到 `window.__MICO_MENUS__`（菜单树）
 - 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
 - 使用 `loadMicroApp` API 动态挂载子应用
 - 子应用共享主应用的 `request` 实例
+- 权限通过菜单交叉引用 + 页面级兜底的双层策略控制
 
 ### 3. 主题系统
 - 支持亮色/暗黑主题切换
 - 使用 CSS Variables 实现运行时动态切换
-- `arco-theme` 控制 Arco Design 组件
+- `arco-theme` 控制 @mico-platform/ui 组件
 - `data-theme` 控制自定义样式
 
 ## 常用命令
@@ -123,6 +124,8 @@ Jenkins 根据环境执行 `CICD/` 下的构建脚本：
 ## 相关文档
 
 - [微前端模式](mdc:apps/layout/docs/feature-微前端模式.md)
+- [路由与菜单解耦](mdc:apps/layout/docs/feature-路由与菜单解耦.md)
+- [菜单权限控制](mdc:apps/layout/docs/feature-菜单权限控制.md)
 - [主题色切换](mdc:apps/layout/docs/feature-主题色切换.md)
 - [提交规范](mdc:docs/commit-message.md)
 - [部署说明](mdc:deployDesc.md)