ev-charging-backend/README.md

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. 환경 설정

cd ev-charging-backend
cp .env.example .env
# .env 파일 편집 — DB, Steve, 토스 키 설정

2. Docker Compose 실행

docker compose up -d

3. API 확인

# 헬스체크
curl http://localhost:8000/health

# Swagger UI
open http://localhost:8000/docs

4. 테스트 흐름 실행

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, 보안 헤더)