generator-mico-cli 0.2.31 → 0.2.33

package/generators/h5-react/templates/scripts/gateway.ts

@@ -0,0 +1,241 @@
+/**
+ * 本地开发网关脚本：读取根目录 `page.config.ts`，为每个 `apps/<key>` 分配端口并启动 `pnpm dev`，
+ * 再启动统一 HTTP/WebSocket 代理（默认从 3000 起占端口），通过路径前缀将流量转发到对应子应用。
+ */
+import http from 'http';
+import path from 'path';
+import fs from 'fs';
+import { spawn, type ChildProcessWithoutNullStreams } from 'child_process';
+import httpProxy from 'http-proxy';
+import portfinder from 'portfinder';
+import chalk from 'chalk';
+
+/**
+ * 仓库根目录的 `page.config.ts`：键名为子应用目录名（对应 `apps/<key>`）。
+ */
+import pageConfig from '../page.config.ts';
+
+/** 单个子应用在网关中的运行时元数据（端口、路径前缀等）。 */
+interface PageConfig {
+  key: string;
+  name: string;
+  fullPath: string;
+  prefixPath: string;
+  port: number;
+}
+
+/**
+ * 遍历 `page.config.ts` 的每个键，在 `apps/<key>` 下读取 `package.json`，
+ * 并为每个子应用从 4000 起顺序分配可用端口，生成 `PageConfig` 列表。
+ */
+async function formatPageConfig(): Promise<PageConfig[]> {
+  const pageConfigs: PageConfig[] = [];
+  const appPath = path.join(process.cwd(), 'apps');
+  let basePort = 4000;
+  for (const [key, value] of Object.entries(pageConfig)) {
+    const appPackagePath = path.join(appPath, key, 'package.json');
+    try {
+      const appPackage = await fs.promises.readFile(appPackagePath, 'utf8');
+      const appPackageJson = JSON.parse(appPackage);
+      const port = await portfinder.getPortPromise({ port: basePort });
+      basePort = port + 1;
+      const pageConfig: PageConfig = {
+        key,
+        name: appPackageJson.name,
+        fullPath: path.join(appPath, key),
+        prefixPath: `/${key}`,
+        port,
+      };
+      pageConfigs.push(pageConfig);
+    } catch (error) {
+      console.error(`[${key}] 读取 package.json 失败: ${(error as Error).message}`);
+      continue;
+    }
+  }
+  return pageConfigs;
+}
+
+/**
+ * 在各自 `cwd` 下执行 `pnpm run dev -p <port>` 启动每个子应用。
+ * 监听 stdout 出现 Ready/successfully 时视为已就绪并 resolve（stderr 常含非错误日志，见下方）。
+ */
+async function runApp(pageConfigs: PageConfig[]) {
+  const promises = pageConfigs.map(config => {
+    return new Promise<ChildProcessWithoutNullStreams>((resolve, reject) => {
+      const child = spawn('pnpm', ['run', 'dev'], {
+        cwd: config.fullPath,
+        env: { ...process.env, PORT: String(config.port) },
+        // 如需在终端直接看到子应用原始输出，可改为 stdio: 'inherit'（需自行调整就绪判断逻辑）
+        shell: process.platform === 'win32',
+      });
+      child.on('error', (err) => {
+        console.error(chalk.red(`[${config.key}] 子进程启动失败:`), err.message);
+      });
+      child.on('exit', (code, signal) => {
+        if (code !== null && code !== 0) {
+          console.error(chalk.red(`[${config.key}] 子进程退出 code=${code} signal=${signal}`));
+        }
+      });
+      child.stdout.on('data', (data) => {
+        const msg = data.toString();
+        console.log(`${chalk.green(`[${config.key}]`)} ${msg}`);
+        const reg = /Local: http:\/\/localhost:(\d+)/
+        const match = msg.match(reg);
+        if (match) {
+          const port = match[1];
+          config.port = parseInt(port);
+          setTimeout(() => {
+            resolve(child)
+          });
+        }
+      });
+      child.stderr.on('data', (data) => {
+        const msg = data.toString();
+        console.log(`${chalk.dim(`[${config.key}]`)} ${msg}`);
+      });
+    })
+  })
+  return Promise.all(promises).then((childs) => {
+    console.log(chalk.green('所有子应用已启动'))
+    pageConfigs.forEach(config => {
+      console.log(`${chalk.green(`[${config.key}]`)} 子应用已启动：${chalk.blue(`http://127.0.0.1:${config.port}`)}`)
+    })
+    return childs
+  })
+}
+
+/**
+ * 根据当前请求解析应转发到的子应用：优先用路径匹配；无 Referer 或 Referer 为根时用请求路径；
+ * 否则用 Referer 的路径（便于静态资源等请求仍落到同一子应用）。无匹配时回退上次目标或第一个应用。
+ */
+function getTargetByRes(req: http.IncomingMessage, pageConfigs: PageConfig[], lastTargetPageConfig: PageConfig | null) {
+  const pathname = urlPathname(req.url) ?? '/';
+  const refererPathname = urlPathname(req.headers.referer)
+  const targetPathname = (
+    !refererPathname || refererPathname === '/'
+      ? pathname
+      : refererPathname
+  )
+  const pathConfig = getTargetByPath(targetPathname, pageConfigs);
+  return pathConfig ?? lastTargetPageConfig ?? pageConfigs[0]!;
+}
+
+/** 判断 `pathname` 是否属于某子应用（等于 `prefixPath` 或以其为前缀）。 */
+function getTargetByPath(pathname: string, pageConfigs: PageConfig[]) {
+  for (const config of pageConfigs) {
+    if (pathname === config.prefixPath || pathname.startsWith(`${config.prefixPath}/`)) {
+      return config;
+    }
+  }
+  return null;
+}
+
+/** 从完整 URL 或相对路径中解析 pathname；无效输入返回 `null`。 */
+function urlPathname(url: string | undefined) {
+  if (!url) return null;
+  try {
+    return new URL(url, 'http://127.0.0.1').pathname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 转发到子应用 dev 服务器前去掉网关层前缀（如 `/app`），使子应用收到根路径下的请求。
+ */
+function rewriteUrlForTarget(rawUrl: string | undefined, target: PageConfig): string {
+  if (!rawUrl) return '/';
+  const url = new URL(rawUrl, 'http://127.0.0.1');
+  url.pathname = url.pathname.replace(new RegExp(`^${target.prefixPath}`), '') || '/';
+  return url.toString();
+}
+
+/**
+ * 在可用端口（默认从 3000 起探测）上启动 HTTP 代理，支持 WebSocket；
+ * 根路径 `/` 返回各子应用入口链接，其余请求按路由规则转发到对应本地端口。
+ */
+async function runProxyServer(pageConfigs: PageConfig[]) {
+  const proxy = httpProxy.createProxyServer({ ws: true });
+  proxy.on('error', (err, req, res) => {
+    console.error(chalk.red('[proxy error]'), err.message);
+  });
+
+  let lastTargetPageConfig: PageConfig | null = null;
+
+  const server = http.createServer((req, res) => {
+    const pathname = urlPathname(req.url) ?? '/';
+    if (pathname === '/' || pathname === '') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      const links = pageConfigs
+        .map((c) => `  <li><a href="${c.prefixPath}">${c.prefixPath}</a> (${c.key})</li>`)
+        .join('\n');
+      res.end(
+        `<!DOCTYPE html><html><body><h1>子应用入口</h1><ul>\n${links}\n</ul></body></html>`
+      );
+      return;
+    }
+
+    lastTargetPageConfig = getTargetByRes(req, pageConfigs, lastTargetPageConfig);
+    req.url = rewriteUrlForTarget(req.url, lastTargetPageConfig);
+    proxy.web(req, res, {
+      target: `http://127.0.0.1:${lastTargetPageConfig.port}`,
+      changeOrigin: true,
+    });
+  });
+
+  server.on('upgrade', (req, socket, head) => {
+    lastTargetPageConfig = getTargetByRes(req, pageConfigs, lastTargetPageConfig);
+    req.url = rewriteUrlForTarget(req.url, lastTargetPageConfig);
+    proxy.ws(req, socket, head, {
+      target: `http://127.0.0.1:${lastTargetPageConfig.port}`,
+    });
+  });
+  const port = await portfinder.getPortPromise({ port: 3000 });
+  server.listen(port, () => {
+    console.log(chalk.green(`[gateway] 代理服务已启动 端口：${chalk.blue(port)}`));
+    console.log(`>>> 统一通过代理访问: ${chalk.blue(`http://127.0.0.1:${port}`)}`);
+    pageConfigs.forEach(config => {
+      console.log(`${chalk.green(`[${config.key}]`)} 子应用访问路径：${chalk.blue(`http://127.0.0.1:${port}${config.prefixPath}`)}`)
+    })
+  });
+  return server;
+}
+
+/**
+ * 在收到 SIGINT（Ctrl+C）或 SIGTERM 时关闭代理 `server` 并终止所有子进程；
+ * `server.close` 若迟迟不回调，3 秒后强制 `process.exit(0)`。
+ */
+function listenerClose(server: http.Server, childs: ChildProcessWithoutNullStreams[]) {
+  let cleaning = false;
+  const cleanup = () => {
+    if (cleaning) return;
+    cleaning = true;
+
+    server.close(() => {
+      childs.forEach((child) => {
+        if (child.killed) return;
+        child.kill('SIGTERM');
+      });
+      process.exit(0);
+    });
+    // 若 server.close 回调未及时触发，超时后强制退出
+    setTimeout(() => process.exit(0), 3000);
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}
+
+/** 加载配置 → 拉起子应用 → 启动网关代理 → 注册退出清理。 */
+async function main() {
+  const pageConfigs = await formatPageConfig();
+  if (pageConfigs.length === 0) {
+    console.error('未开启任何子应用，请检查 page.config.ts 配置');
+    process.exit(1);
+  }
+  const childs = await runApp(pageConfigs);
+  const proxyServer = await runProxyServer(pageConfigs);
+  listenerClose(proxyServer, childs);
+}
+
+main()

package/generators/h5-react/templates/turbo.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalEnv": [
+    "CDN_PUBLIC_PATH",
+    "BRANCH_OR_TAG",
+    "VERSION",
+    "SENTRY_AUTH_TOKEN"
+  ],
+  "envMode": "loose",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.production",
+        ".env.production.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "build:development": {
+      "dependsOn": ["^build:development"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.development",
+        ".env.development.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "build:testing": {
+      "dependsOn": ["^build:testing"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.testing",
+        ".env.testing.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "build:production": {
+      "dependsOn": ["^build:production"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.production",
+        ".env.production.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "lint": {
+      "outputs": []
+    },
+    "lint:fix": {
+      "outputs": []
+    }
+  }
+}

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

@@ -25,6 +25,8 @@ const config: ReturnType<typeof defineConfig> = {
           logo: '',
           apiBaseUrl: '',
           defaultPath: '',
+          // 布局模式, 默认 'side'，可选 'mix'
+          // layoutMode: 'mix',
           // 免认证路由（跳过 SSO 登录），支持 /* 前缀匹配
           // noAuthRouteList: ['/*'],
           // 免权限校验路由（跳过菜单权限检查），与 mock pages 中 accessControlEnabled 示例一致时可按需配置

package/generators/micro-react/templates/apps/layout/docs/feature-/345/244/264/351/203/250/344/270/200/347/272/247/345/257/274/350/210/252/345/270/203/345/261/200.md

@@ -0,0 +1,166 @@
+# 头部一级导航布局（layoutMode: mix）
+
+> 创建时间：2026-06-15
+
+## 功能概述
+
+为主布局新增可配置的 **mix 布局模式**：将菜单树的**一级目录**渲染为头部 Tab，对应一级目录下的**子级目录**渲染在侧边栏。切换头部 Tab 时侧边栏跟随变化为对应一级目录的子树。通过 `window.__MICO_CONFIG__.layoutMode` 开关控制，默认 `side`（经典左侧完整目录树），不配置时行为与旧版完全一致。
+
+## 技术方案
+
+### 技术栈
+
+- 框架：React 18 + @umijs/max
+- UI 组件：@mico-platform/ui（`Tabs` 一级导航）
+- 状态管理：完全由路由 `location.pathname` 驱动，**无新增全局状态**
+
+### 核心实现
+
+1. **配置开关**：`isMixLayout()` 读取 `window.__MICO_CONFIG__.layoutMode`，仅 `'mix'` 时启用新布局。
+2. **数据共用**：抽取 `useFilteredMenuItems()`，统一「权限过滤 + 解析」后的菜单树，供头部一级导航与侧边栏共用，避免重复解析。
+3. **激活一级推导**：`getActiveTopKey(items, pathname)` 复用 `findMenuKeyByPath` 的祖先链 `openKeys[0]` 推导当前激活的一级 key；未命中（403/404、首页、仅在 PAGES 不在 MENUS 的页面）返回 `undefined`，不高亮、不渲染子树。
+4. **头部一级导航**：mix 模式下渲染顶层菜单项为 `Tabs`，高亮跟随路由；点击 Tab 经 `findFirstLeaf` 取该一级下第一个可跳转叶子——`page` 走 `history.push`，`link` 走 `window.open`。
+5. **侧边栏子树**：mix 模式下侧边栏只渲染激活一级的 `children`；该一级**无子目录时隐藏侧边栏**（`--sider-width` 置 0，内容区占满）。
+
+### 数据流
+
+```
+location.pathname
+    │
+    ├── 头部：getActiveTopKey(全树, pathname) → 高亮对应一级 Tab
+    │         点击 Tab → findFirstLeaf(一级) → page: history.push / link: window.open
+    │
+    └── 侧边栏：getActiveTopKey(全树, pathname) → 取该一级 children 渲染
+              children 为空 → hideSider（--sider-width: 0px，不渲染 Sider）
+
+切 Tab = 路由跳转 → pathname 变化 → 头部高亮与侧边栏子树同步刷新
+```
+
+### 兼容策略
+
+```
+isMixLayout() === false（默认 / layoutMode 未配置 / = 'side'）
+    ├── 头部：不渲染一级导航（Logo 保持 margin-right:auto 原布局）
+    └── 侧边栏：渲染完整菜单树，hideSider 恒为 false  ← 与旧版完全一致
+```
+
+## 文件清单
+
+### 新增文件
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/hooks/useFilteredMenuItems.ts` | 权限过滤 + 解析后的菜单树 Hook，头部与侧边栏共用 |
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+| --- | --- |
+| `src/common/menu/types.ts` | `__MICO_CONFIG__` 新增 `layoutMode?: 'side' \| 'mix'` |
+| `src/constants/index.ts` | 新增 `TLayoutMode`、`getLayoutMode()`、`isMixLayout()` |
+| `src/common/menu/parser.ts` | 新增 `getActiveTopKey()`、`findFirstLeaf()` |
+| `src/layouts/components/header/index.tsx` | mix 模式渲染一级 `Tabs`，按叶子类型分流跳转；mix 时根节点加 `layout-header--mix` 类 |
+| `src/layouts/components/header/index.less` | 一级导航 Tab 样式（对齐设计稿）；mix 模式 Logo 列宽对齐侧边栏 |
+| `src/layouts/components/menu/index.tsx` | 改用 `useFilteredMenuItems()`；mix 模式渲染激活一级子树；无子目录时隐藏 Sider |
+| `config/config.dev.ts` | `__MICO_CONFIG__` 增加 `layoutMode` 注释示例 |
+
+## API / 组件接口
+
+### 配置项
+
+```typescript
+interface Window {
+  __MICO_CONFIG__?: {
+    /**
+     * 布局模式
+     * - 'side'（默认）：经典左侧完整目录树
+     * - 'mix'：一级目录在头部 Tab，子级目录在侧边栏
+     */
+    layoutMode?: 'side' | 'mix';
+  };
+}
+```
+
+### 常量函数（`constants/index.ts`）
+
+```typescript
+type TLayoutMode = 'side' | 'mix';
+
+/** 读取布局模式，未配置默认 'side' */
+function getLayoutMode(): TLayoutMode;
+
+/** 是否为「头部一级 + 侧边二级」混合布局 */
+function isMixLayout(): boolean;
+```
+
+### 菜单解析函数（`common/menu/parser.ts`）
+
+```typescript
+/** 根据当前路径推导激活的一级菜单 key；未命中返回 undefined */
+function getActiveTopKey(
+  items: ParsedMenuItem[],
+  pathname: string,
+): string | undefined;
+
+/** 查找一级菜单项下第一个可跳转的叶子节点（DFS，跳过 group 容器） */
+function findFirstLeaf(item: ParsedMenuItem): ParsedMenuItem | undefined;
+```
+
+### 共用 Hook（`hooks/useFilteredMenuItems.ts`）
+
+```typescript
+/** 权限过滤 + 解析后的菜单树，供侧边栏与头部一级导航共用 */
+function useFilteredMenuItems(): ParsedMenuItem[];
+```
+
+## 使用示例
+
+中台注入的 `window.__MICO_CONFIG__` 中开启 mix 布局：
+
+```html
+<script>
+  window.__MICO_CONFIG__ = {
+    appName: '示例平台',
+    layoutMode: 'mix', // 不配置或 'side' 即经典左侧目录树
+  };
+</script>
+```
+
+或在本地开发 `config/config.dev.ts` 的 `define` 中开启：
+
+```typescript
+'window.__MICO_CONFIG__': {
+  layoutMode: 'mix',
+},
+```
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| 激活态来源 | 完全由 `location.pathname` 推导 | 与 `AppTabs`、`useMenuState` 既有范式一致，零新增全局状态，路由天然驱动头部与侧栏同步 |
+| 数据共用 | 抽取 `useFilteredMenuItems()` | 头部与侧栏共用同一份过滤解析结果，避免重复解析与权限逻辑漂移 |
+| 一级导航组件 | `Tabs`（line 型） | 与设计稿一致，自动继承主题/国际化；与内容区多页签 `AppTabs` 功能不冲突，二者并存 |
+| Tab 点击跳转 | `findFirstLeaf` 按类型分流 | `page` 用 `history.push`，`link` 用 `window.open`，避免外链 URL 被推进路由 |
+| 未命中路由 | `getActiveTopKey` 返回 `undefined` | 403/404、首页等不误高亮、不渲染无关子树 |
+| 无子目录的一级 | 隐藏 Sider + `--sider-width: 0` | 内容区占满，避免空侧栏占位 |
+| Logo 列宽对齐 | 仅 `.layout-header--mix` 生效 | mix 下使一级导航起点与内容区左边界对齐；不影响 side 模式原布局 |
+
+## 已知限制与待改进
+
+- mix 模式下若某一级目录及其子级**全部为 group 容器**（无 page/link 叶子），点击该 Tab 不会触发跳转（`findFirstLeaf` 返回空）。
+- Logo 列宽按侧边栏展开态（`@sidebar-width`）对齐；侧栏折叠/隐藏时不会同步调整，对齐仅在展开态成立。
+- 头部一级 Tab 暂未处理 `disabled` 态（一级导航不会出现禁用项，故未实现）。
+
+## 注意事项
+
+- 默认 `side` 模式与旧版行为完全一致，升级零配置。
+- mix 模式不改动路由注册、权限校验、qiankun 加载逻辑，仅影响菜单的「呈现位置」。
+- 头部一级导航与内容区多页签 `AppTabs` 并存、互不冲突。
+- 切换头部 Tab 本质是路由跳转；若当前已在该一级下，点击同一 Tab 不会重复跳转（`Tabs` 仅在 activeTab 变化时触发 `onChange`）。
+
+## 相关文档
+
+- [路由与菜单解耦](./feature-路由与菜单解耦.md) - PAGES/MENUS 数据源、`getActiveTopKey` 依赖的菜单解析
+- [菜单权限控制](./feature-菜单权限控制.md) - `useFilteredMenuItems` 复用的权限过滤逻辑
+- [主题色切换](./feature-主题色切换.md) - 一级导航 Tab 样式使用的主题变量

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

@@ -36,6 +36,7 @@ import {
   clearRedirectCount,
   ensureSsoSession,
   handleAuthFailureRedirect,
+  SsoNetworkError,
 } from './common/request/sso';
 import { initTheme } from './common/theme';
 import MicroAppLoader from './components/MicroAppLoader';
@@ -220,7 +221,19 @@ export async function getInitialState(): Promise<{
 
   // 非免认证路由：走 SSO 流程
   if (!skipAuth) {
-    await ensureSsoSession();
+    try {
+      await ensureSsoSession();
+    } catch (error) {
+      // 仅 ticket 换 token 阶段的网络异常会抛出 SsoNetworkError，
+      // 在此显式拿到信号并触发带网络异常文案的兜底弹窗。
+      if (error instanceof SsoNetworkError) {
+        handleAuthFailureRedirect({ isNetworkError: true });
+        return {
+          fetchUserInfo: fetchUserInfoFn,
+        };
+      }
+      throw error;
+    }
   }
 
   // 仅在「需认证」路径且本地已有 token 时拉取用户信息（登录态刷新等）。
@@ -239,7 +252,12 @@ export async function getInitialState(): Promise<{
 
   // 非免认证路由且没有 token，跳转到 SSO 登录
   if (!skipAuth) {
-    handleAuthFailureRedirect();
+    const redirected = handleAuthFailureRedirect();
+    if (redirected) {
+      // 阻断渲染，等待浏览器导航卸载页面，
+      // 避免页面组件抢先发起被 401 的请求（如 Home 的业务系统列表）
+      await new Promise<never>(() => {});
+    }
     // 返回空状态，页面会被重定向
     return {
       fetchUserInfo: fetchUserInfoFn,

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

@@ -440,6 +440,42 @@ export const findRouteByPath = (
   return exact || bestWildcard?.route;
 };
 
+/**
+ * 查找一级菜单项下第一个可跳转的叶子节点
+ * 深度优先，跳过 group 容器，返回第一个带 path 的 page/link 节点
+ */
+export const findFirstLeaf = (
+  item: ParsedMenuItem,
+): ParsedMenuItem | undefined => {
+  if (item.type !== 'group' && item.path) {
+    return item;
+  }
+  if (item.children && item.children.length > 0) {
+    for (const child of item.children) {
+      const found = findFirstLeaf(child);
+      if (found) return found;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * 根据当前路径推导激活的一级菜单 key
+ * - 命中某个菜单项时，取其祖先链顶端（openKeys[0]）；自身即一级时取自身 key
+ * - 未命中时返回 undefined，不高亮任何一级（如 403/404、首页、仅在 PAGES 不在 MENUS 的页面）
+ */
+export const getActiveTopKey = (
+  items: ParsedMenuItem[],
+  pathname: string,
+): string | undefined => {
+  const result = findMenuKeyByPath(items, pathname);
+  if (result) {
+    return result.openKeys[0] ?? result.key;
+  }
+  // 未命中菜单树（如 403/404、首页、仅在 PAGES 不在 MENUS 的页面）：不高亮任何一级
+  return undefined;
+};
+
 /**
  * 根据路径查找对应的菜单项 key
  */

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

@@ -198,6 +198,12 @@ declare global {
       >;
       /** 默认重定向路径，访问 "/" 时自动跳转到此路径 */
       defaultPath?: string;
+      /**
+       * 布局模式
+       * - 'side'（默认）：经典左侧完整目录树
+       * - 'mix'：一级目录显示在头部 Tab，对应一级下的子级目录显示在侧边栏
+       */
+      layoutMode?: 'side' | 'mix';
       /**
        * 免认证路由列表（跳过 SSO 登录）
        * 支持精确匹配和前缀匹配（以 /* 结尾）

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

@@ -36,7 +36,7 @@ import {
 } from './interceptors';
 
 // SSO 相关
-import { handleAuthFailureRedirect } from './sso';
+import { handleAuthFailureRedirect, isRedirecting } from './sso';
 
 // Token 刷新相关
 import {
@@ -74,6 +74,12 @@ export const request = async <T = unknown>(
   url: string,
   options?: UnifiedRequestOptions,
 ): Promise<T> => {
+  // 正在执行 SSO 硬跳转时，挂起任何在途请求，
+  // 避免在浏览器导航卸载前发出被 401 的请求，进而触发重复 toast 与二次跳转
+  if (isRedirecting()) {
+    return new Promise<T>(() => {});
+  }
+
   const resolvedUrl = resolveRequestUrl(url, options);
 
   const ctx: RequestContext = {
@@ -169,7 +175,7 @@ export const registerRequestInterceptor = addRequestInterceptor;
 export const registerResponseInterceptor = addResponseInterceptor;
 
 // 导出认证相关方法
-export { handleAuthFailureRedirect };
+export { handleAuthFailureRedirect, SsoNetworkError } from './sso';
 
 // 导出类型
 export type {