generator-mico-cli 0.2.27 → 0.2.29

package/README.md

@@ -17,29 +17,21 @@
 ## 要求
 
 - Node >= 18
-- Yeoman CLI: `npm install -g yo`
 
 ## 安装和使用
 
 ```bash
-npm install -g yo generator-mico-cli
+pnpm install -g generator-mico-cli
 ```
 
 ## 包装器 CLI
 
-全局安装后，`mico` 命令可用于委托给 Yeoman 生成器。
-如果 `generators/<name>` 下存在本地生成器，它将作为 `yo mico-cli:<name>` 运行。
+全局安装后，`mico` 命令可用于运行内置的 Yeoman 生成器。
 
 ```bash
 mico create subapp-react
 ```
 
-等同于：
-
-```bash
-yo subapp-react
-```
-
 列出所有可用的生成器：
 
 ```bash
@@ -64,12 +56,6 @@ mico create micro-react --dry-run
 mico doctor
 ```
 
-将额外参数传递给生成器：
-
-```bash
-mico create micro-react -- --help
-```
-
 ## 配置文件
 
 可以在项目目录或用户主目录创建 `.micorc` 或 `.micorc.json` 文件来预设默认值。
@@ -168,8 +154,7 @@ DevTools Sources 面板中可在 `webpack://<name>/src/` 下定位原始 TypeScr
 # 1. 安装依赖
 pnpm install
 
-# 2. 将本地包链接到全局（需要先安装 yo）
-npm install -g yo
+# 2. 将本地包链接到全局
 npm link
 
 # 3. 验证链接成功
@@ -216,9 +201,9 @@ pnpm test:watch
 | `tests/integration/micro-react.test.js` | micro-react 生成器集成测试 |
 | `tests/integration/subapp-react.test.js` | subapp-react 生成器集成测试 |
 | `tests/integration/subapp-umd.test.js` | subapp-umd 生成器集成测试 |
-| `tests/integration/mico-cli.test.js` | `mico` 入口子进程测试（help / version / list / create 透传） |
+| `tests/integration/mico-cli.test.js` | `mico` 入口子进程测试（help / version / list / create / doctor） |
 | `tests/helpers/setup.js` | 测试共享工具（路径常量、monorepo fixture 工厂） |
-| `tests/helpers/mico-subprocess.js` | 子进程运行 `bin/mico.js`、假 `yo` 工具函数 |
+| `tests/helpers/mico-subprocess.js` | 子进程运行 `bin/mico.js` 工具函数 |
 
 ### Scripts 说明
 

package/bin/mico.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-const { spawn, spawnSync } = require('node:child_process');
+const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline');
@@ -56,7 +56,6 @@ Configuration:
   }
 
 Notes:
-  Requires Yeoman CLI (yo) installed globally.
   If a local generator exists at generators/<name>, it will be used.
 `);
 }
@@ -164,15 +163,6 @@ async function runDoctor() {
     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) {
@@ -205,7 +195,7 @@ async function runDoctor() {
   console.log('');
 
   // 总结
-  const allGood = results.node.satisfied && results.pnpm.available && results.yo.available;
+  const allGood = results.node.satisfied && results.pnpm.available;
   if (allGood) {
     console.log('  \x1b[32m✅ All required dependencies are installed!\x1b[0m');
   } else {
@@ -351,14 +341,12 @@ function performUpdate(latestVersion) {
 /**
  * 运行 Yeoman 生成器
  * @param {string} generator - 生成器名称
- * @param {string[]} rest - 剩余参数
- * @param {string[]} passthroughArgs - 透传参数
  * @param {object} options - 选项
  * @param {boolean} options.verbose - 是否启用详细输出
  * @param {boolean} options.dryRun - 是否启用 dry-run 模式
  * @param {boolean} options.force - 是否强制覆盖已有文件
  */
-function runGenerator(generator, rest, passthroughArgs, options = {}) {
+async function runGenerator(generator, options = {}) {
   const localGeneratorEntry = path.join(
     rootDir,
     'generators',
@@ -366,42 +354,37 @@ function runGenerator(generator, rest, passthroughArgs, options = {}) {
     'index.js'
   );
 
+  if (!fs.existsSync(localGeneratorEntry)) {
+    console.error(`❌ Cannot find generator "${generator}".`);
+    console.error(`   Expected: ${localGeneratorEntry}`);
+    console.error('');
+    console.error('   Run "mico list" to see available generators.');
+    process.exit(1);
+  }
+
   const pkgName = typeof pkg.name === 'string' ? pkg.name : '';
   const localNamespace =
     pkgName.replace(/^generator-/, '') || pkgName || 'generator';
+  const namespace = `${localNamespace}:${generator}`;
 
-  const yoGenerator = fs.existsSync(localGeneratorEntry)
-    ? `${localNamespace}:${generator}`
-    : generator;
-
-  const yoArgs = [yoGenerator, ...rest];
-
-  // 添加 dry-run 参数给 yeoman
-  if (options.dryRun) {
-    yoArgs.push('--dry-run');
-  }
-
-  if (options.force) {
-    yoArgs.push('--force');
+  if (options.verbose) {
+    process.env.MICO_VERBOSE = '1';
   }
-
-  if (passthroughArgs.length > 0) {
-    yoArgs.push('--', ...passthroughArgs);
+  if (options.dryRun) {
+    process.env.MICO_DRY_RUN = '1';
   }
 
-  // 通过环境变量传递标志给生成器
-  const env = { ...process.env };
-  if (options.verbose) {
-    env.MICO_VERBOSE = '1';
-  }
+  const runOptions = {};
   if (options.dryRun) {
-    env.MICO_DRY_RUN = '1';
+    runOptions.dryRun = true;
+  }
+  if (options.force) {
+    runOptions.force = true;
   }
 
   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');
+    console.log('  \x1b[2m[verbose] Running generator:', namespace, '\x1b[0m');
     if (options.dryRun) {
       console.log('  \x1b[2m[verbose] Dry-run mode enabled\x1b[0m');
     }
@@ -411,28 +394,10 @@ function runGenerator(generator, rest, passthroughArgs, options = {}) {
     console.log('');
   }
 
-  const child = spawn('yo', yoArgs, { stdio: 'inherit', env });
-
-  let exited = false;
-  const quit = (code) => {
-    if (!exited) {
-      exited = true;
-      process.exit(code);
-    }
-  };
-
-  child.on('error', (error) => {
-    if (error && error.code === 'ENOENT') {
-      console.error('Cannot find "yo". Install it with: npm install -g yo');
-    } else {
-      console.error(error);
-    }
-    quit(1);
-  });
-
-  child.on('exit', (code) => {
-    quit(typeof code === 'number' ? code : 1);
-  });
+  const yeomanEnv = require('yeoman-environment');
+  const env = yeomanEnv.createEnv();
+  env.register(localGeneratorEntry, namespace);
+  await env.run(namespace, runOptions);
 }
 
 /**
@@ -536,7 +501,7 @@ async function main() {
     }
 
     // 运行生成器
-    runGenerator(generator, rest.slice(1), passthroughArgs, {
+    await runGenerator(generator, {
       verbose: isVerbose,
       dryRun: isDryRun,
       force: isForce

package/generators/micro-react/index.js

@@ -109,6 +109,12 @@ module.exports = class extends Generator {
           message: 'Author',
           default: rc.author || 'Your Name <email@example.com>',
         },
+        {
+          type: 'input',
+          name: 'intlTag',
+          message: '多语言中台 tag（如暂无可留空，后续在 packages/common-intl/src/intl.ts 中配置）',
+          default: rc.intlTag || 'fake_tag_does_not_exist',
+        },
       ]);
 
       this.projectName = toKebab(this.answers.projectName);
@@ -116,6 +122,7 @@ module.exports = class extends Generator {
       this.packageScope = this.answers.packageScope;
       this.cdnPrefix = this.answers.cdnPrefix;
       this.author = this.answers.author;
+      this.intlTag = this.answers.intlTag;
       this.templateDir = this.templatePath();
       this.destDir = this.projectRoot;
     } catch (error) {
@@ -172,6 +179,7 @@ module.exports = class extends Generator {
         themeVersion: `^${themeVer}`,
         cdnPrefix: this.cdnPrefix,
         cdnPrefixPath, // 用于拼接路径，已包含尾部斜杠
+        intlTag: this.intlTag,
       };
 
       this.logger.verbose('Template data:', JSON.stringify(templateData, null, 2));

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

@@ -25,6 +25,7 @@ apps/layout/docs/
 ├── feature-菜单权限控制.md      # sideMenus 白名单、认证与授权分离
 ├── feature-主题色切换.md        # 主题系统实现
 ├── feature-404页面.md           # 404 页面
+├── feature-PermissionFilter按钮权限.md  # 按钮级权限 PermissionFilter
 ├── arch-请求模块.md             # HTTP 请求层模块化设计
 ├── arch-日志与常量.md           # Logger 工具与常量管理
 ├── common-intl.md               # 国际化公共包
@@ -41,6 +42,7 @@ apps/layout/docs/
 ### Step 1: 确认需求涉及的模块
 - 微前端相关 → 阅读 `apps/layout/docs/feature-微前端模式.md`
 - 路由/菜单/权限相关 → 阅读 `apps/layout/docs/feature-路由与菜单解耦.md` 和 `apps/layout/docs/feature-菜单权限控制.md`
+- 按钮级权限（PermissionFilter）→ 阅读 `apps/layout/docs/feature-PermissionFilter按钮权限.md`；子应用见 `apps/<subapp>/docs/feature-PermissionFilter按钮权限.md`
 - 主题/样式相关 → 阅读 `apps/layout/docs/feature-主题色切换.md`
 - 请求/认证相关 → 阅读 `apps/layout/docs/arch-请求模块.md` 和 `src/common/auth/` 源码
 - 菜单相关 → 阅读 `src/common/menu/` 源码
@@ -64,6 +66,7 @@ find . -name "*.md" -type f | grep -v node_modules
 | 新建子应用 | `apps/layout/docs/feature-微前端模式.md` |
 | 路由/页面配置 | `apps/layout/docs/feature-路由与菜单解耦.md` |
 | 权限控制 | `apps/layout/docs/feature-菜单权限控制.md` |
+| 按钮级权限 PermissionFilter | `apps/layout/docs/feature-PermissionFilter按钮权限.md` |
 | 主题适配 | `apps/layout/docs/feature-主题色切换.md` |
 | 提交代码 | `docs/commit-message.md` |
 | API 请求 | `apps/layout/docs/arch-请求模块.md` |

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

@@ -126,6 +126,7 @@ Jenkins 根据环境执行 `CICD/` 下的构建脚本：
 - [微前端模式](mdc:apps/layout/docs/feature-微前端模式.md)
 - [路由与菜单解耦](mdc:apps/layout/docs/feature-路由与菜单解耦.md)
 - [菜单权限控制](mdc:apps/layout/docs/feature-菜单权限控制.md)
+- [PermissionFilter 按钮权限](mdc:apps/layout/docs/feature-PermissionFilter按钮权限.md)
 - [主题色切换](mdc:apps/layout/docs/feature-主题色切换.md)
 - [提交规范](mdc:docs/commit-message.md)
 - [部署说明](mdc:deployDesc.md)

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

@@ -123,6 +123,7 @@ layout 应用作为 qiankun 主应用，子应用通过 Umi 配置中的 qiankun
 | [微前端模式](./apps/layout/docs/feature-微前端模式.md) | qiankun 架构、MicroAppLoader、子应用配置 |
 | [路由与菜单解耦](./apps/layout/docs/feature-路由与菜单解耦.md) | PAGES/MENUS 数据源分离、双层权限控制 |
 | [菜单权限控制](./apps/layout/docs/feature-菜单权限控制.md) | sideMenus 白名单、认证与授权分离 |
+| [PermissionFilter 按钮权限](./apps/layout/docs/feature-PermissionFilter按钮权限.md) | `button_perms`、主/子应用用法与数据流 |
 | [主题色切换](./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/README.md

@@ -79,7 +79,7 @@ pnpm list:preset
 
 ```bash
 # 全局安装（一次性）
-pnpm add -g yo mico-cli
+pnpm add -g generator-mico-cli
 
 # 在仓库根目录执行
 mico create subapp-react

package/generators/micro-react/templates/apps/layout/config/config.dev.ts

@@ -27,12 +27,15 @@ const config: ReturnType<typeof defineConfig> = {
           defaultPath: '',
           // 免认证路由（跳过 SSO 登录），支持 /* 前缀匹配
           // noAuthRouteList: ['/*'],
-          // 免权限校验路由（跳过菜单权限检查）
-          noPermissionRouteList: [],
+          // 免权限校验路由（跳过菜单权限检查），与 mock pages 中 accessControlEnabled 示例一致时可按需配置
+          noPermissionRouteList: ['/group-management/*', '/logout/*'],
           // 不显示布局的路由（全屏页面）
           // noLayoutRouteList: [],
           // 关闭权限控制（调试用）
           disableAuth: false,
+          // SSO 外跳地址（与 resolveExternalLoginPath 读取的 externalLoginPath 一致；生产由注入的 __MICO_CONFIG__ 提供）
+          externalLoginPath:
+            'https://micous-idp.cig.tencentcs.com/sso/xxxxxxx/cas',
         };
       `,
     },
@@ -68,8 +71,8 @@ const config: ReturnType<typeof defineConfig> = {
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/',
     'process.env.REFRESH_ENDPOINT':
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/refresh/',
-    'process.env.EXTERNAL_LOGIN_PATH':
-      'https://micous-idp.cig.tencentcs.com/sso/xxxxxxx/cas',
+    'process.env.LOCALE_REQUEST_URL':
+      'https://api-test.micoplatform.com/lang_server/pull',
   },
 };
 

package/generators/micro-react/templates/apps/layout/config/config.prod.development.ts

@@ -33,8 +33,8 @@ const config: ReturnType<typeof defineConfig> = {
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/',
     'process.env.REFRESH_ENDPOINT':
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/refresh/',
-    'process.env.EXTERNAL_LOGIN_PATH':
-      'https://micous-idp.cig.tencentcs.com/sso/xxxxxxx/cas',
+    'process.env.LOCALE_REQUEST_URL':
+      'https://api-test.micoplatform.com/lang_server/pull',
   },
 };
 

package/generators/micro-react/templates/apps/layout/config/config.prod.testing.ts

@@ -33,8 +33,8 @@ const config: ReturnType<typeof defineConfig> = {
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/',
     'process.env.REFRESH_ENDPOINT':
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/refresh/',
-    'process.env.EXTERNAL_LOGIN_PATH':
-      'https://micous-idp.cig.tencentcs.com/sso/xxxxxxx/cas',
+    'process.env.LOCALE_REQUEST_URL':
+      'https://api-test.micoplatform.com/lang_server/pull',
   },
 };
 

package/generators/micro-react/templates/apps/layout/config/config.prod.ts

@@ -21,8 +21,8 @@ const config: ReturnType<typeof defineConfig> = {
       'https://dashboard-api.micoplatform.com/api/yufu_login/',
     'process.env.REFRESH_ENDPOINT':
       'https://dashboard-api.micoplatform.com/api/yufu_login/refresh/',
-    'process.env.EXTERNAL_LOGIN_PATH':
-      'https://micous-idp.cig.tencentcs.com/sso/xxxxxxx/cas',
+    'process.env.LOCALE_REQUEST_URL':
+      'https://api.micoplatform.com/lang_server/pull',
   },
   externals: {
     react: 'React',
@@ -33,7 +33,7 @@ const config: ReturnType<typeof defineConfig> = {
   extraBabelPlugins: ['babel-plugin-dynamic-import-node'],
 
   // 禁用代码分割，只输出一个 JS 和一个 CSS
-  chainWebpack(memo) {
+  chainWebpack(memo: any) {
     // 禁用 splitChunks
     memo.optimization.splitChunks(false);
     // 禁用 runtimeChunk

package/generators/micro-react/templates/apps/layout/docs/feat-/346/236/204/345/273/272define/344/270/216/345/205/215/350/256/244/350/257/201/345/210/235/345/247/213/346/200/201.md

@@ -0,0 +1,44 @@
+# 构建 define 精简与免认证页初始态
+
+> 创建时间：2026-03-24
+
+## 功能概述
+
+1. **Umi `define`**：不再通过构建期注入 `process.env.EXTERNAL_LOGIN_PATH`（本模板从未注入 `APP_ID`）；SSO 外跳等依赖运行时 `window.__MICO_CONFIG__`。
+2. **`getInitialState`**：免认证路由下即使本地仍有 token，也不请求用户信息接口，减少无效调用。
+
+## 技术方案
+
+### 开发环境
+
+`config/config.dev.ts` 的 `headScripts` 中 `window.__MICO_CONFIG__` 增加 **`externalLoginPath`**（模板默认为占位 URL，生成项目后请按实际 IdP 修改）。
+
+`define` 仅保留 `NODE_ENV`、`API_BASE_URL`、`LOGIN_ENDPOINT`、`REFRESH_ENDPOINT`。
+
+### 生产 / 测试构建
+
+`config.prod.ts`、`config.prod.development.ts`、`config.prod.testing.ts` 的 `define` 中同样**不包含** `EXTERNAL_LOGIN_PATH`，由部署时注入的 `__MICO_CONFIG__.externalLoginPath`（或 `__MICO_WORKSPACE__.casServerLoginUrl`）提供。
+
+### 初始态
+
+`src/app.tsx` 中仅在 `getStoredAuthToken() && !skipAuth` 时调用 `fetchUserInfoFn()`；`skipAuth = isNoAuthRoute || isPageAuthFree`。
+
+## 文件清单
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `config/config.dev.ts` | `__MICO_CONFIG__.externalLoginPath`；移除 `EXTERNAL_LOGIN_PATH` define |
+| `config/config.prod.ts` | 移除 `EXTERNAL_LOGIN_PATH` define |
+| `config/config.prod.development.ts` | 同上 |
+| `config/config.prod.testing.ts` | 同上 |
+| `src/app.tsx` | `fetchUserInfo` 条件增加 `!skipAuth` |
+
+## 部署注意
+
+- 生产 HTML 或网关需保证 `window.__MICO_CONFIG__` 含 **`appId`**、**`externalLoginPath`**（或与现有网关字段对齐），否则代理前缀、SSO 外跳可能异常。
+- 详见 `src/common/request/config.ts` 中 `buildDefaultClientOptions` 的解析顺序。
+
+## 相关文档
+
+- [fix-SSO无限重定向](./fix-SSO无限重定向.md)
+- [arch-请求模块](./arch-请求模块.md)

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/276/256/345/211/215/347/253/257/346/250/241/345/274/217.md

@@ -45,7 +45,7 @@
 
 ```typescript
 interface MicroAppLoaderProps {
-  /** 微应用在主应用中的挂载路径前缀（通常与当前页面 route.path 一致），经 normalizeMicroAppBase 后传给子应用 */
+  /** 微应用在主应用中的挂载路径前缀（来自 ParsedRoute.base / 页面配置 base），经 normalizeMicroAppBase 后传给子应用 */
   base: string;
   /** 微应用入口 URL */
   entry: string;
@@ -76,10 +76,10 @@ interface MicroAppLoaderProps {
 
 | 字段 | 含义 |
 | --- | --- |
-| **base** | 该微应用在主应用中的**根路径前缀**，一般等于菜单/动态路由里的 `path`。 |
+| **base** | 该微应用在主应用中的**挂载前缀**，来自中台 **`page.base`**，解析为 **`ParsedRoute.base`**（缺省时解析为 **`'/'`**）；可与动态路由 **`path`** 不同（如 `path` 为 `/subapp/*` 时 `base` 可为 `/subapp`）。 |
 | **routePath** | 当前激活的**完整路由路径**，随浏览器 URL 变化，用于通知子应用做**内部路由同步**。 |
 
-二者在 `layouts/index.tsx` 中常同为 `currentRoute.path`；在 `app.tsx` 的 `patchClientRoutes` 里与动态路由项一致，传入 **`base: route.path`**、**`name: route.path`**（`name` 另在布局侧可能改为基于 `entry` 的 `getAppNameFromEntry`，与 `base` 来源不同，需注意）。
+`routePath` 在布局内为 **`currentRoute.path`**。`base` 在 **`patchClientRoutes`** 与布局内均为 **`route.base` / `currentRoute.base`**。**`name`** 在布局侧常为基于 **`entry`** 的 **`getAppNameFromEntry`**，与 **`base`** 来源不同，需注意。
 
 #### `normalizeMicroAppBase`
 
@@ -96,8 +96,8 @@ export const normalizeMicroAppBase = (path: string): string =>
 
 | 位置 | 说明 |
 | --- | --- |
-| `src/app.tsx` `patchClientRoutes` | 动态注册微应用路由时：`React.createElement(MicroAppLoader, { entry, name: route.path, base: route.path, ... })` |
-| `src/layouts/index.tsx` | 布局内渲染：`<MicroAppLoader base={currentRoute.path} routePath={currentRoute.path} ... />` |
+| `src/app.tsx` `patchClientRoutes` | 动态注册微应用路由时：`React.createElement(MicroAppLoader, { entry, name: route.path, base: route.base, ... })` |
+| `src/layouts/index.tsx` | 布局内渲染：`<MicroAppLoader base={currentRoute.base} routePath={currentRoute.path} ... />` |
 
 #### 加载门控（认证）
 
@@ -165,6 +165,8 @@ export async function update(props: MicroAppProps) {
 ```typescript
 interface ParsedRoute {
   path: string;
+  /** 微应用挂载前缀（来自 page.base，解析缺省为 '/'） */
+  base: string;
   name: string;
   icon: string;
   /** 加载类型: internal(内部路由) | microapp(qiankun微应用) */
@@ -182,6 +184,8 @@ interface PageConfig {
   id: number;
   name: string;
   route: string;
+  /** 微应用挂载前缀（可与 route 不同） */
+  base: string;
   enabled: boolean;
   /** 微应用 HTML 入口 URL (优先使用) */
   htmlUrl: string | null;
@@ -254,7 +258,8 @@ const renderContent = () => {
       <MicroAppLoader
         entry={currentRoute.entry}
         name={currentRoute.name}
-        base={currentRoute.path}
+        base={currentRoute.base}
+        routePath={currentRoute.path}
       />
     );
   }