零食商城 Snack Mall

毕业设计 · 前后端分离的 B2C 电商平台，覆盖用户端、管理端、客服、公告、优惠券、抢购六大模块。

仓库采用单仓多模块结构，包含两个前端项目（用户端 + 管理端）、一个 Spring Boot 后端服务，以及数据库脚本与设计文档。

模块概览

目录	角色	技术栈
server-snack/	后端 API 服务	Spring Boot 4.0.6 · Java 21 · MyBatis-Plus 3.5 · Sa-Token 1.45 · Redis · MySQL 8 · Knife4j 4.6
web-snack/	用户端 H5/PC 前端	Vue 3.5 · Vite 8 · TypeScript 6 · Element Plus 2.14 · Pinia 3
admin-snack/	管理后台前端	Vue 3.5 · Vite 6 · TypeScript 5 · Element Plus 2.9 · Pinia 2 · ECharts 5
db/	数据库脚本与设计文档	schema.sql 建库 + 21 张表 DDL，seed.sql 演示数据
功能设计文档.md	完整功能与接口设计（v1.2）	6 大模块业务与接口说明
db/BUSINESS_DESIGN.md	核心业务设计	WebSocket 客服 + Redis 防超卖方案
admin-snack/design-system/	设计系统资源	视觉令牌与组件规范

业务功能

• 用户端：注册登录、收货地址、购物车、收藏、订单、支付、抢购、客服聊天
• 管理端：仪表盘、商品 / 分类 / SKU 管理、订单处理、用户管理、优惠券、抢购活动、公告、客服会话
• 跨端共享：系统公告、用户优惠券、限时抢购（Redis 原子扣减防超卖）

快速开始

环境要求

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

1. 初始化数据库

mysql -u root -p < db/schema.sql   # 建库 + 21 张表
mysql -u root -p < db/seed.sql     # 演示数据（可选）

2. 启动后端

cd server-snack
mvn spring-boot:run
# 监听 http://localhost:8080
# 接口文档 http://localhost:8080/doc.html

修改 server-snack/src/main/resources/application.yml 中的 MySQL / Redis 配置以匹配本地环境。

3. 启动管理端

cd admin-snack
npm install
npm run dev
# 访问 http://localhost:5173

4. 启动用户端

cd web-snack
npm install
npm run dev

Vite 已将 /api 与 /uploads 代理到 http://localhost:8080，联调时确认后端已启动。

默认账号

角色	用户名	密码
管理员	admin	123456
管理员	manager	123456
管理员	operator	123456
普通用户	user001 ~ user005	123456

架构与约定

后端分层

每个业务模块位于 server-snack/src/main/java/com/snack/server/module/<name>/：

module/<name>/
├── controller/   # @RestController，用户端 / 管理端分文件
├── service/      # 业务接口
│   └── impl/     # 业务实现
├── mapper/       # MyBatis-Plus BaseMapper
├── entity/       # 数据库表实体
├── dto/req       # 入参（带 jakarta.validation 注解）
├── vo/           # 出参（视图对象）
├── enums/        # 模块内枚举
└── constant/     # 模块内常量

跨模块共享：com.snack.server.{common,config,constant,exception,handler,utils,enums,websocket}。

关键技术点

1. 认证 — Sa-Token（非 JWT），用户端与管理端走两套登录体系（LoginType.USER / LoginType.ADMIN），通过 SaRouter.match 按 URL 区分
2. 统一响应 — Result<T> 封装 { code, message, data }，前端 axios 拦截器在 code === 200 时直接返回 data（已解包约定）
3. MyBatis-Plus — 逻辑删除字段 deleted（0/1）、主键自增、createTime/updateTime 自动填充、复杂 SQL 走 XML
4. 防超卖 — Redis DECR 原子扣减库存 → 失败返回"已抢完" → 写入异步队列 → 消费端落 MySQL
5. WebSocket 客服 — Spring WebSocket + STOMP，握手时验证 Token，消息全量落库 chat_message

前端约定

• 路径别名：@ → src/
• 自动导入：unplugin-auto-import + unplugin-vue-components 处理 Vue / Vue Router / Pinia / Element Plus
• 状态管理：Pinia + 持久化（管理端 key 为 snack-admin-user）
• 请求层：utils/request.ts 已解包响应，401 自动清空登录态并跳登录页
• 设计系统：主色 #1E40AF / #3B82F6，圆角 6/10px，背景 #F8FAFC

更多细节参见 CLAUDE.md。

目录结构

snack-mall/
├── server-snack/                # 后端服务
├── web-snack/                   # 用户端
├── admin-snack/                 # 管理端
├── db/                          # 数据库脚本与业务设计
│   ├── schema.sql               # 建库 + 21 张表
│   ├── seed.sql                 # 演示数据
│   ├── README.md
│   └── BUSINESS_DESIGN.md       # WebSocket + 防超卖设计
├── 功能设计文档.md               # 完整功能与接口设计
├── design-system/               # 设计系统资源
├── CLAUDE.md                    # Claude Code 项目指引
└── README.md                    # 本文件

常用命令速查

后端

mvn clean package              # 构建（首次较慢）
mvn spring-boot:run            # 启动
mvn test                       # 跑测试
mvn test -Dtest=类名#方法名    # 单个测试方法

前端

npm install
npm run dev                    # 开发服务器
npm run build                  # 类型检查 + 生产构建
npm run type-check             # vue-tsc 类型检查
npm run lint                   # ESLint --fix
npm run format                 # Prettier 格式化

文档索引

文档	路径	何时读
Claude Code 项目指引	CLAUDE.md	使用 Claude Code 协助开发前
功能设计总览	功能设计文档.md	任何新模块开发前
业务核心设计	db/BUSINESS_DESIGN.md	客服 / 抢购相关开发前
数据库表结构	db/schema.sql + db/README.md	新增 / 修改实体前
管理端技术栈	admin-snack/README.md	前端环境问题排查
用户端说明	web-snack/README.md	用户端环境问题排查

调试与排错

• 后端启动失败 — 检查 MySQL / Redis 是否启动、端口是否被占用、Knife4j 文档能否打开
• 前端 401 风暴 — 检查 VITE_API_BASE_URL、浏览器是否带了 Authorization 头、Sa-Token 拦截器路径配置
• 抢购超卖 — 查看 Redis 中 seckill:stock:* 键值，对照 db/BUSINESS_DESIGN.md 流程
• 类型错误 — 运行 npm run type-check，不要绕过 vue-tsc 直接 build
• 本地上传文件访问不到 — 确认 WebMvcConfig.addResourceHandlers 中 /uploads/** 映射正确

浏览器支持

现代浏览器 + ES2020（Chrome 90+、Edge 90+、Firefox 90+、Safari 14+）

License

仅用于学习与毕业设计用途。