generator-mico-cli 0.2.30 → 0.2.31

package/README.md

@@ -6,13 +6,14 @@
 
 | 文档 | 说明 |
 |---|---|
-| [docs/mico-cli.md](docs/mico-cli.md) | Mico CLI 功能概述与技术方案 |
-| [docs/micro-react-generator.md](docs/micro-react-generator.md) | Monorepo 项目生成器说明 |
-| [docs/subapp-react-generator.md](docs/subapp-react-generator.md) | React 子应用生成器说明 |
-| [docs/subapp-umd-generator.md](docs/subapp-umd-generator.md) | UMD 组件包生成器说明 |
-| [docs/feat-integration-tests.md](docs/feat-integration-tests.md) | 集成测试方案（Vitest + yeoman-test） |
-| [docs/fix-command-injection.md](docs/fix-command-injection.md) | 修复 npm version 查询命令注入风险 |
-| [docs/refactor-code-quality-optimizations.md](docs/refactor-code-quality-optimizations.md) | 代码质量优化（DRY / 错误处理 / 确定性 ID / 可配置化 / 冗余清理） |
+| [docs/architecture.md](docs/architecture.md) | 项目架构、模块职责、关键约定、依赖关系 |
+| [docs/generators.md](docs/generators.md) | 三个生成器的 prompt / 模板变量 / 联动修改细节 |
+| [docs/configuration.md](docs/configuration.md) | `.micorc` 配置字段与加载顺序 |
+| [docs/testing.md](docs/testing.md) | Vitest + yeoman-test 测试体系与 Mock 策略 |
+| [docs/scripts.md](docs/scripts.md) | `sync:subapp-react-template` 与 `verify:micro-react` |
+| [generators/micro-react/README.md](generators/micro-react/README.md) | `micro-react` 生成器就近说明 |
+| [generators/subapp-react/README.md](generators/subapp-react/README.md) | `subapp-react` 生成器就近说明 |
+| [generators/subapp-umd/README.md](generators/subapp-umd/README.md) | `subapp-umd` 生成器就近说明 |
 
 ## 要求
 

package/generators/micro-react/README.md

@@ -0,0 +1,34 @@
+# micro-react 生成器
+
+创建完整的 qiankun 微前端 Monorepo。详细 prompt、模板变量、后置动作请见 [docs/generators.md#micro-react](../../docs/generators.md#micro-react)。
+
+## 快速索引
+
+| 文件 | 职责 |
+|---|---|
+| `index.js` | Yeoman 生成器类（`initializing` / `prompting` / `writing` / `install` / `end`） |
+| `meta.json` | `mico list` 展示的名称、描述、features |
+| `ignore-list.json` | `collectFiles` 按路径片段过滤的清单 |
+| `templates/` | 模板根（本仓库文档审计不覆盖此目录） |
+
+## 使用
+
+```bash
+mkdir my-project && cd my-project
+mico create micro-react
+# 可选：--dry-run / --verbose / --force
+```
+
+要求当前目录**不**是已有 monorepo（没有 `pnpm-workspace.yaml`）；`--force` 可绕过此检查。
+
+## 模板变量速查
+
+| 变量 | 类型 | 来源 |
+|---|---|---|
+| `projectName` / `ProjectName` | string | prompt，`toKebab` / `toPascal` |
+| `appId` | string | prompt |
+| `packageScope` | string | prompt |
+| `cdnPrefix` / `cdnPrefixPath` | string | prompt；`cdnPrefixPath` 为空或带尾斜杠 |
+| `author` | string | prompt |
+| `intlTag` | string | prompt |
+| `micoUiVersion` / `themeVersion` | string | `npm view @mico-platform/{ui,theme} version`，前缀 `^`，失败回退 `^1.0.0` |

package/generators/micro-react/index.js

@@ -186,6 +186,8 @@ module.exports = class extends Generator {
       const templateData = {
         projectName: this.projectName,
         ProjectName: this.ProjectName,
+        // 用于 MFSU mfName 等需要合法 JS 标识符的场景（不允许 `-`）
+        projectNameSnake: this.projectName.replace(/-/g, '_'),
         appId: this.appId,
         packageScope: this.packageScope,
         author: this.author,

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

@@ -34,7 +34,7 @@ const config: ReturnType<typeof defineConfig> = {
           // 关闭权限控制（调试用）
           disableAuth: false,
           // SSO 外跳地址（与 resolveExternalLoginPath 读取的 externalLoginPath 一致；生产由注入的 __MICO_CONFIG__ 提供）
-          externalLoginPath: 'https://micous-idp.cig.tencentcs.com/sso/tn-456d1d3feb5f4e09ad28ab35ee4d2e66/ai-138064426b9e43818098705df5400eef/cas',
+          externalLoginPath: 'https://micous-idp.cig.tencentcs.com/sso/tn-456d1d3feb5f4e09ad28ab35ee4d2e66/ai-4919cf3d4883490b956b90376cfb86e7/cas',
           // 多语言中台（可选）：intl 与 common-intl 包 initIntl 合并；见 packages/common-intl/README.md
           // 这里只是一个例子，需要根据业务在翻译中台的配置来替换
           // intl: {
@@ -80,6 +80,26 @@ const config: ReturnType<typeof defineConfig> = {
     'process.env.LOCALE_REQUEST_URL':
       'https://api-test.micoplatform.com/lang_server/pull',
   },
+
+  /**
+   * @name MFSU 配置
+   * @description
+   * - mfName: 唯一名隔离微前端 runtime，避免多应用共存时 MFSU 容器冲突
+   * - exclude:
+   *   - `@mico-platform/theme`：theme 子路径解析
+   *   - `@mico-platform/ui`：尽量与主应用一起编译
+   *   - `<%= packageScope %>/*`：workspace 包走 webpack 编译，开发态可在 DevTools 直接定位到 packages/* 源码
+   * - shared: React 单例，确保 MFSU 预打包里的组件（如 Layout）与主应用共用同一份 React，否则 useContext 报 null
+   * @doc https://umijs.org/docs/api/config#mfsu
+   */
+  mfsu: {
+    mfName: 'mf_<%= projectNameSnake %>_layout',
+    exclude: ['@mico-platform/theme', '@mico-platform/ui', /^<%= packageScope %>\//],
+    shared: {
+      react: { singleton: true },
+      'react-dom': { singleton: true },
+    },
+  },
 };
 
 export default defineConfig(config);

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

@@ -124,21 +124,6 @@ const config: ReturnType<typeof defineConfig> = {
    */
   extraBabelPresets: ['@mico-platform/ui/babel-preset'],
 
-  /**
-   * @name MFSU 配置
-   * @description
-   * - exclude: theme 子路径解析；ui 尽量与主应用一起编译
-   * - shared: React 单例，确保 MFSU 预打包里的组件（如 Layout）与主应用共用同一份 React，否则 useContext 报 null
-   * @doc https://umijs.org/docs/guides/mfsu
-   */
-  mfsu: {
-    exclude: ['@mico-platform/theme', '@mico-platform/ui'],
-    shared: {
-      react: { singleton: true },
-      'react-dom': { singleton: true },
-    },
-  },
-
   /**
    * @name qiankun 微前端配置
    * @description 作为主应用，动态加载子应用

package/generators/micro-react/templates/apps/layout/docs/arch-/346/227/245/345/277/227/344/270/216/345/270/270/351/207/217.md

@@ -4,7 +4,15 @@
 
 ## Logger 工具
 
-生产环境静默的日志工具，使用 `bind` 保持正确的调用栈位置。
+默认：**开发环境**全量输出；**生产环境**仅 `log` / `info` / `warn` 静默，`error` 仍带前缀输出。使用 `bind` 保持正确的调用栈位置。
+
+### 生产临时全量日志（首屏 query）
+
+首屏 URL 带 **`?debug=1`**（或 `debug=true` / `yes`，大小写不敏感）时，在**本模块首次加载**时解析一次，之后 `log` / `info` / `warn` 与开发环境行为一致；**不**随 SPA 内路由或 query 变更而动态开关（需整页刷新并带上参数）。
+
+常量 **`DEBUG_LOGS_QUERY_KEY`**（当前为 `'debug'`）与 **`isLayoutDebugLogsEnabled`**（布尔）可从 `@/common/logger` 引用。
+
+**安全与合规**：仅用于临时排障；控制台可能含业务或个人信息，**勿长期公开或转发**带 `debug` 的生产链接；接入日志采集时需自行脱敏。
 
 ### 使用
 
@@ -18,12 +26,12 @@ layoutLogger.error('error'); // 保持原始调用栈位置
 ### 实现原理
 
 ```typescript
-// 使用 bind 而非 wrapper，保持控制台显示正确的调用位置
-const createLogger = (prefix: string) => ({
-  log: console.log.bind(console, `[${prefix}]`),
-  error: console.error.bind(console, `[${prefix}]`),
-  // ...
-});
+// 使用 bind 而非 wrapper，保持控制台显示实际调用位置
+// 生产且未开 debug：log/info/warn 为 noop，error 仍 bind
+const createLogger = (prefix: string) =>
+  isLayoutDebugLogsEnabled
+    ? createVerboseHandlers(`[${prefix}]`)
+    : createQuietHandlers(`[${prefix}]`);
 ```
 
 ### 预定义 Logger
@@ -100,6 +108,6 @@ export const STORAGE_KEYS = {
 
 ## 注意事项
 
-- Logger 仅在开发环境输出，生产环境静默
+- 生产默认仅 `error` 输出；首屏 `?debug=1` 等可打开全量日志（见上文），用完建议去掉参数或整页刷新无参 URL
 - 使用 `bind` 实现，DevTools 显示实际调用位置而非 logger.ts
 - 新增路由常量应添加到 `ROUTES` 对象

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

@@ -1,11 +1,13 @@
 # 构建 define 精简与免认证页初始态
 
-> 创建时间：2026-03-24
+> 创建时间：2026-03-24  
+> 更新：2026-05-13（补充 `defaultPath` 首屏与 `authCheckPath`、与手动跳转认证页的差异；补充从免认证页跳进认证页后 **`refresh` → `fetchUserInfo`** 的说明）
 
 ## 功能概述
 
 1. **Umi `define`**：不再通过构建期注入 `process.env.EXTERNAL_LOGIN_PATH`（本模板从未注入 `APP_ID`）；SSO 外跳等依赖运行时 `window.__MICO_CONFIG__`。
 2. **`getInitialState`**：免认证路由下即使本地仍有 token，也不请求用户信息接口，减少无效调用。
+3. **`/` + `defaultPath` 首屏**：若仅用 `location.pathname === '/'` 判断是否免认证，可能与「即将 `replace` 到的默认页」的认证要求不一致；见下文 **`authCheckPath`**。
 
 ## 技术方案
 
@@ -21,7 +23,46 @@
 
 ### 初始态
 
-`src/app.tsx` 中仅在 `getStoredAuthToken() && !skipAuth` 时调用 `fetchUserInfoFn()`；`skipAuth = isNoAuthRoute || isPageAuthFree`。
+`src/app.tsx` 中仅在 `getStoredAuthToken() && !skipAuth` 时调用 `fetchUserInfoFn()`；`skipAuth` 由 **`isNoAuthRoute(authCheckPath) || isPageAuthFree(authCheckPath)`** 计算（见下节 **`authCheckPath`**，勿与仅看 `location.pathname` 混淆）。
+
+### `defaultPath` 与 `authCheckPath`（首屏重定向 vs 手动进认证页）
+
+#### 背景
+
+访问 **`/`** 且配置了 **`window.__MICO_CONFIG__.defaultPath`**（且不为 `/`）时，`app.tsx` 的 **`onRouteChange`** 会 **`history.replace(defaultPath)`**（例如跳到工作台）。**`getInitialState` 与 `onRouteChange` 的执行顺序下，首屏拿到的 `history.location.pathname` 往往仍是 `/`**。
+
+若 **`/`** 被配进 **`noAuthRouteList`**，或 **`/`** 对应页面 **`accessControlEnabled: false`**（页面级免认证），则仅按 **`pathname === '/'`** 会得到 **`skipAuth === true`**：不执行 **`ensureSsoSession`**、不按需认证页拉用户；随后用户马上被重定向到 **`defaultPath` 所指的需登录页**，形成「用免认证壳路径误判、绕开目标页认证」的窗口。为此在 **`getInitialState`**（约自 `app.tsx` 215 行起）对 **`defaultPath`** 做与 **`onRouteChange`** 一致的重定向预判。
+
+#### `authCheckPath` 规则
+
+- 当 **`pathname === '/'`** 且存在有效 **`defaultPath`**（与 `/` 不同）时，视为即将发生默认重定向，令 **`authCheckPath = defaultPath`**；
+- 否则 **`authCheckPath = location.pathname`**。
+
+**`isNoAuthRoute`、`isPageAuthFree` 以及由此得到的 `skipAuth`、`ensureSsoSession`、是否拉 `fetchUserInfo` 等，均基于 `authCheckPath`**，使首屏认证语义与 **重定向目标页** 一致，而不是与瞬时的 **`/`** 一致。
+
+实现上 **`authCheckPath`** 与 **`handleAuthFailureRedirect`**（`src/common/request/sso.ts`）共用 **`resolveAuthCheckPath(pathname)`**（`src/common/auth/auth-check-path.ts`），避免无 token 时 **`getInitialState` 已按 `defaultPath` 判定需认证**，但 SSO 外跳仍按浏览器地址 **`/`** 误判为免认证而**不触发重定向**。
+
+#### 与「从免认证页手动点到认证页」的区别
+
+| 场景 | 典型 `location.pathname` | 为何不会误判 |
+| --- | --- | --- |
+| **`/` + `defaultPath` 首屏** | 首屏仍为 **`/`**，真实要去 **`defaultPath`** | 若只看 **`/`**，可能与 **`defaultPath`** 的认证要求不一致；必须用 **`authCheckPath`** 把判断「对齐到目标页」。 |
+| **应用内从免认证页导航到认证页**（如 `/login` → `/app`） | 导航后 **`/app/...`** | 不会用旧页的免认证 pathname 算 **`skipAuth`**；且布局里 **`useRoutePermissionRefresh`** 在 pathname 变为**非** `isNoAuthRoute` 时会调用 **`@@initialState` 的 `refresh()`**，从而**再次执行 `getInitialState`**，在 **`getStoredAuthToken() && !skipAuth`** 成立时拉 **`fetchUserInfo`**（见下节）。整页刷新直达认证页时逻辑相同，仅触发时机为首屏而非路由变更。 |
+| **外链直达或地址栏改为认证页** | 直接进入 **`/app/xxx`** | 首屏 `getInitialState` 即按认证页计算 **`skipAuth`**；有 token 则拉 **`fetchUserInfo`**。 |
+
+#### 为何客户端从免认证跳进认证页后会拉取用户权限（`fetchUserInfo`）
+
+1. **首屏停在免认证路径**：`getInitialState` 里 **`skipAuth === true`**，模板在 **`getStoredAuthToken() && !skipAuth`** 条件下**不会**为当前首屏去调用户信息接口，`currentUser` 可能仍为空（见 `app.tsx`）。
+
+2. **`pathname` 变为需认证路径**：`layouts/index.tsx` 使用 **`useRoutePermissionRefresh`**（`src/hooks/useRoutePermissionRefresh.ts`）。在**跳过首次渲染**之后，每当 **`location.pathname` 变化**且新路径**不是** **`isNoAuthRoute`** 所指的静态免认证路由时，会防抖调用 Umi **`useModel('@@initialState').refresh()`**。
+
+3. **`refresh()` 会重新执行 `getInitialState`**：此时用于计算 **`skipAuth`** 的路径已是认证页（并适用上文 **`authCheckPath`** 规则），一般 **`skipAuth === false`**；若本地仍有 **`getStoredAuthToken()`**，即进入 **`fetchUserInfoFn()`**，请求 **`GET /user/info/`** 等，更新 **`menu_perms`、`button_perms`** 等，供菜单、PermissionFilter、MicroAppLoader 注入子应用等使用。
+
+4. **与「整页刷新且首屏已在认证页」**：走同一套 `getInitialState` 分支；差别是触发源为 **路由变更 + `refresh()`**，而非 **应用冷启动首屏**。
+
+5. **实现细节**：`useRoutePermissionRefresh` 仅以 **`isNoAuthRoute(pathname)`** 判断是否跳过刷新；若某路由**仅**页面级 **`isPageAuthFree`** 而不在 `noAuthRouteList` 中，离开该页时 pathname 变化仍可能触发 **`refresh()`**——即「离开静态免认证名单就允许刷新权限」的策略。
+
+**结论**：「绕过认证」风险来自 **「URL 暂时是免认证的 `/`，但实际业务要去需 SSO 的 `defaultPath`」** 这一种 **首屏 + 默认重定向** 组合；**`authCheckPath`** 专门纠偏这一种。**手动从免认证页进入认证页**时，浏览器地址已是认证路径，鉴权按认证页执行，**不依赖**与 `defaultPath` 相同的特殊分支；二者差异在于 **是否存在「pathname 与真实首屏业务路径不一致」的短暂错位**。在 **SPA** 下，进入认证页后还会经 **`useRoutePermissionRefresh` → `refresh()`** 在 **有 token** 时补拉 **`fetchUserInfo`**（见上节），避免 **`currentUser` 仍为空**、菜单与子应用权限数据落后。
 
 ## 文件清单
 
@@ -31,7 +72,11 @@
 | `config/config.prod.ts` | 移除 `EXTERNAL_LOGIN_PATH` define |
 | `config/config.prod.development.ts` | 同上 |
 | `config/config.prod.testing.ts` | 同上 |
-| `src/app.tsx` | `fetchUserInfo` 条件增加 `!skipAuth` |
+| `src/app.tsx` | `getInitialState` 使用 `resolveAuthCheckPath` |
+| `src/common/auth/auth-check-path.ts` | `resolveAuthCheckPath`：`/` + `defaultPath` 与真实鉴权路径对齐 |
+| `src/common/request/sso.ts` | `handleAuthFailureRedirect` 使用 `resolveAuthCheckPath`，与 `getInitialState` 一致 |
+| `src/hooks/useRoutePermissionRefresh.ts` | 非静态免认证路径的 pathname 变更时 `refresh()`，触发重跑 `getInitialState` 以拉权限 |
+| `src/layouts/index.tsx` | 使用 `useRoutePermissionRefresh` |
 
 ## 部署注意
 
@@ -40,5 +85,6 @@
 
 ## 相关文档
 
+- [菜单权限控制](./feature-菜单权限控制.md)（SSO 步骤与 pathname / `authCheckPath` 关系）
 - [fix-SSO无限重定向](./fix-SSO无限重定向.md)
 - [arch-请求模块](./arch-请求模块.md)

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,6 +1,6 @@
 # 菜单权限控制
 
-> 创建时间：2026-01-24 更新时间：2026-03-27（同步 `getMenuPage`：pageId 优先，path 兜底）
+> 创建时间：2026-01-24 更新时间：2026-03-27（同步 `getMenuPage`：pageId 优先，path 兜底）；2026-05-13（`getInitialState` 与 `authCheckPath` 说明链至 feat-构建define）
 
 ## 功能概述
 
@@ -84,6 +84,8 @@
 └──────────────────────────────────────────────┘
 ```
 
+**首屏 `getInitialState` 与步骤 1**：若 URL 为 **`/`** 且配置了 **`__MICO_CONFIG__.defaultPath`**（非 `/`），`onRouteChange` 会 **`replace`** 到默认路径，首屏瞬间 **`location.pathname` 可能仍为 `/`**。此时步骤 1 不能只看 **`pathname`**，需用 **`authCheckPath`**（见 [feat-构建define与免认证初始态](./feat-构建define与免认证初始态.md) 中「`defaultPath` 与 `authCheckPath`」）。图中步骤 1 的「pathname」在 **`getInitialState`** 语境下指 **`authCheckPath`**；从免认证页**手动**进入认证页时，地址已是认证路径，无「`/` 壳 vs `defaultPath` 目标」错位。**客户端 SPA** 下进入认证页后，还会由 **`useRoutePermissionRefresh` → `@@initialState.refresh()`** 重跑 `getInitialState`，在 **有 token** 时拉 **`fetchUserInfo`**（详见该文档「为何客户端从免认证跳进认证页后会拉取用户权限」）。
+
 ### 权限判断逻辑（详细）
 
 ```

package/generators/micro-react/templates/apps/layout/docs/feature-/350/267/257/347/224/261/346/235/203/351/231/220/346/227/245/345/277/227.md

@@ -9,14 +9,14 @@
 1. **`routePermission`**：`BasicLayout` 中 **`isForbidden` 路由权限判定**（为何放行 / 为何 403）。
 2. **`menuFilter`**：`filterMenuItems` 中**被隐藏的菜单项**及**隐藏原因**（侧栏不可见条目）。
 
-日志均经 `layoutLogger` 输出，**仅开发环境生效**，生产构建无控制台输出。
+日志均经 `layoutLogger` 输出；**默认仅开发环境**会在控制台看到 `log`；生产首屏带 `?debug=1`（等）时行为与开发一致，见 [日志与常量](./arch-日志与常量.md)。
 
 ## 技术方案
 
 ### 技术栈
 
 - 框架：React 18 + @umijs/max
-- 日志：`apps/layout/src/common/logger.ts` 的 `layoutLogger`（`NODE_ENV === 'development'` 时 `console.log`）
+- 日志：`apps/layout/src/common/logger.ts` 的 `layoutLogger`（开发环境或生产首屏 `debug` query 时输出 `log`）
 
 ### 核心实现
 
@@ -142,13 +142,13 @@ menuFilter
 | 决策点 | 选择 | 理由 |
 |--------|------|------|
 | 日志前缀 | 固定 `'routePermission'` + 对象载荷 | 可过滤、可结构化，便于 AI/人工检索 |
-| 生产环境 | 静默 | `layoutLogger` 在 `production` 下不输出 |
+| 生产环境 | 默认静默 `log` | `layoutLogger` 在 production 下 `log`/`info`/`warn` 为 noop；首屏 `?debug=1` 等同开发 |
 | 无 `currentRoute` 不打日志 | 跳过 | 静态路由访问频繁，避免噪音 |
 | `menuFilter` 与超管/关权限 | 不打 | 无过滤效果时无隐藏项可记 |
 
 ## 已知限制与待改进
 
-- 日志仅在**开发环境**可见；线上问题需依赖 Sentry 或其它监控，不在本功能内。
+- **默认**仅开发环境会在控制台看到本功能的 `log`；生产首屏带 `?debug=1`（等）时亦会输出，见 [日志与常量](./arch-日志与常量.md)。线上问题仍主要依赖 Sentry 或其它监控。
 - `renderContent` 另有 `renderContent:` 日志，与 `routePermission` 独立，排查时可同时参考。
 
 ## 注意事项

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

@@ -22,6 +22,7 @@ import {
   type ILang,
 } from '<%= packageScope %>/common-intl';
 import * as CommonIntl from '<%= packageScope %>/common-intl';
+import { resolveAuthCheckPath } from './common/auth/auth-check-path';
 import { getStoredAuthToken } from './common/auth/auth-manager';
 import type { IUserInfo } from './common/auth/type';
 import { fetchUserInfo } from './services/user';
@@ -210,16 +211,21 @@ export async function getInitialState(): Promise<{
   };
 
   const { location } = history;
-  const noAuthRoute = isNoAuthRoute(location.pathname);
-  const skipAuth = noAuthRoute || isPageAuthFree(location.pathname);
+  // 如果当前路径是 / 且配置了 defaultPath（onRouteChange 会立即重定向），
+  // 用目标路径判断是否需要认证，避免用免认证的兜底页绕过目标页的认证要求（与 resolveAuthCheckPath、sso handleAuthFailureRedirect 一致）
+  const authCheckPath = resolveAuthCheckPath(location.pathname);
+
+  const noAuthRoute = isNoAuthRoute(authCheckPath);
+  const skipAuth = noAuthRoute || isPageAuthFree(authCheckPath);
 
   // 非免认证路由：走 SSO 流程
   if (!skipAuth) {
     await ensureSsoSession();
   }
 
-  // 有 token 就获取用户信息（登录后 refresh、免认证页同样需要 currentUser：
-  // 如 PermissionFilter / MicroAppLoader 注入子应用的 button_perms）
+  // 仅在「需认证」路径且本地已有 token 时拉取用户信息（登录态刷新等）。
+  // 免认证 / 页面级免认证路径不强制 SSO，本地未必有 token；不进入本分支则无 currentUser，
+  // PermissionFilter、MicroAppLoader 注入子应用的 button_perms 等按无登录用户（无权限）处理。
   if (getStoredAuthToken() && !skipAuth) {
     const userInfo = await fetchUserInfoFn();
     if (userInfo) {

package/generators/micro-react/templates/apps/layout/src/common/auth/auth-check-path.ts

@@ -0,0 +1,14 @@
+/**
+ * 与 `app.tsx` 中 `getInitialState` 的鉴权路径语义一致：
+ * 访问 `/` 且配置了 `window.__MICO_CONFIG__.defaultPath`（非 `/`）时，`onRouteChange` 会 `replace` 到该路径，
+ * 首屏 `location.pathname` 可能仍为 `/`，但免认证 / SSO 失败重定向等判断应以**目标路径**为准。
+ */
+export function resolveAuthCheckPath(pathname: string): string {
+  if (typeof window === 'undefined') {
+    return pathname;
+  }
+  const defaultPath = window.__MICO_CONFIG__?.defaultPath;
+  const willRedirectToDefault =
+    pathname === '/' && !!defaultPath && defaultPath !== '/';
+  return willRedirectToDefault ? defaultPath : pathname;
+}

package/generators/micro-react/templates/apps/layout/src/common/auth/index.ts

@@ -6,6 +6,7 @@ import { clearStoredTenantCode } from './tenant';
 
 // 导出 STORAGE_KEYS 常量
 export { STORAGE_KEYS } from '../../constants';
+export { resolveAuthCheckPath } from './auth-check-path';
 
 export function logout(): void {
   clearStoredTokens();

package/generators/micro-react/templates/apps/layout/src/common/logger.ts

@@ -1,37 +1,70 @@
 /**
  * 日志工具
- * 仅在开发环境下输出日志，生产环境自动静默
+ * - 开发环境：全量输出
+ * - 生产环境：默认仅 `error` 带前缀输出；可在**首屏 URL** 带 query 打开全量 `log` / `info` / `warn`（与 dev 一致）
  *
- * 使用 bind 保持原始调用位置，避免错误栈指向 logger 内部
+ * 生产开启方式：首次进入页面时地址栏带 `?debug=1`（或 `debug=true` / `yes`），
+ * 在**本 JS 模块加载时刻**解析一次并固定，后续路由或 query 变更**不会**再切换日志级别（需整页刷新带参 URL）。
+ *
+ * **安全与合规**：`debug` 仅用于临时排障；全量日志可能在控制台暴露业务或个人信息，**勿长期公开或转发**带 `debug` 的生产链接；若接入日志采集需自行脱敏。
+ *
+ * 使用 bind 保持原始调用位置，避免错误栈指向 logger 内部（在开启详细日志时）
  */
 
 const isDev = process.env.NODE_ENV === 'development';
 
-// 空操作函数（生产环境使用）
-const noop = (): void => {};
+/** Query 参数名；勿随意改名以免已分享的排障链接失效 */
+export const DEBUG_LOGS_QUERY_KEY = 'debug';
 
-/**
- * 创建带前缀的日志函数
- * 使用 bind 绑定前缀，保持控制台显示正确的调用位置
- */
-const createLogger = (prefix: string) => {
-  const formattedPrefix = `[${prefix}]`;
-  if (!isDev) {
-    // 生产环境返回空操作，但 error 仍然输出（便于生产排查）
-    return {
-      log: noop,
-      info: noop,
-      warn: noop,
-      error: console.error.bind(console, new Error(formattedPrefix)),
-    };
+/** 模块初始化时读取一次 `location.search`，之后不变 */
+function readVerboseDebugQueryOnce(): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+  try {
+    const v = new URLSearchParams(window.location.search).get(DEBUG_LOGS_QUERY_KEY);
+    if (v == null || v === '') {
+      return false;
+    }
+    const normalized = v.toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+  } catch {
+    return false;
   }
+}
+
+/** 开发环境，或生产环境首屏 URL 已带 `debug` 开关（模块加载时确定）；供业务侧按需分支 */
+export const isLayoutDebugLogsEnabled: boolean = isDev || readVerboseDebugQueryOnce();
+
+const noop = (): void => {};
 
+function createVerboseHandlers(formattedPrefix: string) {
   return {
     log: console.log.bind(console, formattedPrefix),
     info: console.info.bind(console, formattedPrefix),
     warn: console.warn.bind(console, formattedPrefix),
     error: console.error.bind(console, formattedPrefix),
   };
+}
+
+function createQuietHandlers(formattedPrefix: string) {
+  return {
+    log: noop,
+    info: noop,
+    warn: noop,
+    error: console.error.bind(console, formattedPrefix),
+  };
+}
+
+/**
+ * 创建带前缀的日志函数
+ * 使用 bind 绑定前缀，保持控制台显示正确的调用位置（在开启详细日志时）
+ */
+const createLogger = (prefix: string) => {
+  const formattedPrefix = `[${prefix}]`;
+  return isLayoutDebugLogsEnabled
+    ? createVerboseHandlers(formattedPrefix)
+    : createQuietHandlers(formattedPrefix);
 };
 
 // 预定义的日志实例

package/generators/micro-react/templates/apps/layout/src/common/request/sso.ts

@@ -3,6 +3,7 @@
  */
 
 import { request as rawRequest } from '@umijs/max';
+import { resolveAuthCheckPath } from '@/common/auth/auth-check-path';
 import {
   maybePersistTokens,
   setStoredAuthToken,
@@ -59,14 +60,16 @@ const performSsoRedirect = (): void => {
 export const handleAuthFailureRedirect = (): void => {
   if (typeof window === 'undefined') return;
 
-  // 如果当前路由在免认证列表中，不触发 SSO 重定向
-  if (isNoAuthRoute(window.location.pathname)) {
-    console.log('[SSO] 当前路由在免认证列表中，跳过 SSO 重定向');
+  const authCheckPath = resolveAuthCheckPath(window.location.pathname);
+
+  // 与 getInitialState 一致：用 authCheckPath 判断，避免「/ + defaultPath」首屏仍按 / 误判为免认证
+  if (isNoAuthRoute(authCheckPath)) {
+    console.log('[SSO] 当前路由在免认证列表中，跳过 SSO 重定向', { authCheckPath });
     return;
   }
 
-  if (isPageAuthFree(window.location.pathname)) {
-    console.log('[SSO] 页面 accessControlEnabled=false，跳过 SSO 重定向');
+  if (isPageAuthFree(authCheckPath)) {
+    console.log('[SSO] 页面 accessControlEnabled=false，跳过 SSO 重定向', { authCheckPath });
     return;
   }
 

package/generators/micro-react/templates/package.json

@@ -32,7 +32,7 @@
   "devDependencies": {
     "@commitlint/cli": "^19.5.0",
     "@commitlint/config-conventional": "^19.5.0",
-    "@common-web/sentry": "0.0.7",
+    "@common-web/sentry": "0.0.8",
     "@sentry/webpack-plugin": "^4.9.1",
 		"@typescript-eslint/eslint-plugin": "^8.54.0",
 		"@typescript-eslint/parser": "^8.54.0",

package/generators/subapp-react/README.md

@@ -0,0 +1,43 @@
+# subapp-react 生成器
+
+在已有 Monorepo 的 `apps/` 下创建 React 子应用。详细说明见 [docs/generators.md#subapp-react](../../docs/generators.md#subapp-react)。
+
+## 快速索引
+
+| 文件 | 职责 |
+|---|---|
+| `index.js` | 生成器主体；含三处对主应用的联动修改 |
+| `meta.json` | `mico list` 展示信息 |
+| `ignore-list.json` | 模板过滤清单 |
+| `templates/homepage/` | 模板根，本生成器以 `homepage` 作为模板目录名 |
+
+## 使用
+
+```bash
+cd <monorepo-root>
+mico create subapp-react
+```
+
+要求 monorepo 根包含 `apps/` 目录。
+
+## 联动修改
+
+非 dry-run 时会尝试原位修改主应用以下文件（任一缺失静默跳过）：
+
+| 文件 | 修改 |
+|---|---|
+| `dev.preset.json` | 向 `presets.full.apps` 追加 `appName` |
+| `apps/layout/mock/pages.ts` | 在兜底路由前插入页面项（`routeKey = cs_web_menu_<snake>_page`） |
+| `apps/layout/mock/api.mock.ts` | 将 `routeKey` 加入 `menu_perms` |
+
+修改完成后 prettier 仅格式化这两个 mock 文件。
+
+## 模板同步
+
+从源仓库的 `apps/homepage` 同步模板：
+
+```bash
+pnpm sync:subapp-react-template -- <source-project-root>
+```
+
+详见 [docs/scripts.md](../../docs/scripts.md)。

package/generators/subapp-react/index.js

@@ -168,6 +168,8 @@ module.exports = class extends Generator {
       const templateData = {
         appName: this.appName,
         AppName: this.appNamePascal,
+        // 用于 MFSU mfName 等需要合法 JS 标识符的场景（不允许 `-`）
+        appNameSnake: this.appName.replace(/-/g, '_'),
         packageScope: this.packageScope,
         devPort: this.devPort,
         micoUiVersion: `^${micoUiVer}`,

package/generators/subapp-react/templates/homepage/README.md

@@ -64,7 +64,7 @@ PORT=8001
 │   ├── app.tsx              # Umi 运行时配置
 │   ├── assets/              # 静态资源
 │   ├── common/              # 公共模块
-│   │   ├── logger.ts        # 日志工具
+│   │   ├── logger.ts        # 日志工具（与 layout 一致：生产首屏 `?debug=1` 可开全量 log/info/warn）
 │   │   ├── mainApp.ts       # 主应用通信
 │   │   └── request.ts       # 请求封装
 │   ├── pages/               # 页面组件
@@ -75,6 +75,10 @@ PORT=8001
 └── tsconfig.json
 ```
 
+## 日志（logger）
+
+与 monorepo 内 **layout** 的 `src/common/logger.ts` 规则对齐：生产默认静默 `log`/`info`/`warn`，`error` 仍输出；首屏 URL 带 **`?debug=1`**（或 `debug=true` / `yes`）可在模块加载时打开全量日志。详见主应用文档 `apps/layout/docs/arch-日志与常量.md`（生成项目后路径以仓库为准）。
+
 ## 微前端配置
 
 本应用作为 qiankun 子应用运行，关键配置：

package/generators/subapp-react/templates/homepage/config/config.dev.ts

@@ -61,6 +61,26 @@ const config: ReturnType<typeof defineConfig> = {
     // @mico-platform/ui 基础样式（使用运行时解析的最新版本号，避免 latest 标签）
     `https://cdn-portal.micoplatform.com/portal-center/mico-ui/${MICO_UI_VERSION}/ui/dist/css/mico-ui.min.css`,
   ],
+
+  /**
+   * @name MFSU 配置
+   * @description
+   * - mfName: 唯一名隔离微前端 runtime，避免多应用共存时 MFSU 容器冲突
+   * - exclude:
+   *   - `@mico-platform/theme`：theme 子路径解析
+   *   - `@mico-platform/ui`：尽量与主应用一起编译
+   *   - `<%= packageScope %>/*`：workspace 包走 webpack 编译，开发态可在 DevTools 直接定位到 packages/* 源码
+   * - shared: React 单例，确保 MFSU 预打包里的组件（如 UI 库）与应用共用同一份 React，否则 useContext 报 null
+   * @doc https://umijs.org/docs/api/config#mfsu
+   */
+  mfsu: {
+    mfName: 'mf_<%= appNameSnake %>',
+    exclude: ['@mico-platform/theme', '@mico-platform/ui', /^<%= packageScope %>\//],
+    shared: {
+      react: { singleton: true },
+      'react-dom': { singleton: true },
+    },
+  },
 };
 
 export default defineConfig(config);

package/generators/subapp-react/templates/homepage/config/config.ts

@@ -118,21 +118,6 @@ const config: ReturnType<typeof defineConfig> = {
    * @description 使用 @mico-platform/ui 的 babel preset，实现组件与图标的按需加载
    */
   extraBabelPresets: ['@mico-platform/ui/babel-preset'],
-
-  /**
-   * @name MFSU 配置
-   * @description
-   * - exclude: theme 子路径解析；ui 尽量与主应用一起编译
-   * - shared: React 单例，确保 MFSU 预打包里的组件（如 UI 库）与应用共用同一份 React，否则 useContext 报 null
-   * @doc https://umijs.org/docs/guides/mfsu
-   */
-  mfsu: {
-    exclude: ['@mico-platform/theme', '@mico-platform/ui'],
-    shared: {
-      react: { singleton: true },
-      'react-dom': { singleton: true },
-    },
-  },
 };
 
 export default defineConfig(config);

package/generators/subapp-react/templates/homepage/src/common/logger.ts

@@ -1,38 +1,70 @@
 /**
  * 日志工具
- * 仅在开发环境下输出日志，生产环境自动静默
+ * - 开发环境：全量输出
+ * - 生产环境：默认仅 `error` 带前缀输出；可在**首屏 URL** 带 query 打开全量 `log` / `info` / `warn`（与 layout `apps/layout` 的 logger 行为一致）
  *
- * 使用 bind 保持原始调用位置，避免错误栈指向 logger 内部
+ * 生产开启方式：首次进入页面时地址栏带 `?debug=1`（或 `debug=true` / `yes`），
+ * 在**本 JS 模块加载时刻**解析一次并固定，后续路由或 query 变更**不会**再切换日志级别（需整页刷新带参 URL）。
+ *
+ * **安全与合规**：`debug` 仅用于临时排障；全量日志可能在控制台暴露业务或个人信息，**勿长期公开或转发**带 `debug` 的生产链接；若接入日志采集需自行脱敏。
+ *
+ * 使用 bind 保持原始调用位置，避免错误栈指向 logger 内部（在开启详细日志时）
  */
 
 const isDev = process.env.NODE_ENV === 'development';
 
-// 空操作函数（生产环境使用）
-const noop = (): void => {};
+/** Query 参数名；与主应用 layout 一致，勿随意改名以免已分享的排障链接失效 */
+export const DEBUG_LOGS_QUERY_KEY = 'debug';
 
-/**
- * 创建带前缀的日志函数
- * 使用 bind 绑定前缀，保持控制台显示正确的调用位置
- */
-const createLogger = (prefix: string) => {
-  if (!isDev) {
-    // 生产环境返回空操作
-    return {
-      log: noop,
-      info: noop,
-      warn: noop,
-      error: noop,
-    };
+/** 模块初始化时读取一次 `location.search`，之后不变 */
+function readVerboseDebugQueryOnce(): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+  try {
+    const v = new URLSearchParams(window.location.search).get(DEBUG_LOGS_QUERY_KEY);
+    if (v == null || v === '') {
+      return false;
+    }
+    const normalized = v.toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+  } catch {
+    return false;
   }
+}
 
-  const formattedPrefix = `[${prefix}]`;
+/** 开发环境，或生产环境首屏 URL 已带 `debug` 开关（模块加载时确定）；供业务侧按需分支 */
+export const isAppDebugLogsEnabled: boolean = isDev || readVerboseDebugQueryOnce();
+
+const noop = (): void => {};
 
+function createVerboseHandlers(formattedPrefix: string) {
   return {
     log: console.log.bind(console, formattedPrefix),
     info: console.info.bind(console, formattedPrefix),
     warn: console.warn.bind(console, formattedPrefix),
     error: console.error.bind(console, formattedPrefix),
   };
+}
+
+function createQuietHandlers(formattedPrefix: string) {
+  return {
+    log: noop,
+    info: noop,
+    warn: noop,
+    error: console.error.bind(console, formattedPrefix),
+  };
+}
+
+/**
+ * 创建带前缀的日志函数
+ * 使用 bind 绑定前缀，保持控制台显示正确的调用位置（在开启详细日志时）
+ */
+const createLogger = (prefix: string) => {
+  const formattedPrefix = `[${prefix}]`;
+  return isAppDebugLogsEnabled
+    ? createVerboseHandlers(formattedPrefix)
+    : createQuietHandlers(formattedPrefix);
 };
 
 // 预定义的日志实例

package/generators/subapp-umd/README.md

@@ -0,0 +1,37 @@
+# subapp-umd 生成器
+
+在已有 Monorepo 的 `packages/` 下创建 UMD 组件包（Webpack 构建）。详见 [docs/generators.md#subapp-umd](../../docs/generators.md#subapp-umd)。
+
+## 快速索引
+
+| 文件 | 职责 |
+|---|---|
+| `index.js` | 生成器主体；无跨模块联动修改 |
+| `meta.json` | `mico list` 展示信息 |
+| `ignore-list.json` | 模板过滤清单 |
+| `templates/` | 模板根 |
+
+## 使用
+
+```bash
+cd <monorepo-root>
+mico create subapp-umd
+```
+
+要求 monorepo 根包含 `packages/` 目录。
+
+## Prompt 默认值
+
+| name | 默认 |
+|---|---|
+| `appName` | `.micorc.defaultUmdName` ?? `'my-widget'` |
+| `umdGlobalName` | `toPascal(appName)` |
+| `packageScope` | `.micorc.packageScope` ?? `detectPackageScope()` ?? `'@my-project'` |
+| `devPort` | `.micorc.umdDevPort` ?? `'9100'` |
+
+## 运行产物
+
+| URL | 说明 |
+|---|---|
+| `http://localhost:<devPort>/` | HTML 预览页 |
+| `http://localhost:<devPort>/<appName>.umd.js` | UMD JS，供主应用通过 `jsUrls` 接入 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generator-mico-cli",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "Yeoman generator for Mico CLI projects",
   "keywords": [
     "yeoman-generator",