# shop

**Repository Path**: lfc_6666/shop

## Basic Information

- **Project Name**: shop
- **Description**: 零食店，代买，快递代取等业务的一个校园app，小程序
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-05
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 校园零食跑腿小程序

## 项目简介
基于 SpringBoot 2.7.x + uni-app 的校园零食店+跑腿服务小程序。提供宿舍零食购买、取快递、取外卖、代买等校园生活服务。前后端分离架构，支持小程序、H5、App等多端运行。

**核心业务场景**：
- 🏪 **宿舍零食店**：在线购买零食、饮料，配送到宿舍
- 📦 **取快递服务**：帮忙代取快递，送到宿舍
- 🍔 **取外卖服务**：代取外卖，解决不方便出门问题  
- 🛒 **代买服务**：代购商品，满足各种需求

## 技术栈

### 后端技术栈
- **框架**: SpringBoot 2.7.6
- **数据库**: MySQL 5.7+
- **ORM**: MyBatis-Plus 3.5.3.1
- **认证授权**: Sa-Token 1.34.0
- **缓存**: Redis (Spring Data Redis)
- **接口文档**: Knife4j 4.1.0 (Swagger增强)
- **支付SDK**: 微信支付 wechatpay-java 0.2.17
- **工具类**: Lombok
- **数据校验**: Spring Boot Validation

### 前端技术栈
- **框架**: uni-app (Vue 2.x)
- **状态管理**: Vuex
- **HTTP客户端**: uni.request (已封装)
- **UI组件**: uView UI / uni-ui
- **构建工具**: HBuilderX / Vue CLI

## 项目结构

```
snack-shop/
├── admin/                          # 后端服务
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   │   └── com/snack/shop/
│   │   │   │       ├── common/         # 通用类
│   │   │   │       │   ├── Result.java           # 统一返回结果
│   │   │   │       │   ├── ResultCode.java       # 状态码枚举
│   │   │   │       │   ├── BusinessException.java # 业务异常
│   │   │   │       │   ├── GlobalExceptionHandler.java # 全局异常处理
│   │   │   │       │   ├── PageRequest.java      # 分页请求
│   │   │   │       │   └── PageResult.java       # 分页结果
│   │   │   │       ├── config/         # 配置类
│   │   │   │       │   ├── MybatisPlusConfig.java      # MyBatis-Plus配置
│   │   │   │       │   ├── SaTokenConfig.java          # Sa-Token配置
│   │   │   │       │   ├── RedisConfig.java            # Redis配置
│   │   │   │       │   ├── SwaggerConfig.java          # Swagger配置
│   │   │   │       │   ├── MyMetaObjectHandler.java    # 自动填充处理器
│   │   │   │       │   ├── JacksonConfig.java          # Jackson配置
│   │   │   │       │   ├── WebConfig.java              # Web配置
│   │   │   │       │   ├── WxPayConfig.java            # 微信支付配置
│   │   │   │       │   ├── WechatMiniappConfig.java    # 微信小程序配置
│   │   │   │       │   └── RestTemplateConfig.java     # RestTemplate配置
│   │   │   │       ├── controller/     # 控制器（业务代码）
│   │   │   │       ├── entity/         # 实体类
│   │   │   │       │   └── BaseEntity.java       # 基础实体类
│   │   │   │       ├── mapper/         # Mapper接口
│   │   │   │       ├── service/        # 服务层
│   │   │   │       ├── dto/            # 数据传输对象
│   │   │   │       └── ShopApplication.java  # 启动类
│   │   │   └── resources/
│   │   │       ├── application.yml           # 主配置文件
│   │   │       ├── application-dev.yml       # 开发环境配置
│   │   │       ├── application-prod.yml      # 生产环境配置
│   │   │       └── db/
│   │   │           └── schema.sql            # 数据库初始化脚本
│   │   └── test/
│   └── pom.xml                         # Maven依赖配置
├── snack-ui/                       # 前端项目
│   ├── utils/                      # 工具类
│   │   ├── request.js              # HTTP请求封装
│   │   └── date.js                 # 日期格式化工具
│   ├── store/                      # Vuex状态管理
│   │   └── index.js                # Store入口
│   ├── pages/                      # 页面（业务代码）
│   ├── components/                 # 组件（业务代码）
│   ├── api/                        # API接口
│   ├── static/                     # 静态资源
│   ├── App.vue                     # 应用根组件
│   ├── main.js                     # 入口文件
│   ├── manifest.json               # uni-app配置
│   ├── pages.json                  # 页面路由配置
│   └── package.json                # 项目依赖
├── docs/                   # 需求文档
│   ├── 00-意见反馈功能.md
│   └── 01-零食店模块需求.md
├── .gitignore
├── .commitlintrc.js                # Git提交规范配置
└── README.md
```

## 核心功能模块

### 规划中的业务功能

#### 1. 🏪 宿舍零食店
- 零食商品展示与分类（饮料、零食、日用品等）
- 商品搜索与筛选
- 购物车管理
- 在线下单支付
- 配送到宿舍
- 订单查询与评价

#### 2. 📦 取快递服务
- 快递代取下单
- 填写快递信息（快递公司、取件码、收件地址）
- 订单接单与配送
- 实时订单状态跟踪
- 配送费用结算

#### 3. 🍔 取外卖服务
- 外卖代取下单
- 外卖信息填写（商家、地址、备注）
- 配送员接单
- 订单状态更新
- 费用结算

#### 4. 🛒 代买服务
- 代购商品下单
- 商品描述与预算
- 接单与采购
- 费用确认与结算
- 送货上门

#### 5. 👤 用户管理
- 用户注册与登录（手机号/微信授权）
- 个人信息管理
- 收货地址管理
- 常用信息保存（宿舍楼、快递点等）

#### 6. 💰 订单管理
- 订单创建与提交
- 订单接单（骑手/配送员）
- 订单状态流转（待接单→配送中→已完成）
- 订单取消与退款
- 订单评价与投诉

#### 7. 🚴 配送员管理
- 配送员注册与认证
- 接单管理
- 收入统计
- 评价与信誉体系

#### 8. 💳 支付与结算
- 在线支付（微信小程序支付，已集成）
- 自动退款（订单取消时）
- 费用计算（商品费+配送费）
- 收益结算（配送员提现）
  
**已实现功能：**
- ✅ 微信小程序支付
- ✅ 支付回调处理
- ✅ 自动退款功能
- ✅ 订单状态自动更新

#### 9. 📊 数据统计
- 订单量统计
- 销售额统计  
- 用户活跃度分析
- 热门商品/服务排行

#### 10. 💬 意见反馈
- 商品问题反馈
- 配送服务反馈
- 系统功能建议
- 问题追踪与处理

### 已集成的基础功能

#### 后端核心功能

1. **统一响应结果封装**
   - `Result`: 统一返回结果类
   - `ResultCode`: 状态码枚举
   - 标准化API响应格式

2. **全局异常处理**
   - `GlobalExceptionHandler`: 全局异常处理器
   - `BusinessException`: 业务异常类
   - 统一异常响应格式

3. **分页封装**
   - `PageRequest`: 分页请求参数
   - `PageResult`: 分页返回结果
   - MyBatis-Plus分页插件集成

4. **MyBatis-Plus配置**
   - 分页插件
   - 自动填充（创建时间、更新时间）
   - 逻辑删除
   - 驼峰命名自动映射

5. **Sa-Token认证**
   - Token认证配置
   - 登录认证拦截
   - 多端登录支持
   - Token JSON 文件持久化（`./sa-token-data`），重启部署不丢失登录态

6. **Redis缓存**
   - Redis连接配置
   - 序列化配置

7. **Swagger接口文档**
   - Knife4j界面增强
   - 访问地址: `http://localhost:8080/api/doc.html`

8. **微信支付集成** ✨
   - 微信小程序支付
   - 支付回调处理
   - 自动退款功能
   - openid获取与存储
   - 配置详见：[支付接口文档](apiDoc/06-支付接口.md)

#### 前端核心功能

1. **HTTP请求封装**
   - 统一请求拦截（自动添加Token）
   - 统一响应处理（错误提示、登录过期跳转）
   - 支持 GET、POST、PUT、DELETE 方法
   - 加载状态管理

2. **日期工具类**
   - `formatDate`: 灵活的日期格式化
   - `formatDateForBackend`: 后端标准格式
   - `formatRelativeTime`: 相对时间显示
   - `formatDeadline`: 截止时间格式化

3. **Vuex状态管理**
   - 全局loading状态
   - 网络状态监测
   - 模块化状态管理

4. **微信小程序分享功能** ✨
   - 全局分享 Mixin（`utils/shareMixin.js`）
   - 支持"分享给朋友"和"分享到朋友圈"
   - 自动获取当前页面路径和参数
   - 支持页面自定义分享内容
   - 详细说明：[微信小程序分享功能实现说明](docs/微信小程序分享功能实现说明.md)

## 快速开始

### 环境要求

**后端**
- JDK 1.8+
- Maven 3.6+
- MySQL 5.7+
- Redis (可选)
- IDE：IntelliJ IDEA / Eclipse / VSCode + Java扩展包

**前端**
- Node.js 14+
- 微信开发者工具（开发小程序必需）
- HBuilderX（可选，也可以直接用命令行）

### 后端启动

#### 环境准备

1. **安装JDK 1.8+**
   - 下载：[Oracle JDK](https://www.oracle.com/java/technologies/javase-downloads.html) 或 [OpenJDK](https://openjdk.org/)
   - 配置环境变量：`JAVA_HOME`
   - 验证：`java -version`

2. **安装Maven（可选，IDEA自带）**
   - 下载：[Maven](https://maven.apache.org/download.cgi)
   - 验证：`mvn -v`

3. **安装IDE（推荐）**
   - **IntelliJ IDEA**（推荐）：[下载](https://www.jetbrains.com/idea/download/)
     - 社区版免费，已包含Java和Maven支持
     - 直接打开`admin`文件夹作为项目
   - **VSCode + Java扩展包**：
     - 安装 Extension Pack for Java
     - 安装 Spring Boot Extension Pack

#### 启动步骤

1. **配置数据库**
   
   修改 `admin/src/main/resources/application-dev.yml`:
   ```yaml
   spring:
     datasource:
       url: jdbc:mysql://localhost:3306/snack_shop?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
       username: root
       password: your_password
   ```

2. **初始化数据库**
   
   在MySQL中执行 `admin/src/main/resources/db/schema.sql`

3. **启动项目**

   **使用IDEA：**
   - 打开`admin`文件夹
   - 等待Maven依赖下载完成
   - 找到`ShopApplication.java`
   - 右键 -> Run 'ShopApplication'
   
   **使用命令行：**
   ```bash
   cd admin
   mvn spring-boot:run
   ```

4. **访问接口文档**
   
   浏览器打开: `http://localhost:8080/doc.html`

> **提示**：如果当前电脑没有Java运行环境，后端开发需要先安装JDK。前端可以独立开发，使用Mock数据或连接远程后端。

### 前端启动

1. **安装依赖**
   ```bash
   cd snack-ui
   npm install
   ```

2. **配置后端接口地址**
   
   `snack-ui/utils/request.js` 已配置:
   ```javascript
   const BASE_URL = process.env.NODE_ENV === 'development'
     ? 'http://localhost:8080' // 开发环境
     : 'https://your-domain.com' // 生产环境
   ```

3. **运行项目**

   **方式一：命令行运行（推荐）**
   ```bash
   # 微信小程序
   npm run dev:mp-weixin
   
   # 编译完成后，在微信开发者工具中导入项目
   # 导入路径：snack-ui/dist/dev/mp-weixin
   ```
   
   ```bash
   # H5
   npm run dev:h5
   # 访问：http://localhost:8080
   ```

   **方式二：使用HBuilderX**
   - 打开项目
   - 点击"运行" -> 选择目标平台

## 开发指南

### 后端开发流程

1. **创建实体类** (继承 `BaseEntity`)
   ```java
   @Data
   @EqualsAndHashCode(callSuper = true)
   @TableName("t_product")
   public class Product extends BaseEntity {
       private String name;
       private BigDecimal price;
       private Integer stock;
       // 其他字段...
   }
   ```

2. **创建Mapper接口**
   ```java
   @Mapper
   public interface ProductMapper extends BaseMapper<Product> {
   }
   ```

3. **创建Service**
   ```java
   @Service
   public class ProductService extends ServiceImpl<ProductMapper, Product> {
   }
   ```

4. **创建Controller**
   ```java
   @RestController
   @RequestMapping("/product")
   @RequiredArgsConstructor
   public class ProductController {
       private final ProductService productService;
       
       @GetMapping("/list")
       public Result<List<Product>> list() {
           return Result.success(productService.list());
       }
   }
   ```

### 前端开发流程

1. **创建API接口** (`api/product.js`)
   ```javascript
   import request from '@/utils/request'
   
   export const getProductList = () => {
     return request.get('/api/product/list')
   }
   ```

2. **创建Vuex模块** (可选)

3. **创建页面** (`pages/product/list.vue`)

4. **配置路由** (`pages.json`)

## 工具类说明

### BaseEntity
所有实体类的基类，包含:
- `id`: 主键ID（雪花算法）
- `createTime`: 创建时间（自动填充）
- `updateTime`: 更新时间（自动填充）
- `deleted`: 逻辑删除标志

### Result
统一返回结果:
```java
Result.success()           // 成功
Result.success(data)       // 成功并返回数据
Result.failed()            // 失败
Result.failed(message)     // 失败并返回消息
```

### request.js
HTTP请求封装:
```javascript
import request from '@/utils/request'

request.get('/api/product/list')
request.post('/api/product/add', { name: '商品' })
request.put('/api/product/update', { id: 1, name: '新名称' })
request.delete('/api/product/delete', { id: 1 })
```

## 代码规范

### Git提交规范

遵循 [Conventional Commits](https://www.conventionalcommits.org/):

```
<类型>[可选的作用域]: <描述>
```

**类型说明**:
- `feat`: 新功能
- `fix`: Bug修复
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试
- `chore`: 构建/工具
- `revert`: 回滚

**示例**:
```
feat(product): 添加商品管理功能
fix(order): 修复订单计算错误
docs: 更新README文档
```

## 常见问题

### 1. 后端启动失败
- 检查数据库配置
- 检查端口占用
- 查看日志错误信息

### 2. 前端请求失败
- 检查后端是否启动
- 检查接口地址配置
- 查看控制台错误

### 3. Token相关问题
- 检查TOKEN_NAME配置一致性（前后端都是 `ss_satoken`）
- 检查请求头是否正确携带Token

## 贡献指南

欢迎提交Issue和Pull Request!

## 许可证

MIT License

## 更新日志

### v1.0.0 (2025-10-04)
- 项目初始化
- 集成SpringBoot + MyBatis-Plus + Sa-Token
- 集成uni-app前端框架
- 完善基础框架和工具类