generator-mico-cli 0.1.28 → 0.2.1

package/generators/micro-react/templates/apps/layout/docs/feature-/345/276/256/345/211/215/347/253/257/346/250/241/345/274/217.md

@@ -0,0 +1,432 @@
+# 微前端模式
+
+> 创建时间：2025-12-26
+
+## 功能概述
+
+基于 qiankun 微前端框架实现动态子应用加载，支持根据菜单配置自动识别并加载外部微应用，实现主应用与子应用的解耦部署。
+
+## 技术方案
+
+### 技术栈
+
+- 框架：React 18 + @umijs/max
+- 微前端：qiankun (通过 @umijs/max 内置插件)
+- UI 组件：Arco Design
+- 路由：React Router 6
+
+### 核心实现
+
+1. 主应用通过 `window.__MICO_MENUS__` 获取菜单配置
+2. 解析菜单时根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
+3. 路由匹配时，微应用类型使用 `MicroAppLoader` 组件加载
+4. `MicroAppLoader` 使用 qiankun 的 `loadMicroApp` API 动态挂载子应用
+5. 组件卸载时自动调用 `unmount()` 清理子应用
+
+## 文件清单
+
+### 核心文件
+
+| 文件路径                                   | 说明                       |
+| ------------------------------------------ | -------------------------- |
+| `src/components/MicroAppLoader/index.tsx`  | qiankun 微应用加载器组件   |
+| `src/components/MicroAppLoader/index.less` | 加载器样式                 |
+| `src/common/menu/parser.ts`                | 菜单解析，包含加载类型判断 |
+| `src/common/menu/types.ts`                 | 类型定义                   |
+| `src/layouts/index.tsx`                    | 主布局，集成微应用渲染     |
+| `config/config.ts`                         | qiankun master 配置        |
+
+## API / 组件接口
+
+### MicroAppLoader
+
+```typescript
+interface MicroAppLoaderProps {
+  /** 微应用入口 URL */
+  entry: string;
+  /** 微应用名称 */
+  name: string;
+  /** 显示名称（用于加载提示） */
+  displayName?: string;
+  /** 当前路由路径，用于通知子应用进行内部路由切换 */
+  routePath?: string;
+}
+```
+
+**参数说明**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| entry | string | 是 | qiankun 入口 URL (htmlUrl 或 jsUrls[0]) |
+| name | string | 是 | 微应用唯一标识 |
+| displayName | string | 否 | 显示名称，用于加载提示 |
+| routePath | string | 否 | 当前路由路径，用于子应用内部路由切换 |
+
+### MicroAppProps (传递给子应用)
+
+```typescript
+interface MicroAppProps {
+  /** 主应用标识 */
+  mainApp: 'portal-web';
+  /** 运行环境 */
+  env: 'development' | 'testing' | 'production';
+  /** 认证 token */
+  authToken: string;
+  /** 用户 ID */
+  uid: string;
+  /** 用户头像 */
+  avatar: string;
+  /** 用户昵称 */
+  nickname: string;
+  /** 当前语言 */
+  locale: string;
+  /** 当前时区 */
+  timezone: string;
+  /** 在线状态 */
+  presenceStatus: string;
+  /** 当前路由路径 */
+  routePath?: string;
+  /** 共享的 request 实例，子应用可直接使用 */
+  request: <T = any>(url: string, options?: any) => Promise<T>;
+}
+```
+
+**说明**：子应用在 `mount` 生命周期中通过 `props` 接收这些数据。
+
+### 子应用 Props 更新机制
+
+主应用通过 qiankun 的 `update()` 方法实时通知子应用状态变化，无需重新加载：
+
+```typescript
+// MicroAppLoader 内部实现
+useEffect(() => {
+  if (!isMountedRef.current) return;
+  const microApp = getMicroApp(appName);
+  // 当 locale、timezone、presenceStatus、routePath 变化时，调用 update
+  microApp?.update?.(buildPropsRef.current());
+}, [appName, locale, timezone, presenceStatus, routePath]);
+```
+
+子应用需要导出 `update` 生命周期来接收更新：
+
+```typescript
+// 子应用入口
+export async function update(props: MicroAppProps) {
+  console.log('micro app updated', props);
+  // 响应主应用的状态变化，如切换语言、时区等
+}
+```
+
+### ParsedRoute
+
+```typescript
+interface ParsedRoute {
+  path: string;
+  name: string;
+  icon: string;
+  /** 加载类型: internal(内部路由) | microapp(qiankun微应用) */
+  loadType: 'internal' | 'microapp';
+  /** 微应用入口 URL */
+  entry?: string;
+  pageConfig?: PageConfig;
+}
+```
+
+### PageConfig
+
+```typescript
+interface PageConfig {
+  id: number;
+  name: string;
+  route: string;
+  enabled: boolean;
+  /** 微应用 HTML 入口 URL (优先使用) */
+  htmlUrl: string | null;
+  /** 微应用 JS 入口 URL 列表 (备选) */
+  jsUrls: string[];
+  /** 微应用 CSS URL 列表 */
+  cssUrls: string[];
+}
+```
+
+### 辅助函数
+
+```typescript
+/** 判断页面加载类型 */
+function getLoadType(page: MenuItem['page']): 'internal' | 'microapp';
+
+/** 获取微应用入口 URL，优先 htmlUrl */
+function getEntry(page: MenuItem['page']): string | undefined;
+
+/** 根据路径查找路由配置 */
+function findRouteByPath(
+  routes: ParsedRoute[],
+  pathname: string,
+): ParsedRoute | undefined;
+```
+
+## 使用示例
+
+### 菜单配置示例
+
+```typescript
+// window.__MICO_MENUS__ 数据结构
+const menus: MenuItem[] = [
+  {
+    id: 1,
+    name: '内部页面',
+    type: 'page',
+    enabled: true,
+    page: {
+      route: '/dashboard',
+      enabled: true,
+      htmlUrl: null,
+      jsUrls: [],
+      cssUrls: [],
+    },
+  },
+  {
+    id: 2,
+    name: '外部微应用',
+    type: 'page',
+    enabled: true,
+    page: {
+      route: '/external/*',
+      enabled: true,
+      htmlUrl: 'http://localhost:8001', // qiankun entry
+      jsUrls: [],
+      cssUrls: [],
+    },
+  },
+];
+```
+
+### 布局集成
+
+```tsx
+// layouts/index.tsx
+const renderContent = () => {
+  if (currentRoute?.loadType === 'microapp' && currentRoute.entry) {
+    return (
+      <MicroAppLoader entry={currentRoute.entry} name={currentRoute.name} />
+    );
+  }
+  return <Outlet />;
+};
+```
+
+### 子应用配置要求
+
+子应用需要导出 qiankun 生命周期，并可使用主应用共享的 `request` 实例：
+
+```typescript
+// 子应用入口
+import type { MicroAppProps } from '<%= ProjectName %>/layout';
+
+// 存储主应用传递的 props
+let mainAppProps: MicroAppProps | null = null;
+
+export async function bootstrap() {
+  console.log('micro app bootstrapped');
+}
+
+export async function mount(props: MicroAppProps) {
+  console.log('micro app mounted', props);
+  // 保存主应用传递的 props
+  mainAppProps = props;
+
+  // 使用主应用的 request 实例发起请求
+  const data = await props.request('/api/example');
+  console.log('data from main app request:', data);
+}
+
+export async function unmount() {
+  mainAppProps = null;
+  console.log('micro app unmounted');
+}
+
+// 导出 request 供子应用内部使用
+export const getRequest = () => mainAppProps?.request;
+```
+
+## 依赖共享机制
+
+### 问题背景
+
+如果子应用直接安装 React、Arco Design 等大型库，会导致：
+
+1. **包体积重复**：React (~140KB) + Arco Design (~800KB) 被打包多次
+2. **样式冲突**：多份 CSS 可能互相覆盖
+3. **React 实例问题**：可能出现 "Invalid hook call" 错误
+
+### 解决方案：externals + window 共享
+
+主应用将公共库暴露到 `window`，子应用通过 `externals` 配置引用，避免重复打包。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  主应用 (layout)                                            │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ 1. 打包并加载 React、ReactDOM、Arco Design              ││
+│  │ 2. 暴露到 window.React / window.ReactDOM / window.arco  ││
+│  └─────────────────────────────────────────────────────────┘│
+│                           ↓ 共享                            │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ 子应用 (homepage 等)                                    ││
+│  │ - externals 配置: react → window.React                  ││
+│  │ - 运行时从 window 获取，不重复打包                      ││
+│  │ - 打包体积减少 ~1MB                                     ││
+│  └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 主应用配置
+
+在 `src/app.tsx` 中暴露共享依赖：
+
+```typescript
+// apps/layout/src/app.tsx
+import * as arco from '@arco-design/web-react';
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+// 将公共库暴露到 window，供子应用复用
+if (typeof window !== 'undefined') {
+  (window as any).React = React;
+  (window as any).ReactDOM = ReactDOM;
+  (window as any).arco = arco;
+}
+```
+
+### 子应用配置
+
+#### 环境配置策略
+
+| 环境 | 配置文件         | 策略           | 说明                       |
+| ---- | ---------------- | -------------- | -------------------------- |
+| 开发 | `config.dev.ts`  | 直接打包依赖   | 独立运行方便，无需配置 CDN |
+| 生产 | `config.prod.ts` | externals 排除 | 复用主应用依赖，包体积最小 |
+
+#### 1. config.prod.ts - 生产环境 externals 配置
+
+```typescript
+// apps/[子应用]/config/config.prod.ts
+import { defineConfig } from '@umijs/max';
+
+const config: ReturnType<typeof defineConfig> = {
+  // 生产环境：将所有代码打包到一个文件
+  extraBabelPlugins: ['babel-plugin-dynamic-import-node'],
+
+  // 禁用代码分割，只输出一个 JS 和一个 CSS
+  chainWebpack(memo) {
+    memo.optimization.splitChunks(false);
+    memo.optimization.runtimeChunk(false);
+    return memo;
+  },
+
+  /**
+   * @name 外部依赖配置
+   * @description 将大型公共库排除打包，运行时从主应用获取
+   */
+  externals: {
+    react: 'window.React',
+    'react-dom': 'window.ReactDOM',
+    '@arco-design/web-react': 'window.arco',
+  },
+};
+
+export default defineConfig(config);
+```
+
+#### 2. config.dev.ts - 开发环境配置
+
+```typescript
+// apps/[子应用]/config/config.dev.ts
+import { defineConfig } from '@umijs/max';
+
+/**
+ * 开发环境配置
+ * - 不配置 externals，直接打包依赖，方便独立运行调试
+ * - 生产环境通过 config.prod.ts 配置 externals 复用主应用依赖
+ */
+const config: ReturnType<typeof defineConfig> = {
+  publicPath: '/',
+  base: '/',
+};
+
+export default defineConfig(config);
+```
+
+#### 3. package.json - 开发依赖
+
+将 Arco Design 放在 `devDependencies`（用于类型提示和开发），生产环境从主应用获取：
+
+```json
+{
+  "devDependencies": {
+    "@arco-design/web-react": "^2.66.6"
+  }
+}
+```
+
+### 子应用使用 Arco Design
+
+配置完成后，子应用可以正常导入和使用 Arco Design 组件：
+
+```tsx
+// apps/[子应用]/src/pages/index.tsx
+import { Button, Card, Message, Tag } from '@arco-design/web-react';
+
+export default function HomePage() {
+  return (
+    <Card title="子应用示例">
+      <Button type="primary" onClick={() => Message.success('成功!')}>
+        点击按钮
+      </Button>
+      <Tag color="arcoblue">标签</Tag>
+    </Card>
+  );
+}
+```
+
+### 打包体积对比
+
+| 配置方式           | 子应用 JS 体积 | 说明                     |
+| ------------------ | -------------- | ------------------------ |
+| 直接安装依赖       | ~1.2MB         | 包含 React + Arco Design |
+| **externals 共享** | **~50KB**      | 仅业务代码               |
+
+### 运行环境说明
+
+| 环境                   | 依赖来源             | 配置文件         |
+| ---------------------- | -------------------- | ---------------- |
+| 开发环境（独立运行）   | 直接打包到子应用     | `config.dev.ts`  |
+| 生产环境（微前端模式） | 从主应用 window 获取 | `config.prod.ts` |
+
+> **设计理念**：开发时优先调试便利性（直接打包），生产时优先性能（externals 共享）。
+
+## 注意事项
+
+- 微应用路由建议使用通配符 `/path/*` 以支持子路由
+- `htmlUrl` 优先级高于 `jsUrls[0]`
+- 子应用需要配置 CORS 允许主应用域名访问
+- 子应用需要导出 qiankun 标准生命周期函数
+- 组件会在 `entry` 或 `name` 变化时重新加载微应用
+- 加载失败会显示错误信息，便于调试
+- **子应用应使用主应用传递的 `request` 实例**，确保认证 token 和拦截器一致
+- **子应用使用 externals 共享依赖**，避免重复打包 React 和 Arco Design
+
+## 相关文档
+
+- [主题色切换](./feature-主题色切换.md) - 主题系统实现与子应用适配
+- [请求模块架构](./arch-请求模块.md) - HTTP 请求层模块化设计
+- [日志与常量](./arch-日志与常量.md) - Logger 工具与常量管理
+- [shared-styles 包](../../../packages/shared-styles/README.md) - 共享样式包使用指南
+- [提交规范](../../../docs/commit-message.md) - Git Commit 规范
+
+## 加载类型判断逻辑
+
+```
+有 htmlUrl 或 jsUrls  →  microapp (使用 qiankun 加载)
+无 htmlUrl 且无 jsUrls →  internal (使用 Outlet 渲染)
+```

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/mock/api.mock.ts

@@ -6,17 +6,17 @@
 
 export default {
   // 获取用户信息
-  'GET /api/user/info': {
-    success: true,
-    data: {
-      id: 1001,
-      name: '张三',
-      email: 'zhangsan@example.com',
-      avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=homepage',
-      role: 'admin',
-      department: '技术部',
-    },
-  },
+  // 'GET /api/user/info': {
+  //   success: true,
+  //   data: {
+  //     id: 1001,
+  //     name: '张三',
+  //     email: 'zhangsan@example.com',
+  //     avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=homepage',
+  //     role: 'admin',
+  //     department: '技术部',
+  //   },
+  // },
 
   // 获取统计数据
   'GET /api/dashboard/stats': {
@@ -37,25 +37,25 @@ export default {
       list: [
         {
           id: 1,
-          title: '待处理任务 A',
+          title: '待审核内容 A',
           status: 'pending',
           createdAt: '2025-12-27 10:00:00',
         },
         {
           id: 2,
-          title: '待处理任务 B',
+          title: '待审核内容 B',
           status: 'pending',
           createdAt: '2025-12-27 09:30:00',
         },
         {
           id: 3,
-          title: '已完成任务 C',
+          title: '已通过内容 C',
           status: 'approved',
           createdAt: '2025-12-26 15:00:00',
         },
         {
           id: 4,
-          title: '已取消任务 D',
+          title: '已拒绝内容 D',
           status: 'rejected',
           createdAt: '2025-12-26 14:00:00',
         },