# 🌱 农产品直销平台 (SunnyFarm)

一个基于 Spring Boot + Vue.js + MySQL 的现代化农产品电商平台，支持多角色管理（用户、商家、管理员），提供完整的电商功能包括商品管理、订单处理、支付集成、库存管理等。

## 📋 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [部署指南](#部署指南)
- [API文档](#api文档)
- [贡献指南](#贡献指南)

## ✨ 功能特性

### 🛒 核心电商功能
- **商品管理**: 分类管理、商品发布、图片上传、库存管理
- **购物车**: 添加商品、数量调整、批量操作
- **订单系统**: 创建订单、支付集成、状态跟踪、物流管理
- **用户系统**: 注册登录、个人中心、收货地址管理
- **评价系统**: 商品评价、商家回复、评分统计

### 👥 多角色支持
- **普通用户**: 浏览商品、下单购买、管理订单
- **商家**: 商品管理、订单处理、销售统计、客服聊天
- **平台管理员**: 用户管理、商家审核、系统配置、数据统计

### 🔧 技术亮点
- **支付集成**: 支付宝沙箱支付，支持异步回调
- **文件存储**: 腾讯云COS + CDN加速
- **缓存优化**: Redis缓存用户会话和购物车数据
- **邮件服务**: 注册验证码、订单通知
- **实时聊天**: 用户与商家在线客服
- **响应式设计**: 支持PC端和移动端访问

## 🛠 技术栈

### 后端技术
- **框架**: Spring Boot 2.7.14
- **安全**: Spring Security + JWT认证
- **数据库**: MySQL 8.0 + MyBatis Plus
- **缓存**: Redis
- **文件存储**: 腾讯云COS
- **支付**: 支付宝开放平台
- **邮件**: Spring Boot Mail

### 前端技术
- **框架**: Vue 3 + Vite
- **UI组件**: Element Plus
- **状态管理**: Pinia
- **路由**: Vue Router 4
- **图表**: ECharts
- **HTTP客户端**: Axios

### 运维部署
- **容器化**: Docker + Docker Compose
- **云服务**: 支持各类云平台部署
- **反向代理**: Nginx
- **进程管理**: PM2（可选）

## 📋 环境要求

### 开发环境
- **Java**: JDK 8 或以上
- **Node.js**: 16.0 或以上
- **Maven**: 3.6 或以上
- **MySQL**: 8.0 或以上
- **Redis**: 6.0 或以上

### 生产环境
- **服务器**: Linux (推荐 Ubuntu 20.04+)
- **内存**: 建议 2GB 以上
- **存储**: 建议 20GB 以上
- **网络**: 需要公网IP或域名（用于支付回调）

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://git.sq0715.com/qin/SunnyFarm.git
cd SunnyFarm
```

### 2. 配置文件设置

#### 后端配置

复制配置模板并填入你的配置信息：

```bash
# 开发环境配置
cp backend/src/main/resources/application-dev.yml.example backend/src/main/resources/application-dev.yml

# 生产环境配置  
cp backend/src/main/resources/application-prod.yml.example backend/src/main/resources/application-prod.yml
```

### 3. 数据库初始化

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE sunnyfarm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入数据库结构和初始数据
mysql -u your_username -p sunnyfarm < sql/sunnyfarm.sql
mysql -u your_username -p sunnyfarm < sql/init_inventory.sql
```

### 4. 启动后端服务

```bash
cd backend
mvn clean install
mvn spring-boot:run
```

服务启动后访问: http://localhost:8080/api/init/status

### 5. 启动前端服务

```bash
cd frontend
npm install
npm run dev
```

前端启动后访问: http://localhost:3000

## ⚙️ 配置说明

### 数据库配置
```yaml
spring:
  datasource:
    url: jdbc:mysql://your-mysql-host:3306/sunnyfarm
    username: your-db-username  
    password: your-db-password
```

### Redis配置
```yaml
spring:
  redis:
    host: your-redis-host
    port: 6379
    password: your-redis-password
```

### 邮件服务配置 (QQ邮箱示例)
```yaml
spring:
  mail:
    host: smtp.qq.com
    port: 465
    username: your-email@qq.com
    password: your-email-auth-code  # QQ邮箱授权码
```

### 腾讯云COS配置
```yaml
tencent:
  cos:
    secret-id: your-tencent-cos-secret-id
    secret-key: your-tencent-cos-secret-key  
    region: ap-guangzhou
    bucket: your-bucket-name
```

### 支付宝配置
```yaml
alipay:
  app-id: your-alipay-app-id
  app-private-key: your-alipay-app-private-key
  alipay-public-key: your-alipay-public-key
  notify-url: http://your-domain:8080/api/payment/alipay/notify
  return-url: http://your-domain:3000/orders?payment=success
```

**重要**: 支付宝回调地址必须是公网可访问的地址，不能使用localhost

### JWT配置
```yaml
jwt:
  secret: your-jwt-secret-key
  expiration: 86400000  # 24小时，单位毫秒
```

## 🐳 Docker部署

### 使用Docker Compose部署

```bash
# 构建并启动服务
docker-compose up -d

# 查看服务状态  
docker-compose ps

# 查看日志
docker-compose logs -f
```

### 手动Docker部署

```bash
# 构建后端镜像
cd backend  
docker build -t sunnyfarm-backend .

# 构建前端镜像
cd ../frontend
docker build -t sunnyfarm-frontend .

# 启动服务
docker run -d -p 8080:8080 --name sunnyfarm-backend sunnyfarm-backend
docker run -d -p 3000:3000 --name sunnyfarm-frontend sunnyfarm-frontend
```

## 🌍 生产环境部署

### 1. 服务器准备

```bash
# 安装基础软件
sudo apt update && sudo apt install -y git docker.io docker-compose nginx

# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker
```

### 2. 克隆项目并配置

```bash
git clone https://git.sq0715.com/qin/SunnyFarm.git
cd SunnyFarm

# 配置生产环境文件
cp backend/src/main/resources/application-prod.yml.example backend/src/main/resources/application-prod.yml
# 编辑配置文件，填入生产环境配置信息
vim backend/src/main/resources/application-prod.yml
```

### 3. 部署启动

```bash
# 构建并启动
docker-compose up -d

# 检查服务状态
docker-compose ps
curl http://your-server-ip:8080/api/init/status
```

## 📚 API文档

### 认证接口

| 方法 | 路径 | 说明 | 
|------|------|------|
| POST | `/api/user/login` | 用户登录 |
| POST | `/api/user/register` | 用户注册 |  
| POST | `/api/merchant/login` | 商家登录 |
| POST | `/api/admin/login` | 管理员登录 |

### 商品接口

| 方法 | 路径 | 说明 |
|------|------|------|  
| GET | `/api/product/list` | 商品列表 |
| GET | `/api/product/{id}` | 商品详情 |
| POST | `/api/product/create` | 创建商品(商家) |
| PUT | `/api/product/{id}` | 更新商品(商家) |

### 订单接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/order/create` | 创建订单 |
| GET | `/api/order/list` | 订单列表 | 
| GET | `/api/order/{id}` | 订单详情 |
| POST | `/api/order/{id}/pay` | 订单支付 |

## 🎯 默认账号

### 管理员账号
- 用户名: `admin`
- 密码: `admin123`

### 测试商家账号
- 用户名: `merchant`
- 密码: `merchant123`

### 测试用户账号
- 用户名: `user`
- 密码: `user123`

## 📝 开发说明

### 项目结构

```
SunnyFarm/
├── backend/                 # 后端Spring Boot项目
│   ├── src/main/java/      # Java源码
│   ├── src/main/resources/ # 配置文件
│   └── pom.xml            # Maven配置
├── frontend/               # 前端Vue项目  
│   ├── src/               # Vue源码
│   ├── public/            # 静态资源
│   └── package.json       # NPM配置
├── sql/                   # 数据库脚本
├── docker-compose.yml     # Docker编排
└── README.md             # 项目文档
```

### 开发规范

- 代码格式化: 使用项目配置的格式化规则
- 提交规范: 使用语义化提交信息
- 分支管理: 使用Git Flow工作流
- 代码审查: 重要功能需要代码审查

## 🤝 贡献指南

1. Fork本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 联系方式

- 项目地址: https://git.sq0715.com/qin/SunnyFarm
- 问题反馈: 请在GitHub Issues中提交
- 邮箱联系: 852326703@qq.com

## 🙏 致谢

感谢所有为本项目做出贡献的开发者们！

---

**注意**: 本项目仅供学习和研究使用，请勿用于商业用途。使用前请确保遵守相关法律法规。