# YAdmin

**Repository Path**: bwyxy/yadmin

## Basic Information

- **Project Name**: YAdmin
- **Description**: Vue3 + Element Plus + Pinia 后台管理系统前端，适配若依(RuoYi)后端规范，含动态路由、权限控制、代码生成、系统监控，开箱即用。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: vue3, vite

## README

# 系统管理平台（y-admin-sub）使用文档

> 基于 **Vue 3 + TypeScript + Vite + Element Plus + Pinia** 开发的前端后台管理系统，完全适配 **RuoYi（若依）** 后端接口规范，可直接对接若依后端（Spring Boot）快速投入使用。

---

## 目录

1. [项目概述与功能介绍](#一项目概述与功能介绍)
2. [环境要求与依赖项](#二环境要求与依赖项)
3. [安装与配置](#三安装与配置)
4. [基本使用流程](#四基本使用流程)
5. [关键功能模块操作指南](#五关键功能模块操作指南)
6. [常见问题解答与故障排除](#六常见问题解答与故障排除)
7. [附录](#七附录)

---

## 一、项目概述与功能介绍

### 1.1 项目简介

本项目是后台管理系统前端工程，负责与若依后端进行交互，提供统一的登录鉴权、动态路由、权限控制、数据列表增删改查、数据导出、系统监控、代码生成等功能。前端通过 `Authorization: Bearer {token}` 携带令牌访问后端，接口响应遵循若依统一格式（`{ code, msg, data }` / `{ code, msg, rows, total }`）。

### 1.2 功能列表

| 模块 | 功能 | 说明 |
| --- | --- | --- |
| 登录认证 | 账号密码登录 | 支持后端动态验证码（点击图片刷新） |
| 工作台（首页） | 项目介绍、技术栈展示 | 登录后默认进入 |
| 系统管理 | 用户 / 角色 / 菜单 / 部门 / 岗位 / 字典 / 参数设置 / 通知公告 | 常规 CRUD、批量删除、数据导出、权限控制 |
| 系统监控 | 在线用户 / 定时任务 / 调度日志 / 服务监控 / 缓存监控 / Druid 监控 | 服务监控含 CPU、内存、硬盘使用率 |
| 系统工具 | 代码生成 / Swagger 接口文档 / 表单构建 | 代码生成支持导入数据库表、预览、下载 |
| 个人中心 | 基本资料查看与修改、修改密码 | 头像上传 |
| 动态路由 | 菜单由后端 `getRouters` 下发 | 新增页面无需改前端路由代码 |
| 权限控制 | `v-hasPermi` / `v-hasRole` 指令 | 按钮级权限，无权限自动隐藏 |
| 多语言 | 中文 / English | 顶部一键切换 |
| 主题切换 | 亮色 / 暗色 | 顶部一键切换 |
| 布局能力 | PC 端菜单折叠、标签页（TagsView）、面包屑、全屏、菜单搜索 | 提升操作效率 |
| 数据导出 | 列表导出 Excel | 若依规范：POST + form-urlencoded + blob 下载 |

### 1.3 技术栈

| 类别 | 技术 |
| --- | --- |
| 框架 | Vue 3（`<script setup>` 组合式 API）、TypeScript |
| 构建 | Vite 7 |
| UI | Element Plus（含 unplugin 自动导入） |
| 状态管理 | Pinia |
| 路由 | Vue Router（hash 模式） |
| 请求 | Axios（统一拦截器、网络重试） |
| 国际化 | vue-i18n |
| 图表 | ECharts |
| 测试 | Vitest + jsdom + axios-mock-adapter |
| 图标 | @element-plus/icons-vue + vite-plugin-svg-icons（本地 SVG 库） |

---

## 二、环境要求与依赖项

### 2.1 环境要求

| 依赖 | 版本要求 | 说明 |
| --- | --- | --- |
| Node.js | **≥ 20.19**（推荐 22 LTS） | Vite 7 的硬性要求，过低版本无法启动 |
| 包管理器 | pnpm ≥ 9 | 项目使用 pnpm 管理依赖 |
| 后端服务 | 若依（RuoYi）后端，默认端口 **6190** | 提供登录、菜单、业务等接口 |
| 浏览器 | Chrome / Edge 等现代浏览器 | 生产环境建议 Chrome 90+ |

> 安装 Node.js 建议使用 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 管理版本。

### 2.2 依赖项列表

**生产依赖（dependencies）**

| 包名 | 版本 | 用途 |
| --- | --- | --- |
| vue | ^3.5.40 | 核心框架 |
| vue-router | ^5.4.0 | 路由（hash 模式） |
| pinia | ^4.0.2 | 状态管理 |
| element-plus | ^2.14.3 | UI 组件库 |
| @element-plus/icons-vue | ^2.3.2 | Element Plus 图标库 |
| axios | ^1.20.0 | HTTP 请求 |
| vue-i18n | ^9.14.4 | 国际化 |
| echarts | ^6.1.0 | 图表 |
| js-cookie | ^3.0.8 | Cookie 操作（token 存储） |
| sass | ^1.101.6 | 样式预处理器 |

**开发依赖（devDependencies）**

| 包名 | 版本 | 用途 |
| --- | --- | --- |
| vite | ^7.3.0 | 构建工具 |
| typescript | ~5.7.2 | TypeScript |
| vue-tsc | ^2.2.4 | Vue 类型检查 |
| vitest | ^5.0.3 | 单元测试框架 |
| jsdom | ^24.1.3 | 测试 DOM 环境 |
| axios-mock-adapter | ^2.1.0 | 测试接口 Mock |
| unplugin-auto-import | ^21.0.0 | API 自动导入 |
| unplugin-vue-components | ^32.1.0 | 组件自动导入 |
| vite-plugin-svg-icons | ^2.0.1 | SVG 图标雪碧图 |
| @vitejs/plugin-vue | ^5.2.4 | Vue SFC 编译 |

---

## 三、安装与配置

### 3.1 拉取代码

```bash
git clone <仓库地址> xiaee-admin
cd xiaee-admin
```

### 3.2 安装依赖

```bash
# 推荐使用 pnpm（锁定文件 pnpm-lock.yaml 已存在）
pnpm install
```

> 如未安装 pnpm：`npm install -g pnpm`。若安装慢可配置镜像：`pnpm config set registry https://registry.npmmirror.com`

### 3.3 环境配置

项目根目录有两个环境变量文件，配置后端接口地址：

**`.env.development`（开发环境）**

```ini
VITE_NODE_ENV=development
VITE_BASE_API_URL=http://localhost:6190
```

- `VITE_BASE_API_URL`：后端接口根地址。开发环境直连后端地址（后端需开启 CORS，项目 vite 已配置 `cors: true`）。

**`.env.production`（生产环境）**

```ini
VITE_NODE_ENV=production
VITE_BASE_API_URL=/api
```

- 生产环境使用相对路径 `/api`，由 Nginx 等反向代理转发到后端（并在 `vite.config.ts` 中 `base: '/admin/'`，即部署在 `/admin/` 子路径）。

> 修改环境变量后需**重启 dev server** 才能生效。

### 3.4 启动开发服务器

```bash
pnpm dev
```

默认端口 **9002**，启动后访问：

```
http://localhost:9002/admin/
```

> 若 9002 被占用，Vite 会自动递增端口（如 9003、9004），以终端输出为准。

### 3.5 生产构建与部署

```bash
# 类型检查 + 构建（产物输出到 dist/）
pnpm build

# 本地预览构建产物
pnpm preview
```

构建产物部署示例（Nginx）：

```nginx
location /admin/ {
    alias /opt/www/dist/;
    try_files $uri $uri/ /admin/index.html;
}

location /api/ {
    proxy_pass http://127.0.0.1:6190/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
```

---

## 四、基本使用流程

### 4.1 流程总览

```
启动后端(6190) → 启动前端(9002) → 登录 → 进入工作台 → 菜单导航使用各模块 → 退出登录
```

### 4.2 登录系统

1. 确认后端服务已在 `http://localhost:6190` 启动（可访问 `http://localhost:6190/captchaImage` 验证）。
2. 浏览器打开 `http://localhost:9002/admin/`，自动跳转登录页。
3. 输入**用户名**、**密码**，若后端开启了验证码，还需输入**验证码**（点击验证码图片可刷新）。
4. 点击「登 录」按钮，成功后进入工作台首页。

![登录页](docs/screenshots/login.png)

> 说明：图中验证码由后端动态生成（`GET /captchaImage` 返回 base64 图片）。若验证码区域不显示，请检查后端接口是否正常。

### 4.3 界面布局说明

登录后进入主界面，布局分为：

| 区域 | 说明 |
| --- | --- |
| 顶部导航栏 | 左侧：菜单折叠按钮、Logo、面包屑；右侧：菜单搜索、全屏、主题切换、语言切换、消息、设置、退出登录 |
| 左侧菜单栏 | 由后端 `getRouters` 动态生成，支持一级 / 多级菜单，点击「折叠按钮」可收起为纯图标模式 |
| 主内容区 | 顶部为标签页（TagsView），下方为当前页面内容 |
| 工作台首页 | 项目介绍、技术栈说明、特别鸣谢 |

### 4.4 退出登录

点击右上角「退出登录」图标，清除本地登录态后跳转登录页。

---

## 五、关键功能模块操作指南

> 各列表页遵循统一的若依交互规范：**搜索区**（label 宽 68px、输入框 240px）、**按钮区**（新增=primary、修改=success、删除=danger、导出=warning plain）、**操作列**（修改/删除/更多下拉）、**分页**（每页条数、上一页/下一页、跳页）。带权限标识的按钮受 `v-hasPermi` 控制，无权限自动隐藏。

### 5.1 系统管理

#### 5.1.1 用户管理（system/user）

- **搜索**：按用户名、手机号、状态、创建时间筛选。
- **新增/修改**：填写用户信息、选择角色，支持头像上传。
- **重置密码**：在操作列「更多」中重置指定用户密码。
- **分配角色**：在操作列「更多」中为用户分配角色。
- **状态切换**：点击「状态」列开关启用/停用账号。
- **导出**：按当前筛选条件导出用户列表 Excel。

#### 5.1.2 角色管理（system/role）

- 支持按角色名称、权限字符、状态搜索。
- 新增/编辑角色时可**分配菜单权限**（菜单树多选）与数据权限。
- 操作列提供「分配用户」入口。

#### 5.1.3 菜单管理（system/menu）

- **树形表格**：菜单以树形结构展示（目录 / 菜单 / 按钮）。
- **展开/折叠**：点击「展开/折叠」按钮切换全部子菜单展开状态。
- **新增菜单**：选择上级菜单（或主类目）、菜单类型、图标（点击图标选择器搜索）、路由地址、组件路径、权限标识、显示排序、是否显示、是否缓存、是否停用等。
- **图标选择器**：输入关键词可搜索 Element Plus 全部图标。
- 后端菜单的 `component` 字段需对应 `src/views/` 下的文件路径（如 `system/user/index`），否则登录后页面空白（见 FAQ）。

#### 5.1.4 部门管理（system/dept）

- 树形表格展示部门层级，支持展开/折叠。
- 新增/编辑时通过「上级部门」树选择器选择父级（根节点为「主类目」）。
- 支持电话、邮箱格式校验。

#### 5.1.5 岗位管理（system/post）

- 岗位的增删改查、批量删除、导出。

#### 5.1.6 字典管理（system/dict）

- **字典类型**（system/dict）：维护字典名称、字典类型、状态。
- **字典数据**（system/dict/data）：从「字典类型」进入，维护字典标签、键值、排序、回显样式（默认/成功/信息/警告/危险）、状态。

#### 5.1.7 参数设置（system/config）

- 维护系统参数（参数名称、参数键名、参数键值、系统内置 Y/N）。
- 「刷新缓存」按钮：清除后端参数缓存。

#### 5.1.8 通知公告（system/notice）

- 发布通知公告（公告标题、类型：通知/公告、状态）。
- 操作列「更多 → 查看」弹窗展示公告详情。

### 5.2 系统监控

#### 5.2.1 在线用户（monitor/online）

- 查看当前在线用户（登录地址、浏览器、操作系统、登录时间）。
- 支持「强退」指定在线用户。

#### 5.2.2 定时任务（monitor/job）

- 任务增删改查，支持 **cron 表达式**配置（编辑弹窗含表达式预览）。
- 操作列「更多 → 执行一次」手动触发任务；「更多 → 调度日志」查看该任务的执行日志。
- 「状态」开关即时启停任务，失败自动回滚。

#### 5.2.3 调度日志（monitor/jobLog）

- 展示定时任务执行日志：任务名称、任务组、执行状态（成功/失败 tag）、日志信息、执行时间。
- 支持按时间范围筛选、批量删除、清空、导出。

#### 5.2.4 服务监控（monitor/server）

- 卡片展示 **CPU 使用率、内存使用率、硬盘使用率**（进度条）。
- 下方展示服务器信息（服务器名称/操作系统/服务器IP/系统架构/项目路径）、Java 信息（版本/安装路径/运行时间）、部署信息（运行时间/项目路径/启动时间/项目名称）。

#### 5.2.5 缓存监控（monitor/cache）

- 顶部统计卡片：缓存名称数量、缓存键数量、过期键数量、缓存命中率。
- 缓存名称列表 → 点击「查看」进入缓存键列表 → 查看键对应的值、删除键。
- 「清理」按钮清空指定缓存名称 / 全部缓存。

#### 5.2.6 Druid 监控（monitor/druid）

- 进入页面后自动跳转到 Druid 数据源监控页（需后端提供 `/druid/` 访问）；若未自动跳转，点击页面中的链接手动打开。

### 5.3 系统工具

#### 5.3.1 代码生成（tool/gen）

1. **导入表**：点击「导入」，选择数据库表（`listDbTable`）导入生成配置。
2. **列表管理**：按表名称/表描述/创建时间搜索；操作列支持：
   - **预览**：预览生成的前端/后端代码。
   - **编辑**：编辑基本信息（表名、类名、功能名等）、字段信息（插入/编辑/列表/查询显示、查询方式、字典类型等）、生成信息（生成模板、包路径、模块名等）。
   - **同步**：同步数据库表结构变更。
   - **下载**：下载代码压缩包（zip）。
   - **删除**：删除生成配置。
3. **批量生成**：勾选多行后点击「生成」批量下载代码包。

#### 5.3.2 Swagger 接口文档（tool/swagger）

- 点击页面中的链接跳转到若依后端 Swagger 文档页（`/swagger-ui/index.html`）。

#### 5.3.3 表单构建（tool/build）

- 左侧组件库（文本框/多行文本/数字/下拉框/单选框/复选框/日期时间/开关）点击添加组件。
- 中间实时预览表单结构，右侧配置字段属性（label、placeholder、校验等）。
- 点击「生成配置」生成表单 JSON，可复制使用。

### 5.4 个人中心（user/profile）

- 查看基本资料（用户昵称、手机号码、邮箱、性别等），支持头像上传。
- 修改密码（需输入原密码、新密码、确认密码）。

### 5.5 通用功能

| 功能 | 位置 | 操作说明 |
| --- | --- | --- |
| 菜单折叠 | 顶部最左侧按钮 | PC 端点击后左侧菜单收起为纯图标（悬停弹出子菜单）；移动端点击打开抽屉菜单 |
| 菜单搜索 | 顶部搜索图标 | 输入菜单关键字快速跳转 |
| 全屏 | 顶部全屏图标 | 切换浏览器全屏 |
| 主题切换 | 顶部主题图标 | 亮色/暗色主题切换 |
| 语言切换 | 顶部语言图标 | 中文/English |
| 标签页 | 主内容区顶部 | 多标签切换，右键可关闭；刷新/关闭当前/关闭其他/关闭全部 |
| 面包屑 | 顶部导航 | 显示当前页面层级 |

---

## 六、常见问题解答与故障排除

### 6.1 登录后白屏 / 菜单不显示

- **原因**：后端 `getRouters` 下发的菜单 `component` 路径在 `src/views/` 下没有对应文件，`loadView` 解析失败。
- **解决**：确认菜单组件路径与视图文件一致。例如菜单配置 `component = system/user/index`，则必须有 `src/views/system/user/index.vue`。新增页面后**重新登录**刷新动态路由。
- 若为纯目录（无页面），`component` 应配置为 `Layout` 或 `ParentView`。

### 6.2 侧边栏 / 菜单页图标不显示

- 图标解析规则：优先匹配 Element Plus 图标（大小写不敏感，`monitor` 与 `Monitor` 均可），其次匹配 `src/assets/icons/svg/` 下的 SVG 文件（`#icon-{名称}`），也支持 `svg-icon:` 前缀。
- 若仍不显示：确认图标名称拼写正确，且该名称确实是 Element Plus 图标或存在同名 SVG 文件。可在菜单管理的「图标选择器」中搜索验证。

### 6.3 接口报 401 / 403 / 500

- **401**：登录态失效，系统会弹窗提示重新登录；或账号密码错误。
- **403**：当前操作没有权限，检查账号的角色/菜单权限配置。
- **500**：后端异常，按弹窗中的 `msg` 定位后端日志。
- 以上错误均会通过 Axios 拦截器统一弹出提示，无需额外处理。

### 6.4 提示「后端接口连接异常」/「系统接口请求超时」

- 确认后端服务已启动（`curl http://localhost:6190/captchaImage` 应返回 200）。
- 确认 `.env.development` 中 `VITE_BASE_API_URL` 指向正确的后端地址。
- 生产环境确认 Nginx 已正确代理 `/api`。

### 6.5 验证码图片不显示

- 后端 `GET /captchaImage` 接口异常或 CORS 未放行。
- 点击验证码图片可重新获取。若后端关闭验证码，登录页会自动隐藏验证码输入框。

### 6.6 端口被占用

- `pnpm dev` 默认 9002，被占用时 Vite 自动改用 9003/9004……，以终端输出为准。
- 也可在 `vite.config.ts` 的 `server.port` 修改默认端口。

### 6.7 导出文件报错或为空

- 若导出接口返回的是 JSON 错误体而非文件，系统会自动识别并弹出错误信息（`utils/ruoyi.ts` 已处理）。
- 确认当前账号拥有对应菜单的导出权限。

### 6.8 测试与构建失败

- 运行单元测试：`pnpm test`（Vitest，102 个用例覆盖请求拦截、API 接口、指令、store、工具函数）。
- 构建失败多为 TS 类型错误：先运行 `pnpm exec vue-tsc -b` 定位并修复后再构建。
- 依赖安装失败：删除 `node_modules` 与 `pnpm-lock.yaml` 后重新 `pnpm install`。

### 6.9 如何新增一个页面

1. 在 `src/views/` 下创建视图文件（如 `src/views/system/demo/index.vue`）。
2. 若需要接口，在 `src/api/` 下创建对应 API 模块（遵循若依 GET+query 分页、`rows/total` 响应、`download()` 导出规范）。
3. 在后端菜单管理中新增菜单，`component` 填 `system/demo/index`，路由地址 `demo`。
4. 重新登录即可看到新菜单（动态路由自动注册，无需改前端路由代码）。

---

## 七、附录

### 7.1 项目目录结构

```
xiaee-admin
├── docs/screenshots/          # 界面截图
├── src/
│   ├── api/                   # 接口定义（login/user/role/menu/.../monitor/tool）
│   │   ├── system/            # 系统管理接口（user/role/menu/dept/post/config/notice/dict）
│   │   ├── monitor/           # 系统监控接口（job/jobLog/server/cache/online/operlog/logininfor）
│   │   └── tool/              # 系统工具接口（gen/swagger）
│   ├── assets/                # 静态资源（styles、icons/svg 图标库）
│   ├── components/            # 公共组件（BaseTable/MenuIcon/IconSelect/ImageUpload/ParentView 等）
│   ├── directive/permission/  # 权限指令（hasPermi/hasRole）
│   ├── i18n/                  # 国际化（zh-CN/en-US）
│   ├── layout/                # 主布局（Header/Sidebar/TagsView/AppMain/Breadcrumb）
│   ├── router/                # 路由定义（constantRoutes/notFoundRoute）
│   ├── store/modules/         # Pinia store（user/permission/app/tagsView/theme/locale）
│   ├── utils/                 # 工具（request 拦截器/ruoyi 下载/auth/validate）
│   ├── views/                 # 页面视图（login/home/system/monitor/tool/error）
│   ├── global.d.ts            # 全局类型（AjaxResult/TableDataInfo）
│   ├── permission.ts          # 路由守卫（登录校验 + 动态路由注入）
│   └── main.ts                # 应用入口
├── tests/                     # 单元测试（api.test.ts、utils/、store/ 等）
├── .env.development           # 开发环境变量
├── .env.production            # 生产环境变量
├── vite.config.ts             # Vite 配置（端口/代理/自动导入/SVG）
└── package.json
```

### 7.2 常用命令

| 命令 | 说明 |
| --- | --- |
| `pnpm dev` | 启动开发服务器（默认 9002） |
| `pnpm build` | 类型检查 + 生产构建（输出 dist/） |
| `pnpm preview` | 预览构建产物 |
| `pnpm test` | 运行单元测试 |
| `pnpm test:watch` | 监听模式运行测试 |
| `pnpm exec vue-tsc -b` | 单独执行 TypeScript 类型检查 |

### 7.3 界面截图补充清单

以下页面需登录后（有权限账号）人工截图并放入 `docs/screenshots/`，然后在本文档相应章节插入图片：

| 目标截图 | 建议文件名 | 说明 |
| --- | --- | --- |
| 工作台首页 | `home.png` | 登录后默认页面，展示项目介绍/技术栈 |
| 用户管理 | `user.png` | 展示搜索区、按钮区、表格、分页 |
| 菜单管理 | `menu.png` | 树形表格 + 图标列 |
| 角色管理（分配菜单弹窗） | `role.png` | 展示菜单权限树 |
| 代码生成 | `gen.png` | 列表 + 编辑弹窗 |
| 服务监控 | `server.png` | CPU/内存/硬盘进度条卡片 |
| 缓存监控 | `cache.png` | 统计卡片 + 缓存列表 |
| 登录页 | `login.png` | ✅ 已提供（见 4.2 节） |

> 插入方式：在对应章节使用 Markdown 图片语法，如 `![用户管理](docs/screenshots/user.png)`。