237 lines
4.9 KiB
Markdown
237 lines
4.9 KiB
Markdown
# Helios EVCS - EV Charging Station Management System
|
||
|
||
*这是一个毕业设计项目，旨在提供一个完整的电动汽车充电站管理系统（EV Charging Station Management System）。*
|
||
|
||
## 📋 项目概述
|
||
|
||
Helios EVCS 是一个全栈解决方案，用于管理和监控电动汽车充电基础设施。项目包含后端 CSMS（充电管理系统）和前端 Web 应用。
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
helios-evcs/
|
||
├── apps/ # 应用程序包
|
||
│ ├── csms/ # 后端 CSMS 平台服务（Hono + Node.js）
|
||
│ └── web/ # 前端云平台应用（Next.js 15 + React 19）[submodule]
|
||
├── hardware/ # 硬件和固件工程
|
||
│ ├── firmware/ # 充电桩固件
|
||
│ └── pcb-kicad/ # PCB 设计文件（KiCAD）
|
||
├── package.json
|
||
├── pnpm-workspace.yaml
|
||
├── pnpm-lock.yaml
|
||
└── .gitmodules
|
||
```
|
||
|
||
## 📦 工作区包
|
||
|
||
### `apps/csms` - 充电管理系统后端
|
||
- **技术栈**：Node.js + Hono + TypeScript
|
||
- **端口**：3001（默认）
|
||
- **职责**：
|
||
- OCPP 协议实现
|
||
- 充电设备管理
|
||
- 用户认证与授权
|
||
- 实时数据处理
|
||
- RESTful API 接口
|
||
|
||
### `apps/web` - 前端管理界面（子模块）
|
||
- **技术栈**：Next.js 15 + React 19 + Tailwind CSS
|
||
- **端口**：3000（默认）
|
||
- **源仓库**：https://github.com/HoshinoSuzumi/helios
|
||
- **职责**：
|
||
- 充电站管理界面
|
||
- 实时监控面板
|
||
- 数据可视化
|
||
- 用户管理
|
||
|
||
### `hardware/` - 硬件和固件工程
|
||
- **firmware/** - 充电桩微控制器固件代码
|
||
- 设备驱动实现
|
||
- 通信协议栈
|
||
- 实时控制逻辑
|
||
|
||
- **pcb-kicad/** - PCB 电路板设计
|
||
- KiCAD 工程文件
|
||
- 电路原理图
|
||
- PCB 布局设计
|
||
- BOM 物料清单
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
- Node.js >= 18
|
||
- pnpm >= 10.18.2
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
# 安装根工作区和所有子包的依赖
|
||
pnpm install
|
||
```
|
||
|
||
### 开发
|
||
|
||
```bash
|
||
# 启动所有开发服务器（CSMS + Web）
|
||
pnpm dev
|
||
|
||
# 仅启动后端
|
||
pnpm dev:csms
|
||
|
||
# 仅启动前端
|
||
pnpm dev:web
|
||
```
|
||
|
||
访问：
|
||
- 前端应用：http://localhost:3000
|
||
- 后端 API：http://localhost:3001
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
# 构建所有包
|
||
pnpm build
|
||
|
||
# 仅构建后端
|
||
pnpm build:csms
|
||
|
||
# 仅构建前端
|
||
pnpm build:web
|
||
```
|
||
|
||
### 生产启动
|
||
|
||
```bash
|
||
# 启动后端
|
||
pnpm start:csms
|
||
|
||
# 启动前端
|
||
pnpm start:web
|
||
```
|
||
|
||
## 📝 Scripts 说明
|
||
|
||
| 命令 | 描述 |
|
||
|------|------|
|
||
| `pnpm dev` | 启动所有服务的开发模式 |
|
||
| `pnpm dev:csms` | 启动后端开发服务器 |
|
||
| `pnpm dev:web` | 启动前端开发服务器 |
|
||
| `pnpm build` | 构建所有包 |
|
||
| `pnpm build:csms` | 构建后端 |
|
||
| `pnpm build:web` | 构建前端 |
|
||
| `pnpm start:csms` | 生产环境启动后端 |
|
||
| `pnpm start:web` | 生产环境启动前端 |
|
||
|
||
## 🔧 工作区管理
|
||
|
||
### 使用 pnpm filter 运行特定包命令
|
||
|
||
```bash
|
||
# 在指定包中运行命令
|
||
pnpm --filter csms <command>
|
||
pnpm --filter helios-web <command>
|
||
|
||
# 示例：在 csms 中运行测试
|
||
pnpm --filter csms run test
|
||
```
|
||
|
||
### 安装包到特定工作区
|
||
|
||
```bash
|
||
# 在根安装（所有包共用）
|
||
pnpm add <package>
|
||
|
||
# 在特定包中安装
|
||
pnpm --filter csms add <package>
|
||
pnpm --filter helios-web add <package>
|
||
```
|
||
|
||
## 📁 Git 子模块管理
|
||
|
||
`apps/web` 作为 Git 子模块管理：
|
||
|
||
```bash
|
||
# 初始化并更新子模块
|
||
git submodule update --init --recursive
|
||
|
||
# 更新子模块到最新版本
|
||
git submodule update --remote
|
||
|
||
# 克隆包含子模块的仓库
|
||
git clone --recurse-submodules <repo-url>
|
||
```
|
||
|
||
在子模块内修改后的工作流：
|
||
```bash
|
||
# 在 apps/web 目录内提交更改
|
||
cd apps/web
|
||
git add .
|
||
git commit -m "feat: xxx"
|
||
git push
|
||
|
||
# 返回主仓库，更新子模块引用
|
||
cd ..
|
||
git add apps/web
|
||
git commit -m "chore: update helios submodule"
|
||
git push
|
||
```
|
||
|
||
## 📚 技术文档
|
||
|
||
### 后端开发
|
||
- 详见 `apps/csms/README.md`
|
||
- Hono 框架文档：https://hono.dev
|
||
- OCPP 协议规范：https://www.openchargealliance.org
|
||
|
||
### 前端开发
|
||
- 详见 `apps/web/README.md`
|
||
- Next.js 文档：https://nextjs.org/docs
|
||
- Tailwind CSS：https://tailwindcss.com
|
||
|
||
## 🛠️ 环境配置
|
||
|
||
### 环境变量
|
||
|
||
创建 `.env.local` 文件（根据需要在各包目录下）：
|
||
|
||
**后端 (`apps/csms/.env.local`)：**
|
||
```env
|
||
NODE_ENV=development
|
||
PORT=3001
|
||
# 其他配置项...
|
||
```
|
||
|
||
**前端 (`apps/web/.env.local`)：**
|
||
```env
|
||
NEXT_PUBLIC_API_URL=http://localhost:3001
|
||
# 其他配置项...
|
||
```
|
||
|
||
## 🔒 代码质量
|
||
|
||
### ESLint 配置
|
||
- 使用 Next.js 的 ESLint 规则
|
||
- 开发时自动检查（可选）
|
||
|
||
### TypeScript
|
||
- 严格模式启用
|
||
- 所有包使用统一的 TypeScript 版本
|
||
|
||
## 📦 发布/部署
|
||
|
||
### 构建产物
|
||
```bash
|
||
# 构建后的文件位置
|
||
apps/csms/dist/ # 后端构建输出
|
||
apps/web/.next/ # 前端构建输出
|
||
```
|
||
|
||
## 👤 作者
|
||
|
||
- **Timothy Yin** - master@uniiem.com
|
||
|
||
## 🔗 相关资源
|
||
|
||
- 前端仓库：https://github.com/HoshinoSuzumi/helios
|
||
- OCPP 标准：https://www.openchargealliance.org
|