# treasure_hunt_server

**Repository Path**: it4/treasure_hunt_server

## Basic Information

- **Project Name**: treasure_hunt_server
- **Description**: 本项目是“趣味寻宝应用”的后端服务系统，基于 Java 17 + Spring Boot 3 构建。利用 Spring Data JPA 自动生成数据库表结构，内置 Spring Security 和 JWT 实现多角色的轻量级安全认证与鉴权，配合 MySQL 实现高性能的数据存储。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ⚙️ 寻宝应用后端服务 (Treasure Hunt Backend)

本项目是“趣味寻宝应用”的后端服务系统，基于 **Java 17** + **Spring Boot 3** 构建。利用 **Spring Data JPA** 自动生成数据库表结构，内置 **Spring Security** 和 **JWT** 实现多角色的轻量级安全认证与鉴权，配合 **MySQL** 实现高性能的数据存储。

---

## 🛠️ 技术栈

| 技术 | 作用 | 备注 |
| :--- | :--- | :--- |
| **Java 17** | 核心编程语言 | 长期支持版 (LTS)，采用现代 Java 特性 |
| **Spring Boot 3.2.3**| 基础应用框架 | 简化脚手架、自动配置与起步依赖 |
| **Spring Data JPA**  | 持久层对象关系映射 | 基于 Hibernate 实现，全自动建表与持久化 |
| **Spring Security**  | 安全与权限控制 | 细粒度控制接口访问权限 (ADMIN/PUBLISHER/HUNTER) |
| **JSON Web Token (JWT)**| 认证机制 | 无状态身份认证，使用 `jjwt` 库生成与验证 Token |
| **MySQL 8.x**        | 关系型数据库 | 存储用户、宝物、以及认领记录 |
| **Lombok**           | 生产力工具 | 减少 boilerplate 代码（Getter/Setter/Builder 等） |

---

## 📦 环境要求

- **JDK**：Java 17 或以上
- **构建工具**：Maven 3.6+
- **数据库**：MySQL 8.x
- **开发工具**：IntelliJ IDEA / Eclipse / VS Code (需安装 Java 插件)

---

## 🚀 本地运行与配置指引

### 1. 数据库初始化

1. 启动本地 MySQL 服务。
2. 创建目标数据库，名称为 `db_treasure_hunt`（使用 `utf8mb4` 编码）：
   ```sql
   CREATE DATABASE IF NOT EXISTS `db_treasure_hunt` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
   ```
3. 在数据库中执行项目中的初始化 SQL 脚本：[backend/src/main/resources/init.sql](file:///f:/ai_workspace/index4/backend/src/main/resources/init.sql)。
   - **注意**：JPA 会根据实体类自动在数据库中生成表（`tb_user`、`tb_treasure`、`tb_claim`），运行 `init.sql` 主要是插入测试所需的**角色账户**与**初始测试宝物数据**。

### 2. 更改后端配置文件
打开配置文件：[backend/src/main/resources/application.yml](file:///f:/ai_workspace/index4/backend/src/main/resources/application.yml)。

```yaml
server:
  port: 8490
  servlet:
    context-path: /api

spring:
  datasource:
    # 请根据您的本地 MySQL 服务器地址、端口和数据库名称进行修改
    url: jdbc:mysql://localhost:3306/db_treasure_hunt?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true&characterEncoding=utf-8
    username: root
    password: root # 请修改为您本地 MySQL 数据库的实际密码
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update # 本地启动时根据实体类自动同步表结构
    show-sql: false # 开发调试时可以设为 true 打印 SQL 语句
```

### 3. 本地启动运行
在 `backend` 目录下打开终端，运行以下命令启动 Spring Boot 服务：

```bash
# 使用 Maven 插件启动
mvn spring-boot:run
```

启动成功后，后端服务会监听在 **`8490`** 端口，并且 API 的基础路径为 **`/api`**。
👉 本地测试入口：`http://localhost:8490/api`

### 4. 生产构建打包
当您准备打包成可独立运行的 jar 文件时，可以在 `backend` 目录下运行：

```bash
# 跳过单元测试并进行打包
mvn clean package -DskipTests
```
打包成功后，在 `backend/target/` 目录下会生成 `treasure-hunt-backend-0.0.1-SNAPSHOT.jar` 文件，使用以下命令即可在任意安装了 Java 17 的服务器上运行：

```bash
java -jar target/treasure-hunt-backend-0.0.1-SNAPSHOT.jar
```

---

## 👥 预置测试账户

数据库初始化脚本 `init.sql` 默认插入了 3 个不同权限的角色账号，用于模拟不同的系统流程。密码统一为：**`123456`**（在数据库中以 BCrypt 安全哈希格式存储）。

| 角色用户名 | 密码 | 系统角色 (Role) | 权限说明 |
| :--- | :--- | :--- | :--- |
| **admin** | `123456` | `ADMIN` (系统管理员) | 拥有系统的最高权限，可审批猎人的认领请求，管理系统数据。 |
| **publisher**| `123456` | `PUBLISHER` (宝物发布者)| 可在地图的任意经纬度隐藏并发布新宝物，并设置宝物对应的积分。 |
| **hunter** | `123456` | `HUNTER` (寻宝猎人) | 寻宝游戏主体。可在地图浏览宝物、前往现实坐标认领宝物、积累积分。|

---

## 🔑 安全控制与认证说明 (JWT)

1. **接口鉴权**：除登录接口（`/api/auth/login` 等）外，大部分 API 接口均受到 Spring Security 的拦截保护。
2. **认证流程**：
   - 客户端调用登录接口，后端核对用户名与密码。
   - 验证成功后，后端生成包含用户信息的 JWT 令牌并返回给前端。
   - 前端接收到 Token 后缓存在本地，后续发起的每一个 HTTP 请求都在请求头 `Authorization` 中携带该 Token。
     - **格式**：`Authorization: Bearer <Your_Token_Here>`
   - 后端通过 `jwt.secret` 密钥进行解密校验，提取用户身份并完成鉴权。

---

## 📂 项目目录结构说明

```text
backend/
├── src/
│   ├── main/
│   │   ├── java/com/treasure/
│   │   │   ├── controller/ # 控制层 (API 路由定义，处理前端请求)
│   │   │   ├── entity/     # 实体层 (MySQL 表结构映射实体类)
│   │   │   ├── repository/ # 数据访问层 (JPA DAO，负责底层 SQL 操作)
│   │   │   ├── service/    # 业务逻辑层 (具体的业务逻辑处理)
│   │   │   └── security/   # 安全架构 (JWT 过滤器、Spring Security 配置)
│   │   └── resources/
│   │       ├── application.yml # 🛠️ 系统基础配置文件 (数据库/端口/JWT密钥)
│   │       └── init.sql        # 🗄️ 数据库初始化测试数据脚本
│   └── test/               # 测试代码
├── pom.xml                 # Maven 依赖配置文件
└── README.md               # 本文档
```