# vue3test

**Repository Path**: Tomcheung/vue3test

## Basic Information

- **Project Name**: vue3test
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业级 Web 后台管理系统

<div align="center">

![Vue](https://img.shields.io/badge/Vue-3.5.32-4FC08D?logo=vue.js)
![Vite](https://img.shields.io/badge/Vite-8.0.8-646CFF?logo=vite)
![TypeScript](https://img.shields.io/badge/TypeScript-6.0.0-3178C6?logo=typescript)
![Pinia](https://img.shields.io/badge/Pinia-3.0.4-yellow?logo=pinia)
![License](https://img.shields.io/badge/License-MIT-green)

**基于 Vue 3 + Vite + TypeScript 的企业级后台管理系统解决方案**

[快速开始](#-快速开始) • [技术栈](#-技术栈) • [项目结构](#-项目结构) • [开发指南](#-开发指南) • [部署说明](#-部署说明)

</div>

---

## 📋 目录

- [项目简介](#-项目简介)
- [功能特性](#-功能特性)
- [技术栈](#-技术栈)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [开发指南](#-开发指南)
  - [环境准备](#环境准备)
  - [安装依赖](#安装依赖)
  - [开发模式](#开发模式)
  - [生产构建](#生产构建)
- [核心功能模块](#-核心功能模块)
  - [认证与权限](#认证与权限)
  - [布局系统](#布局系统)
  - [用户管理](#用户管理)
  - [角色权限](#角色权限)
  - [菜单管理](#菜单管理)
  - [仪表盘](#仪表盘)
  - [系统日志](#系统日志)
- [通用组件库](#-通用组件库)
- [Hooks 工具集](#-hooks-工具集)
- [代码规范](#-代码规范)
- [测试](#-测试)
- [部署说明](#-部署说明)
- [常见问题](#-常见问题)
- [贡献指南](#-贡献指南)
- [更新日志](#-更新日志)
- [许可证](#-许可证)

---

## 🎯 项目简介

这是一个基于 **Vue 3 + Vite + TypeScript** 技术栈构建的企业级后台管理系统模板。项目采用现代化的前端技术栈，提供了完整的后台管理系统解决方案，包括：

- ✅ 完善的认证与权限控制系统
- ✅ 灵活的动态路由与菜单管理
- ✅ 响应式布局设计，支持多端适配
- ✅ 丰富的通用业务组件
- ✅ 标准化的 CRUD 开发模式
- ✅ 完整的 TypeScript 类型支持
- ✅ 规范的代码风格与工程化配置

本项目适合作为企业内部管理系统、数据管理平台、运营后台等场景的基础框架，帮助开发者快速搭建高质量的管理系统。

---

## ✨ 功能特性

### 核心功能

- 🔐 **认证授权**
  - 用户登录/登出
  - Token 自动刷新
  - 记住我功能
  - 验证码支持

- 🛡️ **权限控制**
  - 基于角色的访问控制 (RBAC)
  - 动态路由加载
  - 按钮级别权限控制
  - 菜单权限过滤

- 🎨 **主题系统**
  - 亮色/暗色主题切换
  - 自定义主题色
  - 多种布局模式
  - 主题配置持久化

- 🌍 **国际化**
  - 中英文双语支持
  - 动态语言切换
  - 语言偏好持久化

- 📊 **数据可视化**
  - ECharts 图表集成
  - 数据统计卡片
  - 实时数据更新

- 📝 **表单处理**
  - 高级搜索表单
  - 表单验证
  - 文件上传
  - 富文本编辑器

- 📋 **表格功能**
  - 分页/排序/筛选
  - 列配置
  - 批量操作
  - Excel 导出

- 🔔 **消息通知**
  - 系统通知
  - 消息中心
  - 实时推送（可扩展）

### 工程化特性

- ⚡️ **快速开发**
  - Vite 极速启动
  - HMR 热更新
  - TypeScript 智能提示

- 🧪 **测试覆盖**
  - Vitest 单元测试
  - Playwright E2E 测试
  - 测试覆盖率报告

- 📦 **构建优化**
  - 代码分割
  - 按需加载
  - Gzip 压缩
  - CDN 支持

- 🔍 **代码质量**
  - ESLint 代码检查
  - Prettier 代码格式化
  - Husky Git 钩子
  - Commit 规范

- 📊 **监控埋点**
  - 错误捕获与上报
  - 用户行为追踪
  - 性能监控

---

## 🛠️ 技术栈

### 核心框架

| 技术 | 版本 | 说明 |
|------|------|------|
| [Vue 3](https://vuejs.org/) | 3.5.32 | 渐进式 JavaScript 框架 |
| [Vite](https://vitejs.dev/) | 8.0.8 | 下一代前端构建工具 |
| [TypeScript](https://www.typescriptlang.org/) | 6.0.0 | JavaScript 的超集 |
| [Vue Router](https://router.vuejs.org/) | 5.0.4 | Vue.js 官方路由管理器 |
| [Pinia](https://pinia.vuejs.org/) | 3.0.4 | Vue 状态管理库 |

### UI 组件库（待选型）

> 以下方案二选一：

**方案 A: Element Plus**
- [Element Plus](https://element-plus.org/) - 基于 Vue 3 的组件库
- 优点：生态成熟、文档完善、社区活跃

**方案 B: Ant Design Vue**
- [Ant Design Vue](https://antdv.com/) - Ant Design 的 Vue 实现
- 优点：设计规范、组件丰富、企业级体验

### HTTP 客户端

- [Axios](https://axios-http.com/) - 基于 Promise 的 HTTP 客户端

### 样式方案

- SCSS - CSS 预处理器
- CSS Modules - 模块化 CSS
- PostCSS - CSS 后处理器

### 工具库

- [Day.js](https://day.js.org/) - 轻量级日期处理库
- [Lodash-es](https://lodash.com/) - JavaScript 实用工具库
- [ECharts](https://echarts.apache.org/) - 数据可视化图表库

### 代码质量

- [ESLint](https://eslint.org/) - 代码检查工具
- [Prettier](https://prettier.io/) - 代码格式化工具
- [Oxlint](https://oxc.rs/) - 高性能 linter
- [Husky](https://typicode.github.io/husky/) - Git hooks 工具
- [lint-staged](https://github.com/okonet/lint-staged) - 暂存文件 lint 工具

### 测试框架

- [Vitest](https://vitest.dev/) - 下一代单元测试框架
- [Playwright](https://playwright.dev/) - 端到端测试框架
- [@vue/test-utils](https://test-utils.vuejs.org/) - Vue 组件测试工具

### 其他

- [vue-i18n](https://vue-i18n.intlify.dev/) - 国际化插件
- [vite-plugin-vue-devtools](https://devtools.vuejs.org/) - Vue DevTools 插件

---

## 🚀 快速开始

### 环境准备

确保你的开发环境满足以下要求：

- **Node.js**: `^20.19.0` 或 `>=22.12.0`
- **npm**: `>=10.0.0` 或使用 `pnpm` / `yarn`
- **Git**: 最新版本

检查 Node.js 版本：

```bash
node -v
npm -v
```

### 安装依赖

```bash
# 克隆项目
git clone <repository-url>
cd vue_vite_test

# 安装依赖
npm install

# 或使用 pnpm
pnpm install

# 或使用 yarn
yarn install
```

### 开发模式

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

# 访问 http://localhost:5173
```

开发服务器启动后，你可以在浏览器中访问 `http://localhost:5173` 查看应用。

### 生产构建

```bash
# 类型检查
npm run type-check

# 构建生产版本
npm run build

# 预览生产构建
npm run preview
```

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

### 其他命令

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

# 运行 E2E 测试
npm run test:e2e

# 代码检查与修复
npm run lint

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

---

## 📁 项目结构

```
vue_vite_test/
├── public/                    # 静态资源目录
│   └── favicon.ico
├── src/
│   ├── api/                   # API 接口管理
│   │   ├── index.ts           # API 统一导出
│   │   └── modules/           # 模块化 API
│   │       ├── auth.ts        # 认证相关接口
│   │       ├── user.ts        # 用户管理接口
│   │       ├── role.ts        # 角色管理接口
│   │       └── menu.ts        # 菜单管理接口
│   ├── assets/                # 静态资源
│   │   ├── images/            # 图片资源
│   │   ├── styles/            # 全局样式
│   │   │   ├── variables.scss # SCSS 变量
│   │   │   ├── mixins.scss    # SCSS 混入
│   │   │   ├── reset.css      # 样式重置
│   │   │   └── themes/        # 主题文件
│   │   │       ├── light.scss
│   │   │       └── dark.scss
│   │   └── icons/             # SVG 图标
│   ├── components/            # 公共组件
│   │   ├── SvgIcon/           # SVG 图标组件
│   │   ├── SearchForm/        # 搜索表单组件
│   │   ├── ProTable/          # 高级表格组件
│   │   ├── UploadFile/        # 文件上传组件
│   │   ├── IconPicker/        # 图标选择器
│   │   └── ...                # 其他通用组件
│   ├── composables/           # 组合式函数
│   │   └── useXxx.ts          # 自定义 hooks
│   ├── directives/            # 自定义指令
│   │   └── permission.ts      # 权限指令
│   ├── hooks/                 # 业务 Hooks
│   │   ├── useTable.ts        # 表格逻辑封装
│   │   ├── useForm.ts         # 表单逻辑封装
│   │   ├── useAuth.ts         # 权限判断
│   │   ├── useTheme.ts        # 主题切换
│   │   └── ...
│   ├── layout/                # 布局组件
│   │   ├── index.vue          # 布局容器
│   │   └── components/
│   │       ├── Sidebar.vue    # 侧边栏
│   │       ├── Navbar.vue     # 顶部导航
│   │       ├── TagsView.vue   # 标签页
│   │       ├── AppMain.vue    # 主内容区
│   │       └── Breadcrumb.vue # 面包屑
│   ├── locales/               # 国际化配置
│   │   ├── index.ts           # i18n 配置
│   │   ├── zh-CN.ts           # 中文语言包
│   │   └── en-US.ts           # 英文语言包
│   ├── router/                # 路由配置
│   │   ├── index.ts           # 路由实例
│   │   ├── guards.ts          # 路由守卫
│   │   └── routes/
│   │       ├── constant.ts    # 常量路由
│   │       └── dynamic.ts     # 动态路由
│   ├── stores/                # Pinia 状态管理
│   │   ├── auth.ts            # 认证状态
│   │   ├── user.ts            # 用户信息
│   │   ├── permission.ts      # 权限状态
│   │   ├── menu.ts            # 菜单状态
│   │   ├── theme.ts           # 主题状态
│   │   └── tagsView.ts        # 标签页状态
│   ├── utils/                 # 工具函数
│   │   ├── request.ts         # Axios 封装
│   │   ├── interceptors.ts    # 请求拦截器
│   │   ├── format.ts          # 格式化工具
│   │   ├── storage.ts         # 存储工具
│   │   ├── validate.ts        # 验证工具
│   │   ├── common.ts          # 通用工具
│   │   ├── permission.ts      # 权限工具
│   │   ├── monitor.ts         # 错误监控
│   │   └── tracker.ts         # 行为埋点
│   ├── views/                 # 页面视图
│   │   ├── LoginView.vue      # 登录页面
│   │   ├── Dashboard/         # 仪表盘
│   │   │   ├── index.vue
│   │   │   └── components/
│   │   ├── User/              # 用户管理
│   │   │   ├── index.vue
│   │   │   └── components/
│   │   ├── Role/              # 角色管理
│   │   │   ├── index.vue
│   │   │   └── components/
│   │   ├── Menu/              # 菜单管理
│   │   │   ├── index.vue
│   │   │   └── components/
│   │   ├── Log/               # 系统日志
│   │   │   ├── LoginLog.vue
│   │   │   └── OperationLog.vue
│   │   ├── ProfileView.vue    # 个人中心
│   │   └── ErrorPage/         # 错误页面
│   │       ├── 403.vue
│   │       └── 404.vue
│   ├── App.vue                # 根组件
│   └── main.ts                # 入口文件
├── tests/                     # 测试文件
│   ├── unit/                  # 单元测试
│   └── e2e/                   # E2E 测试
├── .env.development           # 开发环境变量
├── .env.production            # 生产环境变量
├── .env.staging               # 测试环境变量（可选）
├── .eslintrc.cjs              # ESLint 配置
├── .prettierrc                # Prettier 配置
├── tsconfig.json              # TypeScript 配置
├── vite.config.ts             # Vite 配置
├── package.json               # 项目依赖
├── README.md                  # 项目说明
└── CHANGELOG.md               # 更新日志
```

---

## 📖 开发指南

### 环境准备

#### 1. 安装 Node.js

推荐通过 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本：

```bash
# 安装 nvm
# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Windows
# 下载 nvm-windows: https://github.com/coreybutler/nvm-windows/releases

# 安装指定版本
nvm install 20
nvm use 20
```

#### 2. 配置镜像源（可选）

如果网络较慢，可以配置 npm 镜像源：

```bash
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 或使用 pnpm
pnpm config set registry https://registry.npmmirror.com
```

### 安装依赖

```bash
# 使用 npm
npm install

# 使用 pnpm（推荐）
pnpm install

# 使用 yarn
yarn install
```

### 开发模式

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

开发服务器特性：
- ⚡️ 极速冷启动（< 1s）
- 🔥 即时热更新（HMR）
- 📦 按需编译
- 🗺️ Source Map 支持

### 环境变量

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

**.env.development**
```env
VITE_APP_TITLE=后台管理系统
VITE_APP_BASE_API=/api
VITE_APP_PORT=5173
```

**.env.production**
```env
VITE_APP_TITLE=后台管理系统
VITE_APP_BASE_API=/prod-api
VITE_APP_BASE_URL=https://api.example.com
```

在代码中使用：

```typescript
// 访问环境变量
const title = import.meta.env.VITE_APP_TITLE
const apiUrl = import.meta.env.VITE_APP_BASE_API
```

### API 代理配置

开发环境下配置 API 代理，解决跨域问题：

**vite.config.ts**
```typescript
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})
```

### 生产构建

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

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

构建优化：
- 📦 代码分割（Code Splitting）
- 🗜️ Tree Shaking
- 🖼️ 图片压缩
- 📝 CSS 压缩
- 🔢 文件名哈希

---

## 🎯 核心功能模块

### 认证与权限

#### 登录流程

```typescript
// 1. 用户输入账号密码
// 2. 调用登录接口
const { token } = await authApi.login({ username, password })

// 3. 存储 token
useAuthStore().setToken(token)

// 4. 获取用户信息
const userInfo = await userApi.getInfo()
useUserStore().setUserInfo(userInfo)

// 5. 生成动态路由
const routes = await generateRoutes(userInfo.roles)
router.addRoute(routes)

// 6. 跳转到首页
router.push('/')
```

#### Token 管理

- **Access Token**: 短期有效，用于接口认证
- **Refresh Token**: 长期有效，用于刷新 Access Token
- **自动刷新**: Access Token 过期前自动刷新
- **无感刷新**: 刷新期间请求队列等待

#### 权限控制

**路由级别权限**
```typescript
// 路由配置中添加 meta 信息
{
  path: '/user',
  component: () => import('@/views/User/index.vue'),
  meta: {
    title: '用户管理',
    roles: ['admin', 'editor'] // 允许访问的角色
  }
}
```

**按钮级别权限**
```vue
<template>
  <!-- 使用 v-permission 指令 -->
  <el-button v-permission="['user:add']">新增用户</el-button>
  <el-button v-permission="['user:edit']">编辑用户</el-button>
  <el-button v-permission="['user:delete']">删除用户</el-button>
</template>
```

---

### 布局系统

#### 布局结构

```
┌─────────────────────────────────────┐
│            Navbar (顶部导航)          │
├──────────┬──────────────────────────┤
│          │                          │
│ Sidebar  │      TagsView (标签页)    │
│ (侧边栏)  ├──────────────────────────┤
│          │                          │
│          │     AppMain (主内容区)     │
│          │                          │
│          │                          │
└──────────┴──────────────────────────┘
```

#### 布局模式

支持多种布局模式：
- **左侧菜单模式**（默认）
- **顶部菜单模式**
- **混合菜单模式**

#### 响应式设计

- 🖥️ Desktop: ≥ 1024px
- 📱 Tablet: 768px - 1023px
- 📱 Mobile: < 768px

---

### 用户管理

#### 功能清单

- ✅ 用户列表展示（分页、排序、筛选）
- ✅ 用户搜索（用户名、手机号、邮箱）
- ✅ 新增用户
- ✅ 编辑用户信息
- ✅ 删除用户（单条/批量）
- ✅ 用户详情查看
- ✅ 启用/禁用用户
- ✅ 重置密码
- ✅ 分配角色
- ✅ 导出 Excel

#### 标准 CRUD 示例

```vue
<script setup lang="ts">
import { useTable } from '@/hooks/useTable'
import { userApi } from '@/api/modules/user'

// 使用 useTable Hook
const {
  tableData,
  loading,
  pagination,
  searchParams,
  handleSearch,
  handleReset,
  handleDelete,
  refresh
} = useTable({
  api: userApi.getList,
  defaultParams: {
    pageNum: 1,
    pageSize: 10
  }
})

// 新增用户
const handleAdd = () => {
  // 打开对话框
}

// 编辑用户
const handleEdit = (row: User) => {
  // 打开对话框并填充数据
}
</script>

<template>
  <div class="user-management">
    <!-- 搜索表单 -->
    <SearchForm
      v-model="searchParams"
      :items="searchItems"
      @search="handleSearch"
      @reset="handleReset"
    />

    <!-- 操作按钮 -->
    <div class="toolbar">
      <el-button type="primary" @click="handleAdd">新增</el-button>
      <el-button type="danger" @click="handleBatchDelete">批量删除</el-button>
      <el-button @click="handleExport">导出</el-button>
    </div>

    <!-- 数据表格 -->
    <ProTable
      v-loading="loading"
      :data="tableData"
      :columns="columns"
      :pagination="pagination"
      @selection-change="handleSelectionChange"
      @page-change="handlePageChange"
    >
      <template #action="{ row }">
        <el-button size="small" @click="handleEdit(row)">编辑</el-button>
        <el-button size="small" type="danger" @click="handleDelete(row)">
          删除
        </el-button>
      </template>
    </ProTable>
  </div>
</template>
```

---

### 角色权限

#### RBAC 模型

```
用户 (User) ←→ 角色 (Role) ←→ 权限 (Permission)
```

- **用户**: 系统使用者
- **角色**: 权限集合（如：管理员、编辑、访客）
- **权限**: 具体操作权限（如：用户管理、文章发布）

#### 权限粒度

- **菜单权限**: 控制菜单显示/隐藏
- **页面权限**: 控制页面访问
- **按钮权限**: 控制按钮显示/隐藏
- **数据权限**: 控制数据范围（本部门、全部等）

---

### 菜单管理

#### 菜单类型

- **目录**: 一级菜单，不可点击
- **菜单**: 可点击的菜单项
- **按钮**: 页面内的操作按钮

#### 菜单配置

```typescript
interface MenuItem {
  id: number
  parentId: number
  name: string
  path: string
  component?: string
  icon?: string
  type: 'directory' | 'menu' | 'button'
  permission?: string
  sort: number
  visible: boolean
  children?: MenuItem[]
}
```

---

### 仪表盘

#### 数据展示

- 📊 统计卡片（总用户数、订单数、销售额等）
- 📈 趋势图表（折线图、柱状图）
- 🥧 占比分析（饼图、环形图）
- 📋 最近活动列表

#### 实时更新

支持 WebSocket 或定时轮询实现数据实时更新。

---

### 系统日志

#### 日志类型

- **登录日志**: 记录用户登录行为
- **操作日志**: 记录用户操作行为
- **异常日志**: 记录系统异常

#### 日志字段

```typescript
interface OperationLog {
  id: number
  userId: number
  username: string
  module: string        // 模块名称
  action: string        // 操作类型
  method: string        // 请求方法
  url: string           // 请求地址
  params: string        // 请求参数
  result: string        // 返回结果
  ip: string            // IP 地址
  location: string      // 地理位置
  browser: string       // 浏览器
  os: string            // 操作系统
  status: number        // 状态码
  errorMsg?: string     // 错误信息
  createTime: string    // 创建时间
}
```

---

## 🧩 通用组件库

### 组件清单

| 组件名 | 说明 | 示例 |
|--------|------|------|
| SvgIcon | SVG 图标组件 | `<SvgIcon name="home" />` |
| SearchForm | 搜索表单 | 自动生成搜索表单 |
| ProTable | 高级表格 | 内置分页、排序、筛选 |
| UploadFile | 文件上传 | 支持图片、文件上传 |
| IconPicker | 图标选择器 | 可视化选择图标 |
| TreeSelect | 树形选择器 | 树形数据选择 |
| RichTextEditor | 富文本编辑器 | 富文本内容编辑 |
| ImagePreview | 图片预览 | 点击图片放大预览 |

### 使用示例

#### SvgIcon

```vue
<template>
  <SvgIcon name="dashboard" :size="24" color="#409EFF" />
</template>
```

#### SearchForm

```vue
<script setup lang="ts">
const searchItems = [
  {
    label: '用户名',
    prop: 'username',
    type: 'input',
    placeholder: '请输入用户名'
  },
  {
    label: '状态',
    prop: 'status',
    type: 'select',
    options: [
      { label: '启用', value: 1 },
      { label: '禁用', value: 0 }
    ]
  },
  {
    label: '创建时间',
    prop: 'createTime',
    type: 'daterange'
  }
]

const searchParams = reactive({
  username: '',
  status: null,
  createTime: []
})
</script>

<template>
  <SearchForm
    v-model="searchParams"
    :items="searchItems"
    @search="handleSearch"
    @reset="handleReset"
  />
</template>
```

#### ProTable

```vue
<script setup lang="ts">
const columns = [
  {
    prop: 'username',
    label: '用户名',
    width: 120
  },
  {
    prop: 'email',
    label: '邮箱',
    minWidth: 180
  },
  {
    prop: 'status',
    label: '状态',
    width: 100,
    slot: 'status'
  },
  {
    prop: 'createTime',
    label: '创建时间',
    width: 180
  }
]
</script>

<template>
  <ProTable
    :data="tableData"
    :columns="columns"
    :pagination="pagination"
    @page-change="handlePageChange"
  >
    <template #status="{ row }">
      <el-tag :type="row.status === 1 ? 'success' : 'danger'">
        {{ row.status === 1 ? '启用' : '禁用' }}
      </el-tag>
    </template>
  </ProTable>
</template>
```

---

## 🪝 Hooks 工具集

### 可用 Hooks

| Hook | 说明 | 用途 |
|------|------|------|
| useTable | 表格逻辑封装 | 简化表格开发 |
| useForm | 表单逻辑封装 | 简化表单开发 |
| useDialog | 对话框管理 | 统一管理对话框状态 |
| useAuth | 权限判断 | 检查用户权限 |
| useTheme | 主题切换 | 切换亮色/暗色主题 |
| useFullscreen | 全屏控制 | 元素全屏显示 |
| useClipboard | 剪贴板操作 | 复制文本到剪贴板 |
| useDownload | 文件下载 | 下载文件 |

### 使用示例

#### useTable

```typescript
import { useTable } from '@/hooks/useTable'
import { userApi } from '@/api/modules/user'

const {
  tableData,
  loading,
  pagination,
  searchParams,
  handleSearch,
  handleReset,
  refresh
} = useTable({
  api: userApi.getList,
  defaultParams: {
    pageNum: 1,
    pageSize: 10
  },
  onSuccess: (data) => {
    console.log('数据加载成功', data)
  },
  onError: (error) => {
    console.error('数据加载失败', error)
  }
})
```

#### useAuth

```typescript
import { useAuth } from '@/hooks/useAuth'

const { hasPermission, hasRole, isAdmin } = useAuth()

// 检查是否有某个权限
if (hasPermission('user:add')) {
  // 显示新增按钮
}

// 检查是否有某个角色
if (hasRole('admin')) {
  // 显示管理员专属功能
}

// 检查是否是管理员
if (isAdmin()) {
  // 管理员操作
}
```

---

## 📏 代码规范

### ESLint 配置

项目使用 ESLint 进行代码质量检查：

```bash
# 检查代码
npm run lint

# 自动修复
npm run lint:fix
```

### Prettier 配置

代码格式化配置：

**.prettierrc**
```json
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "none",
  "printWidth": 100
}
```

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

### Git Commit 规范

遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```bash
# 提交格式
<type>(<scope>): <subject>

# 示例
feat(user): 添加用户管理功能
fix(auth): 修复登录 token 刷新问题
docs(readme): 更新项目文档
style(ui): 调整按钮样式
refactor(api): 重构 API 模块
test(user): 添加用户管理单元测试
chore(deps): 升级依赖包版本
```

**Type 类型：**
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档变更
- `style`: 代码格式（不影响功能）
- `refactor`: 重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具变动
- `perf`: 性能优化
- `ci`: CI/CD 配置变更

### TypeScript 规范

- 严格模式：启用 `strict: true`
- 禁止使用 `any` 类型
- 所有函数必须标注返回值类型
- 接口命名以 `I` 开头（可选）
- 类型定义放在 `types/` 目录

---

## 🧪 测试

### 单元测试

使用 Vitest 进行单元测试：

```bash
# 运行所有测试
npm run test:unit

# 运行指定文件的测试
npm run test:unit -- src/utils/format.test.ts

# 监听模式
npm run test:unit -- --watch

# 生成覆盖率报告
npm run test:unit -- --coverage
```

**测试文件示例：**

```typescript
// src/utils/format.test.ts
import { describe, it, expect } from 'vitest'
import { formatDate } from './format'

describe('formatDate', () => {
  it('应该正确格式化日期', () => {
    const date = new Date('2024-01-01')
    expect(formatDate(date)).toBe('2024-01-01')
  })

  it('应该支持自定义格式', () => {
    const date = new Date('2024-01-01')
    expect(formatDate(date, 'YYYY/MM/DD')).toBe('2024/01/01')
  })
})
```

### E2E 测试

使用 Playwright 进行端到端测试：

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

# 以 UI 模式运行
npm run test:e2e -- --ui

# 指定浏览器
npm run test:e2e -- --project=chromium
```

**测试文件示例：**

```typescript
// e2e/vue.spec.ts
import { test, expect } from '@playwright/test'

test('用户应该能够登录', async ({ page }) => {
  await page.goto('/login')
  
  // 填写登录表单
  await page.fill('input[name="username"]', 'admin')
  await page.fill('input[name="password"]', '123456')
  
  // 点击登录按钮
  await page.click('button[type="submit"]')
  
  // 等待跳转
  await page.waitForURL('/')
  
  // 验证是否登录成功
  await expect(page).toHaveURL('/')
})
```

---

## 📦 部署说明

### 构建生产版本

```bash
# 构建
npm run build

# 产物位于 dist/ 目录
```

### Nginx 配置

**nginx.conf**
```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    # gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    # 前端路由 history 模式
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass http://backend-server:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

### Docker 部署

**Dockerfile**
```dockerfile
# 构建阶段
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 生产阶段
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

**docker-compose.yml**
```yaml
version: '3.8'

services:
  web:
    build: .
    ports:
      - "80:80"
    restart: always
    networks:
      - app-network

networks:
  app-network:
    driver: bridge
```

```bash
# 构建并运行
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 环境变量配置

根据不同环境创建对应的 `.env` 文件：

**.env.production**
```env
VITE_APP_TITLE=后台管理系统
VITE_APP_BASE_API=/api
VITE_APP_BASE_URL=https://api.example.com
```

---

## ❓ 常见问题

### Q1: 如何修改端口号？

**A:** 在 `vite.config.ts` 中配置：

```typescript
export default defineConfig({
  server: {
    port: 3000,
    open: true
  }
})
```

或在 `.env.development` 中设置：

```env
VITE_APP_PORT=3000
```

### Q2: 如何解决跨域问题？

**A:** 开发环境使用代理，生产环境配置 Nginx 反向代理。

### Q3: 如何添加新页面？

**A:** 
1. 在 `src/views/` 创建页面组件
2. 在 `src/router/routes/constant.ts` 添加路由配置
3. 在菜单管理中配置菜单项

### Q4: 如何自定义主题色？

**A:** 修改 `src/assets/styles/variables.scss` 中的变量值。

### Q5: 如何添加新的 API 接口？

**A:** 
1. 在 `src/api/modules/` 创建对应的 API 文件
2. 使用 `request` 工具发送请求
3. 在组件中调用 API

### Q6: 如何实现权限控制？

**A:** 
1. 在路由配置中添加 `meta.roles`
2. 使用 `v-permission` 指令控制按钮权限
3. 使用 `useAuth` Hook 进行权限判断

### Q7: 如何优化首屏加载速度？

**A:** 
1. 路由懒加载
2. 组件异步加载
3. 开启 Gzip 压缩
4. 使用 CDN 加载第三方库
5. 图片懒加载和压缩

### Q8: 如何进行国际化？

**A:** 
1. 在 `src/locales/` 添加语言包
2. 使用 `$t()` 函数翻译文本
3. 通过 `useI18n()` 切换语言

---

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. **Fork** 本仓库
2. **创建分支**: `git checkout -b feature/your-feature`
3. **提交更改**: `git commit -m 'feat: add some feature'`
4. **推送分支**: `git push origin feature/your-feature`
5. **提交 Pull Request**

### 开发规范

- 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范
- 编写清晰的注释
- 添加必要的测试用例
- 确保代码通过 ESLint 检查
- 更新相关文档

---

## 📝 更新日志

详见 [CHANGELOG.md](./CHANGELOG.md)

---

## 📄 许可证

本项目采用 [MIT](./LICENSE) 许可证。

---

## 👥 联系方式

- 📧 Email: your-email@example.com
- 💬 Issues: [GitHub Issues](https://github.com/your-repo/issues)
- 📖 文档: [在线文档](https://your-docs-site.com)

---

## 🙏 致谢

感谢以下开源项目：

- [Vue.js](https://vuejs.org/)
- [Vite](https://vitejs.dev/)
- [TypeScript](https://www.typescriptlang.org/)
- [Pinia](https://pinia.vuejs.org/)
- [Element Plus](https://element-plus.org/)
- [ECharts](https://echarts.apache.org/)

---

<div align="center">

**Made with ❤️ by Your Team**

[⬆ 回到顶部](#企业级-web-后台管理系统)

</div>