# exchange

**Repository Path**: guxuefeng/exchange

## Basic Information

- **Project Name**: exchange
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-29
- **Last Updated**: 2025-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 商品兑换平台 - 综合商品兑换系统 (Exchange Platform - Comprehensive Goods Exchange System)

## 概述 (Overview)

这是一个综合性的商品兑换平台，具有以下关键功能：
- 支持多个商家的多租户架构
- 免费套餐（带有资源限制）和付费套餐选项
- 用于商品兑换的兑换码系统
- 包含快递和自提选项的客户兑换流程
- 订单管理和跟踪
- 用于管理商家的管理员面板
- 带有数据分析的商家仪表板
- H5 和移动响应式界面

## 架构 (Architecture)

### 后端 (Backend)
- **框架**: Spring Boot 3.2.0
- **数据库**: MySQL 8.0+
- **缓存**: Redis
- **安全**: 使用 JWT 认证的 Spring Security
- **ORM**: Spring Data JPA

### 前端 (Frontend)
- **框架**: Vue 3
- **UI 组件**: Element Plus
- **路由**: Vue Router
- **状态管理**: Vuex

## 数据库设置 (Database Setup)

1. 使用提供的脚本 `database_init.sql` 创建数据库
2. 创建具有以下详细信息的 MySQL 用户：
   - 用户名: `exchange`
   - 密码: `exchange`
   - 数据库: `exchange`
3. 在 application.yml 文件中更新数据库凭证

## 后端设置 (Backend Setup)

### 环境要求 (Prerequisites)
- Java 17+
- Maven 3.6+
- MySQL 8.0+
- Redis

### 配置 (Configuration)
在后端的 `application.yml` 文件中使用您的设置进行更新：
- 数据库连接详情
- Redis 连接详情
- 邮件服务器设置（用于通知）
- JWT 密钥和过期时间
- 免费套餐的资源限制

### 运行后端 (Running the Backend)
```bash
cd backend
mvn spring-boot:run
```

后端默认在端口 8080 上启动。

## 前端设置 (Frontend Setup)

### 环境要求 (Prerequisites)
- Node.js 16+
- npm 或 yarn

### 安装 (Installation)
```bash
cd frontend
npm install
```

### 运行前端 (Running the Frontend)
```bash
npm run serve
```

前端默认在端口 8081 上启动，并将 API 调用代理到端口 8080 上的后端。

## API 文档 (API Documentation)

### 认证 (Authentication)
- **登录**: `POST /api/auth/login`
  - 请求: `{username: string, password: string}`
  - 响应: `{token: string, user: UserDto}`

- **注册**: `POST /api/auth/register`
  - 请求: `{username: string, email: string, password: string, phone: string}`
  - 响应: `{user: UserDto, message: string}`

### 客户兑换流程 (Customer Exchange Process)
- **验证兑换码**: `POST /api/public/exchange`
  - 请求: `{code: string}`
  - 响应: 兑换码详情和相关产品

- **完成兑换**: `POST /api/public/exchange/complete`
  - 请求: `{code: string, customerName: string, customerPhone: string, customerEmail: string, deliveryType: "SHIP"|"PICKUP", shippingAddress: string}`
  - 响应: 创建的订单详情

- **跟踪订单**: `GET /api/public/order/track/{orderNumber}`
  - 响应: 订单状态和配送信息

### 商家 API (Merchant APIs)
- **获取产品**: `GET /api/products`
- **创建产品**: `POST /api/products`
- **获取兑换码**: `GET /api/exchange-codes`
- **创建兑换码**: `POST /api/exchange-codes`
- **批量生成兑换码**: `POST /api/exchange-codes/batch-generate`
- **获取订单**: `GET /api/orders`
- **更新订单状态**: `PUT /api/orders/{id}`
- **获取仪表板**: `GET /api/dashboard/merchant`

### 管理员 API (Admin APIs)
- **获取商家**: `GET /api/admin/merchants`
- **更新商家**: `PUT /api/admin/merchants/{id}`
- **更新商家状态**: `PUT /api/admin/merchants/{id}/status`

## 资源限制 (Resource Limiting)

系统为免费商家实施资源限制：
- 最大产品数量（默认：10）
- 最大兑换码数量（默认：100）
- 每月最大订单数量（默认：100）

这些限制可以在 `application.yml` 中配置，并且管理员可以为个别商家覆盖这些限制。

## 核心功能实现 (Key Features Implementation)

### 1. 多租户架构 (Multi-tenant Architecture)
- 每个商家都有独立的空间，包括自己的产品、兑换码和订单
- 资源限制按商家应用
- 通过适当的授权实现数据隔离访问

### 2. 兑换码系统 (Exchange Code System)
- 生成唯一的兑换码（支持批量生成）
- 兑换码为一次性使用，可以设置过期日期
- 使用前进行验证和确认
- 自动跟踪兑换码使用情况

### 3. 灵活配送选项 (Flexible Delivery Options)
- 包含跟踪信息的配送服务
- 店铺自提选项
- 配送状态更新和跟踪

### 4. 客户体验 (Customer Experience)
- 简单的兑换码输入界面
- 订单状态跟踪
- 移动响应式设计
- H5 兼容性

### 5. 商家工具 (Merchant Tools)
- 产品管理
- 兑换码管理
- 订单处理
- 带有数据分析的仪表板
- 配送跟踪更新

### 6. 管理员控制 (Admin Controls)
- 商家入驻
- 订阅管理
- 资源分配
- 系统监督

## 安全措施 (Security Measures)

- 基于 JWT 的认证
- 基于角色的访问控制（管理员、商家）
- 使用 BCrypt 的密码加密
- 输入验证和清理
- 安全会话管理
- 使用适当密钥管理的 Redis 缓存

## 移动响应式设计 (Mobile Responsiveness)

前端设计为完全响应式：
- 用于移动导航的汉堡菜单
- 响应式网格布局
- 触摸友好的控制
- 为各种屏幕尺寸优化

## 设置清单 (Setup Checklist)

### 开发环境 (For Development)
1. [x] 数据库模式创建
2. [x] 后端项目结构
3. [x] 前端项目结构
4. [x] 用户管理和认证
5. [x] 商家入驻
6. [x] 产品管理
7. [x] 兑换码系统
8. [x] 客户兑换流程
9. [x] 订单管理
10. [x] 配送跟踪
11. [x] 商家仪表板
12. [x] 管理员面板
13. [x] 移动响应式设计
14. [x] Redis 缓存
15. [x] 安全实现
16. [x] 资源限制
17. [ ] 最终测试
18. [ ] 文档

### 生产环境 (For Production)
1. 安全的 JWT 密钥
2. 生产数据库配置
3. 生产环境的 Redis 配置
4. SSL 证书
5. 负载均衡设置（如果需要）
6. 监控和日志配置
7. 备份程序
8. 安全加固

## API 端点 (API Endpoints)

### 公共端点 (Public Endpoints)
- `/api/public/exchange` - 验证和使用兑换码
- `/api/public/order/track/{orderNumber}` - 跟踪订单状态

### 认证端点 (Authenticated Endpoints)
- `/api/auth/login` - 用户认证
- `/api/auth/register` - 用户注册
- `/api/products` - 产品管理（商家/管理员）
- `/api/exchange-codes` - 兑换码管理（商家/管理员）
- `/api/orders` - 订单管理（商家/管理员）
- `/api/dashboard` - 仪表板访问（商家/管理员）
- `/api/admin` - 管理员面板（仅管理员）
- `/api/merchant` - 商家档案（商家/管理员）
- `/api/delivery` - 配送跟踪（商家/管理员）
- `/api/resources` - 资源使用（商家/管理员）

## 文件结构 (File Structure)

```
exchange/
├── backend/                    # Spring Boot 应用程序
│   ├── src/main/java/com/exchange/
│   │   ├── config/            # 配置类
│   │   ├── controller/        # API 控制器
│   │   ├── dto/              # 数据传输对象
│   │   ├── entity/           # JPA 实体
│   │   ├── repository/       # JPA 仓库
│   │   ├── service/          # 业务逻辑
│   │   ├── security/         # 安全工具
│   │   ├── aspect/           # AOP 方面（资源限制）
│   │   └── util/             # 工具类
│   └── pom.xml
├── frontend/                   # Vue3 应用程序
│   ├── public/
│   ├── src/
│   │   ├── components/       # Vue 组件
│   │   ├── views/            # 页面视图
│   │   ├── router/           # Vue 路由
│   │   ├── store/            # Vuex 状态管理
│   │   ├── styles/           # SCSS 样式
│   │   └── utils/            # 工具类
│   ├── package.json
│   └── vue.config.js
├── database_init.sql          # 数据库初始化脚本
└── README.md                 # 此文件
```

## 使用的技术 (Technologies Used)

### 后端 (Backend)
- Java 17
- Spring Boot 3.2.0
- Spring Security
- Spring Data JPA
- MySQL 8.0+
- Redis
- Hibernate
- JWT
- BCrypt
- Lombok
- Jackson
- Maven

### 前端 (Frontend)
- Vue 3
- Element Plus
- Vue Router
- Vuex
- Axios
- SCSS
- NPM

## 附加功能 (Additional Features)

- 二维码生成（通过 ZXing 库）
- 电子邮件通知
- Redis 缓存性能优化
- 使用 AOP 的资源限制
- 综合错误处理
- 日志配置
- 安全工具
- 响应式设计

这完成了具有所有要求功能的综合商品兑换平台的实现。