generator-mico-cli 0.2.32 → 0.2.34

package/README.md

@@ -117,6 +117,12 @@ mico setup multica-desktop
 
 所有字段均为可选，未配置时使用默认值或交互式提示。
 
+### 组件库版本（`micoPackages`）
+
+CLI 根 `package.json` 的 `micoPackages` 是 `@mico-platform/ui` / `@mico-platform/theme` 的**唯一维护点**（semver range，如 `0.x`）。`mico create` 时在该 range 内 resolve 最新版本，写入生成项目为 `^x.y.z`（如 `^0.0.25`）；子应用开发环境 CDN 的 `MICO_UI_VERSION` 使用同一 resolved 精确版本。
+
+组件库发 patch（仍在 `0.x`）时通常无需发 CLI；切换到 `1.x` 等 major 策略时，修改 `micoPackages` 并发布新 CLI 即可。
+
 ## Monorepo 项目生成器 (micro-react)
 
 创建基于 qiankun 微前端架构的完整 Monorepo 项目：

package/generators/micro-react/README.md

@@ -31,4 +31,4 @@ mico create micro-react
 | `cdnPrefix` / `cdnPrefixPath` | string | prompt；`cdnPrefixPath` 为空或带尾斜杠 |
 | `author` | string | prompt |
 | `intlTag` | string | prompt |
-| `micoUiVersion` / `themeVersion` | string | `npm view @mico-platform/{ui,theme} version`，前缀 `^`，失败回退 `^1.0.0` |
+| `micoUiVersion` / `themeVersion` | string | `^${micoPackages range 内 resolve 的最新版本}` |

package/generators/micro-react/index.js

@@ -9,7 +9,7 @@ const {
   collectFiles,
   transformDestPath,
   isTemplateFile,
-  getPackageVersionsParallel,
+  getMicoTemplateVersions,
   setupErrorHandlers,
   createLogger,
   loadMicorc,
@@ -162,23 +162,14 @@ module.exports = class extends Generator {
 
       // 在 mico_cli 根目录执行 npm view，以使用该目录 .npmrc 中的 Nexus 认证
       const cliRoot = path.resolve(__dirname, '../..');
-      this.logger.verbose('Fetching latest package versions (parallel)...');
-
-      // 并行获取版本
-      const versions = await getPackageVersionsParallel(
-        [
-          { name: '@mico-platform/ui', fallback: '1.0.0' },
-          { name: '@mico-platform/theme', fallback: '1.0.0' },
-        ],
-        8000,
-        cliRoot,
-      );
+      this.logger.verbose('Fetching mico package versions from manifest...');
 
-      const micoUiVer = versions['@mico-platform/ui'];
-      const themeVer = versions['@mico-platform/theme'];
+      const micoVersions = await getMicoTemplateVersions(cliRoot, 8000);
+      const ui = micoVersions['@mico-platform/ui'];
+      const theme = micoVersions['@mico-platform/theme'];
 
-      this.logger.verbose('@mico-platform/ui version:', micoUiVer);
-      this.logger.verbose('@mico-platform/theme version:', themeVer);
+      this.logger.verbose('@mico-platform/ui range:', ui.range, 'resolved:', ui.resolved);
+      this.logger.verbose('@mico-platform/theme range:', theme.range, 'resolved:', theme.resolved);
 
       // 构建 CDN 路径片段：如果有 prefix 则加上斜杠前缀，否则为空
       const cdnPrefixPath = this.cdnPrefix ? `${this.cdnPrefix}/` : '';
@@ -191,8 +182,8 @@ module.exports = class extends Generator {
         appId: this.appId,
         packageScope: this.packageScope,
         author: this.author,
-        micoUiVersion: `^${micoUiVer}`,
-        themeVersion: `^${themeVer}`,
+        micoUiVersion: `^${ui.resolved}`,
+        themeVersion: `^${theme.resolved}`,
         cdnPrefix: this.cdnPrefix,
         cdnPrefixPath, // 用于拼接路径，已包含尾部斜杠
         intlTag: this.intlTag,

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/logger.ts

@@ -23,7 +23,7 @@ function readVerboseDebugQueryOnce(): boolean {
   }
   try {
     const v = new URLSearchParams(window.location.search).get(DEBUG_LOGS_QUERY_KEY);
-    if (v == null || v === '') {
+    if (v === null || v === '') {
       return false;
     }
     const normalized = v.toLowerCase();

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 {

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

@@ -13,6 +13,7 @@ import { isNoAuthRoute, ROUTES } from '@/constants';
 import { captureError } from '@common-web/sentry';
 import { formatLayoutMessage } from '@/common/intl';
 import { Modal } from '@mico-platform/ui';
+import React from 'react';
 import {
   getTicketParam,
   resolveAuthToken,
@@ -36,6 +37,38 @@ let tokenAcquiredAt: number | null = null;
 /** 登录失败弹窗是否已显示，防止多个请求同时失败时重复弹出 */
 let redirectLimitModalShown = false;
 
+/** 是否正在执行 SSO 硬跳转，置位后用于阻断渲染与拦截在途请求 */
+let redirecting = false;
+
+/** 是否正在执行 SSO 硬跳转 */
+export const isRedirecting = (): boolean => redirecting;
+
+/**
+ * ticket 换 token 阶段的网络层故障（Failed to fetch / NetworkError 等）。
+ * 由 ensureSsoSession() 在 catch 阶段抛出，供调用方识别是否为网络异常，
+ * 避免使用模块级 mutable 状态在函数间传递信号。
+ */
+export class SsoNetworkError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'SsoNetworkError';
+  }
+}
+
+/** 判断错误是否为网络层故障（无法建立连接，而非 HTTP 错误响应） */
+const isNetworkError = (err: Error): boolean => {
+  const msg = err.message.toLowerCase();
+  return (
+    msg.includes('failed to fetch') ||
+    msg.includes('networkerror') ||
+    msg.includes('network error') ||
+    msg.includes('load failed')
+  );
+};
+
 /**
  * 执行 SSO 重定向跳转，回跳地址中固定携带 redirect_count=1
  */
@@ -49,6 +82,9 @@ const performSsoRedirect = (): void => {
   redirectUrl.searchParams.delete('ticket');
   const serviceUrl = redirectUrl.toString();
 
+  // 在赋值 location.href 之前置位，浏览器导航期间用于阻断渲染与拦截在途请求
+  redirecting = true;
+
   window.location.href = `${
     externalLoginPath ?? ROUTES.LOGIN
   }?service=${encodeURIComponent(serviceUrl)}`;
@@ -56,21 +92,28 @@ const performSsoRedirect = (): void => {
 
 /**
  * 处理认证失败后的重定向
+ *
+ * @param options.isNetworkError 是否由 ticket 换 token 阶段的网络异常触发，
+ *   true 时弹窗展示 IOA/网络排障指引；其它认证失败入口（401 重试失败、登出等）
+ *   不传或传 false，使用默认「自动登录失败」文案。
  */
-export const handleAuthFailureRedirect = (): void => {
-  if (typeof window === 'undefined') return;
+export const handleAuthFailureRedirect = (
+  options: { isNetworkError?: boolean } = {},
+): boolean => {
+  const { isNetworkError: isNetworkErr = false } = options;
+  if (typeof window === 'undefined') return false;
 
   const authCheckPath = resolveAuthCheckPath(window.location.pathname);
 
   // 与 getInitialState 一致：用 authCheckPath 判断，避免「/ + defaultPath」首屏仍按 / 误判为免认证
   if (isNoAuthRoute(authCheckPath)) {
     console.log('[SSO] 当前路由在免认证列表中，跳过 SSO 重定向', { authCheckPath });
-    return;
+    return false;
   }
 
   if (isPageAuthFree(authCheckPath)) {
     console.log('[SSO] 页面 accessControlEnabled=false，跳过 SSO 重定向', { authCheckPath });
-    return;
+    return false;
   }
 
   // 从 URL 中获取当前 redirect 登录的次数
@@ -85,7 +128,7 @@ export const handleAuthFailureRedirect = (): void => {
   // 如果 redirect 次数小于 1 次，则执行自动 redirect 跳转登录
   if (redirectCount < 1) {
     performSsoRedirect();
-    return;
+    return true;
   }
 
   // redirect 次数已达上限，停止自动重定向，记录日志并弹窗询问用户是否手动重试
@@ -105,18 +148,69 @@ export const handleAuthFailureRedirect = (): void => {
         ? new Date(tokenAcquiredAt).toISOString()
         : null,
       tokenAgeSeconds: tokenAge,
+      isNetworkError: isNetworkErr,
     },
   });
 
   if (redirectLimitModalShown) {
     console.log('[SSO] 登录失败弹窗已显示，跳过重复弹出');
-    return;
+    return false;
   }
 
   redirectLimitModalShown = true;
+  const secondaryStyle: React.CSSProperties = {
+    marginTop: 8,
+    color: 'var(--color-text-3, #86909c)',
+    fontSize: 13,
+  };
+  const modalContent = isNetworkErr
+    ? React.createElement(
+        'div',
+        null,
+        React.createElement(
+          'div',
+          null,
+          formatLayoutMessage({
+            id: 'sso_auth_failure_network_primary',
+            defaultMessage: '网络异常，无法完成自动登录',
+          }),
+        ),
+        React.createElement(
+          'div',
+          { style: secondaryStyle },
+          React.createElement(
+            'div',
+            null,
+            formatLayoutMessage({
+              id: 'sso_auth_failure_network_hint_title',
+              defaultMessage: '请检查以下情况：',
+            }),
+          ),
+          React.createElement(
+            'div',
+            null,
+            formatLayoutMessage({
+              id: 'sso_auth_failure_network_hint_ioa',
+              defaultMessage: '1. IOA 是否已连接',
+            }),
+          ),
+          React.createElement(
+            'div',
+            null,
+            formatLayoutMessage({
+              id: 'sso_auth_failure_network_hint_network',
+              defaultMessage: '2. 当前网络是否可正常访问',
+            }),
+          ),
+        ),
+      )
+    : formatLayoutMessage({
+        id: 'sso_auth_failure_modal_content',
+        defaultMessage: '自动登录失败，是否重新尝试登录？',
+      });
   Modal.confirm({
     title: formatLayoutMessage({ id: 'sso_auth_failure_modal_title', defaultMessage: '登录提示' }),
-    content: formatLayoutMessage({ id: 'sso_auth_failure_modal_content', defaultMessage: '自动登录失败，是否重新尝试登录？' }),
+    content: modalContent,
     okText: formatLayoutMessage({ id: 'sso_auth_failure_modal_ok', defaultMessage: '重新登录' }),
     cancelText: formatLayoutMessage({ id: 'sso_auth_failure_modal_cancel', defaultMessage: '取消' }),
     onOk: () => {
@@ -128,6 +222,9 @@ export const handleAuthFailureRedirect = (): void => {
       redirectLimitModalShown = false;
     },
   });
+
+  // 仅弹出 Modal 询问，未执行硬跳转
+  return false;
 };
 
 /**
@@ -180,12 +277,32 @@ export const ensureSsoSession = async (): Promise<void> => {
           throw new Error('SSO 认证失败');
         }
       } catch (error) {
-        console.error('SSO ticket exchange failed', error);
+        const err = error instanceof Error ? error : new Error(String(error));
+        const networkError = isNetworkError(err);
+        console.error('[SSO] ticket 交换失败', err.message, err.stack);
+        captureError(err, {
+          tags: {
+            scene: 'sso_ticket_exchange_failed',
+            is_network_error: String(networkError),
+          },
+          extra: {
+            ticketParam,
+            message: err.message,
+          },
+        });
         setFetchingToken(false);
 
-        rejectPendingRequests(
-          error instanceof Error ? error : new Error('SSO 认证失败'),
-        );
+        const propagatedErr = networkError
+          ? new SsoNetworkError(err.message, err)
+          : err;
+        rejectPendingRequests(propagatedErr);
+
+        // 仅在网络异常时向外抛出，让调用方据此切换 UI 文案；
+        // 其它失败（如 SSO 业务态失败）保持原有「静默」语义，由调用方
+        // 通过 token 是否就绪判断后续走向。
+        if (networkError) {
+          throw propagatedErr;
+        }
       } finally {
         removeParamFromUrl(ticketParam);
         ticketPromise = null;

package/generators/micro-react/templates/apps/layout/src/components/MicroAppLoader/index.tsx

@@ -115,8 +115,12 @@ const MicroAppLoader: React.FC<MicroAppLoaderProps> = ({
       current_tenant: currentUser?.current_tenant,
       allowed_tenants: allowedTenants,
     };
-    const { request: _request, ...loggableProps } = props;
-    console.log('[MicroAppLoader] buildProps', { appName, ...loggableProps });
+    console.log('[MicroAppLoader] buildProps', {
+      appName,
+      ...Object.fromEntries(
+        Object.entries(props).filter(([key]) => key !== 'request'),
+      ),
+    });
     return props;
   }, [base, env, routePath, currentUser, appName]);
 

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

@@ -132,6 +132,28 @@ export const isAuthDisabled = (): boolean => {
   return window.__MICO_CONFIG__?.disableAuth === true;
 };
 
+/**
+ * 布局模式
+ * - 'side'：经典左侧完整目录树
+ * - 'mix'：一级目录显示在头部 Tab，对应子级目录显示在侧边栏
+ */
+export type TLayoutMode = 'side' | 'mix';
+
+/**
+ * 获取布局模式
+ * 读取 window.__MICO_CONFIG__.layoutMode，未配置时默认 'side'（兼容旧版）
+ */
+export const getLayoutMode = (): TLayoutMode => {
+  return window.__MICO_CONFIG__?.layoutMode === 'mix' ? 'mix' : 'side';
+};
+
+/**
+ * 判断是否为「头部一级 + 侧边二级」混合布局
+ */
+export const isMixLayout = (): boolean => {
+  return getLayoutMode() === 'mix';
+};
+
 /**
  * 主题相关常量
  */