상태 책임을 분리해 웨딩홀 지도 화면 구현

사용자가 지도를 둘러보는 행동과 검색 결과를 갱신하는 행동을 분리했습니다. 현재 보고 있는 영역과 검색에 적용한 영역을 따로 관리해 핀, 목록, 상세 정보가 필요한 시점에만 갱신되도록 구현했습니다.

배경과 과제

배경

리스트 중심의 웨딩홀 탐색을 지도와 목록이 함께 움직이는 화면으로 확장했습니다. 사용자는 지도를 자유롭게 둘러보면서 원하는 시점에만 검색 결과를 갱신할 수 있어야 했습니다.

핵심 과제

지도가 멈출 때마다 검색 결과를 다시 불러오면 사용자가 둘러보기만 해도 기존 결과와 필터가 바뀝니다. 둘러보기와 검색 결과 갱신을 다른 행동으로 다뤄야 했습니다.

설계 시 고려한 점

  • 지도 이동 완료 이벤트만으로는 탐색을 위한 사용자 이동과 상세 카드를 보여주기 위한 자동 이동을 구분할 수 없었습니다.
  • 핀, 목록, 상세 정보는 갱신 조건과 데이터 형태가 달라 하나의 요청이나 저장소로 묶으면 서로 불필요하게 갱신됐습니다.
  • 모바일에서 카드 노출을 위해 지도를 자동으로 옮긴 동작까지 새 검색으로 판단하면 검색 기준과 URL이 잘못 바뀔 수 있었습니다.

운영 제약

  • 카카오 지도 SDK는 브라우저에서 생성되는 외부 객체이므로 서버 렌더링 경로와 전역 직렬화 상태에서 분리해야 했습니다.
  • 같은 화면이 일반 모바일 브라우저와 앱 WebView에서 동작해야 했고 바텀시트와 상세 카드가 가리는 영역도 함께 고려해야 했습니다.

화면 상태, 서버 데이터, 지도 객체의 역할

지도 화면에서 바뀌는 세 종류의 데이터

사용자가 바꾸는 값, 서버에서 받은 값, 카카오 지도 객체는 변경되는 시점과 관리 방법이 달라 각각 분리했습니다.

  1. Zustand
    사용자가 바꾸는 화면 상태

    지도 이동, 필터, 웨딩홀 선택과 바텀시트 전환으로 변경되는 값

    • 현재 영역 / 검색 영역
    • 바텀시트와 선택 웨딩홀
    • 필터, 정렬, 검색 기준 변경 여부
  2. React Query
    서버에서 받은 데이터

    로딩과 실패, 다시 불러오기, 목록 페이지 누적이 필요한 값

    • 지도 핀
    • 웨딩홀 목록
    • 선택한 웨딩홀 상세
  3. 지도 컴포넌트
    카카오 지도 객체

    브라우저에서 지도를 생성한 뒤 이동과 줌 명령을 직접 수행하는 객체

    • 지도 객체
    • 이동 완료 이벤트
    • 이동, 줌, 보이는 영역
상태 연결 흐름

지도 이동, 사용자 조작과 서버 응답을 필요한 위치에서 연결

한쪽의 변화가 다른 모든 상태를 바로 바꾸지 않도록 역할이 달라지는 지점에서 필요한 값만 전달했습니다.

지도 이동, 사용자 조작과 서버 응답을 필요한 위치에서 연결카카오 지도의 이동 완료가 현재 영역을 바꾸고, 확정이나 줌 변경 때만 검색 영역이 바뀌어 서버 조회로 이어지며, 응답으로 그린 핀과 카드를 선택하면 다시 지도 위치를 조정하는 순환 구조지도 컴포넌트ZustandReact Query이동 완료 시 저장확정·줌 변경 시검색 조건 확정화면에 표시지도 위치 조정카카오 지도 객체이동·줌·보이는 영역현재 영역live viewport검색 영역·필터applied viewport서버 조회핀·목록·상세핀·목록·카드핀 선택·카드 노출
지도 이동, 사용자 조작과 서버 응답을 필요한 위치에서 연결카카오 지도의 이동 완료가 현재 영역을 바꾸고, 확정이나 줌 변경 때만 검색 영역이 바뀌어 서버 조회로 이어지며, 응답으로 그린 핀과 카드를 선택하면 다시 지도 위치를 조정하는 순환 구조지도 컴포넌트ZustandReact Query이동 완료시 저장확정·줌변경 시검색 조건확정화면에 표시지도 위치조정카카오 지도 객체이동·줌·보이는 영역현재 영역live viewport검색 영역·필터applied viewport서버 조회핀·목록·상세핀·목록·카드핀 선택·카드 노출

구현 결과

사용자
지도를 자유롭게 둘러보면서 기존 결과와 필터를 유지하고 원하는 영역에서만 검색 결과를 갱신할 수 있게 했습니다.
개발
핀, 목록, 상세 정보의 갱신 조건을 분리해 불필요한 연쇄 조회를 막고 지도 계산 로직을 단위 테스트할 수 있게 했습니다.

핵심 구현과 판단

1. 지도 탐색 상태와 서버 검색 기준을 분리

현재 보고 있는 영역과 서버 검색에 적용한 영역을 나눠 지도를 움직일 때는 현재 영역만 바뀌도록 했습니다.

  • 필터, 선택한 웨딩홀과 바텀시트는 Zustand가 관리하고 서버 응답은 저장하지 않았습니다.
  • 카카오 지도 객체는 생성한 React 컴포넌트 내부에 유지했습니다.

2. 핀, 목록, 상세 정보를 필요한 시점에 조회

지도 핀, 목록, 상세 정보는 갱신되는 조건이 서로 달랐습니다. 핀은 검색 영역이 바뀔 때, 목록은 사용자가 아래로 스크롤할 때, 상세 정보는 웨딩홀을 선택했을 때 조회했습니다. 각 요청의 로딩과 캐시도 서로 영향을 주지 않도록 분리했습니다.

  • 핀과 목록은 확정된 검색 영역과 필터를 함께 사용하지만 별도의 Query Key로 캐시했습니다.
  • 목록 페이지를 이어 붙이고 다음 페이지를 판단하는 일은 React Query의 무한 조회 기능에 맡겼습니다.
  • 상세 정보는 선택한 웨딩홀이 있을 때만 조회했습니다. 선택한 ID는 Zustand가, 서버 응답은 React Query가 관리했습니다.

3. 사용자 이동과 화면 보정을 위한 자동 이동을 구분

카카오 지도 객체는 생성한 컴포넌트 안에 보관하고 다른 컴포넌트에는 이동과 줌 명령만 제공했습니다. 상세 카드 때문에 지도를 자동으로 옮긴 경우에는 다음 이동 완료 이벤트를 사용자 행동과 구분했습니다.

  • 지도 명령 인터페이스(Map Controller)는 이동과 줌을 담당하지만 핀 데이터는 저장하지 않습니다.
  • 별도 핀 컴포넌트가 서버 데이터와 선택한 웨딩홀을 읽어 지도 위 핀을 만들고 화면에서 사라질 때 지도에서 제거합니다.

4. 지도 없이 검증할 수 있는 계산과 화면 흐름을 분리

현재 영역이 기존 검색 범위를 벗어났는지 판단하는 계산, 줌 단계 변환, 자동 줌, 핀 우선순위와 URL 변환을 카카오 지도 없이 실행할 수 있는 함수로 만들었습니다. Vitest는 계산과 상태 변경을, Playwright는 필터와 바텀시트의 사용자 흐름을 검증하도록 나눴습니다.

  • 화면에서는 확정된 검색 영역과 필터로 요청을 만들고, 서버 데이터와 선택 상태를 핀, 목록, 상세 카드에 연결했습니다.
  • 핀 우선순위는 방문예약, 위시, 즉시계약, 일반 순으로 결정하고 같은 유형에서는 추천 순서를 사용했습니다.
  • 실제 카카오 지도를 포함한 브라우저 시나리오는 외부 환경과 인증 상태의 영향을 받으므로 계산 테스트와 분리했습니다.
코드 변경핵심 기능 구현 코드1. 지도 탐색 상태와 서버 검색 기준을 분리 · 2. 핀, 목록, 상세 정보를 필요한 시점에 조회 · 3. 사용자 이동과 화면 보정을 위한 자동 이동을 구분코드 변경 보기

서로 다른 상태를 연결한 방법

상태를 나누는 것만으로는 화면이 동작하지 않습니다. 지도 이동, 사용자 조작과 서버 응답이 만나는 위치를 다음과 같이 제한했습니다.

카카오 지도 이동이 화면 상태를 바꿀 때

처리
지도 이동이 끝나면 현재 경계와 줌 단계를 일반 객체로 변환해 Zustand에 저장했습니다.
결과
카카오 지도 객체를 전역 상태에 넣지 않고도 현재 위치를 핀, 목록과 검색 기준 변경 안내에서 함께 사용할 수 있습니다.

사용자가 서버 검색 영역을 확정할 때

처리
현재 보고 있는 영역이 아니라 사용자의 선택이나 줌 변경으로 확정된 영역과 필터만 핀과 목록 요청에 사용했습니다.
결과
지도를 둘러보는 행동과 서버 검색 결과를 바꾸는 행동이 같은 시점에 발생하지 않습니다.

상세 카드에 가린 지도를 자동으로 옮길 때

처리
선택한 핀과 카드 높이를 기준으로 지도 위치를 조정하고 다음 이동 완료 이벤트를 자동 이동으로 표시했습니다.
결과
자동 중앙 정렬이 검색 범위와 URL을 의도치 않게 변경하지 않습니다.
추가 예외 처리 1개

서버에서 받은 데이터를 지도 핀으로 그릴 때

처리
전용 핀 컴포넌트가 서버 데이터와 선택한 웨딩홀을 조합해 지도 핀을 만들고 변경 시 기존 핀을 제거했습니다.
결과
지도 이동 코드가 핀 데이터와 표시 규칙을 함께 관리하지 않아도 선택 상태를 표현할 수 있습니다.

현재 구조와 다음 개선

지도 객체는 컴포넌트 내부에 두었지만 핀 컴포넌트에는 원본 객체를 전달합니다. 지도 화면이 늘어난다면 핀 전용 인터페이스와 SDK 이벤트 어댑터를 분리해 의존 범위를 더 줄일 수 있습니다.

핀 데이터가 바뀔 때 기존 핀을 모두 다시 생성합니다. 핀 수가 늘어나면 ID를 기준으로 변경된 핀만 갱신하는 방식이 필요합니다.

검색 영역별 캐시 크기와 늦게 도착한 응답은 추가 검증이 필요합니다. 실제 지도에 의존하는 브라우저 테스트를 안정화하려면 통제 가능한 가짜 지도 환경도 필요합니다.

ASK ME기준 ·이 글 · 상태 책임을 분리해 웨딩홀 지도 화면 구현

프로젝트, 담당 범위, 기술적 판단을 물어보세요.

추천 질문

포트폴리오에 작성된 내용으로만 답합니다