加群联系作者vx：xiaoda0423
仓库地址：webvueblog.github.io/JavaPlusDoc…
webvueblog.github.io/JavaPlusDoc…
点击勘误issues，哪吒感谢大家的阅读
# 充电宝租借归还功能设计文档
## 1. 功能概述
本文档详细描述充电宝租借和归还功能的完整实现方案，包括数据库设计、业务流程、API接口和技术实现。
### 1.1 主要功能
- 用户扫码借出充电宝
- 用户扫码归还充电宝
- 费用计算和支付
- 押金管理
- 超时处理
- 设备状态管理
- 用户信用管理
## 2. 数据库设计
### 2.1 用户表 (tb_user)
```sql
CREATE TABLE tb_user (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
user_id VARCHAR(32) UNIQUE NOT NULL COMMENT '用户ID',
username VARCHAR(50) COMMENT '用户名',
phone VARCHAR(20) UNIQUE COMMENT '手机号',
email VARCHAR(100) UNIQUE COMMENT '邮箱',
avatar_url VARCHAR(500) COMMENT '头像URL',
status ENUM('ACTIVE', 'SUSPENDED', 'BLOCKED') DEFAULT 'ACTIVE' COMMENT '用户状态',
credit_score INT DEFAULT 100 COMMENT '信用分数',
balance DECIMAL(10,2) DEFAULT 0.00 COMMENT '账户余额',
deposit DECIMAL(10,2) DEFAULT 0.00 COMMENT '押金',
is_real_name_verified BOOLEAN DEFAULT FALSE COMMENT '是否实名认证',
real_name VARCHAR(50) COMMENT '真实姓名',
id_card VARCHAR(20) COMMENT '身份证号',
registration_time DATETIME COMMENT '注册时间',
last_login_time DATETIME COMMENT '最后登录时间',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
INDEX idx_phone (phone),
INDEX idx_email (email),
INDEX idx_status (status)
) COMMENT='用户表';
```
### 2.2 租借记录表 (tb_rental_record)
```sql
CREATE TABLE tb_rental_record (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
rental_id VARCHAR(32) UNIQUE NOT NULL COMMENT '租借ID',
user_id VARCHAR(32) NOT NULL COMMENT '用户ID',
device_id VARCHAR(32) NOT NULL COMMENT '设备ID',
power_bank_id BIGINT NOT NULL COMMENT '充电宝ID',
rental_status ENUM('RENTING', 'RETURNED', 'LOST', 'DAMAGED', 'CANCELLED') NOT NULL COMMENT '租借状态',
rental_time DATETIME NOT NULL COMMENT '租借时间',
return_time DATETIME COMMENT '归还时间',
rental_duration BIGINT COMMENT '租借时长(分钟)',
rental_longitude DECIMAL(10,7) COMMENT '租借位置经度',
rental_latitude DECIMAL(10,7) COMMENT '租借位置纬度',
return_longitude DECIMAL(10,7) COMMENT '归还位置经度',
return_latitude DECIMAL(10,7) COMMENT '归还位置纬度',
rental_battery_level INT COMMENT '租借时电量',
return_battery_level INT COMMENT '归还时电量',
fee_amount DECIMAL(10,2) DEFAULT 0.00 COMMENT '费用金额',
deposit_amount DECIMAL(10,2) DEFAULT 0.00 COMMENT '押金金额',
payment_status ENUM('UNPAID', 'PAID', 'REFUNDED', 'FAILED') DEFAULT 'UNPAID' COMMENT '支付状态',
payment_method VARCHAR(20) COMMENT '支付方式',
payment_time DATETIME COMMENT '支付时间',
is_overtime BOOLEAN DEFAULT FALSE COMMENT '是否超时',
overtime_fee DECIMAL(10,2) DEFAULT 0.00 COMMENT '超时费用',
remark TEXT COMMENT '备注',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
INDEX idx_user_id (user_id),
INDEX idx_device_id (device_id),
INDEX idx_rental_status (rental_status),
INDEX idx_rental_time (rental_time),
INDEX idx_return_time (return_time)
) COMMENT='租借记录表';
```
### 2.3 二维码表 (tb_qr_code)
```sql
CREATE TABLE tb_qr_code (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
device_id VARCHAR(32) NOT NULL COMMENT '设备ID',
qr_code VARCHAR(500) UNIQUE NOT NULL COMMENT '二维码内容',
qr_type ENUM('RENTAL', 'RETURN', 'MAINTENANCE') NOT NULL COMMENT '二维码类型',
qr_status ENUM('ACTIVE', 'INACTIVE', 'EXPIRED', 'USED') DEFAULT 'ACTIVE' COMMENT '二维码状态',
image_url VARCHAR(500) COMMENT '二维码图片URL',
generation_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '生成时间',
expiration_time DATETIME COMMENT '过期时间',
last_scan_time DATETIME COMMENT '最后扫描时间',
scan_count INT DEFAULT 0 COMMENT '扫描次数',
version INT DEFAULT 1 COMMENT '版本号',
enabled BOOLEAN DEFAULT TRUE COMMENT '是否启用',
remark TEXT COMMENT '备注',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
UNIQUE KEY uk_device_qr (device_id, qr_code),
INDEX idx_qr_status (qr_status),
INDEX idx_qr_type (qr_type),
INDEX idx_expiration_time (expiration_time)
) COMMENT='二维码表';
```
## 3. 业务流程设计
### 3.1 充电宝借出流程
```mermaid
sequenceDiagram
participant User as 用户
participant App as 移动应用
participant API as 后端API
participant DB as 数据库
participant Device as 设备
User->>App: 扫描设备二维码
App->>API: 发送扫码借出请求
API->>DB: 验证二维码有效性
API->>DB: 检查用户状态和余额
API->>DB: 检查设备和充电宝状态
API->>DB: 冻结押金
API->>DB: 创建租借记录
API->>Device: 发送开锁指令
Device-->>API: 返回开锁结果
API->>DB: 更新设备和充电宝状态
API-->>App: 返回借出成功
App-->>User: 显示借出成功信息
```
#### 3.1.1 详细步骤
1. **扫码验证**
- 用户扫描设备上的二维码
- 系统验证二维码的有效性（未过期、状态正常）
- 解析二维码获取设备信息
2. **用户验证**
- 检查用户状态（是否被封禁、暂停）
- 验证用户是否已实名认证
- 检查用户信用分数是否满足要求
- 验证用户账户余额是否充足
3. **设备检查**
- 检查设备是否在线
- 验证设备状态是否正常
- 检查是否有可用的充电宝
- 获取充电宝电量信息
4. **押金处理**
- 根据用户信用分数计算押金金额
- 冻结用户账户中的押金
- 记录押金冻结信息
5. **创建租借记录**
- 生成唯一的租借ID
- 记录租借时间、位置、电量等信息
- 设置租借状态为"RENTING"
6. **设备控制**
- 向设备发送开锁指令
- 等待设备响应
- 更新充电宝状态为"RENTED"
### 3.2 充电宝归还流程
```mermaid
sequenceDiagram
participant User as 用户
participant App as 移动应用
participant API as 后端API
participant DB as 数据库
participant Device as 设备
User->>App: 扫描归还设备二维码
App->>API: 发送扫码归还请求
API->>DB: 验证二维码和租借记录
API->>DB: 检查设备状态
API->>Device: 检查充电宝插入状态
Device-->>API: 返回插入确认
API->>DB: 计算租借费用
API->>DB: 处理费用扣除
API->>DB: 解冻押金
API->>DB: 更新租借记录
API->>DB: 更新设备和充电宝状态
API-->>App: 返回归还成功
App-->>User: 显示费用明细
```
#### 3.2.1 详细步骤
1. **扫码验证**
- 用户扫描归还设备的二维码
- 验证二维码有效性
- 检查设备是否支持归还
2. **租借记录验证**
- 根据用户ID查找正在进行的租借记录
- 验证租借状态
- 检查是否超时
3. **设备检查**
- 验证归还设备状态
- 检查设备是否有空余插槽
- 确认充电宝已正确插入
4. **费用计算**
- 计算租借时长
- 根据计费规则计算基础费用
- 计算超时费用（如有）
- 应用优惠券或折扣（如有）
5. **费用处理**
- 从用户账户扣除费用
- 解冻押金
- 记录支付信息
6. **更新记录**
- 更新租借记录状态为"RETURNED"
- 记录归还时间、位置、电量
- 更新充电宝状态为"AVAILABLE"
## 4. API接口设计
### 4.1 租借相关接口
#### 4.1.1 扫码借出
```http
POST /api/rentals/scan-rent
Content-Type: application/json
{
"qrCode": "设备二维码内容",
"userId": "用户ID",
"longitude": 116.397128,
"latitude": 39.916527
}
```
**响应示例：**
```json
{
"code": 200,
"message": "借出成功",
"data": {
"rentalId": "R202312010001",
"deviceId": "DEV001",
"powerBankId": 1001,
"batteryLevel": 85,
"depositAmount": 99.00,
"rentalTime": "2023-12-01T10:30:00"
}
}
```
#### 4.1.2 扫码归还
```http
POST /api/rentals/scan-return
Content-Type: application/json
{
"qrCode": "设备二维码内容",
"userId": "用户ID",
"longitude": 116.397128,
"latitude": 39.916527
}
```
**响应示例：**
```json
{
"code": 200,
"message": "归还成功",
"data": {
"rentalId": "R202312010001",
"duration": 120,
"feeAmount": 6.00,
"depositRefund": 99.00,
"returnTime": "2023-12-01T12:30:00",
"batteryLevel": 45
}
}
```
### 4.2 费用计算接口
#### 4.2.1 计算租借费用
```http
POST /api/rentals/{rentalId}/calculate-fee
```
**响应示例：**
```json
{
"code": 200,
"message": "计算成功",
"data": {
"baseFee": 5.00,
"overtimeFee": 1.00,
"totalFee": 6.00,
"duration": 120,
"isOvertime": true
}
}
```
## 5. 计费规则
### 5.1 基础计费
- 前30分钟免费
- 30分钟后每30分钟收费2元
- 不足30分钟按30分钟计算
### 5.2 押金规则
- 信用分数≥90分：免押金
- 信用分数70-89分：押金50元
- 信用分数<70分：押金99元
### 5.3 超时处理
- 租借超过24小时视为超时
- 超时费用：每小时10元
- 超时超过72小时视为丢失，扣除押金
## 6. 异常处理
### 6.1 常见异常情况
1. **设备离线**
- 提示用户设备暂时不可用
- 引导用户寻找附近其他设备
2. **充电宝已借完**
- 提示设备无可用充电宝
- 推荐附近有库存的设备
3. **用户余额不足**
- 提示用户充值
- 提供充值入口
4. **用户信用分数过低**
- 提示用户信用分数不足
- 说明提升信用分数的方法
5. **归还设备故障**
- 记录异常情况
- 人工客服介入处理
### 6.2 数据一致性保证
1. **事务处理**
- 使用数据库事务确保操作原子性
- 关键操作使用分布式锁
2. **状态同步**
- 定期同步设备状态
- 异常情况下的状态修复机制
3. **补偿机制**
- 支付失败的重试机制
- 押金异常的人工处理流程
## 7. 监控和运维
### 7.1 关键指标监控
- 设备在线率
- 充电宝利用率
- 用户借还成功率
- 平均租借时长
- 收入统计
### 7.2 告警机制
- 设备离线告警
- 充电宝电量低告警
- 异常交易告警
- 系统性能告警
## 8. 安全考虑
### 8.1 数据安全
- 用户敏感信息加密存储
- API接口鉴权
- 数据传输加密
### 8.2 业务安全
- 防刷机制
- 异常行为检测
- 风控规则引擎
## 9. 扩展功能
### 9.1 会员体系
- VIP用户优惠
- 积分兑换
- 等级特权
### 9.2 营销功能
- 优惠券系统
- 推荐奖励
- 活动促销
### 9.3 数据分析
- 用户行为分析
- 设备使用分析
- 收入分析报表
## 10. 部署和配置
### 10.1 环境要求
- Java 8+
- MySQL 8.0+
- Redis 6.0+
- Maven 3.6+
