[S15P11A705-307] Home 지도 배경 레이어 재구성, SVG 마커 asset 적용, 줌·이동 범위 제한

[TrossYou]

관련 이슈

S15P11A705-307

작업 내용

Home 화면 지도 영역을 카드형 컨테이너에서 페이지 전체를 채우는 배경 레이어로 재구성하고, 마커를 SVG asset으로 교체한 뒤 지도 줌·이동 범위를 제한했다.

레이아웃 · 배경 지도

• HomeMapSection의 카드 스타일(라운드·테두리·그림자·고정 높이)을 제거하고, HomePage를 배경(지도)/오버레이/컨텐츠(히어로+검색 결과) 3개 레이어로 분리. 컨텐츠 레이어만 PAGE_CONTAINER_CLASS 폭을 유지하고 지도는 사이드바를 제외한 영역을 풀블리드로 채운다.
• 검색 결과 유무와 무관하게 지도가 항상 배경으로 떠 있도록 변경(기존엔 검색 결과가 있으면 지도가 사라지고 갤러리로 교체됐음).
• 지도가 항상 떠 있는 구조로 바뀌며 불필요해진 "이 지역에서 재검색" 버튼과 관련 상태(dragged, handleResearch)·bbox 재조회 로직(refetchWithBbox)을 제거.

마커

• 직접 그린 인라인 SVG 대신 src/assets/color-markers/의 SVG asset 20색을 <img>로 렌더링(CustomOverlay). asset 20개가 모두 같은 <filter id="shadow">를 써서 인라인으로 심으면 문서 전체에서 id가 충돌하기 때문에 <img>로 독립 렌더한다.
• getRecordMarkerAsset(collectionId)가 hashPaletteIndex로 01~19번을 배정하고, collectionId가 null인 Record는 20번 slate 고정(미분류). slate를 해시 팔레트에서 빼 미분류가 특정 Collection과 겹치지 않게 했다. 기존 getRecordMarkerColor.ts는 삭제.
• yAnchor를 1이 아니라 핀 끝 비율(68.32/76)로 지정 — asset 하단 여백은 내장 그림자 자리라 1이면 핀 끝이 좌표보다 약 8px 위에 찍힌다.

지도 줌 · 이동 범위 제한

• 카카오는 국내 위주로만 타일을 제공해서 그 밖으로 나가면 화면이 백지가 된다. kakao.maps.Map 생성 옵션 maxLevel: 13으로 최대 축소를 SDK에 직접 맡겼다 — 줌 버튼·휠·트랙패드 핀치·setLevel·setBounds 어느 경로든 예외 없이 적용된다.
• 레벨 13 근거(실측, 1200x900 기준): level 12는 위도폭 4.09°로 제주(33.1N)가 잘리고, level 13은 8.14°(32.2~40.4N)로 한반도 전체가 여유까지 들어온다.
• SDK에 이동 범위 제한 API가 없어 dragend·zoom_changed를 구독해 지도 중심이 KOREA_PAN_BOUNDS(위도 3339, 경도 124132)를 벗어나면 panTo로 가장 가까운 경계로 되돌린다. 마라도·독도·백령도가 모두 범위 안이다.
• 최대 축소 제한 때문에 화면에 못 담긴 기록이 있으면 좌측 하단에 "화면 밖 장소 N개" 배지를 띄운다. 클릭하면 제한 안에서 최대한 축소된 화면으로 이동한다(상한을 해제하는 것이 아니다).
• 제한이 걸릴 때 중심은 기록의 중앙값으로 옮긴다. fitBounds가 잡는 중심(전체 bounds의 한가운데)은 기록이 하나도 없는 지역일 수 있고, 평균은 멀리 떨어진 한 건에 끌려간다.

브랜드 컬러 · 히어로 오버레이

• tailwind.config.js에 snow-white: #FDFDFD 토큰 추가. xl 사이드바 배경을 본문(paper-white)보다 한 단계 흰 톤으로 구분.
• 지도 컨트롤·검색바·장소추가 버튼의 배경을 snow-white, 아이콘/텍스트를 pin-navy, hover를 log-mint로 통일. 비활성 상태는 opacity 대신 cursor-not-allowed와 색상 알파(bg-pin-navy/90)로 표현해 브랜드 색이 흐려지지 않게 했다.
• 히어로-지도 전환은 단일 오버레이 + mask-image(알파 그라데이션)로 구현. backdrop-filter는 요소 영역 안에서만 적용되고 경계에서 끊기므로, 고정 높이로 끝나는 레이어를 쓰면 tint가 투명해진 지점에도 "흐린 지도 / 선명한 지도"가 맞닿는 가로줄이 남는다. 마스크가 요소의 합성 결과 전체에 적용돼 블러와 흰 tint가 같은 곡선으로 사라진다.

버그 수정

• 줌·"내 주변" 버튼이 지도에 덮여 사라지던 문제 / 블러 오버레이가 전혀 보이지 않던 문제: 둘 다 같은 원인이었다. 카카오 SDK가 지도 컨테이너 안에 position:absolute; z-index:1~2인 내부 레이어를 7개 만드는데, 컨테이너가 stacking context가 아니라 그 z-index가 문서 최상위로 새어 나가 z-index:auto인 형제 요소를 전부 덮고 있었다. 컨테이너에 isolate를 줘 SDK 내부 z-index를 가뒀다.
• 마커가 0x0으로 찌그러지던 문제: Tailwind preflight의 img { max-width: 100%; height: auto }가 폭 0인 CustomOverlay 래퍼 안에서 0으로 계산됐다. max-width: none + 인라인 px 크기로 고정.
• React StrictMode(dev) 이중 effect 실행 시 카카오 Map 인스턴스가 중복 생성될 수 있던 레이스를 mapRef.current 가드로 차단.

API 계약

• GET /records/map 응답에 collectionId(number, nullable) 필드가 추가됨을 docs/api-contract.md에 반영(백엔드 배포 시점 대비 프론트 스키마는 optional로 받음).

변경 유형

• feat (기능)
• fix (버그)
• refactor / chore / docs / style / test

확인 방법

1. npm run dev로 / (Home) 접속. (지도 SDK 키는 http://localhost:5173만 등록돼 있어 다른 포트로 뜨면 domain mismatched로 거부된다.)
2. 히어로(제목~검색바) 뒤는 완전히 불투명하고, 그 아래로 지도가 단차 없이 서서히 선명해지는지 확인.
3. 지도 우측 하단 줌 +/- 버튼, 좌측 하단 "내 주변" 버튼이 지도에 덮이지 않고 항상 보이는지 확인.
4. 줌 제한: 줌아웃 버튼 연타 / 마우스 휠 / 트랙패드 핀치로 계속 축소해도 축척이 64km(level 13)에서 더 내려가지 않는지 확인.
5. 이동 제한: 지도를 바다 쪽으로 계속 드래그해도 손을 뗄 때마다 한반도 범위로 되돌아오는지 확인.
6. 마커가 Collection별로 다른 색으로 뜨는지, 핀 끝이 실제 좌표에 맞는지, 클릭 시 RecordDetailOverlay가 열리는지 확인.
7. 검색 실행 후 결과 카드가 지도 배경 위에 올바르게 겹쳐 보이는지 확인.

체크리스트

• 공개 화면(Feed, 타인 Shelf, Collection 상세)에 Context 원문·신원 정보를 노출하지 않았다
• member.id(내부 사용자 ID)를 URL·요청·응답에 사용하지 않았다 (진입점은 Collection id)
• Keyword는 label만 사용하고 code를 노출하지 않았다 — 이 PR은 Keyword를 다루지 않는다
• Context 수정 후 새 contextId로 쿼리 키·URL·선택 상태를 교체했다 — 이 PR은 Context를 수정하지 않는다
• keywords: [] 등 빈 결과를 오류로 처리하지 않았고 로딩·오류·401 상태를 처리했다 (items: []는 "저장된 기록이 없습니다" 안내로 처리, 401 재요청 루프 방지를 위해 retry: false)
• docs/conventions.md(용어·any·컴포넌트 직접 API 호출 금지)를 지켰다 (any 없음, 컴포넌트는 useRecordMapMarkersQuery만 호출)

---

lint / tsc -b / vitest(12 files, 70 tests) 모두 통과. 줌·이동 제한과 마커 색상 매핑은 Playwright로 실제 브라우저에서 확인했고, 순수 로직은 recordMapViewportLimits.test.ts로 고정했다.