|
| 1 | +# CLAUDE.md - umi-react-admin 项目指南 |
| 2 | + |
| 3 | +这是 Claude Code 在处理此项目时的上下文文档。 |
| 4 | + |
| 5 | +## 项目概述 |
| 6 | + |
| 7 | +umi-react-admin 是一个基于 Umi Max 的企业级 React 后台管理系统模板，包含丰富的功能组件展示，如日历、富文本编辑、地图（Cesium/高德/OpenLayers）、低代码设计器等。 |
| 8 | + |
| 9 | +## 技术栈 |
| 10 | + |
| 11 | +- **框架**: Umi Max 4.x + React 18 + TypeScript 5.x |
| 12 | +- **UI**: Ant Design 5 + Ant Design Pro Components |
| 13 | +- **样式**: Tailwind CSS 3 + Less |
| 14 | +- **状态管理**: Valtio (Umi Max 内置) |
| 15 | +- **表单/低代码**: Formily 2 + Designable |
| 16 | +- **地图**: Cesium.js、OpenLayers 9、高德地图 |
| 17 | +- **图表**: Ant Design Charts、D3.js |
| 18 | +- **包管理器**: pnpm |
| 19 | + |
| 20 | +## 常用命令 |
| 21 | + |
| 22 | +```bash |
| 23 | +pnpm install # 安装依赖 |
| 24 | +pnpm start # 启动开发服务器 (端口 8000) |
| 25 | +pnpm build # 生产构建 |
| 26 | +pnpm build:github # GitHub Pages 构建 |
| 27 | +pnpm preview # 构建并预览 (端口 8001) |
| 28 | +pnpm format # Prettier 格式化代码 |
| 29 | +``` |
| 30 | + |
| 31 | +## 项目结构 |
| 32 | + |
| 33 | +``` |
| 34 | +src/ |
| 35 | +├── pages/ # 页面组件（路由对应） |
| 36 | +├── components/ # 可复用组件 |
| 37 | +├── layouts/ # 布局组件 |
| 38 | +├── models/ # 全局数据模型 (hooks) |
| 39 | +├── services/ # API 服务层 |
| 40 | +├── utils/ # 工具函数 |
| 41 | +├── locales/ # 国际化文件 (zh-CN, en-US) |
| 42 | +├── constants/ # 常量定义 |
| 43 | +├── app.tsx # 应用运行时配置 |
| 44 | +└── access.ts # 权限定义 |
| 45 | +
|
| 46 | +config/ |
| 47 | +├── config.ts # Umi 主配置 |
| 48 | +├── config.github.ts # GitHub Pages 配置 |
| 49 | +└── routes.ts # 路由配置 |
| 50 | +``` |
| 51 | + |
| 52 | +## 代码规范 |
| 53 | + |
| 54 | +### 格式化 (Prettier) |
| 55 | +- 行宽: 120 字符 |
| 56 | +- 单引号 |
| 57 | +- 尾逗号: always |
| 58 | +- 自动排序导入 |
| 59 | + |
| 60 | +### ESLint 规则 |
| 61 | +- 禁止 `console.log` (允许 warn/error) |
| 62 | +- 未使用变量警告 (`_` 前缀可忽略) |
| 63 | +- 强制使用 `===` 和 `!==` |
| 64 | +- 禁止显式 `any` (警告) |
| 65 | + |
| 66 | +### 命名规范 |
| 67 | +- React 组件: PascalCase (`Home.tsx`) |
| 68 | +- 工具函数: camelCase (`format.ts`) |
| 69 | +- 组件目录: PascalCase (`FullCalendar/index.tsx`) |
| 70 | + |
| 71 | +## Git 工作流 |
| 72 | + |
| 73 | +- **pre-commit**: 自动运行 lint-staged (ESLint + Prettier) |
| 74 | +- **commit-msg**: 验证 commit 消息格式 (`max verify-commit`) |
| 75 | + |
| 76 | +## 关键配置文件 |
| 77 | + |
| 78 | +- [config/config.ts](config/config.ts) - Umi 构建配置 |
| 79 | +- [config/routes.ts](config/routes.ts) - 路由配置 |
| 80 | +- [tailwind.config.js](tailwind.config.js) - Tailwind CSS 配置 |
| 81 | +- [.prettierrc](.prettierrc) - Prettier 配置 |
| 82 | +- [.eslintrc.js](.eslintrc.js) - ESLint 配置 |
| 83 | + |
| 84 | +## 特殊说明 |
| 85 | + |
| 86 | +### Cesium 地图 |
| 87 | +- 需要设置环境变量 `CESIUM_ION_TOKEN` |
| 88 | +- Cesium 资源在构建时自动复制到 dist/Cesium/ |
| 89 | +- 全局变量 `CESIUM_BASE_URL` 指向 `/Cesium` |
| 90 | + |
| 91 | +### 国际化 |
| 92 | +- 默认语言: zh-CN |
| 93 | +- 菜单项键名前缀: `menu.` |
| 94 | +- 使用 `useIntl()` hook 获取翻译 |
| 95 | + |
| 96 | +### 权限控制 |
| 97 | +- 在 `src/access.ts` 定义权限 |
| 98 | +- 使用 `useAccess()` hook 获取权限 |
| 99 | +- 路由中通过 `access` 属性控制访问 |
| 100 | + |
| 101 | +## 部署 |
| 102 | + |
| 103 | +- **GitHub Pages**: `pnpm build:github` + GitHub Actions |
| 104 | +- **Docker**: 使用根目录 Dockerfile |
| 105 | +- **Vercel**: 支持自动部署 (vercel.json) |
0 commit comments