From 9184e00c9e993c92bb664364be533ace1043fb7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=A0=E5=AE=B6=E8=AE=AD?= Date: Thu, 20 Aug 2026 10:54:32 +0800 Subject: [PATCH] docs: rewrite README --- README.md | 247 +++++++++++++++++------------------------------------- 1 file changed, 75 insertions(+), 172 deletions(-) diff --git a/README.md b/README.md index 4b21fa3..d06cabc 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,62 @@ -# Freedom Admin 管理系统 +# Freedom Admin -## 项目简介 - -Freedom Admin 是一个基于 Spring Boot 2.7.10 的后台管理系统，集成了 Spring Security、MyBatis-Plus、Thymeleaf 等主流技术栈，提供完整的代码生成器、邮件发送、用户管理等功能。 +基于 **Spring Boot 2.7.10** 的后台管理系统后端服务，提供用户、角色、部门、权限等基础管理能力，并内置基于 Beetl 模板引擎的代码生成器。 ## 技术栈 -- **后端框架**: Spring Boot 2.7.10 -- **安全框架**: Spring Security 3.3.2 -- **ORM 框架**: MyBatis-Plus 3.5.7 -- **模板引擎**: Thymeleaf -- **数据库**: MySQL 8.0.33 -- **连接池**: HikariCP -- **权限管理**: JWT 认证 -- **邮件服务**: Spring Mail -- **代码生成**: Beetl 模板引擎 +| 分类 | 技术 | +| ---- | ---- | +| 核心框架 | Spring Boot 2.7.10 | +| 安全框架 | Spring Security 3.3.2 + JWT（jjwt 0.9.1） | +| ORM | MyBatis-Plus 3.5.7 + PageHelper 2.1.0 | +| 模板引擎 | Thymeleaf（登录页等）、Beetl 3.16.2（代码生成） | +| 数据库 | MySQL 8.0（utf8mb4） | +| 连接池 | HikariCP | +| 其他 | Lombok、Fastjson、Guava、Spring Mail | ## 项目结构 ``` -├── src/main/java/com/freedom/admin/ -│ ├── AdminApplication.java # 应用启动类 -│ ├── base/ # 基础类 -│ ├── common/ # 通用工具类 -│ ├── config/ # 配置类 -│ ├── controller/ # 控制器层 -│ ├── entity/ # 实体类 -│ ├── mapper/ # 数据访问层 -│ ├── service/ # 服务层 -│ └── util/ # 工具类 -├── src/main/resources/ -│ ├── mapper/ # MyBatis 映射文件 -│ ├── btl/ # 代码生成模板 -│ └── application.yml # 配置文件 +freedom-admin ├── sql/ -│ └── init.sql # 数据库初始化脚本 -└── pom.xml # Maven 依赖配置 +│ └── init.sql # 数据库初始化脚本（建库建表 + 基础数据） +├── src/main/java/com/freedom/admin/ +│ ├── AdminApplication.java # 启动类 +│ ├── base/ # 基础类与通用返回结构 +│ ├── common/ # 通用常量 / 工具 +│ ├── config/ # Spring Security、JWT 等配置 +│ ├── controller/ # 控制器层 +│ ├── entity/ # 实体类 +│ ├── mapper/ # MyBatis-Plus Mapper +│ ├── service/ # 业务层 +│ └── util/ # 工具类 +└── src/main/resources/ + ├── mapper/ # MyBatis XML 映射文件 + ├── btl/ # 代码生成 Beetl 模板 + ├── logback-spring.xml # 日志配置（控制台 UTF-8） + └── application.yml # 应用配置 ``` +## 数据模型 + +| 表 | 说明 | +| -- | ---- | +| `t_sys_user` | 用户表（BCRYPT 密码加密） | +| `t_sys_dept` | 部门表（支持树形层级） | +| `t_sys_role` | 角色表 | +| `t_sys_permission` | 权限 / 菜单表（动态路由数据源） | +| `t_sys_user_role` | 用户-角色关联表 | +| `t_sys_role_permission` | 角色-权限关联表 | + ## 功能特性 -### 1. 用户管理 -- 用户注册、登录、权限管理 -- JWT 认证机制 -- 用户信息维护 - -### 2. 代码生成器 -- 基于 Beetl 模板引擎 -- 支持前后端代码自动生成 -- 可自定义生成规则和模板 -- 生成 Controller、Service、Mapper、Entity、Vue 等文件 - -### 3. 邮件服务 -- 邮件验证码发送 -- 注册邮件通知 -- 可配置的邮件模板 - -### 4. 数据管理 -- 系统部门管理 -- 活动信息管理 -- 药品信息管理 -- 订单信息管理 -- 病例本管理 - -### 5. 系统特性 -- 统一异常处理 -- 分页插件支持 -- 逻辑删除 -- 接口权限控制 +- **用户管理**：用户注册、登录、JWT 认证、信息维护 +- **角色管理**：角色 CRUD、角色-权限绑定 +- **部门管理**：树形部门结构 +- **权限管理**：菜单 / 权限点维护，驱动前端动态路由 +- **代码生成器**：读取数据库表结构，一键生成 Controller / Service / Mapper / Entity / Vue 等全套代码 +- **邮件服务**：基于 Spring Mail 的邮件发送能力 +- **系统特性**：统一异常处理、PageHelper 分页、逻辑删除、接口权限控制 ## 快速开始 @@ -77,150 +66,64 @@ Freedom Admin 是一个基于 Spring Boot 2.7.10 的后台管理系统，集成 - Maven 3.6.3+ - MySQL 8.0+ -### 数据库配置 +### 1. 初始化数据库 -1. 创建数据库： -```sql -CREATE DATABASE demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -``` - -2. 执行初始化脚本： ```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 spring: 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 - password: 123456 + password: your_password ``` -### 运行项目 +### 3. 启动服务 ```bash -# 使用 Maven 运行 +# 开发运行 mvn spring-boot:run -# 或者打包后运行 -mvn clean package +# 或打包运行 +mvn clean package -DskipTests 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 Content-Type: application/x-www-form-urlencoded tableName=your_table_name&ruleStr=[{"rule":"value"}] ``` -## API 接口 +## 注意事项 -### 认证相关 -- 用户登录 -- Token 刷新 -- 权限验证 +- JWT 密钥与过期时间在 `application.yml` 的 `jwt` 节点配置，生产环境请务必更换密钥。 +- 邮件授权码请使用邮箱服务商提供的 SMTP 授权码，勿直接使用登录密码。 +- 表 / 列中文注释建议使用 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月* \ No newline at end of file +本项目仅用于内部学习与研究使用。