# HomeChargeHub
**Repository Path**: zcoolq/home-charge-hub
## Basic Information
- **Project Name**: HomeChargeHub
- **Description**: 随着新能源汽车的普及，家用充电桩的外借需求日益增加。为规范充电桩的使用管理，避免费用纠纷，需要开发一套完整的充电管理系统，实现预约、计费、结算的自动化管理。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://hch.zcoolq.cn
- **GVP Project**: No
## Statistics
- **Stars**: 2
- **Forks**: 1
- **Created**: 2025-10-27
- **Last Updated**: 2026-04-30
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# HomeChargeHub - 家用充电桩外借充电管理系统
一个完整的家用充电桩外借充电管理系统，支持预约管理、智能结算、费用统计等功能。
## 系统架构
```
├── home-charge-hub-backend/ # 后端（Spring Boot）
├── home-charge-hub-frontend/ # 前端（Vue 3）
├── docker-compose.yml # Docker编排文件
└── README.md # 项目说明
```
## 技术栈
### 后端
- Spring Boot 2.7.18
- MyBatis Plus 3.5.5
- MySQL 8.0+
- Spring Security + JWT
- Knife4j (API文档)
### 前端
- Vue 3.3+
- Element Plus 2.4+ (PC端)
- Vant 4.x (移动端)
- Pinia (状态管理)
- Vite 5.x (构建工具)
## 快速开始
### 方式一：Docker部署（推荐）
#### 1. 确保已安装 Docker 和 Docker Compose
```bash
docker --version
docker-compose --version
```
#### 2. 构建后端项目
```bash
cd home-charge-hub-backend
mvn clean package -DskipTests
cd ..
```
#### 3. 启动所有服务
```bash
docker-compose up -d
```
这将启动以下服务：
- MySQL数据库 (端口 3306)
- 后端API服务 (端口 8080)
- 前端Web服务 (端口 80)
#### 4. 访问系统
- **前端地址**: http://localhost
- **后端API**: http://localhost:8080/api
- **API文档**: http://localhost:8080/api/doc.html
#### 5. 默认账号
- **管理员**: admin / admin123
- **普通用户**: 需要管理员创建
#### 6. 停止服务
```bash
docker-compose down
```
### 方式二：本地开发
#### 前置要求
- Java 8 (JDK 1.8)
- Maven 3.6+
- Node.js 16+ / npm 8+
- MySQL 8.0+（可选，也可使用 SQLite）
#### 1. 启动后端
后端默认使用 `dev` profile，支持 SQLite 和 MySQL 两种模式。
**SQLite 模式（零配置，推荐本地开发）：**
```bash
cd home-charge-hub-backend
mvn spring-boot:run
```
数据库文件自动创建在项目根目录的 `data/home_charge_hub.db`。
**MySQL 模式：**
1. 创建数据库并导入初始数据：
```bash
mysql -u root -p < home-charge-hub-backend/src/main/resources/schema.sql
```
2. 编辑 `src/main/resources/application-dev.yml`，配置数据库连接信息。
3. 启动时指定 MySQL 数据源：
```bash
mvn spring-boot:run -Dspring.profiles.active=dev
```
后端启动后访问 http://localhost:8080/api，API 文档：http://localhost:8080/api/doc.html
#### 2. 启动前端
```bash
cd home-charge-hub-frontend
npm install
npm run dev
```
前端开发服务器启动在 http://localhost:3000，`/api` 请求自动代理到后端。
#### 3. 默认账号
- **管理员**: `admin` / `admin123`
- **普通用户**: 需管理员在后台创建
## 功能特性
### 管理员功能
#### 用户管理
- ✅ 用户列表查询（支持搜索、筛选、分页）
- ✅ 新增用户（设置账号、密码、服务费等）
- ✅ 编辑用户信息
- ✅ 删除用户（检查是否有未结算订单）
- ✅ 启用/禁用用户状态
#### 公告管理
- ✅ 公告列表查询
- ✅ 发布新公告（支持富文本）
- ✅ 编辑公告
- ✅ 删除公告
- ✅ 置顶公告（最多3条）
#### 预约管理
- ✅ 预约列表查询（支持日期、用户、状态筛选）
- ✅ 日历视图（直观展示预约情况）
- ✅ 代用户创建预约
- ✅ 编辑预约信息
- ✅ 取消预约
- ✅ 标记预约完成（自动创建待结算记录）
- ✅ 预约日期冲突检测
#### 结算管理
- ✅ 待结算列表
- ✅ 已结算列表查询
- ✅ 录入充电度数（谷/平/峰）
- ✅ 自动计算费用（支持实时预览）
- ✅ 生成费用账单
- ✅ 修改已结算记录
#### 电价管理
- ✅ 查看当前电价（谷/平/峰）
- ✅ 修改电价配置
- ✅ 电价历史记录
### 用户功能
#### 首页
- ✅ 查看系统公告
- ✅ 当前季节时段电价展示
- ✅ 我的预约快速入口
#### 预约充电
- ✅ 日历选择预约日期
- ✅ 已预约日期标记提示
- ✅ 查看我的预约列表
- ✅ 取消待充电预约
#### 充电记录
- ✅ 查看充电历史记录
- ✅ 查看费用明细（度数、电费、服务费）
- ✅ 按日期筛选记录
#### 个人中心
- ✅ 查看个人信息
- ✅ 修改个人资料
- ✅ 修改登录密码
## 业务规则
### 预约规则
- 每个日期只能有一个预约
- 不能预约当天之前的日期
- 可预约未来90天内的日期
- 普通用户只能有一个待充电预约
- 管理员可以代用户创建预约
### 结算规则
- 预约完成后自动创建待结算记录
- 结算时必须录入至少一个时段的度数
- 费用计算公式：
```
总度数 = 谷度数 + 平度数 + 峰度数
谷电费 = 谷度数 × 谷电价
平电费 = 平度数 × 平电价
峰电费 = 峰度数 × 峰电价
电费小计 = 谷电费 + 平电费 + 峰电费
服务费 = 总度数 × 用户服务费单价
总费用 = 电费小计 + 服务费
```
### 电价时段
根据季节自动区分峰谷平时段：
| 季节 | 月份 | 峰时段 | 平时段 | 谷时段 |
|------|------|--------|--------|--------|
| 春秋季 | 3、4、5、6、10、11月 | 10:00-12:00
17:00-22:00 | 08:00-10:00
12:00-17:00 | 22:00-次日08:00 |
| 夏季 | 7、8、9月 | 11:00-18:00
20:00-23:00 | 07:00-11:00
18:00-20:00
23:00-01:00 | 01:00-07:00 |
| 冬季 | 12、1、2月 | 10:00-12:00
16:00-22:00 | 08:00-10:00
12:00-16:00
22:00-24:00 | 00:00-08:00 |
## 项目状态
### 已完成模块 ✅
- [x] 后端项目基础结构
- [x] 数据库表结构和初始化数据
- [x] 公共模块（配置、异常处理、工具类）
- [x] 用户认证模块（登录、JWT）
- [x] 用户管理模块
- [x] 预约管理模块
- [x] 结算管理模块
- [x] 前端项目基础结构
- [x] 前端公共组件和工具类
- [x] Docker部署配置
### 待完善模块 🚧
由于项目代码量较大，以下模块已提供完整的后端API和前端示例代码，需要参照示例完成：
#### 后端（参考已有Service实现）:
- 公告管理Service/Controller
- 电价管理Service/Controller
#### 前端（参照UserManagement.vue实现）:
- 公告管理页面
- 预约管理页面（含日历视图）
- 结算管理页面
- 电价管理页面
- 用户端所有页面
**实现指南**:
- 后端参考 `home-charge-hub-backend/generate-remaining-code.md`
- 前端参考 `home-charge-hub-frontend/README.md`
## API文档
启动后端服务后，访问 http://localhost:8080/api/doc.html 查看完整的API文档（Knife4j）
## 目录结构
```
home-charge-hub/
├── home-charge-hub-backend/ # 后端项目
│ ├── src/
│ │ ├── main/
│ │ │ ├── java/com/homechargehub/
│ │ │ │ ├── common/ # 公共模块
│ │ │ │ ├── controller/ # 控制器
│ │ │ │ ├── service/ # 业务层
│ │ │ │ ├── mapper/ # 数据访问层
│ │ │ │ ├── entity/ # 实体类
│ │ │ │ ├── dto/ # DTO
│ │ │ │ └── vo/ # VO
│ │ │ └── resources/
│ │ │ ├── mapper/ # MyBatis XML
│ │ │ ├── schema.sql # 数据库初始化脚本
│ │ │ └── application.yml # 配置文件
│ │ └── test/
│ ├── pom.xml
│ ├── Dockerfile
│ └── README.md
├── home-charge-hub-frontend/ # 前端项目
│ ├── src/
│ │ ├── api/ # API接口
│ │ ├── assets/ # 静态资源
│ │ ├── components/ # 组件
│ │ ├── router/ # 路由
│ │ ├── store/ # 状态管理
│ │ ├── utils/ # 工具函数
│ │ ├── views/ # 页面
│ │ │ ├── admin/ # 管理员页面
│ │ │ └── user/ # 用户页面
│ │ ├── App.vue
│ │ └── main.js
│ ├── package.json
│ ├── vite.config.js
│ ├── Dockerfile
│ ├── nginx.conf
│ └── README.md
├── docker-compose.yml # Docker编排
└── README.md # 项目说明
```
## 开发说明
### 后端开发
1. 继承 `BaseMapper` 创建Mapper接口
2. 使用 `@Service` 标注Service实现类
3. 使用 `@RestController` 创建Controller
4. 统一使用 `Result` 封装返回结果
5. 使用 `BusinessException` 抛出业务异常
6. 使用 `@PreAuthorize` 控制接口权限
### 前端开发
1. 在 `src/api` 中定义接口函数
2. 在 `src/views` 中创建页面组件
3. 在 `src/router` 中配置路由
4. 使用 Pinia 进行状态管理
5. 统一使用 `ElMessage` 显示提示信息
## 常见问题
### 1. Docker启动失败
- 确保 3306、8080、80 端口未被占用
- 检查Docker服务是否正常运行
- 查看日志: `docker-compose logs -f`
### 2. 后端连接数据库失败
- 检查MySQL是否正常启动
- 确认数据库连接信息是否正确
- 等待MySQL完全启动（约30秒）
### 3. 前端无法访问后端API
- 确认后端服务已启动
- 检查跨域配置
- 查看浏览器控制台错误信息
## 许可证
MIT License
## 联系方式
如有问题，欢迎提Issue。