# PaxAdmin

**Repository Path**: zchty/pax-admin

## Basic Information

- **Project Name**: PaxAdmin
- **Description**: PaxAdmin 是一个基于 Vue 3.5 + Vite + Ant Design Vue 4.2.6 构建的现代化前端管理系统。该项目采用最新的前端技术栈，提供了完整的用户认证、权限管理、动态路由、数据可视化等功能，适用于企业级管理系统的快速开发。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-02-11
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <h1>Pax Admin</h1>
  <img src="./public/logo.png" alt="Pax Admin Logo" width="120">
</div>

<div align="center">

![Pax Admin](https://img.shields.io/badge/Pax%20Admin-1.0.0-blue.svg)
![Vue](https://img.shields.io/badge/Vue-3.5.13-green.svg)
![Vite](https://img.shields.io/badge/Vite-7.0.6-646CFF.svg)
![Ant Design Vue](https://img.shields.io/badge/Ant%20Design%20Vue-4.2.6-red.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

[在线演示](http://106.13.37.129:8123) | [后端项目](https://gitee.com/zchty/pax-core) | [更新日志](./CHANGELOG.md)

</div>

## 📋 目录

- [项目简介](#项目简介)
- [技术架构](#技术架构)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [核心功能](#核心功能)
- [项目特色](#项目特色)
- [API 接口](#api-接口)
- [浏览器支持](#浏览器支持)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 项目简介

Pax Admin 是一个基于 **Vue 3.5 + Vite + Ant Design Vue 4.2.6** 构建的现代化前端管理系统。该项目采用最新的前端技术栈，提供了完整的用户认证、权限管理、动态路由、数据可视化等功能，适用于企业级管理系统的快速开发。

### ✨ 主要特性

- 🚀 **最新技术栈** - 基于 Vue 3.5、Vite 7、Ant Design Vue 4 等前沿技术
- 🔐 **完善的权限系统** - 基于 Token 的认证、动态路由、角色权限控制
- 📦 **丰富的组件库** - 封装了 FormTable、IconPicker 等通用业务组件
- 🎨 **现代化 UI** - 基于 Ant Design Vue 的企业级设计体系
- 📱 **响应式设计** - 适配桌面、平板等多种设备
- 🛠️ **CLI 脚手架** - 提供项目快速生成工具，支持多种模板选择
- 📊 **数据可视化** - 集成 ECharts 图表库，支持丰富的数据展示
- 🌍 **国际化支持** - 预留国际化接口，便于多语言扩展


### 🖼️ 效果预览

<table>
  <tr>
    <td align="center">
      <img src="./src/assets/imgs/md/login.png" alt="登录页面" width="280">
      <br>登录页面
    </td>
    <td align="center">
      <img src="./src/assets/imgs/md/console.png" alt="控制台" width="280">
      <br>控制台
    </td>
    <td align="center">
      <img src="./src/assets/imgs/md/serviceMonitoring.png" alt="服务监控" width="280">
      <br>服务监控
    </td>
  </tr>
  <tr>
    <td align="center">
      <img src="./src/assets/imgs/md/statistics.png" alt="统计图表" width="280">
      <br>统计图表
    </td>
    <td align="center">
      <img src="./src/assets/imgs/md/menu.png" alt="菜单管理" width="280">
      <br>菜单管理
    </td>
  </tr>
</table>

## 技术架构

### 核心框架

| 技术 | 版本 | 说明 |
|------|------|------|
| [Vue](https://vuejs.org/) | 3.5.13 | 渐进式 JavaScript 框架，采用 Composition API 和 `<script setup>` 语法糖 |
| [Vite](https://vitejs.dev/) | 7.0.6 | 下一代前端构建工具，提供极速的开发体验 |
| [Vue Router](https://router.vuejs.org/) | 4.4.5 | 官方路由管理器，支持动态路由和路由守卫 |
| [Pinia](https://pinia.vuejs.org/) | 2.2.6 | Vue 官方推荐的状态管理方案，替代 Vuex |

### UI 框架

| 技术 | 版本 | 说明 |
|------|------|------|
| [Ant Design Vue](https://antdv.com/) | 4.2.6 | 企业级 UI 设计语言和组件库 |
| [@ant-design/icons-vue](https://github.com/ant-design/ant-design-icons) | 7.0.1 | Ant Design 官方图标库 |

### 工具库

| 技术 | 版本 | 说明 |
|------|------|------|
| [Alova](https://alova.js.org/) | 3.2.6 | 下一代请求工具，提供更强大的请求管理能力 |
| [Dayjs](https://day.js.org/) | 1.11.13 | 轻量级日期处理库，Moment.js 的替代方案 |
| [ECharts](https://echarts.apache.org/) | 6.0.0 | 开源可视化库，提供丰富的图表类型 |
| [file-saver](https://github.com/eligrey/FileSaver.js) | 2.0.5 | 文件保存工具，支持客户端文件下载 |
| [pinia-plugin-persist](https://github.com/Seb-L/pinia-plugin-persist) | 1.0.0 | Pinia 状态持久化插件 |

### 开发工具

| 工具 | 版本 | 说明 |
|------|------|------|
| [ESLint](https://eslint.org/) | 9.12.0 | 代码质量检查和规范 |
| [Prettier](https://prettier.io/) | 3.3.3 | 代码格式化工具 |
| [vite-plugin-clean](https://github.com/zjxxxxxxxxx/vite-plugin-clean) | 2.0.1 | 构建时清理旧文件插件 |

## 项目结构

```
Pax Admin/
├── bin/                     # CLI 脚手架工具
│   ├── cli.js               # 命令行入口
│   ├── generator.js         # 项目生成器
│   ├── prompts.js           # 交互式提示
│   └── utils.js             # 工具函数
├── public/                  # 静态资源（不经过构建处理）
│   └── logo.png             # 项目 Logo
├── src/                     # 源代码目录
│   ├── api/                 # API 接口层
│   │   ├── methods/         # 各模块 API 方法
│   │   │   ├── department.js    # 部门管理接口
│   │   │   ├── employee.js      # 员工管理接口
│   │   │   ├── login.js         # 登录认证接口
│   │   │   ├── sysAccount.js    # 账户管理接口
│   │   │   ├── sysDict.js       # 字典管理接口
│   │   │   ├── sysMenu.js       # 菜单管理接口
│   │   │   ├── sysRole.js       # 角色管理接口
│   │   │   └── ...              # 其他接口
│   │   └── request.js       # 请求封装配置
│   ├── assets/              # 静态资源
│   │   ├── css/             # 样式文件
│   │   │   ├── style.css        # 全局样式
│   │   │   └── zcui.css         # 自定义 UI 样式
│   │   └── imgs/            # 图片资源
│   ├── components/          # 公共组件
│   │   ├── details/         # 详情组件
│   │   ├── edit/            # 编辑组件
│   │   │   ├── organizationalStructure/  # 组织架构编辑
│   │   │   ├── SysAccountEdit.vue        # 账户编辑
│   │   │   ├── SysRoleEdit.vue           # 角色编辑
│   │   │   └── ...
│   │   ├── FormTable.vue    # 通用表格表单组件
│   │   ├── IconPicker.vue   # 图标选择器组件
│   │   └── MainPage.vue     # 主页面布局组件
│   ├── config/              # 配置文件
│   ├── directives/          # 自定义指令
│   │   └── permission.js    # 权限指令 v-permission
│   ├── router/              # 路由配置
│   │   └── index.js         # 路由入口配置
│   ├── stores/              # Pinia 状态管理
│   │   ├── config.js        # 配置状态
│   │   ├── dict.js          # 字典状态
│   │   ├── menu.js          # 菜单状态
│   │   └── user.js          # 用户状态
│   ├── utils/               # 工具函数
│   │   ├── baseEcharts.js   # ECharts 基础配置
│   │   ├── dictTemplate.js  # 字典模板工具
│   │   ├── regionUtils.js   # 区域工具函数
│   │   └── useFormCRUD.js   # 表单 CRUD 封装
│   ├── views/               # 页面视图
│   │   ├── baiscstatis/     # 基础统计页面
│   │   ├── demo/            # 示例页面
│   │   ├── operations/      # 运维管理
│   │   ├── organizationalStructure/  # 组织架构
│   │   ├── system/          # 系统管理
│   │   ├── console.vue      # 控制台
│   │   ├── home.vue         # 首页
│   │   └── login.vue        # 登录页
│   ├── App.vue              # 根组件
│   └── main.js              # 入口文件
├── templates/               # CLI 项目模板
├── .env.development         # 开发环境变量
├── .env.production          # 生产环境变量
├── .env.test                # 测试环境变量
├── eslint.config.js         # ESLint 配置
├── .prettierrc.json         # Prettier 配置
├── vite.config.js           # Vite 配置
└── package.json             # 项目依赖
```

## 核心功能

### 🔐 1. 用户认证与权限管理

- **基于 Token 的认证** - JWT Token 实现无状态认证
- **动态权限控制** - 根据用户角色动态分配权限
- **角色管理** - 支持多角色配置和权限分配
- **权限指令** - 自定义 `v-permission` 指令控制按钮级权限
- **路由守卫** - 全局路由守卫实现访问控制

### 🛣️ 2. 动态路由系统

- **后端配置路由** - 基于后端返回的菜单配置动态生成路由
- **路由懒加载** - 按需加载页面组件，优化首屏性能
- **多级菜单支持** - 支持无限层级菜单嵌套
- **路由缓存** - 支持页面缓存配置，提升切换性能
- **面包屑导航** - 自动生成面包屑导航

### 📊 3. 数据管理

- **通用 CRUD 封装** - [useFormCRUD](src/utils/useFormCRUD.js) 工具函数简化增删改查
- **表单验证** - 基于 Ant Design Vue 的表单验证机制
- **数据导入导出** - 支持 Excel 文件导入导出
- **文件上传下载** - 封装文件上传下载功能
- **分页查询** - 统一分页查询处理

### ⚙️ 4. 系统管理

| 模块 | 功能描述 |
|------|----------|
| **用户管理** | 用户增删改查、状态管理、密码重置 |
| **角色管理** | 角色配置、权限分配、角色关联用户 |
| **菜单管理** | 菜单配置、权限标识、路由配置 |
| **字典管理** | 数据字典维护、字典项管理 |
| **部门管理** | 组织架构管理、部门层级维护 |
| **职位管理** | 职位信息维护、职位关联员工 |
| **员工管理** | 员工信息管理、员工状态维护 |
| **系统监控** | 服务监控、在线用户、数据监控 |
| **日志管理** | 操作日志、登录日志、错误日志、定时任务日志 |

### 📈 5. 数据可视化

- **ECharts 图表** - 集成 ECharts 6.x，支持多种图表类型
- **统计分析页面** - 提供数据统计和分析视图
- **数据仪表盘** - 可视化数据展示面板
- **实时监控** - 服务状态实时监控展示

## 快速开始

### 环境要求

在开始之前，请确保您的环境满足以下要求：

| 环境 | 版本要求 | 说明 |
|------|----------|------|
| Node.js | >= 16.0.0 | 推荐使用 LTS 版本 |
| npm | >= 7.0.0 | 或 yarn、pnpm |
| 浏览器 | 现代浏览器 | Chrome、Firefox、Edge、Safari 最新版 |

### 安装 CLI 脚手架（推荐）

```bash
# 使用 npx 快速创建项目（推荐，无需全局安装）
npx Pax Admin create my-project

# 或者全局安装后使用
npm install -g Pax Admin
Pax Admin create my-project

# 进入项目目录
cd my-project

# 启动开发服务器
npm run dev
```

更多脚手架使用说明请参考 [CLI 脚手架工具](#cli-脚手架工具) 章节。

### CLI 脚手架工具

Pax Admin 提供了功能强大的 CLI 脚手架工具，帮助您快速创建项目。

#### 全局安装

```bash
npm install -g Pax Admin
```

#### 可用命令

| 命令 | 说明 | 示例 |
|------|------|------|
| `create <project-name>` | 创建新项目 | `Pax Admin create my-project` |
| `list-templates` | 查看可用模板 | `Pax Admin list-templates` |
| `--help` | 查看帮助信息 | `Pax Admin --help` |
| `--version` | 查看版本号 | `Pax Admin --version` |

#### 创建项目选项

```bash
Pax Admin create <project-name> [options]

Options:
  -t, --template <template>      选择项目模板 (default: "default")
  -d, --description <desc>       项目描述
  -a, --author <author>          作者名称
  --skip-install                 跳过依赖安装
  --no-interactive               禁用交互式模式
```

#### 项目模板

| 模板名称 | 说明 |
|----------|------|
| `default` | 默认模板，包含完整的管理系统功能 |
| `basic` | 基础模板，仅包含核心功能，适合高度自定义 |
| `full` | 完整模板，包含所有示例页面和高级功能 |

#### 交互式创建示例

```bash
$ Pax Admin create my-project --interactive

? 请输入项目描述: 我的管理系统
? 请输入作者名称: zc
? 请选择项目模板: default
? 请选择功能特性: (Press <space> to select)
❯◉ 用户管理模块
 ◉ 权限管理模块
 ◉ 数据可视化图表
 ◯ 文件上传功能
 ◯ 国际化支持
? 是否跳过依赖安装? (y/N) N

✔ 项目创建成功！
✔ 依赖安装完成！

cd my-project
npm run dev
```

### 手动克隆项目

```bash
# 克隆项目
git clone https://gitee.com/your-username/Pax Admin.git

# 进入项目目录
cd Pax Admin

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

### 常用命令

```bash
# 启动开发服务器（默认端口 8080）
npm run dev

# 构建生产版本（输出到 dist 目录）
npm run build

# 预览生产构建
npm run preview

# 代码检查并自动修复
npm run lint

# 代码格式化
npm run format
```

### 环境配置

项目支持多环境配置，通过 `.env` 文件管理不同环境的变量：

| 文件 | 说明 |
|------|------|
| `.env.development` | 开发环境配置 |
| `.env.test` | 测试环境配置 |
| `.env.production` | 生产环境配置 |

### 开发规范

#### Vue 组件规范

1. 使用 Composition API (`<script setup>`) 语法糖
2. 组件命名使用 PascalCase (大驼峰命名法)
3. 组件文件扩展名统一使用 `.vue`
4. 使用 `scoped` 样式避免全局污染

#### JavaScript 规范

1. 使用 ES6+ 语法
2. 使用 `import/export` 模块化导入导出
3. 变量声明优先使用 `const`，其次使用 `let`，避免使用 `var`
4. 使用箭头函数简化代码

#### CSS 规范

1. CSS 类名使用 kebab-case (短横线命名法)
2. 组件样式使用 `scoped` 避免全局污染

#### 代码提交规范

1. 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范
2. 提交前确保通过 ESLint 检查

```bash
# 示例
feat: 添加用户管理功能
fix: 修复登录页面样式问题
docs: 更新 README 文档
style: 格式化代码
refactor: 重构权限控制逻辑
```

## 项目特色

### 🧩 1. 模块化设计

项目采用高度模块化的设计，各功能模块相互独立，便于维护和扩展：
- 清晰的目录结构，职责分离
- 组件化开发，提高复用性
- 模块间低耦合，易于扩展

### 🧰 2. 通用组件封装

提供了丰富的通用业务组件，提高开发效率：

| 组件 | 路径 | 说明 |
|------|------|------|
| **FormTable** | [src/components/FormTable.vue](src/components/FormTable.vue) | 通用表格表单组件，支持搜索、分页、操作 |
| **IconPicker** | [src/components/IconPicker.vue](src/components/IconPicker.vue) | 图标选择器组件，集成 Ant Design 图标 |
| **MainPage** | [src/components/MainPage.vue](src/components/MainPage.vue) | 主页面布局组件，统一页面结构 |
| **DepartmentEdit** | [src/components/edit/...](src/components/edit/organizationalStructure/DepartmentEdit.vue) | 部门编辑弹窗组件 |
| **SysRoleEdit** | [src/components/edit/...](src/components/edit/SysRoleEdit.vue) | 角色编辑弹窗组件 |

### 🛠️ 3. 工具函数库

封装了常用的工具函数，简化业务逻辑开发：

| 工具 | 路径 | 说明 |
|------|------|------|
| **useFormCRUD** | [src/utils/useFormCRUD.js](src/utils/useFormCRUD.js) | 表单增删改查操作封装 |
| **regionUtils** | [src/utils/regionUtils.js](src/utils/regionUtils.js) | 省市区数据工具函数 |
| **dictTemplate** | [src/utils/dictTemplate.js](src/utils/dictTemplate.js) | 字典数据模板工具 |
| **baseEcharts** | [src/utils/baseEcharts.js](src/utils/baseEcharts.js) | ECharts 基础配置 |

### 📱 4. 响应式设计

基于 Ant Design Vue 的响应式设计，适配不同屏幕尺寸的设备：
- 自适应布局，支持桌面、平板、手机
- 侧边栏可折叠，优化小屏体验
- 表格、表单的响应式适配

### 🌍 5. 国际化支持

预留了国际化接口，便于后续多语言扩展：
- 基于 Vue I18n 的国际化方案
- 语言包结构清晰，易于维护
- 支持动态切换语言

### 🚀 6. 性能优化

- **路由懒加载** - 按需加载页面组件
- **组件按需引入** - 减少打包体积
- **Pinia 持久化** - 状态数据本地存储
- **Vite 构建优化** - 快速的开发和构建体验

## API 接口

项目采用模块化方式组织 API 接口，位于 `src/api/methods/` 目录下：

### 接口模块

| 模块 | 文件 | 说明 |
|------|------|------|
| **登录认证** | `login.js` | 登录、登出、获取用户信息 |
| **账户管理** | `sysAccount.js` | 账户增删改查、密码管理 |
| **角色管理** | `sysRole.js` | 角色增删改查、权限分配 |
| **菜单管理** | `sysMenu.js` | 菜单增删改查、路由配置 |
| **字典管理** | `sysDict.js` / `sysDictItem.js` | 字典类型和字典项管理 |
| **部门管理** | `department.js` | 部门组织架构管理 |
| **职位管理** | `position.js` | 职位信息管理 |
| **员工管理** | `employee.js` | 员工信息管理 |
| **日志管理** | `logOperation.js` / `logError.js` / `logLogin.js` | 操作日志、错误日志、登录日志 |
| **定时任务** | `quartz.js` | 定时任务管理 |
| **区域数据** | `region.js` | 省市区数据获取 |

### 请求封装

请求核心配置位于 [src/api/request.js](src/api/request.js)，基于 Alova 实现：

```javascript
// 示例：使用封装好的请求方法
import { getUserList, addUser, updateUser, deleteUser } from '@/api/methods/sysUser.js'

// 获取用户列表
const { data } = await getUserList({ page: 1, size: 10 })

// 添加用户
await addUser({ username: 'admin', nickname: '管理员' })
```

## 浏览器支持

| 浏览器 | 版本要求 |
|--------|----------|
| Chrome | >= 80 |
| Firefox | >= 75 |
| Safari | >= 13 |
| Edge | >= 80 |

> 不支持 IE 浏览器

## 部署说明

### 构建生产版本

```bash
# 执行构建命令
npm run build

# 构建输出位于 dist/ 目录
```

### 部署方式

#### 方式一：静态服务器部署

将 `dist` 目录下的文件部署到任意静态 Web 服务器：

```bash
# 使用 nginx 示例
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://your-backend-server;
    }
}
```

#### 方式二：Docker 部署

```dockerfile
FROM nginx:alpine
COPY dist/ /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
```

### 环境变量配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `VITE_APP_BASE_API` | API 基础路径 | `/api` |
| `VITE_APP_TITLE` | 应用标题 | `Pax Admin` |
| `VITE_APP_PORT` | 开发服务器端口 | `8080` |


## 贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目！

### 提交 Issue

- 描述清楚问题的复现步骤
- 提供相关的代码片段或错误截图
- 标注使用的版本号和环境信息

### 提交 Pull Request

1. Fork 本项目到您的仓库
2. 创建特性分支：`git checkout -b feature/AmazingFeature`
3. 提交更改：`git commit -m 'feat: Add some AmazingFeature'`
4. 推送到分支：`git push origin feature/AmazingFeature`
5. 提交 Pull Request 到主仓库

### 开发注意事项

- 确保代码通过 ESLint 检查：`npm run lint`
- 保持代码风格一致
- 提交信息遵循 Conventional Commits 规范
- 更新相关文档（如有必要）

## 许可证

本项目采用 [MIT](LICENSE) 许可证开源。

```
MIT License

Copyright (c) 2024 zc

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

<div align="center">

**如果觉得这个项目对您有帮助，请给个 Star ⭐**

[返回顶部](#目录)

</div>