본문으로 건너뛰기

프론트엔드 요소

최종 업데이트: 2025년 6월 29일

이 문서는 SurfAI 웹사이트 화면을 만드는 프로그램(comfy-surfai-frontend-next)의 주요 부품들(컴포넌트), 정보 관리 도구(Context), 그리고 특별한 기능들(Hook)이 어떤 역할을 하고 어떻게 구성되어 있는지 쉽게 설명해 드립니다.

1. 전체 웹사이트에서 사용되는 정보 관리 및 기능들​

웹사이트 전체의 상태와 중요한 기능들을 관리하는 핵심 부분입니다.

가. AuthContext.tsx (로그인 정보 관리)​

  • 위치: src/contexts/AuthContext.tsx
  • 역할: 사용자가 로그인했는지, 어떤 사용자인지 같은 로그인 정보를 웹사이트 전체에서 관리하고, 로그인/로그아웃 같은 관련 기능들을 제공하는 **"로그인 정보 관리자"**입니다.
  • 주요 제공 정보:
    • user: 사용자 정보 | 없음: 현재 로그인한 사용자의 정보. 로그인하지 않았다면 '없음'으로 표시됩니다.
    • isLoading: 예/아니오: 웹사이트가 시작될 때나 로그인/로그아웃할 때 로그인 정보를 확인하는 동안 '예'가 됩니다.
    • login(로그인 정보): 일반 이메일/비밀번호 로그인을 처리하는 기능.
    • logout(): 사용자를 로그아웃시키고 관련 정보를 지우는 기능.
    • fetchUserProfile(): 서버에서 사용자 정보를 가져와서 현재 사용자 정보를 업데이트하는 기능.

나. useComfyWebSocket.ts (실시간 소통 기능)​

  • 위치: src/hooks/useComfyWebSocket.ts
  • 역할: 뒤에서 일하는 프로그램(서버)과 실시간으로 정보를 주고받으며, AI 그림/영상을 만드는 과정에서 발생하는 모든 상황들을 받아서 관련 정보들을 관리하는 **"실시간 소통 관리자"**입니다.
  • 주요 제공 정보:
    • isWsConnected: 예/아니오: 실시간 소통 연결 상태.
    • executionStatus: 글자 | 없음: "만드는 중...", "완성!" 등 현재 작업 상태를 알려주는 글자.
    • progressValue: { 현재 값, 최대 값 } | 없음: 그림/영상 만드는 과정의 진행률.
    • sessionOutputs: 기록된 그림/영상 정보 목록: '만들기' 페이지에서 현재 작업 중에 만들어진 그림/영상들의 목록. (최대 20개까지 보여줍니다)

다. apiClient.ts (정보 주고받는 통로)​

  • 위치: src/lib/apiClient.ts
  • 역할: 뒤에서 일하는 프로그램(서버)과 모든 정보를 주고받는 **"중앙 통신 통로"**입니다.
  • 주요 기능:
    • 자동 로그인 정보 갱신: 정보를 요청할 때 로그인 정보가 만료되어 오류가 발생하면, 자동으로 새로운 로그인 정보를 받아와서 원래 요청했던 작업을 다시 시도합니다.
    • 해킹 방지 기능 자동 추가: 정보를 보내서 내용을 바꾸는 요청(예: POST, PUT, DELETE)을 할 때, 해킹 공격을 막기 위한 특별한 정보(X-XSRF-TOKEN)를 자동으로 추가합니다.
    • 로그인 쿠키 자동 전송: 모든 요청에 사용자 컴퓨터에 저장된 로그인 관련 정보(cookie)가 자동으로 함께 보내지도록 합니다.

2. 웹사이트 페이지 부품들​

src/app/ 폴더 안에 있으며, 각 웹사이트 주소(URL)의 시작점이 되는 중요한 부품들입니다.

가. generate/page.tsx (그림/영상 만들기 페이지)​

  • 역할: AI 그림/영상을 만드는 웹사이트의 주요 페이지입니다.
  • 주요 기능:
    • useComfyWebSocket 기능을 사용해서 실시간으로 작업 상태를 관리합니다.
    • 그림/영상 만드는 방법(템플릿) 목록을 서버에서 가져와서 화면에 보여줍니다.
    • 사용자가 입력한 설정 값들로 그림/영상 만들기 요청을 서버에 보냅니다.
    • 현재 작업 중에 만들어진 그림/영상들을 화면에 보여줍니다.
    • 그림을 크게 보거나 작게 보는 기능(ImageLightbox)을 관리합니다.

나. history/page.tsx (내가 만든 기록 페이지)​

  • 역할: 사용자가 만들었던 모든 그림/영상 기록을 영구적으로 보여주는 "나의 앨범" 페이지입니다.
  • 주요 기능:
    • 서버에서 내가 만든 그림/영상 기록 목록을 가져옵니다.
    • '더 보기' 버튼을 눌러서 이전 기록들을 계속 볼 수 있는 기능을 제공합니다.
    • HistoryGallery와 GeneratedItem이라는 부품들을 사용해서 그림/영상들을 보여줍니다.
    • 그림을 크게 보거나 작게 보는 기능(ImageLightbox)을 관리합니다.

다. admin/workflows/new/page.tsx 및 admin/workflows/[id]/edit/page.tsx (관리자용 템플릿 관리 페이지)​

  • 역할: 관리자가 그림/영상 만드는 방법(템플릿)을 새로 만들거나 수정하는 페이지입니다.
  • 주요 기능:
    • 페이지에 접속할 때 사용자가 관리자인지 확인하고, 관리자가 아니면 다른 페이지로 이동시킵니다.
    • ParameterMappingForm이라는 부품을 사용해서 설정 값들을 입력하는 화면을 보여줍니다.
    • 새로 만들기 페이지: 템플릿의 기본 정보를 입력하고, 세부 설정 값들을 연결하는 두 단계로 진행됩니다. 각 단계에 맞는 요청을 서버에 보냅니다.
    • 수정 페이지: 페이지가 열릴 때 기존 템플릿 정보를 가져와서 화면에 보여주고, '저장' 버튼을 누르면 모든 변경 사항을 한 번에 서버에 반영합니다.

3. 다시 사용할 수 있는 부품들​

src/components/ 폴더 안에 있으며, 특정 화면 조각이나 기능을 담당하는 "단순한" 부품들입니다.

가. ParameterMappingForm.tsx (설정 값 연결 전문 부품)​

  • 위치: src/components/admin/ParameterMappingForm.tsx
  • 역할: 그림/영상 만드는 방법(템플릿)의 세부 설정 값들을 만들고 수정하는 데 사용되는, 복잡하지만 중요한 화면을 담당하는 **"설정 값 연결 전문 부품"**입니다.
  • 다시 사용되는 방법:
    • 새로 만들기 페이지: 두 번째 단계 화면에서 사용됩니다. '저장', '취소' 버튼을 누르면 해당 기능이 작동하도록 연결되어 있습니다.
    • 수정 페이지: 페이지의 일부로 포함됩니다. 정보만 보여주고 수정하는 역할을 하며, 최종 저장은 페이지의 메인 '저장' 버튼이 처리합니다.
  • 주요 기능:
    • 종류별 기능: 어떤 종류의 템플릿인지에 따라 필요한 설정 값 목록을 서버에서 가져옵니다.
    • 필수 설정 값 자동 추가: 새로 만들 때, 해당 종류에 꼭 필요한 설정 값들을 자동으로 화면에 추가합니다.
    • 똑똑한 화면:
      • 어떤 부품을 선택하면 그 부품의 자세한 정보(inputs, class_type)를 보여줍니다.
      • 설정 값 이름을 한 번 클릭하면 자동으로 완성됩니다.
      • 미리 정해진 설정 값들은 이름과 종류를 바꿀 수 없게 잠겨 있어서 실수를 막아줍니다.
      • 꼭 필요한 설정 값들은 지울 수 없게 되어 있습니다.
      • 이미 추가된 설정 값들은 '설정 값 추가' 목록에서 선택할 수 없게 비활성화됩니다.
    • 정보 관리: 부모 부품(페이지)에서 설정 값 정보와 업데이트 기능을 받아서 직접 화면의 정보를 관리합니다.

나. GeneratedItem.tsx (만들어진 그림/영상 하나)​

  • 역할: 갤러리에 보이는 그림/영상 카드 하나를 보여줍니다. '지금 작업 중인 그림/영상'과 '내가 만든 기록' 갤러리에서 모두 사용됩니다.
  • 주요 기능:
    • 받은 정보(item)를 바탕으로 화면을 그립니다.
    • 파일 종류에 따라 그림(<img>) 또는 영상(<video>)을 보여줍니다.
    • 사용된 설정 값들을 분석해서 영상의 길이를 계산하고 보여줍니다.
    • 만들어진 날짜를 기준으로 파일이 만료되었는지 확인하고, 만료되었다면 다른 화면을 보여줍니다.
    • 크게 보기/다운로드/삭제 버튼이 있으며, 이 버튼을 누르면 부모 부품에서 연결된 기능(onImageClick, onDelete)이 작동합니다.

다. ImageLightbox.tsx (그림/영상 크게 보기)​

  • 역할: 사용자가 갤러리에서 그림/영상을 눌렀을 때, 화면 전체를 덮으면서 그림/영상을 크게 보여주고 자세한 정보도 함께 보여주는 창입니다.
  • 주요 기능:
    • 받은 정보(item)를 바탕으로 화면을 보여줍니다. 정보가 없다면 숨겨집니다.
    • 왼쪽에는 그림/영상 주소(item.viewUrl)를 사용해서 그림/영상을 크게 보여줍니다.
    • 오른쪽에는 사용된 설정 값(item.usedParameters), 만들어진 날짜(item.createdAt) 등 자세한 정보들을 스크롤해서 볼 수 있게 보여줍니다.
    • 창 바깥쪽이나 'X' 버튼을 누르면 창이 닫히도록 연결된 기능(onClose)이 작동합니다.