yiciheng/freedom-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README

Browse Source
This commit is contained in:
张家训
2026-08-20 10:54:32 +08:00
parent 069fc85579
commit 9184e00c9e
1 changed files with 75 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+72 -169
View File
@@ -1,73 +1,62 @@
# Freedom Admin 管理系统 # Freedom Admin
## 项目简介 基于 **Spring Boot 2.7.10** 的后台管理系统后端服务，提供用户、角色、部门、权限等基础管理能力，并内置基于 Beetl 模板引擎的代码生成器。
Freedom Admin 是一个基于 Spring Boot 2.7.10 的后台管理系统，集成了 Spring Security、MyBatis-Plus、Thymeleaf 等主流技术栈，提供完整的代码生成器、邮件发送、用户管理等功能。
## 技术栈 ## 技术栈
- **后端框架**: Spring Boot 2.7.10 | 分类 | 技术 |
- **安全框架**: Spring Security 3.3.2 | ---- | ---- |
- **ORM 框架**: MyBatis-Plus 3.5.7 | 核心框架 | Spring Boot 2.7.10 |
- **模板引擎**: Thymeleaf | 安全框架 | Spring Security 3.3.2 + JWT（jjwt 0.9.1） |
- **数据库**: MySQL 8.0.33 | ORM | MyBatis-Plus 3.5.7 + PageHelper 2.1.0 |
- **连接池**: HikariCP | 模板引擎 | Thymeleaf（登录页等）、Beetl 3.16.2（代码生成） |
- **权限管理**: JWT 认证 | 数据库 | MySQL 8.0（utf8mb4） |
- **邮件服务**: Spring Mail | 连接池 | HikariCP |
- **代码生成**: Beetl 模板引擎 | 其他 | Lombok、Fastjson、Guava、Spring Mail |
## 项目结构 ## 项目结构
``` ```
freedom-admin
├── sql/
│ └── init.sql # 数据库初始化脚本（建库建表 + 基础数据）
├── src/main/java/com/freedom/admin/ ├── src/main/java/com/freedom/admin/
│ ├── AdminApplication.java # 应用启动类 │ ├── AdminApplication.java # 启动类
│ ├── base/ # 基础类 │ ├── base/ # 基础类与通用返回结构
│ ├── common/ # 通用工具类 │ ├── common/ # 通用常量 / 工具
│ ├── config/ # 配置类 │ ├── config/ # Spring Security、JWT 等配置
│ ├── controller/ # 控制器层 │ ├── controller/ # 控制器层
│ ├── entity/ # 实体类 │ ├── entity/ # 实体类
│ ├── mapper/ # 数据访问层 │ ├── mapper/ # MyBatis-Plus Mapper
│ ├── service/ # 服务层 │ ├── service/ # 业务层
│ └── util/ # 工具类 │ └── util/ # 工具类
├── src/main/resources/ └── src/main/resources/
│ ├── mapper/ # MyBatis 映射文件 ├── mapper/ # MyBatis XML 映射文件
│ ├── btl/ # 代码生成模板 ├── btl/ # 代码生成 Beetl 模板
│ └── application.yml # 配置文件 ├── logback-spring.xml # 日志配置（控制台 UTF-8）
├── sql/ └── application.yml # 应用配置
│ └── init.sql # 数据库初始化脚本
└── pom.xml # Maven 依赖配置
``` ```
## 数据模型
| 表 | 说明 |
| -- | ---- |
| `t_sys_user` | 用户表（BCRYPT 密码加密） |
| `t_sys_dept` | 部门表（支持树形层级） |
| `t_sys_role` | 角色表 |
| `t_sys_permission` | 权限 / 菜单表（动态路由数据源） |
| `t_sys_user_role` | 用户-角色关联表 |
| `t_sys_role_permission` | 角色-权限关联表 |
## 功能特性 ## 功能特性
### 1. 用户管理 - **用户管理**：用户注册、登录、JWT 认证、信息维护
- 用户注册、登录、权限管理 - **角色管理**：角色 CRUD、角色-权限绑定
- JWT 认证机制 - **部门管理**：树形部门结构
- 用户信息维护 - **权限管理**：菜单 / 权限点维护，驱动前端动态路由
- **代码生成器**：读取数据库表结构，一键生成 Controller / Service / Mapper / Entity / Vue 等全套代码
### 2. 代码生成器 - **邮件服务**：基于 Spring Mail 的邮件发送能力
- 基于 Beetl 模板引擎 - **系统特性**：统一异常处理、PageHelper 分页、逻辑删除、接口权限控制
- 支持前后端代码自动生成
- 可自定义生成规则和模板
- 生成 Controller、Service、Mapper、Entity、Vue 等文件
### 3. 邮件服务
- 邮件验证码发送
- 注册邮件通知
- 可配置的邮件模板
### 4. 数据管理
- 系统部门管理
- 活动信息管理
- 药品信息管理
- 订单信息管理
- 病例本管理
### 5. 系统特性
- 统一异常处理
- 分页插件支持
- 逻辑删除
- 接口权限控制
## 快速开始 ## 快速开始
@@ -77,150 +66,64 @@ Freedom Admin 是一个基于 Spring Boot 2.7.10 的后台管理系统，集成
- Maven 3.6.3+ - Maven 3.6.3+
- MySQL 8.0+ - MySQL 8.0+
### 数据库配置 ### 1. 初始化数据库
1. 创建数据库：
```sql
CREATE DATABASE demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
2. 执行初始化脚本：
```bash ```bash
mysql -u root -p demo < sql/init.sql mysql -u root -p < sql/init.sql
``` ```
### 配置文件 脚本会自动创建 `freedom_db` 数据库、全部业务表并写入基础数据（默认管理员账号 `admin` / `123456`）。
修改 `src/main/resources/application.yml` 中的数据库连接信息： ### 2. 修改数据库配置
编辑 `src/main/resources/application.yml`：
```yaml ```yaml
spring: spring:
datasource: datasource:
url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=UTC url: jdbc:mysql://localhost:3306/freedom_db?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
username: root username: root
password: 123456 password: your_password
``` ```
### 运行项目 ### 3. 启动服务
```bash ```bash
# 使用 Maven 运行 # 开发运行
mvn spring-boot:run mvn spring-boot:run
# 或者打包后运行 # 或打包运行
mvn clean package mvn clean package -DskipTests
java -jar target/freedom-admin-1.0.1.jar java -jar target/freedom-admin-1.0.1.jar
``` ```
项目启动后访问：http://localhost:8800 > Windows 下可直接使用 `start.bat` 启动（已自动设置控制台 UTF-8 编码，避免中文日志乱码）。
## 代码生成器使用 启动后服务地址：`http://localhost:8800`
### 1. 查询数据库表 ## 代码生成器 API
| 接口 | 方法 | 说明 |
| ---- | ---- | ---- |
| `/generator/findListWithPage` | GET | 分页查询数据库表列表 |
| `/generator/getTableSelectList` | GET | 获取表下拉列表 |
| `/generator/execute` | POST | 执行代码生成 |
生成参数示例：
```bash
GET /generator/findListWithPage?pageNum=1&pageSize=10
``` ```
### 2. 获取表下拉列表
```bash
GET /generator/getTableSelectList
```
### 3. 执行代码生成
```bash
POST /generator/execute POST /generator/execute
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
tableName=your_table_name&ruleStr=[{"rule":"value"}] tableName=your_table_name&ruleStr=[{"rule":"value"}]
``` ```
## API 接口 ## 注意事项
### 认证相关 - JWT 密钥与过期时间在 `application.yml` 的 `jwt` 节点配置，生产环境请务必更换密钥。
- 用户登录 - 邮件授权码请使用邮箱服务商提供的 SMTP 授权码，勿直接使用登录密码。
- Token 刷新 - 表 / 列中文注释建议使用 UTF-8 编码执行脚本，避免乱码入库。
- 权限验证
### 用户管理 ## License
- 用户注册
- 用户信息查询
- 用户信息修改
### 邮件服务 本项目仅用于内部学习与研究使用。
- 发送验证码
- 注册邮件通知
### 数据管理
- 部门管理
- 活动管理
- 药品管理
- 订单管理
## 开发指南
### 添加新功能模块
1. 在 `entity` 包下创建实体类
2. 在 `mapper` 包下创建 Mapper 接口
3. 在 `service` 包下创建 Service 接口和实现类
4. 在 `controller` 包下创建 Controller 类
5. 在 `resources/mapper` 下创建对应的 XML 映射文件
### 权限配置
在 Controller 方法上使用注解控制权限：
```java
@PermitAll // 允许所有用户访问
@PreAuthorize("hasRole('ADMIN')") // 需要管理员权限
```
## 部署说明
### 生产环境配置
1. 修改数据库连接为生产环境地址
2. 配置 JWT 密钥
3. 配置邮件服务器信息
4. 设置日志级别和路径
### 安全建议
- 定期更换 JWT 密钥
- 使用 HTTPS 协议
- 配置防火墙规则
- 定期备份数据库
## 常见问题
### Q: 项目启动失败，提示数据库连接错误
A: 检查 application.yml 中的数据库配置是否正确，确保数据库服务已启动
### Q: 代码生成器无法生成文件
A: 检查模板文件路径和项目路径配置，确保有写入权限
### Q: 邮件发送失败
A: 检查邮件服务器配置，包括 SMTP 主机、端口、用户名和授权码
## 贡献指南
1. Fork 本仓库
2. 创建新的功能分支
3. 提交代码变更
4. 创建 Pull Request
## 许可证
本项目仅用于内部学习和研究使用。
## 联系方式
- 项目作者: zhangjiaxun
- 邮箱: 732128096@qq.com
---
*项目最后更新: 2024年4月*