[Feat] 페이지 스냅샷 추가

[minsoo0506]

요약

링크 검사 결과에서 사용자가 최종 URL의 페이지 화면을 확인할 수 있도록 페이지 스냅샷 생성 기능을 추가했습니다. 스냅샷 이미지를 API 응답에 직접 포함하지 않고, 서버 로컬 저장소에 PNG로 저장한 뒤 응답에는 스냅샷 상태와 storage_key를 내려주는 방식입니다. (임시)

주요 변경 사항:

• PageSnapshotResult, PageSnapshotStatus 스키마 추가
• PipelineSuccess.snapshot 응답 필드 추가
• Playwright 기반 페이지 스냅샷 생성 서비스 추가
• 정상 검사 경로에서 콘텐츠 분석과 스냅샷 생성을 병렬 실행
• threat DB 매치 등으로 위험 판정이 이미 확정된 경우 스냅샷 생성 스킵
• 스냅샷 실패/타임아웃이 verdict, score, summary에 영향을 주지 않도록 분리
• 기본 스냅샷 대기 시간을 1초로 제한해 파이프라인 응답 지연을 방지
• 스냅샷 상태를 available, skipped, timeout, failed로 구분

응답 :

{
  "status": "success",
  "verdict": "safe",
  "score": 0,
  "summary": "현재 분석 기준에서 뚜렷한 위험 신호가 확인되지 않았습니다.",
  "snapshot": {
    "status": "available",
    "final_url": "https://example.com/",
    "storage_key": "aid-snapshot.png",
    "elapsed_seconds": 0.83,
    "error": null
  }
}

이미지 전달 방식 검토

1. S3/R2/GCS 등 객체 스토리지 사용

흐름:

1. FastAPI가 최종 URL 페이지 스냅샷을 PNG로 생성
2. PNG를 S3 같은 객체 스토리지에 업로드
3. 응답에는 snapshot_url 또는 storage_key 반환
4. 프론트엔드는 해당 URL로 이미지를 표시
5. 일정 시간이 지나면 lifecycle rule 또는 백엔드 cleanup job으로 삭제

예시 응답:

{
  "snapshot": {
    "status": "available",
    "final_url": "https://example.com/",
    "storage_key": "snapshots/analysis-id.png",
    "snapshot_url": "https://cdn.example.com/snapshots/analysis-id.png",
    "elapsed_seconds": 0.83
  }
}

장점:

• API 응답 크기가 작음
• 프론트에서 일반 이미지처럼 로드 가능
• CDN 캐싱 가능
• 만료/삭제 정책 적용 쉬움
• 다중 서버 환경에서도 안정적
• 이미지 재조회가 쉬움

삭제 방식 예시:

• S3 lifecycle rule로 snapshots/ prefix 파일을 1일 후 자동 삭제
• 또는 분석 결과 조회 가능 시간이 짧다면 10분~1시간 TTL 적용
• 민감 페이지 가능성을 고려하면 public bucket보다는 presigned URL 방식 권장

운영 방식:

FastAPI -> S3 private bucket 업로드 -> presigned URL 발급 -> 프론트 표시 -> TTL 후 만료/삭제

2. base64 inline 응답

이미지를 API 응답 JSON 안에 직접 넣는 방식입니다.

예시:

{
  "snapshot": {
    "status": "available",
    "mime_type": "image/png",
    "base64": "iVBORw0KGgoAAAANSUhEUg...",
    "elapsed_seconds": 0.83
  }
}

장점:

• 별도 저장소가 필요 없음
• 프론트가 즉시 data:image/png;base64,...로 표시 가능
• MVP나 내부 테스트에는 단순함

단점:

• PNG 원본보다 약 33% 커짐
• API 응답 크기가 커짐
• callback, 로그, APM, gateway body size 제한에 걸릴 수 있음
• 캐싱/재조회/삭제 개념이 애매함
• 여러 사용자가 동시에 요청하면 네트워크 비용이 커짐

현실적인 사용 조건:

• 스냅샷이 1장이고 수백 KB 수준
• 내부 테스트 또는 MVP
• 응답 크기 제한을 명확히 둠

예시 제한:

page_snapshot_inline_max_bytes = 500_000

3. FastAPI 로컬 디스크 + 정적 파일 서빙

흐름:

1. FastAPI 서버 로컬 디스크에 PNG 저장
2. /static/snapshots/{id}.png 같은 URL로 제공
3. 응답에는 해당 경로 반환

장점:

• 구현이 단순함
• 개발/스테이징 테스트에 적합
• S3 없이 바로 확인 가능

단점:

• 운영 다중 인스턴스 환경에서 문제가 생김
• 서버 재시작/배포 시 파일 유지가 불안정함
• 디스크 cleanup 필요
• CDN/접근 제어/만료 처리가 번거로움

성능 테스트 결과

실제 정상 URL 10개를 대상으로 스냅샷 생성 테스트를 수행했습니다.

테스트 URL:

• https://www.google.com/

• https://www.youtube.com/

• https://www.wikipedia.org/

• https://www.apple.com/

• https://www.microsoft.com/

• https://github.com/

• https://www.python.org/

• https://fastapi.tiangolo.com/

• https://www.postgresql.org/

• https://www.mozilla.org/

  결과:

  • 총 10개
  • 성공 10개
  • 실패 0개
  • 타임아웃 0개
  • 평균 생성 시간: 약 1.94초
  • median: 약 1.99초

  테스트 산출물은 로컬 확인용으로 생성했으며 PR 커밋에는 포함하지 않았습니다.

  테스트

  실행한 검증:

  ruff check app/services/page_snapshot.py app/services/pipeline.py app/schemas/page_snapshot.py app/schemas/pipeline.py app/schemas/db_independent_pipeline.py tests/
  services/test_page_snapshot.py tests/services/test_pipeline.py

  pytest tests/services/test_pipeline.py tests/services/test_page_snapshot.py tests/api/test_analyze_db_independent.py tests/services/test_analysis_callback.py

  결과:

  • ruff 통과
  • 관련 테스트 39개 통과

  참고:

  전체 pytest 실행 시 450개 통과, 5개 실패가 있었으나 실패는 기존 작업트리에 남아 있는 OpenAIProvider 테스트 기대값 변경과 관련된 것으로, 이번 페이지 스냅샷 커밋에는 포함하지 않았습니다.

  연관 이슈 및 Close 할 이슈

  close [FEATURE] 링크 검사 결과에 페이지 스냅샷 제공 #45

  Pull Request 체크리스트

  TODO

  • 최종 결과물을 확인했는가?
  • 의미 있는 커밋 메시지를 작성했는가?