feat : 카카오맵 연동 및 검색 결과 마커 자동으로 이동되도록 구현

[jjjsun]

💡 개요

카카오맵 SDK를 동적 로딩으로 연동하고, 검색 결과를 지도 마커로 표시해서 선택상태와 검색 상태에 따라 자동으로 지도의 중심이 이동 및 줌 동작을 적용했습니다.

🔢 관련 이슈 링크

• Closes [feat] 식당리스트 지도 영역에 카카오맵 연동 + 주소 기반 마커 표시 #44

💻 작업내용

• Kakao Maps SDK 동적 로딩 유틸(src/lib/kakao.ts) 추가 및 .env(VITE_KAKAO_JS_KEY) 기반 키 주입
• KakaoMap 컴포넌트 구현: 지도생성, 마커 랜더링, 마커 클릭 이벤트(상세 모달 오픈) 연결
• 검색 결과에 따라 지도 bounds 자동 맞춤진행, 그중 식당 1개 선택시 자동으로 식당 중심으로 이동과 줌 진행
• SearchPage에서 검색/선택 상태 관리 정리 (식당 선택을 해제한 후에 다시 검색할시에 bounds 정상작동하도록 설정)

📌 변경사항PR

• FEAT: 새로운 기능 추가
• FIX: 버그/오류 수정
• CHORE: 코드/내부 파일/설정 수정
• DOCS: 문서 수정(README 등)
• REFACTOR: 코드 리팩토링 (기능 변경 없음)
• TEST: 테스트 코드 추가/수정
• STYLE: 스타일 변경(포맷, 세미콜론 등)

🤔 추가 논의하고 싶은 내용

• 마커 스타일 작업은 추후에 진행예정입니다!
• 기본 주소는 서울시청으로 잡아두었으니 그점 참고 부탁드립니다!

✅ 체크리스트

• 브랜치는 잘 맞게 올렸는지
• 관련 이슈를 맞게 연결했는지
• 로컬에서 정상 동작을 확있했는지
• 충돌이 없다(또는 브랜치에서 충돌 해결 후 PR 업데이트 완료)

Summary by CodeRabbit

• New Features

  • 카카오 지도 통합: 인터랙티브 맵, 마커 선택·하이라이트·정보창, SDK 런타임 로더
  • 검색·상세 흐름용 모의 API와 상세 샘플 데이터 제공

• Improvements

  • 검색 결과와 상세 정보 형식 통일(거리, 썸네일, 위치 포함)
  • 상세 모달의 상태관리(로딩·성공·오류) 및 재시도 UX 추가
  • 카테고리 레이블, 운영시간·휴게시간 표시 개선, 테이블 사진 노출 개선

[coderabbitai]

📝 Walkthrough

Walkthrough

카카오맵 SDK 동적 로드와 KakaoMap 컴포넌트 추가, DTO·어댑터·도메인 타입(RestaurantSummary/RestaurantDetail) 도입, 모의 데이터와 검색·상세 흐름을 SearchPage에 통합해 지도 마커 표시 및 상태 기반 상세 모달 흐름을 구현했습니다. (약 50단어)

Changes

Cohort / File(s)	Summary
도메인 타입 & 레이블 src/types/store.ts	도메인 타입 추가: RestaurantSummary, RestaurantDetail, BusinessHour, BreakTime, Category, Day 및 categoryLabel 매핑 상수 추가.
API DTOs src/api/dto/store.dto.ts	API DTO 타입 추가: ApiResponseDTO, StoreSearchItemDTO, StoreDetailDataDTO, 페이징·영업시간 관련 DTO 등 정의.
어댑터 (DTO → 도메인) src/api/adapters/store.adapter.ts	toRestaurantSummary / toRestaurantDetail 추가. 필드 직접 매핑 및 toBreakTime 헬퍼로 optional break 처리.
카카오 SDK 로더 src/lib/kakao.ts	환경변수(VITE_KAKAO_JS_KEY) 기반 싱글톤 방식 SDK 동적 로드 함수 loadKakaoMapSdk() 추가 및 global kakao 선언 보강.
지도 컴포넌트 src/components/map/KakaoMap.tsx	KakaoMap 컴포넌트 추가: SDK 로드, 마커/InfoWindow 생성·관리, 선택/하이라이트, center/selectedLevel 반응, 마운트/언마운트 안전 처리 및 로딩 상태 표시.
레스토랑 UI 컴포넌트 src/components/restaurant/... RestaurantCard.tsx, RestaurantList.tsx, RestaurantDetailModal.tsx	Card/List: 타입 변경(Restaurant → RestaurantSummary). DetailModal: 상태 기반 렌더링(idle/loading/success/error), 영업시간 포맷 유틸(DAY_LABEL/formatBusinessHours), mainImageUrl/tableImageUrls 등 새 필드 반영.
Mock 데이터 및 유틸 src/mock/stores.search.mock.ts, src/mock/stores.detail.mock.ts, src/mock/store.api.mock.ts	검색용 고정 배열과 상세 데이터 맵, searchMockStores(키워드·반경 필터, 정렬), 거리계산 유틸(haversineKm/toRad) 추가.
페이지 통합 src/pages/SearchPage.tsx	지오로케이션 기반 검색 흐름과 KakaoMap 연동, selectedStoreId 및 detailStatus/detailData/detailError 상태 추가, 상세 조회·재시도 로직 및 모달/맵/리스트 연동 구현.

Sequence Diagram(s)

sequenceDiagram
    actor User as "사용자"
    participant SearchPage as "SearchPage"
    participant MockAPI as "Mock Store API"
    participant KakaoMap as "KakaoMap 컴포넌트"
    participant KakaoSDK as "Kakao Maps SDK"
    participant DetailModal as "DetailModal"

    User->>SearchPage: 검색어 입력 / Enter
    SearchPage->>SearchPage: geolocation 확인 (coords)
    SearchPage->>MockAPI: searchMockStores(lat,lng,keyword)
    MockAPI-->>SearchPage: RestaurantSummary[] 반환
    SearchPage->>KakaoMap: markers={results}, selectedId
    KakaoMap->>KakaoSDK: loadKakaoMapSdk() 호출
    KakaoSDK-->>KakaoMap: SDK 준비완료
    KakaoMap->>KakaoMap: 마커 렌더링 및 InfoWindow 설정
    User->>KakaoMap: 마커 클릭
    KakaoMap->>SearchPage: onSelectMarker(store)
    SearchPage->>MockAPI: getMockStoreDetail(storeId)
    MockAPI-->>SearchPage: RestaurantDetail 반환
    SearchPage->>DetailModal: status=success, restaurant={detail}
    DetailModal-->>User: 상세 정보 표시

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• yooseolhee
• dew102938

Poem

🗺️ 카카오 한 줄 불러오니
마커들이 지도 위 춤추네.
클릭 한 번에 상세가 오고,
모의 데이터가 길을 비추네.
작은 타입들이 큰 흐름을 만드네. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	PR 제목이 변경사항의 핵심(카카오맵 연동 및 검색 결과 자동 이동)을 명확하고 간결하게 설명하고 있습니다.
Description check	✅ Passed	PR 설명이 템플릿을 잘 따르고, 개요, 작업내용, 변경사항, 체크리스트 등을 모두 작성하여 변경내용을 이해하기 쉽습니다.
Linked Issues check	✅ Passed	PR 변경사항이 #44 이슈의 핵심 요구사항(카카오맵 SDK 연동, 마커 표시, bounds 자동 조정)을 모두 구현하고 있습니다.
Out of Scope Changes check	✅ Passed	모든 변경사항이 카카오맵 연동 및 검색 기능 개선과 직접 관련되어 있으며, 이슈 범위를 벗어나는 변경은 없습니다.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/kakaoMapIntegration

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 8

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/pages/SearchPage.tsx (1)

12-50: ⚠️ Potential issue | 🟠 Major

검색 중 로딩 상태가 없고, 예약 버튼 클릭 시 조건부 렌더링으로 인한 침묵 실패

현재 구조에서 selectedLegacy를 찾지 못하면(ID 미존재 시) 예약 모달이 아무 피드백 없이 렌더링되지 않습니다. 또한 검색 결과 영역(251-257줄)에서 로딩 상태가 없어서 사용자가 검색 중인지 알 수 없어요.

개선 방안:

1. 검색 중 로딩 표시 추가
2. selectedLegacy가 null일 때는 에러 또는 경고 메시지 표시
3. 예약 데이터 소스 통합 검토: 현재 MOCK_RESTAURANTS(레거시)와 MOCK_STORE_DETAIL_BY_ID(신규)를 분리 관리 중인데, 모두 RestaurantDetail 기반으로 통일하거나 서로 동기화하는 방식 추천

예시 수정 (로딩 상태 + 에러 피드백)

// 검색 영역에 로딩 상태 추가
const [isSearching, setIsSearching] = useState(false);

const runSearch = async () => {
  setIsSearching(true);
  try {
    // ... 기존 검색 로직
  } finally {
    setIsSearching(false);
  }
};

// 렌더 부분
<div className="mt-6 w-full max-w-2xl mx-auto">
  {isSearching && <p className="text-blue-500">검색 중...</p>}
  {searchError && <p className="text-red-500">{searchError}</p>}
  {!isSearching && hasSearched && results.length === 0 && (
    <p className="text-gray-500">검색 결과가 없습니다</p>
  )}
  {hasSearched && !isSearching && (
    <RestaurantList restaurants={results} onSelect={handleSelectStore} />
  )}
</div>

// 예약 모달 렌더 방어
{detailOpen && detailData ? (
  <RestaurantDetailModal {...props} />
) : null}
{selectedLegacy ? (
  <ReservationModal {...props} />
) : null}

🤖 Fix all issues with AI agents

In `@src/api/adapters/store.adapter.ts`:
- Around line 11-24: toRestaurantSummary currently returns a RestaurantSummary
but omits the required location: Location field, causing TypeScript errors
because StoreSearchItemDTO lacks coords; update the adapter so
toRestaurantSummary populates location by either (A) reading lat/lng properties
from StoreSearchItemDTO if you add them (e.g., dto.latitude/dto.longitude →
location: { lat: dto.latitude, lng: dto.longitude }) or (B) calling your
geocoding helper before mapping (e.g., await geocodeAddress(dto.address) and set
location to the returned {lat,lng}); ensure the returned object from
toRestaurantSummary includes location: Location and adjust StoreSearchItemDTO or
the calling flow accordingly to provide coordinates.

In `@src/api/dto/store.dto.ts`:
- Around line 1-6: The ApiResponseDTO type incorrectly defines the payload field
as date: T; update the ApiResponseDTO type definition (symbol: ApiResponseDTO)
to use data: T instead of date so it matches the shape used elsewhere (e.g.,
ApiResponse<T>) and the real API responses; ensure any references in the same
file to the old property name are updated accordingly to avoid type mismatches
at compile/runtime.

In `@src/components/map/KakaoMap.tsx`:
- Around line 81-90: There are two duplicated useEffect blocks that both call
mapRef.current.setLevel and the map is never panned to the selected store;
consolidate into a single useEffect (watching selectedId and selectedLevel) that
first ensures kakao.maps and mapRef.current exist, then if selectedId exists
call mapRef.current.panTo(location) using the marker/position for that
selectedId, and only call mapRef.current.setLevel(selectedLevel) when
selectedLevel is defined (make setLevel conditional). Update/remove the other
duplicate useEffect so only this unified effect handles panning and zooming.
- Around line 91-123: The code injects store.name directly into the HTML string
passed to infoRef.current.setContent causing XSS risk; instead, build a DOM
element and assign the store.name via textContent to escape any markup, then
pass that element (not an HTML string) to infoRef.current.setContent and open it
with mapRef.current and marker; update the marker click handler in the useEffect
(where kakao.maps.event.addListener is set) to create the safe element, use
infoRef and setContent with the element, and keep onSelectMarker?.(store)
unchanged.

In `@src/components/restaurant/RestaurantDetailModal.tsx`:
- Around line 63-140: The modal's accessibility needs fixes: in
RestaurantDetailModal (the status === "idle" | "loading" and status === "error"
branches) add descriptive aria-labels to the icon-only close buttons (the
<button> that renders <X />) and to the overlay button (the absolute inset-0
bg-black/40 button) so screen readers can identify their purpose; also update
the modal container's aria-label (currently "식당 상세 로딩") to reflect the actual
state (e.g., "식당 상세 — 로딩" for loading and "식당 상세 — 오류" for error) and ensure the
same labelled close button appears in the success branch/header; use existing
props onOpenChange and onRetry to keep behavior unchanged and update the buttons
near the X icons, overlay button, and header X in the success branch
accordingly.

In `@src/lib/kakao.ts`:
- Around line 22-38: The loadingPromise currently stays rejected after a script
load failure and prevents future retries; modify the code that creates/assigns
loadingPromise (the Promise created in the module and used by loadKakaoMapSdk /
loadingPromise) so that whenever you reject (both in script.onerror and in the
onload branch where window.kakao?.maps?.load is missing) you first reset
loadingPromise to null/undefined before calling reject, and also reset it if you
successfully resolve or after cleanup to ensure subsequent calls create a new
Promise; update any places that read loadingPromise to allow recreation when it
is null/undefined.

In `@src/mock/store.api.mock.ts`:
- Around line 40-52: The computed distanceKm is only used for filtering/sorting
but not included in the returned records; update the return so each result
includes the calculated distanceKm. In the block that builds withDistance (using
haversineKm(center, r.location) and variables radiusKm, sort), map the final
output to return either a new object merging r with distanceKm (e.g., {...r,
distanceKm}) or otherwise set a distanceKm property on the record before
returning so the UI receives the actual computed distance.

In `@src/pages/SearchPage.tsx`:
- Around line 52-95: The race condition occurs when openDetail or retryDetail
fire concurrent async fetchStoreDetailMock calls and a slower earlier call
overwrites a later result; add a request-id guard: create a mutable request
counter (e.g., useRef requestIdRef) incremented at the start of openDetail and
retryDetail, capture the current id in a local variable before awaiting, and
only call setDetailData/setDetailStatus/setDetailError when the captured id
matches requestIdRef.current; reference the functions openDetail, retryDetail,
fetchStoreDetailMock and the state setters setDetailData, setDetailStatus,
setDetailError (and selectedStoreId) to ensure only the latest request updates
state.

🧹 Nitpick comments (1)

src/pages/SearchPage.tsx (1)

178-257: 검색 로딩/빈 결과 상태 표시 추가 권장

runSearch가 비동기인데 로딩 상태가 없어 연속 클릭/엔터 시 UX가 불안정할 수 있어요. isSearching 상태로 버튼 비활성화/로딩 표시, 그리고 hasSearched && results.length === 0일 때 빈 결과 메시지를 보여주면 좋습니다.

🔧 간단한 예시

+  const [isSearching, setIsSearching] = useState(false);

   const runSearch = async () => {
+    setIsSearching(true);
     setHasSearched(true);
     ...
     try {
       const items = await searchMockStores({ ... });
       setResults(items);
       ...
     } catch (e) {
       ...
     } finally {
+      setIsSearching(false);
     }
   };
...
-        {hasSearched ? (
-          <RestaurantList restaurants={results} onSelect={handleSelectStore} />
-        ) : null}
+        {hasSearched ? (
+          results.length === 0 && !searchError && !isSearching ? (
+            <p className="mt-2 text-sm text-gray-500">검색 결과가 없어요.</p>
+          ) : (
+            <RestaurantList restaurants={results} onSelect={handleSelectStore} />
+          )
+        ) : null}

As per coding guidelines, src/pages/**: 라우팅/레이아웃 영향, 로딩/에러/empty 상태 UX 확인.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/components/map/KakaoMap.tsx`:
- Around line 185-189: The component currently uses a direct check of
window.kakao?.maps in the render which can leave the "로딩 중" message visible
because React may not re-render when the SDK loads; update the KakaoMap
component to track SDK load with a state variable (e.g., isKakaoLoaded) and set
that state to true when the Kakao script's onload fires or when you detect
window.kakao.maps in a useEffect (or via the existing script load handler), then
replace the direct window.kakao?.maps check with the state (render loading UI
while isKakaoLoaded is false) so React updates correctly once the SDK finishes
loading.

🧹 Nitpick comments (5)

src/components/map/KakaoMap.tsx (2)

82-97: 중복된 useEffect로 인해 panTo와 setLevel이 두 번 호출됩니다

Lines 82-97과 Lines 132-156 두 effect 모두 selectedId 변경 시 panTo와 setLevel을 실행하고 있어서, 선택된 마커로 이동할 때 동일한 로직이 중복 실행돼요.

이전 리뷰에서 panTo 누락 문제는 수정됐지만, 두 effect를 하나로 통합하는 부분은 아직 반영되지 않은 것 같아요. Lines 132-156의 effect가 이미 zIndex 변경 + panTo + setLevel을 모두 처리하고 있으니, Lines 82-97의 effect는 제거해도 될 것 같습니다.

♻️ 중복 effect 제거 제안

-  useEffect(() => {
-    const kakao = window.kakao;
-    if (!kakao?.maps || !mapRef.current) return;
-
-    if (!selectedId) return;
-    const target = safeMarkers.find((m) => m.id === selectedId);
-    if (!target) return;
-
-    const next = new kakao.maps.LatLng(
-      target.location.lat,
-      target.location.lng,
-    );
-
-    mapRef.current.panTo(next);
-    if (selectedLevel) mapRef.current.setLevel(selectedLevel);
-  }, [selectedId, selectedLevel, safeMarkers]);
-
   //3. 마커 바뀌면 마커 재생성

Also applies to: 132-156

---

43-69: 초기화 effect의 의존성 배열 정리 제안

주석대로 "지도 최초 1회 생성"이 목적인데, [center.lat, center.lng, defaultLevel]이 의존성에 있어서 코드 의도가 모호해 보여요. 실제로는 mapRef.current 체크로 재생성을 막고 있지만요.

초기 center/level만 사용하고 이후 변경은 다른 effect에서 처리하니까, 빈 배열 []로 바꾸고 초기값을 ref나 첫 렌더 값으로 캡처하는 게 의도가 더 명확할 것 같아요.

src/components/restaurant/RestaurantDetailModal.tsx (1)

200-202: hourLines의 key로 텍스트 대신 인덱스나 요일 사용 권장

key={t}로 텍스트 내용을 키로 사용하고 있는데, 만약 두 요일이 같은 운영시간을 가지면 (예: "월: 09:00 - 18:00", "화: 09:00 - 18:00") 중복 키 경고가 발생할 수 있어요.

🔧 안정적인 key 사용

-                    {hourLines.map((t) => (
-                      <p key={t}>{t}</p>
+                    {hourLines.map((t, idx) => (
+                      <p key={idx}>{t}</p>
                     ))}

src/pages/SearchPage.tsx (2)

45-47: 상수와 유틸 함수를 컴포넌트 밖으로 이동 권장

FALLBACK_COORDS와 getCoords 함수가 컴포넌트 내부에 정의되어 있어서 매 렌더마다 재생성돼요. 컴포넌트 밖으로 이동하면 불필요한 재생성을 방지할 수 있습니다.

♻️ 상수/함수 이동 제안

+const FALLBACK_COORDS = { lat: 37.5665, lng: 126.978 };
+
+function getCoords(): Promise<{ lat: number; lng: number }> {
+  return new Promise((resolve) => {
+    if (!navigator.geolocation) {
+      resolve(FALLBACK_COORDS);
+      return;
+    }
+    navigator.geolocation.getCurrentPosition(
+      (pos) => resolve({ lat: pos.coords.latitude, lng: pos.coords.longitude }),
+      () => resolve(FALLBACK_COORDS),
+      { enableHighAccuracy: false, timeout: 5000 },
+    );
+  });
+}
+
 export default function SearchPage() {
   // ... 
-  const FALLBACK_COORDS = { lat: 37.5665, lng: 126.978 };
   // ...
-  function getCoords(): Promise<{ lat: number; lng: number }> { ... }

---

49-52: selectedLegacy는 현재 동작하지만 데이터 소스 분리로 인한 구조적 개선 필요

현재 MOCK_RESTAURANTS와 MOCK_STORE_SEARCH의 ID가 일치해서 즉각적인 문제는 없어요. 다만 코드가 레거시 Restaurant 타입(예약 모달용)과 새 RestaurantDetail 타입(상세 조회)을 섞어 쓰고 있고, 두 개의 별도 mock 데이터를 유지해야 하는 구조라 향후 유지보수 시 ID 불일치 위험이 있습니다.

실제 API 연동 시에는 MOCK_STORE_DETAIL_BY_ID의 RestaurantDetail에서 필요한 정보(영업시간, 좌석, 결제정책 등)를 추출해서 예약 모달에 전달하도록 통합하면, mock 데이터 중복을 없애고 타입도 일관성 있게 정리할 수 있을 것 같아요.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/components/map/KakaoMap.tsx`:
- Line 42: The initial state and a rendering check are wrong: change the
useState initializer to check window.kakao?.maps (not .map) by making sdkReady
initialize as !!window.kakao?.maps (symbol: useState and sdkReady), and fix any
places that mistakenly reference the setter setSdkReady in render logic (symbol:
setSdkReady) to instead use the state variable sdkReady; also ensure
loadKakaoMapSdk references window.kakao.maps consistently so the SDK ready flag
is set and the loading message can appear.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/components/map/KakaoMap.tsx`:
- Around line 180-193: The map container in KakaoMap.tsx currently lacks
accessibility attributes; update the root div (the one using containerRef and
className) to include a semantic role (e.g., role="region") and an accessible
label (accept a prop like ariaLabel with a sensible default such as "카카오 지도") so
screen readers can identify the map; tie loading state to ARIA by adding
aria-busy={!sdkReady} on the container and ensure the loading message uses an
aria-live="polite" (and/or role="status") so screen readers announce "카카오맵 로딩
중.." while sdkReady is false; keep prop naming clear (ariaLabel) and maintain
existing containerRef and className usage.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/components/map/KakaoMap.tsx`:
- Around line 44-72: The effect that loads the Kakao SDK (useEffect calling
loadKakaoMapSdk) currently only logs errors so the UI stays stuck showing
loading; add an error state (e.g., sdkError) alongside sdkReady, set sdkError
with the caught error message in the catch of init and ensure sdkReady is false,
and clear sdkError appropriately when a subsequent successful load occurs (e.g.,
before/after setSdkReady(true)). Update the component render to show a
user-facing error message when sdkError is set (use role="alert") and keep the
existing loading UI when !sdkReady && !sdkError; keep references to
containerRef, mapRef and infoRef untouched.