# Helios EVCS

_这是一个毕业设计项目，旨在尝试实现一个完整的电动汽车充电站管理系统（EV CSMS）和配套的演示用充电桩终端。_

## 📋 项目概述

Helios EVCS 是一个全栈解决方案，用于管理和监控电动汽车充电基础设施。项目包含后端 CSMS（充电管理系统）和前端 Web 云平台应用。并设计了一个基于 ESP32，演示用的充电桩终端固件和 PCB 设计。

## 🏗️ 项目结构

```
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

## 👤 作者

- **Timothy Yin** - master@uniiem.com

## 🔗 相关资源

- 前端仓库：https://github.com/HoshinoSuzumi/helios
- OCPP 标准：https://www.openchargealliance.org