Feat/api ai recommend pass

[zzuhannn]

📌 작업 개요

CatBoost 기반 AI 추천 시스템 구현 및 FastAPI-Spring Boot 통합 아키텍처 구축. 9개 설문 항목을 기반으로 사용자 맞춤형 운동 패키지를 추천하는 하이브리드 추천 시스템을 개발하고, Docker 컨테이너 기반 자동 배포 파이프라인을 구성했습니다.

📝 작업 내용

AI 추천 시스템 (FastAPI)

• CatBoost ML 모델을 활용한 협업 필터링 기반 추천 엔진 구현
• 규칙 기반 필터링(목적, 강도, 환경 등) 추가로 하이브리드 추천 시스템 구축
• 9개 설문 항목 지원 (목적, 시간, 강도, 이동시간, 환경, 종목, 회복도, 예산, 회피요소)
• FastAPI 서버 구현 및 Pydantic 스키마 정의
• 학습 데이터 생성 및 모델 학습 파이프라인 구축

Spring Boot 통합

• AI 추천 프록시 컨트롤러 구현 (POST /api/ai/recommendations)
• FastAPI와 통신하는 서비스 레이어 구현 (RestTemplate 사용)
• 9개 설문 필드를 지원하는 DTO 생성 (AISurveyRequest, AIRecommendationRes)
• SecurityConfig에 AI 추천 엔드포인트 인증 제외 설정 추가
• application.properties에 FastAPI URL 환경변수 설정

배포 인프라

• FastAPI용 Dockerfile 작성 (Python 3.9 기반)
• .dockerignore 생성 (venv, 캐시 파일 제외)
• GitHub Actions CI/CD 파이프라인 수정
  • Spring Boot + FastAPI 병렬 빌드 job 구성
  • Docker Hub에 두 이미지 자동 푸시
  • EC2에 두 컨테이너 자동 배포 (8080, 8000 포트)
• requirements.txt 생성 (FastAPI, CatBoost, Pandas 등)

문서화

• AI 추천 시스템 README 작성 (한국어)
• 시스템 아키텍처 다이어그램 추가
• API 사용법 및 통합 가이드 작성
• 트러블슈팅 가이드 추가

📎 참고 사항

아키텍처 결정

• FastAPI를 별도 서비스로 분리한 이유: ML 모델 실행 환경과 Spring Boot 비즈니스 로직을 분리하여 독립적인 스케일링 가능
• 프록시 패턴 채택: 프론트엔드는 Spring Boot만 호출하여 일관된 인증/인가 처리 가능
• Docker 컨테이너 분리: Spring Boot(8080)와 FastAPI(8000)를 별도 컨테이너로 실행하여 장애 격리 및 독립 배포 가능

알려진 이슈

• predicted_score 동일 문제: 현재 학습 데이터가 부족하여 모든 패키지에 유사한 점수 부여. 실제 사용자 데이터가 쌓이면 재학습 필요
• 학습되지 않은 특성: budgetRange, preferredTime, travelTime은 아직 학습 데이터에 포함되지 않아 ML 예측에 미사용. 추후 데이터 수집 후 재학습 예정

배포 전 체크리스트

• GitHub Secrets에 DOCKERHUB_USERNAME, DOCKERHUB_TOKEN 등록 확인
• EC2 보안그룹에 8000 포트 인바운드 규칙 추가
• Spring Boot의 application.properties에 DB 정보가 환경변수로 관리되는지 확인

로컬 테스트 방법

# 1. Spring Boot 실행
./gradlew bootRun

# 2. FastAPI 실행 (별도 터미널)
cd ai_recommendation
source venv/bin/activate
uvicorn api.server:app --reload

# 3. API 테스트
curl -X POST http://localhost:8080/api/ai/recommendations \
  -H "Content-Type: application/json" \
  -d '{"purpose":"다이어트","preferred_time":"저녁(18시~23시)",...}'
🖼️ 사진
시스템 아키텍처
프론트엔드 (React)
    ↓
Spring Boot (8080 포트) - 인증/인가, 비즈니스 로직
    ↓ (프록시)
FastAPI (8000 포트) - ML 추천 엔진
    ↓
MySQL RDS - 패키지 데이터
추천 알고리즘 흐름
사용자 설문 → Spring Boot → FastAPI → 패키지 메타데이터 조회
→ CatBoost 점수 산출 → 규칙 필터링 → Top 10 반환