지도 뷰포트 기반 실시간 숙소 검색 구현

지도 뷰포트 기반 실시간 숙소 검색 구현

📋 개요

사용자가 지도를 이동하거나 확대/축소할 때, 현재 화면에 보이는 영역(뷰포트) 내의 숙소만 실시간으로 검색하여 표시하는 기능입니다.

Airbnb와 같은 지도 기반 검색 서비스에서 널리 사용되는 패턴으로, 사용자가 관심 있는 지역의 숙소를 효율적으로 탐색할 수 있습니다.

---

🎯 핵심 개념

1. 뷰포트(Viewport)란?

뷰포트는 지도에서 현재 화면에 보이는 사각형 영역을 의미합니다.

          북(North)
            ↑
            |
서(West) ←--+--→ 동(East)
            |
            ↓
          남(South)

┌─────────────────┐ ← NE (북동쪽) 모서리
│                 │   좌표: (neLat, neLng)
│   지도 화면     │
│   (뷰포트)      │
│                 │
└─────────────────┘ ← SW (남서쪽) 모서리
↑                    좌표: (swLat, swLng)

2. Bounds (경계) 좌표

뷰포트는 두 개의 모서리 좌표로 완벽하게 정의됩니다:

• SW (SouthWest): 남서쪽 모서리 - 왼쪽 아래 끝
  • swLat: 남서쪽 위도 (가장 낮은 위도)
  • swLng: 남서쪽 경도 (가장 낮은 경도)
• NE (NorthEast): 북동쪽 모서리 - 오른쪽 위 끝
  • neLat: 북동쪽 위도 (가장 높은 위도)
  • neLng: 북동쪽 경도 (가장 높은 경도)

예시: 서울 시내 뷰포트

{
  swLat: 37.50,  // 남쪽 경계
  swLng: 126.95, // 서쪽 경계
  neLat: 37.60,  // 북쪽 경계
  neLng: 127.05  // 동쪽 경계
}

---

🏗️ 아키텍처

전체 흐름도

┌─────────────────────────────────────────────────────────────┐
│                         사용자 액션                          │
│            (지도 이동, 확대/축소, 드래그)                    │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    MapView 컴포넌트                          │
│  - 카카오맵 API에서 bounds 정보 획득                        │
│  - bounds_changed 이벤트 리스닝                             │
│  - 디바운싱 없이 즉시 부모 컴포넌트로 전달                  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ onMapBoundsChange({ swLat, swLng, neLat, neLng })
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                SearchResultPage 컴포넌트                     │
│  - handleMapBoundsChange에서 bounds 수신                    │
│  - 500ms 디바운싱 적용 (과도한 API 호출 방지)               │
│  - SearchParams 구성 (기존 필터 + bounds)                   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ searchAccommodations(params)
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  Backend API Server                          │
│  GET /accommodations?swLat=...&swLng=...&neLat=...&neLng=...│
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              AccommodationService (NestJS)                   │
│  - bounds 파라미터 우선 검사                                │
│  - SQL WHERE 절로 사각형 영역 필터링                        │
│  - 뷰포트 내 숙소만 반환                                    │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ { items: [...], total, page, ... }
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    화면에 결과 표시                          │
│  - 좌측: 숙소 리스트 업데이트                               │
│  - 우측: 지도 마커 업데이트                                 │
└─────────────────────────────────────────────────────────────┘

---

💻 구현 상세

1. 프론트엔드: MapView 컴포넌트

역할

• 카카오맵 API에서 뷰포트 bounds 정보 추출
• 지도 이동/줌 변경 시 부모 컴포넌트로 bounds 전달

핵심 코드

// frontend/src/components/map/MapView.tsx

// bounds_changed 이벤트 리스닝
useEffect(() => {
  if (!map) return;

  const updateBounds = () => {
    // 카카오맵에서 현재 뷰포트의 경계 좌표 획득
    const mapBounds = map.getBounds();
    const sw = mapBounds.getSouthWest(); // 남서쪽 모서리
    const ne = mapBounds.getNorthEast(); // 북동쪽 모서리

    const newBounds = {
      swLat: sw.getLat(),  // 남서쪽 위도
      swLng: sw.getLng(),  // 남서쪽 경도
      neLat: ne.getLat(),  // 북동쪽 위도
      neLng: ne.getLng(),  // 북동쪽 경도
    };

    // 부모 컴포넌트로 bounds 전달
    onMapBoundsChange?.(newBounds);
  };

  // bounds_changed 이벤트 등록
  // (zoom_changed, dragend 발생 시에도 자동으로 트리거됨)
  kakao.maps.event.addListener(map, 'bounds_changed', updateBounds);

  return () => {
    kakao.maps.event.removeListener(map, 'bounds_changed', updateBounds);
  };
}, [map, onMapBoundsChange]);

주요 포인트

1. getBounds() 메서드: 카카오맵 API가 제공하는 현재 뷰포트 정보
2. bounds_changed 이벤트: 지도 이동/줌 변경 시 자동 발생
3. 즉시 전달: MapView에서는 디바운싱 없이 즉시 부모로 전달

---

2. 프론트엔드: SearchResultPage 컴포넌트

역할

• MapView로부터 bounds 수신
• 디바운싱 적용하여 과도한 API 호출 방지
• 기존 검색 필터 + bounds를 결합하여 API 호출

핵심 코드

// frontend/src/pages/SearchResultPage.tsx

const handleMapBoundsChange = useCallback(
  (bounds: {
    swLat: number;
    swLng: number;
    neLat: number;
    neLng: number;
  }) => {
    // 기존 타이머 취소
    if (debounceTimerRef.current) {
      clearTimeout(debounceTimerRef.current);
    }

    // 500ms 후에 API 호출 (디바운싱)
    debounceTimerRef.current = window.setTimeout(async () => {
      setIsLoading(true);
      setError(null);

      try {
        // 기존 검색 파라미터 유지 + bounds 추가
        const params = parseSearchParams();
        params.swLat = bounds.swLat;
        params.swLng = bounds.swLng;
        params.neLat = bounds.neLat;
        params.neLng = bounds.neLng;

        const response = await searchAccommodations(params);
        const convertedData = response.items.map(convertToAccommodation);
        setAccommodations(convertedData);
      } catch (err) {
        console.error('지도 이동 중 숙소 검색 오류:', err);
      } finally {
        setIsLoading(false);
      }
    }, 500);
  },
  [parseSearchParams]
);

주요 포인트

1. 디바운싱 (500ms): 사용자가 지도를 계속 드래그하는 동안 API 호출 방지
2. 기존 필터 유지: 날짜, 가격, 인원 등 기존 검색 조건 유지
3. 에러 처리: 에러 발생 시 기존 목록 유지 (UX 향상)

---

3. 백엔드: DTO (Data Transfer Object)

역할

• API 요청 파라미터 정의 및 유효성 검증

핵심 코드

// backend/src/modules/accommodation/dto/search-accommodation.dto.ts

export class SearchAccommodationDto {
  // 지도 뷰포트 기반 검색 (사각형 영역)
  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  swLat?: number; // 남서쪽 위도

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  swLng?: number; // 남서쪽 경도

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  neLat?: number; // 북동쪽 위도

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  neLng?: number; // 북동쪽 경도

  // ... 기타 필터 (날짜, 가격, 인원 등)
}

---

4. 백엔드: Service 레이어

역할

• bounds 기반 SQL 쿼리 생성
• 뷰포트 내 숙소만 필터링

핵심 코드

// backend/src/modules/accommodation/accommodation.service.ts

async findAll(searchDto: SearchAccommodationDto) {
  const { swLat, swLng, neLat, neLng } = searchDto;

  const query = this.accommodationRepository
    .createQueryBuilder('accommodation')
    .leftJoinAndSelect('accommodation.amenities', 'amenity')
    .leftJoinAndSelect('accommodation.host', 'host')
    .leftJoinAndSelect('accommodation.reviews', 'review');

  // 지도 기반 검색
  // 1. bounds가 있으면 뷰포트 기반 사각형 검색
  // 2. bounds가 없으면 중심점 + 반경 기반 검색 (하위 호환성)
  const hasBounds =
    swLat !== undefined &&
    swLng !== undefined &&
    neLat !== undefined &&
    neLng !== undefined;

  if (hasBounds) {
    // 뷰포트 기반 사각형 검색
    query
      .andWhere('accommodation.latitude BETWEEN :swLat AND :neLat', {
        swLat,
        neLat,
      })
      .andWhere('accommodation.longitude BETWEEN :swLng AND :neLng', {
        swLng,
        neLng,
      });
  } else {
    // 중심점 + 반경 기반 검색 (기본값: 서울 중심 10km)
    // ... 기존 로직
  }

  // ... 기타 필터 (가격, 인원, 예약 날짜 등)

  const [items, total] = await query.getManyAndCount();
  return { items, total, page, limit, totalPages };
}

생성되는 SQL 쿼리 예시

SELECT accommodation.*, amenity.*, host.*, review.*
FROM accommodations accommodation
LEFT JOIN accommodation_amenities ON ...
LEFT JOIN amenities amenity ON ...
LEFT JOIN users host ON ...
LEFT JOIN reviews review ON ...
WHERE accommodation.latitude BETWEEN 37.50 AND 37.60
  AND accommodation.longitude BETWEEN 126.95 AND 127.05
  -- 기타 필터 조건들
ORDER BY ...
LIMIT 20 OFFSET 0;

---

🔄 데이터 흐름 예시

시나리오: 사용자가 지도를 강남역에서 홍대로 드래그

1. 사용자 액션
2. 지도를 강남역 → 홍대로 드래그
3. MapView: bounds 추출
4. { swLat: 37.54, // 홍대 남쪽 swLng: 126.91, // 홍대 서쪽 neLat: 37.56, // 홍대 북쪽 neLng: 126.93 // 홍대 동쪽 }
5. SearchResultPage: 디바운싱
6. 사용자가 드래그를 멈춘 후 500ms 대기 → API 호출 준비
7. API 요청
8. GET /accommodations?swLat=37.54&swLng=126.91&neLat=37.56&neLng=126.93 &checkIn=2024-01-01&checkOut=2024-01-02 &minPrice=50000&maxPrice=200000
9. 백엔드: SQL 실행
10. WHERE latitude BETWEEN 37.54 AND 37.56 AND longitude BETWEEN 126.91 AND 126.93 AND price_per_night BETWEEN 50000 AND 200000 -- 예약 가능 여부 체크 등
11. 응답
12. { "items": [ { "id": 123, "title": "홍대 근처 아늑한 숙소", "latitude": 37.55, "longitude": 126.92, "price_per_night": 80000, ... }, // ... 홍대 지역 숙소들만 ], "total": 45, "page": 1, "limit": 20 }
13. 화면 업데이트
14. - 좌측 리스트: 홍대 지역 숙소 45개 표시 - 우측 지도: 해당 숙소들의 마커만 표시

---

⚡ 성능 최적화

1. 디바운싱 (Debouncing)

문제: 사용자가 지도를 빠르게 드래그하면 초당 수십 번의 API 호출 발생

해결책: 500ms 디바운싱 적용

// 마지막 이벤트 발생 후 500ms 동안 추가 이벤트가 없으면 API 호출
debounceTimerRef.current = window.setTimeout(async () => {
  // API 호출
}, 500);

효과:

• API 호출 횟수: 초당 30회 → 2초에 1회
• 서버 부하 대폭 감소
• 네트워크 트래픽 절감

2. SQL 인덱스

필수 인덱스:

-- 위도/경도에 공간 인덱스 생성
CREATE INDEX idx_accommodation_location
ON accommodations(latitude, longitude);

-- 또는 복합 인덱스
CREATE INDEX idx_accommodation_lat ON accommodations(latitude);
CREATE INDEX idx_accommodation_lng ON accommodations(longitude);

효과:

• 쿼리 실행 시간: 1000ms → 10ms (예시)
• BETWEEN 조건 검색 최적화

3. 페이지네이션

기본 설정: 한 번에 20개씩만 조회

limit?: number = 20;

효과:

• 응답 크기 감소
• 초기 로딩 속도 향상

---

🎨 사용자 경험 (UX)

1. 로딩 상태 표시

{isLoading && (
  <div className="flex flex-col gap-4">
    {Array.from({ length: 5 }).map((_, index) => (
      <AccommodationCardSkeleton key={index} />
    ))}
  </div>
)}

효과:

• 사용자는 데이터가 로딩 중임을 명확히 인지
• 스켈레톤 UI로 레이아웃 변화 최소화

2. 에러 처리

catch (err) {
  console.error('지도 이동 중 숙소 검색 오류:', err);
  // 에러 발생 시 기존 목록 유지 (사용자 경험 향상)
}

효과:

• 네트워크 오류 시에도 기존 데이터 유지
• 사용자 경험 중단 방지

---

🔍 대안: 원형 반경 검색 vs 사각형 뷰포트 검색

원형 반경 검색 (Haversine)

// 중심점 + 반경으로 검색
{
  lat: 37.5665,
  lng: 126.978,
  radius: 5  // 5km 반경
}

장점:

• 거리 기반 정확한 검색
• 중심점에서 일정 거리 이내 보장

단점:

• 화면에 보이지 않는 숙소도 포함될 수 있음
• 지도 모양과 불일치 (지도는 사각형, 검색은 원형)

사각형 뷰포트 검색 (현재 구현) ✅

// 현재 화면 영역으로 검색
{
  swLat: 37.50,
  swLng: 126.95,
  neLat: 37.60,
  neLng: 127.05
}

장점:

• 정확성: 화면에 보이는 영역과 검색 결과가 정확히 일치
• 성능: SQL BETWEEN 쿼리로 빠른 검색
• 직관성: 사용자가 보는 것 = 검색 결과

단점:

• 거리 기반 정렬은 별도 계산 필요

---

📊 테스트 시나리오

1. 기본 동작 테스트

1. 지도를 서울 시청으로 이동
2. 500ms 후 API 호출 확인
3. 서울 시청 주변 숙소만 표시되는지 확인

2. 디바운싱 테스트

1. 지도를 빠르게 여러 번 드래그
2. 마지막 드래그 종료 후 500ms에만 API 호출되는지 확인
3. 중간 드래그들은 API 호출 안 되는지 확인

3. 필터 유지 테스트

1. 날짜, 가격, 인원 필터 설정
2. 지도 이동
3. 설정한 필터가 유지되면서 지역만 변경되는지 확인

4. 에러 처리 테스트

1. 네트워크 연결 끊기
2. 지도 이동
3. 기존 숙소 목록이 유지되는지 확인

---

🚀 향후 개선 방안

1. 무한 스크롤

// 현재: 페이지네이션
// 개선: 스크롤 시 자동으로 다음 페이지 로드

2. 클러스터링

// 줌 아웃 시 개별 마커 대신 클러스터 표시
// 예: "강남구 (25개)"

3. 캐싱

// 이미 조회한 영역의 데이터를 캐시
// 같은 영역으로 돌아갈 때 API 재호출 방지

4. WebSocket 실시간 업데이트

// 새로운 숙소 등록 시 실시간 마커 추가
// 예약 완료 시 실시간 마커 제거

---

📚 참고 자료

• Kakao Maps JavaScript API 문서
• TypeORM QueryBuilder 문서
• React 디바운싱 패턴
• Airbnb Engineering Blog

---

🏁 결론

지도 뷰포트 기반 실시간 검색은 다음과 같은 특징을 가집니다.

✅ 정확성: 화면에 보이는 영역 = 검색 결과
✅ 성능: SQL 인덱스 + 디바운싱으로 최적화
✅ 사용자 경험: 스켈레톤 UI + 에러 처리로 안정적인 UX
✅ 확장성: 추가 필터와 쉽게 결합 가능

이 구조는 지도 기반 검색 서비스의 표준 패턴이며, 대규모 트래픽에서도 안정적으로 동작합니다.