generator-mico-cli 0.2.20 → 0.2.22

package/README.md

@@ -48,12 +48,41 @@ mico list
 mico create micro-react --verbose
 ```
 
+预览模式（只显示将创建的文件，不实际创建）：
+
+```bash
+mico create micro-react --dry-run
+```
+
+检查环境依赖：
+
+```bash
+mico doctor
+```
+
 将额外参数传递给生成器：
 
 ```bash
 mico create micro-react -- --help
 ```
 
+## 配置文件
+
+可以在项目目录或用户主目录创建 `.micorc` 或 `.micorc.json` 文件来预设默认值：
+
+```json
+{
+  "packageScope": "@my-company",
+  "cdnPrefix": "portal",
+  "author": "Team <team@example.com>",
+  "defaultSubappName": "subapp"
+}
+```
+
+配置查找顺序：
+1. 当前目录的 `.micorc` 或 `.micorc.json`
+2. 用户主目录的 `.micorc` 或 `.micorc.json`
+
 ## Monorepo 项目生成器 (micro-react)
 
 创建基于 qiankun 微前端架构的完整 Monorepo 项目：

package/bin/mico.js

@@ -22,18 +22,32 @@ Commands:
   create <generator>    Run a generator (e.g., mico create subapp-react)
   list                  List all available generators
   update                Update mico-cli to the latest version
+  doctor                Check environment dependencies
 
 Options:
   --help, -h            Show this help message
   --version, -v         Show version number
   --verbose             Show detailed output during generation
+  --dry-run             Preview files without creating them
   --no-update-check     Skip update check
 
 Examples:
   mico create subapp-react
   mico create micro-react --verbose
+  mico create micro-react --dry-run
   mico list
   mico update
+  mico doctor
+
+Configuration:
+  Create a .micorc or .micorc.json file in your project or home directory
+  to set default values for prompts:
+
+  {
+    "packageScope": "@my-company",
+    "cdnPrefix": "portal",
+    "author": "Team <team@example.com>"
+  }
 
 Notes:
   Requires Yeoman CLI (yo) installed globally.
@@ -118,6 +132,85 @@ function printVersion() {
   console.log(`mico-cli v${pkg.version}`);
 }
 
+/**
+ * 运行 doctor 检查
+ */
+async function runDoctor() {
+  const { runDoctorChecks, loadMicorc } = require('../lib/utils');
+
+  console.log('');
+  console.log(`  \x1b[1mMico CLI Environment Check\x1b[0m (v${pkg.version})`);
+  console.log('');
+
+  const results = await runDoctorChecks();
+
+  // Node.js
+  const nodeIcon = results.node.satisfied ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+  const nodeStatus = results.node.satisfied ? 'OK' : `Required: >= ${results.node.required}`;
+  console.log(`  ${nodeIcon} Node.js ${results.node.current} (${nodeStatus})`);
+
+  // pnpm
+  const pnpmIcon = results.pnpm.available ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+  if (results.pnpm.available) {
+    console.log(`  ${pnpmIcon} pnpm ${results.pnpm.version}`);
+  } else {
+    console.log(`  ${pnpmIcon} pnpm not found`);
+    console.log('     Install: npm install -g pnpm');
+  }
+
+  // Yeoman
+  const yoIcon = results.yo.available ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+  if (results.yo.available) {
+    console.log(`  ${yoIcon} yo ${results.yo.version}`);
+  } else {
+    console.log(`  ${yoIcon} yo not found`);
+    console.log('     Install: npm install -g yo');
+  }
+
+  // Git
+  const gitIcon = results.git.available ? '\x1b[32m✓\x1b[0m' : '\x1b[33m⚠\x1b[0m';
+  if (results.git.available) {
+    console.log(`  ${gitIcon} git ${results.git.version}`);
+  } else {
+    console.log(`  ${gitIcon} git not found (optional)`);
+  }
+
+  // npm registry
+  const npmIcon = results.npm.reachable ? '\x1b[32m✓\x1b[0m' : '\x1b[33m⚠\x1b[0m';
+  if (results.npm.reachable) {
+    console.log(`  ${npmIcon} npm registry reachable`);
+  } else {
+    console.log(`  ${npmIcon} npm registry unreachable (${results.npm.error})`);
+  }
+
+  // .micorc 配置
+  console.log('');
+  const { config, configPath } = loadMicorc();
+  if (configPath) {
+    console.log(`  \x1b[32m✓\x1b[0m Config loaded from: ${configPath}`);
+    const keys = Object.keys(config);
+    if (keys.length > 0) {
+      console.log(`     Keys: ${keys.join(', ')}`);
+    }
+  } else {
+    console.log('  \x1b[2m○\x1b[0m No .micorc config found (optional)');
+  }
+
+  console.log('');
+
+  // 总结
+  const allGood = results.node.satisfied && results.pnpm.available && results.yo.available;
+  if (allGood) {
+    console.log('  \x1b[32m✅ All required dependencies are installed!\x1b[0m');
+  } else {
+    console.log('  \x1b[31m❌ Some required dependencies are missing.\x1b[0m');
+    console.log('     Please install them before using mico-cli.');
+  }
+  console.log('');
+
+  return allGood;
+}
+
 /**
  * 检查是否有新版本
  * @returns {Promise<{current: string, latest: string, hasUpdate: boolean} | null>}
@@ -256,6 +349,7 @@ function performUpdate(latestVersion) {
  * @param {string[]} passthroughArgs - 透传参数
  * @param {object} options - 选项
  * @param {boolean} options.verbose - 是否启用详细输出
+ * @param {boolean} options.dryRun - 是否启用 dry-run 模式
  */
 function runGenerator(generator, rest, passthroughArgs, options = {}) {
   const localGeneratorEntry = path.join(
@@ -275,17 +369,31 @@ function runGenerator(generator, rest, passthroughArgs, options = {}) {
 
   const yoArgs = [yoGenerator, ...rest];
 
+  // 添加 dry-run 参数给 yeoman
+  if (options.dryRun) {
+    yoArgs.push('--dry-run');
+  }
+
   if (passthroughArgs.length > 0) {
     yoArgs.push('--', ...passthroughArgs);
   }
 
-  // 通过环境变量传递 verbose 标志给生成器
+  // 通过环境变量传递标志给生成器
   const env = { ...process.env };
   if (options.verbose) {
     env.MICO_VERBOSE = '1';
+  }
+  if (options.dryRun) {
+    env.MICO_DRY_RUN = '1';
+  }
+
+  if (options.verbose) {
     console.log('');
     console.log('  \x1b[2m[verbose] Running generator:', yoGenerator, '\x1b[0m');
     console.log('  \x1b[2m[verbose] Arguments:', yoArgs.join(' '), '\x1b[0m');
+    if (options.dryRun) {
+      console.log('  \x1b[2m[verbose] Dry-run mode enabled\x1b[0m');
+    }
     console.log('');
   }
 
@@ -323,6 +431,7 @@ async function main() {
   const hasVersion = mainArgs.includes('--version') || mainArgs.includes('-v');
   const skipUpdateCheck = mainArgs.includes('--no-update-check');
   const isVerbose = mainArgs.includes('--verbose');
+  const isDryRun = mainArgs.includes('--dry-run');
 
   // 过滤掉标志参数
   const filteredArgs = mainArgs.filter(
@@ -332,7 +441,8 @@ async function main() {
       arg !== '--version' &&
       arg !== '-v' &&
       arg !== '--no-update-check' &&
-      arg !== '--verbose'
+      arg !== '--verbose' &&
+      arg !== '--dry-run'
   );
 
   // 处理 --version
@@ -355,6 +465,12 @@ async function main() {
     process.exit(0);
   }
 
+  // 处理 doctor 命令
+  if (command === 'doctor') {
+    const success = await runDoctor();
+    process.exit(success ? 0 : 1);
+  }
+
   // 处理 update 命令
   if (command === 'update') {
     const updateInfo = await checkForUpdate();
@@ -376,8 +492,8 @@ async function main() {
       process.exit(1);
     }
 
-    // 检查更新（除非跳过）
-    if (!skipUpdateCheck) {
+    // 检查更新（除非跳过或 dry-run）
+    if (!skipUpdateCheck && !isDryRun) {
       const updateInfo = await checkForUpdate();
       if (updateInfo && updateInfo.hasUpdate) {
         const shouldUpdate = await askForUpdate(
@@ -396,7 +512,10 @@ async function main() {
     }
 
     // 运行生成器
-    runGenerator(generator, rest.slice(1), passthroughArgs, { verbose: isVerbose });
+    runGenerator(generator, rest.slice(1), passthroughArgs, {
+      verbose: isVerbose,
+      dryRun: isDryRun
+    });
     return;
   }
 

package/generators/micro-react/index.js

@@ -9,10 +9,10 @@ const {
   collectFiles,
   transformDestPath,
   isTemplateFile,
-  getLatestNpmVersion,
+  getPackageVersionsParallel,
   setupErrorHandlers,
   createLogger,
-  // isVerbose,
+  loadMicorc,
 } = require('../../lib/utils');
 
 const IGNORE_LIST = require('./ignore-list.json');
@@ -25,6 +25,17 @@ module.exports = class extends Generator {
     this.projectRoot = process.cwd();
     this.logger = createLogger(this);
 
+    // 检查 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
     const workspaceFile = path.join(this.projectRoot, 'pnpm-workspace.yaml');
     if (fs.existsSync(workspaceFile)) {
@@ -46,12 +57,15 @@ module.exports = class extends Generator {
 
   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);
@@ -63,7 +77,7 @@ module.exports = class extends Generator {
           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('@'))
@@ -80,7 +94,7 @@ module.exports = class extends Generator {
    - 输入 "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: '',
+          default: rc.cdnPrefix || '',
           filter: (input) => {
             // 移除首尾斜杠，规范化路径
             return input.trim().replace(/^\/+|\/+$/g, '');
@@ -90,7 +104,7 @@ module.exports = class extends Generator {
           type: 'input',
           name: 'author',
           message: 'Author',
-          default: 'Your Name <email@example.com>',
+          default: rc.author || 'Your Name <email@example.com>',
         },
       ]);
 
@@ -110,7 +124,7 @@ module.exports = class extends Generator {
     }
   }
 
-  writing() {
+  async writing() {
     try {
       if (!fs.existsSync(this.templateDir)) {
         console.error('');
@@ -125,21 +139,21 @@ module.exports = class extends Generator {
 
       // 在 mico_cli 根目录执行 npm view，以使用该目录 .npmrc 中的 Nexus 认证
       const cliRoot = path.resolve(__dirname, '../..');
-      this.logger.verbose('Fetching latest package versions...');
+      this.logger.verbose('Fetching latest package versions (parallel)...');
 
-      const micoUiVer = getLatestNpmVersion(
-        '@mico-platform/ui',
-        '1.0.0',
-        8000,
-        cliRoot,
-      );
-      const themeVer = getLatestNpmVersion(
-        '@mico-platform/theme',
-        '1.0.0',
+      // 并行获取版本
+      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);
 
@@ -173,6 +187,45 @@ 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}`);
@@ -210,6 +263,9 @@ module.exports = class extends Generator {
   }
 
   install() {
+    // 跳过 dry-run 模式
+    if (this._skipInstall) return;
+
     // 检查并初始化 git
     const gitDir = path.join(this.destDir, '.git');
     if (!fs.existsSync(gitDir)) {
@@ -228,6 +284,9 @@ module.exports = class extends Generator {
   }
 
   end() {
+    // 跳过 dry-run 模式
+    if (this._skipInstall) return;
+
     this.log('');
     this.log('✅ 项目创建成功！');
     this.log('');

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/layout-app.mdc

@@ -63,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 />;
   };
 
@@ -98,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) => {
@@ -128,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,
       },
     });
   });
@@ -265,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

@@ -61,15 +61,16 @@ 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. 主题系统
 - 支持亮色/暗黑主题切换
@@ -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)

package/generators/micro-react/templates/CLAUDE.md

@@ -53,15 +53,21 @@ apps/                         # Workspace 应用目录（微前端子应用）
 │   │   ├── app.tsx          # Umi 运行时配置
 │   │   ├── layouts/         # 布局组件
 │   │   ├── pages/           # 路由页面
-│   │   ├── components/      # 公共组件
+│   │   ├── components/      # 公共组件（MicroAppLoader 等）
 │   │   ├── common/          # 工具模块（auth、request、upload、menu）
+│   │   ├── constants/       # 常量定义（路由、主题、时区等）
 │   │   ├── hooks/           # 自定义 Hooks
 │   │   ├── services/        # API 服务层
 │   │   ├── models/          # Umi model（全局状态）
-│   │   ├── locales/         # 国际化文件（zh-CN、en-US）
-│   │   └── styles/          # 主题变量与样式覆盖
+│   │   └── locales/         # 国际化文件（zh-CN、en-US）
 │   └── config/              # Umi 配置
-packages/                     # 共享包
+├── basis/                    # 基础数据子应用（货币管理等）
+│   ├── src/
+│   │   ├── pages/           # 路由页面
+│   │   ├── locales/         # 国际化文件
+│   │   └── common/          # 工具模块
+│   └── config/              # Umi 配置
+packages/                     # 共享包（common-intl 等）
 scripts/                      # 构建与开发脚本
 CICD/                         # 部署资源
 ```
@@ -97,13 +103,13 @@ refactor(auth): 重构认证服务
 API 请求配置在 `src/common/request/`（模块化拆分为 6 个文件），错误处理在 `src/requestErrorConfig.ts`。详见 [请求模块架构](./apps/layout/docs/arch-请求模块.md)。
 
 ### 日志与常量
-Logger 工具在 `src/common/logger.ts`，常量定义在 `src/common/constants.ts`。详见 [日志与常量](./apps/layout/docs/arch-日志与常量.md)。
+Logger 工具在 `src/common/logger.ts`，常量定义在 `src/constants/index.ts`。详见 [日志与常量](./apps/layout/docs/arch-日志与常量.md)。
 
 ### 认证模块
 认证逻辑在 `src/common/auth/`，核心文件 `auth-manager.ts` 管理 Token 存储和用户信息。SSO 登录在 `getInitialState()` 中完成，确保 UI 渲染前认证已就绪。
 
-### 菜单系统
-菜单解析与类型定义在 `src/common/menu/`。
+### 菜单与路由系统
+菜单解析与类型定义在 `src/common/menu/`。路由注册消费 `window.__MICO_PAGES__`（页面列表），菜单栏消费 `window.__MICO_MENUS__`（菜单树），两者解耦运作。权限通过菜单交叉引用 + 页面级兜底的双层策略控制。详见 [路由与菜单解耦](./apps/layout/docs/feature-路由与菜单解耦.md) 和 [菜单权限控制](./apps/layout/docs/feature-菜单权限控制.md)。
 
 ### 微前端
 layout 应用作为 qiankun 主应用，子应用通过 Umi 配置中的 qiankun 配置注册。详见 [微前端模式](./apps/layout/docs/feature-微前端模式.md)。
@@ -115,6 +121,8 @@ layout 应用作为 qiankun 主应用，子应用通过 Umi 配置中的 qiankun
 | [README.md](./README.md) | 项目入口、技术栈、常用命令 |
 | [提交规范](./docs/commit-message.md) | Git Commit 详细规范 |
 | [微前端模式](./apps/layout/docs/feature-微前端模式.md) | qiankun 架构、MicroAppLoader、子应用配置 |
+| [路由与菜单解耦](./apps/layout/docs/feature-路由与菜单解耦.md) | PAGES/MENUS 数据源分离、双层权限控制 |
+| [菜单权限控制](./apps/layout/docs/feature-菜单权限控制.md) | sideMenus 白名单、认证与授权分离 |
 | [主题色切换](./apps/layout/docs/feature-主题色切换.md) | useTheme Hook、CSS 变量系统 |
 | [请求模块架构](./apps/layout/docs/arch-请求模块.md) | HTTP 请求层模块化设计 |
 | [日志与常量](./apps/layout/docs/arch-日志与常量.md) | Logger 工具与常量管理 |

package/generators/micro-react/templates/_gitignore

@@ -55,3 +55,5 @@ build
 /openspec
 
 **/tasks/*
+
+.pnpm-store/**