⚙️[기능추가][지도] Google Maps 실제 지도 연동 + 핵심 로직 + 실시간 동기화 통합 #7
Description
📝 현재 문제점
- MockMapView(목업 지도)만 표시되며 실제 Google Maps가 연동되지 않음
- 마커 좌표 기반 중심점/TSP/거리 계산 로직이 없음 (백엔드 이관 예정)
- 장소 검색/자동완성 기능이 동작하지 않음
- 좌표 → 주소 변환(역지오코딩)이 구현되지 않음
- 실시간 동기화(Polling), GPS 위치 감지, PWA 설치 프롬프트가 미완성
🛠️ 해결 방안
Phase 1: Google Maps 기본 연동 (MVP)
사용 API: Maps JavaScript API, Places API (Autocomplete), Geocoding API
환경변수: GOOGLE_MAPS_API_KEY (Vite proxy 또는 서버사이드 주입)
@vis.gl/react-google-maps패키지 활용APIProvider로 앱 전체 래핑- MockMapView → 실제 Google Maps 기반
MapView컴포넌트 교체 AdvancedMarker+Pin으로 커스텀 마커 (내 마커: sub, 타인: primary, 중심점: center)- Places Autocomplete → SearchBar 장소 검색 연동
- Geocoding → 마커 위치 확정 시 주소 표시, 중심점 주소 표시
Phase 2: 핵심 계산 로직 (백엔드 연동)
결정: 계산 로직은 백엔드(Spring Boot) 책임. 프론트는 결과 표시만.
GET /api/rooms/{roomId}/result응답의RoomResult(centroid, route, distances) 표시- 중심점 마커 + 주소 표시
- TSP 최단거리 경로 Polyline 표시
- 참여자별 중심점까지 거리 표시
Phase 3: 실시간 동기화 + GPS + PWA
useRoom훅: 3초 Polling으로 방 데이터 실시간 갱신useGeolocation훅: 브라우저 Geolocation API + "내 위치" 버튼usePWA훅: beforeinstallprompt 이벤트 캐치, 조건부 배너 표시- clipboard 유틸: navigator.clipboard + textarea 폴백
Phase 4: 고급 지도 기능
사용 API: Directions API, Places API (Nearby Search)
- Directions API: 자동차 실제 도로 경로 거리/폴리라인 (Haversine 직선거리 대체)
- Places Nearby Search: 중심점 주변 식당/카페/지하철역 POI 추천
⚙️ 작업 내용
Phase 1: Google Maps 기본 연동
-
@vis.gl/react-google-maps설치 및 APIProvider 설정 - 환경변수
GOOGLE_MAPS_API_KEY설정 (.env.local) - MapView 컴포넌트 구현 (Google Maps 기반, MockMapView 교체)
- AdvancedMarker + Pin 커스텀 마커 구현
- Geocoding 훅 구현 (좌표 → 주소 변환)
- LocationConfirmSheet에 역지오코딩 주소 표시
- SearchBar에 Places Autocomplete 연동
Phase 2: 백엔드 연동
- (백엔드) Haversine, Centroid, TSP 계산 로직 구현
- (백엔드)
GET /api/rooms/{roomId}/resultAPI 구현 - (프론트) mock API → HTTP API 전환 (api.http.ts 구현)
- (프론트) ResultPanel에 계산 결과 표시
- (프론트) 중심점 마커 + Polyline 경로 표시
Phase 3: 실시간 동기화 + GPS + PWA
- useRoom 훅 (3초 Polling)
- useGeolocation 훅 + "내 위치" 버튼
- usePWA 훅 + PWAInstallBanner 실제 연결
- clipboard 유틸 구현
Phase 4: 고급 지도 기능
- Directions API 연동 (도로 기반 거리/경로)
- Places Nearby Search 연동 (주변 시설 추천)
📋 참고 문서
- Google API 설계:
docs/plans/2026-03-08-google-api-design.md - 시스템 아키텍처:
docs/01_ARCHITECTURE.md - PRD:
docs/PRD.md
🔗 통합된 기존 이슈
- 20260228 #3 home page 및 방 생성 플로우 구현 #4 핵심 계산 로직 (중심점, TSP, Haversine) → Phase 2
- ⚙️[기능추가][RoomPage] RoomPage UI 레이아웃 구현 (목업 지도 + 패널 + 모달) #5 Google Maps 지도 연동 → Phase 1
- 20260228 #5 room page UI 레이아웃 구현 목업 지도 패널 모달 #6 실시간 동기화, GPS, PWA → Phase 3
🙋♂️ 담당자
- 백엔드: 이름
- 프론트엔드: 이름
- 디자인: 이름