generator-mico-cli 0.1.29 → 0.2.2

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

@@ -23,6 +23,7 @@ const config: ReturnType<typeof defineConfig> = {
         window.__MICO_CONFIG__ = {
           appName: 'Mico Center',
           apiBaseUrl: '',
+          defaultPath: '',
         };
       `,
     },
@@ -47,7 +48,7 @@ const config: ReturnType<typeof defineConfig> = {
   define: {
     'process.env.NODE_ENV': 'development',
     'process.env.APP_ID': 'mibot_dev',
-    'process.env.API_BASE_URL': 'https://dashboard-api-test.micoplatform.com',
+    'process.env.API_BASE_URL': '',
     'process.env.PROXY_SUFFIX': '/',
     'process.env.LOGIN_ENDPOINT':
       '',

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

@@ -15,4 +15,9 @@ export default [
     component: './Home',
     name: '首页',
   },
+  {
+    path: '/403',
+    component: './403',
+    name: '无权限',
+  },
 ];

package/generators/micro-react/templates/apps/layout/docs/arch-/350/257/267/346/261/202/346/250/241/345/235/227.md

@@ -4,7 +4,7 @@
 
 ## 功能概述
 
-HTTP 请求层模块化架构，将原 599 行单文件拆分为 6 个职责单一的模块，遵循 SRP 原则。
+HTTP 请求层模块化架构，将原 599 行单文件拆分为 7 个文件（1 个入口 + 6 个功能模块），遵循 SRP 原则。
 
 ## 模块结构
 

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

@@ -0,0 +1,175 @@
+# 菜单权限控制
+
+> 创建时间：2026-01-24
+
+## 功能概述
+
+基于用户信息中的 `side_menus` 字段实现菜单和路由的白名单权限控制。非超级用户只能看到和访问 `side_menus` 中配置的菜单项，访问无权限路由时显示 403 页面。
+
+## 技术方案
+
+### 技术栈
+
+- 框架：React 18 + @umijs/max
+- UI 组件：Arco Design (Result 组件)
+- 状态管理：Umi initialState
+
+### 核心实现
+
+1. 用户信息接口返回 `side_menus` 字段（白名单）
+2. `filterMenuItems` 根据白名单过滤菜单项
+3. Layout 组件对比"所有路由"和"有权限路由"判断 403
+4. 无权限时在 Layout 内直接渲染 403 组件（无跳转）
+
+### 权限判断逻辑
+
+```
+用户访问 /some-path
+    ↓
+是否是超级用户？
+    ├── 是 → 允许访问所有菜单
+    └── 否 → 检查 side_menus 白名单
+              ├── 精确匹配：menuPath === side_menus[i]
+              ├── 前缀匹配：side_menus[i].startsWith(menuPath + '.')
+              └── 都不匹配 → 禁止访问，显示 403
+```
+
+## 文件清单
+
+### 新增文件
+
+| 文件路径 | 说明 |
+|----------|------|
+| `src/pages/403/index.tsx` | 403 无权限页面组件 |
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+|----------|----------|
+| `src/common/menu/parser.ts` | 新增 `filterMenuItems`、`isMenuAllowed` 等权限过滤函数 |
+| `src/layouts/index.tsx` | 新增 `isForbidden` 判断和 403 渲染逻辑 |
+| `src/layouts/components/menu/index.tsx` | 集成菜单过滤 |
+| `config/routes.ts` | 新增 `/403` 路由 |
+
+## API / 组件接口
+
+### MenuFilterOptions
+
+```typescript
+interface MenuFilterOptions {
+  /** 是否是超级用户 */
+  isSuperuser?: boolean | number;
+  /** 允许访问的菜单路径列表（白名单） */
+  sideMenus?: string[];
+}
+```
+
+### filterMenuItems
+
+```typescript
+/**
+ * 根据权限过滤菜单项（白名单逻辑）
+ */
+function filterMenuItems(
+  items: MenuItem[],
+  options?: MenuFilterOptions,
+  parentPath?: string,
+): MenuItem[];
+```
+
+**参数说明**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| items | MenuItem[] | 是 | 原始菜单数据 |
+| options | MenuFilterOptions | 否 | 过滤选项 |
+| parentPath | string | 否 | 父级路径（递归用） |
+
+### isRouteAllowed
+
+```typescript
+/**
+ * 检查路由是否允许访问
+ */
+function isRouteAllowed(
+  menuPath: string,
+  options?: MenuFilterOptions,
+): boolean;
+```
+
+### 用户信息相关字段
+
+```typescript
+interface IUserInfo {
+  is_superuser: boolean | number;
+  /** 允许访问的菜单路径列表 */
+  side_menus: string[];
+  /** 缺失的操作权限（用于按钮级别控制，非菜单） */
+  miss_permissions: string[];
+}
+```
+
+## 使用示例
+
+### 用户信息接口返回
+
+```json
+{
+  "is_superuser": false,
+  "side_menus": ["列队管理.配置队列", "工作台"],
+  "miss_permissions": ["列队管理.配置队列.查看"]
+}
+```
+
+### 菜单过滤结果
+
+```
+原始菜单：
+├── 工作台           ✅ 精确匹配 "工作台"
+├── 列队管理         ✅ 前缀匹配 "列队管理.配置队列"
+│   └── 配置队列     ✅ 精确匹配 "列队管理.配置队列"
+├── 质量管理         ❌ 不在白名单
+│   └── 抽样检查     ❌ 不在白名单
+└── 权限管理         ❌ 硬编码禁止（非超级用户）
+```
+
+### Layout 中的权限判断
+
+```tsx
+// layouts/index.tsx
+const isForbidden = useMemo(() => {
+  if (currentRoute) return false; // 在有权限的路由中找到了
+  const routeInAll = findRouteByPath(allRoutes, location.pathname);
+  return !!routeInAll; // 在所有路由中存在但无权限
+}, [currentRoute, allRoutes, location.pathname]);
+
+const renderContent = () => {
+  if (isForbidden) {
+    return <ForbiddenPage />;
+  }
+  // ... 正常渲染
+};
+```
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+|--------|------|------|
+| 权限模型 | 白名单 (`side_menus`) | 后端返回的 `side_menus` 是允许列表，比黑名单更安全 |
+| 403 处理 | 原地渲染组件 | 保持 URL 不变，用户体验更好，便于分享链接 |
+| 父级菜单显示 | 前缀匹配 | 子菜单有权限时，父级菜单需要作为容器显示 |
+| 超级用户 | 跳过所有检查 | 管理员需要完整访问权限 |
+| 权限管理菜单 | 硬编码禁止 | 非超级用户不应看到权限管理入口 |
+
+## 注意事项
+
+- `side_menus` 为空时，非超级用户没有任何菜单权限
+- `side_menus` 格式为菜单路径，如 `"列队管理.配置队列"`
+- `miss_permissions` 用于按钮级别权限控制，不影响菜单显示
+- 403 页面在 Layout 内渲染，不会触发路由跳转
+- 调试时可在控制台搜索 `isForbidden check` 查看权限判断日志
+
+## 相关文档
+
+- [微前端模式](./feature-微前端模式.md) - 路由和菜单解析
+- [用户信息接口](./feature-用户信息接口.md) - 用户数据结构

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

@@ -1,10 +1,8 @@
-import { history, type RequestConfig } from '@umijs/max';
-import { prefetchApps } from 'qiankun';
+import { history, Navigate, type RequestConfig } from '@umijs/max';
+import { addGlobalUncaughtErrorHandler, prefetchApps } from 'qiankun';
 import { errorConfig } from './requestErrorConfig';
 // 解决「React19 中无法使用 Message/Notification」的问题。 @see https://github.com/arco-design/arco-design/issues/2900#issuecomment-2796571653
 import * as arco from '@arco-design/web-react';
-import '@arco-design/web-react/dist/css/arco.css';
-import '@arco-design/web-react/es/_util/react-19-adapter';
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 
@@ -23,6 +21,57 @@ import MicroAppLoader from './components/MicroAppLoader';
 import { NO_AUTH_ROUTE_LIST } from './constants';
 import './global.less';
 
+// ==================== qiankun 全局错误处理 ====================
+// 捕获子应用运行时未捕获的异常，防止页面崩溃
+
+/**
+ * 注册 qiankun 全局未捕获错误处理器
+ * 处理以下场景：
+ * 1. 子应用 JS 运行时错误
+ * 2. 子应用生命周期钩子抛出的异常
+ * 3. 子应用资源加载失败
+ */
+if (typeof window !== 'undefined') {
+  addGlobalUncaughtErrorHandler((event: Event | string) => {
+    // 提取错误信息
+    const error =
+      event instanceof ErrorEvent
+        ? event.error
+        : event instanceof PromiseRejectionEvent
+        ? event.reason
+        : event;
+
+    const errorMessage =
+      error instanceof Error
+        ? error.message
+        : typeof error === 'string'
+        ? error
+        : 'Unknown micro-app error';
+
+    console.error('[qiankun] Global uncaught error:', {
+      error,
+      message: errorMessage,
+      type: event instanceof Event ? event.type : 'unknown',
+    });
+
+    // 检查是否是子应用加载失败（资源 404 等）
+    const isLoadError =
+      errorMessage.includes('Failed to fetch') ||
+      errorMessage.includes('Loading chunk') ||
+      errorMessage.includes('load') ||
+      errorMessage.includes('Script error');
+
+    if (isLoadError) {
+      console.error(
+        '[qiankun] Micro-app resource loading failed. Please check if the micro-app server is running.',
+      );
+    }
+
+    // 注意：这里不阻止错误冒泡，让控制台仍能显示原始错误
+    // 如果需要阻止，可以 return true
+  });
+}
+
 // ==================== 微应用预加载 ====================
 // 预加载所有微应用资源，避免快速切换时的竞态条件
 // 当资源已预加载时，loadMicroApp 的异步加载会快速完成，减少容器不存在的错误
@@ -124,21 +173,22 @@ export async function getInitialState(): Promise<{
     }
   };
 
-  // 如果不是登录页面，执行
   const { location } = history;
-  if (!NO_AUTH_ROUTE_LIST.includes(location.pathname)) {
-    // 先确保 SSO 会话完成（如果 URL 中有 ticket 参数，会换取 token 并存储用户信息）
+  const isNoAuthRoute = NO_AUTH_ROUTE_LIST.includes(location.pathname);
+
+  // 非免认证路由：走 SSO 流程
+  if (!isNoAuthRoute) {
     await ensureSsoSession();
+  }
 
-    // 有 token 时，获取用户信息
-    if (getStoredAuthToken()) {
-      const userInfo = await fetchUserInfoFn();
-      if (userInfo) {
-        return {
-          fetchUserInfo: fetchUserInfoFn,
-          currentUser: userInfo,
-        };
-      }
+  // 有 token 就获取用户信息（无论在哪个页面，支持登录后 refresh 场景）
+  if (getStoredAuthToken()) {
+    const userInfo = await fetchUserInfoFn();
+    if (userInfo) {
+      return {
+        fetchUserInfo: fetchUserInfoFn,
+        currentUser: userInfo,
+      };
     }
   }
 
@@ -147,6 +197,7 @@ export async function getInitialState(): Promise<{
   };
 }
 
+
 /**
  * @name request 配置，可以配置错误处理
  * 它基于 axios 和 ahooks 的 useRequest 提供了一套统一的网络请求和错误处理方案。
@@ -179,7 +230,11 @@ export function patchClientRoutes({ routes }: { routes: UmiRoute[] }) {
   const menus = getWindowMenus();
   const dynamicRoutes = extractRoutes(menus);
 
-  console.log('[app.tsx] patchClientRoutes:', { menus, dynamicRoutes, routes });
+  console.log('[app.tsx] patchClientRoutes:', {
+    menus,
+    dynamicRoutes,
+    routes,
+  });
 
   // 找到根路由（全局布局）
   const rootRoute = routes.find((r) => r.path === '/');
@@ -222,6 +277,23 @@ export function patchClientRoutes({ routes }: { routes: UmiRoute[] }) {
   });
 }
 
+
+/**
+ * @name 路由变化处理
+ * @description 处理 defaultPath 重定向：访问 "/" 时自动跳转到配置的默认路径
+ * @doc https://umijs.org/docs/api/runtime-config#onroutechange
+ */
+export function onRouteChange({
+  location,
+}: {
+  location: { pathname: string };
+}) {
+  const defaultPath = window.__MICO_CONFIG__?.defaultPath;
+  if (location.pathname === '/' && defaultPath && defaultPath !== '/') {
+    history.replace(defaultPath);
+  }
+}
+
 /**
  * @name qiankun 微前端子应用生命周期
  * @description 当应用作为 qiankun 子应用运行时，这些生命周期会被调用

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

@@ -9,6 +9,108 @@ export const getWindowMenus = (): MenuItem[] => {
   return Array.isArray(menus) ? menus : [];
 };
 
+export interface MenuFilterOptions {
+  /** 是否是超级用户 */
+  isSuperuser?: boolean | number;
+  /** 允许访问的菜单路径列表（白名单） */
+  sideMenus?: string[];
+}
+
+const isSuperuserUser = (value?: boolean | number): boolean => {
+  return value === true || value === 1;
+};
+
+export const buildMenuPath = (parentPath: string, name: string): string => {
+  return parentPath ? `${parentPath}.${name}` : name;
+};
+
+/**
+ * 检查菜单路径是否允许访问（白名单逻辑）
+ * - 超级用户可以访问所有菜单
+ * - 非超级用户不能访问"权限管理"
+ * - 菜单路径在 sideMenus 中，或是 sideMenus 中某项的前缀（父级菜单）
+ */
+const isMenuAllowed = (
+  menuPath: string,
+  options: MenuFilterOptions,
+): boolean => {
+  // 超级用户可以访问所有菜单
+  if (isSuperuserUser(options.isSuperuser)) return true;
+
+  // 非超级用户不能访问"权限管理"
+  if (menuPath === '权限管理') return false;
+
+  const sideMenus = options.sideMenus || [];
+
+  // 如果没有配置 sideMenus，非超级用户没有任何菜单权限
+  if (sideMenus.length === 0) return false;
+
+  // 检查是否在白名单中（精确匹配或前缀匹配）
+  return sideMenus.some((allowedPath) => {
+    // 精确匹配：菜单路径完全等于白名单中的路径
+    if (menuPath === allowedPath) return true;
+    // 前缀匹配：白名单路径以菜单路径开头（说明菜单是父级）
+    if (allowedPath.startsWith(menuPath + '.')) return true;
+    return false;
+  });
+};
+
+export const isRouteAllowed = (
+  menuPath: string,
+  options: MenuFilterOptions = {},
+): boolean => {
+  return isMenuAllowed(menuPath, options);
+};
+
+/**
+ * 根据权限过滤菜单项（白名单逻辑）
+ */
+export const filterMenuItems = (
+  items: MenuItem[],
+  options: MenuFilterOptions = {},
+  parentPath = '',
+): MenuItem[] => {
+  return items
+    .filter((item) => item.enabled)
+    .map((item) => {
+      const menuPath = buildMenuPath(parentPath, item.name);
+      const isAllowed = isMenuAllowed(menuPath, options);
+
+      // 递归处理子菜单
+      const nextChildren = item.children?.length
+        ? filterMenuItems(item.children, options, menuPath)
+        : [];
+
+      // 分组类型：如果没有子菜单，不显示
+      if (item.type === 'group' && nextChildren.length === 0) {
+        return null;
+      }
+
+      // 当前菜单不允许访问
+      if (!isAllowed) {
+        // 但如果有允许的子菜单，仍需显示当前菜单作为容器
+        if (nextChildren.length > 0) {
+          return { ...item, children: nextChildren };
+        }
+        return null;
+      }
+
+      // 当前菜单允许访问
+      const hasChildren = (item.children?.length || 0) > 0;
+      if (!hasChildren) {
+        return item;
+      }
+
+      // 有子菜单但过滤后为空，不显示
+      if (nextChildren.length === 0) {
+        return null;
+      }
+
+      return { ...item, children: nextChildren };
+    })
+    .filter((item): item is MenuItem => Boolean(item));
+};
+
 /**
  * 判断页面的加载类型
  * 有 htmlUrl 或 jsUrls 时使用 qiankun 微应用加载
@@ -40,10 +142,13 @@ const getEntry = (page: MenuItem['page']): string | undefined => {
 export const extractRoutes = (
   items: MenuItem[],
   routes: ParsedRoute[] = [],
+  parentPath = '',
 ): ParsedRoute[] => {
   for (const item of items) {
     if (!item.enabled) continue;
 
+    const menuPath = buildMenuPath(parentPath, item.name);
+
     if (item.type === 'page' && item.page && item.page.enabled) {
       const loadType = getLoadType(item.page);
       routes.push({
@@ -57,7 +162,7 @@ export const extractRoutes = (
     }
 
     if (item.children && item.children.length > 0) {
-      extractRoutes(item.children, routes);
+      extractRoutes(item.children, routes, menuPath);
     }
   }
 

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

@@ -155,6 +155,8 @@ declare global {
     __MICO_CONFIG__?: {
       appName?: string;
       apiBaseUrl?: string;
+      /** 默认重定向路径，访问 "/" 时自动跳转到此路径 */
+      defaultPath?: string;
       [key: string]: unknown;
     };
     __MICO_WORKSPACE__?: WorkspaceConfig | null;

package/generators/micro-react/templates/apps/layout/src/common/request/url-resolver.ts

@@ -2,7 +2,7 @@
  * URL 解析与拼接工具
  */
 
-import { resolveProxySuffix } from './config';
+import { resolveApiBaseUrl, resolveProxySuffix } from './config';
 import type { UnifiedRequestOptions } from './types';
 
 /**
@@ -33,8 +33,12 @@ const joinProxyAndPath = (proxySuffix: string, path: string): string => {
  * 配置优先级：
  * 1. rawUrl: true → 直接返回原始 url
  * 2. 绝对 URL → 直接返回
- * 3. skipProxy: true → 返回相对路径，不拼接代理前缀
- * 4. 其他情况 → 拼接 proxySuffix + url
+ * 3. skipProxy: true → 拼接 apiBaseUrl + url（跳过 proxySuffix）
+ * 4. 其他情况 → 拼接 apiBaseUrl + proxySuffix + url
+ *
+ * 示例（testing 环境，apiBaseUrl = https://dashboard-api-test.micoplatform.com）：
+ * - 默认: /api/user/info → https://dashboard-api-test.micoplatform.com/proxy/audit_svr/api/user/info
+ * - skipProxy: /api/user/info → https://dashboard-api-test.micoplatform.com/api/user/info
  */
 export const resolveRequestUrl = (
   url: string,
@@ -50,13 +54,24 @@ export const resolveRequestUrl = (
     return url;
   }
 
-  // skipProxy: true 时不拼接代理前缀
-  if (options?.skipProxy) {
-    return url;
+  // 拼接 apiBaseUrl + proxySuffix + url
+  const apiBaseUrl = resolveApiBaseUrl();
+  // skipProxy: true 时不拼接 proxySuffix
+  const proxySuffix = options?.skipProxy
+    ? ''
+    : resolveProxySuffix(options?.proxySuffix);
+
+  if (apiBaseUrl) {
+    // 有 apiBaseUrl 时，拼接完整的绝对路径
+    const pathPart = proxySuffix ? joinProxyAndPath(proxySuffix, url) : url;
+    const normalizedBase = apiBaseUrl.endsWith('/')
+      ? apiBaseUrl.slice(0, -1)
+      : apiBaseUrl;
+    const normalizedPath = pathPart.startsWith('/') ? pathPart : `/${pathPart}`;
+    return `${normalizedBase}${normalizedPath}`;
   }
 
-  // 拼接 proxySuffix
-  const proxySuffix = resolveProxySuffix(options?.proxySuffix);
+  // 没有 apiBaseUrl 时，仅拼接 proxySuffix（相对路径）
   if (proxySuffix) {
     return joinProxyAndPath(proxySuffix, url);
   }