generator-mico-cli 0.2.28 → 0.2.30

package/generators/micro-react/templates/packages/shared/timezone/index.ts

@@ -0,0 +1,228 @@
+/**
+ * 时区工具
+ *
+ * 设计：
+ * - 时区**读写**（如 localStorage 存储）由消费方（主应用）负责
+ * - 本模块通过 `configureTimezone({ getTimezone })` 注入器拿到「当前 IANA 时区」
+ * - 包内业务函数（解析、格式化、范围）统一调用注入函数，避免与具体存储耦合
+ *
+ * 外部依赖：dayjs + utc/timezone/customParseFormat 插件，需消费方在入口预先调用
+ *   dayjs.extend(utc); dayjs.extend(timezone); dayjs.extend(customParseFormat);
+ */
+
+import dayjs, { type Dayjs } from 'dayjs';
+
+// ==================== 常量与类型 ====================
+
+/**
+ * UTC 偏移量键的枚举映射，覆盖 UTC-12 到 UTC+14
+ */
+export const TIMEZONE = {
+  'UTC-12': 'UTC-12',
+  'UTC-11': 'UTC-11',
+  'UTC-10': 'UTC-10',
+  'UTC-9': 'UTC-9',
+  'UTC-8': 'UTC-8',
+  'UTC-7': 'UTC-7',
+  'UTC-6': 'UTC-6',
+  'UTC-5': 'UTC-5',
+  'UTC-4': 'UTC-4',
+  'UTC-3': 'UTC-3',
+  'UTC-2': 'UTC-2',
+  'UTC-1': 'UTC-1',
+  'UTC+0': 'UTC+0',
+  'UTC+1': 'UTC+1',
+  'UTC+2': 'UTC+2',
+  'UTC+3': 'UTC+3',
+  'UTC+4': 'UTC+4',
+  'UTC+5': 'UTC+5',
+  'UTC+6': 'UTC+6',
+  'UTC+7': 'UTC+7',
+  'UTC+8': 'UTC+8',
+  'UTC+9': 'UTC+9',
+  'UTC+10': 'UTC+10',
+  'UTC+11': 'UTC+11',
+  'UTC+12': 'UTC+12',
+  'UTC+13': 'UTC+13',
+  'UTC+14': 'UTC+14',
+} as const;
+
+export type TTimezone = keyof typeof TIMEZONE;
+
+/**
+ * 地理上 24 个时区，但实际上有约 38 个不同的偏移时区，行政上则有上百个不同的时区规则地区。
+ * 24 个理论时区基于经度划分，每 15° 一时区，整数小时 UTC 偏移。
+ * 大部分时区可能有多个可用的城市/地区标识，此处仅使用一个常用标识。
+ */
+export const TIMEZONE_HASH: Record<TTimezone, string> = {
+  [TIMEZONE['UTC-12']]: 'Etc/GMT+12',
+  [TIMEZONE['UTC-11']]: 'Pacific/Pago_Pago',
+  [TIMEZONE['UTC-10']]: 'Pacific/Honolulu',
+  [TIMEZONE['UTC-9']]: 'America/Anchorage',
+  [TIMEZONE['UTC-8']]: 'America/Los_Angeles',
+  [TIMEZONE['UTC-7']]: 'America/Denver',
+  [TIMEZONE['UTC-6']]: 'America/Chicago',
+  [TIMEZONE['UTC-5']]: 'America/New_York',
+  [TIMEZONE['UTC-4']]: 'America/Puerto_Rico',
+  [TIMEZONE['UTC-3']]: 'America/Sao_Paulo',
+  [TIMEZONE['UTC-2']]: 'America/Noronha',
+  [TIMEZONE['UTC-1']]: 'Atlantic/Azores',
+  [TIMEZONE['UTC+0']]: 'Europe/London',
+  [TIMEZONE['UTC+1']]: 'Europe/Paris',
+  [TIMEZONE['UTC+2']]: 'Europe/Kyiv',
+  [TIMEZONE['UTC+3']]: 'Europe/Moscow',
+  [TIMEZONE['UTC+4']]: 'Asia/Dubai',
+  [TIMEZONE['UTC+5']]: 'Asia/Tashkent',
+  [TIMEZONE['UTC+6']]: 'Asia/Dhaka',
+  [TIMEZONE['UTC+7']]: 'Asia/Bangkok',
+  [TIMEZONE['UTC+8']]: 'Asia/Shanghai',
+  [TIMEZONE['UTC+9']]: 'Asia/Tokyo',
+  [TIMEZONE['UTC+10']]: 'Australia/Sydney',
+  [TIMEZONE['UTC+11']]: 'Pacific/Noumea',
+  [TIMEZONE['UTC+12']]: 'Pacific/Auckland',
+  [TIMEZONE['UTC+13']]: 'Pacific/Tongatapu',
+  [TIMEZONE['UTC+14']]: 'Pacific/Kiritimati',
+};
+
+/** 默认 IANA 时区，所有注入未就绪 / 未匹配时的兜底 */
+const DEFAULT_IANA = TIMEZONE_HASH[TIMEZONE['UTC+8']];
+
+// ==================== 纯转换函数 ====================
+
+/**
+ * 将 UTC offset 数字转换为 UTC+N 格式的时区字符串
+ * @example utcOffsetToTimezone(8)  => 'UTC+8'
+ * @example utcOffsetToTimezone(-5) => 'UTC-5'
+ */
+export const utcOffsetToTimezone = (utcOffset: number): string => {
+  if (utcOffset >= 0) {
+    return `UTC+${utcOffset}`;
+  }
+  return `UTC${utcOffset}`;
+};
+
+/**
+ * 将 UTC 偏移量转换为 IANA 时区标识（带兜底）
+ * 回退顺序：TIMEZONE_HASH → dayjs.tz.guess() → Asia/Shanghai
+ */
+export const utcOffsetToTimeZoneStr = (utcOffset: number): string => {
+  const key = utcOffsetToTimezone(utcOffset) as TTimezone;
+  return TIMEZONE_HASH[key] ?? dayjs.tz?.guess?.() ?? DEFAULT_IANA;
+};
+
+// ==================== 注入器 ====================
+
+/**
+ * 时区注入函数：返回当前 IANA 时区标识（如 'Asia/Shanghai'）
+ * 由消费方在应用入口注入，通常代理到主应用的时区管理模块
+ */
+export type TimezoneGetter = () => string;
+
+let _getTimezone: TimezoneGetter | null = null;
+
+/**
+ * 注入时区获取器
+ *
+ * @example
+ * import { configureTimezone } from '<%= packageScope %>/shared/timezone';
+ * import { getTimezone } from '@/common/helpers';
+ *
+ * configureTimezone({ getTimezone });
+ */
+export function configureTimezone(options: { getTimezone: TimezoneGetter }): void {
+  _getTimezone = options.getTimezone;
+}
+
+/**
+ * 获取当前 IANA 时区
+ * - 已注入：调用注入器
+ * - 未注入：尝试 `dayjs.tz.guess()`，最终兜底到 'Asia/Shanghai'
+ *
+ * 包内所有格式化函数都通过此函数取时区，避免直接耦合 storage 实现
+ */
+export function getCurrentTimezoneIANA(): string {
+  if (_getTimezone) {
+    try {
+      const tz = _getTimezone();
+      if (tz) return tz;
+    } catch {
+      // 注入器异常时走兜底
+    }
+  }
+  return dayjs.tz?.guess?.() ?? DEFAULT_IANA;
+}
+
+// ==================== 时间解析与格式化 ====================
+
+const BUSINESS_TIME_PARSE_FORMAT = 'YYYY-MM-DD HH:mm:ss';
+const BUSINESS_MINUTE_PARSE_FORMAT = 'YYYY-MM-DD HH:mm';
+const BUSINESS_DATE_PARSE_FORMAT = 'YYYY-MM-DD';
+
+const getBusinessTimeParseFormat = (value: string): string => {
+  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)) {
+    return BUSINESS_TIME_PARSE_FORMAT;
+  }
+  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(value)) {
+    return BUSINESS_MINUTE_PARSE_FORMAT;
+  }
+  return BUSINESS_DATE_PARSE_FORMAT;
+};
+
+/**
+ * 按当前业务时区解析日期字符串，避免回退到浏览器本机时区
+ */
+export const parseDateInTimezone = (value: string): Dayjs => {
+  return dayjs.tz(value, getBusinessTimeParseFormat(value), getCurrentTimezoneIANA());
+};
+
+export type TShortcutDateRangeUnit = 'day' | 'week';
+
+/**
+ * 生成当前业务时区下的快捷日期范围
+ * - day: 当天开始与结束
+ * - week: 当周开始与结束
+ * - undefined: 当前时刻
+ */
+export const getShortcutDateRange = (
+  unit?: TShortcutDateRangeUnit,
+): [Dayjs, Dayjs] => {
+  const now = dayjs().tz(getCurrentTimezoneIANA());
+  if (!unit) {
+    return [now, now];
+  }
+  return [now.startOf(unit), now.endOf(unit)];
+};
+
+/**
+ * 格式化时间戳为用户时区的标准日期时间字符串
+ * @returns YYYY.MM.DD HH:mm:ss；非法输入原样返回
+ *
+ * @example
+ * formatTimestampToDateTime(1730721621000) // => '2025.11.04 16:20:21' (UTC+8)
+ */
+export const formatTimestampToDateTime = (timestamp: number): string | number => {
+  if (!Number.isFinite(timestamp)) {
+    return timestamp;
+  }
+  return dayjs.utc(timestamp).tz(getCurrentTimezoneIANA()).format('YYYY.MM.DD HH:mm:ss');
+};
+
+/**
+ * 格式化时间戳为指定时区的标准日期时间字符串（带时区后缀）
+ * @returns YYYY.MM.DD HH:mm:ss(UTC+n)；非法输入或未知时区原样返回
+ *
+ * @example
+ * formatTimestampToDateTimeWithTimezone(1730721621000, 'UTC+8') // => '2025.11.04 16:20:21(UTC+8)'
+ */
+export const formatTimestampToDateTimeWithTimezone = (
+  timestamp: number,
+  timezone: TTimezone,
+): string | number => {
+  if (!Number.isFinite(timestamp) || !TIMEZONE[timezone]) {
+    return timestamp;
+  }
+  return dayjs
+    .utc(timestamp)
+    .tz(TIMEZONE_HASH[timezone])
+    .format(`YYYY.MM.DD HH:mm:ss(${timezone})`);
+};

package/generators/micro-react/templates/packages/shared/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true
+  },
+  "include": ["services", "timezone"]
+}

package/generators/micro-react/templates/scripts/apply-sentry-plugin.ts

@@ -16,6 +16,11 @@ export function applySentryPlugin({
   project = '<%= projectName %>',
 }: ApplySentryPluginOptions) {
   const version = require('../package.json').version;
+  const buildNumber = process.env.BUILD_NUMBER?.trim();
+  const releaseName =
+    buildNumber && buildNumber.length > 0
+      ? `${version}+${buildNumber}`
+      : version;
 
   // 使用 Legacy Upload 方式，自托管 Sentry 不支持 Debug ID / Artifact Bundle
   const { sentryWebpackPlugin } = require('@sentry/webpack-plugin');
@@ -29,7 +34,7 @@ export function applySentryPlugin({
           /** @see https://micoworld.feishu.cn/wiki/AmXQwmnEairvQ9k2m9KcgJNcndv#share-OupCdqeeUoESO4x6YKPcrs4nn3c */
           authToken: process.env.SENTRY_AUTH_TOKEN,
           release: {
-            name: version,
+            name: releaseName,
             uploadLegacySourcemaps: {
               paths: ['./dist'],
               urlPrefix: `~/<%= cdnPrefixPath %><%= projectName %>/${version}/${appName}`,

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

@@ -1,6 +1,14 @@
 {
   "$schema": "https://turbo.build/schema.json",
-  "globalEnv": ["CDN_PUBLIC_PATH", "SENTRY_AUTH_TOKEN"],
+  "globalEnv": ["CDN_PUBLIC_PATH", "SENTRY_AUTH_TOKEN", "BRANCH_OR_TAG", "GIT_COMMIT", "VERSION"],
+  "globalPassThroughEnv": [
+    "VERSION",
+    "BUILD_NUMBER",
+    "GIT_COMMIT",
+    "BRANCH_OR_TAG",
+    "BUILD_TIME",
+    "GIT_BRANCH"
+  ],
   "tasks": {
     "build": {
       "dependsOn": ["^build"],

package/generators/subapp-react/index.js

@@ -257,7 +257,7 @@ module.exports = class extends Generator {
 
       this._updateDevPreset();
       this._updateMockPages();
-      this._updateConfigDev();
+      this._updateApiMockMenuPerms();
     } catch (error) {
       console.error('');
       console.error('❌ Error during file generation:');
@@ -297,6 +297,12 @@ module.exports = class extends Generator {
     }
   }
 
+  /** 与 mock menus / api.mock menu_perms 一致的权限 key（cs_web_menu_subapp_page 风格） */
+  _subappRouteKey() {
+    const snake = this.appName.replace(/-/g, '_');
+    return `cs_web_menu_${snake}_page`;
+  }
+
   _updateMockPages() {
     const pagesPath = path.join(this.monorepoRoot, 'apps/layout/mock/pages.ts');
     if (!fs.existsSync(pagesPath)) {
@@ -312,6 +318,8 @@ module.exports = class extends Generator {
         return;
       }
 
+      const routeKey = this._subappRouteKey();
+
       // 找出已有的最大 id
       const idMatches = [...content.matchAll(/id:\s*(\d+)/g)];
       const maxId = idMatches.reduce((max, m) => Math.max(max, Number(m[1])), 0);
@@ -330,9 +338,9 @@ module.exports = class extends Generator {
         "    prefixPath: '',",
         "    routeMode: 'prefix',",
         '    enabled: true,',
-        '    accessControlEnabled: false,',
+        '    accessControlEnabled: true,',
         '    adminOnly: false,',
-        '    routeKey: null,',
+        `    routeKey: '${routeKey}',`,
         `    mainDocumentId: ${maxId + 1},`,
         "    version: '',",
         '  },',
@@ -369,40 +377,38 @@ module.exports = class extends Generator {
     }
   }
 
-  _updateConfigDev() {
-    const configPath = path.join(this.monorepoRoot, 'apps/layout/config/config.dev.ts');
-    if (!fs.existsSync(configPath)) {
-      this.logger.verbose('apps/layout/config/config.dev.ts not found, skipping');
+  /** 将子应用 routeKey 写入 layout mock 的 GET /user/info menu_perms，本地 mock 用户具备该页菜单权限 */
+  _updateApiMockMenuPerms() {
+    const apiMockPath = path.join(this.monorepoRoot, 'apps/layout/mock/api.mock.ts');
+    if (!fs.existsSync(apiMockPath)) {
+      this.logger.verbose('apps/layout/mock/api.mock.ts not found, skipping');
       return;
     }
 
     try {
-      const content = fs.readFileSync(configPath, 'utf-8');
-      const routeEntry = `'/${this.appName}/*'`;
+      const content = fs.readFileSync(apiMockPath, 'utf-8');
+      const routeKey = this._subappRouteKey();
+      const quotedKey = `'${routeKey}'`;
 
-      if (content.includes(routeEntry)) {
-        this.logger.verbose(`Route "${routeEntry}" already in noPermissionRouteList, skipping`);
+      if (content.includes(quotedKey)) {
+        this.logger.verbose(`menu_perms already contains ${routeKey}, skipping`);
         return;
       }
 
       const updated = content.replace(
-        /noPermissionRouteList:\s*\[([^\]]*)\]/,
-        (match, inner) => {
-          const trimmed = inner.trim();
-          const entries = trimmed ? `${trimmed}, ${routeEntry}` : routeEntry;
-          return `noPermissionRouteList: [${entries}]`;
-        },
+        /(menu_perms:\s*\[[\s\S]*?)(\n\s*\],)/,
+        (match, before, closing) => `${before}\n        ${quotedKey},${closing}`,
       );
 
       if (updated === content) {
-        this.logger.verbose('noPermissionRouteList not found in config.dev.ts, skipping');
+        this.logger.verbose('menu_perms array not found in api.mock.ts, skipping');
         return;
       }
 
-      fs.writeFileSync(configPath, updated, 'utf-8');
-      this.log(`   📝 已将 "${routeEntry}" 添加到 config.dev.ts 的 noPermissionRouteList 中`);
+      fs.writeFileSync(apiMockPath, updated, 'utf-8');
+      this.log(`   📝 已将 "${routeKey}" 添加到 api.mock.ts 的 GET /user/info menu_perms 中`);
     } catch (e) {
-      console.warn(`   ⚠️  更新 config.dev.ts 失败: ${e.message}`);
+      console.warn(`   ⚠️  更新 api.mock.ts 失败: ${e.message}`);
     }
   }
 
@@ -429,7 +435,7 @@ module.exports = class extends Generator {
     if (fs.existsSync(path.join(layoutDir, '.prettierrc'))) {
       const filesToFormat = [
         path.join(layoutDir, 'mock/pages.ts'),
-        path.join(layoutDir, 'config/config.dev.ts'),
+        path.join(layoutDir, 'mock/api.mock.ts'),
       ].filter((f) => fs.existsSync(f));
 
       if (filesToFormat.length > 0) {

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

@@ -102,6 +102,7 @@ PORT=8001
 ### 项目文档
 
 - [项目根目录 README](../../README.md)
+- [PermissionFilter 按钮权限](./docs/feature-PermissionFilter按钮权限.md)（子应用用法与主应用文档入口）
 
 ### UmiJS 官方文档
 

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

@@ -45,6 +45,7 @@ const config: ReturnType<typeof defineConfig> = {
     'react-dom': 'ReactDOM',
     '@mico-platform/ui': 'micoUI',
     '@common-web/sentry': 'CommonWebSentry',
+    '<%= packageScope %>/common-intl': 'CommonIntl',
   },
 };
 

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

@@ -45,6 +45,7 @@ const config: ReturnType<typeof defineConfig> = {
     'react-dom': 'ReactDOM',
     '@mico-platform/ui': 'micoUI',
     '@common-web/sentry': 'CommonWebSentry',
+    '<%= packageScope %>/common-intl': 'CommonIntl',
   },
 };
 

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

@@ -44,6 +44,7 @@ const config: ReturnType<typeof defineConfig> = {
     'react-dom': 'ReactDOM',
     '@mico-platform/ui': 'micoUI',
     '@common-web/sentry': 'CommonWebSentry',
+    '<%= packageScope %>/common-intl': 'CommonIntl',
   },
 };
 

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

@@ -76,6 +76,16 @@ const config: ReturnType<typeof defineConfig> = {
    */
   layout: false,
 
+  /**
+   * @name 国际化插件（与 layout 一致；intl 未命中 key 时读 src/locales）
+   * @doc https://umijs.org/docs/max/i18n
+   */
+  locale: {
+    default: 'zh-CN',
+    antd: false,
+    baseNavigator: false,
+  },
+
   /**
    * @name 其他配置
    */

package/generators/subapp-react/templates/homepage/docs/feature-PermissionFilter/346/214/211/351/222/256/346/235/203/351/231/220.md

@@ -0,0 +1,35 @@
+# PermissionFilter 按钮权限（子应用）
+
+> 创建时间：2025-03-27
+
+## 说明
+
+子应用内 `PermissionFilter` 与主应用**同名同 Props**，但权限数据来源不同：通过 qiankun 接收主应用注入的 `button_perms`、`is_superuser`，详见 `src/common/mainApp.ts` 与 `useMainAppProps()`。
+
+**完整架构、主应用用法、Mock 与 `getInitialState` 说明**请阅读主应用文档：
+
+`apps/layout/docs/feature-PermissionFilter按钮权限.md`
+
+## 子应用要点
+
+| 项目 | 说明 |
+| --- | --- |
+| 权限来源 | 主应用 `MicroAppLoader` 传入的 props，非子应用自行请求 `/user/info/` |
+| Hook | `useMainAppProps()`，props 变更时组件会重渲染 |
+| 独立运行 | 无主应用 props，无 `button_perms`，默认走 `fallback` |
+| 示例 | `src/pages/index.tsx` 中「PermissionFilter 按钮权限示例」卡片 |
+
+## 使用示例
+
+```tsx
+import PermissionFilter from '@/components/PermissionFilter';
+
+<PermissionFilter
+  permissionKey="cs_web_btn_subapp_demo"
+  fallback={<Alert type="warning" title="无权限" content="..." />}
+>
+  <Button type="primary">有权限时可见</Button>
+</PermissionFilter>
+```
+
+主应用需在用户信息接口返回的 `button_perms` 中包含与页面一致的 `permissionKey`；本地联调可修改主应用 `mock/api.mock.ts`。

package/generators/subapp-react/templates/homepage/docs/feature-/345/233/275/351/231/205/345/214/226.md

@@ -0,0 +1,124 @@
+# 国际化（common-intl 与 Umi 兜底）
+
+> 创建时间：2026-04-07
+
+## 功能概述
+
+子应用通过 **`<%= packageScope %>/common-intl`**（生产环境常与主应用 **externals 共享**）拉取中台文案；**未命中 key** 时回落到 **Umi `src/locales`**。可选在工程内配置 **独立 `initIntl`**（独立 tag / IndexedDB），与主应用默认实例隔离。语言与主应用对齐：qiankun 下优先主应用注入的 `locale`，否则与 layout 相同的 URL / `umi_locale` / 浏览器规则（见 `getSubappCurrentLocale`）。
+
+## 技术方案
+
+### 技术栈
+
+- Umi Max `locale` 插件 + `src/locales/zh-CN.ts`、`en-US.ts`
+- `<%= packageScope %>/common-intl`：`configureLocale`、`i18n`、`fetchMultilingualData`、`initIntl`（独立实例时）
+- 统一入口：`useSubappIntl`（合并逻辑对齐主应用 `useLayoutIntl`）
+
+### 核心实现
+
+1. **`app.tsx`**：最早调用 `configureLocale`，使包内 `getLocale`/`setLocale` 与 `getSubappCurrentLocale` 一致；导出 Umi 运行时 `locale.getLocale`；在 `render` 中按条件调用中台 `fetchMultilingualData`（默认 tag 与可选的独立 intl 实例并行）。
+2. **`useSubappIntl`**：若 `subappIntlConfig` 有效则优先 **独立实例** `i18n`；否则在未启用中台时仅用 Umi，启用时优先包内 **`i18n`**；与 `defaultMessage` 比较后决定是否采用 Umi 译文。
+3. **`subappIntlConfig.ts`**：默认返回 `undefined`；返回含 **`tag`、`app_name`** 的对象即启用独立 intl（见 `subappOwnIntl.ts` 内 `initIntl`）。
+
+## 文件清单
+
+### 新增 / 模块目录
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/common/intl/subappIntlConfig.ts` | 独立 intl 配置入口 `getSubappIntlInitOptions()` |
+| `src/common/intl/subappOwnIntl.ts` | 条件 `initIntl`、独立 `fetchMultilingualData` |
+| `src/common/intl/useSubappIntl.ts` | 页面统一 Hook |
+| `src/common/intl/intlRuntime.ts` | `isCommonIntlEnabled`（`window.__MICO_CONFIG__.intl` / `commonIntl`） |
+| `src/common/intl/types.ts` | `IMicoConfigCommonIntl` |
+| `src/common/intl/index.ts` | 对外导出 |
+| `src/common/intl/localeMapping.ts` | Umi locale ↔ `ILang`（模板已存在） |
+| `src/common/intl/subappLocale.ts` | 当前 Umi 风格 locale（模板已存在） |
+| `src/locales/zh-CN.ts` | Umi 兜底文案 |
+| `src/locales/en-US.ts` | Umi 兜底文案 |
+
+### 修改
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `config/config.ts` | 开启 `locale` 插件 |
+| `src/app.tsx` | `configureLocale`、`export const locale`、`render` 预拉取 |
+| `src/pages/index.tsx` | 国际化示例区（可选参考） |
+| `typings.d.ts` | `__MICO_CONFIG__.intl` / `commonIntl` 类型 |
+
+## API / 组件接口
+
+### `useSubappIntl`
+
+```typescript
+const {
+  formatMessage,       // 与 layout useLayoutIntl 相同签名
+  commonIntlEnabled,   // 是否启用中台（有效 tag + app_name）
+  locale,              // 当前 Umi 风格 locale 字符串
+  subappOwnIntl,       // 是否启用子应用独立 initIntl
+  subappOwnIntlTag,    // 独立 tag（未启用时为 undefined）
+} = useSubappIntl();
+```
+
+**参数说明**：无入参；`formatMessage` 第二参数为插值对象，与 `useIntl().formatMessage` 一致。
+
+### `getSubappIntlInitOptions`
+
+返回 `undefined` 表示使用包默认实例；返回 `ISubappIntlInitOptions` 时需至少包含 **`tag`**、**`app_name`**，可选 **`indexedDBParams`**（与 `packages/common-intl` README 一致）。
+
+## 使用示例
+
+```tsx
+import { useSubappIntl } from '@/common/intl';
+
+export default function Page() {
+  const { formatMessage, commonIntlEnabled, locale, subappOwnIntl, subappOwnIntlTag } =
+    useSubappIntl();
+
+  return (
+    <p>
+      {formatMessage(
+        { id: 'page.subapp.home.title', defaultMessage: '标题' },
+      )}
+    </p>
+  );
+}
+```
+
+独立 intl（节选，`subappIntlConfig.ts`）：
+
+```typescript
+export function getSubappIntlInitOptions() {
+  return {
+    tag: 'my_subapp_tag',
+    app_name: 'middle',
+    indexedDBParams: { dbName: 'my_subapp_i18n_db' },
+  };
+}
+```
+
+启用独立 tag 且生产仍使用 `externals` 指向主应用 `CommonIntl` 时，需评估与上游 **多实例 / 单例** 语义是否冲突，详见 **`generators/micro-react/templates/packages/common-intl/README.md`**「不同 tag」。
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| 统一 Hook | `useSubappIntl` 对齐 `useLayoutIntl` | 与主应用行为一致，intl 与 Umi 兜底规则可维护 |
+| 独立 intl 配置 | 单一入口 `getSubappIntlInitOptions` | 默认关闭，按需开启，避免误初始化 |
+| 预拉取 | `render` 内并行 fetch 默认 tag + 独立实例 | 首屏前尽量拉齐中台数据，失败仍渲染 |
+
+## 已知限制与待改进
+
+- 独立 intl 与 **externals 共享同一 `common-intl` 运行时** 时的边界行为以 **上游包** 为准；若需完全隔离，可能需调整打包策略（见 common-intl README）。
+- `LOCALE_REQUEST_URL` 未配置时，行为依赖上游 `fetchMultilingualData` 实现。
+
+## 注意事项
+
+- 主应用通过 qiankun 注入的 **`locale`** 会参与 `getSubappCurrentLocale`；独立运行依赖本地存储与 URL。
+- 中台未配置时 **`commonIntlEnabled`** 为 `false`，页面仅走 Umi `locales`。
+
+## 相关文档
+
+- [packages/common-intl README](../../../../micro-react/templates/packages/common-intl/README.md)
+- [子应用国际化（CLI 仓库总览）](../../../../../docs/feat-subapp-国际化翻译.md)
+- [Layout 国际化](../../../../../docs/feat-layout-国际化翻译.md)

package/generators/subapp-react/templates/homepage/package.json

@@ -19,7 +19,9 @@
     "@mico-platform/theme": "<%= themeVersion %>",
     "@umijs/max": "^4.4.8",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react-dom": "^18.2.0",
+    "<%= packageScope %>/common-intl": "workspace:*",
+    "<%= packageScope %>/shared": "workspace:*"
   },
   "devDependencies": {
     "@mico-platform/ui": "<%= micoUiVersion %>",