# SnapBox智能租物柜-后端

**Repository Path**: rainfoxbysnow/snapbox-a

## Basic Information

- **Project Name**: SnapBox智能租物柜-后端
- **Description**: SnapBox智能租物柜移动端平台后端
- **Primary Language**: Java
- **License**: CC-BY-SA-4.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2025-10-28
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# snapbox 智能相机租赁柜后端项目

# 一、项目概述

snapbox 智能相机租赁柜后端项目，是支撑智能相机租赁柜全流程业务运转的核心服务集群。项目基于微服务架构设计，实现了用户认证授权、相机设备管理、租赁订单处理、充值支付、设备远程控制等核心功能，为前端应用、租赁柜硬件设备提供稳定、高效的接口服务，最终实现相机租赁业务的自动化、智能化管理。

核心业务场景包括：用户注册登录、相机查询与预约、租赁柜设备状态监控、订单生成与支付、相机取还操作记录、费用自动结算、充值与余额管理等。

# 二、技术栈选型

项目采用主流微服务技术体系，兼顾稳定性、可扩展性与开发效率，具体技术栈如下：

## 2.1 核心框架与中间件

- **微服务基础**：Spring Cloud + Spring Boot，实现微服务的快速开发与集成

- **服务注册与配置中心**：Nacos，提供服务注册发现、配置动态管理能力

- **服务通信**：OpenFeign，基于HTTP的声明式服务调用，简化服务间交互

- **API网关**：Spring Cloud Gateway，实现请求路由、负载均衡、权限校验、限流熔断等功能

- **消息队列**：RabbitMQ（MQTT协议），用于设备消息通信（如租赁柜状态上报、控制指令下发）、异步业务处理（如订单状态通知、日志异步写入）

- **持久层框架**：SSM（Spring + Spring MVC + MyBatis），经典Java EE持久层解决方案，稳定高效

- **数据库**：MySQL，存储核心业务数据（用户信息、订单数据、设备信息等）

- **缓存中间件**：Redis，用于热点数据缓存（如用户会话、设备状态）、分布式锁实现

- **定时任务**：XXL-Job，实现分布式定时任务（如订单超时自动取消、费用周期性结算）

## 2.2 工具类库

- **Hutool**：Java工具类库，简化日期处理、加密解密、IO操作等通用功能开发

- **Gson**：Google的JSON解析库，用于JSON数据的序列化与反序列化

# 三、项目模块结构

项目采用模块化设计，各模块职责单一、边界清晰，通过服务调用协同完成业务流程，具体模块如下：

## 3.1 核心业务模块

|模块名称|核心职责|关键功能|
|---|---|---|
|auth 模块|用户认证与授权|用户注册、登录、权限校验、Token生成与解析、角色管理|
|user 模块|用户信息管理|用户基本信息维护、收货地址管理、用户积分与等级管理|
|camera 模块|相机资源管理|相机信息维护（型号、参数、状态）、相机库存管理、相机故障上报与维修记录|
|device 模块|租赁柜设备管理|租赁柜信息维护（位置、编号、状态）、设备状态监控、设备控制指令下发（如开箱、关箱）、设备故障诊断|
|order 模块|租赁订单管理|订单生成、订单状态流转（待支付、已支付、租赁中、已完成、已取消）、订单查询、订单明细统计|
|recharge 模块|用户充值管理|充值方案配置、充值订单生成、充值记录查询、余额变动日志、充值优惠活动管理|
|payment 模块|支付流程处理（拓展模块）|集成第三方支付（微信、支付宝）、支付回调处理、支付状态查询、退款处理|
## 3.2 公共与支撑模块

|模块名称|核心职责|关键功能|
|---|---|---|
|common 模块|公共工具与基础配置|全局异常处理、通用返回结果封装、常量定义、工具类封装、数据库基础配置|
|api 模块|服务API接口定义|各模块对外暴露的API接口声明、数据传输对象（DTO）定义、接口文档聚合|
|gateway 模块|API网关服务|请求路由转发、统一权限拦截、接口限流、日志记录、跨域配置|
# 四、环境搭建与部署

## 4.1 本地开发环境要求

- JDK 1.8+：项目基于Java 8开发，需确保环境变量配置正确

- Maven 3.6+：用于项目依赖管理与构建

- MySQL 8.0+：建议使用8.0及以上版本，需提前创建项目数据库（默认库名：snapbox_db）

- Redis 6.0+：用于缓存服务，默认端口6379，需确保服务正常启动

- RabbitMQ 3.9+：启用MQTT插件（rabbitmq-plugins enable rabbitmq_mqtt），默认端口1883

- Nacos 2.0+：服务注册与配置中心，默认端口8848，启动后需在控制台创建命名空间（默认：snapbox-namespace）

- XXL-Job 2.3+：定时任务调度中心，需部署调度器服务，并配置执行器信息

## 4.2 项目启动步骤

1. **环境准备**：启动MySQL、Redis、RabbitMQ、Nacos、XXL-Job调度器服务，确保各中间件正常运行

2. **配置调整**：修改各模块配置文件（nacos配置中心或本地application.yml），适配本地中间件地址、端口、账号密码等信息

3. **数据库初始化**：执行项目sql目录下的初始化脚本（snapbox_init.sql），创建数据表与基础数据

4. **服务启动顺序**：
        1. Nacos服务（必须先启动，确保其他服务可注册）

5. 2. common模块（若为独立部署，否则无需单独启动）

6. 3. gateway模块（网关服务，承接前端请求）

7. 4. 核心业务模块（auth、user、camera、device、order、recharge等，启动顺序无强制依赖）

8. **接口测试**：通过Postman或Swagger访问网关地址（默认：http://localhost:8080），调用接口进行测试

## 4.3 生产环境部署

生产环境建议采用Docker容器化部署，配合Docker Compose或Kubernetes实现服务编排与运维管理，核心部署流程如下：

1. 通过Maven构建各模块Jar包（mvn clean package -DskipTests）

2. 编写各服务Dockerfile，定义容器化配置

3. 使用Docker Compose或K8s配置文件，编排Nacos、MySQL、Redis等中间件与业务服务

4. 部署至生产服务器，通过日志监控服务运行状态（推荐使用ELK日志收集系统）

# 五、核心业务流程

## 5.1 相机租赁流程

1. 用户通过前端登录（auth模块校验身份，生成Token）

2. 前端通过gateway调用camera模块接口，查询附近可用相机与租赁柜信息

3. 用户选择相机并提交租赁请求，order模块生成待支付订单

4. 用户发起支付，payment模块集成第三方支付完成支付流程

5. 支付成功后，order模块更新订单状态为“已支付”，并通过RabbitMQ发送开箱指令至device模块

6. device模块接收指令，控制租赁柜开箱，同时将设备状态同步至Redis

7. 用户取走相机后，设备状态更新为“租赁中”，order模块启动计时（通过XXL-Job实现费用实时计算）

8. 用户归还相机时，租赁柜检测到设备并上报device模块，device模块发送状态变更通知至order模块

9. order模块结算租赁费用，更新订单状态为“已完成”，并同步至user模块扣除相应余额

## 5.2 用户充值流程

1. 用户在前端发起充值请求，选择充值金额与支付方式

2. recharge模块生成充值订单，同步至payment模块

3. 用户完成支付后，payment模块接收支付回调，通知recharge模块更新充值订单状态

4. recharge模块调用user模块接口，更新用户余额，并记录充值日志

5. 充值完成后，通过RabbitMQ发送消息至前端，提示用户充值成功

# 六、接口文档

项目集成Swagger/OpenAPI实现接口文档自动化生成，启动服务后可通过以下地址访问：

网关聚合接口文档：http://localhost:8080/swagger-ui.html

单个模块接口文档（以auth模块为例）：http://localhost:8081/swagger-ui.html

接口文档包含接口地址、请求参数、返回结果、错误码等详细信息，支持在线调试。

# 七、常见问题与排查

- **服务注册失败**：检查Nacos服务是否正常启动，服务配置文件中Nacos地址、命名空间是否正确，确保服务端口未被占用

- **设备指令下发失败**：检查RabbitMQ服务状态与MQTT插件是否启用，device模块与RabbitMQ连接配置是否正确，设备网络是否正常

- **订单支付回调异常**：检查payment模块第三方支付配置（APPID、密钥等）是否正确，确保回调接口可被外部访问，日志中查看回调参数是否完整

- **缓存数据不一致**：检查Redis服务状态，确认核心业务流程中Redis数据更新逻辑是否完整，必要时通过分布式锁避免并发问题

# 八、拓展说明

- **payment模块拓展**：当前支持基础支付流程，可拓展接入银联、Apple Pay等更多支付方式，同时增加支付密码、指纹支付等安全验证机制

- **recharge模块拓展**：可增加充值套餐折扣、积分兑换余额、充值后抽奖等营销功能，提升用户粘性

- **监控体系拓展**：建议集成Prometheus + Grafana实现服务性能监控，集成Sentinel实现流量控制与服务熔断，提升系统稳定性

- **国际化拓展**：若需支持多语言，可在common模块中集成i18n国际化配置，实现接口返回信息多语言适配


# 十、联系方式

项目维护人：Sn0w

联系邮箱：2257557033@qq.com


# 十一、许可证

cc-by-sa 您使用本源码默认您遵守开源协议
请尊重成果,感谢您的支持