[FEATURE] 페이지 불가용(PAGE_UNAVAILABLE) 분석 응답 처리

[kbh0218]

📝 기능 설명

백엔드 LinClean-BE-spring의 PR #47로 페이지 불가용(PAGE_UNAVAILABLE) 처리 결과가 분석 응답에 포함되도록 변경되었습니다.

참고 백엔드 PR:

• [FEATURE] 페이지 불가용(PAGE_UNAVAILABLE) 처리 추가 LinClean-BE-spring#47

백엔드 변경 내용:

• FastAPI가 전달하는 stages.content_analysis.statusCode, error, reason 값을 Spring에서 역직렬화합니다.
• 분석 응답 AnalysisResponse에 contentAnalysisError 필드가 추가되었습니다.
• contentAnalysisError는 content analysis 단계에서 fetched=false인 경우 stages.content_analysis.reason 값을 기반으로 내려옵니다.
• contentAnalysisError가 없으면 JSON 응답에서 제외됩니다.
• 기존 정상 fetch 케이스의 응답 구조는 변경되지 않습니다.

현재 프론트의 AnalysisResponse 타입에는 contentAnalysisError 필드가 없어, 페이지 본문을 가져오지 못한 분석 결과를 별도로 표시할 수 없습니다.

이번 작업에서는 분석 응답 타입에 contentAnalysisError를 반영하고, 검사 결과 화면에서 페이지 불가용 사유를 사용자가 이해할 수 있는 형태로 안내합니다.

📋 구현할 Task

• 백엔드 PR #47의 분석 응답 변경 사항을 확인했는가?
• api/analyses.ts의 AnalysisResponse 타입에 contentAnalysisError?: string 필드를 추가했는가?
• contentAnalysisError가 없는 기존 정상 분석 응답이 그대로 동작하는가?
• contentAnalysisError가 있는 응답을 검사 결과 화면에서 확인할 수 있는가?
• 페이지 불가용 사유를 사용자에게 자연스러운 한글 문구로 변환했는가?
• contentAnalysisError 값이 예상하지 못한 문자열이어도 화면이 깨지지 않도록 처리했는가?
• 페이지 본문 분석을 완료하지 못한 경우에도 기존 verdict 결과 화면 이동 흐름이 깨지지 않는가?
• 안전 결과 화면에서 contentAnalysisError 표시 정책을 확인했는가?
• 주의 결과 화면에서 contentAnalysisError 표시 정책을 확인했는가?
• 위험 결과 화면에서 contentAnalysisError 표시 정책을 확인했는가?
• 기존 summary와 reasons 표시 우선순위와 충돌하지 않도록 처리했는가?
• 페이지 불가용 안내가 기존 ScanResultReason 카드 또는 별도 안내 UI 안에서 어색하지 않게 표시되는가?
• 저장 링크 모달에 전달되는 제목/설명 값이 기존처럼 정상 동작하는가?
• 저장 링크 API 호출 시 analysisId 기반 저장 흐름이 기존과 동일하게 유지되는가?
• Android 에뮬레이터에서 페이지 불가용 URL 검사 결과를 확인했는가?
• 실제 휴대폰 preview 빌드에서 페이지 불가용 안내 문구가 자연스럽게 표시되는지 확인했는가?

📎 우선 확인 대상

분석 API 타입:

• api/analyses.ts
• AnalysisResponse
• requestAnalysis
• fetchAnalysis

분석 결과 조회 hook:

• hooks/use-analysis-result.ts
• 분석 결과 fetch 후 응답 타입 처리

검사 중 화면:

• app/(tabs)/(home)/scanning.tsx
• handleAnalysisResult
• 결과 화면 router.replace() 흐름

검사 결과 화면:

• app/(tabs)/(home)/scan-result.tsx
• app/(tabs)/(home)/scan-result-caution.tsx
• app/(tabs)/(home)/scan-result-block.tsx

결과 표시 유틸:

• utils/analysis-result-display.ts
• getAnalysisReasonText
• 필요 시 contentAnalysisError 표시 문구 formatter 추가

결과 사유 컴포넌트:

• components/ui/scan-result-reason.tsx

📎 해결 방향

분석 응답 타입에 contentAnalysisError를 추가하고, 검사 결과 화면에서 해당 값이 있을 때 페이지 불가용 안내를 표시합니다.

처리 방향:

• api/analyses.ts의 AnalysisResponse에 contentAnalysisError?: string 필드를 추가합니다.
• 백엔드 분석 API는 { data: AnalysisResponse } 형태로 응답하지만, 프론트의 authenticatedApiRequest에서 data가 unwrap되므로 화면/훅에서는 기존처럼 AnalysisResponse로 다룹니다.
• 결과 화면에서는 analysis.contentAnalysisError가 존재하는지 확인합니다.
• contentAnalysisError 값은 백엔드의 stages.content_analysis.reason 기반 값이므로 특정 문자열 하나로만 고정하지 않고 방어적으로 처리합니다.
• 사용자에게는 원본 에러 문자열을 그대로 노출하기보다 자연스러운 한글 안내 문구로 변환합니다.
• 예시 문구: 페이지 내용을 가져오지 못했어요. 사이트 접속이 제한되었거나 일시적으로 응답하지 않을 수 있습니다.
• 기존 summary, reasons 표시와 충돌하지 않도록 우선순위를 정리합니다.
• contentAnalysisError가 없으면 기존 결과 화면 표시 방식은 그대로 유지합니다.

📎 추가 내용

• 이번 이슈에서는 백엔드 PR #47의 contentAnalysisError 응답 반영만 처리합니다.
• 분석 요청 API나 polling 구조 자체는 변경하지 않습니다.
• 페이지 불가용이어도 백엔드가 status: succeeded와 verdict를 내려주는 경우, 기존 결과 화면 이동 정책을 유지합니다.
• contentAnalysisError가 없는 기존 정상 분석 결과, 실패 결과, timeout 처리 흐름에 영향이 없어야 합니다.