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

[minsoo0506]

기능 추가/수정

설명

링크 검사 결과에서 사용자가 최종 URL 페이지의 시각적 스냅샷을 확인할 수 있도록 스냅샷 생성/저장/응답 기능을 추가한다.

현재 파이프라인은 normalize -> unchain -> threat_db/domain_heuristic -> content_analysis 흐름이며, 가능한 경우 스냅샷 생성은 기존 검사 흐름과 병렬로 실행한다. 단, 스냅샷 생성을 병렬로 붙였을 때도 사용자 응답 시간이 1초 이상 증가한다면 동기 응답 경로에 포함하지 않고 비동기 후처리 또는 스킵 처리로 전환한다.

수용 기준:

• 최종 URL 기준으로 페이지 스냅샷을 생성한다.
• 응답에는 스냅샷 상태를 표현하는 필드를 추가한다.
  • 예: available, skipped, timeout, failed
  • 스냅샷 URL 또는 storage key는 성공 시에만 포함한다.
• threat DB 매치 등으로 이미 위험 판정이 확정되어 콘텐츠 분석을 건너뛰는 경우, 실제 페이지를 열지 않고 스냅샷도 생성하지 않는다.
• SSRF 방어, private IP 차단, 타임아웃 정책은 기존 콘텐츠 분석/렌더링 정책과 일관되게 적용한다.
• 스냅샷 실패/타임아웃은 링크 검사 verdict, score, summary를 실패시키지 않는다.
• 병렬 실행 기준으로 timings.total_seconds 또는 실제 wall-clock 증가분이 p95에서 1초 이상이면 동기 응답 경로에서 제외한다.
• 스냅샷 생성 소요 시간과 실패 사유를 로그 또는 응답 메타데이터로 관측할 수 있어야 한다.

테스트 요구사항

• 정상 HTML 페이지에서 스냅샷 성공 상태가 응답에 포함되는지 검증한다.
• threat DB 매치로 조기 종료되는 경우 스냅샷 생성을 호출하지 않는지 검증한다.
• 페이지 unavailable, timeout, blocked_host 상황에서 스냅샷 실패가 파이프라인 실패로 전파되지 않는지 검증한다.
• 스냅샷 task가 예외를 내도 기존 PipelineSuccess/PipelineFailure 의미가 바뀌지 않는지 검증한다.
• 스냅샷 생성 지연이 최종 응답 시간을 1초 이상 늘리는 경우 timeout, skipped, 또는 비동기 후처리 경로로 처리되는지 검증한다.
• 외부 네트워크나 실제 브라우저에 강하게 의존하지 않도록 mock/fake 기반 단위 테스트를 포함한다.

🗒 체크리스트

• 스냅샷 생성 설계를 마쳤는가?
• 스냅샷 응답 스키마를 정의했는가?
• 스냅샷 저장 위치 및 만료 정책을 정했는가?
• 파이프라인 병렬 실행 시 응답 시간 증가분이 1초 미만인지 측정했는가?
• 실패/타임아웃/스킵 상태가 사용자에게 구분되어 전달되는가?
• 보안 차단 정책이 기존 콘텐츠 분석 정책과 일관되는가?
• 테스트 코드를 작성했는가?
• API 명세서(Swagger 등)를 업데이트했는가?