[FE] refactor: 파일 다운로드 api 변경

[mun-kyeong]

🔨어떤 작업인가요?

파일 다운로드 로직 수정

✅작업 상세 내용

• 파일 다운로드 로직 수정

🙋🏻참고할만한 자료(선택)

[mun-kyeong]

새롭게 알게 된 사실

 enabled: pollingEnabled,
  refetchInterval: (query) => {
    const data = query.state.data;
    if (!data) return 2000;
    if (
      data.data.jobStatus === 'COMPLETED' ||
      data.data.jobStatus === 'FAILED'
    ) {
      return false;
    }
    return 2000;
  },

polling을 시작하고 끝내는 로직을 enabled와 refetchInterval 값으로 관리하게 되었다.

• enabled값으로는 jobId가 할당되기 전까지는 polling이 시작하지 않는다.
• jobId가 생기는 순간 polling을 시작하게 된다. 그리고 api의 응답 값으로 COMPLETED 또는 FAILED 상태를 가지면 polling을 중단한다.

원래는 refetchInterval 값을 2000 이런 식으로 재시도 할 시간으로 사용할 수 있는데, 함수형으로 작성하면 각 쿼리의 상태에 따라 폴링 동작을 동적으로 제어할 수 있다.

쿼리 실행 도중 polling을 멈추고 싶다면 enabled로는 제어할 수 없다. 왜냐면 enabled는 한번 false 에서 다시 true로 바껴야만 쿼리가 재시작 되기 때문에 data 기반으로 자연스럽게 polling을 중단하는 패턴과 맞지 않다.

참고 링크 - polling 중단 상태 관리

[mun-kyeong]

다운로드 중 상태 표현 방식

• 토스트 알림
• 버튼 텍스트 변경

위의 두 가지로 상태를 표시할 수 있을 것 같다.
떠오르는 방법으로는

1. 토스트 알림으로 진행률 표시 (완료 전까지 계속 떠있어야함) + 버튼 비활성화 처리
2. 토스트 알림으로는 '시작했습니다!' '완료되었습니다!'라는 알림만 주고, 버튼의 배경 색이 왼쪽부터 오른쪽으로 채워지는 형식으로 진행률 표시하기

이렇게 두 가지가 있는 것 같다.
첫번째 방법으로는 토스트 메시지를 통해 사용자가 다운로드 상태를 직관적으로 알 수 있다는 점이 있지만 토스트 컴포넌트를 새로 만들어야 하고, 오랫동안 다운로드 받아야 하는 상황이라면 거슬릴 수 있을 것 같다

두번째 방법으로는 구현이 간단하지만 사용자가 얼마나 다운로드 되고 있는지를 확인하려면 옵션 창을 열어야 한다.

@coderabbitai
위의 두가지 방법 중에 어느 방법이 더 좋을까?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@mun-kyeong, 두 가지 방법의 장단점을 잘 분석하셨네요! 제 의견을 공유하겠습니다.

추천: 하이브리드 접근 방식

두 가지 중 하나를 선택하기보다는, 하이브리드 접근을 추천드립니다:

제안하는 방식

1. 버튼 상태로 진행률 표시 (옵션 2의 아이디어)

   • 버튼 텍스트: "다운로드 중..."
   • 버튼 배경이 왼쪽에서 오른쪽으로 채워지는 진행 표시
   • 버튼 비활성화 처리 (클릭 방지)

2. 토스트는 시작/완료/실패 알림만 (옵션 2의 아이디어)

   • 시작: "다운로드를 시작합니다"
   • 완료: "다운로드가 완료되었습니다"
   • 실패: "다운로드에 실패했습니다"

이 방식을 추천하는 이유

✅ 장점:

• 비침해적(Non-intrusive): 토스트가 오래 떠있지 않아 다른 작업에 방해되지 않음
• 진행 상태 가시성: 버튼 자체가 진행 상태를 보여주므로 사용자가 옵션 창을 열어두면 언제든 확인 가능
• 간단한 구현: 기존 토스트 컴포넌트 재사용 가능, 버튼 진행 바만 구현하면 됨
• 일관성: 일반적인 다운로드 UX 패턴과 일치 (많은 웹 앱에서 버튼이 로딩 상태를 표시)

📌 추가 고려사항:

• 진행률이 백엔드에서 제공되지 않는다면 (jobStatus만 확인), 무한 로딩 애니메이션 또는 indeterminate 진행 바 사용
• 백엔드에서 진행률(%)을 제공한다면 정확한 퍼센트 표시 가능

구현 참고

// 버튼 상태 예시
{isDownloading ? (
  <Button disabled className="relative overflow-hidden">
    <span className="relative z-10">다운로드 중...</span>
    {/* 진행률이 있다면 */}
    <div 
      className="absolute left-0 top-0 h-full bg-primary-dark transition-all"
      style={{ width: `${progress}%` }}
    />
    {/* 진행률이 없다면 무한 로딩 애니메이션 */}
    <div className="absolute left-0 top-0 h-full w-full animate-shimmer" />
  </Button>
) : (
  <Button onClick={handleDownload}>다운로드</Button>
)}

만약 장시간 다운로드가 예상된다면, 추가로 브라우저 알림(Browser Notification API)을 고려해볼 수도 있습니다. 사용자가 다른 탭으로 이동해도 완료 알림을 받을 수 있거든요.

어떻게 생각하시나요?

[mun-kyeong]

@coderabbitai
**브라우저 알림(Browser Notification API)**이게 정확하게 어떤걸 의미해?
현재 다운로드가 끝나면 자동으로 만들어진 파일을 다운로드 할 수 있게 redirect api를 요청하고, 그럼 브라우저가 다운로드 받게 되는데 그거랑은 다른거야?

아 그리고 다운로드 중에는 창 닫지 못하게 하고싶어

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@mun-kyeong, 좋은 질문입니다! 두 가지 질문에 대해 자세히 설명드리겠습니다.

1. Browser Notification API란?

Browser Notification API는 브라우저의 시스템 레벨 알림을 의미합니다. 현재 구현하신 자동 다운로드와는 완전히 다른 기능입니다.

차이점

구분	Browser Notification API	현재 구현 (브라우저 다운로드)
위치	OS 알림 센터 (화면 우측 상단/하단)	브라우저 다운로드 바 (하단)
표시 시점	개발자가 명시적으로 호출	파일 다운로드 시 자동
다른 탭에서 알림	✅ 가능 (사용자가 다른 탭/앱 사용 중에도 알림)	❌ 불가능
권한 필요	✅ 사용자 권한 필요	❌ 권한 불필요
용도	장시간 작업 완료 알림	파일 다운로드

Browser Notification API 예시

// 1. 권한 요청
const requestNotificationPermission = async () => {
  if ('Notification' in window) {
    const permission = await Notification.requestPermission();
    return permission === 'granted';
  }
  return false;
};

// 2. 알림 표시
const showNotification = (title: string, body: string) => {
  if (Notification.permission === 'granted') {
    new Notification(title, {
      body,
      icon: '/logo.png', // 선택사항
      badge: '/badge.png', // 선택사항
    });
  }
};

// 3. 다운로드 완료 시 사용 예시
const handleDownloadComplete = () => {
  // 기존 토스트 알림
  toast.success('다운로드가 완료되었습니다');
  
  // 추가: 사용자가 다른 탭을 보고 있을 때를 위한 시스템 알림
  if (document.hidden) { // 현재 탭이 비활성화 상태일 때만
    showNotification(
      '다운로드 완료',
      '요청하신 파일 다운로드가 완료되었습니다'
    );
  }
};

언제 유용한가?

• 파일 생성에 수 분 이상 걸리는 경우
• 사용자가 다른 탭이나 다른 앱을 사용할 가능성이 높은 경우
• 예: 대용량 데이터 export, 복잡한 리포트 생성 등

현재 상황에서는 필요 없을 수 있습니다 (다운로드가 빠르다면).

---

2. 다운로드 중 창 닫기 방지

다운로드 진행 중에 사용자가 실수로 창을 닫는 것을 방지하려면 beforeunload 이벤트를 사용하면 됩니다.

구현 방법

import { useEffect } from 'react';

const usePreventWindowClose = (isDownloading: boolean) => {
  useEffect(() => {
    if (!isDownloading) return;

    const handleBeforeUnload = (e: BeforeUnloadEvent) => {
      // 표준 방식
      e.preventDefault();
      // 일부 브라우저 호환성을 위해
      e.returnValue = '';
      return '';
    };

    window.addEventListener('beforeunload', handleBeforeUnload);

    return () => {
      window.removeEventListener('beforeunload', handleBeforeUnload);
    };
  }, [isDownloading]);
};

사용 예시

const DownloadOptions = () => {
  const [jobId, setJobId] = useState<string | null>(null);
  const [isDownloading, setIsDownloading] = useState(false);

  // 다운로드 상태 조회 (polling)
  const { data } = useQuery({
    queryKey: ['downloadStatus', jobId],
    queryFn: () => fetchDownloadStatus(jobId!),
    enabled: !!jobId && isDownloading,
    refetchInterval: (query) => {
      const data = query.state.data;
      if (!data) return 2000;
      
      const status = data.data.jobStatus;
      if (status === 'COMPLETED' || status === 'FAILED') {
        setIsDownloading(false); // polling 중단
        return false;
      }
      return 2000;
    },
  });

  // 창 닫기 방지 hook 사용
  usePreventWindowClose(isDownloading);

  const handleDownload = async () => {
    setIsDownloading(true);
    const response = await startDownload();
    setJobId(response.jobId);
  };

  useEffect(() => {
    if (data?.data.jobStatus === 'COMPLETED') {
      // 파일 다운로드 시작
      window.location.href = `/api/download/${jobId}/redirect`;
      toast.success('다운로드가 완료되었습니다');
    }
  }, [data?.data.jobStatus]);

  return (
    <Button 
      onClick={handleDownload}
      disabled={isDownloading}
    >
      {isDownloading ? '다운로드 중...' : '다운로드'}
    </Button>
  );
};

동작 방식

1. isDownloading이 true가 되면 beforeunload 이벤트 리스너 등록
2. 사용자가 탭/창을 닫으려고 하면 브라우저가 확인 대화상자 표시:
   • Chrome/Edge: "변경사항이 저장되지 않을 수 있습니다"
   • Firefox: "이 페이지를 나가시겠습니까?"
3. 다운로드 완료/실패 시 isDownloading이 false가 되어 이벤트 리스너 제거

주의사항

• 브라우저는 사용자 보호를 위해 커스텀 메시지를 표시하지 않습니다 (과거에는 가능했지만 보안상 이유로 제거됨)
• 모달 형태로 직접 만든 확인 대화상자는 사용할 수 없습니다 (브라우저 기본 대화상자만 가능)
• 이 기능은 사용자 경험을 위한 안전장치이므로 반드시 필요한 경우에만 활성화하세요

이렇게 구현하면 다운로드 중 실수로 창을 닫는 것을 방지할 수 있습니다! 🐰

[mun-kyeong]

상태 끌어올리기

메뉴 창이 닫힐 때 마다 다운로드를 하지 못하는 현상을 발견했다.
원래의 구조는 MoreMenu 라는 컴포넌트 내에서 파일 다운로드 훅을 호출하는 형식이였는데,
원래 기대했던 방식은 '피드백 추출' 버튼을 누른 다음 파일 다운로드는 백그라운드에서 자동으로 실행되기를 바랬다.
그래서 파일 다운로드가 완료 될 때 까지 메뉴 창을 닫지 못하는 현상이 수정되어야 할 필요성을 느끼게 되었다.

문제 원인

MoreMenu를 호출하는 부모 컴포넌트에서 아래와 같은 조건부 렌더링을 보여주고 있었기 때문이였다.
closeMoreMenu를 호출하면 isOpenMoreMenu 값이 false가 되면서 화면에서 언마운트가 되어버렸던 것.
그래서 MoreMenu안에 있던 훅들도 제거가 되면서 다운로드 상태를 받아오지 못할 뿐더러,
다운로드 api를 호출할 수 있는 트리거도 제거가 된 것이 원인이였다.

    {isOpenMoreMenu && (
        <div css={moreMenu}>
          <MoreMenu closeMoreMenu={closeMoreMenu} />
        </div>
      )}

MoreMenu가 닫히면서(언마운트) 폴링 훅이 제거 → 다운로드 완료 상태를 못 받음 → 다운로드 실행 함수가 트리거되지 않음 → 다운로드가 “취소된 것처럼” 보임

해결책

생각나는 해결책은 두가지 정도였다.

1. 상태를 부모 컴포넌트로 끌어올리기. 단, props drilling이 발생할 수 있음
2. 조건부 렌더링을 사용해서 컴포넌트를 언마운트 시키지 말고 css의 display와 같은 속성을 사용하여 보이지 않게 하기

위의 두 가지 방법중에 1번, 커스텀 훅을 부모 컴포넌트로 끌어올리는 방법을 선택하게 되었다.
이유는 '파일 다운로드'라는 기능이 UI에 영향을 받아선 안된다고 생각이 들었고,
단순이 눈에 보이지 않게 만드는 것 보다 '언마운트로 인한 api 흐름이 끊기는 문제'를 근본적으로 해결할 수 있는 방법이라는 생각이 들었다.

결과는!

메뉴 컴포넌트가 닫혀도 파일 다운로드는 계속 유지되고 있는 것을 확인할 수 있다~~

2025-11-20.2.43.41.mov