项目结构
以下是项目的核心目录结构及其职责说明：
tree
src/
├── api/ # API 接口管理
│ ├── system/ # 系统相关接口
│ │ ├── user/ # 用户管理接口
│ │ ├── role/ # 角色管理接口
│ │ ├── menu/ # 菜单管理接口
│ │ └── permission/ # 权限管理接口
│ └── common/ # 通用接口
│ ├── upload.ts # 文件上传接口
│ └── auth.ts # 认证相关接口
│
├── components/ # 全局通用组件
│ ├── animate/ # 动画组件
│ │ ├── index.tsx # 组件入口
│ │ ├── AnimateProvider.tsx # 动画提供者
│ │ └── types.ts # 类型定义
│ ├── table/ # 增强表格组件
│ ├── upload/ # 文件上传组件
│ ├── toast/ # 消息提示组件
│ ├── icon/ # 图标组件
│ ├── loading/ # 加载组件
│
├── configs/ # 应用配置
│ ├── theme/ # 主题配置
│ │ ├── hooks # 主题hooks，用来生成全局css var和antd的theme tokens
│ │ ├── token # antd theme token配置文件
│ └── configProvider.ts # 应用全局设置,入口组件
│
├── hooks/ # 自定义Hooks
│ ├── usePagination.ts # 分页管理Hook
│
├── layouts/ # 页面布局
│ ├── MainLayout/ # 主布局
│ │ ├── index.tsx
│ │ ├── Header.tsx
│ │ └── Sidebar.tsx
│ ├── VerticalSplit/ # 垂直分栏布局
│ │ ├── index.tsx
│ │ └── config.ts
│
├── pages/ # 页面组件
│ ├── Dashboard/ # 仪表盘页面
│ └── system/ # 系统管理
│ ├── user/ # 用户管理
│ ├── role/ # 角色管理
│ ├── menu/ # 菜单管理
│ └── permission/ # 权限管理
│
├── router/ # 路由配置
│
├── store/ # 状态管理
│ ├── systemStore.ts # 系统相关状态
│ ├── userStore.ts # 用户相关状态
│ ├── menuStore.ts # 菜单状态
│ └── themeStore.ts # 主题状态
│
├── styles/ # 全局样式
│ ├── reset.css # 样式重置
│ ├── theme.css # 主题样式
│
│
└── utils/ # 工具函数
├── auth.ts # 认证相关工具
├── http.ts # 封装axios请求
└── nprogress.ts # 进度条工具各模块说明
layouts布局
布局系统提供了5种不同的布局方式，可以根据不同的应用场景选择合适的布局：
1. Vertical (垂直菜单布局)
左侧为垂直菜单，右侧上方为header，下方为内容区域。
┌────────┬───────────────────────────┐
│ │ Header │
│ ├───────────────────────────┤
│ Menu │ │
│ │ │
│ │ Content Area │
│ │ │
│ │ │
└────────┴───────────────────────────┘- 特点：导航结构清晰，适合层级较多的菜单
- 适用场景：大型管理系统，复杂的功能层级
- 关键配置：
layout: 'vertical'
2. Horizontal (水平菜单布局)
顶部为header和水平菜单，下方为内容区域。
┌────────────────────────────────────┐
│ Header with Menu │
├────────────────────────────────────┤
│ │
│ │
│ Content Area │
│ │
│ │
└────────────────────────────────────┘- 特点：节省空间，适合菜单项较少的系统
- 适用场景：功能较为简单的系统，或移动端适配
- 关键配置：
layout: 'horizontal'
3. Mini (迷你菜单布局)
左侧为收缩的迷你菜单（只显示图标），右侧上方为header，下方为内容区域。
┌──┬─────────────────────────────────┐
│ │ Header │
│ ├─────────────────────────────────┤
│M │ │
│e │ │
│n │ Content Area │
│u │ │
│ │ │
└──┴─────────────────────────────────┘- 特点：最大化内容区域，同时保留菜单快速访问
- 适用场景：需要更多内容展示空间的应用
- 关键配置：
layout: 'mini'
4. VerticalSplit (垂直分栏布局)
左侧分为两栏：左边窄栏显示主菜单图标，右边宽栏显示子菜单列表，最右侧上方为header，下方为内容区域。
┌──┬────────┬─────────────────────────┐
│ │ │ Header │
│主│ ├─────────────────────────┤
│菜│ 子菜单 │ │
│单│ 列表 | │
│图│ │ Content Area │
│标│ │ │
│ │ │ │
└──┴────────┴─────────────────────────┘- 特点：三栏布局，主菜单和子菜单分离，导航层次清晰
- 适用场景：大型系统，需要清晰展示多级导航结构
- 关键配置：
layout: 'vertical-split'
5. VerticalSplitMini (垂直分栏迷你布局)
与垂直分栏布局类似，但中间的子菜单栏被压缩为仅显示图标状态，左边窄栏仍显示主菜单图标，最右侧上方为header，下方为内容区域。
┌──┬──┬───────────────────────────────┐
│ │ │ Header │
│主│子├───────────────────────────────┤
│菜│菜│ │
│单│单│ │
│图│图│ Content Area │
│标│标│ │
│ │ │ │
└──┴──┴───────────────────────────────┘- 特点：三栏布局的精简版，主菜单和子菜单都以图标形式显示，在保持完整导航结构的同时扩大内容区域
- 适用场景：需要更多内容展示空间，但仍需快速访问所有导航层级的系统
- 关键配置：
layout: 'vertical-split-mini'
每种布局都支持以下配置：
- 暗色主题：可设置菜单区域为暗色主题
- 菜单折叠：支持垂直菜单的折叠与展开
- 固定顶栏：支持顶部导航固定
- 主题色定制：支持通过主题系统修改布局主色调
主题系统
主题系统基于Ant Design的主题配置机制，同时扩展了更灵活的主题切换能力：
主题配置
主题配置通过configs/theme目录下的文件进行管理：
hooks：包含生成CSS变量和Ant Design主题Token的钩子函数
useTheme：处理主题状态和生成CSS变量useThemeToken：生成Ant Design组件库使用的主题Token
token：Ant Design主题Token配置
light.ts：浅色主题的配置dark.ts：深色主题的配置base.ts：基础主题配置
主题特性
- 多主题色支持：预设多种主题色，用户可一键切换
- 明暗模式切换：支持系统级别的明暗模式自动切换
- 组件级主题：可为特定组件设置独立的主题配置
- CSS变量实现：使用CSS变量实现无刷新主题切换
- 主题状态持久化：用户的主题偏好会被保存在localStorage中
自定义主题
开发者可以通过以下步骤自定义主题：
- 在
token目录中创建新的主题配置文件 - 在
themeStore中注册新主题 - 在主题选择器组件中添加新主题选项
RBAC权限系统
本项目实现了完整的基于角色的访问控制(RBAC)系统，包含以下核心功能：
权限模型
- 用户(User)：系统的使用者，与角色关联
- 角色(Role)：权限的集合，定义用户可以执行的操作
- 权限(Permission)：系统中的原子操作单元
- 菜单(Menu)：系统功能的导航入口，与权限关联
权限控制
- 路由权限：基于用户角色控制页面访问权限
- 操作权限：控制用户界面中按钮、链接等操作元素的显示
- 数据权限：控制用户可以访问的数据范围
权限组件
系统提供了多个权限控制组件：
<AuthRoute />：权限路由组件，用于控制路由访问<AuthButton />：权限按钮组件，根据权限控制按钮显示useHasPermission：权限判断Hook，用于条件渲染
权限管理界面
- 角色管理：创建、编辑和删除角色
- 权限分配：为角色分配菜单和操作权限
- 用户角色管理：为用户分配角色
组件系统
项目包含多个核心组件，用于提升开发效率和用户体验：
基础组件
- Icon：基于
@iconify/react的图标组件，支持多种图标库 - Button：扩展Ant Design的按钮组件，支持权限控制
- Form：封装常用表单控件和验证逻辑
- Table：增强表格组件，集成分页、排序和筛选功能
功能组件
- Upload：文件上传组件，支持图片预览和上传进度
- RichText：富文本编辑器，支持图片上传和格式控制
- Chart：数据可视化图表组件，基于ECharts
- Map：地图组件，支持位置选择和地理信息展示
动画组件
- AnimateProvider：动画上下文提供者，管理全局动画状态
- Transition：过渡动画组件，支持多种动画效果
- LoadingIcon：自定义加载动画，支持多种样式
布局组件
- PageContainer：页面容器组件，提供统一的页面布局
- Card：卡片组件，用于内容分组展示
- Drawer：抽屉组件，用于侧边栏表单和详情展示
API接口
API接口按照业务模块进行组织，主要包括：
系统管理API
- 用户管理：用户的CRUD操作，密码重置，状态管理
- 角色管理：角色的CRUD操作，权限分配
- 菜单管理：菜单的CRUD操作，排序和状态管理
- 权限管理：权限的CRUD操作，与菜单关联
通用API
- 上传：文件和图片上传
- 认证：登录、注销、刷新令牌
- 日志：系统日志查询
API封装
所有API请求通过utils/http.ts进行封装，提供了以下功能：
- 统一请求/响应拦截：处理认证Token、响应错误等
- 请求重试：网络错误自动重试
- 响应缓存：支持GET请求缓存
- 取消请求：支持取消进行中的请求
- 请求队列：防止重复请求
开发规范
组件命名
- PascalCase命名（如
UserAvatar.tsx） - 目录与主组件同名（如
components/UserAvatar/index.tsx）
文件结构
tree
components/
└── ComponentName/
├── index.tsx # 组件出口
├── types.ts # 类型定义
├── style.css # 组件样式
└── SubComponent/ # 子组件目录代码分割
- 路由级代码分割使用
React.lazy - 组件级分割使用动态导入
import()
提交规范
- feat: 新功能
- fix: bug修复
- docs: 文档变更
- refactor: 代码重构
- chore: 构建/工具变更