# 零食商城 Snack Mall — 项目介绍

> 毕业设计 · 前后端分离的 B2C 零食电商平台
>
> 技术栈：Spring Boot 4 + Vue 3 + MySQL 8 + Redis + WebSocket

## 一、项目简介

零食商城是一个面向"爱吃零食的年轻人"的在线购物平台，覆盖**商品浏览、购物车、下单支付、订单追踪、优惠券、限时抢购、在线客服**等完整电商闭环。项目采用前后端分离架构，包含用户端（H5/PC）、管理后台、后端 API 服务三部分，并配套完整的数据库脚本与设计文档，适合作为毕业设计展示"全栈 + 高并发 + 实时通信"的综合能力。

### 核心目标

- **用户端**：商品浏览与搜索、商品详情、购物车、收藏、订单支付（支付宝沙箱）、领券中心、限时抢购、在线客服、公告、个人中心
- **管理端**：数据可视化仪表盘、商品/分类/SKU 管理、订单处理、用户管理、优惠券管理、抢购活动管理、公告管理、客服会话处理
- **技术验证**：Redis 原子操作防超卖、WebSocket 实时客服、订单状态机、双端登录鉴权、支付宝沙箱支付

## 二、功能模块

### 2.1 用户端（前台）

| 模块 | 说明 |
|------|------|
| 商品中心 | 首页轮播、商品分类浏览、关键词搜索、商品详情（SKU 选择/多图预览） |
| 购物车 | 增删改、全选/单选、批量结算 |
| 订单支付 | 地址选择、优惠券抵扣、支付宝沙箱收银台、支付回调自动更新状态 |
| 收藏 | 商品详情页一键收藏，个人中心"我的收藏"管理 |
| 领券中心 | 展示可领取优惠券（满减/折扣/无门槛），一键领取，我的优惠券按状态筛选 |
| 限时抢购 | 活动场次倒计时、抢购价 + 库存进度、一键抢购生成订单、立即支付 |
| 在线客服 | WebSocket 实时聊天、等待接入/处理中/已关闭状态流转、历史消息 |
| 个人中心 | 资料、订单（支付/取消/确认收货）、地址管理、收藏、优惠券 |

### 2.2 管理端（后台）

| 模块 | 说明 |
|------|------|
| 仪表盘 | ECharts 数据可视化：销售趋势、订单状态分布、热销商品 |
| 商品管理 | SPU/分类/SKU 管理、上下架、图片上传、富文本详情 |
| 订单管理 | 分页筛选、订单详情（商品/金额/物流/时间轴）、发货、取消 |
| 用户管理 | 用户启停、重置密码、历史订单查询 |
| 优惠券管理 | 优惠券模板 CRUD、领取记录查询 |
| 抢购管理 | 活动创建/编辑/上线预热、活动商品配置、强制结束 |
| 公告管理 | 公告 CRUD + 上下线 |
| 客服管理 | 会话列表（待处理/处理中）、接管、转接、快捷回复、实时聊天 |

## 三、系统架构

```mermaid
flowchart TB
    subgraph FE["前端层 Vue 3"]
        WEB["用户端 web-snack<br/>Vite + Element Plus + Pinia"]
        ADMIN["管理端 admin-snack<br/>Vite + Element Plus + ECharts"]
    end

    subgraph BE["后端层 Spring Boot 4"]
        API["RESTful API<br/>MyBatis-Plus / Sa-Token"]
        WS["WebSocket 客服<br/>原生 WS + JSON 协议"]
        JOB["定时任务 @Scheduled"]
    end

    subgraph DATA["数据层"]
        MYSQL[("MySQL 8<br/>21 张表")]
        REDIS[("Redis<br/>缓存 / 抢购库存 / 在线状态")]
    end

    WEB --> API
    ADMIN --> API
    WEB --> WS
    ADMIN --> WS
    API --> MYSQL
    API --> REDIS
    WS --> MYSQL
```

### 技术栈

| 层次 | 技术 | 说明 |
|------|------|------|
| 用户端 | Vue 3.5 · Vite 8 · TypeScript 6 · Element Plus 2.14 · Pinia · VueUse | H5/PC 响应式商城 |
| 管理端 | Vue 3.5 · Vite 6 · TypeScript 5 · Element Plus 2.9 · Pinia 2 · ECharts 5 | 数据密集型管理后台 |
| 后端 | Spring Boot 4.0.6 · Java 21 · MyBatis-Plus 3.5 · Sa-Token 1.45 · Knife4j | RESTful API + 鉴权 + 接口文档 |
| 数据 | MySQL 8 · Redis | 持久化 + 缓存/原子操作 |
| 通信 | REST（axios）· WebSocket（VueUse useWebSocket） | HTTP 业务 + 实时客服 |
| 第三方 | 支付宝开放平台（沙箱） | 电脑网站支付 |

## 四、界面预览

### 4.1 用户端

| 页面 | 预览 | 说明 |
|------|------|------|
| 商城首页 | ![商城首页](images/商城首页.png) | 轮播图、分类导航、商品推荐 |
| 商品详情 | ![商品详情](images/商品详情.png) | 图片画廊、SKU 选择、加购与收藏 |
| 购物车 | ![购物车](images/购物车.png) | 数量调整、勾选结算 |
| 限时抢购 | ![限时抢购](images/限时抢购.png) | 活动倒计时、抢购价、库存进度 |
| 在线客服 | ![客服](images/客服.png) | WebSocket 实时会话 |
| 用户中心 | ![用户中心](images/用户中心.png) | 订单、地址、收藏、优惠券 |

### 4.2 管理端

| 页面 | 预览 | 说明 |
|------|------|------|
| 后台登录 | ![后台登录](images/后台登录.png) | 管理员登录（验证码） |
| 数据仪表盘 | ![后台首页](images/后台首页.png) | ECharts 销售统计 |
| 商品管理 | ![后台商品列表](images/后台商品列表.png) | 商品列表与上下架 |
| 订单详情 | ![后台订单详情](images/后台订单详情.png) | 商品/金额/物流/状态时间轴 |
| 客服会话 | ![后台客服](images/后台客服.png) | 会话列表 + 快捷回复 + 实时聊天 |
| 抢购活动 | ![后台限时抢购活动](images/后台限时抢购活动.png) | 活动与商品配置 |

## 五、核心业务亮点

### 5.1 双端登录鉴权（Sa-Token）

用户端与管理端使用两套登录体系（`LoginType.USER / ADMIN`），通过 `SaRouter` 按 URL 模式统一拦截，`Authorization: Bearer <token>` 传递凭证，业务异常由全局异常处理器统一返回 `Result<T>`（code/message/data）。

### 5.2 支付宝沙箱支付

电脑网站支付（`alipay.trade.page.pay`）：后端生成签名收银台 URL，浏览器跳转沙箱收银台；支付成功后支付宝**异步通知**验签、金额比对、幂等更新订单（状态 0→1、支付渠道、交易号、支付时间），**同步跳转**仅用于前端展示，不修改业务状态。

### 5.3 WebSocket 实时客服

- 原生 WebSocket + JSON 文本协议，客户端基于 **VueUse `useWebSocket`** 封装，断线自动重连；
- 握手时 Sa-Token 校验，按 `user:{id}` / `admin:{id}` 建立连接表，消息**点对点推送** + 客服广播；
- 消息全部落 `chat_message` 表，`seq` 递增 + ACK 已读确认，断线后按序号补发，**不丢消息**；
- 管理端支持**接管 / 转接 / 已解决 / 关闭**会话与**快捷回复**模板，用户端可见"等待接入/客服接入/已关闭"状态流转。

### 5.4 限时抢购防超卖（Redis 原子操作）

- **Lua 脚本原子完成**"限购校验 + 库存扣减"，杜绝高并发超卖；
- `seckill:stock:{activityId}:{skuId}` 实时库存，`seckill:user:{userId}:{activityId}:{skuId}` 一人一单限购；
- 抢购成功**同步生成主订单**（orders + order_item 快照）并回填 `seckill_order.order_id`，落库失败自动回滚 Redis 库存；
- 取消未支付订单自动**恢复抢购库存**；支付回调同步抢购记录状态。

### 5.5 优惠券体系

领券中心展示可领取优惠券（满减/折扣/无门槛），支持每人限领、库存限制、领取后有效期；订单结算时校验并抵扣，状态机管控"未使用 → 已使用/已过期"防止重复核销。

### 5.6 订单状态机

`待付款 → 待发货 → 待收货 → 已完成`，取消/退款分支由 `OrderStatusEnum.canTransition` 严格约束，配合 `UPDATE ... WHERE status = ?` 条件更新防止并发状态错乱；支付、发货、收货、取消均记录对应时间字段。

## 六、数据库设计

共 **21 张表**，覆盖用户、商品、订单、支付、收藏、优惠券、抢购、客服、公告等业务：

| 分类 | 表 |
|------|----|
| 基础 | `user`、`admin`、`address` |
| 商品 | `product`、`product_sku`、`product_category`、`banner`、`favorite` |
| 交易 | `orders`、`order_item`、`cart`、`payment` |
| 营销 | `coupon`、`user_coupon`、`seckill_activity`、`seckill_product`、`seckill_order` |
| 客服 | `chat_session`、`chat_message`、`quick_reply` |
| 内容 | `notice`、`file` |

> 完整 DDL 见 `db/schema.sql`，演示数据见 `db/seed.sql`，核心业务设计见 `db/BUSINESS_DESIGN.md`。

## 七、快速启动

### 环境要求

| 工具 | 版本 |
|------|------|
| JDK | 21 |
| Maven | 3.8+ |
| Node.js | ≥ 20 |
| MySQL | 8.0+ |
| Redis | 6.0+ |

### 启动步骤

```bash
# 1. 初始化数据库（建库 + 21 张表）
mysql -u root -p < db/schema.sql
# 可选：导入演示数据
mysql -u root -p < db/seed.sql

# 2. 启动后端（端口 8080，接口文档 http://localhost:8080/doc.html）
cd server-snack && mvn spring-boot:run

# 3. 启动管理端（http://localhost:5173）
cd admin-snack && npm install && npm run dev

# 4. 启动用户端（http://localhost:5174）
cd web-snack && npm install && npm run dev
```

> Vite 已把 `/api`、`/uploads`、`/ws` 代理到后端 `http://localhost:8080`，联调前确认后端与 MySQL/Redis 已启动。

### 默认账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 管理员 | `admin` | `123456` |
| 普通用户 | `user001` ~ `user005` | `123456` |

## 八、项目目录结构

```
snack-mall/
├── server-snack/          # 后端 API（Spring Boot 4 + MyBatis-Plus + Redis）
│   └── src/main/java/com/snack/server/module/
│       ├── product/       # 商品 / 分类 / SKU
│       ├── order/         # 订单 / 支付宝支付
│       ├── cart/          # 购物车
│       ├── coupon/        # 优惠券 / 领券
│       ├── seckill/       # 限时抢购（Lua 防超卖）
│       ├── chat/          # 客服（WebSocket 处理器）
│       ├── user/          # 用户 / 认证
│       ├── admin/         # 管理员
│       ├── notice/        # 公告
│       └── favorite/      # 收藏
├── web-snack/             # 用户端（Vue 3 + Vite）
├── admin-snack/           # 管理端（Vue 3 + Element Plus + ECharts）
├── db/                    # schema.sql / seed.sql / BUSINESS_DESIGN.md
├── images/                # 项目截图
├── 功能设计文档.md          # 功能与接口设计（v1.2）
└── 项目介绍.md             # 本文档
```

## 九、相关文档

| 文档 | 路径 | 内容 |
|------|------|------|
| 功能设计总览 | `功能设计文档.md` | 六大模块业务与接口设计 |
| 核心业务设计 | `db/BUSINESS_DESIGN.md` | WebSocket 客服 + Redis 防超卖 |
| 数据库设计 | `db/schema.sql` | 21 张表 DDL 与说明 |
| 管理端说明 | `admin-snack/README.md` | 技术栈、命令、设计系统 |