# light-speed-express

**Repository Path**: xgyharmony/light-speed-express

## Basic Information

- **Project Name**: light-speed-express
- **Description**: 正在开发中......
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-29
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 光速外卖 (Light Speed Express)

<div align="center">

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.3-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![MyBatis](https://img.shields.io/badge/MyBatis-2.2.0-orange.svg)](https://mybatis.org/mybatis-3/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

**基于 Spring Boot + MyBatis 的餐饮外卖管理系统**

[主要特性](#主要特性) • [技术栈](#技术栈) • [项目结构](#项目结构) • [快速开始](#快速开始) • [API 文档](#API文档) • [系统架构](#系统架构)

</div>

---

## 📖 项目简介

光速外卖是一个现代化的餐饮外卖管理系统，采用前后端分离架构，提供完整的订单管理、菜品管理、套餐管理、员工管理等功能。系统分为**管理端**和**用户端**双端接口，支持 JWT 认证、微信支付、阿里云 OSS 文件存储等企业级功能。

### 核心业务
- 🍽️ **菜品管理**：菜品分类、菜品维护、口味配置
- 📦 **套餐管理**：套餐组合、状态控制
- 🛒 **订单管理**：下单、支付、接单、派单、完成全流程
- 👥 **员工管理**：员工信息、权限控制、账号状态
- 📊 **数据报表**：营业额统计、订单统计、销量排行
- 🏪 **店铺管理**：营业状态、店铺信息

---

## 🚀 主要特性

### 核心功能
- ✅ **双端接口设计**：管理端 (`/admin/**`) 和用户端 (`/user/**`) 完全分离
- 🔐 **JWT 身份认证**：管理员和用户独立的 Token 认证机制
- 💳 **微信支付集成**：完整的支付流程，包括预支付、回调通知
- ☁️ **阿里云 OSS**：图片上传存储，支持菜品图片管理
- 📝 **AOP 自动填充**：基于切面的公共字段自动填充（创建时间、更新时间等）
- 🎯 **全局异常处理**：统一的异常捕获和友好的错误响应
- 🔄 **事务管理**：基于注解的声明式事务控制
- ⏰ **定时任务**：订单超时自动取消、派送等定时处理
- 📡 **WebSocket 支持**：实时消息推送（催单提醒等）
- 📄 **Knife4j 接口文档**：美观的 API 文档界面

### 技术亮点
- 🏷️ **分层架构**：Controller → Service → Mapper → DB，职责清晰
- 📦 **多模块 Maven**：light-common、light-pojo、light-server 模块化设计
- 🗂️ **数据模型分离**：DTO、Entity、VO 各司其职
- 🔧 **MyBatis XML 映射**：灵活的 SQL 管理与优化
- 📊 **Druid 连接池**：高性能数据库连接池，带监控功能
- 📑 **PageHelper 分页**：简洁高效的物理分页
- 🎨 **Lombok 简化代码**：减少样板代码，提升开发效率

---

## 🛠️ 技术栈

### 后端框架
| 技术 | 版本 | 说明 |
|------|------|------|
| **Spring Boot** | 2.7.3 | 核心开发框架 |
| **MyBatis** | 2.2.0 | 数据持久层框架 |
| **MyBatis PageHelper** | 1.3.0 | 分页插件 |
| **Druid** | 1.2.1 | 数据库连接池 |

### 认证与安全
| 技术 | 版本 | 说明 |
|------|------|------|
| **JWT (jjwt)** | 0.9.1 | Token 认证 |
| **拦截器** | - | JWT 令牌校验拦截 |

### 第三方服务
| 技术 | 版本 | 说明 |
|------|------|------|
| **微信支付** | 0.4.8 | 微信 SDK |
| **阿里云 OSS** | 3.10.2 | 对象存储 |
| **Redis** | - | 缓存中间件 |

### 工具与组件
| 技术 | 版本 | 说明 |
|------|------|------|
| **Knife4j** | 3.0.2 | Swagger 增强，API 文档 |
| **Lombok** | 1.18.20 | 简化代码 |
| **FastJSON** | 1.2.76 | JSON 处理 |
| **Apache POI** | 3.16 | Excel 导入导出 |
| **AspectJ** | 1.9.4 | AOP 切面编程 |
| **Jackson** | - | JSON 序列化 |

### 开发环境
- **JDK**: 1.8+
- **Maven**: 3.6+
- **MySQL**: 5.7+ / 8.0+
- **Redis**: 5.0+

---

## 📁 项目结构

```
light-speed-express/
├── light-common/              # 公共模块
│   └── src/main/java/com/light/
│       ├── constant/          # 常量类
│       │   ├── AutoFillConstant.java      # 自动填充常量
│       │   ├── JwtClaimsConstant.java     # JWT Claims 常量
│       │   ├── MessageConstant.java       # 消息常量
│       │   ├── PasswordConstant.java      # 密码常量
│       │   └── StatusConstant.java        # 状态常量
│       ├── context/           # 上下文
│       │   └── BaseContext.java           # 线程上下文（存储当前用户 ID）
│       ├── enumeration/       # 枚举
│       │   └── OperationType.java         # 操作类型枚举
│       ├── exception/         # 自定义异常
│       │   ├── AccountLockedException.java          # 账号锁定异常
│       │   ├── AccountNotFoundException.java        # 账号不存在异常
│       │   ├── AddressBookBusinessException.java    # 地址簿业务异常
│       │   ├── BaseException.java                   # 基础异常
│       │   ├── DeletionNotAllowedException.java     # 不允许删除异常
│       │   ├── LoginFailedException.java            # 登录失败异常
│       │   ├── OrderBusinessException.java          # 订单业务异常
│       │   ├── PasswordEditFailedException.java     # 修改密码失败异常
│       │   ├── PasswordErrorException.java          # 密码错误异常
│       │   ├── SetmealEnableFailedException.java    # 套餐启用失败异常
│       │   ├── ShoppingCartBusinessException.java   # 购物车业务异常
│       │   └── UserNotLoginException.java           # 用户未登录异常
│       ├── json/              # JSON 处理
│       │   └── JacksonObjectMapper.java   # Jackson 对象映射器
│       ├── properties/        # 配置属性类
│       │   ├── AliOssProperties.java      # 阿里云 OSS 配置
│       │   ├── JwtProperties.java         # JWT 配置
│       │   └── WeChatProperties.java      # 微信配置
│       ├── result/            # 统一返回结果
│       │   ├── PageResult.java            # 分页结果
│       │   └── Result.java                # 统一响应结果
│       ├── utils/             # 工具类
│       │   ├── AliOssUtil.java            # 阿里云 OSS 工具
│       │   ├── HttpClientUtil.java        # HTTP 客户端工具
│       │   ├── JwtUtil.java               # JWT 工具
│       │   └── WeChatPayUtil.java         # 微信支付工具
│       └── pom.xml
│
├── light-pojo/                # 数据模型模块
│   └── src/main/java/com/light/
│       ├── dto/               # 数据传输对象（接收参数）
│       │   ├── CategoryDTO.java
│       │   ├── CategoryPageQueryDTO.java
│       │   ├── DishDTO.java
│       │   ├── DishPageQueryDTO.java
│       │   ├── EmployeeDTO.java
│       │   ├── EmployeeLoginDTO.java
│       │   ├── OrdersCancelDTO.java
│       │   ├── OrdersConfirmDTO.java
│       │   ├── OrdersDTO.java
│       │   ├── OrdersPaymentDTO.java
│       │   ├── OrdersSubmitDTO.java
│       │   ├── SetmealDTO.java
│       │   └── ... (其他 DTO)
│       ├── entity/            # 实体类（对应数据库表）
│       │   ├── AddressBook.java
│       │   ├── Category.java
│       │   ├── Dish.java
│       │   ├── DishFlavor.java
│       │   ├── Employee.java
│       │   ├── OrderDetail.java
│       │   ├── Orders.java
│       │   ├── Setmeal.java
│       │   ├── SetmealDish.java
│       │   ├── ShoppingCart.java
│       │   └── User.java
│       └── vo/                # 视图对象（返回给前端）
│           ├── BusinessDataVO.java
│           ├── DishOverViewVO.java
│           ├── DishVO.java
│           ├── EmployeeLoginVO.java
│           ├── OrderOverViewVO.java
│           ├── OrderPaymentVO.java
│           ├── OrderReportVO.java
│           ├── OrderSubmitVO.java
│           ├── OrderVO.java
│           ├── SalesTop10ReportVO.java
│           ├── SetmealOverViewVO.java
│           ├── SetmealVO.java
│           ├── TurnoverReportVO.java
│           ├── UserLoginVO.java
│           └── ... (其他 VO)
│       └── pom.xml
│
└── light-server/              # 服务端模块（主启动模块）
    └── src/main/
        ├── java/com/light/
        │   ├── annotation/        # 自定义注解
        │   │   └── AutoFill.java              # 自动填充注解
        │   ├── aspect/            # 切面
        │   │   └── AutoFillAspect.java        # 自动填充切面
        │   ├── config/            # 配置类
        │   │   ├── OssConfiguration.java      # OSS 配置
        │   │   ├── RedisConfiguration.java    # Redis 配置
        │   │   ├── WebMvcConfiguration.java   # Web MVC 配置（拦截器、Swagger）
        │   │   └── WebSocketConfiguration.java# WebSocket 配置
        │   ├── controller/        # 控制器层
        │   │   ├── admin/                     # 管理端接口
        │   │   │   ├── CategoryController.java
        │   │   │   ├── CommonController.java
        │   │   │   ├── DishController.java
        │   │   │   ├── EmployeeController.java
        │   │   │   ├── OrderController.java
        │   │   │   ├── ReportController.java
        │   │   │   ├── SetmealController.java
        │   │   │   ├── ShopController.java
        │   │   │   └── WorkSpaceController.java
        │   │   ├── notify/                    # 通知接口
        │   │   │   └── PayNotifyController.java  # 支付回调通知
        │   │   └── user/                      # 用户端接口
        │   │       ├── AddressBookController.java
        │   │       ├── CategoryController.java
        │   │       ├── DishController.java
        │   │       ├── OrderController.java
        │   │       ├── SetmealController.java
        │   │       ├── ShopController.java
        │   │       ├── ShoppingCartController.java
        │   │       └── UserController.java
        │   ├── handler/           # 处理器
        │   │   └── GlobalExceptionHandler.java  # 全局异常处理器
        │   ├── interceptor/       # 拦截器
        │   │   ├── JwtTokenAdminInterceptor.java  # 管理员 JWT 拦截器
        │   │   └── JwtTokenUserInterceptor.java   # 用户 JWT 拦截器
        │   ├── mapper/            # 数据访问层
        │   │   ├── AddressBookMapper.java
        │   │   ├── CategoryMapper.java
        │   │   ├── DishFlavorMapper.java
        │   │   ├── DishMapper.java
        │   │   ├── EmployeeMapper.java
        │   │   ├── OrderDetailMapper.java
        │   │   ├── OrderMapper.java
        │   │   ├── SetmealDishMapper.java
        │   │   ├── SetmealMapper.java
        │   │   ├── ShoppingCartMapper.java
        │   │   └── UserMapper.java
        │   ├── service/           # 业务逻辑层
        │   │   ├── impl/                        # 实现类
        │   │   │   ├── AddressBookServiceImpl.java
        │   │   │   ├── CategoryServiceImpl.java
        │   │   │   ├── DishServiceImpl.java
        │   │   │   ├── EmployeeServiceImpl.java
        │   │   │   ├── OrderServiceImpl.java
        │   │   │   ├── ReportServiceImpl.java
        │   │   │   ├── SetmealServiceImpl.java
        │   │   │   ├── ShoppingCartServiceImpl.java
        │   │   │   ├── UserServiceImpl.java
        │   │   │   └── WorkSpaceServiceImpl.java
        │   │   ├── AddressBookService.java
        │   │   ├── CategoryService.java
        │   │   ├── DishService.java
        │   │   ├── EmployeeService.java
        │   │   ├── OrderService.java
        │   │   ├── ReportService.java
        │   │   ├── SetmealService.java
        │   │   ├── ShoppingCartService.java
        │   │   ├── UserService.java
        │   │   └── WorkSpaceService.java
        │   ├── task/              # 定时任务
        │   │   └── OrderTask.java             # 订单定时任务
        │   ├── websocket/         # WebSocket
        │   │   └── WebSocketServer.java       # WebSocket 服务端
        │   └── LightApplication.java          # 启动类
        │
        └── resources/
            ├── mapper/              # MyBatis XML 映射文件
            │   ├── AddressBookMapper.xml
            │   ├── CategoryMapper.xml
            │   ├── DishFlavorMapper.xml
            │   ├── DishMapper.xml
            │   ├── EmployeeMapper.xml
            │   ├── OrderDetailMapper.xml
            │   ├── OrderMapper.xml
            │   ├── SetmealDishMapper.xml
            │   ├── SetmealMapper.xml
            │   ├── ShoppingCartMapper.xml
            │   └── UserMapper.xml
            ├── application.yml      # 主配置文件
            └── application-dev.yml  # 开发环境配置
            └── pom.xml
```

---

## 🏗️ 系统架构

### 整体架构图

```
┌─────────────────────────────────────────────────────────┐
│                      前端应用                             │
│         (管理后台 / 用户小程序 / H5)                        │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/HTTPS
┌────────────────────▼────────────────────────────────────┐
│                  Nginx (反向代理)                         │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│              Spring Boot 应用服务器                       │
├─────────────────────────────────────────────────────────┤
│  Controller 层 (REST API)                                │
│  ├─ admin/ 管理端接口                                     │
│  └─ user/  用户端接口                                     │
├─────────────────────────────────────────────────────────┤
│  Interceptor 层 (JWT 认证拦截)                            │
│  ├─ JwtTokenAdminInterceptor                           │
│  └─ JwtTokenUserInterceptor                            │
├─────────────────────────────────────────────────────────┤
│  Service 层 (业务逻辑)                                    │
│  ├─ 事务管理 @EnableTransactionManagement               │
│  └─ 缓存支持 @EnableCaching                             │
├─────────────────────────────────────────────────────────┤
│  Mapper 层 (数据访问)                                     │
│  └─ MyBatis XML 映射                                     │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
    ┌──────┐   ┌──────┐   ┌──────┐
    │ MySQL│   │Redis │   │ OSS  │
    └──────┘   └──────┘   └──────┘
```

### 核心技术流程

#### 1. JWT 认证流程
```
请求 → 拦截器 → 解析 Token → 验证有效性 → 提取用户 ID → 存入 ThreadLocal → 放行
                              ↓
                         验证失败 → 返回 401
```

#### 2. 订单处理流程
```
用户下单 → 生成订单 → 微信支付 → 支付回调 
                              ↓
                        商家接单 → 派送 → 完成
                              ↓
                        拒单/取消 → 退款
```

#### 3. AOP 自动填充
```
@AutoFill(OperationType.INSERT/UPDATE)
        ↓
AutoFillAspect 切面拦截
        ↓
反射设置公共字段 (createTime, updateTime, createId, updateId)
```

---

## 🚀 快速开始

### 环境准备

确保已安装以下软件：
- JDK 1.8+
- Maven 3.6+
- MySQL 5.7+
- Redis 5.0+

### 安装步骤

#### 1. 克隆项目
```bash
git clone <repository-url>
cd light-speed-express
```

#### 2. 配置数据库
创建数据库并导入 SQL 脚本：
```sql
CREATE DATABASE light_speed_express DEFAULT CHARACTER SET utf8mb4;
USE light_speed_express;
-- 导入提供的 SQL 脚本
```

#### 3. 配置文件修改
编辑 `light-server/src/main/resources/application-dev.yml`：

```yaml
light:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    host: localhost
    port: 3306
    database: light_speed_express
    username: root
    password: your_password
  
  redis:
    host: localhost
    port: 6379
    password: 
    database: 0
  
  alioss:
    endpoint: oss-cn-beijing.aliyuncs.com
    access-key-id: your_access_key_id
    access-key-secret: your_access_key_secret
    bucket-name: your_bucket_name
  
  wechat:
    appid: wx_appid
    secret: your_secret
    mch-id: merchant_id
    # ... 其他微信配置
```

#### 4. 编译打包
```bash
mvn clean package -DskipTests
```

#### 5. 启动项目
```bash
# 方式一：使用 Maven 启动
mvn spring-boot:run -pl light-server

# 方式二：运行 JAR 包
java -jar light-server/target/light-server-1.0-SNAPSHOT.jar
```

#### 6. 访问应用
- **服务端口**: http://localhost:8080
- **接口文档**: http://localhost:8080/doc.html
- **管理端 API**: http://localhost:8080/admin/**
- **用户端 API**: http://localhost:8080/user/**

---

## 📚 API 文档

### 接口文档访问
项目集成了 Knife4j 接口文档，启动后访问：
```
http://localhost:8080/doc.html
```

### 接口分组
- **管理端接口组**: `/admin/**`
  - 员工管理
  - 菜品管理
  - 套餐管理
  - 订单管理
  - 数据报表
  - 店铺管理

- **用户端接口组**: `/user/**`
  - 用户登录
  - 菜品浏览
  - 套餐浏览
  - 购物车
  - 订单提交
  - 地址簿

### 接口规范

#### 统一响应格式
所有接口返回统一的 JSON 格式：

**成功响应：**
```json
{
  "code": 1,
  "msg": null,
  "data": {
    // 业务数据
  }
}
```

**失败响应：**
```json
{
  "code": 0,
  "msg": "错误信息",
  "data": null
}
```

#### 分页查询格式
```json
{
  "code": 1,
  "msg": null,
  "data": {
    "total": 100,
    "records": [
      // 数据列表
    ]
  }
}
```

---

## 🔧 配置说明

### 核心配置项

#### application.yml
```yaml
server:
  port: 8080

spring:
  profiles:
    active: dev  # 环境配置

light:
  jwt:
    # 管理员 JWT 配置
    admin-secret-key: xgy
    admin-ttl: 7200000  # 2 小时
    admin-token-name: token
    
    # 用户 JWT 配置
    user-secret-key: user-xgy
    user-ttl: 7200000
    user-token-name: authentication
  
  alioss:  # 阿里云 OSS 配置
  wechat:  # 微信支付配置
  tencent: # 腾讯地图配置
  shop:    # 店铺配置
```

### 环境变量
敏感配置建议使用环境变量或配置中心：
```yaml
light:
  datasource:
    host: ${DB_HOST:localhost}
    password: ${DB_PASSWORD}
```

---

## 📊 数据库设计

### 核心数据表

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `employee` | 员工表 | id, username, name, password, status |
| `category` | 分类表 | id, name, type, sort, status |
| `dish` | 菜品表 | id, name, category_id, price, status |
| `dish_flavor` | 菜品口味表 | id, dish_id, name, value |
| `setmeal` | 套餐表 | id, name, category_id, price, status |
| `setmeal_dish` | 套餐菜品关系表 | id, setmeal_id, dish_id |
| `orders` | 订单表 | id, order_number, user_id, status, amount |
| `order_detail` | 订单明细表 | id, order_id, name, number, amount |
| `address_book` | 地址表 | id, user_id, consignee, phone, address |
| `shopping_cart` | 购物车表 | id, user_id, dish_id/setmeal_id, number |
| `user` | 用户表 | id, openid, name, phone |

---

## 🎯 核心功能详解

### 1. 员工管理
- **登录认证**: 用户名 + 密码，生成 JWT Token
- **员工 CRUD**: 新增、修改、查询、删除
- **账号管理**: 启用/禁用账号
- **分页查询**: 支持姓名、状态筛选

**接口示例：**
```
POST   /admin/employee/login      # 登录
POST   /admin/employee            # 新增员工
GET    /admin/employee/page       # 分页查询
PUT    /admin/employee            # 修改员工
POST   /admin/employee/status/{status}  # 启用/禁用
```

### 2. 菜品管理
- **分类管理**: 菜品分类的增删改查
- **菜品维护**: 菜品信息、价格、图片
- **口味配置**: 支持多种口味选项
- **状态控制**: 起售/停售

**接口示例：**
```
POST   /admin/dish                # 新增菜品
GET    /admin/dish/page           # 分页查询
PUT    /admin/dish                # 修改菜品
POST   /admin/dish/status/{status}  # 起售/停售
DELETE /admin/dish?id=xxx         # 删除菜品
```

### 3. 订单管理
- **订单提交**: 用户下单，生成订单
- **支付流程**: 微信支付预支付
- **订单状态机**: 待付款→待接单→已接单→派送中→已完成
- **订单操作**: 接单、拒单、取消、派送、完成

**订单状态流转：**
```
待付款 (1) → 待接单 (2) → 已接单 (3) → 派送中 (4) → 已完成 (5)
                ↓           ↓
             已取消 (6)   已拒单 (7)
```

### 4. 数据统计
- **营业额统计**: 按日期统计营业额
- **订单统计**: 订单数量、完成率
- **销量排行**: Top10 菜品销量
- **数据概览**: 核心经营数据展示

---

## 🔐 安全机制

### JWT 认证
系统采用双重 JWT 认证机制：

| 角色 | Token 名称 | 秘钥 | 过期时间 |
|------|-----------|------|---------|
| 管理员 | `token` | `admin-secret-key` | 2 小时 |
| 用户 | `authentication` | `user-secret-key` | 2 小时 |

**认证流程：**
1. 登录成功后生成 JWT Token
2. 前端在请求头携带 Token
3. 拦截器校验 Token 有效性
4. 解析出用户 ID 存入 ThreadLocal
5. 业务层通过 `BaseContext.getCurrentId()` 获取

### 拦截器配置
```java
// 管理端拦截
.addPathPatterns("/admin/**")
.excludePathPatterns("/admin/employee/login");  // 登录接口放行

// 用户端拦截
.addPathPatterns("/user/**")
.excludePathPatterns("/user/user/login");  // 登录接口放行
```

---

## ⚙️ 高级特性

### 1. AOP 自动填充
通过自定义注解 `@AutoFill` 和切面，自动填充公共字段：

**支持的字段：**
- `createTime` (INSERT)
- `updateTime` (INSERT/UPDATE)
- `createId` (INSERT)
- `updateId` (INSERT/UPDATE)

**使用示例：**
```java
@AutoFill(OperationType.INSERT)
public void save(DishDTO dishDTO) {
    // 自动填充 createTime, createId
}

@AutoFill(OperationType.UPDATE)
public void update(DishDTO dishDTO) {
    // 自动填充 updateTime, updateId
}
```

### 2. 全局异常处理
`GlobalExceptionHandler` 统一处理各类异常：

```java
@ExceptionHandler(Exception.class)
public Result<String> exceptionHandler(Exception ex) {
    if (ex instanceof BaseException) {
        return Result.error(ex.getMessage());
    }
    return Result.error("系统繁忙，请稍后再试");
}
```

### 3. 定时任务
订单定时任务 `OrderTask`：

```java
@Scheduled(cron = "0 * * * * ?")  // 每分钟执行
public void processTimeoutOrder() {
    // 处理超时未支付的订单（自动取消）
}

@Scheduled(cron = "0 0 1 * * ?")  // 每天凌晨 1 点
public void processDeliveryOrder() {
    // 处理已派送超时的订单（自动完成）
}
```

### 4. WebSocket 实时推送
用于催单提醒：

```java
@GetMapping("/reminder/{id}")
public Result<String> reminder(@PathVariable Long id) {
    // 通过 WebSocket 向商家端推送消息
    webSocketServer.sendToAllClient("订单" + id + "催单");
}
```

---

## 📝 开发指南

### 新增功能模块

#### 1. 创建 Entity
```java
@Data
@TableName("your_table")
public class YourEntity {
    private Long id;
    private String name;
    // ...
}
```

#### 2. 创建 Mapper接口
```java
@Mapper
public interface YourMapper {
    void insert(YourEntity entity);
    YourEntity getById(Long id);
    // ...
}
```

#### 3. 创建 Mapper XML
```xml
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" 
    "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.light.mapper.YourMapper">
    
    <insert id="insert" parameterType="com.light.entity.YourEntity">
        INSERT INTO your_table (name, ...) 
        VALUES (#{name}, ...)
    </insert>
    
</mapper>
```

#### 4. 创建 Service
```java
public interface YourService {
    void save(YourDTO dto);
    YourVO getById(Long id);
}

@Service
public class YourServiceImpl implements YourService {
    @Autowired
    private YourMapper yourMapper;
    
    @Override
    public void save(YourDTO dto) {
        YourEntity entity = new YourEntity();
        BeanUtils.copyProperties(dto, entity);
        yourMapper.insert(entity);
    }
}
```

#### 5. 创建 Controller
```java
@RestController
@RequestMapping("/admin/your")
@Api(tags = "你的接口")
public class YourController {
    
    @Autowired
    private YourService yourService;
    
    @PostMapping
    @ApiOperation("保存")
    public Result<String> save(@RequestBody YourDTO dto) {
        yourService.save(dto);
        return Result.success();
    }
}
```

---

## 🐛 常见问题

### 1. 启动报错
**问题**: `Cannot load driver class: com.mysql.cj.jdbc.Driver`  
**解决**: 检查 MySQL 依赖和版本号，确保驱动类正确

### 2. JWT 认证失败
**问题**: 请求返回 401  
**解决**: 
- 检查请求头是否包含正确的 Token
- 确认 Token 未过期
- 验证秘钥配置一致

### 3. 文件上传失败
**问题**: OSS 上传报错  
**解决**:
- 检查阿里云 AccessKey 配置
- 确认 Bucket 名称正确
- 验证网络连通性

### 4. 微信支付回调失败
**问题**: 收不到回调通知  
**解决**:
- 检查 `notify-url` 配置是否为外网可访问地址
- 验证证书配置是否正确
- 查看日志确认签名验证

---

## 📄 许可证

Apache License 2.0

---

## 👥 贡献指南

欢迎提交 Issue 和 Pull Request！

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

---

## 📞 联系方式

如有问题，请通过以下方式联系：
- Email: 3791158284@qq.com
- Issues: GitHub Issues

---

<div align="center">

**感谢使用光速外卖系统！** 🚀

如果这个项目对你有帮助，请给一个 ⭐️ Star 支持！

</div>