Loop Backend

Loop 해커톤용 FastAPI 백엔드입니다. 학생/교수 매칭 시나리오를 기준으로 회원가입, 프로필 탐색, 좋아요, 파일 업로드(S3), PDF 요약(OpenAI) API를 제공합니다.

1. 프로젝트 개요

• 역할 기반 사용자: STUDENT, PROFESSOR
• 핵심 도메인: User, StudentProfile, ProfessorProfile, Like
• 파일 처리: S3 Presigned URL 기반 직접 업로드
• AI 기능: PDF 텍스트 추출 후 논문 요약/연구 분야 추출

2. 기술 스택

• Python 3.11+
• FastAPI, Uvicorn
• SQLAlchemy 2.x, Alembic
• PostgreSQL
• boto3 (AWS S3)
• pypdf
• OpenAI Python SDK (Responses API)

3. 폴더 구조

back/
├─ app/
│  ├─ api/                # 라우터 계층
│  │  ├─ auth.py          # 회원가입
│  │  ├─ user.py          # 사용자 활성화 상태 변경
│  │  ├─ profiles.py      # 프로필 탐색/이미지 저장/조회
│  │  ├─ likes.py         # 좋아요 토글/좋아요 카드 조회
│  │  ├─ files.py         # presign(pdf/image), pdf 요약
│  │  └─ health.py        # 헬스체크
│  ├─ core/               # 설정 및 도메인 서비스
│  ├─ db/                 # SQLAlchemy 엔진/세션
│  ├─ models/             # DB 모델
│  ├─ schemas/            # 요청/응답 스키마
│  └─ services/           # S3/PDF/OpenAI 서비스
├─ alembic/               # 마이그레이션
├─ docs/                  # API 세부 문서
├─ requirements.txt
└─ .env.example

4. 로컬 실행

4.1 의존성 설치

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

4.2 환경변수 준비

copy .env.example .env

4.3 PostgreSQL 준비

• .env의 DATABASE_URL에 맞는 DB 생성
• 기본값: postgresql+psycopg2://postgres:postgres@localhost:5432/loop_db

4.4 마이그레이션

alembic upgrade head

4.5 서버 실행

uvicorn app.main:app --reload

• Swagger: http://127.0.0.1:8000/docs
• Health: GET /health

5. 환경변수

APP_NAME="Loop Hackathon API"
APP_ENV="local"
DEBUG=true
DATABASE_URL="postgresql+psycopg2://postgres:postgres@localhost:5432/loop_db"

AWS_ACCESS_KEY_ID=""
AWS_SECRET_ACCESS_KEY=""
AWS_REGION="ap-northeast-2"
AWS_S3_BUCKET=""
AWS_S3_PDF_PREFIX="loop/papers"
AWS_S3_IMAGE_PREFIX="loop/images"
AWS_PRESIGNED_URL_EXPIRES=300

OPENAI_API_KEY=""
OPENAI_MODEL="gpt-4.1-mini"

6. API 요약

6.1 인증/유저

• POST /api/auth/signup
  • 학생/교수 회원가입 + 역할별 프로필 생성
• PATCH /api/users/{user_id}/active
  • 사용자 활성화 상태 변경

6.2 프로필

• GET /profiles/discover
  • 현재 사용자 역할 기준 반대 역할 프로필 카드 목록 조회
• POST /profiles/image
  • 프로필 이미지 S3 Key 저장
• GET /profiles/image
  • 프로필 이미지 Presigned Download URL 조회

6.3 좋아요

• POST /likes/toggle
  • 좋아요 저장/취소 토글
• GET /likes/cards
  • 내가 좋아요한 카드 목록 조회

6.4 파일/PDF

• POST /files/presign/pdf
  • PDF 업로드용 Presigned URL 발급
• POST /files/presign/image
  • 이미지 업로드용 Presigned URL 발급
• POST /files/summarize-pdf
  • S3 PDF 텍스트 추출 + AI 요약 + 연구 분야 추출

7. 주요 비즈니스 규칙

• 자기 자신에게 좋아요 불가
• 프로필 탐색은 요청 role과 실제 user role이 일치해야 함
• PDF presign은 .pdf + application/pdf만 허용
• 이미지 presign은 .jpg/.jpeg/.png/.webp, MIME 타입 제한
• 교수 회원가입 시 s3_key와 summary가 함께 오면 ai_status=COMPLETED, 아니면 PENDING

8. 데이터 모델 개요

• users
  • 공통 사용자 정보(이메일, 성별, 역할, 활성화 여부)
• student_profiles
  • 학생 카드 정보(학년, 기술스택, 관심분야, 소개 등)
• professor_profiles
  • 교수 카드 정보(학력, 경력, 희망 인재상, 논문 요약 정보 등)
• likes
  • 사용자 간 좋아요 관계

9. 처리 흐름

9.1 PDF 요약 플로우

1. POST /files/presign/pdf
2. 클라이언트가 S3에 직접 PUT
3. POST /files/summarize-pdf with s3_key
4. 요약 결과 수신

9.2 프로필 이미지 플로우

1. POST /files/presign/image
2. 클라이언트가 S3에 직접 PUT
3. POST /profiles/image로 profile_image_s3_key 저장
4. 필요 시 GET /profiles/image로 조회

10. 참고 문서

docs/ 폴더에 기능별 상세 문서가 있습니다.

• pdf-upload-presign-api.md
• pdf-summarize-api.md
• profile-list-api.md
• profile-image-presign-api.md
• profile-image-save-api.md
• profile-image-get-api.md
• like-save-api.md
• liked-cards-api.md

11. 현재 상태와 확장 포인트

• 현재 API는 인증 토큰 없이 일부 엔드포인트에서 user_id를 직접 받는 구조입니다.
• 운영 전환 시 JWT 인증, 권한 검증, rate limit, 에러 표준화, 관측성(로그/메트릭) 보강을 권장합니다.