Feat/#73 키워드 기반 등록된 맛집 검색 API 연결 및 useSearch 커스텀 훅 구현

apps/web/app/_apis/schemas/kakaoSearch.ts

@@ -0,0 +1,21 @@
+export const KAKAO_CATEGORY_CODE = {
+  restaurant: 'FD6',
+  cafe: 'CE7',
+}
+
+export type KakaoSearchFuncParams = {
+  query: string
+  categoryCode: KakaoCategoryCode
+  location: { x: number; y: number }
+}
+
+export type SearchPlaceByKakao = {
+  id: string
+  place_name: string
+  x: string
+  y: string
+  road_address_name?: string
+  address_name: string
+}
+
+export type KakaoCategoryCode = keyof typeof KAKAO_CATEGORY_CODE

apps/web/app/_apis/schemas/place.ts

@@ -37,6 +37,12 @@ export const PlaceByMapSchema = BasePlaceSchema.extend({
   photos,
 })
 
+export const PlaceBySearchSchema = BasePlaceSchema.pick({
+  placeId: true,
+  placeName: true,
+  address: true,
+})
+
 export const PlaceDetailSchema = BasePlaceSchema.extend({
   location,
   isLiked: z.boolean(),
@@ -75,6 +81,7 @@ export type MapBounds = {
 
 export type BasePlace = z.infer<typeof BasePlaceSchema>
 export type PlaceByMap = z.infer<typeof PlaceByMapSchema>
+export type PlaceBySearch = z.infer<typeof PlaceBySearchSchema>
 export type PlaceDetail = z.infer<typeof PlaceDetailSchema>
 export type PlaceByPreview = z.infer<typeof PlaceByPreviewSchema>
 export type NewPlaceRequest = z.infer<typeof NewPlaceRequestSchema>

apps/web/app/_apis/services/kakaoSearch.ts

@@ -0,0 +1,35 @@
+import axios from 'axios'
+import { API_PATH } from '@/_constants/path'
+import {
+  KAKAO_CATEGORY_CODE,
+  type KakaoSearchFuncParams,
+  type SearchPlaceByKakao,
+} from '@/_apis/schemas/kakaoSearch'
+
+export const getSearchPlaceByKakao = async ({
+  query,
+  categoryCode,
+  location,
+}: KakaoSearchFuncParams): Promise<SearchPlaceByKakao[]> => {
+  const KAKAO_API_KEY = process.env.NEXT_PUBLIC_KAKAO_API || ''
+  const { x, y } = location
+  try {
+    const { data } = await axios.get(
+      API_PATH.KAKAO.SEARCH(query, KAKAO_CATEGORY_CODE[categoryCode], x, y),
+      {
+        headers: {
+          Authorization: `KakaoAK ${KAKAO_API_KEY}`,
+        },
+      },
+    )
+
+    if (!data?.documents || !Array.isArray(data.documents)) {
+      return []
+    }
+
+    return data.documents
+  } catch (error) {
+    console.error('카카오 장소 검색 실패:', error)
+    throw error
+  }
+}

apps/web/app/_apis/services/place.ts

@@ -1,4 +1,3 @@
-import axios from 'axios'
 import axiosInstance from '@/_lib/axiosInstance'
 import { API_PATH } from '@/_constants/path'
 import type { CampusType } from '@/_constants/campus'
@@ -8,18 +7,16 @@ import {
   type PlaceDetail,
   type MapBounds,
   type PlaceByMap,
+  type PlaceBySearch,
   type PlaceByPreview,
   type NewPlaceRequest,
   type NewPlaceResponse,
   BasePlaceSchema,
   PlaceByMapSchema,
+  PlaceBySearchSchema,
   PlaceDetailSchema,
   PlaceByPreviewSchema,
 } from '../schemas/place'
-import {
-  type KakaoSearchFuncParams,
-  KAKAO_CATEGORY_CODE,
-} from '@/_hooks/useSearchPlaceByKakao'
 
 export const getPlacesByRanking = async (
   sort: RankingPlaceSort,
@@ -58,30 +55,18 @@ export const getPlacesByMap = async ({
   return PlaceByMapSchema.array().parse(data)
 }
 
+export const getPlacesBySearch = async (
+  keyword: string,
+): Promise<PlaceBySearch[]> => {
+  const { data } = await axiosInstance.get(API_PATH.PLACES.SEARCH(keyword))
+  return PlaceBySearchSchema.array().parse(data)
+}
+
 export const getPlaceDetail = async (id: string): Promise<PlaceDetail> => {
   const { data } = await axiosInstance.get(API_PATH.PLACES.DETAIL(id))
   return PlaceDetailSchema.parse(data)
 }
 
-export const getSearchPlaceByKakao = async ({
-  query,
-  categoryCode,
-  location,
-}: KakaoSearchFuncParams) => {
-  const KAKAO_API_KEY = process.env.NEXT_PUBLIC_KAKAO_API || ''
-  const { x, y } = location
-
-  const { data } = await axios.get(
-    API_PATH.KAKAO.SEARCH(query, KAKAO_CATEGORY_CODE[categoryCode], x, y),
-    {
-      headers: {
-        Authorization: `KakaoAK ${KAKAO_API_KEY}`,
-      },
-    },
-  )
-  return data
-}
-
 export const getPlaceByPreview = async (
   kakaoPlaceId: string,
 ): Promise<PlaceByPreview> => {

apps/web/app/_components/SearchPage/SearchPage.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useState } from 'react'
+import { useState } from 'react'
+import { Spinner } from '@heroui/react'
 import { Icon } from '@repo/ui/components/Icon'
 import { Flex, VerticalScrollArea } from '@repo/ui/components/Layout'
 import { SearchPlaceListItem } from './SearchPlaceListItem'
@@ -47,15 +48,21 @@ export const SearchPage = ({
   useBackHandler = false,
 }: Props) => {
   const [inputValue, setInputValue] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
 
-  useEffect(() => {
-    if (inputValue.length > 0) {
-      searchFunc(inputValue)
+  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const value = e.target.value
+    setInputValue(value)
+    if (value.length > 0) {
+      searchFunc(value)
     }
-  }, [inputValue, searchFunc])
+  }
 
   return (
     <>
+      {isLoading && (
+        <Spinner className='absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2' />
+      )}
       <Flex className={'border-b-1 gap-2.5 border-gray-100 p-3.5'}>
         {useBackHandler ? (
           <HeaderBackButton />
@@ -64,7 +71,7 @@ export const SearchPage = ({
         )}
         <input
           value={inputValue}
-          onChange={(e) => setInputValue(e.target.value)}
+          onChange={handleInputChange}
           className={'w-full text-lg font-medium outline-none'}
           placeholder={placeholder || '장소 또는 주소를 검색하세요'}
         />
@@ -76,7 +83,10 @@ export const SearchPage = ({
               key={place.id}
               inputValue={inputValue}
               place={place}
-              onClick={() => onSelectPlace(place.id)}
+              onClick={() => {
+                setIsLoading(true)
+                onSelectPlace(place.id)
+              }}
             />
           ))}
         </VerticalScrollArea>

apps/web/app/_constants/path.ts

@@ -26,6 +26,7 @@ export const API_PATH = {
       POST: (id: string) => `/places/${id}/like`,
       DELETE: (id: string) => `/places/${id}/like`,
     },
+    SEARCH: (keyword: string) => `/places/search?keyword=${keyword}`,
   },
   KAKAO: {
     SEARCH: (query: string, categoryCode: string, x: number, y: number) =>

apps/web/app/_hooks/useSearch.ts

@@ -0,0 +1,53 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/**
+ * - 입력된 query를 기준으로 장소 검색 API 호출
+ * - 300ms 디바운싱 적용 (빠른 입력 시 불필요한 요청 방지)
+ * - API 결과를 상태로 관리하여 컴포넌트에서 바로 사용 가능
+ *
+ * @example
+ *  const { searchResult: cafeResult, searchFunc: cafeSearchFunc } = useSearch<
+ *     SearchPlace,
+ *     KakaoSearchFuncParams
+ *   >(getSearchPlaceByKakao)
+ *
+ *
+ * @template T 검색 결과 아이템의 타입 (예: SearchPlace)
+ * @template P 검색 함수에 들어갈 파라미터 타입 (예: KakaoSearchFuncParams)
+ * @param fetcher Promise<T[]>를 반환하는 비동기 검색 함수
+ *
+ * @returns searchResult - 검색된 장소 리스트
+ * @returns searchFunc - 검색을 수행하는 함수
+ */
+
+export const useSearch = <T, P>(fetcher: (params: P) => Promise<T[]>) => {
+  const [searchResult, setSearchResult] = useState<T[]>([])
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const searchFunc = useCallback(
+    (params: P) => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current)
+
+      timeoutRef.current = setTimeout(async () => {
+        try {
+          // 주입받은 fetcher 실행
+          const result = await fetcher(params)
+          setSearchResult(result)
+        } catch (error) {
+          console.error('Search failed:', error)
+          setSearchResult([])
+        }
+      }, 300)
+    },
+    [fetcher], // fetcher가 변경되면 함수 재생성
+  )
+
+  // 언마운트 시 타이머 클리어
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current)
+    }
+  }, [])
+
+  return { searchResult, searchFunc }
+}

apps/web/app/places/[id]/PlaceDetailPage.tsx

@@ -23,23 +23,20 @@ export const PlaceDetailPage = ({ id }: { id: string }) => {
         right={<LikeButton placeId={placeId} initIsLiked={isLiked} />}
       />
       <VerticalScrollArea className={'flex-1'}>
-        {photos.length > 0 && (
-          <Banner
-            contents={photos.map((photo) => (
-              <Image
-                key={photo.displayOrder}
-                src={photo.photoUrl}
-                alt='place-photo'
-                width={450}
-                height={180}
-                className={'max-h-[180px] object-contain'}
-              />
-            ))}
-            minHeight={180}
-            showIndicator={true}
-          />
-        )}
-
+        <Banner
+          contents={photos.map((photo) => (
+            <Image
+              key={photo.displayOrder}
+              src={photo.photoUrl}
+              alt='place-photo'
+              width={450}
+              height={180}
+              className={'max-h-[180px] object-contain'}
+            />
+          ))}
+          minHeight={180}
+          showIndicator={true}
+        />
         <Column className={'flex-1 justify-around gap-4 p-5'}>
           <Location location={location} />
           <Menus menus={menus} />

apps/web/app/places/new/_components/Step/PlacePreview/PlacePreview.tsx

@@ -60,6 +60,7 @@ export const PlacePreview = ({ getValues, setValue, nextStep }: Props) => {
               className={'max-h-[180px] object-contain'}
             />
           ))}
+          showIndicator={true}
           minHeight={180}
         />
         <Column className={'flex-1 justify-around gap-4'}>