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