# VUE3通用后台模板

**Repository Path**: candy_7/candy-sample

## Basic Information

- **Project Name**: VUE3通用后台模板
- **Description**: VUE搭建后台通用模板项目，使用vite + vue3 + element plus + pinia + vue-router + axios, 使用JS语法（非TS），搭建一套通用的后台管理模板；并基于常见业务场景，抽象出常见功能组件；包括动态菜单，菜单权限、登录、主题切换，开箱即用。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, JavaScript, Element-UI

## README

# Candy Sample - Vue 3 管理系统

<div align="center">

[![在线预览](https://img.shields.io/badge/🌐_在线预览-demo.joker.icu-blue?style=for-the-badge&logo=internet-explorer&logoColor=white)](https://demo.joker.icu/)
[![Gitee仓库](https://img.shields.io/badge/📦_Gitee仓库-candy--sample-red?style=for-the-badge&logo=gitee&logoColor=white)](https://gitee.com/candy_7/candy-sample)

</div>

一个基于 Vue 3 + Element Plus 的现代化管理系统模板，提供完整的后台管理解决方案。

## ✨ 特性

- 🚀 **Vue 3** - 使用最新的 Vue 3 Composition API
- 🎨 **Element Plus** - 基于 Vue 3 的组件库  
- 📱 **响应式设计** - 完美适配桌面端和移动端
- 🔥 **热重载** - 开发时快速热重载
- 📦 **组件化** - 高度组件化的架构设计
- 🛡️ **权限管理** - 完整的权限控制系统
- 🌈 **多主题** - 支持多种主题切换
- 📊 **图表集成** - 集成 ECharts 图表库
- 🎯 **字体大小调节** - 支持动态字体大小调整
- 💾 **状态持久化** - 用户设置自动保存

## 🛠️ 技术栈

- **前端框架**: Vue 3.4+
- **构建工具**: Vite 5.0+
- **UI 组件库**: Element Plus 2.4+
- **状态管理**: Pinia 2.1+
- **路由管理**: Vue Router 4.2+
- **HTTP 客户端**: Axios
- **图表库**: ECharts 5.4+
- **样式预处理**: Sass/SCSS
- **加密工具**: CryptoJS
- **日期处理**: Moment.js

## 📁 项目结构

```
candy-sample/
├── public/                 # 静态资源
├── src/                    # 源代码
│   ├── api/               # API 接口
│   │   ├── auth.js        # 认证相关API
│   │   ├── department.js  # 部门管理API
│   │   ├── logs.js        # 日志相关API
│   │   ├── menu.js        # 菜单管理API
│   │   ├── role.js        # 角色管理API
│   │   ├── setting.js     # 系统设置API
│   │   └── theme.js       # 主题相关API
│   ├── common/            # 公共模块
│   │   └── isAuth.js      # 权限验证
│   ├── components/        # 组件
│   │   ├── Layout/        # 布局组件
│   │   │   ├── AdminLayout.vue    # 管理员布局
│   │   │   ├── MixLayout.vue      # 混合布局
│   │   │   ├── TopLayout.vue      # 顶部布局
│   │   │   └── TabsView.vue       # 标签页视图
│   │   ├── common/        # 通用组件
│   │   │   ├── FontSizeSwitch.vue # 字体大小切换
│   │   │   ├── LayoutSwitch.vue   # 布局切换
│   │   │   ├── ThemeSwitch.vue    # 主题切换
│   │   │   └── Watermark.vue      # 水印组件
│   │   └── employee/      # 员工相关组件
│   ├── mock/              # Mock 数据
│   │   ├── api.js         # Mock API配置
│   │   └── data.js        # Mock 数据
│   ├── router/            # 路由配置
│   │   └── index.js       # 路由主配置
│   ├── stores/            # 状态管理 (Pinia)
│   │   ├── layout.js      # 布局状态
│   │   ├── tabs.js        # 标签页状态
│   │   └── user.js        # 用户状态
│   ├── styles/            # 样式文件
│   │   ├── common.css     # 通用样式
│   │   ├── responsive.css # 响应式样式
│   │   └── theme.css      # 主题样式
│   ├── utils/             # 工具函数
│   │   ├── dynamicRoutes.js # 动态路由工具
│   │   ├── echarts.js     # 图表工具
│   │   ├── fontSize.js    # 字体大小工具
│   │   ├── request.js     # HTTP请求工具
│   │   ├── theme.js       # 主题工具
│   │   └── tools.js       # 通用工具
│   └── views/             # 页面组件
│       ├── ClearCache.vue     # 清理缓存页面
│       ├── Home.vue           # 首页
│       ├── Login.vue          # 登录页面
│       ├── NotFound.vue       # 404页面
│       ├── UnderDevelopment.vue # 开发中页面
│       ├── department/        # 部门管理模块
│       ├── logs/             # 日志模块
│       ├── menu/             # 菜单管理模块
│       ├── role/             # 角色管理模块
│       └── sys/              # 系统管理模块
├── doc/                   # 项目文档
│   ├── README.md          # 文档目录说明
│   ├── api/              # API接口文档
│   ├── components/       # 组件文档
│   ├── stores/           # 状态管理文档
│   ├── utils/            # 工具函数文档
│   └── views/            # 页面组件文档
├── dist/                  # 构建输出
├── node_modules/          # 依赖包
├── .gitignore            # Git 忽略文件
├── package.json          # 项目配置
├── vite.config.js        # Vite 配置
└── README.md             # 项目说明
```

## 🚀 快速开始

### 环境要求

- Node.js >= 16.0.0
- npm >= 8.0.0 或 yarn >= 1.22.0

### 安装依赖

```bash
# 使用 npm
npm install

# 或使用 yarn
yarn install
```

### 开发环境

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

# 或使用 yarn
yarn dev
```

访问 http://localhost:5173 查看应用

### 生产构建

```bash
# 构建生产版本
npm run build

# 或使用 yarn
yarn build
```

### 预览构建结果

```bash
# 预览构建结果
npm run preview

# 或使用 yarn
yarn preview
```

## 🔧 配置说明

### 环境变量

创建 `.env.local` 文件配置环境变量：

```env
# API 基础地址
VITE_API_BASE_URL=http://localhost:8080/api

# 应用标题
VITE_APP_TITLE=Candy Sample

# 是否启用 Mock 数据
VITE_USE_MOCK=true
```

### Vite 配置

主要配置项在 `vite.config.js` 中：

- **路径别名**: `@` 指向 `src` 目录
- **代理配置**: 开发环境 API 代理
- **构建优化**: 代码分割和压缩
- **CSS 内联**: 生产环境 CSS 内联优化，减少HTTP请求

### Mock 数据配置

开发环境默认启用 Mock 数据，在 `src/utils/request.js` 中配置：

```javascript
// 是否使用 Mock 数据
const USE_MOCK = true
```

## 📚 功能模块

### 🏠 首页 (Home)
- 用户信息展示卡片
- 系统公告列表
- 快捷操作入口
- 响应式布局设计

### 👥 部门管理 (Department)
- 部门列表查看
- 部门信息管理
- 部门层级结构
- 部门员工统计

### 👤 角色管理 (Role)
- 角色权限配置
- 角色分配管理
- 权限控制矩阵
- 角色继承关系

### 📋 菜单管理 (Menu)
- 菜单配置管理
- 动态路由生成
- 菜单权限控制
- 菜单图标配置

### 📊 日志管理 (Logs)
- **登录日志**: 用户登录记录查看
- **操作日志**: 用户操作行为记录
- 日志统计分析
- 日志导出功能

### ⚙️ 系统设置 (System)
- **系统参数**: 基础配置管理
- **公告管理**: 系统公告发布
- 主题设置
- 字体大小配置

### 🧹 缓存管理 (ClearCache)
- 用户信息缓存清理
- 主题设置缓存清理
- 页面标签缓存清理
- 本地存储管理

## 🎨 主题系统

系统支持7种预设主题，支持实时切换：

- **默认蓝色** (#409EFF) - 经典蓝色主题
- **清新绿色** (#67C23A) - 绿色自然主题  
- **优雅紫色** (#9C27B0) - 紫色优雅主题
- **活力橙色** (#FF9800) - 橙色活力主题
- **热情红色** (#F44336) - 红色热情主题
- **温馨粉色** (#E91E63) - 粉色温馨主题
- **深色模式** (#2C3E50) - 深色护眼主题

### 主题切换

```javascript
import { setTheme, getAllThemes, getCurrentTheme } from '@/utils/theme'

// 获取所有主题
const themes = getAllThemes()

// 获取当前主题
const current = getCurrentTheme()

// 切换到绿色主题
setTheme('green')
```

### 主题持久化

主题设置自动保存到 localStorage，页面刷新后保持用户选择。

## 🔤 字体大小系统

支持动态字体大小调整，提供更好的用户体验：

### 预设字体大小
- **小号** (12px) - 适合信息密集场景
- **默认** (14px) - 标准阅读大小
- **中号** (16px) - 舒适阅读大小
- **大号** (18px) - 适合长时间阅读
- **特大** (20px) - 视力辅助大小

### 字体大小切换

```javascript
import { setFontSize, getAllFontSizes, getCurrentFontSize } from '@/utils/fontSize'

// 获取所有字体大小选项
const fontSizes = getAllFontSizes()

// 获取当前字体大小
const current = getCurrentFontSize()

// 设置字体大小
setFontSize(16)
```

## 📱 响应式设计

系统采用响应式设计，支持多种设备：

- **桌面端** (>= 1200px): 完整功能展示，三栏布局
- **平板端** (768px - 1199px): 适配平板布局，两栏布局
- **手机端** (< 768px): 移动端优化，单栏布局

### 布局模式

系统提供3种布局模式：

1. **AdminLayout**: 经典左侧边栏布局
2. **MixLayout**: 顶部菜单+侧边栏混合布局  
3. **TopLayout**: 纯顶部菜单布局

## 🔐 权限系统

### 路由权限
```javascript
// 路由守卫
router.beforeEach((to, from, next) => {
  const userStore = useUserStore()
  
  if (to.meta.requiresAuth && !userStore.isLoggedIn) {
    next('/login')
  } else if (to.meta.roles && !to.meta.roles.includes(userStore.role)) {
    next('/403')
  } else {
    next()
  }
})
```

### 组件权限
```vue
<template>
  <el-button v-if="$isAuth('user:add')" @click="addUser">
    添加用户
  </el-button>
</template>

<script setup>
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()

// 检查权限
const hasPermission = (permission) => {
  return userStore.permissions.includes(permission)
}
</script>
```

### 菜单权限

菜单根据用户权限动态生成，无权限的菜单项不会显示。

## 🧪 Mock 数据

开发环境使用 Mock 数据，配置在 `src/mock/` 目录：

```javascript
// src/mock/api.js
export const mockLogin = {
  url: '/login',
  method: 'post',
  response: {
    status: true,
    msg: '登录成功',
    data: {
      token: 'mock_token_123456',
      employeeInfo: {
        id: 1,
        username: 'admin',
        realname: '管理员',
        mobile: '13800138000',
        dpname: '技术部',
        role_name: '系统管理员',
        style: 'default'
      },
      menuList: [
        // 菜单数据
      ],
      notice: [
        // 公告数据
      ]
    }
  }
}
```

## 📖 开发指南

### 添加新页面

1. 在 `src/views/` 创建页面组件
2. 在 `src/router/index.js` 添加路由配置
3. 在菜单配置中添加菜单项
4. 在 `doc/views/` 添加页面文档

### 添加新组件

1. 在 `src/components/` 创建组件
2. 编写组件文档到 `doc/components/`
3. 导出组件供其他模块使用

### API 接口开发

```javascript
// src/api/example.js
import request from '@/utils/request'

export const getList = (params) => {
  return request({
    url: '/example/list',
    method: 'get',
    params
  })
}

export const createItem = (data) => {
  return request({
    url: '/example/create',
    method: 'post',
    data
  })
}
```

### 状态管理

```javascript
// src/stores/example.js
import { defineStore } from 'pinia'

export const useExampleStore = defineStore('example', {
  state: () => ({
    list: [],
    loading: false,
    currentItem: null
  }),

  getters: {
    itemCount: (state) => state.list.length,
    hasItems: (state) => state.list.length > 0
  },

  actions: {
    async fetchList() {
      this.loading = true
      try {
        const response = await getList()
        this.list = response.data
      } catch (error) {
        console.error('获取列表失败:', error)
      } finally {
        this.loading = false
      }
    },

    setCurrentItem(item) {
      this.currentItem = item
    }
  }
})
```

### 工具函数

```javascript
// src/utils/example.js

/**
 * 格式化日期
 * @param {Date|string} date 日期
 * @param {string} format 格式
 * @returns {string} 格式化后的日期
 */
export const formatDate = (date, format = 'YYYY-MM-DD HH:mm:ss') => {
  return moment(date).format(format)
}

/**
 * 防抖函数
 * @param {Function} func 要防抖的函数
 * @param {number} delay 延迟时间
 * @returns {Function} 防抖后的函数
 */
export const debounce = (func, delay) => {
  let timeoutId
  return function (...args) {
    clearTimeout(timeoutId)
    timeoutId = setTimeout(() => func.apply(this, args), delay)
  }
}
```

## 🎯 性能优化

### 代码分割
```javascript
// 路由懒加载
const Home = () => import('@/views/Home.vue')
const Department = () => import('@/views/department/index.vue')
```

### 组件懒加载
```vue
<script setup>
import { defineAsyncComponent } from 'vue'

// 异步组件
const HeavyComponent = defineAsyncComponent(() =>
  import('@/components/HeavyComponent.vue')
)
</script>
```

### 构建优化

Vite 配置包含多项构建优化：

- **CSS 内联**: 减少 HTTP 请求
- **代码压缩**: Terser 压缩 JavaScript
- **Tree Shaking**: 移除未使用的代码
- **资源压缩**: 图片和字体文件压缩

## 🔒 安全特性

### 数据加密
```javascript
import CryptoJS from 'crypto-js'

// 加密用户数据
const encryptData = (data, key) => {
  return CryptoJS.AES.encrypt(JSON.stringify(data), key).toString()
}

// 解密用户数据
const decryptData = (encryptedData, key) => {
  const bytes = CryptoJS.AES.decrypt(encryptedData, key)
  return JSON.parse(bytes.toString(CryptoJS.enc.Utf8))
}
```

### XSS 防护
- 用户输入内容自动转义
- 使用 `v-html` 时进行内容过滤
- CSP (Content Security Policy) 配置

### CSRF 防护
- API 请求包含 CSRF Token
- 验证请求来源

## 🧪 测试

### 单元测试
```bash
# 运行单元测试
npm run test:unit

# 测试覆盖率
npm run test:coverage
```

### E2E 测试
```bash
# 运行端到端测试
npm run test:e2e
```

## 📊 监控和分析

### 性能监控
- 页面加载时间统计
- API 请求性能监控
- 用户操作行为分析

### 错误监控
- JavaScript 错误捕获
- API 请求错误统计
- 用户反馈收集

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

### 代码规范

- 使用 ESLint 进行代码检查
- 使用 Prettier 进行代码格式化
- 遵循 Vue 3 组合式 API 最佳实践
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case
- 提交信息遵循 Conventional Commits 规范

### 文档规范

- 新增功能必须包含相应文档
- 文档使用 Markdown 格式
- 包含代码示例和使用说明
- 保持文档与代码同步更新

## 📚 相关文档

- [项目文档目录](./doc/README.md) - 完整的技术文档
- [API 接口文档](./doc/api/) - 所有 API 接口说明
- [组件文档](./doc/components/) - 组件使用指南
- [工具函数文档](./doc/utils/) - 工具函数说明

## 🔄 更新日志

### v1.2.0 (2025-09-19)
- ✨ 新增字体大小调节功能
- 🎨 优化主题切换体验
- 🧹 清理未使用的代码和依赖
- 📚 完善项目文档结构
- 🐛 修复已知问题

### v1.1.0 (2024-12-01)
- ✨ 新增多主题支持
- 📱 优化响应式布局
- 🔐 完善权限管理系统
- 📊 集成 ECharts 图表

### v1.0.0 (2024-10-01)
- 🎉 项目初始版本发布
- ✨ 基础功能模块完成
- 🎨 UI 界面设计完成


## 🙏 致谢

- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Element Plus](https://element-plus.org/) - Vue 3 组件库
- [Vite](https://vitejs.dev/) - 下一代前端构建工具
- [Pinia](https://pinia.vuejs.org/) - Vue 状态管理库
- [ECharts](https://echarts.apache.org/) - 数据可视化图表库


---

**Candy Sample** © 2024. Released under the MIT License.

*一个现代化、功能完整的 Vue 3 管理系统模板，助力快速开发高质量的后台管理应用。*