EV 충전 플랫폼 초기 백업

2026-04-18 05:59:31 +09:00
commit 4558ac10c0
40 changed files with 6246 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,139 @@
+# 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, 보안 헤더)