MoodPing FastAPI 백엔드 (DDD 아키텍처)

감정 기록 + AI 분석 웹앱 백엔드 (FastAPI / Python 3.14 호환)

기존 스파게티 구조의 백엔드를 **도메인 주도 설계(DDD)**와 레이어드 아키텍처를 적용하여 완전히 분리된 구조로 재구성한 독립 실행형 프로젝트입니다.

---

🚀 빠른 시작

0. 이상적인 프로젝트 폴더 구조

이 프로젝트를 다른 곳으로 이동하여 실행할 때, ModuleNotFoundError를 방지하기 위해 아래와 같은 폴더 배치를 권장합니다. (인프라 설정 파일들은 바깥에, 파이썬 코드는 moodping/ 안에 배치)

MoodPing_Project/
├── docker-compose.yml       # DB 컨테이너 설정
├── schema.sql               # DB 초기화 스크립트
├── requirements.txt         # 파이썬 패키지 의존성
├── .env.example             # 복사해서 .env 로 사용
└── moodping/                # 실제 파이썬 소스 코드 폴더
    ├── main.py
    ├── config/
    ├── static/
    └── ... (도메인 폴더들)

1. 환경변수 설정

cp .env.example .env
# .env 파일을 열어 API 키 입력 (카카오, OpenAI 등)

2. Docker로 MySQL 실행

docker compose up -d
# 3307 포트로 MySQL 서버 실행 및 schema.sql 자동 적용

3. Python 가상환경 & 의존성 설치

# 가상환경 생성 (파이썬 3.14 완벽 호환)
python -m venv venv

# Windows
venv\Scripts\activate

# Mac/Linux
source venv/bin/activate

# 의존성 설치 (버전 충돌을 막기 위해 항상 이 명령어를 사용하세요)
pip install -r requirements.txt

4. 서버 실행

**루트 폴더(MoodPing_Project/ 위치)**에서 다음 명령어를 실행합니다.

uvicorn moodping.main:app --reload --port 33333

• 웹앱 접속: http://localhost:33333
• API 문서: http://localhost:33333/docs

---

🤖 LLM 전환 방법

.env 파일의 LLM_PROVIDER 값만 변경하면 여러 AI 모델을 자유롭게 스위칭할 수 있습니다. (비즈니스 서비스 코드 수정 불필요)

LLM_PROVIDER=openai   # GPT-4.1-mini (기본값)
LLM_PROVIDER=gemini   # Gemini 2.5 Flash
LLM_PROVIDER=claude   # Claude Haiku 4.5

---

🏛️ 패키지 구조 (도메인 주도 설계)

각 비즈니스 기능별로 폴더(도메인)를 분리하고, 내부를 단방향 계층형(Controller -> Service -> Repository)으로 엄격하게 관리합니다.

moodping/
├── main.py              # 앱 진입점 (FastAPI)
├── config/              # 공통 환경 및 DB 설정
├── static/              # 프론트엔드 정적 파일
├── llm/                 # 통합 LLM 클라이언트 모듈 (Factory 패턴)
│
├── account/             # 도메인: 사용자 계정
├── authentication/      # 도메인: JWT 세션
├── kakao_authentication/# 도메인: 카카오 로그인 플로우
├── mood_record/         # 도메인: 감정 기록
├── mood_analysis/       # 도메인: LLM 감정 분석
├── weekly_report/       # 도메인: 주간 리포트
└── event_log/           # 도메인: 퍼널/리텐션 분석 로그

[도메인 내부 기본 구조]
└── {도메인명}/
    ├── controller/       # FastAPI 라우터 및 요청 DTO
    ├── service/          # 비즈니스 로직 (인터페이스 & 싱글톤 구현체)
    ├── repository/       # DB 및 외부 API 연동
    └── domain/entity/    # SQLAlchemy 모델 (Factory Method 'create' 패턴 사용)

---

🔌 주요 API 엔드포인트

메서드	URL	담당 도메인	설명
GET	/auth/kakao	kakao_authentication	카카오 OAuth 리다이렉트
GET	/auth/callback	kakao_authentication	카카오 로그인 + Account 생성 + JWT 발급
GET	/auth/me	authentication	현재 로그인 사용자 정보 (Bearer 토큰 필요)
POST	/mood-records	mood_record	감정 기록 저장 + 즉시 LLM 분석 실행
GET	/api/reports/weekly/latest	weekly_report	주간 리포트 조회/생성 (Bearer 토큰 필요)
POST	/api/events	event_log	프론트엔드 퍼널 이벤트 로그 저장
GET	/api/debug/metrics	event_log	퍼널 이탈률 + 7일 리텐션 지표 (디버그)
POST	/users/link-data	account	비로그인(anon_id) 데이터를 로그인(user_id)으로 승계
GET	/docs	main.py	Swagger UI 자동 생성