docs: 初始化项目文档与提交规范
新增项目根README，完整介绍零食商城项目的模块、功能、快速启动流程、技术栈与约定；新增.git提交规范配置文件，定义中文提交信息规则
This commit is contained in:
parent
487778f0f8
commit
05950b4ca3
|
|
@ -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/<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`](./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
|
||||||
|
|
||||||
|
仅用于学习与毕业设计用途。
|
||||||
Loading…
Reference in New Issue