# easy-admin

**Repository Path**: LiCcccc1124-java/easy-admin

## Basic Information

- **Project Name**: easy-admin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-10-28
- **Last Updated**: 2025-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy Admin 后台管理系统

基于 Vue 3 + Element Plus 的简易后台管理系统，对接 Spring Boot 后端 API，提供丰富的业务组件。

后端项目地址：https://gitee.com/Love_Noah_chen/easy-back

## 技术栈

- **框架**: Vue 3.4
- **UI 组件库**: Element Plus 2.5
- **状态管理**: Pinia 2.1
- **路由**: Vue Router 4.2
- **HTTP 客户端**: Axios 1.6
- **构建工具**: Vite 5.0
- **图标**: @element-plus/icons-vue
- **进度条**: nprogress
- **Cookie管理**: js-cookie

## 功能模块

### ✅ 已实现功能

1. **用户认证**
   - 用户名密码登录
   - Sa-Token 认证
   - 自动 Token 刷新
   - 路由守卫和权限控制

2. **菜单管理**
   
   - 菜单树展示
   - 新增/编辑/删除菜单
- 菜单权限关联
  
3. **部门管理**
   - 部门树展示
   - 新增/编辑/删除部门
   - 级联删除
   - 启用/停用部门

4. **角色管理**
   - 角色列表（分页）
   - 新增/编辑/删除角色
   - 角色状态管理

5. **用户管理**
   - 用户列表（分页）
   - 新增/编辑/删除用户
   - 用户角色分配
   - 用户状态管理

6. **权限管理**
   - 菜单权限
   - 按钮权限
   - 权限指令 `v-permission`

7. **系统配置**
   - 系统参数配置
   - 字典管理
   - 枚举管理

8. **个人中心**
   - 个人信息修改
   - 头像上传
   - 密码修改

9. **文件管理**
   - 文件上传（单文件/多文件）
   - 批量模式（流水号）
   - 图片预览
   - 文件下载

10. **系统布局**
    - 动态菜单加载
    
    - 侧边栏菜单
    
    - 顶部导航栏
    
    - 面包屑导航
    
    - 响应式布局
    
    - 俄罗斯方块登录背景动画
    
## 页面截图

![image-20251021222956505](docs/images/image-20251021222956505.png)

![image-20251021223154894](docs/images/image-20251021223154894.png)

![image-20251021223215713](docs/images/image-20251021223215713.png)

![image-20251021223247031](docs/images/image-20251021223247031.png)

## 项目结构

```
easy-admin/
├── public/              # 静态资源
├── src/
│   ├── api/            # API 接口封装
│   │   ├── login.js    # 登录接口
│   │   ├── menu.js     # 菜单接口
│   │   ├── dept.js     # 部门接口
│   │   ├── role.js     # 角色接口
│   │   └── file.js     # 文件接口
│   ├── assets/         # 资源文件
│   ├── components/     # 业务组件
│   │   ├── PageTable.vue       # 分页表格组件
│   │   ├── DictSelect.vue      # 字典选择器
│   │   ├── EnumSelect.vue      # 枚举选择器
│   │   ├── FileUpload.vue      # 文件上传
│   │   ├── ImageUpload.vue     # 图片上传
│   │   ├── ImageCell.vue       # 图片单元格
│   │   ├── IconPicker.vue      # 图标选择器
│   │   ├── PaginationSelect.vue # 分页选择器
│   │   ├── MenuTree.vue        # 菜单树
│   │   ├── DeptTree.vue        # 部门树
│   │   └── RectLoading.vue     # 加载动画
│   ├── layout/         # 布局组件
│   │   ├── index.vue   # 主布局
│   │   └── components/ # 布局子组件
│   ├── router/         # 路由配置
│   │   └── index.js    # 路由主文件
│   ├── stores/         # Pinia 状态管理
│   │   └── user.js     # 用户状态
│   ├── styles/         # 全局样式
│   │   └── index.scss  # 主样式文件
│   ├── utils/          # 工具函数
│   │   ├── request.js  # Axios 封装
│   │   └── auth.js     # 认证工具
│   ├── views/          # 页面组件
│   │   ├── login/      # 登录页
│   │   ├── dashboard/  # 首页
│   │   ├── system/     # 系统管理
│   │   │   ├── menu/   # 菜单管理
│   │   │   ├── dept/   # 部门管理
│   │   │   └── role/   # 角色管理
│   │   └── error/      # 错误页面
│   ├── App.vue         # 根组件
│   └── main.js         # 入口文件
├── index.html          # HTML 模板
├── vite.config.js      # Vite 配置
├── package.json        # 依赖配置
└── README.md          # 项目说明
```

## 开始使用

### 环境要求

- Node.js >= 16.0.0
- npm >= 8.0.0 或 pnpm >= 7.0.0

### 安装依赖

```bash
# 进入前端项目目录
cd easy-admin

# 使用 npm
npm install

# 或使用 pnpm（推荐）
pnpm install

# 或使用 yarn
yarn install
```

### 开发环境运行

```bash
npm run dev
# 或
pnpm dev
# 或
yarn dev
```

访问: http://localhost:3000

### 生产环境构建

```bash
npm run build
# 或
pnpm build
# 或
yarn build
```

构建产物在 `dist` 目录。

### 预览生产构建

```bash
npm run preview
# 或
pnpm preview
# 或
yarn preview
```

## API 配置

后端 API 地址配置在 `vite.config.js` 中的代理设置：

```javascript
server: {
  port: 3000,
  proxy: {
    '/api': {
      target: 'http://localhost:8080',  // 后端服务地址
      changeOrigin: true
    }
  }
}
```

## API 接口说明

### 后端接口地址

所有接口都通过 `/api/v1/` 前缀访问。

#### 认证相关
- **POST** `/api/v1/login` - 用户登录
  - 请求体: `{ username, password, loginType }`
  - 响应: `{ token, userInfo }`
- **GET** `/api/v1/logout` - 用户登出

#### 菜单管理
- **PUT** `/api/v1/menu/add` - 新增菜单
- **POST** `/api/v1/menu/modify` - 修改菜单
- **DELETE** `/api/v1/menu/delete/{menuId}` - 删除菜单
- **GET** `/api/v1/menu/tree` - 获取完整菜单树
- **GET** `/api/v1/menu/info/{menuId}` - 获取菜单详情
- **GET** `/api/v1/menu/current-user-tree` - 获取当前用户菜单树
- **GET** `/api/v1/menu/current-user-permissions` - 获取当前用户权限列表

#### 部门管理
- **PUT** `/api/v1/dept/add` - 新增部门
- **POST** `/api/v1/dept/modify` - 修改部门
- **DELETE** `/api/v1/dept/delete/{deptId}` - 删除部门
- **POST** `/api/v1/dept/disable/{deptId}` - 停用部门
- **POST** `/api/v1/dept/enable/{deptId}` - 启用部门
- **POST** `/api/v1/dept/page` - 部门分页列表
- **GET** `/api/v1/dept/tree` - 部门树
- **GET** `/api/v1/dept/info/{deptId}` - 部门详情

#### 角色管理
- **PUT** `/api/v1/role/add` - 新增角色
- **POST** `/api/v1/role/modify` - 修改角色
- **DELETE** `/api/v1/role/delete/{roleId}` - 删除角色
- **POST** `/api/v1/role/page` - 角色分页列表
- **GET** `/api/v1/role/info/{roleId}` - 角色详情

#### 用户管理
- **PUT** `/api/v1/user/add` - 新增用户
- **POST** `/api/v1/user/modify` - 修改用户
- **DELETE** `/api/v1/user/delete/{userId}` - 删除用户
- **POST** `/api/v1/user/page` - 用户分页列表
- **GET** `/api/v1/user/info/{userId}` - 用户详情

#### 个人中心
- **GET** `/api/v1/profile/info` - 获取当前用户信息
- **POST** `/api/v1/profile/update` - 更新个人信息
- **POST** `/api/v1/profile/updatePassword` - 修改密码

#### 文件管理
- **POST** `/api/v1/file/upload` - 上传文件
  - 支持单文件和多文件上传
  - 支持批量模式（返回流水号）
- **GET** `/api/v1/file/download/{fileId}` - 下载文件
- **GET** `/api/v1/file/preview/{fileId}` - 预览文件（需认证）
- **GET** `/api/v1/file/info/{fileId}` - 获取文件信息
- **GET** `/api/v1/file/list/batch/{fileSerial}` - 通过流水号获取文件列表
- **GET** `/api/v1/file/download/batch/{fileSerial}` - 批量下载（ZIP）

#### 系统配置
- **GET** `/api/v1/system/config/getSystemName` - 获取系统名称
- **GET** `/api/v1/system/config/getByKey/{key}` - 根据键获取配置值
- **POST** `/api/v1/system/config/page` - 配置分页列表
- **POST** `/api/v1/system/config/modify` - 修改配置

#### 字典管理
- **GET** `/api/v1/dict/list/{dictCode}` - 获取字典项列表
- **POST** `/api/v1/dict/page` - 字典分页列表

#### 枚举管理
- **GET** `/api/v1/enum/options/{enumName}` - 获取枚举选项列表

## 默认账号

系统会在首次启动时自动初始化默认管理员账号：
- 用户名: `admin`
- 密码: `123456`

**注意**: 请在生产环境中及时修改默认密码！

## 开发说明

### 新增页面

1. 在 `src/views/` 下创建对应的 Vue 组件
3. 在 `src/api/` 中添加对应的 API 接口

### 自动导入

项目使用了 `unplugin-auto-import` 和 `unplugin-vue-components`：

- Vue API（ref, reactive, computed 等）无需手动导入
- Element Plus 组件按需自动导入
- Vue Router API 自动导入

### 样式规范

- 使用 SCSS 预处理器
- 采用 BEM 命名规范
- 全局样式定义在 `src/styles/index.scss`

## 浏览器支持

- Chrome >= 87
- Firefox >= 78
- Safari >= 14
- Edge >= 88

## 注意事项

1. **Token 存储**: Token 存储在 Cookie 中，键名为 `Admin-Token`
2. **请求拦截**: 所有请求自动携带 Token（请求头 `authorize-token: Bearer {token}`）
3. **响应拦截**: 
   - 自动处理 401/40100 错误，跳转到登录页
   - 业务错误（code !== 20000）统一处理
4. **路由守卫**: 
   - 未登录用户自动重定向到登录页
   - 动态加载菜单路由
   - 首次访问自动跳转到第一个菜单
5. **权限控制**:
   - 按钮级权限使用 `v-permission` 指令
   - 支持 `v-permission="'add'"` 单个权限
   - 支持 `v-permission="['add','edit']"` 多个权限（任一）
   - 支持 `v-permission.and="['add','edit']"` 多个权限（全部）

## 业务组件使用说明

### 1. PageTable 分页表格组件

功能强大的分页表格组件，支持搜索、工具栏、自动高度等特性。

**基础用法：**

```vue
<template>
  <PageTable
    :data="tableData"
    :loading="loading"
    :pagination="pagination"
    @update:pagination="pagination = $event"
    @refresh="loadData"
  >
    <el-table-column prop="name" label="姓名" />
    <el-table-column prop="age" label="年龄" />
  </PageTable>
</template>

<script setup>
import PageTable from '@/components/PageTable.vue'

const tableData = ref([])
const loading = ref(false)
const pagination = ref({
  current: 1,
  size: 10,
  total: 0
})

const loadData = async () => {
  loading.value = true
  // 加载数据逻辑
  loading.value = false
}
</script>
```

**主要属性：**
- `data`: 表格数据
- `loading`: 加载状态
- `pagination`: 分页配置 `{ current, size, total }`
- `showPagination`: 是否显示分页器（默认 true）
- `showToolbar`: 是否显示工具栏（默认 false）

**支持的插槽：**
- `search-form`: 搜索表单
- `toolbar-left`: 工具栏左侧按钮
- `toolbar-right`: 工具栏右侧按钮

---

### 2. DictSelect 字典选择器

从后端字典表加载数据的下拉选择组件，支持两种显示模式。

**基础用法：**

```vue
<template>
  <!-- 下拉框模式 -->
  <DictSelect
    v-model="form.status"
    dict-code="sys_status"
    placeholder="请选择状态"
  />

  <!-- 按钮组模式 -->
  <DictSelect
    v-model="form.type"
    dict-code="sys_type"
    mode="button"
    :button-border="true"
  />
</template>

<script setup>
import DictSelect from '@/components/DictSelect.vue'

const form = reactive({
  status: '',
  type: ''
})
</script>
```

**主要属性：**
- `dict-code`: 字典编码（必填）
- `mode`: 显示模式，`'select'` 或 `'button'`（默认 'select'）
- `multiple`: 是否多选（默认 false）
- `immediate`: 是否立即加载（默认 false，首次展开时加载）

---

### 3. EnumSelect 枚举选择器

从后端枚举类加载数据的下拉选择组件。

**基础用法：**

```vue
<template>
  <EnumSelect
    v-model="form.gender"
    enum-name="GenderEnum"
    placeholder="请选择性别"
  />
</template>

<script setup>
import EnumSelect from '@/components/EnumSelect.vue'

const form = reactive({
  gender: ''
})
</script>
```

**主要属性：**
- `enum-name`: 枚举类名称（必填）
- `mode`: 显示模式，`'select'` 或 `'button'`
- `multiple`: 是否多选

---

### 4. FileUpload 文件上传组件

支持多文件上传、拖拽、粘贴的文件上传组件，支持批量下载。

**基础用法：**

```vue
<template>
  <!-- 单文件上传 -->
  <FileUpload
    v-model="form.fileId"
    :limit="1"
    accept=".pdf,.doc,.docx"
    :max-size="10"
  />

  <!-- 多文件上传 -->
  <FileUpload
    v-model="form.fileIds"
    :limit="5"
    :multiple="true"
  />

  <!-- 批量模式（使用流水号） -->
  <FileUpload
    v-model="form.fileSerial"
    :batch-mode="true"
    :limit="10"
    :multiple="true"
  />
</template>

<script setup>
import FileUpload from '@/components/FileUpload.vue'

const form = reactive({
  fileId: null,
  fileIds: [],
  fileSerial: ''
})
</script>
```

**主要属性：**
- `batch-mode`: 批量模式，多文件共用一个流水号（默认 false）
- `limit`: 允许上传的文件数量
- `accept`: 接受的文件类型
- `max-size`: 文件大小限制（MB）

**特色功能：**
- 拖拽文件到表格区域上传
- Ctrl+V 粘贴图片上传
- 批量下载（批量模式）

---

### 5. ImageUpload 图片上传组件

专用于图片上传的组件，支持预览、拖拽、粘贴。

**基础用法：**

```vue
<template>
  <!-- 单张图片 -->
  <ImageUpload
    v-model="form.avatar"
    :limit="1"
    :max-size="5"
  />

  <!-- 多张图片 -->
  <ImageUpload
    v-model="form.images"
    :limit="9"
    :multiple="true"
  />

  <!-- 手动上传模式 -->
  <ImageUpload
    v-model="form.images"
    :limit="5"
    :auto-upload="false"
  />
</template>

<script setup>
import ImageUpload from '@/components/ImageUpload.vue'

const form = reactive({
  avatar: null,
  images: []
})
</script>
```

**主要属性：**
- `limit`: 允许上传的图片数量
- `max-size`: 图片大小限制（MB，默认 5）
- `auto-upload`: 是否自动上传（默认 true）
- `batch-mode`: 批量模式

---

### 6. ImageCell 图片单元格组件

在表格中展示图片，支持预览、点击放大。

**基础用法：**

```vue
<template>
  <el-table :data="tableData">
    <!-- 通过文件ID加载 -->
    <el-table-column label="图片">
      <template #default="{ row }">
        <ImageCell :file-id="row.imageId" />
      </template>
    </el-table-column>

    <!-- 通过流水号加载多张图片 -->
    <el-table-column label="附件">
      <template #default="{ row }">
        <ImageCell 
          mode="serial"
          :serial="row.fileSerial"
          :max-display="3"
        />
      </template>
    </el-table-column>
  </el-table>
</template>

<script setup>
import ImageCell from '@/components/ImageCell.vue'
</script>
```

**主要属性：**
- `mode`: 加载模式，`'id'` 或 `'serial'`（默认 'id'）
- `file-id`: 文件ID或ID数组
- `serial`: 文件流水号
- `max-display`: 最大显示数量（默认 3）
- `size`: 缩略图大小（默认 40）

---

### 7. IconPicker 图标选择器

选择 Element Plus 图标的选择器组件。

**基础用法：**

```vue
<template>
  <IconPicker
    v-model="form.icon"
    placeholder="请选择图标"
  />
</template>

<script setup>
import IconPicker from '@/components/IconPicker.vue'

const form = reactive({
  icon: 'User'
})
</script>
```

**特色功能：**
- 支持搜索图标
- 图标预览
- 自适应高度

---

### 8. PaginationSelect 分页选择器

支持分页的下拉选择组件，适用于大数据量选择。

**基础用法：**

```vue
<template>
  <PaginationSelect
    v-model="form.userId"
    :load-data="loadUserList"
    label-key="userName"
    value-key="userId"
    placeholder="请选择用户"
  />
</template>

<script setup>
import PaginationSelect from '@/components/PaginationSelect.vue'
import { getUserPage } from '@/api/user'

const form = reactive({
  userId: null
})

const loadUserList = async (params) => {
  const res = await getUserPage(params)
  return res
}
</script>
```

**主要属性：**
- `load-data`: 数据加载函数（必填）
- `load-initial-data`: 加载初始数据的函数（用于回显）
- `label-key`: 显示的标签字段
- `value-key`: 值字段
- `show-pagination`: 是否显示分页（默认 true）

---

### 9. RectLoading 加载动画

美观的加载动画组件。

**基础用法：**

```vue
<template>
  <RectLoading
    :visible="loading"
    type="default"
    color="#165dff"
    text="加载中..."
  />
</template>

<script setup>
import RectLoading from '@/components/RectLoading.vue'

const loading = ref(true)
</script>
```

**主要属性：**
- `visible`: 是否显示
- `type`: 类型，`'default'` 或 `'small'`
- `color`: 颜色
- `text`: 提示文字

---

## 常见问题

### 1. 启动后无法访问后端接口？

检查 `vite.config.js` 中的代理配置，确保 `target` 指向正确的后端地址（默认 `http://localhost:8080`）。

### 2. 登录后跳转 404？

- 检查后端是否正常返回菜单数据
- 检查菜单表中是否有可用的菜单项
- 查看浏览器控制台是否有错误信息

### 3. 图片/文件无法预览或下载？

- 确保后端 MinIO 服务已正常启动
- 检查 MinIO 配置是否正确
- 查看后端配置文件中的文件存储设置

### 4. Token 过期后无法自动跳转登录页？

检查响应拦截器中的错误码处理逻辑，确保正确处理 `40100` 错误码。

### 5. 按钮权限指令不生效？

- 确保已在 `main.js` 中注册 `v-permission` 指令
- 检查用户是否有对应的权限
- 查看 localStorage 中是否正确存储了权限列表

### 6. 组件使用问题

详细的组件文档请查看本文档中的"业务组件使用说明"章节。

## 许可证

MIT License



## 觉得项目不错可以考虑请作者喝杯蜜雪

![image-1](docs/images/images-1.jpg)

![image-20251022203632466](docs/images/image-20251022203632466.png)