# easy-back

**Repository Path**: Love_Noah_chen/easy-back

## Basic Information

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

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy Admin 后台管理系统 - 后端

基于 Spring Boot 3.x + MyBatis Plus + Sa-Token 的现代化企业级后台管理系统后端，采用模块化设计，支持多种文件存储策略。

## 技术栈

### 核心框架
- **Java**: JDK 21
- **Spring Boot**: 3.2.4
- **Maven**: 多模块项目管理

### 数据访问
- **MyBatis Plus**: 3.5.12 - 增强型 ORM 框架
- **MySQL**: 8.0.33 - 数据库
- **HikariCP**: 高性能数据库连接池

### 认证授权
- **Sa-Token**: 1.44.0 - 轻量级权限认证框架
- **Redis**: 分布式会话存储

### 工具库
- **Hutool**: 5.8.38 - Java 工具类库
- **Fastjson2**: 2.0.58 - JSON 处理
- **Lombok**: 1.18.30 - 简化 Java 代码

### API 文档
- **Knife4j**: 4.4.0 - 增强型 Swagger 文档

### 文件存储
- **MinIO**: 8.5.7 - 对象存储（可选）
- **本地存储**: 默认存储方式

### 其他
- **FastExcel**: 1.2.0 - Excel 导入导出
- **IP2Region**: 2.7.0 - IP 地址定位

## 项目结构

```
easy-back/
├── easy-all/                   # 主应用模块
│   └── src/
│       ├── main/
│       │   ├── java/
│       │   │   └── com/noah/easy/
│       │   │       ├── EasyApplication.java  # 启动类
│       │   │       ├── controller/           # 控制器层
│       │   │       │   ├── dict/             # 字典接口
│       │   │       │   ├── file/             # 文件管理接口
│       │   │       │   ├── login/            # 登录接口
│       │   │       │   └── system/           # 系统管理接口
│       │   │       │       ├── config/       # 系统配置
│       │   │       │       ├── dept/         # 部门管理
│       │   │       │       ├── menu/         # 菜单管理
│       │   │       │       ├── role/         # 角色管理
│       │   │       │       └── user/         # 用户管理 + 个人中心
│       │   │       ├── entity/               # 实体类
│       │   │       │   ├── domain/           # 数据库实体（DO）
│       │   │       │   │   ├── dict/         # 字典实体
│       │   │       │   │   ├── file/         # 文件实体
│       │   │       │   │   └── system/       # 系统实体
│       │   │       │   ├── dto/              # 数据传输对象（DTO）
│       │   │       │   │   ├── dict/
│       │   │       │   │   ├── file/
│       │   │       │   │   └── system/
│       │   │       │   └── vo/               # 视图对象（VO）
│       │   │       │       ├── common/       # 公共 VO
│       │   │       │       ├── login/        # 登录相关 VO
│       │   │       │       └── system/       # 系统模块 VO
│       │   │       ├── enums/                # 枚举类
│       │   │       │   ├── common/           # 公共枚举
│       │   │       │   ├── config/           # 配置枚举
│       │   │       │   ├── dict/             # 字典枚举
│       │   │       │   ├── file/             # 文件枚举
│       │   │       │   ├── login/            # 登录枚举
│       │   │       │   └── menu/             # 菜单枚举
│       │   │       ├── mapper/               # MyBatis Mapper 接口
│       │   │       │   ├── dict/             # 字典 Mapper
│       │   │       │   ├── file/             # 文件 Mapper
│       │   │       │   └── system/           # 系统 Mapper
│       │   │       ├── service/              # 业务逻辑层
│       │   │       │   ├── dict/             # 字典服务
│       │   │       │   │   └── impl/
│       │   │       │   ├── file/             # 文件服务
│       │   │       │   │   └── storage/      # 存储策略（本地/MinIO）
│       │   │       │   ├── login/            # 登录服务
│       │   │       │   │   └── strategy/     # 登录策略
│       │   │       │   └── system/           # 系统服务
│       │   │       │       └── impl/
│       │   │       ├── constants/            # 常量定义
│       │   │       ├── init/                 # 初始化组件
│       │   │       └── utils/                # 工具类
│       │   └── resources/
│       │       ├── application.yml           # 主配置文件
│       │       ├── data-source.yml           # 数据源配置
│       │       ├── sql/                      # SQL 脚本
│       │       │   └── init.sql              # 数据库初始化脚本
│       │       └── com/noah/easy/mapper/     # MyBatis XML 映射文件
│       │           ├── dict/
│       │           ├── file/
│       │           └── system/
│       └── test/                             # 测试代码
├── common/                     # 公共模块
│   ├── common-auth/           # Sa-Token 认证授权模块
│   ├── common-core/           # 核心工具模块（异常、结果、工具类）
│   ├── common-log/            # 日志模块（操作日志、登录日志）
│   ├── common-mybatis/        # MyBatis Plus 配置模块
│   ├── common-opendoc/        # Knife4j API 文档模块
│   ├── common-redis/          # Redis 配置模块
│   └── common-web/            # Web 配置模块（CORS、异常处理、i18n）
├── docs/                      # 文档目录
│   ├── 文件存储策略说明.md
│   ├── 文件上传功能说明.md
│   ├── MinIO存储启用指南.md
│   └── MinIO快速启用指南.md
└── pom.xml                    # 父 POM 文件（多模块管理）
```

## 核心功能

### 1. 用户认证
- 用户名密码登录
- 基于 Sa-Token 的权限认证
- Redis 分布式会话管理
- 自动刷新 Token
- 登录背景俄罗斯方块动画（前端）

### 2. 权限管理
- RBAC 权限模型（用户-角色-权限）
- 细粒度权限控制（菜单权限、按钮权限）
- 部门数据权限
- 动态权限加载

### 3. 系统管理
- **用户管理**: 用户增删改查、密码重置、状态管理
- **角色管理**: 角色配置、权限分配
- **部门管理**: 部门树形结构、层级管理
- **菜单管理**: 菜单树、图标管理、路由配置
- **字典管理**: 字典类型、字典项管理
- **配置管理**: 系统参数配置

### 4. 文件管理
- **多存储策略**: 本地存储、MinIO 对象存储
- **文件上传**: 单文件/批量上传
- **文件下载**: 单文件/批量下载（ZIP）
- **文件预览**: 图片预览、文档预览
- **流水号管理**: 批量文件关联

### 5. 数据字典
- 字典类型管理
- 字典项 CRUD
- 字典缓存（Redis）
- 前端字典接口

### 6. 枚举管理
- 枚举类型自动注册
- 枚举选项 API
- 前端枚举下拉框支持

### 7. 日志审计
- 操作日志记录
- 登录日志
- IP 地址定位

### 8. Excel 导入导出 代办项
- 用户数据导出
- Excel 模板下载
- FastExcel 高性能处理

## 快速开始

### 环境要求

- **JDK**: 21+
- **Maven**: 3.6+
- **MySQL**: 8.0+
- **Redis**: 5.0+
- **MinIO**: 可选，用于对象存储

### 数据库表结构

系统包含以下 11 张核心表：

| 表名 | 说明 | 主要字段 |
|-----|------|---------|
| `t_sys_user` | 系统用户表 | 用户名、密码、昵称、邮箱、部门ID等 |
| `t_sys_dept` | 部门表 | 部门编码、部门名称、父部门ID |
| `t_sys_role` | 角色表 | 角色编码、角色名称、状态 |
| `t_sys_menus` | 菜单表 | 菜单名称、菜单类型、路由路径、组件路径 |
| `t_sys_permission` | 权限表 | 权限名称、权限编码、关联菜单ID |
| `t_sys_user_role_rel` | 用户角色关联表 | 用户ID、角色ID |
| `t_sys_role_menus_rel` | 角色菜单关联表 | 角色ID、菜单ID |
| `t_sys_role_permission_rel` | 角色权限关联表 | 角色ID、权限ID |
| `t_sys_dict` | 字典表 | 字典编码、字典标签、字典值 |
| `t_sys_config` | 系统配置表 | 配置键、配置值、配置类型 |
| `t_sys_file` | 文件管理表 | 文件名、文件路径、MD5、流水号 |

### 数据库配置

1. 创建数据库：

```sql
CREATE DATABASE easy_admin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

2. 配置数据源（`src/main/resources/data-source.yml`）：

```yaml
mysql:
  host: localhost
  port: 3306
  database: easy_admin
  username: root
  password: your_password

redis:
  host: localhost
  port: 6379
  database: 0
  password: your_password  # 如果没有密码则留空或注释掉
```

### 启动步骤

#### 1. 克隆项目

```bash
git clone <repository-url>
cd easy-back
```

#### 2. 安装依赖

```bash
mvn clean install
```

#### 3. 配置文件

编辑 `easy-all/src/main/resources/data-source.yml`，配置数据库和 Redis 连接信息。

#### 4. 数据库初始化

首次启动时，系统会自动执行初始化 SQL 脚本（`src/main/resources/sql/init.sql`），创建表结构和初始数据。

**初始化内容：**
- ✅ 创建 11 张系统表
- ✅ 创建必要的索引
- ✅ 初始化超级管理员账号（admin / 123456）
- ✅ 初始化系统菜单（首页、欢迎页、系统管理等）
- ✅ 初始化角色菜单关联
- ✅ 初始化系统配置
- ✅ 初始化基础字典

可通过以下配置控制：

```yaml
app:
  db:
    init:
      enabled: true            # 是否启用自动初始化
      check-table: t_sys_user  # 检查此表是否存在
      script-location: classpath:sql/init.sql
```

**注意：** 系统会检查 `t_sys_user` 表是否存在，如果已存在则跳过初始化，避免重复执行。

#### 5. 启动应用

```bash
cd easy-all
mvn spring-boot:run
```

或在 IDE 中运行 `EasyApplication.java`。

#### 6. 访问应用

- **应用地址**: http://localhost:8080
- **API 文档**: http://localhost:8080/doc.html
- **默认账号**: admin / 123456（⚠️ 生产环境请及时修改密码）

## 配置说明

### 1. 应用配置

`application.yml`:

```yaml
server:
  port: 8080                    # 服务端口

spring:
  application:
    name: EasyApplication
  servlet:
    multipart:
      max-file-size: 100MB      # 单个文件最大 100MB
      max-request-size: 500MB   # 批量上传最大 500MB
```

### 2. 文件存储配置

#### 本地存储（默认）

```yaml
file:
  storage:
    type: local                 # 存储类型: local
  upload:
    path: /data/upload          # 本地存储路径
```

#### MinIO 存储

```yaml
file:
  storage:
    type: minio                 # 存储类型: minio
  minio:
    endpoint: http://localhost:9000
    access-key: minioadmin
    secret-key: minioadmin
    bucket-name: easy-files
```

详细说明请查看：[文件存储策略说明](docs/文件存储策略说明.md)

### 3. Sa-Token 配置

`common-auth/src/main/resources/sa-token.yml`:

```yaml
sa-token:
  token-name: authorize-token  # Token 名称（前端使用此名称）
  token-prefix: Bearer         # Token 前缀
  timeout: 86400               # Token 有效期（24小时）
  active-timeout: 1800         # Token 最低活跃时间（30分钟）
  is-concurrent: true          # 是否允许同一账号并发登录
  is-share: false              # 是否共享 Token
  token-style: uuid            # Token 风格
  is-log: false                # 是否打印日志
```

### 4. MyBatis Plus 配置

```yaml
mybatis-plus:
  mapper-locations: classpath*:mapper/**/*.xml
  type-aliases-package: com.noah.**.entity
  configuration:
    map-underscore-to-camel-case: true    # 驼峰命名转换
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      logic-delete-field: isDelete        # 逻辑删除字段
      logic-delete-value: true
      logic-not-delete-value: false
```

## API 接口

### 接口规范

所有接口统一前缀：`/api/v1`

**响应格式：**

```json
{
  "code": 20000,
  "message": "操作成功",
  "data": {}
}
```

### 主要接口模块

#### 1. 认证接口 `/api/v1`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/login` | POST | 用户登录（请求体：`{username, password, loginType}`） |
| `/logout` | GET | 退出登录 |

#### 2. 用户管理 `/api/v1/user`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/page` | POST | 用户分页列表 |
| `/add` | PUT | 新增用户 |
| `/modify` | POST | 修改用户 |
| `/delete/{userId}` | DELETE | 删除用户 |
| `/info/{userId}` | GET | 用户详情 |
| `/resetPassword` | POST | 重置密码 |

#### 3. 角色管理 `/api/v1/role`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/page` | POST | 角色分页列表 |
| `/add` | PUT | 新增角色 |
| `/modify` | POST | 修改角色 |
| `/delete/{roleId}` | DELETE | 删除角色 |
| `/info/{roleId}` | GET | 角色详情 |

#### 4. 部门管理 `/api/v1/dept`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/tree` | GET | 部门树 |
| `/page` | POST | 部门分页列表 |
| `/add` | PUT | 新增部门 |
| `/modify` | POST | 修改部门 |
| `/delete/{deptId}` | DELETE | 删除部门 |
| `/enable/{deptId}` | POST | 启用部门 |
| `/disable/{deptId}` | POST | 停用部门 |

#### 5. 菜单管理 `/api/v1/menu`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/tree` | GET | 完整菜单树 |
| `/current-user-tree` | GET | 当前用户菜单树 |
| `/current-user-permissions` | GET | 当前用户权限列表 |
| `/add` | PUT | 新增菜单 |
| `/modify` | POST | 修改菜单 |
| `/delete/{menuId}` | DELETE | 删除菜单 |
| `/info/{menuId}` | GET | 菜单详情 |

#### 6. 字典管理 `/api/v1/dict`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/list/{dictCode}` | GET | 获取字典项列表（支持 Redis 缓存） |
| `/page` | POST | 字典分页列表 |
| `/add` | PUT | 新增字典 |
| `/modify` | POST | 修改字典 |
| `/delete/{dictId}` | DELETE | 删除字典 |

#### 7. 文件管理 `/api/v1/file`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/upload` | POST | 文件上传（支持单文件/多文件/批量模式） |
| `/preview/{id}` | GET | 文件预览（需认证，返回文件流） |
| `/download/{id}` | GET | 文件下载 |
| `/download/batch/{fileSerial}` | GET | 按流水号批量下载（ZIP） |
| `/info/{id}` | GET | 获取文件信息 |
| `/list/batch/{fileSerial}` | GET | 通过流水号获取文件列表 |
| `/delete/{id}` | DELETE | 删除文件 |

#### 8. 个人中心 `/api/v1/profile`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/info` | GET | 获取当前用户信息 |
| `/update` | POST | 更新个人信息 |
| `/updatePassword` | POST | 修改密码 |

#### 9. 系统配置 `/api/v1/system/config`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/getSystemName` | GET | 获取系统名称 |
| `/getByKey/{key}` | GET | 根据键获取配置值 |
| `/page` | POST | 配置分页列表 |
| `/modify` | POST | 修改配置 |

#### 10. 枚举接口 `/api/v1/enum`

| 接口 | 方法 | 说明 |
|-----|------|-----|
| `/options/{enumName}` | GET | 获取枚举选项（支持缓存） |

详细接口文档请访问：http://localhost:8080/doc.html

## 核心特性

### 1. 策略模式文件存储

支持本地存储和 MinIO 对象存储，通过配置切换，无需修改代码。

```java
// 自动根据配置选择存储策略
FileStorageStrategy strategy = strategyFactory.getStrategy(storageType);
strategy.uploadFile(file);
```

### 2. 自动数据库初始化

首次启动自动创建表结构和初始数据，开箱即用。

### 3. 统一异常处理

全局异常拦截，统一返回格式。

```java
@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    public Result handleBusinessException(BusinessException e) {
        return Result.error(e.getMessage());
    }
}
```

### 4. Redis 缓存

字典数据、用户权限等热点数据使用 Redis 缓存，提升性能。

### 5. 国际化支持

⚠ 此功能为代办项

```java
// i18n 资源文件位于 common-web/src/main/resources/i18n/
// messages.properties (默认)
// messages_zh_CN.properties (中文)
// messages_en_US.properties (英文)

@Resource
private MessageSource messageSource;

String message = messageSource.getMessage("error.user.not.found", null, locale);
```

**注意**: 当前版本国际化功能已实现基础架构，完整的多语言支持在计划中。

### 6. 数据权限

基于部门的数据权限控制。

### 7. Excel 导入导出
⚠ 该功能未实现，目前为代办项
使用 FastExcel 实现高性能 Excel 处理。

## 开发指南

### 新增模块

1. 在 `entity/domain` 创建实体类
2. 在 `mapper` 创建 Mapper 接口
3. 在 `service` 创建 Service 接口和实现类
4. 在 `controller` 创建 Controller
5. 在 `entity/vo` 和 `entity/dto` 创建视图对象和数据传输对象

### 代码规范

- 使用 Lombok 简化代码
- Service 层处理业务逻辑
- Controller 层只做参数校验和转发
- 使用 DTO/VO 模式分离数据传输

### 日志规范

```java
@Slf4j
public class UserService {
    public void updateUser(UserDTO dto) {
        log.info("更新用户: {}", dto);
        // 业务逻辑
    }
}
```

## 常见问题

### 1. 启动失败：数据库连接错误

检查 `data-source.yml` 中的数据库配置是否正确。

### 2. Redis 连接失败

确保 Redis 服务已启动，检查 Redis 配置。

### 3. 文件上传失败

- 检查文件大小是否超过限制（默认 100MB）
- 检查上传路径是否有写入权限
- 如使用 MinIO，检查 MinIO 服务是否正常

### 4. Token 失效

检查 Sa-Token 配置的 timeout 和 active-timeout。

### 5. 跨域问题

系统已配置全局跨域，如有问题检查 `common-web` 模块的 CORS 配置。

## 项目文档

- [文件存储策略说明](docs/文件存储策略说明.md)
- [文件上传功能说明](docs/文件上传功能说明.md)
- [MinIO 存储启用指南](docs/MinIO存储启用指南.md)
- [MinIO 快速启用指南](docs/MinIO快速启用指南.md)

## 性能优化

### 1. 数据库优化
- 合理使用索引
- 分页查询避免全表扫描
- 使用 MyBatis Plus 的 LambdaWrapper 避免魔法值

### 2. Redis 缓存
- 字典数据缓存
- 用户权限缓存
- 合理设置过期时间

### 3. 连接池优化
- HikariCP 连接池参数调优
- Redis 连接池配置

## 许可证

MIT License

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

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

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