refactor(#14): FastAPI backend 라우터, 서비스, DB 모듈 분리

[AI-WonYJ]

🍀 이슈 번호

• closed: refactor: FastAPI backend 라우터, 서비스, DB 모듈 분리 #14

---

📝 변경 사항

• DB connection pool 관리 로직을 database.py로 분리
• 현재 상태 및 통계 조회 로직을 services/stats_service.py로 분리
• 추론 성공·실패 결과 저장 및 통계 갱신 로직을 services/stats_service.py로 분리
• 이미지 디코딩, YOLO 추론, 추론 시간 측정 로직을 services/inference_service.py로 분리
• 프론트엔드용 API를 routers/public.py로 분리
  • GET /api/v2/count/current
  • GET /api/v2/stats/today
  • GET /api/v2/stats/weekly
• ESP32-CAM 관련 API를 routers/device.py로 분리
  • POST /api/v2/device/upload
  • GET /api/v2/device/command
  • POST /api/v2/test/trigger
• main.py를 FastAPI 앱 초기화, middleware 설정, 정적 파일 제공, 라우터 등록 중심으로 정리
• 기존 API 경로와 응답 구조 유지

🎯 목적

기존 backend의 FastAPI 앱 설정, DB 접근, YOLO 추론, 통계 처리, API 라우팅 로직이 main.py에 집중되어 있어 기능별 책임 구분이 어려웠습니다.

향후 public API와 device API를 독립적으로 관리하고 배포 환경별 설정을 분리할 수 있도록 backend 구조를 라우터, 서비스, DB 모듈 단위로 정리했습니다.

이번 변경은 기능 추가가 아닌 구조 리팩토링이며, 기존 프론트엔드와 ESP32-CAM이 사용하는 API 경로와 응답 형식은 변경하지 않았습니다.

📂 적용 범위

• backend/main.py
• backend/database.py
• backend/routers/__init__.py
• backend/routers/public.py
• backend/routers/device.py
• backend/services/__init__.py
• backend/services/inference_service.py
• backend/services/stats_service.py

---

🖥️ 주요 코드 설명

FastAPI 라우터 등록

app.include_router(public_router)
app.include_router(device_router)

main.py에서는 각 API를 직접 정의하지 않고 기능별 라우터를 등록하도록 변경했습니다.

Public API 분리

router = APIRouter(prefix="/api/v2", tags=["public"])

프론트엔드가 사용하는 현재 인원 및 통계 API를 routers/public.py에서 관리합니다.

Device API 분리

router = APIRouter(prefix="/api/v2", tags=["device"])

ESP32-CAM의 명령 조회와 이미지 업로드 API를 routers/device.py에서 관리합니다.

서비스 계층 분리

frame = decode_image(content)
people_count, inference_time_ms = run_inference(frame)

라우터에서는 요청과 응답 처리를 담당하고, 이미지 디코딩과 YOLO 추론은 inference_service.py에 위임합니다.

DB 조회와 추론 결과 저장 및 통계 갱신은 stats_service.py에서 담당합니다.

---

📋 체크리스트

• Merge 대상 브랜치가 올바른가?
• 정상적으로 빌드되는가?
• 코드가 에러 없이 잘 동작하는가?
• 전체 변경사항이 500줄을 넘지 않는가?
• 관련 테스트 코드를 작성했는가?
• 기존 테스트가 모두 통과하는가?
• 코드 스타일(Ruff)을 준수하는가?

📌 참고 사항

• 기존 API의 경로와 응답 형식을 유지한 상태에서 모듈 구조만 변경했습니다.