Doubleyin
63d0860553
All checks were successful
构建并部署 Spring Boot 应用 / build-and-deploy (push) Successful in 13m13s
256 lines
6.8 KiB
Markdown
256 lines
6.8 KiB
Markdown
# Light Delivery 后端项目
|
||
|
||
## 项目概述
|
||
|
||
Light Delivery 是一个为小程序配送服务设计的后端系统，提供了用户管理、订单管理、配送员管理、位置同步等核心功能。
|
||
|
||
## 技术栈
|
||
|
||
- Java 17
|
||
- Spring Boot 3.1.4
|
||
- Spring Data JPA
|
||
- Spring WebSocket
|
||
- MySQL
|
||
- 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. **本地开发环境** (`local`)
|
||
- 端口: 8443
|
||
- 数据库: 远程MySQL (与生产环境相同)
|
||
- SSL: 禁用
|
||
- 日志级别: DEBUG
|
||
|
||
2. **测试环境** (`test`)
|
||
- 端口: 8443
|
||
- 数据库: H2内存数据库
|
||
- SSL: 禁用
|
||
- 日志级别: DEBUG
|
||
|
||
3. **生产环境** (`prod`)
|
||
- 端口: 443
|
||
- 数据库: 远程MySQL
|
||
- SSL: 启用
|
||
- 日志级别: INFO
|
||
|
||
### 本地运行方式
|
||
|
||
#### 方式一：IDE直接运行（推荐用于开发调试）
|
||
|
||
1. 在IDE中打开[LightApplication.java](file:///E:/StudyProject/Light/src/main/java/com/light/delivery/LightApplication.java)
|
||
2. 添加运行参数: `-Dspring.profiles.active=local`
|
||
3. 直接运行main方法
|
||
|
||
#### 方式二：Maven命令运行
|
||
|
||
```bash
|
||
# 使用local配置文件运行
|
||
mvn spring-boot:run -Dspring-boot.run.profiles=local
|
||
|
||
# 或者使用test配置文件运行（使用内存数据库）
|
||
mvn spring-boot:run -Dspring-boot.run.profiles=test
|
||
```
|
||
|
||
#### 方式三：打包后运行
|
||
|
||
```bash
|
||
# 打包项目
|
||
mvn clean package -DskipTests
|
||
|
||
# 使用local配置运行
|
||
java -jar target/light-delivery-1.0.0.jar --spring.profiles.active=local
|
||
|
||
# 使用test配置运行
|
||
java -jar target/light-delivery-1.0.0.jar --spring.profiles.active=test
|
||
```
|
||
|
||
### 运行Docker容器
|
||
|
||
```bash
|
||
# 构建本地Docker镜像
|
||
build-local.bat
|
||
|
||
# 运行容器
|
||
docker run -d --name light-delivery -p 8443:8443 light-delivery-app
|
||
```
|
||
|
||
## 部署说明
|
||
|
||
### 服务打包
|
||
|
||
使用Maven将项目打包为可执行JAR文件：
|
||
|
||
```bash
|
||
# 清理并打包，跳过测试
|
||
mvn clean package -DskipTests
|
||
|
||
# 或者运行测试后打包
|
||
mvn clean package
|
||
```
|
||
|
||
打包后的文件位于: `target/light-delivery-1.0.0.jar`
|
||
|
||
### Docker镜像构建
|
||
|
||
项目支持多种Docker镜像构建方式：
|
||
|
||
#### 方式一：使用Jib插件（推荐）
|
||
|
||
```bash
|
||
# 构建Docker镜像到本地Docker守护进程
|
||
mvn compile jib:dockerBuild
|
||
|
||
# 构建Docker镜像到tar文件
|
||
mvn compile jib:buildTar
|
||
```
|
||
|
||
#### 方式二：使用Dockerfile
|
||
|
||
```bash
|
||
# 构建Docker镜像
|
||
docker build -t light-delivery-app .
|
||
```
|
||
|
||
### 云端部署
|
||
|
||
使用提供的部署脚本将应用部署到云服务器：
|
||
|
||
```bash
|
||
# Windows环境下运行
|
||
deploy.bat
|
||
```
|
||
|
||
脚本将执行以下操作：
|
||
1. 构建Docker镜像
|
||
2. 导出为tar文件
|
||
3. 通过SCP上传到云服务器
|
||
4. 在云服务器上加载镜像并运行容器
|
||
|
||
## 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. 位置历史记录功能已被移除，如有需要可使用第三方服务进行位置追踪 |