# Huima Admin
**基于 Vue 3 + Spring Boot 3 的企业级全栈快速开发框架**
前后端分离 | 动态权限 | 数据隔离 | 多主题 | 暗黑模式
[](LICENSE)
[](https://openjdk.org/)
[](https://spring.io/projects/spring-boot)
[](https://vuejs.org/)
[](https://element-plus.org/)
[](https://www.typescriptlang.org/)
---
## 简介
Huima Admin 是一套开箱即用的企业级后台管理系统，涵盖用户管理、角色管理、菜单管理、部门管理、审计日志、数据权限等核心功能。项目参考 [Vben Admin](https://www.vben.pro/) 设计风格，提供了完整的权限模型和丰富的 UI 交互体验，适用于中后台业务系统的快速搭建。
## 核心特性
- **权限模型** - 基于 Sa-Token 实现页面级 + 按钮级权限控制，支持 `@SaCheckPermission` 注解和 `v-permission` / `v-role` 前端指令
- **数据权限** - 通过 `@DataScope` AOP 注解实现行级数据隔离，支持全部数据、本部门及子部门、本部门、仅本人四种策略
- **审计日志** - `@AuditLog` 注解自动记录操作日志，包含操作人、模块、请求参数、执行耗时、异常信息
- **动态路由** - 后端返回菜单数据，前端动态生成路由和导航菜单，无需硬编码
- **主题系统** - 支持蓝/绿/紫/橙四种主题色切换，暗黑模式带 View Transition 圆形扩散动画
- **多种布局** - 垂直布局、水平布局、双列布局等多种布局模式可选
- **MyBatis-Plus 分页** - 统一封装的后端分页，自动 LIMIT / COUNT，零手动计算
## 技术栈
### 后端
| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.2.0 | 应用框架 |
| Sa-Token | 1.37.0 | 权限认证 |
| MyBatis-Plus | 3.5.5 | ORM 框架 |
| MySQL | 5.7+ | 关系型数据库 |
| Redis | 6.0+ | 缓存 / Token 存储 |
| Druid | 1.2.20 | 数据库连接池 |
| Hutool | 5.8.23 | Java 工具库 |
| Lombok | - | 代码简化 |
### 前端
| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.4 | 渐进式 JS 框架 |
| TypeScript | 5.3 | 类型安全 |
| Vite | 5.0 | 构建工具 |
| Element Plus | 2.5 | UI 组件库 |
| Pinia | 2.1 | 状态管理 |
| Vue Router | 4.2 | 路由管理 |
| Axios | 1.6 | HTTP 客户端 |
| Sass | 1.70 | CSS 预处理器 |
## 项目结构
```
huima-framework/
├── huima-server/ # 后端 Spring Boot
│ ├── src/main/java/com/huima/admin/
│ │ ├── auth/ # 认证模块 (登录/登出/用户信息)
│ │ ├── common/ # 公共组件
│ │ │ ├── annotation/ # 自定义注解 (@AuditLog, @DataScope)
│ │ │ ├── aspect/ # AOP 切面 (审计日志, 数据权限)
│ │ │ ├── exception/ # 全局异常处理
│ │ │ ├── request/ # 通用请求模型
│ │ │ ├── result/ # 统一响应封装 (Result, PageResult)
│ │ │ └── security/ # 安全工具
│ │ ├── config/ # 配置类 (MyBatis-Plus, Sa-Token)
│ │ └── system/ # 业务模块
│ │ ├── controller/ # REST 接口
│ │ ├── entity/ # 实体类
│ │ ├── mapper/ # 数据访问层
│ │ └── service/ # 业务逻辑层
│ └── src/main/resources/
│ ├── application.yml # 应用配置
│ ├── db/schema.sql # 数据库结构
│ └── sql/init.sql # 初始化数据
│
├── huima-web/ # 前端 Vue 3
│ ├── src/
│ │ ├── api/ # API 接口层
│ │ ├── layouts/ # 布局组件 (Header, Sidebar, Tabs, Footer)
│ │ ├── views/ # 页面组件
│ │ │ ├── dashboard/ # 仪表盘
│ │ │ ├── login/ # 登录页
│ │ │ ├── system/ # 系统管理 (用户/角色/菜单/部门/审计日志)
│ │ │ └── demo/ # 演示功能 (权限/数据权限/商品)
│ │ ├── stores/ # Pinia 状态管理
│ │ ├── router/ # 路由配置 (动态路由)
│ │ ├── directives/ # 自定义指令 (v-permission, v-role)
│ │ ├── types/ # TypeScript 类型定义
│ │ └── styles/ # 全局样式 / CSS 变量
│ ├── index.html
│ ├── vite.config.ts
│ └── package.json
│
├── LICENSE
└── README.md
```
## 快速开始
### 环境要求
| 环境 | 版本 |
|------|------|
| JDK | >= 17 |
| Node.js | >= 18 |
| MySQL | >= 5.7 |
| Redis | >= 6.0 |
| Maven | >= 3.8 |
### 1. 克隆项目
```bash
git clone https://github.com/your-org/huima-framework.git
cd huima-framework
```
### 2. 初始化数据库
创建数据库并导入初始化脚本：
```sql
CREATE DATABASE huima_framework DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```
```bash
mysql -u root -p huima_framework < huima-server/src/main/resources/sql/init.sql
```
### 3. 配置后端
编辑 `huima-server/src/main/resources/application.yml`，修改数据库和 Redis 连接信息：
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/huima_framework?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
username: root
password: your_password
data:
redis:
host: localhost
port: 6379
```
### 4. 启动后端
```bash
cd huima-server
mvn clean compile
mvn spring-boot:run
```
后端服务运行在 http://localhost:8080
### 5. 启动前端
```bash
cd huima-web
npm install
npm run dev
```
前端服务运行在 http://localhost:3000
### 6. 访问系统
打开浏览器访问 http://localhost:3000 ，使用以下账号登录：
| 账号 | 密码 | 角色 | 数据权限 |
|------|------|------|----------|
| admin | 123456 | 超级管理员 | 全部数据 |
| zhangsan | 123456 | 管理员 | 本部门及子部门 |
| lisi | 123456 | 普通用户 | 仅本人数据 |
## 功能模块
### 系统管理
| 功能 | 说明 |
|------|------|
| 用户管理 | 用户增删改查、批量操作、状态切换、密码重置、角色分配 |
| 角色管理 | 角色配置、菜单权限绑定、数据权限策略设置 |
| 菜单管理 | 动态菜单配置、支持目录/菜单/按钮三级权限 |
| 部门管理 | 树形部门结构、支持多级部门 |
| 审计日志 | 操作日志自动记录、支持按模块/操作人/时间范围检索 |
### 数据权限
通过 `@DataScope` 注解实现自动的行级数据过滤：
| 策略 | 说明 |
|------|------|
| ALL | 查看全部数据 |
| DEPT_AND_CHILD | 查看本部门及子部门数据 |
| DEPT | 仅查看本部门数据 |
| SELF | 仅查看本人数据 |
```java
@DataScope(deptAlias = "g", userAlias = "g")
public PageResult