generator-mico-cli 0.1.18

package/generators/micro-react/templates/.cursor/rules/development-guide.mdc

@@ -0,0 +1,295 @@
+---
+description: 开发指南 - 环境配置、常用命令、调试技巧
+globs: []
+---
+
+# 开发指南
+
+## 环境要求
+
+- **Node.js**: ≥ 18
+- **pnpm**: 10.18.2（推荐使用 corepack）
+
+```bash
+# 启用 corepack 并安装指定版本 pnpm
+corepack prepare pnpm@10.18.2 --activate
+```
+
+## 项目初始化
+
+```bash
+# 克隆项目
+git clone <repo-url>
+cd <%= projectName %>
+
+# 安装依赖
+pnpm install
+```
+
+## 开发命令
+
+### 启动开发服务器
+
+```bash
+# 交互式选择应用
+pnpm dev
+
+# 直接启动指定应用
+pnpm -C apps/layout dev
+
+# 启动 layout 应用（不使用 mock）
+pnpm -C apps/layout start:development:no-mock
+
+# 使用测试环境配置
+pnpm -C apps/layout start:testing
+```
+
+### 构建命令
+
+```bash
+# 生产环境构建（默认）
+pnpm build
+
+# 开发环境构建
+pnpm build:development
+
+# 测试环境构建
+pnpm build:testing
+
+# 生产环境构建
+pnpm build:production
+
+# 本地构建（不包含环境变量）
+pnpm build:local
+```
+
+### 代码检查
+
+```bash
+# 运行 lint
+pnpm lint
+
+# 自动修复
+pnpm lint:fix
+```
+
+### 创建新应用
+
+```bash
+# 在 apps/ 下创建新的 Umi 应用
+pnpm create:umi-app <app-name>
+```
+
+## 环境变量配置
+
+### 文件优先级
+```
+.env                  # 基础配置
+.env.local            # 本地覆盖（不提交）
+.env.development      # 开发环境
+.env.development.local
+.env.testing          # 测试环境
+.env.testing.local
+.env.production       # 生产环境
+.env.production.local
+```
+
+### 常用变量
+```bash
+# API 基础地址
+API_BASE_URL=https://api.example.com
+
+# 代理路径
+PROXY_SUFFIX=/api
+
+# 应用 ID
+APP_ID=<%= projectName %>
+
+# CDN 公共路径
+CDN_PUBLIC_PATH=/dist/
+
+# SSO 配置
+LOGIN_ENDPOINT=/auth/login
+REFRESH_ENDPOINT=/auth/refresh
+EXTERNAL_LOGIN_PATH=https://sso.example.com/login
+```
+
+## 目录约定
+
+### 新建页面
+```
+src/pages/
+├── MyPage/
+│   ├── index.tsx      # 页面组件
+│   ├── index.less     # 页面样式
+│   └── components/    # 页面私有组件
+│       └── List.tsx
+```
+
+### 新建组件
+```
+src/components/
+├── MyComponent/
+│   ├── index.tsx      # 组件入口
+│   ├── index.less     # 组件样式
+│   └── types.ts       # 类型定义（可选）
+```
+
+### 新建 Hook
+```
+src/hooks/
+├── useMyHook.ts       # Hook 实现
+└── index.ts           # 统一导出
+```
+
+### 新建服务
+```
+src/services/
+├── user.ts            # 用户相关 API
+└── auth.ts            # 认证相关 API
+```
+
+## 调试技巧
+
+### 查看微应用加载日志
+```javascript
+// 在浏览器控制台过滤
+[MicroAppLoader]
+[Layout]
+```
+
+### 查看请求日志
+```javascript
+// 在 src/common/request/index.ts 中添加
+addRequestInterceptor(async (ctx) => {
+  console.log('[Request]', ctx.url, ctx.options);
+  return ctx;
+});
+```
+
+### 主题调试
+```javascript
+// 在控制台切换主题
+document.body.setAttribute('arco-theme', 'dark');
+document.body.setAttribute('data-theme', 'dark');
+```
+
+## Mock 数据
+
+### 文件位置
+```
+apps/layout/mock/
+├── menus.json         # 菜单数据
+├── menus.ts           # 菜单数据处理
+└── user.mock.ts       # 用户相关 Mock API
+```
+
+### Mock 文件命名
+- `*.mock.ts` - Mock API 文件
+- `_mock.ts` - 页面级 Mock 文件
+
+### 禁用 Mock
+```bash
+# 启动时禁用 mock
+pnpm -C apps/layout start:development:no-mock
+```
+
+## Umi 配置
+
+### 路由配置
+```typescript
+// config/routes.ts
+export default [
+  {
+    path: '/',
+    component: '@/layouts/index',
+    routes: [
+      { path: '/', component: '@/pages/Home' },
+    ],
+  },
+];
+```
+
+### 环境配置覆盖
+```typescript
+// config/config.dev.ts
+export default {
+  define: {
+    'process.env.API_BASE': 'http://localhost:3000',
+  },
+};
+```
+
+## 常见问题
+
+### 1. 依赖安装失败
+```bash
+# 清除缓存重新安装
+pnpm store prune
+rm -rf node_modules
+pnpm install
+```
+
+### 2. TypeScript 类型报错
+```bash
+# 重新生成类型
+pnpm -C apps/layout setup
+```
+
+### 3. 样式不生效
+- 检查 Less 文件是否导入
+- 检查类名是否正确
+- 检查主题变量是否使用正确
+
+### 4. 微应用加载失败
+- 检查子应用是否启动
+- 检查 CORS 配置
+- 检查 entry URL 是否正确
+- 查看控制台 `[MicroAppLoader]` 日志
+
+## CI/CD 构建
+
+### Jenkins 构建流程
+
+Jenkins 根据不同环境执行 `CICD/` 目录下的脚本：
+
+| 环境 | 脚本 | 构建命令 |
+|------|------|---------|
+| 开发 | `CICD/start_dev.sh` | `build:development` |
+| 测试 | `CICD/start_test.sh` | `build:testing` |
+| 生产 | `CICD/start_prod.sh` | `build:production` |
+| 本地 | `CICD/start_local.sh` | `build:local` |
+
+### 本地模拟构建
+
+```bash
+# 模拟测试环境构建
+sh CICD/start_test.sh
+
+# 模拟生产环境构建
+sh CICD/start_prod.sh
+```
+
+### CDN 路径
+
+构建产物上传到 CDN：
+```
+cdn-portal[-env].micoplatform.com/<%= projectName %>/{version}/dist/{app}/
+```
+
+- `version`：`package.json` 的 version 字段
+- `app`：`apps/` 目录下的应用名（layout、homepage 等）
+
+### 分支策略
+
+| 分支 | 环境 |
+|------|------|
+| `test` | 测试环境 |
+| `main` | 生产环境 |
+
+## 相关链接
+
+- [UmiJS 文档](https://umijs.org/)
+- [Arco Design](https://arco.design/)
+- [qiankun 文档](https://qiankun.umijs.org/)
+- [Turborepo 文档](https://turbo.build/repo)

package/generators/micro-react/templates/.cursor/rules/layout-app.mdc

@@ -0,0 +1,275 @@
+---
+description: Layout 主应用详解 - 布局组件、菜单系统、路由管理
+globs: ["apps/layout/**"]
+---
+
+# Layout 主应用
+
+## 应用角色
+
+Layout 是 qiankun 微前端架构的**主应用**，负责：
+- 提供整体布局框架（Header + Menu + Content）
+- 管理菜单导航和路由
+- 处理认证和授权
+- 加载和管理微前端子应用
+- 提供主题切换功能
+- 共享 request 实例给子应用
+
+## 目录结构
+
+```
+apps/layout/
+├── config/                    # Umi 配置
+│   ├── config.ts              # 主配置
+│   ├── config.dev.ts          # 开发环境覆盖
+│   ├── config.testing.ts      # 测试环境覆盖
+│   ├── config.prod.ts         # 生产环境覆盖
+│   └── routes.ts              # 静态路由配置
+├── docs/                      # 功能文档
+├── mock/                      # Mock 数据
+├── public/                    # 静态资源
+└── src/
+    ├── app.tsx                # Umi 运行时配置
+    ├── global.less            # 全局样式
+    ├── layouts/               # 布局组件
+    │   ├── index.tsx          # 主布局
+    │   ├── index.less
+    │   └── components/
+    │       ├── header/        # 顶部导航
+    │       └── menu/          # 侧边菜单
+    ├── pages/                 # 路由页面
+    │   └── Home/
+    ├── components/            # 公共组件
+    │   ├── MicroAppLoader/    # 微应用加载器
+    │   └── IconFont/          # 图标组件
+    ├── common/                # 工具模块
+    │   ├── auth/              # 认证模块
+    │   ├── request/           # 请求封装
+    │   ├── menu/              # 菜单解析
+    │   ├── upload/            # 上传模块
+    │   └── theme.ts           # 主题初始化
+    ├── hooks/                 # 自定义 Hooks
+    ├── services/              # API 服务
+    ├── models/                # Umi Model
+    ├── locales/               # 国际化
+    └── styles/                # 主题样式
+        ├── themes/            # 主题变量
+        ├── variables.less     # Less 变量
+        └── arco-override.less # Arco 覆盖
+```
+
+## 核心模块
+
+### 1. 布局组件 (layouts/index.tsx)
+
+```tsx
+const BasicLayout: React.FC = () => {
+  const location = useLocation();
+
+  // 解析路由配置
+  const routes = useMemo(() => {
+    const menus = getWindowMenus();
+    return extractRoutes(menus);
+  }, []);
+
+  // 查找当前路由配置
+  const currentRoute = useMemo(() => {
+    return findRouteByPath(routes, location.pathname);
+  }, [routes, location.pathname]);
+
+  // 渲染页面内容
+  const renderContent = () => {
+    // 微应用类型使用 MicroAppLoader
+    if (currentRoute?.loadType === 'microapp' && currentRoute.entry) {
+      return <MicroAppLoader entry={currentRoute.entry} name={currentRoute.path} />;
+    }
+    // 内部路由使用 Outlet
+    return <Outlet />;
+  };
+
+  return (
+    <Layout className="layout-container">
+      <LayoutHeader />
+      <Layout className="layout-content">
+        <LayoutMenu />
+        <Layout className="layout-content-right">
+          <Content>{renderContent()}</Content>
+        </Layout>
+      </Layout>
+    </Layout>
+  );
+};
+```
+
+### 2. 菜单系统 (common/menu/)
+
+```typescript
+// 获取菜单数据
+const menus = getWindowMenus();
+
+// 提取路由配置
+const routes = extractRoutes(menus);
+
+// 解析菜单项
+const menuItems = parseMenuItems(menus);
+
+// 查找当前路由
+const currentRoute = findRouteByPath(routes, pathname);
+```
+
+### 3. 动态路由 (app.tsx)
+
+```typescript
+export function patchClientRoutes({ routes }: { routes: any[] }) {
+  const menus = getWindowMenus();
+  const dynamicRoutes = extractRoutes(menus);
+
+  const rootRoute = routes.find((r) => r.path === '/');
+  dynamicRoutes.forEach((route) => {
+    rootRoute.routes.push({
+      path: route.path,
+      name: route.name,
+      meta: {
+        loadType: route.loadType,
+        htmlUrl: route.htmlUrl,
+        jsUrls: route.jsUrls,
+        cssUrls: route.cssUrls,
+      },
+    });
+  });
+}
+```
+
+### 4. 认证初始化 (app.tsx)
+
+```typescript
+export async function getInitialState() {
+  const authInfo = getAuthInfo();
+  return {
+    currentUser: {
+      name: authInfo.nickname,
+      avatar: authInfo.avatar,
+      userid: authInfo.uid,
+    },
+  };
+}
+```
+
+## Umi 配置要点
+
+### config/config.ts
+```typescript
+export default defineConfig({
+  // 挂载元素
+  mountElementId: '<%= projectName %>',
+
+  // 禁用内置 layout，使用自定义布局
+  layout: false,
+
+  // 国际化
+  locale: {
+    default: 'zh-CN',
+    antd: false,
+  },
+
+  // qiankun 主应用配置
+  qiankun: {
+    master: {
+      apps: [], // 子应用在运行时动态注册
+    },
+  },
+
+  // Tailwind CSS
+  tailwindcss: {},
+});
+```
+
+## 常用 Hooks
+
+### useTheme
+```typescript
+const { theme, isDark, toggleTheme, setTheme } = useTheme();
+```
+
+### useMenu
+```typescript
+const { menuItems, selectedKey, openKeys } = useMenu();
+```
+
+### useAuth
+```typescript
+const { isAuthenticated, user, logout } = useAuth();
+```
+
+## 样式系统
+
+### 主题变量引入
+```less
+// 在组件样式中使用
+@import '@/styles/variables.less';
+
+.my-component {
+  background: @color-fill-1;
+  color: @color-text-2;
+}
+```
+
+### Tailwind CSS 使用
+```tsx
+<div className="flex items-center gap-4 p-4">
+  <span className="text-gray-600">标题</span>
+</div>
+```
+
+## 国际化
+
+### 定义翻译
+```typescript
+// locales/zh-CN.ts
+export default {
+  'menu.home': '首页',
+  'menu.settings': '设置',
+};
+
+// locales/en-US.ts
+export default {
+  'menu.home': 'Home',
+  'menu.settings': 'Settings',
+};
+```
+
+### 使用翻译
+```tsx
+import { useIntl } from '@umijs/max';
+
+const { formatMessage } = useIntl();
+const title = formatMessage({ id: 'menu.home' });
+```
+
+## Model 状态管理
+
+```typescript
+// models/global.ts
+export default {
+  namespace: 'global',
+  state: {
+    collapsed: false,
+  },
+  reducers: {
+    toggleCollapsed(state) {
+      return { ...state, collapsed: !state.collapsed };
+    },
+  },
+};
+
+// 使用
+const { collapsed } = useModel('global');
+```
+
+## 注意事项
+
+1. **菜单数据来源**: 通过 `window.__MICO_MENUS__` 注入
+2. **路由动态生成**: 在 `patchClientRoutes` 中根据菜单生成路由
+3. **微应用判断**: 根据 `htmlUrl` 或 `jsUrls` 判断是否为微应用
+4. **主题初始化**: 在 `app.tsx` 中调用 `initTheme()` 避免闪烁
+5. **认证共享**: 子应用使用主应用传递的 `request` 实例