140 lines
4.9 KiB
Markdown
140 lines
4.9 KiB
Markdown
# EV 충전 플랫폼 — FastAPI 백엔드
|
|
|
|
CPO 없는 전기차 충전 플랫폼 백엔드 서버.
|
|
Steve OCPP 서버와 연동하여 충전 세션 관리, 결제 처리, 정산을 수행.
|
|
|
|
## 아키텍처
|
|
|
|
```
|
|
사용자 (QR 스캔)
|
|
│
|
|
▼
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
│ Nginx :443 │────▶│ FastAPI :8000│────▶│ PostgreSQL │
|
|
│ (리버스프록시)│ │ (REST API) │ │ (세션/정산) │
|
|
└──────┬───────┘ └──────┬───────┘ └──────────────┘
|
|
│ │
|
|
│ ▼
|
|
│ ┌──────────────┐
|
|
│ │ 토스페이먼츠 │
|
|
│ │ (결제 PG) │
|
|
│ └──────────────┘
|
|
▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ Steve :8180 │◀───▶│ 충전기 │
|
|
│ (OCPP 서버) │ WS │ (OCPP 1.6J) │
|
|
└──────────────┘ └──────────────┘
|
|
```
|
|
|
|
## 충전 흐름
|
|
|
|
```
|
|
① QR 스캔 → POST /api/v1/sessions (세션 생성)
|
|
② 결제 → POST /api/v1/payments/prepare (orderId 발급)
|
|
→ 토스 결제 UI 호출
|
|
→ POST /api/v1/payments/confirm (결제 승인)
|
|
③ 충전 → POST /api/v1/sessions/{uid}/start (RemoteStart)
|
|
→ OCPP MeterValues 수신 중...
|
|
④ 종료 → POST /api/v1/sessions/{uid}/stop (RemoteStop)
|
|
→ 자동 정산
|
|
```
|
|
|
|
## 빠른 시작
|
|
|
|
### 1. 환경 설정
|
|
|
|
```bash
|
|
cd ev-charging-backend
|
|
cp .env.example .env
|
|
# .env 파일 편집 — DB, Steve, 토스 키 설정
|
|
```
|
|
|
|
### 2. Docker Compose 실행
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
### 3. API 확인
|
|
|
|
```bash
|
|
# 헬스체크
|
|
curl http://localhost:8000/health
|
|
|
|
# Swagger UI
|
|
open http://localhost:8000/docs
|
|
```
|
|
|
|
### 4. 테스트 흐름 실행
|
|
|
|
```bash
|
|
pip install httpx
|
|
python test_flow.py
|
|
```
|
|
|
|
## API 엔드포인트
|
|
|
|
| 경로 | 메서드 | 설명 |
|
|
|------|--------|------|
|
|
| `/api/v1/chargers/` | GET/POST | 충전기 목록/등록 |
|
|
| `/api/v1/sessions/` | POST | 세션 생성 (QR 스캔) |
|
|
| `/api/v1/sessions/{uid}` | GET | 세션 상태 조회 |
|
|
| `/api/v1/sessions/{uid}/start` | POST | 충전 시작 |
|
|
| `/api/v1/sessions/{uid}/stop` | POST | 충전 종료 |
|
|
| `/api/v1/sessions/{uid}/billing` | GET | 정산 내역 |
|
|
| `/api/v1/payments/prepare` | POST | 결제 준비 |
|
|
| `/api/v1/payments/confirm` | POST | 결제 승인 |
|
|
| `/api/v1/ocpp/status` | POST | 충전기 상태 콜백 |
|
|
| `/api/v1/ocpp/start-transaction` | POST | 충전 시작 콜백 |
|
|
| `/api/v1/ocpp/stop-transaction` | POST | 충전 종료 콜백 |
|
|
| `/api/v1/ocpp/meter-values` | POST | MeterValues 콜백 |
|
|
| `/api/v1/dashboard/summary` | GET | 대시보드 요약 |
|
|
| `/api/v1/qr/{chargeBoxId}` | GET | QR 코드 이미지 |
|
|
|
|
## Nginx 설정
|
|
|
|
기존 Steve Nginx 설정에 `nginx_fastapi.conf` 내용을 추가하면
|
|
같은 도메인(`s1.byunc.com`)에서 `/api/` → FastAPI, `/steve/` → Steve로 분기.
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
ev-charging-backend/
|
|
├── docker-compose.yml
|
|
├── Dockerfile
|
|
├── requirements.txt
|
|
├── .env.example
|
|
├── nginx_fastapi.conf ← Nginx 추가 설정
|
|
├── test_flow.py ← 전체 흐름 테스트
|
|
├── alembic.ini
|
|
└── app/
|
|
├── main.py ← FastAPI 앱 진입점
|
|
├── config.py ← 환경변수 설정
|
|
├── database.py ← DB 연결
|
|
├── models/
|
|
│ └── __init__.py ← SQLAlchemy 모델
|
|
├── schemas/
|
|
│ └── __init__.py ← Pydantic 스키마
|
|
├── routers/
|
|
│ ├── chargers.py ← 충전기 관리
|
|
│ ├── sessions.py ← 충전 세션 (핵심)
|
|
│ ├── payments.py ← 토스 결제
|
|
│ ├── ocpp_callbacks.py← OCPP 이벤트 수신
|
|
│ ├── dashboard.py ← 대시보드
|
|
│ └── qr.py ← QR 코드 생성
|
|
└── services/
|
|
├── steve_client.py ← Steve REST API 클라이언트
|
|
├── billing.py ← 요금 정산 로직
|
|
├── payment.py ← 토스페이먼츠 연동
|
|
└── scheduler.py ← 백그라운드 태스크
|
|
```
|
|
|
|
## 다음 단계
|
|
|
|
- [ ] Alembic 마이그레이션 초기화 (`alembic init alembic`)
|
|
- [ ] 토스페이먼츠 테스트 키 발급 및 연동
|
|
- [ ] 모바일 웹 결제 프론트 (QR → 결제 → 충전 상태)
|
|
- [ ] Steve API 인증 설정 확인
|
|
- [ ] Grafana 연동 (PostgreSQL 데이터소스)
|
|
- [ ] 프로덕션 배포 (SSL, 보안 헤더)
|