Light Delivery 后端项目

项目概述

Light Delivery 是一个为小程序配送服务设计的后端系统，提供了用户管理、订单管理、配送员管理、位置同步等核心功能。

技术栈

• Java 17
• Spring Boot 3.1.4
• Spring Data JPA
• Spring WebSocket
• MySQL
• Redis
• Maven

主要功能模块

1. 用户管理

• 微信小程序登录
• 用户角色管理（管理员、配送员、游客）
• 用户签到功能

2. 订单管理

• 订单创建与查询
• 订单状态跟踪
• 订单指派给配送员

3. 配送员管理

• 配送员注册
• 配送员位置实时同步
• 配送员状态管理

4. 位置同步

• 基于WebSocket的实时位置同步
• REST API位置查询接口
• 位置过期处理机制

项目结构

src
├── main
│   ├── java
│   │   └── com
│   │       └── light
│   │           └── delivery
│   │               ├── config          # 配置类
│   │               ├── controller      # 控制器层
│   │               ├── dto             # 数据传输对象
│   │               ├── exception       # 异常处理
│   │               ├── model           # 实体模型
│   │               ├── repository      # 数据访问层
│   │               ├── service         # 业务逻辑层
│   │               │   └── impl        # 业务逻辑实现
│   │               └── util            # 工具类
│   └── resources
│       ├── application.properties      # 配置文件
│       └── db                         # 数据库脚本
└── test                               # 测试代码

核心设计

认证授权机制

系统采用基于JWT的无状态认证机制：

1. 用户通过微信登录获取code
2. 后端通过code换取用户openid
3. 根据openid查找或创建用户
4. 生成JWT Token返回给前端
5. 前端在后续请求中通过Authorization头携带Token
6. 后端通过拦截器验证Token有效性

实时位置同步

位置同步采用双通道设计：

1. WebSocket实时推送：建立长连接，服务器主动推送位置更新
2. REST API查询：提供HTTP接口查询当前位置信息

位置信息现在存储在服务器内存缓存中，而不是持久化到数据库，以提高访问速度和减少数据库负载。

数据模型

主要实体包括：

• User：用户基础信息实体（所有用户通用）
• Employee：员工信息实体（后台配置数据，用于验证用户身份）
• DeliveryPerson：配送员扩展信息实体
• Order：订单实体

用户系统架构说明：

• 所有用户首先以游客身份静默登录，创建User记录
• 用户签到或注册时，系统根据手机号在Employee表中查找匹配记录
• 如果匹配成功，将用户的openid写入Employee表，表示该员工已成为系统用户
• 根据Employee中的角色信息更新User的角色
• 对于配送员，还会创建或更新DeliveryPerson记录

部署说明

1. 确保安装了Java 17和Maven
2. 配置MySQL数据库
3. 修改application.properties中的数据库连接信息
4. 运行mvn spring-boot:run启动项目

API接口

主要API接口包括：

用户相关

• POST /user/wxlogin - 微信登录
• GET /user/info - 获取用户信息
• POST /user/logout - 用户登出
• POST /user/signin - 用户签到
• POST /user/register - 注册为配送员

订单相关

• GET /orders - 获取订单列表
• GET /orders/{id} - 获取订单详情
• POST /orders/{id}/assign - 指派订单

配送员相关

• GET /delivery-persons - 获取配送员列表
• GET /delivery-persons/{id} - 获取配送员详情
• PUT /delivery-persons/{id}/location - 更新配送员位置

位置同步相关

• GET /location-sync/delivery-persons/locations - 获取所有配送员位置

最近更新

位置历史记录功能移除

为了简化系统架构并提高性能，我们移除了位置历史记录功能。具体变更包括：

• 删除了LocationHistory实体类
• 删除了LocationHistoryRepository数据访问接口
• 删除了LocationService服务接口及其实现类LocationServiceImpl
• 删除了LocationController控制器及相关API端点

位置信息现在完全基于实时同步机制，存储在服务器内存中，不再持久化到数据库。

注意事项

1. 系统仅支持微信登录，不再支持用户名密码登录
2. 所有敏感接口都需要通过JWT Token认证
3. 配送员位置信息具有时效性，默认5分钟内有效
4. 位置历史记录功能已被移除，如有需要可使用第三方服务进行位置追踪