# VMarket

**Repository Path**: hf-sun/vmarket

## Basic Information

- **Project Name**: VMarket
- **Description**: VMarket 虚拟商品交易平台，采用 Spring Boot 3 + Vue 3 前后端分离架构，支持游戏道具、游戏账号、点卡充值、数字权益等多品类虚拟商品交易。平台提供担保交易、极速发货、找回包赔保障，覆盖用户选购、下单支付、订单履约、商家运营的全流程业务。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-16
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VMarket 虚拟商品交易平台

一套基于 Java 主流前后端分离架构的虚拟商品交易平台，覆盖商品浏览、购物车、下单支付、订单管理、个人中心、商家发布商品，以及平台公告、热销榜、商家推荐等运营模块，平台担保交易，全流程可追溯。

## 技术栈

| 层级 | 技术选型 |
| --- | --- |
| 核心基础 | JDK 17（运行于 21）、Spring Boot 3.2.x、Maven |
| 数据层 | MySQL 8.0、MyBatis-Plus 3.5.x、Redis 7.x |
| 鉴权权限 | Sa-Token |
| 接口增强 | Spring Validation、Knife4j 4.x |
| 前端 | Vue 3、Vite 5、Element Plus、Pinia、Axios |
| 工程化 | 统一响应封装、全局异常处理、自定义业务异常、Redis 缓存、接口限流、Docker |

## 项目结构

```
VMarket/
├── vmarket-backend/     # Spring Boot 后端
│   ├── src/main/java/com/vmarket/
│   │   ├── controller/  service/(impl)  mapper/  entity/  dto/  vo/
│   │   ├── config/      common/{result,exception,enums,constant,annotation}/
│   │   ├── task/        utils/
│   │   └── VmarketApplication.java
│   ├── src/main/resources/{application*.yml, db/schema.sql}
│   └── Dockerfile
├── vmarket-frontend/    # Vue3 前端
│   ├── src/{api,components,views,router,store,utils,layout,styles}/
│   ├── Dockerfile、nginx.conf
│   └── vite.config.js
├── docker-compose.yml   # 一键容器编排
└── .gitignore
```

## 一、本地启动

### 1. 环境要求
- JDK 17+（项目源码级 17，可运行于 JDK 21）
- Maven 3.8+
- MySQL 8.0、Redis 7.x
- Node.js 18+

### 2. 后端
1. 建库建表：执行 `vmarket-backend/src/main/resources/db/schema.sql`。
2. 配置：复制 `application-example.yml` 为 `application-dev.yml`，填入本机 MySQL / Redis 连接信息（该文件已被 `.gitignore` 屏蔽）。
3. 启动：
```bash
cd vmarket-backend
mvn spring-boot:run
```
4. 首次启动会自动初始化演示数据（分类、商品、公告、演示账号）。
5. 接口文档：http://localhost:8080/api/doc.html

### 3. 前端
```bash
cd vmarket-frontend
npm install
npm run dev
```
访问：http://localhost:5173 （已配置 `/api` 代理到后端 8080）

### 演示账号（首次启动自动创建，密码均为 123456）
- 管理员：`admin`
- 普通用户：`user`（初始余额 1000 元）
- 商家：`seller`

## 二、Docker 一键部署

确保已安装 Docker 与 Docker Compose，在项目根目录执行：
```bash
docker compose up -d --build
```
启动后：
- 前端：http://localhost
- 后端接口文档：http://localhost:8080/api/doc.html
- MySQL 对外端口 3307、Redis 对外端口 6380（避免与本机冲突）

停止并清理：
```bash
docker compose down          # 停止
docker compose down -v       # 停止并删除数据卷
```

## 三、接口文档使用

启动后端后访问 `http://localhost:8080/api/doc.html`（Knife4j）：
- 接口按模块分组：认证、个人中心、商品、交易、商家、运营、管理后台等。
- 需要登录的接口：先调用 `/auth/login` 获取 token，在文档右上角「认证」中填入请求头 `vmarket-token` 后即可调试。

## 四、核心特性
- Sa-Token 鉴权 + 自动续期，注解式接口权限控制（登录态 / 管理员角色）。
- 平台担保交易：买家付款资金由平台托管，确认收货后再结算给商家，全程流水可追溯。
- 订单状态机：待支付 → 待发货 → 待收货 → 已完成 / 已取消，未支付订单 30 分钟定时任务自动取消并恢复库存。
- 库存乐观扣减防止超卖，自动 / 手动发货，钱包余额支付与模拟支付。
- Redis 缓存首页热点、商品详情、分类列表，接口限流防刷。

## 五、分阶段开发记录
- 阶段 1：项目初始化与基础架构
- 阶段 2：用户体系与权限鉴权
- 阶段 3：商品分类与商品核心
- 阶段 4：交易核心（购物车 + 订单 + 支付）
- 阶段 5：商家运营与辅助功能
- 阶段 6：前端开发与联调
- 阶段 7：部署优化与工程化完善