# 潮玩盲盒电商系统

**Repository Path**: yoaki233/Pop-Toy-Blind-Box

## Basic Information

- **Project Name**: 潮玩盲盒电商系统
- **Description**: 潮玩盲盒电商系统 - Spring Boot 3 + 微信小程序 + Vue 3 全栈项目。支持盲盒开盒抽奖（权重随机+保底机制）、模拟微信登录和支付、订单管理、藏品收集，含管理后台和小程序端。
欢迎大家提出任何意见和创意！🙏🙏🙏
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2026-06-19
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot, 毕业设计, 盲盒, 电商, Java

## README

# 🎁 潮玩盲盒电商系统 (BlindBoxShop)

基于 Spring Boot 3 的盲盒抽盒电商平台，支持管理端运营与用户端开盒体验。

## 技术栈

| 层级 | 技术 |
|------|------|
| **后端框架** | Spring Boot 3.2.5 + Java 17 |
| **ORM** | MyBatis-Plus 3.5.7 |
| **数据库** | MySQL 8.0 |
| **缓存** | Redis (Spring Data Redis + Commons Pool2) |
| **安全** | Spring Security + JWT (双端认证) |
| **连接池** | Druid 1.2.23 |
| **API 文档** | Knife4j (OpenAPI 3) |
| **工具库** | Hutool 5.8.28, Lombok, Fastjson |
| **对象存储** | 阿里云 OSS |
| **前端** | Vue 3 + Element Plus + Pinia |
| **小程序** | 微信小程序原生 |
| **构建工具** | Maven |

## 功能演示

### 🎁 开盒演示

![开盒演示](docs/images/开盒演示动图.gif)

### 📱 小程序端

| 首页 | 款式展示 | 藏品图鉴 |
|------|---------|---------|
| ![首页](docs/images/小程序端-首页展示.png) | ![款式](docs/images/小程序端-盲盒款式展示.png) | ![图鉴](docs/images/小程序端-藏品图鉴.png) |

### 🖥️ 管理后台

![款式管理](docs/images/管理端后台-款式管理.png)

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                     Nginx (反向代理)                      │
└──────┬──────────────────────────────────┬────────────────┘
       │                                  │
       ▼                                  ▼
┌──────────────┐                  ┌──────────────┐
│  Vue 管理后台  │                  │  微信小程序端  │
│  (Port 5173)  │                  │  (WeChat MP) │
└──────┬────────┘                  └──────┬────────┘
       │                                  │
       │  /admin/**                       │  /api/**
       ▼                                  ▼
┌─────────────────────────────────────────────────────────┐
│              Spring Boot 后端 (Port 8080)                │
│                                                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ 拦截器层   │ │ 控制器层   │ │ 业务服务层 │ │ 数据访问层 │  │
│  │ JWT Admin │ │ Admin    │ │ Service  │ │ MyBatis-  │  │
│  │ JWT User  │ │ User     │ │ Impl     │ │ Plus      │  │
│  └──────────┘ └──────────┘ └─────┬────┘ └─────┬─────┘  │
│                                   │             │       │
│                          ┌────────┴──┐   ┌─────┴─────┐ │
│                          │ Redis 缓存  │   │  MySQL DB │ │
│                          │ 热点数据    │   │  持久化    │ │
│                          └───────────┘   └───────────┘ │
└─────────────────────────────────────────────────────────┘
```

## 项目结构

```
Pop-Toy-Blind-Box/
├── blind-box-shop/              # Spring Boot 后端
│   ├── src/main/java/com/blindbox/shop/
│   │   ├── config/              # Spring配置 (Security, Redis, CORS, OSS)
│   │   ├── common/              # 统一返回体 Result/PageResult/ResultCode
│   │   ├── constant/            # 常量 (JWT Claims, Cache Keys)
│   │   ├── context/             # ThreadLocal用户上下文
│   │   ├── controller/          # 控制器 (admin/user/common)
│   │   ├── dto/                 # 请求数据传输对象
│   │   ├── entity/              # 数据库实体
│   │   ├── exception/           # 全局异常处理
│   │   ├── interceptor/         # JWT拦截器 (admin + user 双端)
│   │   ├── mapper/              # MyBatis-Plus Mapper
│   │   ├── properties/          # 配置属性 (JWT, OSS)
│   │   ├── service/             # 业务服务接口 + impl
│   │   ├── utils/               # 工具类 (JWT, Redis, OSS)
│   │   └── vo/                  # 响应视图对象
│   ├── src/main/resources/
│   │   ├── application.yml                # 基础配置
│   │   ├── application-template.yml       # 本地配置模板
│   │   └── mapper/                        # MyBatis XML
│   └── pom.xml
├── mini-program/                # 微信小程序端（原生开发）
│   ├── api/                     # 接口封装
│   ├── components/              # 公共组件
│   ├── pages/                   # 页面 (首页/系列/订单/开盒/藏品/我的)
│   ├── store/                   # 本地状态 (用户登录)
│   ├── utils/                   # 工具 (请求封装, 常量)
│   ├── app.js / app.json / app.wxss
│   └── project.config.json
├── nginx-blind-box-shop/        # Vue 3 管理后台
│   ├── src/                     # 页面 + 组件 + API
│   ├── nginx/                   # Nginx 配置
│   ├── vite.config.js
│   └── package.json
└── docker-compose.yml           # Docker 部署
```

## 核心业务

### 开盒抽奖引擎

```
开盒流程:
  1. 校验订单归属 + 状态
  2. 检查系列库存
  3. 获取/初始化用户抽盒统计
  4. 保底判定: 隐藏款(80抽) > 稀有款(30抽)
  5. 未触发保底 → 按权重随机抽取
  6. 扣减库存 + 更新统计 + 开盒记录 + 藏品收录
  7. 全部开完 → 订单状态更新为"已开盒"

保底机制:
  - drawsSinceHidden >= 79 → 触发隐藏保底 → 必出 rarity>=3
  - drawsSinceRare >= 29 → 触发稀有保底 → 必出 rarity>=2
  - 触发后对应计数器归零
```

### Redis 缓存策略

| 缓存域 | Key Pattern | TTL | 驱逐触发 |
|--------|-------------|-----|---------|
| 系列列表 | `series:page:{keyword}:{page}:{size}` | 30min | 系列CRUD、SKU变更、开盒 |
| 系列详情 | `series:detail:{id}` | 30min | 系列更新、SKU变更 |
| 系列库存 | `series:remain:{id}` | 5min | 开盒、补货 |
| 款式列表 | `sku:series:{seriesId}` | 30min | SKU CRUD |
| 库存概览 | `stock:overview:{filter}` | 5min | 补货、开盒 |
| 库存预警 | `stock:warning:{threshold}` | 5min | 补货 |
| SKU库存 | `sku:stock:{skuId}` | 1min | 开盒后即时更新 |
| 销售统计 | `dashboard:sales:{days}` | 10min | 过期自动刷新 |
| 热门款式 | `dashboard:hot:{limit}` | 10min | 过期自动刷新 |
| 用户统计 | `dashboard:users` | 10min | 过期自动刷新 |

## 快速启动

### 环境要求
- JDK 17+
- Maven 3.8+
- MySQL 8.0+
- Redis 6.0+

### 数据库初始化
```sql
CREATE DATABASE blind_box_shop DEFAULT CHARACTER SET utf8mb4;
-- 执行项目提供的 SQL 初始化脚本
```

### 启动后端
```bash
cd blind-box-shop
mvn spring-boot:run
# 服务启动在 http://localhost:8080
# API 文档: http://localhost:8080/swagger-ui.html
```

### 启动前端
```bash
cd nginx-blind-box-shop
npm install
npm run dev
# 管理后台: http://localhost:5173
```

### 默认管理员
- 用户名: `admin`
- 密码: `123456`

## API 概览

### 管理端 (/admin)

| 接口 | 方法 | 说明 |
|------|------|------|
| `/admin/auth/login` | POST | 管理员登录 |
| `/admin/series` | GET/POST | 系列列表/创建 |
| `/admin/series/{id}` | PUT/DELETE | 系列更新/删除 |
| `/admin/skus` | GET/POST | 款式列表/创建 |
| `/admin/skus/{id}` | PUT/DELETE | 款式更新/删除 |
| `/admin/stock/overview` | GET | 库存概览 |
| `/admin/stock/replenish` | POST | 库存补货 |
| `/admin/stock/warning` | GET | 库存预警 |
| `/admin/orders` | GET | 订单管理 |
| `/admin/orders/{orderNo}` | GET/PUT | 订单详情/发货 |
| `/admin/dashboard/sales` | GET | 销售统计 |
| `/admin/dashboard/hot-styles` | GET | 热门排行 |
| `/admin/dashboard/user-stats` | GET | 用户统计 |

### 用户端 (/api)

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/login` | POST | 用户登录 |
| `/api/series` | GET | 系列列表 |
| `/api/series/{id}` | GET | 系列详情 |
| `/api/orders` | GET/POST | 订单列表/创建 |
| `/api/orders/{orderNo}/pay` | POST | 支付订单 |
| `/api/orders/{orderNo}` | GET/DELETE | 订单详情/取消 |
| `/api/box/open/{orderNo}` | POST | 执行开盒 |
| `/api/box/records` | GET | 开盒记录 |
| `/api/collections` | GET | 我的藏品 |

## 设计亮点

- **双端JWT认证**: 管理端和用户端使用独立密钥和过期策略，拦截器分离
- **权重随机算法**: 按款式权重分配概率，支持稀有度保底机制
- **分层缓存TTL**: 根据数据变更频率设置不同的缓存过期时间 (1min ~ 30min)
- **缓存一致性**: 写操作主动驱逐相关缓存，避免读到脏数据
- **库存扣减**: 支付时扣库存而非下单时，减少未支付订单占用库存
- **逻辑删除**: 所有实体使用MyBatis-Plus逻辑删除，数据可恢复