generator-mico-cli 0.2.29 → 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` 生成器就近说明 |
 
 ## 要求
 
@@ -69,6 +70,7 @@ mico doctor
 ```json
 {
   "projectName": "my-app",
+  "appId": "portal_dev",
   "packageScope": "@my-company",
   "cdnPrefix": "portal",
   "author": "Team <team@example.com>",
@@ -82,6 +84,7 @@ mico doctor
 | 字段 | 类型 | 适用生成器 | 说明 | 默认值 |
 |------|------|-----------|------|--------|
 | `projectName` | string | micro-react | 项目名称 | 当前目录名 |
+| `appId` | string | micro-react | 开发环境 `window.__MICO_CONFIG__.appId`（请求代理等） | `portal_dev` |
 | `packageScope` | string | 所有 | 包作用域（如 `@my-company`） | micro-react: `@<projectName>`；其他: 从根 `package.json` 检测 |
 | `cdnPrefix` | string | micro-react | CDN 路径前缀（如 `portal`、`admin/v2`） | 空字符串 |
 | `author` | string | micro-react | 作者信息 | `Your Name <email@example.com>` |

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

@@ -76,6 +76,18 @@ module.exports = class extends Generator {
             return true;
           },
         },
+        {
+          type: 'input',
+          name: 'appId',
+          message:
+            'App ID（开发环境 window.__MICO_CONFIG__.appId，用于请求代理 / 网关等）',
+          default: rc.appId || 'portal_dev',
+          validate: (input) => {
+            const v = String(input ?? '').trim();
+            if (!v) return 'App ID is required';
+            return true;
+          },
+        },
         {
           type: 'input',
           name: 'packageScope',
@@ -91,7 +103,7 @@ module.exports = class extends Generator {
         {
           type: 'input',
           name: 'cdnPrefix',
-          message: `CDN path prefix (用于区分不同业务线的 CDN 目录)
+          message: `CDN path prefix (用于区分不同业务线的 CDN 目录,一般是运营配置的group名,切记不可乱填)
    示例：CDN 完整路径 = https://cdn.example.com/<prefix>/<projectName>/<version>/
    - 留空: https://cdn.example.com/my-project/1.0.0/
    - 输入 "portal": https://cdn.example.com/portal/my-project/1.0.0/
@@ -119,6 +131,7 @@ module.exports = class extends Generator {
 
       this.projectName = toKebab(this.answers.projectName);
       this.ProjectName = toPascal(this.projectName);
+      this.appId = String(this.answers.appId ?? '').trim();
       this.packageScope = this.answers.packageScope;
       this.cdnPrefix = this.answers.cdnPrefix;
       this.author = this.answers.author;
@@ -173,6 +186,9 @@ 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,
         micoUiVersion: `^${micoUiVer}`,
@@ -204,6 +220,7 @@ module.exports = class extends Generator {
         this.log('\x1b[33m📋 Dry run mode - no files will be created\x1b[0m');
         this.log('');
         this.log(`   Project: ${this.projectName}`);
+        this.log(`   App ID: ${this.appId}`);
         this.log(`   Scope: ${this.packageScope}`);
         this.log(`   Destination: ${this.destDir}`);
         this.log('');
@@ -239,6 +256,7 @@ module.exports = class extends Generator {
 
       this.log('');
       this.log(`📦 Creating project: ${this.projectName}`);
+      this.log(`   App ID: ${this.appId}`);
       this.log(`   Scope: ${this.packageScope}`);
       this.log('');
 

package/generators/micro-react/templates/CICD/start_dev.sh

@@ -14,6 +14,7 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # 用 node 命令读取 package.json 里的 version 字段
 VERSION=$(node -p "require('$PROJECT_ROOT/package.json').version")
+export VERSION
 # 输出项目版本号
 echo "项目版本: $VERSION"
 
@@ -23,6 +24,16 @@ cd "$PROJECT_ROOT"
 # 导出 PROJECT_ROOT 供 before_build.sh 使用
 export PROJECT_ROOT
 
+# Jenkins 等 CI 注入的构建号（供 Sentry release、layout window.__MICO_BUILD__ 等）
+export BUILD_NUMBER="${BUILD_NUMBER:-}"
+echo "BUILD_NUMBER: ${BUILD_NUMBER:-<unset>}"
+
+export GIT_COMMIT="${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo '')}"
+export BRANCH_OR_TAG="${BRANCH_OR_TAG:-${GIT_BRANCH:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')}}"
+export BUILD_TIME="${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")}"
+echo "GIT_COMMIT: ${GIT_COMMIT:-<empty>}"
+echo "BRANCH_OR_TAG: ${BRANCH_OR_TAG:-<empty>}"
+
 # 在执行构建前，计算 BASE_REF / TURBO_FILTER 等增量构建信息
 if [ -f "$PROJECT_ROOT/CICD/before_build.sh" ]; then
   # shellcheck disable=SC1090

package/generators/micro-react/templates/CICD/start_local.sh

@@ -14,12 +14,21 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # 用 node 命令读取 package.json 里的 version 字段
 VERSION=$(node -p "require('$PROJECT_ROOT/package.json').version")
+export VERSION
 # 输出项目版本号
 echo "项目版本: $VERSION"
 
 # 切换到项目根目录，确保后续命令在根目录下运行
 cd "$PROJECT_ROOT"
 
+# Jenkins 等 CI 注入的构建号（供 Sentry release、layout window.__MICO_BUILD__ 等）
+export BUILD_NUMBER="${BUILD_NUMBER:-}"
+echo "BUILD_NUMBER: ${BUILD_NUMBER:-<unset>}"
+
+export GIT_COMMIT="${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo '')}"
+export BRANCH_OR_TAG="${BRANCH_OR_TAG:-${GIT_BRANCH:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')}}"
+export BUILD_TIME="${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")}"
+
 # 设置子应用的 CDN 公共路径（本地环境使用相对路径）
 export CDN_PUBLIC_PATH="./"
 echo "CDN_PUBLIC_PATH: $CDN_PUBLIC_PATH"

package/generators/micro-react/templates/CICD/start_prod.sh

@@ -14,6 +14,7 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # 用 node 命令读取 package.json 里的 version 字段
 VERSION=$(node -p "require('$PROJECT_ROOT/package.json').version")
+export VERSION
 # 输出项目版本号
 echo "项目版本: $VERSION"
 
@@ -23,6 +24,18 @@ cd "$PROJECT_ROOT"
 # 导出 PROJECT_ROOT 供 before_build.sh 使用
 export PROJECT_ROOT
 
+# Jenkins 等 CI 注入的构建号（供 Sentry release、layout window.__MICO_BUILD__ 等）
+export BUILD_NUMBER="${BUILD_NUMBER:-}"
+echo "BUILD_NUMBER: ${BUILD_NUMBER:-<unset>}"
+
+# 供 Umi define 注入 window.__MICO_BUILD__（与 package.json 一致；未导出时子进程 process.env.VERSION 为空）
+# Jenkins 常注入 GIT_BRANCH / GIT_COMMIT，BRANCH_OR_TAG 为业务约定名时可由 Job 覆盖
+export GIT_COMMIT="${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo '')}"
+export BRANCH_OR_TAG="${BRANCH_OR_TAG:-${GIT_BRANCH:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')}}"
+export BUILD_TIME="${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")}"
+echo "GIT_COMMIT: ${GIT_COMMIT:-<empty>}"
+echo "BRANCH_OR_TAG: ${BRANCH_OR_TAG:-<empty>}"
+
 # 在执行构建前，计算 BASE_REF / TURBO_FILTER 等增量构建信息（用于增量构建）
 if [ -f "$PROJECT_ROOT/CICD/before_build.sh" ]; then
   # shellcheck disable=SC1090

package/generators/micro-react/templates/CICD/start_test.sh

@@ -14,6 +14,7 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 # 用 node 命令读取 package.json 里的 version 字段
 VERSION=$(node -p "require('$PROJECT_ROOT/package.json').version")
+export VERSION
 # 输出项目版本号
 echo "项目版本: $VERSION"
 
@@ -23,6 +24,16 @@ cd "$PROJECT_ROOT"
 # 导出 PROJECT_ROOT 供 before_build.sh 使用
 export PROJECT_ROOT
 
+# Jenkins 等 CI 注入的构建号（供 Sentry release、layout window.__MICO_BUILD__ 等）
+export BUILD_NUMBER="${BUILD_NUMBER:-}"
+echo "BUILD_NUMBER: ${BUILD_NUMBER:-<unset>}"
+
+export GIT_COMMIT="${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo '')}"
+export BRANCH_OR_TAG="${BRANCH_OR_TAG:-${GIT_BRANCH:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')}}"
+export BUILD_TIME="${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")}"
+echo "GIT_COMMIT: ${GIT_COMMIT:-<empty>}"
+echo "BRANCH_OR_TAG: ${BRANCH_OR_TAG:-<empty>}"
+
 # 在执行构建前，计算 BASE_REF / TURBO_FILTER 等增量构建信息
 if [ -f "$PROJECT_ROOT/CICD/before_build.sh" ]; then
   # shellcheck disable=SC1090

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

@@ -19,7 +19,7 @@ const config: ReturnType<typeof defineConfig> = {
         window.__MICO_MENUS__ = ${JSON.stringify(mockMenus)};
         window.__MICO_PAGES__ = ${JSON.stringify(mockPages)};
         window.__MICO_CONFIG__ = {
-          appId: '<%= projectName %>',
+          appId: '<%= appId %>',
           appName: '<%= projectName %>',
           title: '测试样例',
           logo: '',
@@ -34,8 +34,14 @@ const config: ReturnType<typeof defineConfig> = {
           // 关闭权限控制（调试用）
           disableAuth: false,
           // SSO 外跳地址（与 resolveExternalLoginPath 读取的 externalLoginPath 一致；生产由注入的 __MICO_CONFIG__ 提供）
-          externalLoginPath:
-            'https://micous-idp.cig.tencentcs.com/sso/xxxxxxx/cas',
+          externalLoginPath: 'https://micous-idp.cig.tencentcs.com/sso/tn-456d1d3feb5f4e09ad28ab35ee4d2e66/ai-4919cf3d4883490b956b90376cfb86e7/cas',
+          // 多语言中台（可选）：intl 与 common-intl 包 initIntl 合并；见 packages/common-intl/README.md
+          // 这里只是一个例子，需要根据业务在翻译中台的配置来替换
+          // intl: {
+          //   tag: 'cs_fe_pc',
+          //   app_name: 'middle',
+          //   indexedDBParams: { dbName: 'mico_cs_pc_i18n_db' },
+          // },
         };
       `,
     },
@@ -74,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.prod.development.ts

@@ -1,8 +1,13 @@
 // https://umijs.org/config/
 
 import { defineConfig } from '@umijs/max';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 // 开发环境，不上传 sourcemap。调试时如有需要再解开
 // import { applySentryPlugin } from "../../../scripts/apply-sentry-plugin";
+const packageVersion: string = JSON.parse(
+  readFileSync(join(__dirname, '../../../package.json'), 'utf-8'),
+).version;
 const { CDN_PUBLIC_PATH } = process.env;
 
 const PUBLIC_PATH: string = CDN_PUBLIC_PATH
@@ -33,6 +38,11 @@ const config: ReturnType<typeof defineConfig> = {
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/',
     'process.env.REFRESH_ENDPOINT':
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/refresh/',
+    'process.env.BUILD_NUMBER': process.env.BUILD_NUMBER ?? '',
+    'process.env.BRANCH_OR_TAG': process.env.BRANCH_OR_TAG ?? '',
+    'process.env.GIT_COMMIT': process.env.GIT_COMMIT ?? '',
+    'process.env.VERSION': process.env.VERSION ?? packageVersion,
+    'process.env.BUILD_TIME': process.env.BUILD_TIME ?? '',
     'process.env.LOCALE_REQUEST_URL':
       'https://api-test.micoplatform.com/lang_server/pull',
   },

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

@@ -1,8 +1,13 @@
 // https://umijs.org/config/
 
 import { defineConfig } from '@umijs/max';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 // 测试环境，不上传 sourcemap。调试时如有需要再解开
 // import { applySentryPlugin } from "../../../scripts/apply-sentry-plugin";
+const packageVersion: string = JSON.parse(
+  readFileSync(join(__dirname, '../../../package.json'), 'utf-8'),
+).version;
 const { CDN_PUBLIC_PATH } = process.env;
 
 const PUBLIC_PATH: string = CDN_PUBLIC_PATH
@@ -33,6 +38,11 @@ const config: ReturnType<typeof defineConfig> = {
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/',
     'process.env.REFRESH_ENDPOINT':
       'https://dashboard-api-test.micoplatform.com/api/yufu_login/refresh/',
+    'process.env.BUILD_NUMBER': process.env.BUILD_NUMBER ?? '',
+    'process.env.BRANCH_OR_TAG': process.env.BRANCH_OR_TAG ?? '',
+    'process.env.GIT_COMMIT': process.env.GIT_COMMIT ?? '',
+    'process.env.VERSION': process.env.VERSION ?? packageVersion,
+    'process.env.BUILD_TIME': process.env.BUILD_TIME ?? '',
     'process.env.LOCALE_REQUEST_URL':
       'https://api-test.micoplatform.com/lang_server/pull',
   },

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

@@ -1,7 +1,14 @@
 // https://umijs.org/config/
 
 import { defineConfig } from '@umijs/max';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { applySentryPlugin } from '../../../scripts/apply-sentry-plugin';
+
+const packageVersion: string = JSON.parse(
+  readFileSync(join(__dirname, '../../../package.json'), 'utf-8'),
+).version;
+
 const { CDN_PUBLIC_PATH } = process.env;
 
 const PUBLIC_PATH: string = CDN_PUBLIC_PATH
@@ -21,6 +28,11 @@ const config: ReturnType<typeof defineConfig> = {
       'https://dashboard-api.micoplatform.com/api/yufu_login/',
     'process.env.REFRESH_ENDPOINT':
       'https://dashboard-api.micoplatform.com/api/yufu_login/refresh/',
+    'process.env.BUILD_NUMBER': process.env.BUILD_NUMBER ?? '',
+    'process.env.BRANCH_OR_TAG': process.env.BRANCH_OR_TAG ?? '',
+    'process.env.GIT_COMMIT': process.env.GIT_COMMIT ?? '',
+    'process.env.VERSION': process.env.VERSION ?? packageVersion,
+    'process.env.BUILD_TIME': process.env.BUILD_TIME ?? '',
     'process.env.LOCALE_REQUEST_URL':
       'https://api.micoplatform.com/lang_server/pull',
   },

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-/345/233/275/351/231/205/345/214/226.md

@@ -0,0 +1,121 @@
+# 国际化（common-intl 与 Umi 兜底）
+
+> 创建时间：2026-04-07
+
+## 功能概述
+
+layout 主应用通过 **`<%= packageScope %>/common-intl`**（`packages/common-intl` 中转包）绑定中台 **`tag`**，在 **`app.tsx`** 中 **`configureLocale`** 与 Umi **`umi_locale`** 对齐；当 **`window.__MICO_CONFIG__.intl` 或 `commonIntl`** 含有效 **`tag`、`app_name`** 时视为启用中台，首屏在 **`render`** 中 **`fetchMultilingualData`**。业务侧统一使用 **`useLayoutIntl()`**：**`i18n` 优先**，与 `defaultMessage` 比较后未命中则 **Umi `formatMessage`**（`src/locales/*`）。未启用中台时 **仅 Umi**。
+
+## 技术方案
+
+### 技术栈
+
+- Umi 4 `@umijs/max`：`locale` 运行时、`export const locale`、`useIntl`
+- `<%= packageScope %>/common-intl`：`configureLocale`、`fetchMultilingualData`、`i18n`、`intl`（包内 `initIntl`）
+- 门控与类型：`src/common/intl/intlRuntime.ts`、`types.ts`
+
+### 核心实现
+
+1. **`app.tsx`**：最早 **`configureLocale({ getLocale, setLocale })`**，与 **`getCurrentLocale`** / **`setLocaleToStorage`**（`src/common/locale.ts`）及 **`localeMapping`** 一致；**`export const locale`** 供 Umi 插件；**`render`** 仅在 **`isCommonIntlEnabled()`** 为真时调用 **`fetchMultilingualData`**（`request`、`Message`、`lang`、`LOCALE_REQUEST_URL`）。
+2. **`useLayoutIntl.ts`**：读取 **`isCommonIntlEnabled()`**；启用时 **`i18n({ key, defaultMessage })`**，否则直接 **`useIntl().formatMessage`**；兜底规则与 **`defaultMessage`**、Umi 结果比较（同子应用 **`useSubappIntl`** 策略）。
+3. **全局暴露**：**`window.CommonIntl`** 指向包模块，供子应用 **externals** 复用。
+4. **包内实现**：**`packages/common-intl/src/intl.ts`** 中 **`initIntl`** 合并 **`__MICO_CONFIG__`** 与默认 tag，详见包 README。
+
+## 文件清单（相对 `apps/layout`）
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/common/intl/useLayoutIntl.ts` | 页面统一 Hook |
+| `src/common/intl/intlRuntime.ts` | `isCommonIntlEnabled`、`getCommonIntlConfig` |
+| `src/common/intl/localeMapping.ts` | Umi locale ↔ `ILang` |
+| `src/common/intl/types.ts` | `IMicoConfigCommonIntl` |
+| `src/common/intl/index.ts` | 导出 `useLayoutIntl`、`intl`、`isCommonIntlEnabled` 等 |
+| `src/common/locale.ts` | URL / storage / 浏览器语言（与 Umi 一致） |
+| `src/app.tsx` | `configureLocale`、`locale`、`render`、**`window.CommonIntl`** |
+| `config/config.ts` | `locale` 插件（`default`、`antd: false`、`baseNavigator: false`） |
+| `src/locales/zh-CN.ts`、`en-US.ts` | Umi 兜底文案 |
+| `src/pages/Home/index.tsx` | 国际化用法示例（可选参考） |
+
+## API / 组件接口
+
+### `useLayoutIntl`
+
+```typescript
+const {
+  formatMessage,       // 与 useIntl 相同 descriptor / values 签名
+  commonIntlEnabled,   // 是否启用中台（有效 tag + app_name）
+  locale,              // 当前 Umi 风格 locale（getCurrentLocale）
+  intl,                // 包内便捷对象，仅 commonIntlEnabled 为 true 时非 undefined
+} = useLayoutIntl();
+```
+
+### `window.__MICO_CONFIG__.intl` / `commonIntl`
+
+二者取其一（见 `intlRuntime`），字段含义一致：
+
+| 字段 | 说明 |
+| --- | --- |
+| `tag` | 多语言中台 tag（必填） |
+| `app_name` | 中台应用名（必填） |
+| `indexedDBParams` | 可选本地缓存参数 |
+
+## 使用示例
+
+**运行时注入（示例）：**
+
+```javascript
+window.__MICO_CONFIG__ = {
+  commonIntl: {
+    tag: 'cs_fe_pc',
+    app_name: 'middle',
+    indexedDBParams: { dbName: 'mico_cs_web_i18n_db' },
+  },
+};
+```
+
+**页面：**
+
+```tsx
+import { useLayoutIntl } from '@/common/intl';
+
+const { formatMessage, commonIntlEnabled, locale } = useLayoutIntl();
+
+return (
+  <span>
+    {formatMessage({ id: 'page.home.title', defaultMessage: '首页' })}
+  </span>
+);
+```
+
+**包内预置文案（中台 key 亦可走 `i18n`）：**
+
+```tsx
+import { intl } from '@/common/intl';
+
+intl.common_hello();
+```
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| 门控 | `intl` 与 `commonIntl` 字段兼容 | 与注入脚本、历史配置一致 |
+| 首屏拉取 | 仅 `isCommonIntlEnabled()` 时 `render` 内 fetch | 未配置中台时不阻塞首屏 |
+| 合并策略 | `i18n` 与 Umi 二选一兜底 | 与微前端子应用 `useSubappIntl` 对齐，便于维护 |
+
+## 已知限制与待改进
+
+- **`LOCALE_REQUEST_URL`** 未配置时，行为依赖上游 **`fetchMultilingualData`** 实现。
+- 中台文案与 **`src/locales`** 的 key 需自行约定，避免重复 id 语义冲突。
+
+## 注意事项
+
+- 修改语言时请走与 **`getCurrentLocale`** / **`setLocaleToStorage`** 一致的入口，避免与 **`configureLocale`** 脱节。
+- 子应用不复制上述 **`render`** 逻辑时，嵌入主应用后通常仍依赖主应用已加载的 **`CommonIntl`**；独立运行子应用需自行 **`render` + fetch**（见子应用模板文档）。
+
+## 相关文档
+
+- [packages/common-intl README](../../../../packages/common-intl/README.md)
+- [Layout 国际化（CLI 仓库总览）](../../../../../../docs/feat-layout-国际化翻译.md)
+- [子应用国际化（模板内说明）](../../../../../subapp-react/templates/homepage/docs/feature-国际化.md)
+- [微前端模式](./feature-微前端模式.md)（主应用暴露 `CommonIntl`）