# fourseans-admin-springboot

**Repository Path**: mos-tabs/fourseans-admin-springboot

## Basic Information

- **Project Name**: fourseans-admin-springboot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-16
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 贵州四季康养智慧文旅综合服务平台 - 后端服务

<div align="center">

![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.6-brightgreen.svg)
![Java](https://img.shields.io/badge/Java-21-orange.svg)
![MySQL](https://img.shields.io/badge/MySQL-8.0-blue.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

**基于 Spring Boot 的智慧文旅综合服务平台后端 API**

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

</div>

---

## 📖 项目简介

贵州四季康养智慧文旅综合服务平台后端服务，为微信小程序和Web管理后台提供RESTful API接口。系统整合了旅游、康养、电商、社区等多种服务，为贵州地区的智慧旅游产业提供数字化解决方案。

### 🎯 项目定位

- **用户端服务**：为微信小程序提供景点查询、商品购买、订单管理、社区互动等功能
- **管理端服务**：为Web管理后台提供用户管理、商品管理、订单管理、数据统计等功能
- **商家端服务**：为商家提供店铺管理、商品上架、订单处理等功能

---

## ✨ 功能特性

### 核心功能模块

#### 🔐 用户认证与授权
- 微信小程序授权登录
- JWT令牌认证
- 基于角色的权限控制（RBAC）
- 手机号验证

#### 🏞️ 旅游服务
- 景点信息管理
- 四季路线推荐
- AR导览支持
- 挑战贵州活动

#### 🛒 电商服务
- 商品分类管理
- 商品上下架
- 购物车功能
- 订单管理
- 支付集成（微信支付）
- 物流跟踪

#### 💊 康养服务
- 康养产品预约
- 健康记录管理
- 苗医苗药咨询
- 预约订单管理

#### 👥 社区互动
- 游记发布与分享
- 用户评论
- 点赞收藏
- 志愿者服务

#### 📊 数据统计
- 用户数据分析
- 销售数据统计
- 订单趋势分析
- 热门商品排行


---

## 🛠️ 技术栈

### 核心框架
- **Spring Boot 3.3.6** - 应用框架
- **Spring Security** - 安全框架
- **Spring Data JPA** - 数据持久化
- **MyBatis-Plus 3.5.9** - ORM增强框架

### 数据存储
- **MySQL 8.0** - 关系型数据库
- **Redis** - 缓存数据库

### 安全认证
- **JWT 0.12.6** - 令牌认证
- **BCrypt** - 密码加密

### 接口文档
- **Knife4j 4.5.0** - API文档工具（Swagger增强版）

### 工具库
- **Hutool 5.8.32** - Java工具类库
- **Lombok** - 简化Java代码
- **MinIO 8.5.13** - 对象存储

### 构建工具
- **Maven 3.9+** - 项目构建管理
- **Java 21** - 开发语言

---

## 🚀 快速开始

### 环境要求

- **JDK 21+**
- **Maven 3.9+**
- **MySQL 8.0+**
- **Redis 6.0+**（可选）

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://gitee.com/mos-tabs/fourseans-admin-springboot.git
cd fourseans-admin-springboot
```

#### 2. 配置数据库

创建数据库：
```sql
CREATE DATABASE fourseasons_health DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

导入数据库脚本：
```bash
mysql -u root -p fourseasons_health < docs/sql/init.sql
```

#### 3. 修改配置文件

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

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/fourseasons_health?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: your_username
    password: your_password
```

#### 4. 启动项目

**方式一：使用 Maven**
```bash
mvn clean install
mvn spring-boot:run
```

**方式二：使用 IDE**
- 导入项目到 IntelliJ IDEA 或 Eclipse
- 运行 `FourseasonsAdminApplication.java`

#### 5. 访问服务

- **应用地址**：http://localhost:8080
- **API文档**：http://localhost:8080/doc.html
- **健康检查**：http://localhost:8080/actuator/health


---

## 📁 项目结构

```
fourseasons-health-admin/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/fourseasons/admin/
│   │   │       ├── common/              # 公共组件
│   │   │       │   ├── constant/        # 常量定义
│   │   │       │   ├── exception/       # 异常处理
│   │   │       │   └── result/          # 统一响应结果
│   │   │       ├── config/              # 配置类
│   │   │       │   ├── SecurityConfig.java      # 安全配置
│   │   │       │   ├── RedisConfig.java         # Redis配置
│   │   │       │   ├── CorsConfig.java          # 跨域配置
│   │   │       │   └── Knife4jConfig.java       # API文档配置
│   │   │       ├── controller/          # 控制器层
│   │   │       │   ├── UserController.java      # 用户接口
│   │   │       │   ├── ProductController.java   # 商品接口
│   │   │       │   ├── OrderController.java     # 订单接口
│   │   │       │   └── ...
│   │   │       ├── dto/                 # 数据传输对象
│   │   │       ├── entity/              # 实体类
│   │   │       │   ├── User.java        # 用户实体
│   │   │       │   ├── Product.java     # 商品实体
│   │   │       │   ├── Order.java       # 订单实体
│   │   │       │   └── ...
│   │   │       ├── enums/               # 枚举类
│   │   │       ├── mapper/              # MyBatis Mapper
│   │   │       ├── security/            # 安全相关
│   │   │       │   ├── JwtAuthenticationFilter.java  # JWT过滤器
│   │   │       │   ├── JwtTokenProvider.java         # JWT工具类
│   │   │       │   └── UserDetailsServiceImpl.java   # 用户详情服务
│   │   │       ├── service/             # 服务层
│   │   │       │   ├── UserService.java
│   │   │       │   ├── ProductService.java
│   │   │       │   ├── OrderService.java
│   │   │       │   └── impl/            # 服务实现类
│   │   │       ├── task/                # 定时任务
│   │   │       ├── util/                # 工具类
│   │   │       ├── vo/                  # 视图对象
│   │   │       └── FourseasonsAdminApplication.java  # 启动类
│   │   └── resources/
│   │       ├── application.yml          # 主配置文件
│   │       ├── application-dev.yml      # 开发环境配置
│   │       ├── application-prod.yml     # 生产环境配置
│   │       ├── mapper/                  # MyBatis XML映射文件
│   │       └── static/                  # 静态资源
│   └── test/                            # 测试代码
├── docs/                                # 项目文档
│   ├── api/                             # API接口文档
│   ├── database/                        # 数据库设计文档
│   └── sql/                             # SQL脚本
├── pom.xml                              # Maven配置文件
└── README.md                            # 项目说明文档
```

---

## 🔌 API文档

### 访问方式

启动项目后，访问 Knife4j 文档：
```
http://localhost:8080/doc.html
```

### 主要接口模块

#### 1. 用户认证接口
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/logout` - 用户登出
- `GET /api/auth/info` - 获取当前用户信息

#### 2. 用户管理接口
- `GET /api/users` - 获取用户列表
- `GET /api/users/{id}` - 获取用户详情
- `PUT /api/users/{id}` - 更新用户信息
- `DELETE /api/users/{id}` - 删除用户

#### 3. 商品管理接口
- `GET /api/products` - 获取商品列表
- `GET /api/products/{id}` - 获取商品详情
- `POST /api/products` - 创建商品
- `PUT /api/products/{id}` - 更新商品
- `DELETE /api/products/{id}` - 删除商品

#### 4. 订单管理接口
- `GET /api/orders` - 获取订单列表
- `GET /api/orders/{id}` - 获取订单详情
- `POST /api/orders` - 创建订单
- `PUT /api/orders/{id}/status` - 更新订单状态
- `POST /api/orders/{id}/pay` - 订单支付

#### 5. 景点管理接口
- `GET /api/scenic-spots` - 获取景点列表
- `GET /api/scenic-spots/{id}` - 获取景点详情
- `POST /api/scenic-spots` - 创建景点
- `PUT /api/scenic-spots/{id}` - 更新景点


---

## 🔧 配置说明

### 数据库配置

```yaml
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/fourseasons_health?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
```

### Redis配置（可选）

```yaml
spring:
  redis:
    host: localhost
    port: 6379
    password: 
    database: 0
    timeout: 3000ms
```

### JWT配置

```yaml
jwt:
  secret: your-secret-key-here-must-be-at-least-256-bits
  expiration: 86400000  # 24小时（毫秒）
  header: Authorization
  prefix: Bearer 
```

### 文件上传配置

```yaml
spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 10MB
```

### 微信支付配置

```yaml
wechat:
  pay:
    app-id: your-app-id
    mch-id: your-mch-id
    api-key: your-api-key
    notify-url: https://your-domain.com/api/pay/notify
```

---

## 🔐 安全说明

### 认证流程

1. 用户通过 `/api/auth/login` 接口登录
2. 服务器验证用户名密码，生成JWT令牌
3. 客户端在后续请求中携带JWT令牌
4. 服务器验证令牌有效性，返回数据

### 权限控制

系统采用基于角色的权限控制（RBAC）：

- **ADMIN** - 管理员：拥有所有权限
- **MERCHANT** - 商家：管理自己的店铺和商品
- **USER** - 普通用户：浏览和购买商品

### 接口权限示例

```java
@PreAuthorize("hasRole('ADMIN')")
@GetMapping("/users")
public Result<List<User>> getUserList() {
    // 只有管理员可以访问
}

@PreAuthorize("hasAnyRole('ADMIN', 'MERCHANT')")
@PostMapping("/products")
public Result<Product> createProduct(@RequestBody Product product) {
    // 管理员和商家可以访问
}
```

---

## 📊 数据库设计

### 核心数据表

#### 用户表（users）
```sql
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    nickname VARCHAR(50),
    avatar_url VARCHAR(255),
    phone VARCHAR(20),
    email VARCHAR(100),
    role VARCHAR(20) DEFAULT 'USER',
    status TINYINT DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

#### 商品表（products）
```sql
CREATE TABLE products (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    category_id BIGINT,
    price DECIMAL(10,2) NOT NULL,
    stock INT DEFAULT 0,
    description TEXT,
    images JSON,
    status TINYINT DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

#### 订单表（orders）
```sql
CREATE TABLE orders (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    order_no VARCHAR(50) UNIQUE NOT NULL,
    user_id BIGINT NOT NULL,
    total_amount DECIMAL(10,2) NOT NULL,
    status VARCHAR(20) DEFAULT 'PENDING',
    payment_method VARCHAR(20),
    payment_time DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

详细的数据库设计文档请查看：[docs/database/database_design.md](docs/database/database_design.md)


---

## 🚢 部署指南

### Docker 部署

#### 1. 构建镜像

```bash
# 构建项目
mvn clean package -DskipTests

# 构建Docker镜像
docker build -t fourseasons-health-admin:1.0.0 .
```

#### 2. 运行容器

```bash
docker run -d \
  --name fourseasons-admin \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e MYSQL_HOST=your-mysql-host \
  -e MYSQL_PORT=3306 \
  -e MYSQL_DATABASE=fourseasons_health \
  -e MYSQL_USERNAME=root \
  -e MYSQL_PASSWORD=your-password \
  fourseasons-health-admin:1.0.0
```

### 微信云托管部署

#### 1. 准备 Dockerfile

```dockerfile
FROM openjdk:21-jdk-slim
WORKDIR /app
COPY target/fourseasons-health-admin-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
```

#### 2. 配置云托管

- 登录微信云托管控制台
- 创建新服务
- 上传代码或连接Git仓库
- 配置环境变量
- 部署服务

详细部署文档请查看：[docs/deployment/wechat_cloud_hosting.md](docs/deployment/wechat_cloud_hosting.md)

### 传统服务器部署

#### 1. 打包项目

```bash
mvn clean package -DskipTests
```

#### 2. 上传到服务器

```bash
scp target/fourseasons-health-admin-1.0.0.jar user@server:/opt/app/
```

#### 3. 启动服务

```bash
# 后台运行
nohup java -jar fourseasons-health-admin-1.0.0.jar \
  --spring.profiles.active=prod \
  > app.log 2>&1 &

# 或使用systemd服务
sudo systemctl start fourseasons-admin
```

---

## 🧪 测试

### 运行单元测试

```bash
mvn test
```

### 运行集成测试

```bash
mvn verify
```

### 测试覆盖率

```bash
mvn clean test jacoco:report
```

查看测试报告：`target/site/jacoco/index.html`

---

## 📈 性能优化

### 数据库优化
- 使用索引优化查询
- 配置数据库连接池
- 使用Redis缓存热点数据

### 接口优化
- 分页查询大数据量
- 异步处理耗时操作
- 使用CDN加速静态资源

### 缓存策略
```java
@Cacheable(value = "products", key = "#id")
public Product getProductById(Long id) {
    return productRepository.findById(id).orElse(null);
}
```

---

## 🐛 常见问题

### Q1: 启动时报数据库连接失败
**A:** 检查数据库配置是否正确，确保MySQL服务已启动

### Q2: JWT令牌验证失败
**A:** 检查JWT密钥配置，确保前后端使用相同的密钥

### Q3: 跨域请求被拒绝
**A:** 检查CorsConfig配置，确保允许前端域名访问

### Q4: 文件上传失败
**A:** 检查文件大小限制配置，确保不超过最大限制

### Q5: Redis连接失败
**A:** 如果不使用Redis，可以在配置中禁用Redis自动配置

```yaml
spring:
  autoconfigure:
    exclude: org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration
```

---

## 📝 开发规范

### 代码规范
- 遵循阿里巴巴Java开发手册
- 使用统一的代码格式化配置
- 编写清晰的注释和文档

### Git提交规范
```
feat: 新增功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具链相关
```

### 分支管理
- `main` - 主分支，生产环境代码
- `develop` - 开发分支
- `feature/*` - 功能分支
- `hotfix/*` - 紧急修复分支


---

## 🤝 贡献指南

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

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

---

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

---

## 📞 联系方式

- **项目负责人**：【你的姓名】
- **邮箱**：【你的邮箱】
- **项目地址**：https://gitee.com/mos-tabs/fourseans-admin-springboot

---

## 🙏 致谢

感谢以下开源项目：

- [Spring Boot](https://spring.io/projects/spring-boot)
- [MyBatis-Plus](https://baomidou.com/)
- [Knife4j](https://doc.xiaominfo.com/)
- [Hutool](https://hutool.cn/)

---

## 📚 相关项目

- **微信小程序前端**：[fourseasons-health](https://gitee.com/mos-tabs/fourseasons-health) (分支: newfile/0.1.1)
- **Web管理后台**：[fourseans-admin-Vue3](https://gitee.com/mos-tabs/fourseans-admin-Vue3)

---

## 📅 更新日志

### v1.0.0 (2025-12-31)
- ✨ 初始版本发布
- ✅ 完成用户认证模块
- ✅ 完成商品管理模块
- ✅ 完成订单管理模块
- ✅ 完成景点管理模块
- ✅ 完成康养服务模块
- ✅ 完成社区互动模块
- ✅ 集成微信支付
- ✅ 集成JWT认证
- ✅ 集成Knife4j文档

---

<div align="center">

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

Made with ❤️ by FourSeasons Team

</div>