generator-mico-cli 0.2.31 → 0.2.32

package/generators/h5-react/index.js

@@ -0,0 +1,349 @@
+'use strict';
+
+const Generator = require('yeoman-generator');
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  toKebab,
+  toPascal,
+  collectFiles,
+  transformDestPath,
+  isTemplateFile,
+  setupErrorHandlers,
+  createLogger,
+  loadMicorc,
+} = require('../../lib/utils');
+
+const IGNORE_LIST = require('./ignore-list.json');
+
+setupErrorHandlers();
+
+module.exports = class extends Generator {
+  initializing() {
+    this.projectRoot = process.cwd();
+    this.logger = createLogger(this);
+
+    this.isDryRun = this.options.dryRun || process.env.MICO_DRY_RUN === '1';
+
+    const { config: rcConfig, configPath } = loadMicorc(this.projectRoot);
+    this.rcConfig = rcConfig;
+    if (configPath) {
+      this.logger.verbose('Loaded config from:', configPath);
+      this.logger.verbose('Config:', JSON.stringify(rcConfig, null, 2));
+    }
+
+    const workspaceFile = path.join(this.projectRoot, 'pnpm-workspace.yaml');
+    if (fs.existsSync(workspaceFile) && !this.options.force) {
+      console.error('');
+      console.error('❌ Error: Current directory is already a monorepo.');
+      console.error('');
+      console.error('   A pnpm-workspace.yaml file already exists.');
+      console.error(
+        '   Please run this command in an empty directory or specify a new project name.',
+      );
+      console.error('');
+      console.error('   Usage:');
+      console.error('     mkdir my-h5 && cd my-h5');
+      console.error('     mico create h5-react');
+      console.error('');
+      console.error('   To regenerate in an existing monorepo, use --force:');
+      console.error('     mico create h5-react --force');
+      console.error('');
+      process.exit(1);
+    }
+  }
+
+  async prompting() {
+    try {
+      const rc = this.rcConfig || {};
+
+      this.answers = await this.prompt([
+        {
+          type: 'input',
+          name: 'projectName',
+          message: 'Project name',
+          default: rc.projectName || path.basename(this.projectRoot),
+          filter: (input) => toKebab(input),
+          validate: (input) => {
+            const value = toKebab(input);
+            if (!value) return 'Project name is required';
+            return true;
+          },
+        },
+        {
+          type: 'input',
+          name: 'packageScope',
+          message: 'Package scope (e.g., @my-project)',
+          default: (answers) => rc.packageScope || `@${toKebab(answers.projectName)}`,
+          validate: (input) => {
+            if (!input) return 'Package scope is required';
+            if (!input.startsWith('@')) return 'Package scope must start with @';
+            return true;
+          },
+        },
+        {
+          type: 'input',
+          name: 'cdnPrefix',
+          message: `CDN path prefix (用于区分不同业务线的 CDN 目录)
+   示例：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/
+   - 输入 "admin/v2": https://cdn.example.com/admin/v2/my-project/1.0.0/
+   Prefix`,
+          default: rc.cdnPrefix || '',
+          filter: (input) => {
+            return input.trim().replace(/^\/+|\/+$/g, '');
+          },
+        },
+        {
+          type: 'input',
+          name: 'author',
+          message: 'Author',
+          default: rc.author || 'Your Name <email@example.com>',
+        },
+        {
+          type: 'input',
+          name: 'initialSubAppName',
+          message: 'First sub-app name (directory under apps/)',
+          default: rc.initialSubAppName || 'app',
+          filter: (input) => toKebab(input),
+          validate: (input) => {
+            const value = toKebab(input);
+            if (!value) return 'Sub-app name is required';
+            const destDir = path.join(this.projectRoot, 'apps', value);
+            if (fs.existsSync(destDir)) {
+              return `Target already exists: apps/${value}`;
+            }
+            return true;
+          },
+        },
+        {
+          type: 'input',
+          name: 'initialSubAppDevPort',
+          message: 'First sub-app dev port (standalone pnpm dev in that app)',
+          default: rc.initialSubAppDevPort || '8000',
+          validate: (input) => {
+            const port = Number(input);
+            if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+              return 'Port must be an integer between 1024 and 65535';
+            }
+            return true;
+          },
+        },
+      ]);
+
+      this.projectName = toKebab(this.answers.projectName);
+      this.ProjectName = toPascal(this.projectName);
+      this.packageScope = this.answers.packageScope;
+      this.cdnPrefix = this.answers.cdnPrefix;
+      this.author = this.answers.author;
+      this.initialSubAppName = toKebab(this.answers.initialSubAppName);
+      this.initialSubAppDevPort = String(this.answers.initialSubAppDevPort);
+      this.templateDir = this.templatePath();
+      this.destDir = this.projectRoot;
+    } catch (error) {
+      console.error('');
+      console.error('❌ Error during prompting:');
+      console.error(`   ${error.message}`);
+      console.error('');
+      process.exit(1);
+    }
+  }
+
+  async writing() {
+    try {
+      if (!fs.existsSync(this.templateDir)) {
+        console.error('');
+        console.error('❌ Error: Template directory not found.');
+        console.error(`   Expected: ${this.templateDir}`);
+        console.error('');
+        process.exit(1);
+      }
+
+      this.logger.verbose('Template directory:', this.templateDir);
+      this.logger.verbose('Destination directory:', this.destDir);
+
+      const cdnPrefixPath = this.cdnPrefix ? `${this.cdnPrefix}/` : '';
+
+      const templateData = {
+        projectName: this.projectName,
+        ProjectName: this.ProjectName,
+        packageScope: this.packageScope,
+        author: this.author,
+        cdnPrefix: this.cdnPrefix,
+        cdnPrefixPath,
+      };
+
+      this.logger.verbose('Template data:', JSON.stringify(templateData, null, 2));
+
+      const files = collectFiles(this.templateDir, this.templateDir, IGNORE_LIST);
+
+      if (files.length === 0) {
+        console.error('');
+        console.error('❌ Error: No template files found.');
+        console.error(`   Template directory: ${this.templateDir}`);
+        console.error('');
+        process.exit(1);
+      }
+
+      if (this.isDryRun) {
+        this.log('');
+        this.log('\x1b[33m📋 Dry run mode - no files will be created\x1b[0m');
+        this.log('');
+        this.log(`   Project: ${this.projectName}`);
+        this.log(`   Scope: ${this.packageScope}`);
+        this.log(`   CDN prefix: ${this.cdnPrefix || '(empty)'}`);
+        this.log(`   First sub-app: ${this.initialSubAppName} (via subapp-h5)`);
+        this.log(`   Destination: ${this.destDir}`);
+        this.log('');
+        this.log('   Would create the following files:');
+        this.log('');
+
+        let templateCount = 0;
+        let copyCount = 0;
+
+        for (const relPath of files) {
+          const destRelPath = transformDestPath(relPath);
+          const isTemplate = isTemplateFile(relPath);
+          const tag = isTemplate ? '\x1b[32m[tpl]\x1b[0m' : '\x1b[36m[cpy]\x1b[0m';
+          this.log(`   ${tag} ${destRelPath}`);
+
+          if (isTemplate) {
+            templateCount++;
+          } else {
+            copyCount++;
+          }
+        }
+
+        this.log('');
+        this.log(
+          `   Total: ${files.length} files (${templateCount} templates, ${copyCount} static)`,
+        );
+        this.log('');
+        this.log(
+          `   Then would run generator subapp-h5 → apps/${this.initialSubAppName}/ (not executed in dry-run).`,
+        );
+        this.log('');
+        this.log('   Run without --dry-run to actually create these files.');
+        this.log('');
+
+        this._skipInstall = true;
+        return;
+      }
+
+      this.log('');
+      this.log(`📦 Creating H5 monorepo: ${this.projectName}`);
+      this.log(`   Scope: ${this.packageScope}`);
+      this.log('');
+
+      this.logger.verbose(`Processing ${files.length} files...`);
+
+      let templateCount = 0;
+      let copyCount = 0;
+
+      for (const relPath of files) {
+        const srcPath = path.join(this.templateDir, relPath);
+        const destRelPath = transformDestPath(relPath);
+        const destPath = path.join(this.destDir, destRelPath);
+
+        if (isTemplateFile(relPath)) {
+          this.logger.file('template', destRelPath);
+          this.fs.copyTpl(srcPath, destPath, templateData);
+          templateCount++;
+        } else {
+          this.logger.file('copy', destRelPath);
+          this.fs.copy(srcPath, destPath);
+          copyCount++;
+        }
+      }
+
+      this.logger.verbose(`Processed: ${templateCount} templates, ${copyCount} copied`);
+
+      // Yeoman 此阶段文件尚在 mem-fs，尚未落盘；subapp-h5 的 initializing 会用 fs 检查 apps/，
+      // 且其更新根配置时会读磁盘。先保证磁盘上存在 apps/，子应用再通过 this.fs 读写根目录文件。
+      const appsDirOnDisk = path.join(this.destDir, 'apps');
+      fs.mkdirSync(appsDirOnDisk, { recursive: true });
+
+      const subappGen = path.resolve(__dirname, '../subapp-h5/index.js');
+      this.log('');
+      this.log(`📦 联动创建首个子应用: apps/${this.initialSubAppName}`);
+      this.log('');
+      await this.composeWith(subappGen, {
+        composedFromH5React: true,
+        skipInstall: true,
+        skipEndMessage: true,
+        composeAnswers: {
+          appName: this.initialSubAppName,
+          packageScope: this.packageScope,
+          devPort: this.initialSubAppDevPort,
+          author: this.author,
+        },
+      });
+    } catch (error) {
+      console.error('');
+      console.error('❌ Error during file generation:');
+      console.error(`   ${error.message}`);
+      console.error('');
+      process.exit(1);
+    }
+  }
+
+  install() {
+    if (this._skipInstall) return;
+
+    const gitDir = path.join(this.destDir, '.git');
+    if (!fs.existsSync(gitDir)) {
+      this.log('');
+      this.log('🔧 初始化 Git 仓库...');
+      this.spawnCommandSync('git', ['init'], {
+        cwd: this.destDir,
+      });
+    }
+
+    this.log('');
+    this.log('📦 正在安装依赖...');
+    try {
+      this.spawnCommandSync('pnpm', ['install'], {
+        cwd: this.destDir,
+      });
+    } catch (e) {
+      this._installFailed = true;
+      this.log('');
+      this.log('⚠️  依赖安装失败，但项目文件已全部生成。');
+      this.logger.verbose('Install error:', e.message);
+      return;
+    }
+  }
+
+  end() {
+    if (this._skipInstall) return;
+
+    this.log('');
+
+    if (this._installFailed) {
+      this.log('⚠️  项目文件已创建，但依赖安装未完成。');
+      this.log('');
+      this.log('   请手动安装依赖:');
+      this.log('');
+      this.log('   pnpm install');
+      this.log('');
+      this.log('   如果安装仍然失败，可尝试:');
+      this.log('   pnpm install --network-concurrency 4');
+    } else {
+      this.log('✅ 项目创建成功！');
+    }
+
+    this.log('');
+    this.log('   后续步骤:');
+    this.log('');
+    this.log('   # 网关开发（单端口代理多应用）');
+    this.log('   pnpm dev:gateway');
+    this.log('');
+    this.log('   # 或按 dev 预设并行启动（见 dev.preset.json）');
+    this.log('   pnpm dev:preset');
+    this.log('');
+    this.log('   # 新增更多子应用（可在 monorepo 根目录多次执行）');
+    this.log('   mico create subapp-h5');
+    this.log('');
+  }
+};

package/generators/h5-react/meta.json

@@ -0,0 +1,11 @@
+{
+  "name": "h5-react",
+  "description": "创建 H5 Monorepo（Umi 4 + 网关 + dev 预设），并联动生成首个子应用",
+  "usage": "mkdir my-h5 && cd my-h5 && mico create h5-react",
+  "features": [
+    "Turborepo + pnpm Workspace + catalog",
+    "开发网关 page.config.ts、dev.preset 多应用并行",
+    "首个子应用由 subapp-h5 生成（不重复维护子应用模板）",
+    "可多次 mico create subapp-h5 扩展业务应用"
+  ]
+}

package/generators/h5-react/templates/.commitlintrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'header-max-length': [0, 'always', 10000],
+    'body-max-line-length': [0, 'always', Infinity],
+  },
+};

package/generators/h5-react/templates/.cursor/rules/cicd-deploy.mdc

@@ -0,0 +1,104 @@
+---
+description: CI/CD 与部署 - Jenkins 构建流程、环境配置、CDN 发布（H5 Monorepo）
+globs: ["CICD/**"]
+---
+
+# CI/CD 与部署
+
+## 构建架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Jenkins                                   │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  根据环境执行对应脚本：                                       ││
+│  │                                                              ││
+│  │  开发环境 → CICD/start_dev.sh   → build:development          ││
+│  │  测试环境 → CICD/start_test.sh  → build:testing              ││
+│  │  生产环境 → CICD/start_prod.sh → build:production           ││
+│  │  本地构建 → CICD/start_local.sh → build:local                ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                              ↓                                   │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  Turborepo 构建后 collect-dist：根目录 dist/<子应用>/        ││
+│  │  上传 CDN：cdn-portal[-env].micoplatform.com/<%= cdnPrefixPath %><%= projectName %>/   ││
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## CICD 脚本
+
+| 脚本 | 环境 | 构建命令 | CDN 路径 |
+|------|------|---------|---------|
+| `start_dev.sh` | 开发 | `build:development` | `cdn-portal-dev.micoplatform.com` |
+| `start_test.sh` | 测试 | `build:testing` | `cdn-portal-test.micoplatform.com` |
+| `start_prod.sh` | 生产 | `build:production` | `cdn-portal.micoplatform.com` |
+| `start_local.sh` | 本地 | `build:local` | `./`（相对路径） |
+
+## 脚本执行流程（摘要）
+
+```bash
+# 1. 安装 Node / pnpm（见各脚本内 nvm 版本）
+pnpm install
+
+# 2. 版本号
+VERSION=$(node -p "require('./package.json').version")
+
+# 3. 静态资源公共路径（与创建项目时填写的 CDN prefix 一致）
+export CDN_PUBLIC_PATH="https://cdn-portal[-env].micoplatform.com/<%= cdnPrefixPath %><%= projectName %>/${VERSION}/"
+
+# 4. 构建（根 package.json 中 turbo + collect-dist）
+pnpm run build:[environment]
+```
+
+## CDN 路径结构
+
+```
+cdn-portal.micoplatform.com/
+<% if (cdnPrefix) { %>└── <%= cdnPrefix %>/
+    └── <%= projectName %>/
+<% } else { %>└── <%= projectName %>/
+<% } %>        └── {version}/
+            └── dist/
+                ├── <子应用 A>/   # Umi 应用，与 apps/ 下目录名对应
+                ├── <子应用 B>/
+                └── ...
+```
+
+创建仓库时 **`mico create h5-react`** 会提示 **CDN path prefix**（可选）；留空则路径中无额外业务线目录段。
+
+## 环境变量
+
+### CDN_PUBLIC_PATH
+
+- 由 `CICD/start_*.sh` 在构建前导出，并在 `turbo.json` 的 `globalEnv` 中声明，主要用于：CDN 上传脚本 / 网宿刷新路径 / 与 Sentry **`urlPrefix`** 对齐的人读路径标记。
+- **不再**作为 Umi 构建期 `publicPath` / `cssPublicPath` 的输入。子应用 `createProConfig` 现固定输出 **`publicPath: 'auto'`** + **`cssPublicPath: './'`**：JS publicPath 由 webpack 在运行时按 HTML 加载位置解析，CSS `url()` 走相对路径，避免与 qiankun slave 默认开启的 `runtimePublicPath` 冲突。
+- 各环境域名见上表；Sentry sourcemap 的 `urlPrefix`（`<%= cdnPrefixPath %><%= projectName %>/<version>/<appName>`）由 **`createProductionConfig`** 内部按 `appName` 拼接，与 `CDN_PUBLIC_PATH` 在路径语义上一致。
+
+### SENTRY_AUTH_TOKEN
+
+- 生产/测试流水线若需上传 Source Map，在 Jenkins 或本地构建环境中注入 **`SENTRY_AUTH_TOKEN`**（**`turbo.json`** 的 **`globalEnv`** 已声明，避免 Turbo 缓存忽略该变量）。
+
+### 版本号
+
+- 从根 **`package.json`** 的 **`version`** 读取，用于 CDN 路径中的版本隔离；**`packages/umi-config/src/plugins/apply-sentry-plugin.ts`** 中 Sentry **`release.name`** 与该文件读取的同一个 **`version`** 一致。
+
+## 构建产物（根目录）
+
+`pnpm build` 成功后，`scripts/collect-dist.js` 将各 **`apps/<名>/dist`** 汇总为根目录 **`dist/<名>/`**，与 CDN 上按子应用划分的目录一致。
+
+## 本地模拟
+
+```bash
+sh CICD/start_test.sh
+sh CICD/start_prod.sh
+sh CICD/start_local.sh
+```
+
+## 注意事项
+
+1. **CDN prefix**：与 **`micro-react`** 生成器语义相同，仅影响路径中是否包含业务线前缀。
+2. **网宿刷新**：见 `wangsu_fresh_*.sh`。
+3. **Turborepo**：增量与 `before_build.sh` 中 `TURBO_FILTER` 等逻辑以脚本为准。
+4. **Sentry sourcemap 已不在 `scripts/`**：上传逻辑封装在 **`packages/umi-config/src/plugins/apply-sentry-plugin.ts`**，由 **`createProductionConfig`** 自动调用；CICD 只需注入 **`SENTRY_AUTH_TOKEN`** 即可，无需手工改子应用 `config.prod.ts`。
+5. **环境变量 `.env*` 集中在仓库根**：`.env`、`.env.development`、`.env.testing`、`.env.production` 维护 `UMI_APP_API_BASE_URL` / `UMI_APP_CDN_BASE_URL` / `UMI_APP_LANG_BASE_URL` / `UMI_APP_ENV` 等；CICD 脚本在调用 `pnpm build:[env]` 之前导出 `CDN_PUBLIC_PATH`，由根 `package.json` 中的 `dotenv-cli` 链注入到子应用进程。

package/generators/h5-react/templates/.cursor/rules/common-intl.mdc

@@ -0,0 +1,42 @@
+---
+description: <%= packageScope %>/common-intl 包实现与在 Umi 应用中的接入约定
+globs: "packages/common-intl/**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# `<%= packageScope %>/common-intl`（`packages/common-intl`）
+
+- 包名 **`<%= packageScope %>/common-intl`**；应用依赖写 **`workspace:^`**，说明见 **`packages/common-intl/README.md`**
+- 本包是 **`@common-web/common-intl`** 的**项目级封装**（re-export + 预配置）。`src/index.ts` 通过 `export * from '@common-web/common-intl'` 透传上游全部 API（`initIntl`、`addIntl`、`configureLocale`、`i18n` 等），同时导出本地的 **`init`** 函数
+- 包依赖 **`@common-web/common-intl`**（上游库）、**`<%= packageScope %>/domain`**（`langBaseUrl`）、**`<%= packageScope %>/request`**（`request`）、**`<%= packageScope %>/js-bridge`**（`getUserInfo` 取语言）
+- **无构建步骤**：`package.json` 的 `exports` 直接指向 **`./src/index.ts`**（源码 TS），无 vite / 无 dist
+
+## `init()` 函数（`src/intl.ts`）
+
+- **`init(params)`** 是项目级便捷入口；接收 `IInitIntlParams`（`app_name` 可选，默认 `<%= projectName %>`，**`tag`**、**`indexedDBParams`** 由调用方传入），返回 `{ fetchMultilingualData, i18n }`
+- 内部 `initIntl()` 即时执行；**`configureLocale`** 与 `requestInstance` 绑定**延迟到** `fetchMultilingualData()` 首次调用：会先经 **`<%= packageScope %>/js-bridge` 的 `getUserInfo()`** 拉到客户端语言（失败兜底 `'en'`），再 `configureLocale({ getLocale: () => lang, setLocale })`
+- `requestInstance` 自动包装 **`<%= packageScope %>/request` 的 `request`**，并强制 **`skipRequestInterceptors: true`**，避免业务请求拦截器影响多语言拉取
+- `messageInstance` 默认走 `console.error / console.warn`，业务需要替换为 toast 时可在子应用层重写
+- 返回的 `fetchMultilingualData()` 已预置 `requestInstance`、`messageInstance`、`lang`、`localeRequestUrl`，子应用调用时**无需再传任何参数**
+
+## 子应用接入（`subapp-h5` 模板）
+
+- **`src/intl.ts`**：`import { addIntl, init } from '<%= packageScope %>/common-intl'`；用 **`init({ tag, indexedDBParams })`** 取得 `{ fetchMultilingualData, i18n }`，再用 **`addIntl({ ... }, i18n)`** 定义文案对象并 `export default`；同时 `export { fetchMultilingualData }`
+- **`src/app.tsx`** 的 **`render`** 仅从 **`@/intl`** 调用 **`fetchMultilingualData()`**，再 **`oldRender()`**（失败同样 **`oldRender()`**）
+- 业务组件 **`import intl from '@/intl'`**，通过 `intl.xxx()` 使用文案；勿在子应用里再从包根导入一份业务 `intl`
+
+## 微前端
+
+- 主应用 **`initIntl`** 拉取后写入全局（`window.__MICO_COMMON_INTL_TRANSLATIONS__`）；子应用只使用共享文案（见 **`packages/common-intl/README.md`** 微前端模式），勿重复初始化
+- 若子应用需要**独立 tag**，直接依赖 `@common-web/common-intl` 在子应用内自行调用 `initIntl`，不经过本中转包
+
+## JSBridge 与语言
+
+- `init()` 中通过 **`getUserInfo()`** 拿 `lang`，需要客户端实现 `getUserInfo` JSBridge；本地/测试环境下 **`<%= packageScope %>/js-bridge`** 的 `getUserInfo` 在 `isDebug` 下会回退 fetch 远程登录接口（仅供联调，不要在线上启用
+
+## 其他
+
+- 占位符为 **`%AA%`、`%BB%`**…，与 **`interpolations`** 顺序对应
+- 修改包内代码后无需单独构建；依赖该包的应用重新 dev / build 即可生效
+
+应用层与 **`<%= packageScope %>/request`**、**`<%= packageScope %>/utils`** 的配合见 **`.cursor/rules/umi-app.mdc`**。

package/generators/h5-react/templates/.cursor/rules/git-hooks.mdc

@@ -0,0 +1,40 @@
+---
+description: Husky、lint-staged、commitlint 与提交前检查流程（<%= ProjectName %>）
+alwaysApply: true
+---
+
+# Git 钩子与提交规范
+
+## Husky
+
+- `pnpm install` 后由根 `prepare` 脚本安装 Husky（`"prepare": "husky"`）
+- **pre-commit**：执行 `pnpm run lint-staged`，随后 **`git add .`**（把格式化结果重新暂存）
+- **commit-msg**：调 `pnpm exec commitlint --edit "$1"` 校验提交说明
+
+## lint-staged
+
+- **统一在仓库根 `.lintstagedrc.js` 维护**（CommonJS）；当前规则：
+
+  ```js
+  module.exports = {
+    'apps/*/**/*.{js,jsx,ts,tsx}': 'eslint --flag v10_config_lookup_from_file --fix',
+    'apps/*/**/*.{css,less}': 'stylelint --fix',
+    'packages/!(eslint)/**/*.{js,jsx,ts,tsx}': 'eslint --flag v10_config_lookup_from_file --fix',
+  };
+  ```
+
+- 根 `package.json` 的 `lint-staged` 脚本直接使用 **`lint-staged`**（**不再**用 `turbo run lint-staged --concurrency=1`）
+- **`--flag v10_config_lookup_from_file`**：让 ESLint 9 在传入文件路径时按**文件所在目录**解析 flat config，从而命中各包根目录下的 `eslint.config.ts`，避免误用根目录配置
+- `apps/*/**/*.{css,less}` 走 stylelint；**packages/* 不跑 stylelint**（共享包不写样式）
+- **`packages/!(eslint)`**：排除 `packages/eslint`（共享 ESLint 配置自身改动不需要再跑一遍）
+- **已废弃**：每个 `packages/<x>/.lintstagedrc`、各子应用 `.lintstagedrc`、根 `lint-staged` 调 turbo 的旧写法；新增包**不需要**再放 `.lintstagedrc`，集中在根的 glob 即可命中
+
+## commitlint
+
+- 配置：`.commitlintrc.js`，继承 **`@commitlint/config-conventional`**
+- 提交信息需符合 **Conventional Commits**（如 `feat:`、`fix:`、`chore:`）
+
+```text
+✅ feat(apps/<子应用目录>): add login form
+❌ update stuff
+```

package/generators/h5-react/templates/.cursor/rules/internal-packages.mdc

@@ -0,0 +1,46 @@
+---
+description: packages/* 内部包的模块格式、exports 与命名空间（<%= packageScope %>）
+globs: "packages/**/*.{ts,tsx,mjs,js,json}"
+alwaysApply: false
+---
+
+# `packages/*` 内部包
+
+## 通用约定
+
+- 包名一律使用 **`<%= packageScope %>/*`**；`package.json` 多数声明 **`"type": "module"`**，入口与导出按 ESM 约定
+- 对外 API 通过 **`exports`** 暴露子路径（避免应用深链 `../../`）；应用只 `import` 已导出条目
+- 子应用引用本仓库包统一写 **`workspace:^`**；共享包变更后，依赖它的应用需重新 dev / build 才能看到效果
+- 多数包还导出 **`./*`** 通配（如 `<%= packageScope %>/utils/tailwind`、`<%= packageScope %>/js-bridge/closeH5Page`），可按子路径直接 `import`，无需在 `index.ts` 里 re-export
+
+```json
+// 示例（<%= packageScope %>/utils）：直接按子路径导出
+"exports": {
+  ".": "./src/index.ts",
+  "./*": "./src/*.ts"
+}
+```
+
+## 工具与基线
+
+- **`<%= packageScope %>/eslint`**：ESLint 9 flat config 共享配置；**`exports`** 中 **`.`** → `eslint.config.base.ts`（推荐 + TS + Prettier，并 ignore `mock/**`、`tailwind.config.*`、`postcss.config.*`、`src/.umi*` 等）；**`./react`** 在 base 上叠加 React / Hooks / Refresh。子应用 / 子包的 `eslint.config.ts` 都 `import` 此处的导出，并补 **`parserOptions.tsconfigRootDir: import.meta.dirname`**
+- **`<%= packageScope %>/typescript`**：导出 **`.`** → `tsconfig.base.json`、**`./react`** → `tsconfig.react.json`；多数子包 `tsconfig.json` 直接 `extends` 此包，Umi 子应用与 **`packages/components`** 等含 Umi 类型的包则 `extends "./src/.umi/tsconfig.json"`
+- **`<%= packageScope %>/utils`**：通用工具（`tailwind` 的 **`cn` / `cva` / `VariantProps`**、`env` 平台与环境判断、`url`、`number`、`date`、`md5`，以及 **`mock`**：开发 Mock 复用的 **`baseUrl`** / **`tryProxy`** 远程透传 / **`validateBody`** zod 入参校验工具）；按 **`./<文件名>`** 子路径引用即可
+
+## 运行时基础
+
+- **`<%= packageScope %>/domain`**：导出 **`apiBaseUrl`**、**`cdnBaseUrl`**、**`langBaseUrl`** 等；优先读 **`window.__MICO_CONFIG__`**，否则回退 **`UMI_APP_API_BASE_URL`** / **`UMI_APP_CDN_BASE_URL`** / **`UMI_APP_LANG_BASE_URL`**（来自仓库根 `.env.<env>`）。无业务 UI，被 **`request`**、**`common-intl`**、**`js-bridge`** 等消费
+- **`<%= packageScope %>/js-bridge`**：原生 H5 通信能力。**`canUseJSBridge`**（`isAndroid` 用 `window.Omigo.post`、`isIOS` 用 `window.MCAIJsBridge.post`）+ **`callJSBridgeMethods<D, T>(method, payload, options?)`**（含 postID 路由、`AndroidJSBridgeCallback` 全局桥、Loading 防抖）。子路径示例 **`./getUserInfo`**、**`./closeH5Page`**；类型与全局声明在 **`type.d.ts`**。开发期 `getUserInfo` 在 `isDebug` 下回退 fetch 远程登录接口，便于本地联调；线上**不要**开放此回退分支
+- **`<%= packageScope %>/request`**：基于 Umi **`request`** 的统一封装。**`src/index.ts`** 导出 **`request`**、**`withTemporaryInterceptors`**、**`registerRequestInterceptor` / `registerResponseInterceptor`** 与 **`UnifiedRequestOptions`** 等类型；**`src/url-resolver.ts`** 使用 `domain` 的 `apiBaseUrl` 拼接相对路径；模块加载时已注入默认拦截器（默认请求头 + 业务 `code` 校验，可在 **`buildDefaultHeaders`** 内放开 `Authorization`）。`isShowLoading` **默认 `true`**，与请求池配合做并发显隐。详见 **`.cursor/rules/workspace-request.mdc`**
+- **`<%= packageScope %>/common-intl`**：**`@common-web/common-intl`** 的项目级封装（re-export 上游全部 API + 预配置的 **`init()`** 函数）；依赖 **`@common-web/common-intl`**、**`domain`**、**`request`**、**`js-bridge`**（`init()` 内部用 **`getUserInfo()`** 取 `lang`）。无构建步骤，`exports` 直接指向源码 TS。详见 **`.cursor/rules/common-intl.mdc`**
+
+## UI 与业务复用
+
+- **`<%= packageScope %>/components`**：项目级 UI 组件库；当前内置 **`Layout`**（普通 / 沉浸式两种 + 头部安全区）、**`ImmersiveHeader`**（默认头：返回按钮通过 `closeH5Page` 走 JSBridge）、**`LayoutFooter`**（fixed/非 fixed + `pb-safe-or-4`）。依赖 **`<%= packageScope %>/js-bridge`** 与 **`<%= packageScope %>/utils`**；`peerDependencies` 上 React / React-DOM 写 `catalog:`。包目录有 `tailwind.config.js` 扫描入口由各子应用追加（见 **`.cursor/rules/tailwind-umi.mdc`**）。**资源**通过 **`./assets/*`** 子路径导出，例如 `import backIcon from '<%= packageScope %>/components/assets/image/back.png'`
+- **`<%= packageScope %>/constant`**：业务常量集中地（如示例 **`MEMBER_CONSTANT`**）；`exports` 同时支持 **`.`** 与 **`./<文件>`**，建议按业务域拆分文件（如 `member.ts`），不要把所有枚举塞进 `index.ts`
+- **`<%= packageScope %>/deeplink`**：客户端跳转链接的语义层；当前提供 **`togoHome`** 等占位实现，业务侧需按客户端 deeplink 协议改写（默认值含 `<%= projectName %>://router/home` 占位）
+- **`<%= packageScope %>/umi-config`**：子应用 Umi 配置工厂集合（`createBaseConfig` / `createDevConfig` / `createProConfig` / `createDevelopmentConfig` / `createTestingConfig` / `createProductionConfig`）+ 内部 **`plugins/apply-sentry-plugin.ts`**。**所有子应用 `config/*.ts` 均委托到本包**，**不要**在子应用里再抄基础配置或 Sentry 上传逻辑。完整设计见 **`.cursor/rules/umi-config.mdc`**
+
+## 与 Mock / 服务类型的配合
+
+子应用 **`mock/`** 不在 **`packages/`**，但与 **`request`**、**`domain`** 的 URL 规则强相关；公共逻辑（`baseUrl`、`tryProxy`）来自 **`<%= packageScope %>/utils/mock`**，约定见 **`.cursor/rules/umi-mock.mdc`**。请求/响应类型就近定义在 **`apps/<子应用>/src/services/`** 下对应模块中。