Merge pull request #1331 from Moadong/feature/#1330-banner-api-MOA-744

[feature] 배너 api 연동

Author: seongwon030

.gitignore

@@ -6,4 +6,6 @@
 .env
 
 CLAUDE.md
-.claude
+.claude
+
+dailyNote/

frontend/src/apis/banner.ts

@@ -0,0 +1,28 @@
+import API_BASE_URL from '@/constants/api';
+import { handleResponse } from './utils/apiHelpers';
+
+export type BannerType = 'WEB' | 'APP_HOME' | 'WEB_MOBILE';
+
+export interface Banner {
+  id: string;
+  imageUrl: string;
+  linkTo: string | null;
+  alt: string;
+}
+
+// Banner API
+export const bannerApi = {
+  getBanners: async (type: BannerType = 'WEB'): Promise<Banner[]> => {
+    const url = new URL(`${API_BASE_URL}/api/banner`);
+    url.searchParams.set('type', type);
+
+    const response = await fetch(url);
+    const data = await handleResponse<{
+      statuscode: string;
+      message: string;
+      images: Banner[];
+    }>(response, `배너 목록 조회 실패 : ${response.status}`);
+
+    return data?.images ?? [];
+  },
+};

frontend/src/constants/queryKeys.ts

@@ -23,4 +23,9 @@ export const queryKeys = {
     all: ['promotions'] as const,
     list: () => ['promotions', 'list'] as const,
   },
+  banner: {
+    all: ['banner'] as const,
+    list: (type: 'WEB' | 'APP_HOME' | 'WEB_MOBILE') =>
+      ['banner', type] as const,
+  },
 } as const;

frontend/src/hooks/Queries/useBanner.ts

@@ -0,0 +1,12 @@
+import { useQuery } from '@tanstack/react-query';
+import { Banner, bannerApi, BannerType } from '@/apis/banner';
+import { queryKeys } from '@/constants/queryKeys';
+
+export const useGetBanners = (type: BannerType = 'WEB') => {
+  return useQuery<Banner[]>({
+    queryKey: queryKeys.banner.list(type),
+    queryFn: () => bannerApi.getBanners(type),
+    staleTime: 24 * 60 * 60 * 1000,
+    gcTime: 24 * 60 * 60 * 1000,
+  });
+};

frontend/src/pages/MainPage/components/Banner/Banner.stories.tsx

@@ -6,6 +6,7 @@ import NextButton from '@/assets/images/icons/next_button_icon.svg';
 import PrevButton from '@/assets/images/icons/prev_button_icon.svg';
 import { USER_EVENT } from '@/constants/eventName';
 import useMixpanelTrack from '@/hooks/Mixpanel/useMixpanelTrack';
+import { useGetBanners } from '@/hooks/Queries/useBanner';
 import useDevice from '@/hooks/useDevice';
 import useNavigator from '@/hooks/useNavigator';
 import { detectPlatform, getAppStoreLink } from '@/utils/appStoreLink';
@@ -18,6 +19,23 @@ const Banner = () => {
   const trackEvent = useMixpanelTrack();
   const [swiperInstance, setSwiperInstance] = useState<SwiperType | null>(null);
   const [currentIndex, setCurrentIndex] = useState(0);
+  const bannerType = isMobile ? 'WEB_MOBILE' : 'WEB';
+  const { data: banners, isLoading, isFetched } = useGetBanners(bannerType);
+
+  const fallbackBanners = BANNERS.map((banner) => ({
+    id: banner.id,
+    imageUrl: isMobile ? banner.mobileImage : banner.desktopImage,
+    linkTo: banner.linkTo ?? null,
+    alt: banner.alt,
+  }));
+
+  const hasApiBanners = (banners?.length ?? 0) > 0;
+  const shouldUseFallback = isFetched && !hasApiBanners;
+  const displayBanners = hasApiBanners
+    ? banners
+    : shouldUseFallback
+      ? fallbackBanners
+      : [];
 
   const handlePrev = () => {
     swiperInstance?.slidePrev();
@@ -53,6 +71,14 @@ const Banner = () => {
     handleLink(url);
   };
 
+  if (isLoading) {
+    return null;
+  }
+
+  if (displayBanners?.length === 0) {
+    return null;
+  }
+
   return (
     <Styled.BannerContainer>
       <Styled.BannerWrapper>
@@ -76,31 +102,32 @@ const Banner = () => {
           }}
           speed={500}
         >
-          {BANNERS.map((banner) => (
+          {displayBanners?.map((banner) => (
             <SwiperSlide key={banner.id}>
               <Styled.BannerItem
                 isClickable={!!banner.linkTo}
                 onClick={() =>
-                  handleBannerClick(banner.id, banner.alt, banner.linkTo)
+                  handleBannerClick(
+                    banner.id,
+                    banner.alt,
+                    banner.linkTo || undefined,
+                  )
                 }
               >
-                <img
-                  src={isMobile ? banner.mobileImage : banner.desktopImage}
-                  alt={banner.alt}
-                />
+                <img src={banner.imageUrl} alt={banner.alt} />
               </Styled.BannerItem>
             </SwiperSlide>
           ))}
         </Swiper>
         {isMobile && (
           <Styled.NumericPagination>
-            {currentIndex + 1} / {BANNERS.length}
+            {currentIndex + 1} / {displayBanners?.length ?? 0}
           </Styled.NumericPagination>
         )}
 
         {!isMobile && (
           <Styled.DotPagination>
-            {BANNERS.map((_, index) => (
+            {displayBanners?.map((_, index) => (
               <Styled.Dot key={index} active={currentIndex === index} />
             ))}
           </Styled.DotPagination>