generator-mico-cli 0.1.18

package/generators/micro-react/templates/.cursor/rules/micro-frontend.mdc

@@ -0,0 +1,196 @@
+---
+description: 微前端架构指南 - qiankun 子应用加载与通信
+globs: ["**/MicroAppLoader/**", "**/menu/**", "**/qiankun/**"]
+---
+
+# 微前端架构
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Layout (主应用)                          │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │  Header                                                  ││
+│  ├─────────┬───────────────────────────────────────────────┤│
+│  │         │                                               ││
+│  │  Menu   │  ┌─────────────────────────────────────────┐  ││
+│  │         │  │  MicroAppLoader / Outlet                │  ││
+│  │         │  │  (根据 loadType 选择渲染方式)            │  ││
+│  │         │  │                                         │  ││
+│  │         │  │  loadType: 'microapp' → qiankun 加载    │  ││
+│  │         │  │  loadType: 'internal' → React Router    │  ││
+│  │         │  └─────────────────────────────────────────┘  ││
+│  └─────────┴───────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 核心文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/components/MicroAppLoader/index.tsx` | qiankun 微应用加载器 |
+| `src/common/menu/parser.ts` | 菜单解析，包含加载类型判断 |
+| `src/common/menu/types.ts` | 类型定义 |
+| `src/layouts/index.tsx` | 主布局，集成微应用渲染 |
+| `config/config.ts` | qiankun master 配置 |
+
+## 加载类型判断
+
+```typescript
+/**
+ * 判断页面的加载类型
+ * 有 htmlUrl 或 jsUrls 时使用 qiankun 微应用加载
+ */
+const getLoadType = (page: MenuItem['page']): 'internal' | 'microapp' => {
+  if (!page) return 'internal';
+  
+  // 有 htmlUrl 或 jsUrls 使用 qiankun 微应用加载
+  if (page.htmlUrl || (page.jsUrls && page.jsUrls.length > 0)) {
+    return 'microapp';
+  }
+  
+  return 'internal';
+};
+```
+
+## MicroAppLoader 组件
+
+### Props 接口
+```typescript
+interface MicroAppLoaderProps {
+  /** 微应用入口 URL */
+  entry: string;
+  /** 微应用唯一标识（用于生成容器 ID） */
+  name: string;
+  /** 微应用显示名称（用于 loading 提示） */
+  displayName?: string;
+}
+```
+
+### 使用示例
+```tsx
+<MicroAppLoader
+  entry="http://localhost:8001"
+  name="/homepage"
+  displayName="首页"
+/>
+```
+
+## 传递给子应用的 Props
+
+```typescript
+interface MicroAppProps {
+  /** 主应用标识 */
+  mainApp: '<%= projectName %>';
+  /** 共享的 request 实例 */
+  request: <T = any>(url: string, options?: any) => Promise<T>;
+}
+```
+
+子应用可以使用主应用的 `request` 实例，确保认证 token 和拦截器一致。
+
+## 菜单数据结构
+
+### MenuItem
+```typescript
+interface MenuItem {
+  id: number;
+  name: string;
+  icon: string;
+  type: 'page' | 'folder' | 'link';
+  enabled: boolean;
+  sortOrder: number;
+  path?: string;           // type === 'link' 时的外链地址
+  page?: PageConfig;       // type === 'page' 时的页面配置
+  children?: MenuItem[];
+}
+```
+
+### PageConfig
+```typescript
+interface PageConfig {
+  id: number;
+  name: string;
+  route: string;
+  enabled: boolean;
+  htmlUrl: string | null;  // 微应用 HTML 入口（优先使用）
+  jsUrls: string[];        // 微应用 JS 入口（备选）
+  cssUrls: string[];       // 微应用 CSS
+}
+```
+
+## 子应用接入指南
+
+### 1. 导出 qiankun 生命周期
+```typescript
+// 子应用入口
+let mainAppProps: MicroAppProps | null = null;
+
+export async function bootstrap() {
+  console.log('micro app bootstrapped');
+}
+
+export async function mount(props: MicroAppProps) {
+  mainAppProps = props;
+  // 渲染应用
+  ReactDOM.render(<App />, props.container);
+}
+
+export async function unmount(props: MicroAppProps) {
+  mainAppProps = null;
+  // 卸载应用
+  ReactDOM.unmountComponentAtNode(props.container);
+}
+```
+
+### 2. 使用主应用的 request
+```typescript
+// 获取主应用传递的 request 实例
+const request = mainAppProps?.request;
+
+// 发起请求
+const data = await request('/api/users');
+```
+
+### 3. Webpack 配置
+```javascript
+// 子应用需要配置 umd 输出
+output: {
+  library: `${name}-[name]`,
+  libraryTarget: 'umd',
+  jsonpFunction: `webpackJsonp_${name}`,
+}
+```
+
+## 路由匹配
+
+```typescript
+/**
+ * 根据路径查找对应的路由配置
+ * 支持通配符路由 /test/*
+ */
+export const findRouteByPath = (
+  routes: ParsedRoute[],
+  pathname: string,
+): ParsedRoute | undefined => {
+  return routes.find((route) => {
+    // 处理通配符路由
+    if (route.path.endsWith('/*')) {
+      const basePath = route.path.slice(0, -2);
+      return pathname.startsWith(basePath);
+    }
+    return route.path === pathname;
+  });
+};
+```
+
+## 注意事项
+
+1. **路由通配符**: 微应用路由建议使用 `/path/*` 以支持子路由
+2. **入口优先级**: `htmlUrl` 优先级高于 `jsUrls[0]`
+3. **CORS 配置**: 子应用需要配置允许主应用域名访问
+4. **生命周期**: 子应用必须导出 `bootstrap`、`mount`、`unmount`
+5. **重载触发**: `entry` 或 `name` 变化时会重新加载微应用
+6. **错误处理**: 加载失败会显示错误信息，便于调试
+7. **认证共享**: 子应用应使用主应用传递的 `request` 实例

package/generators/micro-react/templates/.cursor/rules/project-overview.mdc

@@ -0,0 +1,128 @@
+---
+description: <%= ProjectName %> 项目总览 - 基于 qiankun 微前端架构的管理平台
+alwaysApply: true
+---
+
+# <%= ProjectName %>
+
+## 项目简介
+
+<%= ProjectName %> 是一个基于 qiankun 微前端架构的管理平台 Monorepo，采用 Turborepo + pnpm Workspace 管理多个子应用。
+
+## 技术栈
+
+| 分类 | 技术 |
+|------|------|
+| **Monorepo** | Turborepo + pnpm Workspace |
+| **前端框架** | UmiJS 4 (@umijs/max)、React 18、TypeScript |
+| **微前端** | qiankun |
+| **UI 组件** | Arco Design Web |
+| **样式方案** | Tailwind CSS + Less + CSS Variables |
+| **代码规范** | ESLint、Stylelint、Husky、Commitlint |
+
+## 项目结构
+
+```
+<%= projectName %>/
+├── apps/                         # Workspace 应用目录
+│   ├── layout/                   # 🏠 主布局应用（qiankun 主应用）
+│   │   ├── config/               # Umi 配置
+│   │   ├── docs/                 # 功能文档
+│   │   ├── mock/                 # Mock 数据
+│   │   └── src/
+│   │       ├── app.tsx           # Umi 运行时配置
+│   │       ├── layouts/          # 布局组件
+│   │       ├── pages/            # 路由页面
+│   │       ├── components/       # 公共组件
+│   │       ├── common/           # 工具模块
+│   │       │   ├── auth/         # 认证模块
+│   │       │   ├── request/      # 请求层
+│   │       │   ├── menu/         # 菜单系统
+│   │       │   └── upload/       # 上传模块
+│   │       ├── hooks/            # 自定义 Hooks
+│   │       ├── services/         # API 服务层
+│   │       ├── models/           # Umi model（全局状态）
+│   │       ├── locales/          # 国际化（zh-CN、en-US）
+│   │       └── styles/           # 主题变量与样式
+│   └── [subapp]/                 # 📄 子应用
+├── scripts/                      # 构建与开发脚本
+├── CICD/                         # CI/CD 部署脚本
+├── docs/                         # 项目文档
+├── turbo.json                    # Turborepo 配置
+├── pnpm-workspace.yaml           # Workspace 配置
+└── package.json                  # 根包配置
+```
+
+## 核心模块说明
+
+### 1. Layout 主应用 (apps/layout)
+- **角色**: qiankun 主应用容器
+- **职责**: 提供布局框架、菜单导航、主题切换、认证管理
+- **关键文件**:
+  - `src/layouts/index.tsx` - 主布局组件
+  - `src/components/MicroAppLoader/` - 微应用加载器
+  - `src/common/menu/parser.ts` - 菜单解析与路由提取
+  - `src/common/request/index.ts` - 统一请求封装
+  - `src/hooks/useTheme.ts` - 主题管理 Hook
+
+### 2. 微前端架构
+- 菜单数据通过 `window.__MICO_MENUS__` 注入
+- 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
+- 使用 `loadMicroApp` API 动态挂载子应用
+- 子应用共享主应用的 `request` 实例
+
+### 3. 主题系统
+- 支持亮色/暗黑主题切换
+- 使用 CSS Variables 实现运行时动态切换
+- `arco-theme` 控制 Arco Design 组件
+- `data-theme` 控制自定义样式
+
+## 常用命令
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发（交互式选择应用）
+pnpm dev
+
+# 直接启动指定应用
+pnpm -C apps/layout dev
+
+# 构建
+pnpm build                    # 生产环境
+pnpm build:development        # 开发环境
+pnpm build:testing            # 测试环境
+
+# 代码检查
+pnpm lint
+pnpm lint:fix
+
+# 创建新应用
+mico create subapp-react
+```
+
+## 环境变量
+
+- 根目录 `.env` 文件通过 `dotenv-cli` 注入所有应用
+- 应用专属变量放在 `apps/<app>/.env.local`
+- 影响缓存的变量需在 `turbo.json` 的 `globalEnv` 中登记
+
+## CI/CD 构建
+
+Jenkins 根据环境执行 `CICD/` 下的构建脚本：
+
+| 环境 | 脚本 | CDN 域名 |
+|------|------|---------|
+| 开发 | `start_dev.sh` | `cdn-dev.example.com` |
+| 测试 | `start_test.sh` | `cdn-test.example.com` |
+| 生产 | `start_prod.sh` | `cdn.example.com` |
+
+分支策略：`test` → 测试环境，`main` → 生产环境
+
+## 相关文档
+
+- [微前端模式](mdc:apps/layout/docs/feature-微前端模式.md)
+- [主题色切换](mdc:apps/layout/docs/feature-主题色切换.md)
+- [提交规范](mdc:docs/commit-message.md)
+- [部署说明](mdc:deployDesc.md)

package/generators/micro-react/templates/.cursor/rules/request-auth.mdc

@@ -0,0 +1,220 @@
+---
+description: 请求与认证模块 - API 请求封装与 SSO 认证流程
+globs: ["**/request/**", "**/auth/**", "**/services/**"]
+---
+
+# 请求与认证模块
+
+## 请求层架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     request() 函数                           │
+├─────────────────────────────────────────────────────────────┤
+│  1. ensureSsoSession() - 处理 SSO ticket 换 token            │
+│  2. runRequestInterceptors() - 执行请求拦截器                 │
+│  3. baseRequest() - 发起实际请求                             │
+│  4. runResponseInterceptors() - 执行响应拦截器               │
+│  5. 错误处理 - 401/403 时刷新 token                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 核心文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/common/request/index.ts` | 统一请求封装 |
+| `src/common/auth/cs-auth-manager.ts` | Token 存储管理 |
+| `src/common/auth/index.ts` | 认证入口 |
+| `src/common/auth/tool.ts` | 认证工具函数 |
+| `src/requestErrorConfig.ts` | 错误处理配置 |
+
+## 请求函数使用
+
+### 基本用法
+```typescript
+import { request } from '@/common/request';
+
+// GET 请求
+const users = await request<IUserList>('/api/users');
+
+// POST 请求
+const result = await request('/api/users', {
+  method: 'POST',
+  data: { name: 'John' },
+});
+
+// 带自定义 headers
+const data = await request('/api/data', {
+  headers: { 'X-Custom': 'value' },
+});
+```
+
+### 请求选项
+```typescript
+interface UnifiedRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  data?: any;
+  headers?: Record<string, string>;
+  proxySuffix?: string;      // 自定义代理路径
+  useCache?: boolean;        // 使用缓存
+  [key: string]: any;
+}
+```
+
+## 请求拦截器
+
+### 内置拦截器
+1. **等待队列拦截器**: 在获取 token 期间拦截请求
+2. **默认 Headers 拦截器**: 添加认证信息
+
+### 注册自定义拦截器
+```typescript
+import { registerRequestInterceptor, registerResponseInterceptor } from '@/common/request';
+
+// 请求拦截器
+const removeInterceptor = registerRequestInterceptor(async (ctx) => {
+  console.log('Request:', ctx.url);
+  return ctx;
+});
+
+// 响应拦截器
+registerResponseInterceptor(async (data, ctx) => {
+  console.log('Response:', data);
+  return data;
+});
+
+// 移除拦截器
+removeInterceptor();
+```
+
+## 认证流程
+
+### SSO 登录流程
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│  用户    │     │  主应用   │     │ SSO 服务  │
+└────┬─────┘     └────┬─────┘     └────┬─────┘
+     │                │                │
+     │  访问页面      │                │
+     │───────────────>│                │
+     │                │                │
+     │                │ 无 token，重定向 │
+     │<───────────────│                │
+     │                │                │
+     │  SSO 登录      │                │
+     │──────────────────────────────────>
+     │                │                │
+     │  带 ticket 回调 │                │
+     │<──────────────────────────────────
+     │                │                │
+     │  ticket 换 token                │
+     │                │───────────────>│
+     │                │<───────────────│
+     │                │                │
+     │  返回页面内容   │                │
+     │<───────────────│                │
+```
+
+### Token 刷新流程
+```typescript
+// 401/403 时自动刷新 token
+try {
+  const response = await baseRequest(url, options);
+} catch (error) {
+  if (shouldAttemptRefresh(error)) {
+    const newToken = await getRefreshPromise();
+    if (newToken) {
+      // 使用新 token 重试请求
+      return baseRequest(url, { ...options, headers: { authtoken: newToken } });
+    }
+    // 刷新失败，重定向登录
+    handleAuthFailureRedirect();
+  }
+}
+```
+
+## Token 存储
+
+### 存储 Key
+```typescript
+const AUTH_TOKEN_KEY = 'auth_token';
+const REFRESH_TOKEN_KEY = 'refresh_token';
+const UID_KEY = 'uid';
+```
+
+### 获取/设置 Token
+```typescript
+import {
+  getStoredAuthToken,
+  setStoredAuthToken,
+  getStoredRefreshToken,
+  setStoredRefreshToken,
+  clearStoredTokens,
+} from '@/common/auth/cs-auth-manager';
+
+// 获取 token
+const token = getStoredAuthToken();
+
+// 设置 token
+setStoredAuthToken(newToken);
+
+// 清除所有 token（登出）
+clearStoredTokens();
+```
+
+## 环境变量
+
+在 `.env` 文件中配置：
+
+```bash
+# API 基础地址
+API_BASE_URL=https://api.example.com
+
+# 代理路径后缀
+PROXY_SUFFIX=/api
+
+# 应用 ID
+APP_ID=<%= projectName %>
+
+# SSO 相关
+LOGIN_ENDPOINT=/auth/login
+REFRESH_ENDPOINT=/auth/refresh
+EXTERNAL_LOGIN_PATH=https://sso.example.com/login
+```
+
+## 错误处理
+
+### 业务错误码
+```typescript
+// 响应拦截器处理 result.code
+addResponseInterceptor(async (data) => {
+  if (data?.result?.code !== 0) {
+    const error = new Error(data.result.desc);
+    error.code = data.result.code;
+    error.response = data;
+    throw error;
+  }
+  return data;
+});
+```
+
+### 使用 try-catch
+```typescript
+try {
+  const data = await request('/api/users');
+} catch (error) {
+  if (error.code === 1001) {
+    // 处理特定错误码
+  }
+  console.error('请求失败:', error.message);
+}
+```
+
+## 注意事项
+
+1. **统一使用 request**: 不要直接使用 `fetch` 或 `axios`
+2. **Token 自动处理**: 请求头自动携带 authtoken
+3. **错误自动提示**: success: false 时自动弹出错误消息
+4. **子应用共享**: 微应用应使用主应用传递的 request 实例
+5. **防重复刷新**: token 刷新期间的请求会进入等待队列