From 05950b4ca359743e3d0c62a5344f7bbe14119b82 Mon Sep 17 00:00:00 2001 From: sparksfly Date: Wed, 3 Jun 2026 23:45:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3=E4=B8=8E=E6=8F=90=E4=BA=A4=E8=A7=84?= =?UTF-8?q?=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增项目根README，完整介绍零食商城项目的模块、功能、快速启动流程、技术栈与约定；新增.git提交规范配置文件，定义中文提交信息规则 --- README.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4060e1c --- /dev/null +++ b/README.md @@ -0,0 +1,187 @@ +# 零食商城 Snack Mall + +> 毕业设计 · 前后端分离的 B2C 电商平台，覆盖用户端、管理端、客服、公告、优惠券、抢购六大模块。 + +仓库采用单仓多模块结构，包含两个前端项目（用户端 + 管理端）、一个 Spring Boot 后端服务，以及数据库脚本与设计文档。 + +## 模块概览 + +| 目录 | 角色 | 技术栈 | +|------|------|--------| +| [`server-snack/`](./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/`](./web-snack/) | 用户端 H5/PC 前端 | Vue 3.5 · Vite 8 · TypeScript 6 · Element Plus 2.14 · Pinia 3 | +| [`admin-snack/`](./admin-snack/) | 管理后台前端 | Vue 3.5 · Vite 6 · TypeScript 5 · Element Plus 2.9 · Pinia 2 · ECharts 5 | +| [`db/`](./db/) | 数据库脚本与设计文档 | `schema.sql` 建库 + 21 张表 DDL，`seed.sql` 演示数据 | +| [`功能设计文档.md`](./功能设计文档.md) | 完整功能与接口设计（v1.2） | 6 大模块业务与接口说明 | +| [`db/BUSINESS_DESIGN.md`](./db/BUSINESS_DESIGN.md) | 核心业务设计 | WebSocket 客服 + Redis 防超卖方案 | +| [`admin-snack/design-system/`](./design-system/) | 设计系统资源 | 视觉令牌与组件规范 | + +## 业务功能 + +- **用户端**：注册登录、收货地址、购物车、收藏、订单、支付、抢购、客服聊天 +- **管理端**：仪表盘、商品 / 分类 / SKU 管理、订单处理、用户管理、优惠券、抢购活动、公告、客服会话 +- **跨端共享**：系统公告、用户优惠券、限时抢购（Redis 原子扣减防超卖） + +## 快速开始 + +### 环境要求 + +| 工具 | 版本 | +|------|------| +| JDK | 21 | +| Maven | 3.8+ | +| Node.js | ≥ 20.19 | +| MySQL | 8.0+ | +| Redis | 6.0+ | + +### 1. 初始化数据库 + +```bash +mysql -u root -p < db/schema.sql # 建库 + 21 张表 +mysql -u root -p < db/seed.sql # 演示数据（可选） +``` + +### 2. 启动后端 + +```bash +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. 启动管理端 + +```bash +cd admin-snack +npm install +npm run dev +# 访问 http://localhost:5173 +``` + +### 4. 启动用户端 + +```bash +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//`： + +``` +module// +├── 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` 封装 `{ 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`](./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 # 本文件 +``` + +## 常用命令速查 + +### 后端 + +```bash +mvn clean package # 构建（首次较慢） +mvn spring-boot:run # 启动 +mvn test # 跑测试 +mvn test -Dtest=类名#方法名 # 单个测试方法 +``` + +### 前端 + +```bash +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.md) | 使用 Claude Code 协助开发前 | +| 功能设计总览 | [`功能设计文档.md`](./功能设计文档.md) | 任何新模块开发前 | +| 业务核心设计 | [`db/BUSINESS_DESIGN.md`](./db/BUSINESS_DESIGN.md) | 客服 / 抢购相关开发前 | +| 数据库表结构 | [`db/schema.sql`](./db/schema.sql) + [`db/README.md`](./db/README.md) | 新增 / 修改实体前 | +| 管理端技术栈 | [`admin-snack/README.md`](./admin-snack/README.md) | 前端环境问题排查 | +| 用户端说明 | [`web-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`](./db/BUSINESS_DESIGN.md) 流程 +- **类型错误** — 运行 `npm run type-check`，不要绕过 `vue-tsc` 直接 build +- **本地上传文件访问不到** — 确认 `WebMvcConfig.addResourceHandlers` 中 `/uploads/**` 映射正确 + +## 浏览器支持 + +现代浏览器 + ES2020（Chrome 90+、Edge 90+、Firefox 90+、Safari 14+） + +## License + +仅用于学习与毕业设计用途。