# one-admin-react

**Repository Path**: maoxiaojiu9/one-admin-react

## Basic Information

- **Project Name**: one-admin-react
- **Description**: OneAdmin通用管理系统，基于 React 19 +Vite 8+ TypeScript+ React Router 7+ Zustand + Ant Design 6 的后台管理系统脚手架。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, TypeScript, Ant-Design

## README

# One Admin 管理系统

# 一、项目简介

One Admin 是一套基于 React 19 + TypeScript + Vite 构建的企业级后台管理系统脚手架，采用 Ant Design 6 作为 UI 组件库，使用 antd-style 进行 CSS-in-JS 样式编写，Zustand 进行轻量级状态管理，React Router 7 管理路由，Axios 处理 HTTP 请求，并内置 MockJS 数据模拟能力。

## 技术栈

| 分类 | 技术 | 说明 |
| --- | --- | --- |
| 核心框架 | React 19 | 函数组件 + Hooks |
| 开发语言 | TypeScript 6 | 全量类型注解 |
| 构建工具 | Vite 8 | 极速冷启动 + HMR |
| UI 组件库 | Ant Design 6 | 企业级 UI 组件 |
| 样式方案 | antd-style | createStyles CSS-in-JS，支持主题 token |
| 路由管理 | React Router DOM 7 | 懒加载 + 路由守卫 |
| 状态管理 | Zustand | useXxxStore 组合式风格 |
| HTTP 请求 | Axios | 统一请求封装 |
| 数据模拟 | MockJS + vite-plugin-mock | 开发环境接口模拟 |
| 代码规范 | ESLint + Prettier + Stylelint | JS/TS/CSS/LESS 统一规范 |
| Git 规范 | Husky + lint-staged + commitlint | 提交校验 + 约定式提交 |
| 拖拽引擎 | dnd-kit | 页面设计器拖拽排序 |
| 代码编辑器 | Monaco Editor | 模板编辑、代码预览 |
| 代码高亮 | Shiki | 轻量级语法高亮 |
| 全屏组件 | screenfull | 全屏切换 |
| 滚动条 | simplebar-react | 自定义滚动条 |

# 二、安装与启动

## 环境要求

- Node.js >= 18
- 包管理器：npm / pnpm / yarn 任选其一（以下以 npm 为例）

## 安装依赖

```bash
npm install
```

## 启动开发服务器

```bash
npm run dev
```

启动后默认自动打开浏览器，访问地址以 Vite 配置为准（通常为 http://localhost:5173）。

## 构建生产包

```bash
npm run build
```

构建产物输出至 `dist/` 目录。

## 预览生产构建

```bash
npm run preview
```

## 其他脚本

| 命令 | 说明 |
| --- | --- |
| `npm run lint` | 执行 ESLint 检查 |
| `npm run lint:fix` | 自动修复 ESLint 问题 |
| `npm run format` | 使用 Prettier 格式化代码 |
| `npm run lint:style` | 执行 Stylelint 检查 |
| `npm run lint:style:fix` | 自动修复 Stylelint 问题 |

## 环境变量

项目通过 `.env.*` 文件区分多环境配置：

| 文件 | 说明 |
| --- | --- |
| `.env` | 通用配置 |
| `.env.development` | 开发环境（API 基础路径、日志开关、Mock 开关） |
| `.env.staging` | 预发布环境 |
| `.env.production` | 生产环境 |
| `.env.test` | 测试环境 |

主要变量：

- `VITE_API_BASE_URL`：接口基础路径
- `VITE_ENABLE_LOGGING`：是否开启日志
- `VITE_ENABLE_MOCK`：是否启用 Mock 数据

# 三、功能特性

## 3.1 业务模块

| 模块 | 路由 | 功能说明 |
| --- | --- | --- |
| 登录 | `/login` | 科技风登录页，左侧 antd 登录表单 + 右侧运维机器人场景（雷达扫描、状态徽章、指标卡片），复用异常页视觉框架 |
| 仪表盘 | `/dashboard` | 首页数据看板：核心指标统计卡、系统监控机器人场景、访问趋势柱状图、用户角色占比饼图、近期访问记录列表 |
| 用户管理 | `/system/user` | 用户 CRUD、部门树过滤（按 deptId 精确匹配）、角色分配弹窗 |
| 角色管理 | `/system/role` | 角色 CRUD、资源权限分配弹窗（菜单/按钮权限树） |
| 资源管理 | `/system/resource` | 菜单与权限资源维护，支持图标选择器、外链/内嵌配置 |
| 部门管理 | `/system/dept` | 部门树形 CRUD |
| 字典管理 | `/system/dict` | 字典类型与字典数据维护 |
| 通知公告 | `/system/notice` | 通知列表、新增、编辑、详情页（富文本编辑） |
| 操作日志 | `/system/operationLog` | 操作日志查询、详情抽屉 |
| 登录日志 | `/system/loginLog` | 登录日志查询、详情抽屉 |
| 在线用户 | `/monitor/online-user` | 在线用户查询、批量强制下线 |
| 缓存监控 | `/monitor/cache-monitor` | Redis 缓存信息概览、键值列表、缓存详情 |
| 服务器监控 | `/monitor/server-monitor` | 服务器 CPU 仪表盘、磁盘信息表格等 |
| 数据源管理 | `/generator/data-source` | 代码生成数据源 CRUD、连接测试 |
| 代码生成表 | `/generator/table` | 导入数据库表、代码生成配置、预览、下载 |
| 生成任务 | `/generator/task` | 代码生成任务列表、执行、下载 |
| 模板管理 | `/generator/template` | 代码模板 CRUD、模板内容编辑（Monaco） |
| 模板分组 | `/generator/template-group` | 模板分组 CRUD、分组下模板配置 |
| 模板管理器 | `/generator/template-manager` | 模板管理入口页 |
| 页面设计器 | `/generator/designer` | 可视化拖拽页面设计器，三栏布局（物料/画布/属性），28 种物料组件，大纲树拖拽增删复制，实时预览，一键出码 |
| 异常页 | `/error/*` | 403 禁止访问、404 未找到、500 服务器错误，统一科技风视觉 |

## 3.2 布局与导航

| 能力 | 说明 |
| --- | --- |
| 侧边栏菜单 | 根据用户权限动态渲染，支持折叠/展开、手风琴模式、亮色/深色菜单切换 |
| 顶栏 | sticky 定位，含折叠按钮、面包屑导航、用户信息 |
| 多标签页 | KeepAlive 缓存路由出口，标签持久化到 localStorage，展示菜单名称 |
| 面包屑 | 根据当前路由层级自动生成 |
| 系统设置弹窗 | 外观主题、主题色、圆角、字号、语言、侧边栏深色菜单等偏好，实时生效并持久化 |
| 通知中心 | 顶栏铃铛 + 通知抽屉 |
| 全屏切换 | 基于 screenfull 的全屏模式 |
| 外链/内嵌 | 外链重定向组件、Iframe 内嵌页面 |
| 语言切换 | 顶栏语言切换组件 |

## 3.3 主题系统

| 能力 | 说明 |
| --- | --- |
| 外观主题 | 亮色 / 暗色外观切换，带过渡动画 |
| 主题色 | 8 种预设主题色（拂晓蓝、草绿、日暮、薄暮、酱紫、明青、法式洋红、日橘） |
| 全局圆角 | 滑块调节全局圆角大小 |
| 全局字号 | 滑块调节全局字体大小 |
| 图表主题联动 | echarts 主题色由 antd token 派生，随外观主题联动切换 |
| 主题持久化 | 通过 zustand persist 持久化至 localStorage，支持版本迁移 |

## 3.4 权限与路由

| 能力 | 说明 |
| --- | --- |
| 路由守卫 | AuthGuard 鉴权守卫，未登录跳登录页 |
| 动态路由 | 根据用户菜单权限动态生成路由表 |
| 懒加载 | 路由组件按需加载 |
| 业务码跳转 | 响应体业务码 401 → 登录页（硬跳转重置状态），403 → 后台布局下 403 页面（SPA 内部导航，保留状态） |
| 菜单权限 | 侧边栏菜单根据资源权限过滤渲染 |
| 按钮权限 | `<Access>` 组件 + `hasPermission` 工具函数，按权限标识控制按钮/元素显隐；登录时通过 `/auth/getUserAllInfo` 聚合接口获取 permissions |

## 3.5 状态管理（Zustand）

| Store | 说明 |
| --- | --- |
| useAuthStore | 认证状态：token、用户信息、菜单树 |
| useSettingsStore | 系统设置状态：外观、主题色、圆角、字号、侧边栏、语言等，persist 持久化 |
| useTabStore | 多标签页状态：标签列表、激活标签，persist 持久化 |
| useDesignerStore | 页面设计器状态：组件树、选中节点、拖拽状态、历史记录 |

## 3.6 通用组件

| 组件 | 说明 |
| --- | --- |
| charts | 基于 echarts 封装的 BaseChart / LineChart / BarChart / PieChart，主题联动 |
| tiptap-editor | TipTap 富文本编辑器，含工具栏、颜色、图片、链接、任务列表、文本对齐等扩展 |
| icon | 图标选择器（IconPicker / IconPickerPopover）、字体图标（IconFont）、应用图标（AppIcon） |
| skeleton | 骨架屏组件：SkeletonFormItem、PageSkeleton |
| loading | 通用加载态 Loading |
| scrollbar | 自定义滚动条 Scrollbar（基于 simplebar-react） |
| table-toolbar | 表格工具栏 TableToolbar |
| access | 权限控制组件 `<Access>`，按权限标识条件渲染；`hasPermission` 工具函数用于按钮数组过滤 |
| code-editor | 代码编辑器 CodeEditor（Monaco，按需加载，主题跟随系统）+ 代码高亮 CodeHighlight（Shiki 轻量高亮） |
| slider-captcha | 滑块验证码组件，用于登录页人机验证 |
| robot | 运维机器人场景组件，用于登录页/仪表盘/异常页视觉装饰 |

## 3.7 工程能力

| 能力 | 说明 |
| --- | --- |
| HTTP 请求 | Axios 统一封装，拦截器处理 token、业务码跳转、错误提示 |
| Mock 数据 | vite-plugin-mock 开发环境接口模拟，覆盖认证、用户、角色、部门、资源、仪表盘、在线用户等模块 |
| 国际化 | 简体中文 / English 语言包，按 locale 切换 |
| 代码规范 | ESLint + Prettier + Stylelint 统一规范 |
| Git 规范 | Husky + lint-staged + commitlint 约定式提交校验 |
| 环境变量 | `.env` / `.env.development` / `.env.staging` / `.env.production` / `.env.test` 多环境配置 |
| 日志工具 | 可按环境开关的日志工具 |

## 3.8 代码生成模块

| 能力 | 说明 |
| --- | --- |
| 数据源管理 | 支持配置多个数据库数据源，连接测试，为代码生成提供数据源选择 |
| 表导入与配置 | 导入数据库表，配置生成选项（包名、模块名、作者、模板等），支持单表/批量生成 |
| 代码预览与下载 | 在线预览生成的代码（多文件 Tab 切换），支持打包下载 |
| 模板管理 | 自定义代码模板，Monaco Editor 编辑模板内容，支持变量占位符 |
| 模板分组 | 模板分组管理，一个分组关联多个模板，便于按场景批量应用 |
| 生成任务 | 代码生成任务记录，支持重新生成、下载历史产物 |

## 3.9 页面可视化设计器

| 能力 | 说明 |
| --- | --- |
| 三栏布局 | 左侧物料面板（28 种组件）、中间画布（拖拽设计）、右侧属性面板（组件配置） |
| 拖拽编排 | 基于 dnd-kit，物料拖入画布、画布内拖拽排序、容器嵌套拖拽 |
| 物料组件 | 28 种：Container/Row/Col/Form/FormItem/Card/Tabs/Table/Descriptions/Statistic/Divider/Space/Alert/Badge/Tag/Empty/Text/Input/Password/Textarea/InputNumber/Select/Switch/Checkbox/Radio/DatePicker/Button |
| 大纲树 | 组件树大纲，支持拖拽排序、新增子节点（Popover 气泡卡片 + Segmented 分类）、删除、复制（含全部子节点） |
| 属性面板 | 通用属性（字段名、标签）、样式属性（宽高/内外边距/对齐/背景色等）、组件特有属性 |
| 实时预览 | 预览模式复用设计态 DOM 结构，禁用拖拽，所见即所得 |
| 一键出码 | 根据组件树生成 React + Antd 源码，2 空格缩进，支持复制和下载 |
| 画布交互 | 网格背景、hover 高亮不穿透、hover 显示组件名、选中高亮可删除 |

# 四、目录结构

```text
one-admin-react/
├── public/                          # 静态资源（不经过构建处理）
├── src/                             # 源码目录
│   ├── api/                         # 接口请求层（按业务模块组织）
│   ├── assets/                      # 静态资源（会被构建处理）
│   ├── components/                  # 全局通用组件（access/charts/code-editor/icon/loading/robot/scrollbar/skeleton/slider-captcha/table-toolbar/tiptap-editor）
│   ├── constants/                   # 全局常量（布局、主题）
│   ├── hooks/                       # 自定义 Hooks（useAuth、useFullscreen）
│   ├── layouts/                     # 布局层（BasicLayout + 顶栏/侧边栏/内容/多标签页/设置弹窗等子组件）
│   ├── locales/                     # 国际化资源（zh-CN、en-US）
│   ├── mock/                        # 接口 Mock 数据
│   ├── pages/                       # 页面视图（dashboard/errors/generator/login/monitor/system）
│   ├── router/                      # 路由层（guards 守卫、modules 动态/静态路由、懒加载）
│   ├── store/                       # Zustand 状态管理（useAuthStore/useDesignerStore/useSettingsStore/useTabStore）
│   ├── types/                       # 全局类型定义
│   ├── utils/                       # 工具函数（auth、logger、menu、request、storage）
│   ├── App.tsx                      # 应用根组件
│   └── main.tsx                     # 应用入口
├── .env.*                           # 多环境变量配置
├── eslint.config.js                 # ESLint 配置
├── stylelint.config.js              # Stylelint 配置
├── commitlint.config.cjs            # commitlint 配置
├── index.html                       # HTML 入口模板
├── package.json                     # 项目依赖与脚本
├── tsconfig*.json                   # TypeScript 配置
└── vite.config.ts                   # Vite 构建配置
```



# 五、演示

## 5.1 登录页

![登录页面-明亮](doc/images/登录页面-明亮.png)

![登录页面-暗黑](doc/images/登录页面-暗黑.png)

![代码生成-表管理](doc/images/登录页面-明亮-验证码.png)

## 5.2 仪表盘

![仪表盘](doc/images/仪表盘.png)

## 5.3 主题设置

![主题设置](doc/images/主题设置.png)

## 5.4 系统管理

![系统管理-用户管理](doc/images/系统管理-用户管理.png)

![系统管理-部门管理](doc/images/系统管理-部门管理.png)

![系统管理-资源管理](doc/images/系统管理-资源管理.png)

![系统管理-通知公告](doc/images/系统管理-通知公告.png)

![系统管理-数据字典](doc/images/系统管理-数据字典.png)

![系统管理-日志管理](doc/images/系统管理-日志管理.png)

## 5.5 系统监控

![系统监控-在线用户](doc/images/系统监控-在线用户.png)

![系统监控-服务监控](doc/images/系统监控-服务监控.png)

## 5.6 代码生成

![代码生成-表管理](doc/images/代码生成-模板管理.png)

![代码生成-表管理](doc/images/代码生成-业务表管理1.png)

![代码生成-表管理](doc/images/代码生成-业务表管理2.png)

![代码生成-页面设计器](doc/images/代码生成-页面设计器.png)

## 5.7 异常页面

![异常页面-403](doc/images/异常页面-403.png)

![异常页面-404](doc/images/异常页面-404.png)

![异常页面-500](doc/images/异常页面-500.png)

## 5.8 外部链接与内嵌链接

![外部链接-内嵌链接](doc/images/外部链接-内嵌链接.png)