generator-mico-cli 0.2.29 → 0.2.31

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

@@ -136,6 +136,14 @@ interface MicroAppProps {
 
 **说明**：子应用在 `mount` 生命周期中通过 `props` 接收这些数据。
 
+### 国际化（common-intl）
+
+- **共享文案（默认）**：主应用在 `render` 中拉取中台后，子应用 `import { intl } from '<%= packageScope %>/common-intl'` 即可（与主应用同一默认 tag），详见 `packages/common-intl/README.md`。
+- **不同 tag**：上游支持多次 `initIntl`，子应用可对同一依赖再绑定一套 tag 并在子应用 `render` 中拉取；或直连 `@common-web/common-intl`，见 README「不同 tag」。
+- **可选模板层**：若子应用需 `formatMessage` 式 API 与 Umi 兜底，见仓库 `docs/feat-subapp-国际化翻译.md`（生成项目根目录文档以实际为准）。
+
+主应用 **不向** 子应用 props 传递 `commonIntl`；子应用 **locale** 以 props 与主应用对齐（见上表 `locale`）。
+
 ### 子应用 Props 更新机制
 
 主应用通过 qiankun 的 `update()` 方法实时通知子应用状态变化，无需重新加载：

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/mock/menus.ts

@@ -116,6 +116,20 @@ const mockMenus: MockMenuItem[] = [
     adminOnly: true,
     children: [],
   },
+  {
+    id: 9,
+    name: '小组管理',
+    nameEn: 'Group Management',
+    nameKey: 'cs_web_menu_group_management',
+    type: 'page',
+    path: '/group-management',
+    icon: 'Group',
+    enabled: true,
+    sortOrder: 4,
+    pageId: 125,
+    adminOnly: true,
+    children: [],
+  }
 ];
 
 export default mockMenus;

package/generators/micro-react/templates/apps/layout/mock/pages.ts

@@ -31,7 +31,7 @@ const mockPages: PublicPageItem[] = [
     // htmlUrl:
     //   'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.2/login/index.html',
     htmlUrl:
-      'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.4/login/index.html',
+      'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.9/login/index.html',
     jsUrls: [],
     cssUrls: [],
     prefixPath: '/user',
@@ -51,7 +51,27 @@ const mockPages: PublicPageItem[] = [
     // htmlUrl:
     //   'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.3/permission/index.html',
     htmlUrl:
-      'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.4/permission/index.html',
+      'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.9/permission/index.html',
+    jsUrls: [],
+    cssUrls: [],
+    prefixPath: '',
+    routeMode: 'prefix',
+    enabled: true,
+    accessControlEnabled: true,
+    adminOnly: true,
+    routeKey: null,
+    mainDocumentId: 59,
+    version: 'v2026.02.26-04.13-419',
+  },
+  {
+    id: 125,
+    name: '小组管理',
+    route: '/group-management',
+    base: '/',
+    // htmlUrl:
+    //   'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.3/permission/index.html',
+    htmlUrl:
+      'https://cdn-portal.micoplatform.com/portal-center/common-web/0.0.9/group-management/index.html',
     jsUrls: [],
     cssUrls: [],
     prefixPath: '',

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

@@ -22,6 +22,8 @@
     "test": "cross-env UMI_ENV=test max dev"
   },
   "dependencies": {
+    "<%= packageScope %>/common-intl": "workspace:*",
+    "<%= packageScope %>/shared": "workspace:*",
     "@mico-platform/ui": "<%= micoUiVersion %>",
     "@mico-platform/theme": "<%= themeVersion %>",
     "@umijs/max": "^4.6.15",
@@ -29,8 +31,7 @@
     "qiankun": "^2.10.16",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "spark-md5": "^3.0.2",
-    "<%= packageScope %>/common-intl": "workspace:*"
+    "spark-md5": "^3.0.2"
   },
   "devDependencies": {
     "@types/react": "^18.0.33",

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

@@ -1,19 +1,28 @@
 import { history, type RequestConfig } from '@umijs/max';
 import { addGlobalUncaughtErrorHandler } from 'qiankun';
+import * as CommonWebSentry from '@common-web/sentry';
 import { SentryErrorBoundary } from '@common-web/sentry';
 import { errorConfig } from './requestErrorConfig';
 // 将 @mico-platform/ui 暴露到 window，供子应用 externals 使用
 import * as micoUI from '@mico-platform/ui';
+import dayjs from 'dayjs';
 import React from 'react';
 import ReactDOM from 'react-dom';
 
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+import dayjsTimezone from 'dayjs/plugin/timezone';
+import dayjsUtc from 'dayjs/plugin/utc';
 import { request as commonRequest } from './common/request';
+import { configureRequest } from '<%= packageScope %>/shared/services';
+import { configureTimezone } from '<%= packageScope %>/shared/timezone';
+import { getTimezone } from '@/common/helpers';
 import {
+  configureLocale,
   fetchMultilingualData,
-  getCurrentLocale as getIntlLocale,
   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';
@@ -30,10 +39,32 @@ import {
 } from './common/request/sso';
 import { initTheme } from './common/theme';
 import MicroAppLoader from './components/MicroAppLoader';
+import { isCommonIntlEnabled } from '@/common/intl';
 import { isNoAuthRoute } from '@/constants';
-import { getCurrentLocale } from '@/common/locale';
 import '@mico-platform/theme/dist/css/theme.css';
 import './global.less';
+import { getCurrentLocale, setLocaleToStorage } from './common/locale';
+import { ilangToUmiLocale, umiLocaleToILang } from '@/common/intl/localeMapping';
+
+// 主应用：将统一 request 注入 shared 包，供共享服务层（getRequest）使用
+// 注意：模块顶层注入，确保任何业务调用 getRequest() 之前已就绪
+configureRequest(commonRequest as <T = unknown>(url: string, options?: Record<string, unknown>) => Promise<T>);
+
+// 主应用：扩展 dayjs 插件并注入「当前 IANA 时区」获取器，供 shared/timezone 使用
+// 说明：apps/layout/src/common/helpers.ts 已扩展 utc/timezone，此处再补 customParseFormat（shared/timezone 的 parseDateInTimezone 需要它）
+// dayjs.extend 内部去重，重复调用安全
+dayjs.extend(dayjsUtc);
+dayjs.extend(dayjsTimezone);
+dayjs.extend(customParseFormat);
+configureTimezone({ getTimezone });
+
+// 主应用：common-intl initIntl 的 getLocale/setLocale 与 Umi `umi_locale` 单一数据源对齐（见 packages/common-intl configureLocale）
+configureLocale({
+  getLocale: () => umiLocaleToILang(getCurrentLocale()),
+  setLocale: (lang: ILang) => {
+    setLocaleToStorage(ilangToUmiLocale(lang));
+  },
+});
 
 // ==================== qiankun 全局错误处理 ====================
 // 捕获子应用运行时未捕获的异常，防止页面崩溃
@@ -87,15 +118,31 @@ if (typeof window !== 'undefined') {
     // 注意：这里不阻止错误冒泡，让控制台仍能显示原始错误
     // 如果需要阻止，可以 return true
   });
+
+  // 注入构建信息
+  if (typeof window !== 'undefined') {
+    window.__MICO_BUILD__ = {
+      branchOrTag: process.env.BRANCH_OR_TAG,
+      gitCommit: process.env.GIT_COMMIT,
+      version: process.env.VERSION,
+      buildTime: dayjs(process.env.BUILD_TIME).format('YYYY-MM-DD HH:mm:ss'),
+      buildNumber: process.env.BUILD_NUMBER,
+    };
+  }
 }
 
 // ==================== 微前端共享依赖 ====================
 // 将公共库暴露到 window，供子应用复用，避免重复打包
 // 子应用通过 externals 配置引用这些全局变量
-if (typeof window !== 'undefined') {
+if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
   const win = window as unknown as Record<string, unknown>;
   win.React = React;
   win.ReactDOM = ReactDOM;
+  win.CommonWebSentry = CommonWebSentry;
+}
+
+if (typeof window !== 'undefined') {
+  const win = window as unknown as Record<string, unknown>;
   win.micoUI = micoUI;
   win.CommonIntl = CommonIntl;
 }
@@ -117,15 +164,22 @@ export const locale = {
 
 // ==================== 国际化数据预加载 ====================
 
-/** @see https://umijs.org/docs/api/runtime-config#render */
+/**
+ * 配置了有效 `__MICO_CONFIG__.commonIntl` 时首屏拉取中台文案；失败仍继续渲染。
+ * @see generators/micro-react/templates/packages/common-intl/README.md
+ */
 export function render(oldRender: () => void): void {
+  if (!isCommonIntlEnabled()) {
+    oldRender();
+    return;
+  }
   fetchMultilingualData({
     requestInstance: commonRequest,
     messageInstance: {
       error: micoUI.Message.error,
       warning: micoUI.Message.warning,
     },
-    lang: getIntlLocale() as ILang,
+    lang: umiLocaleToILang(getCurrentLocale()) as ILang,
     localeRequestUrl: process.env.LOCALE_REQUEST_URL,
   })
     .then(oldRender)
@@ -157,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

@@ -2,12 +2,16 @@ import { authLogger } from '@/common/logger';
 import { checkStaffAuth } from '@/services/auth';
 import { handleAuthFailureRedirect } from '../request';
 import { clearStoredTokens, getAuthInfo } from './auth-manager';
+import { clearStoredTenantCode } from './tenant';
 
 // 导出 STORAGE_KEYS 常量
 export { STORAGE_KEYS } from '../../constants';
+export { resolveAuthCheckPath } from './auth-check-path';
 
 export function logout(): void {
   clearStoredTokens();
+  // 清理当前租户，避免切换账号后残留
+  clearStoredTenantCode();
 }
 
 /**

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

@@ -0,0 +1,25 @@
+import { getFromStorage, removeStorage, setStorage } from '@/common/helpers';
+import { STORAGE_KEYS } from '@/constants';
+
+/**
+ * 当前租户 code 存储工具
+ *
+ * 多租户模式下，当前选中的租户会被持久化到 localStorage，
+ * 在调用 `fetchUserInfo` 时作为 `tenant` 参数传给后端，
+ * 以获取对应租户的 menu_perms / button_perms / region_perms。
+ */
+
+export const getStoredTenantCode = (): string | null => {
+  return getFromStorage(STORAGE_KEYS.CURRENT_TENANT);
+};
+
+export const setStoredTenantCode = (code: string): void => {
+  if (!code) {
+    return;
+  }
+  setStorage(STORAGE_KEYS.CURRENT_TENANT, code);
+};
+
+export const clearStoredTenantCode = (): void => {
+  removeStorage(STORAGE_KEYS.CURRENT_TENANT);
+};

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

@@ -8,19 +8,43 @@ export const UID = 'uid';
 /** 微应用模式下主应用传递的环境标识 */
 export const MICRO_ENV_KEY = 'micro_env';
 
+export interface IAppPerms {
+  key: string;
+  value: string;
+}
+
+export interface ITenantItem {
+  /** 租户名 */
+  name: string;
+  /** 租户 code */
+  code: string;
+}
+
+/** 租户模式枚举 */
+export enum ETenantModel {
+  Single = 1,
+  Multi = 2,
+}
+
 /**
- * OpenAPI 8 — GET /user/info/ 响应 `data`（与 Apifox 导出 8 一致）
+ * OpenAPI — GET /user/info/ 响应 `data`
  */
 export interface IUserInfoApiData {
   id: number;
   avatar: string;
   email: string;
   name: string;
-  app_perms: string[];
+  app_perms: IAppPerms[];
   region_perms: string[];
   menu_perms: string[];
   button_perms: string[];
   is_superuser: boolean;
+  /** 租户模式：1 单租户，2 多租户 */
+  tenant_model: number;
+  /** 用户所属租户列表 */
+  tenant: ITenantItem[];
+  /** 当前租户 code，对应 ITenantItem.code */
+  current_tenant: string;
 }
 
 /**
@@ -32,4 +56,6 @@ export interface IUserInfo extends IUserInfoApiData {
   user_name: string;
   /** 登录名/账号展示，可与 `name` 或 `email` 一致 */
   username: string;
+  /** 是否多租户模式（tenant_model === 2 的语义化快捷字段） */
+  isMultiTenant: boolean;
 }

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

@@ -0,0 +1,30 @@
+import { i18n } from '<%= packageScope %>/common-intl';
+import { getIntl } from '@umijs/max';
+import { isCommonIntlEnabled } from './intlRuntime';
+
+/**
+ * 非组件上下文（如 request 拦截器、工具函数）的国际化方法。
+ *
+ * 与 useLayoutIntl.formatMessage 逻辑一致：
+ * - commonIntl 未启用 → 直接走 Umi getIntl()
+ * - commonIntl 启用 → 远程 i18n() 优先，返回 defaultMessage 时回退到 Umi
+ */
+export function formatLayoutMessage(
+  descriptor: { id: string; defaultMessage?: string },
+  values?: Record<string, string | number | boolean | Date | null | undefined>,
+): string {
+  const umiIntl = getIntl();
+  const dm = descriptor.defaultMessage ?? descriptor.id;
+
+  if (!isCommonIntlEnabled()) {
+    return umiIntl.formatMessage(descriptor, values);
+  }
+
+  const fromIntl = i18n({ key: descriptor.id, defaultMessage: dm });
+  const fromUmi = umiIntl.formatMessage(descriptor, values);
+
+  if (fromIntl === dm && fromUmi !== fromIntl) {
+    return fromUmi || dm;
+  }
+  return fromIntl;
+}

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

@@ -0,0 +1,6 @@
+export { intl } from '<%= packageScope %>/common-intl';
+export { getCommonIntlConfig, isCommonIntlEnabled } from './intlRuntime';
+export { ilangToUmiLocale, umiLocaleToILang } from './localeMapping';
+export type { IMicoConfigCommonIntl } from './types';
+export { useLayoutIntl } from './useLayoutIntl';
+export { formatLayoutMessage } from './formatLayoutMessage';

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

@@ -0,0 +1,14 @@
+import type { IMicoConfigCommonIntl } from './types';
+
+/**
+ * 是否启用多语言中台拉取：以 __MICO_CONFIG__.intl 或 commonIntl 含有效 tag、app_name 为准
+ */
+export function isCommonIntlEnabled(): boolean {
+  const c = getCommonIntlConfig();
+  return !!(c?.tag && c?.app_name);
+}
+
+export function getCommonIntlConfig(): IMicoConfigCommonIntl | undefined {
+  const w = window.__MICO_CONFIG__;
+  return w?.intl ?? w?.commonIntl;
+}

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

@@ -0,0 +1,30 @@
+import { LANG, type ILang } from '<%= packageScope %>/common-intl';
+import type { SupportedLocale } from '@/common/locale';
+import { LOCALE } from '@/common/locale';
+
+/** 与 packages/common-intl/src/umiLocaleBridge.ts 保持一致 */
+const UMI_TO_ILANG: Record<SupportedLocale, ILang> = {
+  [LOCALE.ZH_CN]: LANG.ZH_CN,
+  [LOCALE.EN_US]: LANG.EN,
+};
+
+/**
+ * Umi 权威 locale → common-intl 中台 / 缓存键（ILang）
+ */
+export function umiLocaleToILang(locale: SupportedLocale): ILang {
+  return UMI_TO_ILANG[locale] ?? LANG.EN;
+}
+
+const ILANG_TO_UMI: Partial<Record<ILang, SupportedLocale>> = {
+  [LANG.ZH_CN]: LOCALE.ZH_CN,
+  [LANG.EN]: LOCALE.EN_US,
+  [LANG.AR]: LOCALE.EN_US,
+  [LANG.TR]: LOCALE.EN_US,
+};
+
+/**
+ * ILang → Umi 存储用 locale（layout 仅支持 zh-CN / en-US 时，其余语系落到 en-US）
+ */
+export function ilangToUmiLocale(lang: ILang): SupportedLocale {
+  return ILANG_TO_UMI[lang] ?? LOCALE.EN_US;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * layout 运行时 common-intl 配置（见 window.__MICO_CONFIG__.intl，兼容 commonIntl）
+ */
+export interface IMicoConfigCommonIntl {
+  /** 多语言中台 tag */
+  tag: string;
+  app_name: string;
+  indexedDBParams?: {
+    dbName?: string;
+    dbVersion?: number;
+    storeName?: string;
+    keyPathKey?: string;
+  };
+}

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

@@ -0,0 +1,40 @@
+import { i18n, intl } from '<%= packageScope %>/common-intl';
+import { useIntl } from '@umijs/max';
+import { getCurrentLocale } from '@/common/locale';
+import { isCommonIntlEnabled } from './intlRuntime';
+
+/**
+ * layout 统一国际化 Hook：未配置 commonIntl 时仅 Umi；配置后 common-intl 优先，无命中时 Umi 兜底。
+ */
+export function useLayoutIntl() {
+  const umiIntl = useIntl();
+  const commonIntlEnabled = isCommonIntlEnabled();
+  const locale = getCurrentLocale();
+
+  const formatMessage = (
+    descriptor: { id: string; defaultMessage?: string },
+    values?: Record<string, string | number | boolean | Date | null | undefined>,
+  ): string => {
+    if (!commonIntlEnabled) {
+      return umiIntl.formatMessage(descriptor, values);
+    }
+    const dm = descriptor.defaultMessage ?? descriptor.id;
+    const fromIntl = i18n({
+      key: descriptor.id,
+      defaultMessage: dm,
+    });
+    const fromUmi = umiIntl.formatMessage(descriptor, values);
+    if (fromIntl === dm && fromUmi !== fromIntl) {
+      return fromUmi;
+    }
+    return fromIntl;
+  };
+
+  return {
+    commonIntlEnabled,
+    locale,
+    formatMessage,
+    /** 仅 common-intl 启用时有值 */
+    intl: commonIntlEnabled ? intl : undefined,
+  };
+}

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

@@ -1,38 +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) => {
-  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 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);
 };
 
 // 预定义的日志实例