generator-mico-cli 0.2.11 → 0.2.13

package/README.md

@@ -67,6 +67,39 @@ cd <monorepo-root>
 mico create subapp-react
 ```
 
+## 本地调试
+
+克隆项目后，执行以下步骤进行本地开发和调试：
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 将本地包链接到全局（需要先安装 yo）
+npm install -g yo
+npm link
+
+# 3. 验证链接成功
+mico --version
+```
+
+链接成功后，`mico` 命令会使用本地代码，可以直接修改代码并测试：
+
+```bash
+# 测试 micro-react 生成器
+mkdir test-project && cd test-project
+mico create micro-react
+
+# 测试 subapp-react 生成器（需在已有 monorepo 中执行）
+mico create subapp-react
+```
+
+调试完成后，可以取消全局链接：
+
+```bash
+npm unlink -g generator-mico-cli
+```
+
 ## 同步子应用模板
 
 将源项目的 `apps/homepage` 同步到生成器模板目录：

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

@@ -0,0 +1,76 @@
+#!/bin/bash
+
+# 计算当前构建分支的 BASE_REF，并为 Turbo 增量构建准备 TURBO_FILTER
+# 该脚本会被其他脚本 source 调用，不要在这里直接 exit 1
+
+set -e
+
+# 获取项目根目录（如果调用方已设置 PROJECT_ROOT，则使用；否则使用当前工作目录）
+PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
+
+# 获取当前构建的分支（去掉 origin/ 前缀，用于比较）
+# 优先使用环境变量 CURRENT_BRANCH（Jenkins 传入，格式可能是 origin/main、origin/feat/xxx）
+# 其次使用 BRANCH_OR_TAG，最后从 git 获取
+if [ -n "${CURRENT_BRANCH}" ]; then
+  CURRENT_BRANCH_NAME="${CURRENT_BRANCH#origin/}"  # 去掉 origin/ 前缀
+elif [ -n "${BRANCH_OR_TAG}" ]; then
+  CURRENT_BRANCH_NAME="${BRANCH_OR_TAG#origin/}"  # 去掉 origin/ 前缀
+else
+  CURRENT_BRANCH_NAME="$(git rev-parse --abbrev-ref HEAD)"
+fi
+
+echo "[before_build] Current branch (without origin/): ${CURRENT_BRANCH_NAME}"
+
+# 比较当前分支和上次成功构建的分支是否一致
+# LAST_SUCCESS_BRANCH 由 Jenkins 在构建时设置（从上次构建的结果中获取，格式可能是 origin/main、origin/feat/xxx）
+if [ -n "${LAST_SUCCESS_BRANCH}" ]; then
+  # 去掉 LAST_SUCCESS_BRANCH 的 origin/ 前缀，用于比较
+  LAST_SUCCESS_BRANCH_NAME="${LAST_SUCCESS_BRANCH#origin/}"
+  echo "[before_build] Last success branch (without origin/): ${LAST_SUCCESS_BRANCH_NAME}"
+  
+  if [ "${CURRENT_BRANCH_NAME}" != "${LAST_SUCCESS_BRANCH_NAME}" ]; then
+    # 分支不一致，需要全量构建
+    echo "[before_build] Branch changed: ${LAST_SUCCESS_BRANCH_NAME} -> ${CURRENT_BRANCH_NAME}, will perform full build (no filter)"
+    unset TURBO_FILTER
+  else
+    # 分支一致，尝试使用 PREVIOUS_COMMIT 进行增量构建
+    echo "[before_build] Branch unchanged: ${CURRENT_BRANCH_NAME}, checking PREVIOUS_COMMIT for incremental build"
+    if [ -n "${PREVIOUS_COMMIT}" ]; then
+      # 验证 commit 是否存在且有效
+      if git rev-parse --verify "${PREVIOUS_COMMIT}" >/dev/null 2>&1; then
+        # 关键检查：验证 PREVIOUS_COMMIT 是否是当前 HEAD 的祖先
+        # 这可以避免以下问题：
+        # 1. Rebase/Force push：PREVIOUS_COMMIT 不再是当前分支的祖先
+        # 2. Tag 被其他分支更新：PREVIOUS_COMMIT 不是当前分支的祖先
+        CURRENT_HEAD="$(git rev-parse HEAD)"
+        if git merge-base --is-ancestor "${PREVIOUS_COMMIT}" "${CURRENT_HEAD}" 2>/dev/null; then
+          # PREVIOUS_COMMIT 是当前 HEAD 的祖先，可以安全使用
+          BASE_REF="${PREVIOUS_COMMIT}"
+          echo "[before_build] Use PREVIOUS_COMMIT as BASE_REF: ${BASE_REF} (ancestor check passed)"
+          # 为 turbo --filter 准备语法形如 ...[<BASE_REF>]
+          TURBO_FILTER="...[${BASE_REF}]"
+          export TURBO_FILTER
+          echo "[before_build] TURBO_FILTER=${TURBO_FILTER} (incremental build)"
+        else
+          # PREVIOUS_COMMIT 不是当前 HEAD 的祖先，降级为全量构建
+          echo "[before_build] Warning: PREVIOUS_COMMIT=${PREVIOUS_COMMIT} is not an ancestor of HEAD=${CURRENT_HEAD}"
+          echo "[before_build] Possible reasons: rebase/force-push, tag updated by another branch, or shallow clone issue"
+          echo "[before_build] Falling back to full build (no filter)"
+          unset TURBO_FILTER
+        fi
+      else
+        echo "[before_build] Warning: PREVIOUS_COMMIT=${PREVIOUS_COMMIT} is not a valid commit, will perform full build"
+        unset TURBO_FILTER
+      fi
+    else
+      # PREVIOUS_COMMIT 未设置，进行全量构建
+      echo "[before_build] PREVIOUS_COMMIT not set, will perform full build (no filter)"
+      unset TURBO_FILTER
+    fi
+  fi
+else
+  # LAST_SUCCESS_BRANCH 未设置，说明是第一次构建或 Jenkins 未配置该环境变量
+  echo "[before_build] LAST_SUCCESS_BRANCH not set, will perform full build (no filter)"
+  # 不设置 TURBO_FILTER，这样 package.json 中的 ${TURBO_FILTER:+--filter=${TURBO_FILTER}} 不会生效
+  unset TURBO_FILTER
+fi

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

@@ -20,11 +20,24 @@ echo "项目版本: $VERSION"
 # 切换到项目根目录，确保后续命令在根目录下运行
 cd "$PROJECT_ROOT"
 
+# 导出 PROJECT_ROOT 供 before_build.sh 使用
+export PROJECT_ROOT
+
+# 在执行构建前，计算 BASE_REF / TURBO_FILTER 等增量构建信息
+if [ -f "$PROJECT_ROOT/CICD/before_build.sh" ]; then
+  # shellcheck disable=SC1090
+  source "$PROJECT_ROOT/CICD/before_build.sh"
+fi
+
 # 设置子应用的 CDN 公共路径（开发环境）
 export CDN_PUBLIC_PATH="https://cdn-portal-dev.micoplatform.com/<%= projectName %>/${VERSION}/"
 echo "CDN_PUBLIC_PATH: $CDN_PUBLIC_PATH"
 
 pnpm run build:development
 
-echo "VERSION=$VERSION" > .env_x_<%= projectName %>
+# 只有在 CI 环境时才写入版本号文件（覆盖写入）
+if [ "${CI}" = "true" ]; then
+  echo "VERSION=$VERSION" > .env_x_portal-web
+fi
+
 

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

@@ -20,11 +20,23 @@ echo "项目版本: $VERSION"
 # 切换到项目根目录，确保后续命令在根目录下运行
 cd "$PROJECT_ROOT"
 
+# 导出 PROJECT_ROOT 供 before_build.sh 使用
+export PROJECT_ROOT
+
+# 在执行构建前，计算 BASE_REF / TURBO_FILTER 等增量构建信息（用于增量构建）
+if [ -f "$PROJECT_ROOT/CICD/before_build.sh" ]; then
+  # shellcheck disable=SC1090
+  source "$PROJECT_ROOT/CICD/before_build.sh"
+fi
+
 # 设置子应用的 CDN 公共路径（生产环境）
 export CDN_PUBLIC_PATH="https://cdn-portal.micoplatform.com/<%= projectName %>/${VERSION}/"
 echo "CDN_PUBLIC_PATH: $CDN_PUBLIC_PATH"
 
 pnpm run build:production
 
-echo "VERSION=$VERSION" > .env_x_<%= projectName %>
+# 只有在 CI 环境时才写入版本号文件（覆盖写入）
+if [ "${CI}" = "true" ]; then
+  echo "VERSION=$VERSION" > .env_x_portal-web
+fi
 

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

@@ -20,11 +20,24 @@ echo "项目版本: $VERSION"
 # 切换到项目根目录，确保后续命令在根目录下运行
 cd "$PROJECT_ROOT"
 
+# 导出 PROJECT_ROOT 供 before_build.sh 使用
+export PROJECT_ROOT
+
+# 在执行构建前，计算 BASE_REF / TURBO_FILTER 等增量构建信息
+if [ -f "$PROJECT_ROOT/CICD/before_build.sh" ]; then
+  # shellcheck disable=SC1090
+  source "$PROJECT_ROOT/CICD/before_build.sh"
+fi
+
+
 # 设置子应用的 CDN 公共路径（测试环境）
 export CDN_PUBLIC_PATH="https://cdn-portal-test.micoplatform.com/<%= projectName %>/${VERSION}/"
 echo "CDN_PUBLIC_PATH: $CDN_PUBLIC_PATH"
 
 pnpm run build:testing
 
-echo "VERSION=$VERSION" > .env_x_<%= projectName %>
+# 只有在 CI 环境时才写入版本号文件（覆盖写入）
+if [ "${CI}" = "true" ]; then
+  echo "VERSION=$VERSION" > .env_x_portal-web
+fi
 

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

@@ -28,14 +28,14 @@ const config: ReturnType<typeof defineConfig> = {
   proxy: {
     '/api': {
       // 要代理的地址
-      target: 'https://dashboard-api-test.micoplatform.comn',
+      target: 'https://dashboard-api-test.micoplatform.com',
       // 配置了这个可以从 http 代理到 https
       // 依赖 origin 的功能可能需要这个，比如 cookie
       changeOrigin: true,
     },
     '/proxy/audit_svr': {
       // 要代理的地址
-      target: 'https://dashboard-api-test.micoplatform.comn',
+      target: 'https://dashboard-api-test.micoplatform.com',
       // 配置了这个可以从 http 代理到 https
       // 依赖 origin 的功能可能需要这个，比如 cookie
       changeOrigin: true,

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

@@ -20,4 +20,9 @@ export default [
     component: './403',
     name: '无权限',
   },
+  {
+    path: '/*',
+    component: './404',
+    name: '页面不存在',
+  },
 ];

package/generators/micro-react/templates/apps/layout/docs/feature-404/351/241/265/351/235/242.md

@@ -0,0 +1,103 @@
+# 404 页面
+
+> 创建时间：2025-01-27
+
+## 功能概述
+
+当用户访问不存在的路由时，展示 404 页面并提供导航选项，支持返回上页或跳转至第一个有权限访问的路由。
+
+## 技术方案
+
+### 技术栈
+
+- 框架：React 18 + @umijs/max
+- UI 组件：Arco Design `Result`、`Button`、`Space`
+- 路由：React Router 6 通配符路由
+
+### 核心实现
+
+1. 使用 Umi 路由通配符 `/*` 捕获所有未匹配的路径
+2. 复用 403 页面的布局风格，保持 UI 一致性
+3. 动态计算第一个可访问路由：从菜单数据中提取路由，根据用户权限过滤后返回首个有效路径
+
+## 文件清单
+
+### 新增文件
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/pages/404/index.tsx` | 404 页面组件 |
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+| --- | --- |
+| `config/routes.ts` | 添加通配符路由 `/*` |
+
+## API / 组件接口
+
+### NotFoundPage
+
+无外部 Props，使用 Umi 全局状态获取用户信息。
+
+### getFirstAvailablePath
+
+```typescript
+/**
+ * 获取第一个可访问的路由路径
+ */
+const getFirstAvailablePath = (filterOptions: MenuFilterOptions): string;
+```
+
+**逻辑说明**：
+
+1. 从 `window.__MICO_MENUS__` 获取菜单数据
+2. 根据 `disableAuth` 配置决定是否过滤权限
+3. 调用 `filterMenuItems` 过滤无权限菜单
+4. 调用 `extractRoutes` 提取路由列表
+5. 返回第一个路由的 `path`，若无则返回 `/`
+
+## 路由配置
+
+```typescript
+// config/routes.ts
+{
+  path: '/*',
+  component: './404',
+  name: '页面不存在',
+}
+```
+
+通配符路由放在路由配置末尾，匹配所有未被其他路由匹配的路径。
+
+## 使用示例
+
+用户访问 `/non-existent-page` 时：
+
+1. 路由系统无法匹配到具体路由
+2. 通配符路由 `/*` 生效
+3. 渲染 404 页面，显示两个按钮：
+   - **返回上页**：调用 `history.back()`
+   - **前往首页**：跳转至第一个有权限的路由
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| UI 组件 | Arco Design Result | 与 403 页面保持一致，复用现有组件库 |
+| 首页跳转逻辑 | 动态获取第一个可访问路由 | 适应动态菜单配置，不硬编码路径 |
+| 权限过滤 | 复用 filterMenuItems | 与菜单权限逻辑保持一致 |
+
+## 相关文件
+
+| 文件 | 说明 |
+| --- | --- |
+| `src/pages/403/index.tsx` | 403 页面，UI 风格参考 |
+| `src/common/menu/parser.ts` | 菜单解析工具函数 |
+| `src/constants/index.ts` | `isAuthDisabled` 权限控制函数 |
+
+## 注意事项
+
+- 通配符路由必须放在路由配置最后，否则会提前匹配
+- 动态路由（从 `window.__MICO_MENUS__` 注入）的 404 场景由 `layouts/index.tsx` 处理
+- 此 404 页面主要处理静态路由未匹配的情况

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,7 +1,6 @@
 # 菜单权限控制
 
-> 创建时间：2026-01-24
-> 更新时间：2026-01-26
+> 创建时间：2026-01-24 更新时间：2026-01-27
 
 ## 功能概述
 
@@ -13,10 +12,10 @@
 
 ### 认证 vs 授权
 
-| 概念 | 英文 | 作用 | 配置项 |
-| --- | --- | --- | --- |
-| 认证 | Authentication | 确认用户身份（是否登录） | `noAuthRouteList` |
-| 授权 | Authorization | 确认用户权限（能否访问） | `noPermissionRouteList` |
+| 概念 | 英文           | 作用                     | 配置项                  |
+| ---- | -------------- | ------------------------ | ----------------------- |
+| 认证 | Authentication | 确认用户身份（是否登录） | `noAuthRouteList`       |
+| 授权 | Authorization  | 确认用户权限（能否访问） | `noPermissionRouteList` |
 
 ### 四种路由场景
 
@@ -103,8 +102,8 @@
 
 ### 新增文件
 
-| 文件路径 | 说明 |
-| --- | --- |
+| 文件路径                  | 说明               |
+| ------------------------- | ------------------ |
 | `src/pages/403/index.tsx` | 403 无权限页面组件 |
 
 ### 修改文件
@@ -204,13 +203,13 @@ window.__MICO_CONFIG__ = {
   noAuthRouteList: [
     '/',
     '/subapp',
-    '/public/*',  // 前缀匹配
+    '/public/*', // 前缀匹配
   ],
   // 免权限校验路由（跳过菜单权限检查）
   noPermissionRouteList: [
     '/',
     '/subapp',
-    '/settings',  // 登录后的公共页面
+    '/settings', // 登录后的公共页面
   ],
   disableAuth: false,
 };
@@ -230,10 +229,7 @@ export const NO_AUTH_ROUTE_LIST: string[] = [
 ];
 
 // 静态免权限校验路由（始终生效）
-export const NO_PERMISSION_ROUTE_LIST: string[] = [
-  '/403',
-  '/404',
-];
+export const NO_PERMISSION_ROUTE_LIST: string[] = ['/403', '/404'];
 ```
 
 ### 菜单过滤结果
@@ -291,6 +287,56 @@ if (!isAuthReady) {
 | 超级用户 | 跳过所有检查 | 管理员需要完整访问权限 |
 | 免权限路由的菜单 | 显示全部 | 用户访问公开页面时应能看到所有导航选项 |
 | 免权限路由的子应用 | 直接加载 | 不等待 currentUser，避免加载卡住 |
+| 静态路由不受权限控制 | 默认允许访问 | 见下方"静态路由与动态路由"说明 |
+
+## 静态路由与动态路由
+
+### 定义
+
+| 类型 | 来源 | 示例 |
+| --- | --- | --- |
+| **静态路由** | 代码中定义 (`config/routes.ts`) | `/`, `/403`, `/404`, `/user/login` |
+| **动态路由** | 后端菜单配置 (`window.__MICO_MENUS__`) | `/queue-management`, `/quality-check` |
+
+### 权限控制范围
+
+**当前设计：权限控制仅作用于动态路由，静态路由默认允许访问。**
+
+```
+权限判断逻辑（isForbidden）：
+1. 检查 isAuthDisabled() → 关闭则全部允许
+2. 检查 isNoPermissionRoute() → 在免权限列表中则允许
+3. 检查 currentRoute（有权限路由） → 找到则允许
+4. 检查 routeInAll（所有动态路由） → 存在则返回 403
+5. 都不匹配 → 交给 Umi 处理（静态路由走这里）
+```
+
+### 设计理由
+
+1. **职责分离**：静态路由是框架层面的基础设施（登录、错误页），动态路由才是业务功能
+2. **简化配置**：不需要额外配置哪些静态路由需要权限，减少出错概率
+3. **向后兼容**：现有部署无需任何改动
+4. **复杂度控制**：避免引入更多配置项增加理解成本
+
+### 影响
+
+当用户 `is_superuser=false` 且 `side_menus=[]` 时：
+
+| 路由 | 结果 | 原因 |
+| --- | --- | --- |
+| `/` (Home) | ✅ 正常显示 | 静态路由，不受权限控制 |
+| `/403` | ✅ 正常显示 | 在 `noPermissionRouteList` 中 |
+| `/404` | ✅ 正常显示 | 在 `noPermissionRouteList` 中 |
+| `/user/login` | ✅ 正常显示 | 静态路由 + 在 `noAuthRouteList` 中 |
+| `/queue-management` | ❌ 显示 403 | 动态路由，无权限 |
+
+### 如需控制静态路由
+
+如果业务上需要让某个静态路由（如 `/`）也受权限控制，有以下方案：
+
+1. **方案 A**：将该路由从静态路由改为动态路由（通过菜单配置）
+2. **方案 B**：在对应页面组件内部自行判断权限并重定向
+3. **方案 C**：扩展 `isForbidden` 逻辑（需额外开发，当前未实现）
 
 ## 注意事项
 

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

@@ -298,7 +298,7 @@ if (typeof window !== 'undefined') {
         return;
       }
 
-      log('用户交互开始:', event.type);
+      // log('用户交互开始:', event.type);
       isInUserInteraction = true;
       // 记录交互开始时间，用于判断意图是否在当前交互期间设置的
       currentInteractionStartTime = Date.now();
@@ -308,7 +308,7 @@ if (typeof window !== 'undefined') {
       setTimeout(() => {
         isInUserInteraction = false;
         interactionEndTime = Date.now();
-        log('用户交互结束');
+        // log('用户交互结束');
       }, 0);
     }
   };

package/generators/micro-react/templates/apps/layout/src/pages/404/index.tsx

@@ -0,0 +1,82 @@
+import {
+  extractRoutes,
+  filterMenuItems,
+  getWindowMenus,
+  type MenuFilterOptions,
+} from '@/common/menu';
+import { isAuthDisabled } from '@/constants';
+import { Button, Result, Space } from '@arco-design/web-react';
+import { history, useModel } from '@umijs/max';
+import React, { useMemo } from 'react';
+
+/**
+ * 获取第一个可访问的路由路径
+ */
+const getFirstAvailablePath = (filterOptions: MenuFilterOptions): string => {
+  const menus = getWindowMenus();
+
+  // 根据权限过滤菜单
+  const filteredMenus = isAuthDisabled()
+    ? menus
+    : filterMenuItems(menus, filterOptions);
+
+  // 提取路由
+  const routes = extractRoutes(filteredMenus);
+
+  // 返回第一个有效路由，默认返回首页
+  return routes[0]?.path || '/';
+};
+
+const NotFoundPage: React.FC = () => {
+  const { initialState } = useModel('@@initialState');
+  const currentUser = initialState?.currentUser;
+
+  const filterOptions = useMemo<MenuFilterOptions>(
+    () => ({
+      isSuperuser: currentUser?.is_superuser,
+      sideMenus: (currentUser?.side_menus || []) as string[],
+    }),
+    [currentUser?.is_superuser, currentUser?.side_menus],
+  );
+
+  const firstAvailablePath = useMemo(
+    () => getFirstAvailablePath(filterOptions),
+    [filterOptions],
+  );
+
+  const handleGoBack = () => {
+    history.back();
+  };
+
+  const handleGoFirst = () => {
+    history.push(firstAvailablePath);
+  };
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'center',
+        height: '100%',
+        minHeight: 400,
+      }}
+    >
+      <Result
+        status="404"
+        title="页面不存在"
+        subTitle="抱歉，您访问的页面不存在"
+        extra={
+          <Space>
+            <Button onClick={handleGoBack}>返回上页</Button>
+            <Button type="primary" onClick={handleGoFirst}>
+              前往首页
+            </Button>
+          </Space>
+        }
+      />
+    </div>
+  );
+};
+
+export default NotFoundPage;

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

@@ -12,9 +12,9 @@
   "scripts": {
     "dev": "node scripts/dev.js",
     "build": "dotenv -e .env -e .env.local -e .env.production -e .env.production.local -- turbo run build && node scripts/collect-dist.js",
-    "build:development": "dotenv -e .env -e .env.local -e .env.development -e .env.development.local -- turbo run build:development && node scripts/collect-dist.js",
-    "build:testing": "dotenv -e .env -e .env.local -e .env.testing -e .env.testing.local -- turbo run build:testing && node scripts/collect-dist.js",
-    "build:production": "dotenv -e .env -e .env.local -e .env.production -e .env.production.local -- turbo run build:production && node scripts/collect-dist.js",
+    "build:development": "dotenv -e .env -e .env.local -e .env.development -e .env.development.local -- turbo run build:development ${TURBO_FILTER:+--filter=${TURBO_FILTER}} && node scripts/collect-dist.js",
+    "build:testing": "dotenv -e .env -e .env.local -e .env.testing -e .env.testing.local -- turbo run build:testing ${TURBO_FILTER:+--filter=${TURBO_FILTER}} && node scripts/collect-dist.js",
+    "build:production": "dotenv -e .env -e .env.local -e .env.production -e .env.production.local -- turbo run build:production ${TURBO_FILTER:+--filter=${TURBO_FILTER}} && node scripts/collect-dist.js",
     "build:local": "dotenv -e .env -e .env.local -- turbo run build:local && node scripts/collect-dist.js",
     "lint": "eslint . --ext .js,.jsx,.ts,.tsx && turbo run lint",
     "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix && turbo run lint:fix",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generator-mico-cli",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Yeoman generator for Mico CLI projects",
   "keywords": [
     "yeoman-generator",