# SmartAdPlatform-server

**Repository Path**: panrobot/smart-ad-platform-server

## Basic Information

- **Project Name**: SmartAdPlatform-server
- **Description**: SmartAdPlatform-server：一个专注于广告投放平台后端开发的开源项目，提供高效稳定的广告管理与投放解决方案，支持多种广告格式和精准 targeting。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-02-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# Smart Ad Platform Server

**智能广告平台后端服务系统**

[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.org/projects/jdk/17/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4.10-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Gitee](https://img.shields.io/badge/Gitee-0.0.1-red.svg)](https://gitee.com/panrobot/smart-ad-platform-server)

一款基于 Spring Boot 3.4.10 的企业级智能广告平台后端系统，采用单体架构设计，提供完整的用户权限管理、邮箱账号池、智能安全防护、异步日志处理等核心功能。

[功能特性](#核心特性) • [快速开始](#快速开始) • [项目结构](#项目结构) • [API文档](#api文档)

</div>

---

## 📖 项目简介

Smart Ad Platform Server 是一个功能完善的企业级后端项目，采用 RBAC 权限模型，集成了邮箱账号池、智能安全防护、异步日志处理等先进特性。项目代码规范、注释详细、架构清晰，非常适合作为毕业设计、学习参考或企业项目的基础框架。

### 版本信息

- **当前版本：** v2.1
- **项目状态：** 活跃开发中
- **最后更新：** 2026-01-27

---

## ✨ 核心特性

### 🔐 权限管理系统
- **RBAC 权限模型** - 用户-角色-权限三层分离，支持菜单、按钮、接口三种权限类型
- **多用户类型支持** - 广告主、流量主、管理员
- **权限缓存机制** - Redis 缓存 + 数据库热查询，实时权限更新，高性能
- **会话管理** - 支持单点登录、多点登录控制、踢人下线

### 📧 邮箱账号池系统（v2.1 新增）
- **账号池管理** - 支持多个邮箱账号管理与动态切换
- **策略模式** - 轮询策略、最少发送策略、加权随机策略
- **模板渲染** - 基于 Thymeleaf 的邮件模板动态渲染
- **场景化管理** - 支持不同业务场景的邮件模板配置
- **智能降级** - 邮件发送失败自动降级处理

### 🛡️ 智能安全防护
- **IP 黑名单机制**
  - 临时黑名单（Redis 缓存，自动过期）
  - 永久黑名单（数据库持久化）
  - 反复拉黑自动升级为永久拉黑
- **智能限流** - 滑动窗口算法，基于 IP 的请求频率限制
- **恶意行为检测**
  - SQL 注入检测
  - XSS 攻击检测
  - 路径遍历检测
  - 可疑 User-Agent 识别

### 📊 异步日志系统（v1.8 新增）
- **RabbitMQ 消息队列** - 业务日志队列、接口日志队列
- **降级策略** - MQ 故障时自动降级到数据库存储
- **日志分类** - 业务日志、接口日志、系统日志、错误日志
- **链路追踪** - 支持 trace_id 追踪

### ⚙️ 系统配置中心
- **热更新机制** - 配置修改后无需重启，自动刷新 Redis 缓存
- **配置化管理** - 所有系统参数通过数据库配置
- **分类管理** - IP 限流、权限缓存、邮箱策略等配置独立管理

### 🔍 完善的 API 文档
- **Knife4j 增强** - 基于 Swagger 3.0 的 API 文档增强工具
- **在线调试** - 支持接口在线测试
- **中文界面** - 符合国内开发者使用习惯

---

## 🛠️ 技术栈

### 核心框架
| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 17 | 编程语言 |
| Spring Boot | 3.4.10 | 应用框架 |
| Maven | - | 项目构建工具 |

### 数据库相关
| 技术 | 版本 | 说明 |
|------|------|------|
| MySQL | 8.0.33 | 关系型数据库 |
| MyBatis-Plus | 3.5.6 | 持久层框架 |
| Redis | - | 缓存与 Session 存储 |
| HikariCP | - | 数据库连接池 |

### 权限认证
| 技术 | 版本 | 说明 |
|------|------|------|
| Sa-Token | 1.44.0 | 轻量级权限认证框架 |
| Sa-Token-Redis | 1.44.0 | 分布式 Session 支持 |

### 消息队列
| 技术 | 版本 | 说明 |
|------|------|------|
| RabbitMQ | - | 异步日志处理 |

### 文件存储
| 技术 | 版本 | 说明 |
|------|------|------|
| 阿里云 OSS | 3.1.0 | 对象存储服务 |

### 邮件服务
| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Mail | 3.3.4 | 邮件发送 |
| Thymeleaf | 3.1.2.RELEASE | 邮件模板引擎 |

### 工具类库
| 技术 | 版本 | 说明 |
|------|------|------|
| Lombok | 1.18.38 | 代码简化 |
| Fastjson | 1.2.83 | JSON 处理 |
| Knife4j | 4.4.0 | API 文档增强 |
| Commons Pool2 | - | Redis 连接池 |
| Spring AOP | - | 切面编程 |

### 验证与短信
| 技术 | 版本 | 说明 |
|------|------|------|
| 阿里云短信 | 2.0.0 | 短信验证码 |
| Spring Validation | - | 参数校验 |

---

## 🚀 快速开始

### 环境要求

- **JDK:** 17+
- **Maven:** 3.6+
- **MySQL:** 8.0+
- **Redis:** 6.0+
- **RabbitMQ:** 3.8+

### 克隆项目

```bash
git clone https://gitee.com/panrobot/smart-ad-platform-server.git
cd SmartAdPlatform-server
```

### 数据库初始化

1. 创建数据库 `smart_ad`
2. 执行 SQL 脚本

```sql
-- 创建数据库
CREATE DATABASE smart_ad CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 使用数据库
USE smart_ad;

-- 执行初始化脚本
SOURCE src/main/resources/sql/smart_ad.sql;
```

### 配置文件修改

编辑 `src/main/resources/application.yml` 文件：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/smart_ad?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root  # 修改为你的数据库用户名
    password: your_password  # 修改为你的数据库密码

  data:
    redis:
      host: localhost
      port: 6379
      password: 123456  # 修改为你的 Redis 密码

  rabbitmq:
    host: 127.0.0.1
    port: 5672
    username: guest  # 修改为你的 RabbitMQ 用户名
    password: guest  # 修改为你的 RabbitMQ 密码
```

### 启动项目

#### 方式一：IDEA 启动

1. 打开 IDEA，导入项目
2. 配置 Maven（JDK 17）
3. 运行 `SmartAdPlatformServerApplication.java`

#### 方式二：Maven 命令启动

```bash
# 编译打包
mvn clean package

# 运行项目
java -jar target/SmartAdPlatform-server-0.0.1-SNAPSHOT.jar
```

### 访问项目

- **应用地址：** http://localhost:8080
- **Swagger UI：** http://localhost:8080/swagger-ui.html
- **Knife4j 文档：** http://localhost:8080/doc.html

---

## 📁 项目结构

```
SmartAdPlatform-server/
├── src/main/
│   ├── java/com/smartadplatformserver/
│   │   ├── common/                    # 公共模块
│   │   │   ├── annotation/           # 自定义注解
│   │   │   ├── constant/             # 常量定义
│   │   │   ├── exception/            # 异常类
│   │   │   ├── filter/               # 过滤器
│   │   │   ├── handler/              # 全局异常处理器
│   │   │   ├── interceptor/          # 拦截器（IP限流、日志收集）
│   │   │   └── Result.java           # 统一返回结果类
│   │   ├── config/                    # 配置类
│   │   │   ├── ApplicationStartupRunner.java  # 启动检查程序
│   │   │   ├── AsyncConfig.java               # 异步配置
│   │   │   ├── MybatisPlusConfig.java         # MP配置
│   │   │   ├── OssConfig.java                 # OSS配置
│   │   │   ├── RabbitMQConfig.java            # MQ配置
│   │   │   ├── RedisConfig.java               # Redis配置
│   │   │   ├── StpInterfaceImpl.java          # Sa-Token权限实现
│   │   │   └── SwaggerConfig.java             # API文档配置
│   │   ├── controller/               # 控制器层（10个）
│   │   ├── email/                    # 邮箱模块（v2.1新增）
│   │   │   ├── config/               # 邮箱策略配置
│   │   │   ├── dto/                  # 邮箱数据传输对象
│   │   │   ├── scene/                # 场景管理
│   │   │   ├── strategy/             # 账号选择策略
│   │   │   │   └── impl/             # 策略实现类
│   │   │   ├── EmailService.java     # 邮件核心服务
│   │   │   └── EmailUseService.java  # 邮件使用服务
│   │   ├── mapper/                   # 数据访问层（15个Mapper）
│   │   ├── pojo/                     # 数据对象
│   │   │   ├── dto/                  # 数据传输对象
│   │   │   ├── entity/               # 实体类（15个实体）
│   │   │   └── vo/                   # 视图对象
│   │   ├── service/                  # 服务层
│   │   │   ├── impl/                 # 服务实现类（22个）
│   │   │   ├── MQProducerService.java      # MQ生产者
│   │   │   ├── MQConsumerService.java      # MQ消费者
│   │   │   └── SystemConfigService.java    # 系统配置服务
│   │   ├── utils/                    # 工具类（12个）
│   │   └── SmartAdPlatformServerApplication.java  # 启动类
│   ├── resources/
│   │   ├── application.yml           # 主配置文件
│   │   ├── mapper/                   # MyBatis XML映射文件（15个）
│   │   ├── sql/
│   │   │   └── smart_ad.sql          # 数据库初始化脚本
│   │   ├── static/                   # 静态资源
│   │   └── templates/                # 模板文件
│   └── test/                         # 测试代码
├── pom.xml                          # Maven依赖配置
└── README.md                        # 项目说明文档
```

---

## 💡 核心功能模块

### 1. 用户管理模块
- 用户注册（用户名/邮箱/手机号）
- 用户登录（支持验证码验证）
- 用户信息 CRUD
- 用户角色分配
- 用户状态管理

### 2. 角色权限模块
- 角色管理（增删改查）
- 权限管理（树形结构）
- 角色权限分配
- 用户角色分配
- 权限树查询（管理员/普通用户）
- 权限缓存与实时更新

### 3. 字典管理模块
- 字典类型管理
- 字典项管理
- 热查询功能（快速查询常用字典）

### 4. IP 黑名单模块
- 手动添加 IP 黑名单
- 自动检测恶意 IP 并拉黑
- 黑名单列表分页查询
- 黑名单移除
- Redis 黑名单刷新

### 5. 日志管理模块
- 接口日志分页查询
- 业务日志分页查询
- 日志异步收集（RabbitMQ）
- 日志降级策略

### 6. 系统配置模块
- 系统配置查询
- 系统配置修改（热更新）
- 配置分类管理
- OSS 连接测试
- 邮件发送测试

### 7. 验证码模块
- 图形验证码生成
- 图形验证码验证
- 短信验证码发送
- 邮箱验证码发送

### 8. 邮箱服务模块（v2.1 新增）
- 邮箱账号管理
- 邮箱账号池
- 邮件模板管理
- 邮件场景管理
- 多策略邮件发送
- 模板渲染与发送

---

## 📚 API 文档

项目集成了 Knife4j（Swagger 增强工具），提供完整的 API 文档和在线调试功能。

### 访问地址

- **Swagger UI：** http://localhost:8080/swagger-ui.html
- **Knife4j 文档：** http://localhost:8080/doc.html

### 主要接口

| 模块 | 接口前缀 | 说明 |
|------|---------|------|
| 用户管理 | `/api/user` | 用户注册、登录、信息管理 |
| 角色管理 | `/api/role` | 角色 CRUD、权限分配 |
| 权限管理 | `/api/permission` | 权限树查询、权限管理 |
| 字典管理 | `/api/dict` | 字典类型、字典项管理 |
| 系统配置 | `/api/config` | 系统配置查询与修改 |
| 日志查询 | `/api/log` | 接口日志、业务日志查询 |
| IP 黑名单 | `/api/ip-blacklist` | IP 黑名单管理 |
| 验证码 | `/api/captcha` | 图形验证码、短信验证码 |

---

## 🗄️ 数据库设计

项目包含 **15 张核心数据表**：

### 系统管理表
- `sys_user` - 用户表
- `sys_user_role` - 用户角色关联表
- `sys_role` - 角色表
- `sys_role_permission` - 角色权限关联表
- `sys_permission` - 权限表
- `sys_config` - 系统配置表
- `sys_dict_type` - 字典类型表
- `sys_dict_item` - 字典项表
- `sys_ip_blacklist` - IP 黑名单表
- `sys_log` - 业务日志表
- `sys_api_log` - 接口日志表

### 邮箱服务表（v2.1 新增）
- `email_account` - 邮箱账号表
- `email_template` - 邮件模板表
- `email_scene` - 邮件场景表
- `email_scene_template` - 场景模板关联表

### 广告业务表（待开发）
- `site` - 网站表
- `ad_slot` - 广告位表
- `ad_advertisement` - 广告表
- `ad_placement` - 投放关系表
- `ad_stat_daily` - 统计表
- `ad_event_log` - 行为日志表
- `ad_risk_log` - 风控日志表
- `user_point_account` - 积分账户表
- `user_point_flow` - 积分流水表

---

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的修改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request

### 开发规范

- **架构模式** - 三层架构（Controller → Service → Mapper）
- **依赖注入** - 推荐使用构造器注入
- **异常处理** - 使用全局异常处理器 + BusinessException
- **日志规范** - 使用 LogPlus 工具类，自动推送到 MQ
- **接口返回** - 统一使用 Result 包装
- **参数校验** - 使用 @Valid/@Validated 注解
- **权限控制** - Sa-Token 注解 + StpInterface 实现

---

## 📄 开源协议

本项目采用 [Apache License 2.0](LICENSE) 开源协议。

---

## 👨‍💻 作者

**Panrobot** - [Gitee](https://gitee.com/panrobot)

---

## 🙏 致谢

感谢以下开源项目：

- [Spring Boot](https://spring.io/projects/spring-boot)
- [MyBatis-Plus](https://baomidou.com/)
- [Sa-Token](https://sa-token.cc/)
- [Knife4j](https://doc.xiaominfo.com/)
- [RabbitMQ](https://www.rabbitmq.com/)
- [Thymeleaf](https://www.thymeleaf.org/)

---

## 📮 联系方式

- **Gitee：** https://gitee.com/panrobot/smart-ad-platform-server
- **问题反馈：** [Issues](https://gitee.com/panrobot/smart-ad-platform-server/issues)

---

<div align="center">

**如果这个项目对你有帮助，请给一个 ⭐️ Star 支持一下！**

Made with ❤️ by Panrobot

</div>

## License

This project is licensed under the Apache License 2.0.

© 2026 潘建冰