문서 관리

작성일	2025-05-30
버전	1.1
작성자	suzy.kang (강수지)
검토자	kevin
상태	완료

변경 이력

버전	날짜	작성자	검토자	변경내용
1.0	2025-04-25	suzy	kevin	초안
1.1	2025-05-30	suzy	kevin	MVP 개발 이후 문서 동기화

---

배경 (Background)

프로젝트 목표 (Objective)

• 사용자 위치 기반 장소 검색 및 추천 기능 제공
• 직관적인 지도 인터페이스로 장소 탐색 경험 개선
• 장소 정보의 효율적인 표시 및 북마크 기능 구현
• 바텀시트를 활용한 모바일 최적화 UX 제공

목표가 아닌 것 (Non-goals)

• 실시간 장소 정보 업데이트
• 장소 리뷰 및 평점 시스템
• 장소 예약 시스템

설계 및 기술 자료 (Architecture and Technical Documentation)

아키텍처 개요 (Architecture Overview)

프레임워크/라이브러리

• Next.js (v15.3.0) + React (v19.1.0)
  • App Router 기반 라우팅
  • SSR/ISR 활용으로 SEO 최적화
  • React 19의 use() 훅 활용한 데이터 페칭

상태 관리

• Zustand (v5.0.3)
  • 바텀시트 상태 관리 (bottomSheetStore)
  • 서버 컴포넌트 호환성
  • 직관적인 API로 빠른 개발 가능

UI/스타일링

• Tailwind CSS (v4.1)
  • 유틸리티 퍼스트 접근으로 빠른 개발
  • 커스텀 테마로 브랜드 디자인 시스템 구축
• shadcn/ui
  • Tailwind 기반 컴포넌트
  • 필요한 컴포넌트만 가져와 번들 크기 최적화
• Vaul
  • 모바일 최적화 바텀시트 라이브러리
  • 터치 제스처 지원

데이터 관리

• React use() + TanStack Query (v5)
  • 서버 컴포넌트: use() 훅으로 SEO 최적화
  • 클라이언트: TanStack Query로 복잡한 상태 관리
• Zod (v3.24.3)
  • 타입스크립트 연동
  • 서버-클라이언트 스키마 공유

폼 상태 관리

• react-hook-form (v7.51.2)
  • 가벼운 번들 사이즈로 모바일 친화적
  • Zod과 통합해 정교한 유효성 검사 가능
  • Server Action과 병행 사용 가능 (필요 시 SSR + 빠른 UX 모두 확보)

지도 서비스

• Kakao Maps SDK (v2.7.5)
  • 국내 사용자 친화적 UI
  • 커스텀 마커 지원
  • 지도 영역 제한 기능

빌드 도구

• Turbopack(v1.5.3) + webpack (v5)
• Next.js 15 내장 빌드 도구 ( Turbopack : 개발 환경, Webpack : 프로덕션 환경 )
• 빠른 개발 환경과 HMR 지원

SSR / ISR / SSG 적용 범위

• / : SSR + CSR 혼합
  • SSR 적용 부분:
    • 초기 카테고리 목록 로드
    • 기본 지도 설정
    • 메타데이터 및 SEO 최적화
  • CSR 적용 부분:
    • 사용자 위치 기반 동적 콘텐츠
    • 실시간 지도 인터랙션
    • 검색 결과 및 필터링
• /places/[id] : SSR + CSR 혼합
  • SSR 적용 부분:
    • 장소 기본 정보 (이름, 주소, 설명 등)
    • 메타데이터 및 SEO 최적화
    • 초기 방문 기록 로드
  • CSR 적용 부분:
    • 실시간 위치 확인
    • 북마크 토글
    • 무한 스크롤 방문 기록
    • 기록 작성 버튼 상태

폴더 구조

src/
├── app/(main)/(places)/
│   ├── page.tsx              # 메인 페이지
│   ├── places/[id]/page.tsx  # 장소 상세 페이지
│   └── search/               # 검색 결과 페이지
│       ├── page.tsx
│       └── layout.tsx
└── features/place/
    ├── api/                  # API 함수
    │   ├── getCategories.ts
    │   ├── getPlaceDetail.ts
    │   └── searchPlaces.ts
    ├── components/           # UI 컴포넌트
    │   ├── category-list/
    │   ├── keyword-list/
    │   ├── map/
    │   ├── place-basic-info/
    │   ├── place-item/
    │   ├── place-list-bottom-sheet/
    │   ├── place-menu/
    │   ├── place-open-hours/
    │   ├── place-pin-bottom-sheet/
    │   ├── search-bar/
    │   └── search-result-bar/
    ├── constants/           # 상수
    ├── hooks/              # 커스텀 훅
    │   ├── useBottomSheetSnapManagement.ts
    │   ├── useGlobalFocusHandler.ts
    │   ├── usePlaceToast.ts
    │   ├── useScrollRestoration.ts
    │   └── useSearchBar.ts
    ├── stores/             # Zustand 스토어
    │   └── bottomSheetStore.ts
    ├── types/              # 타입 정의
    │   ├── bottomSheetStore.ts
    │   └── place.ts
    └── utils/              # 유틸리티 함수
        └── map.ts

주요 페이지

/ : 메인 페이지

• 주요기능:
  • 장소 검색 (최소 1자, 최대 25자)
  • 지도 기반 장소 표시
  • 카테고리별 장소 필터링
  • 초기 빈 상태 표시
• 사용 컴포넌트:
  • SearchBar - 검색 입력
  • Map - 카카오맵
  • CategoryList - 카테고리 리스트
• 특징:
  • 검색어 입력 시 /search 페이지로 이동
  • 카테고리 선택 시 해당 카테고리로 검색

/search : 검색 결과 페이지

• 주요기능:
  • 검색 결과 지도 표시
  • 바텀시트로 장소 목록 표시
  • 마커 클릭 시 장소 핀 바텀시트 표시
  • 위치 기반 검색 (현재 위치는 판교 유스페이스로 고정)
• 사용 컴포넌트:
  • Map - 검색된 장소 마커 표시
  • PlaceListBottomSheet - 장소 목록 바텀시트
  • PlacePinBottomSheet - 개별 장소 바텀시트
• 데이터 로딩:
  • searchPlaces API 호출
  • TanStack Query로 캐싱

/places/[id] : 장소 상세 페이지

• 주요기능:
  • 장소 기본 정보 표시
  • 영업 시간 표시
  • 메뉴 정보 표시
  • 헤더 뒤로가기 버튼
• 사용 컴포넌트:
  • PlaceBasicInfo - 장소 기본 정보
  • PlaceOpenHours - 영업 시간
  • PlaceMenu - 메뉴 정보
• 데이터 로딩:
  • SSR로 getPlaceDetail API 호출

공통 컴포넌트

SearchBar : 검색 입력 컴포넌트

• 역할: 장소 검색어 입력 및 제출

• Props & Interface:

  interface SearchBarProps {
    initialQuery?: string;
    onSearch?: (query: string) => void;
    placeholder?: string;
    className?: string;
  }
  
  

• 기능:

  • 최소 1자 입력 검증
  • 최대 25자 제한
  • 엔터키 검색 지원
  • 토스트 메시지 표시
  • 검색 시 /search 페이지로 라우팅
  • 위치 정보 포함한 쿼리 파라미터 전달

• 상태 관리:

  • useSearchBar 커스텀 훅 사용
  • 검색어 상태 및 유효성 검증
  • 검색 시 바텀시트 상태 초기화

• 스타일링:

  • 둥근 모서리 검색 바
  • 호버/포커스 시 그림자 효과
  • 검색 아이콘 버튼

Map : 카카오맵 컴포넌트

• 역할: 카카오맵 표시 및 마커 관리

• Props & Interface:

  interface MapProps {
    places: Place[];
  }
  
  

• 기능:

  • 사용자 위치 마커 표시 (현재 위치)
  • 장소 마커 표시
  • 마커 클릭 이벤트 처리
  • 지도 영역 제한 (반경 1km)
  • 영역 벗어남 토스트 알림
  • 마커 선택 상태 관리

• 상태 관리:

  • 지도 인스턴스 ref 관리
  • 마커 클릭 시 바텀시트 상태 변경
  • 선택된 장소 ID 저장

• 스타일링:

  • 전체 화면 지도
  • 커스텀 마커 이미지
  • 선택된 마커 하이라이트

CategoryList : 카테고리 리스트 컴포넌트

• 역할: 카테고리 기반 검색
• 기능:
  • 카테고리 목록 표시
  • 선택된 카테고리 하이라이트
  • 가로 스크롤
  • 카테고리 클릭 시 검색
• 데이터 페칭:
  • 서버 컴포넌트로 getCategories API 호출
  • SSR로 카테고리 데이터 로드
• 스타일링:
  • 가로 스크롤 컨테이너
  • 스크롤바 숨김
  • 카테고리 칩 스타일

PlaceListBottomSheet : 장소 목록 바텀시트 컴포넌트

• 역할: 장소 목록을 바텀시트로 표시

• Props & Interface:

  interface PlaceListProps {
    places: Place[];
  }
  
  

• 기능:

  • 드래그 제스처 지원
  • 높이 스냅 포인트
  • 스크롤 복원
  • 장소 아이템 클릭
  • 높이 상태 저장 및 복원

• 상태 관리:

  • Zustand bottomSheetStore 사용
  • 스냅 포인트 상태
  • 스크롤 위치 저장
  • 이전 높이 복원

• 커스텀 훅:

  • useBottomSheetSnapManagement: 스냅 포인트 관리
  • useScrollRestoration: 스크롤 위치 복원
  • useGlobalFocusHandler: 포커스 이벤트 처리

• 스타일링:

  • Vaul 라이브러리 기반
  • 상단 드래그 핸들
  • 최대 너비 430px

PlacePinBottomSheet : 장소 핀 바텀시트 컴포넌트

• 역할: 선택된 장소 정보 표시

• Props & Interface:

  interface PlaceBottomSheetProps {
    onOpenChange: (open: boolean) => void;
    place: Place | null;
  }
  
  

• 기능:

  • 장소 기본 정보 표시
  • 키워드 표시
  • 닫기 기능
  • 상세 보기 버튼

• 상태 관리:

  • Zustand bottomSheetStore에서 opened 상태 확인
  • 닫기 시 opened 상태를 'list'로 변경

• 스타일링:

  • 모달 오버레이
  • 하단 고정 위치
  • 둥근 상단 모서리

PlaceItem : 장소 아이템 컴포넌트

• 역할: 개별 장소 카드

• Props & Interface:

  interface PlaceItemProps {
    id: number;
    name: string;
    thumbnail: string;
    keywords: string[];
    isClickable?: boolean;
    isDetailButton?: boolean;
  }
  
  

• 기능:

  • 이미지 표시 (없을 경우 플레이스홀더)
  • 장소명, 카테고리
  • 클릭 시 상세 페이지 이동
  • 상세 보기 버튼 (선택적)

• 상태 관리:

  • Next.js useRouter 사용
  • 클릭 시 /places/${id}로 라우팅

• 스타일링:

  • 이미지 + 정보 가로 레이아웃
  • 96x96px 이미지 크기
  • 키워드 리스트 포함

PlaceBasicInfo : 장소 기본 정보 컴포넌트

• 역할: 장소 상세 정보

• Props & Interface:

  interface PlaceBasicInfoProps {
    placeBasicInfo: Omit<PlaceDetail, 'menu' | 'opening_hours'>;
  }
  
  

• 기능:

  • 이미지 갤러리 (1:1 비율)
  • 기본 정보 표시 (이름, 주소, 전화번호)
  • 키워드 리스트
  • 설명 텍스트

• 스타일링:

  • 정사각형 이미지
  • 키워드 태그 스타일
  • 정보 계층 구조

PlaceOpenHours : 영업 시간 컴포넌트

• 역할: 영업 시간 정보

• Props & Interface:

  interface PlaceOpenHoursProps {
    openHours: OpeningHours;
  }
  
  

• 기능:

  • 현재 영업 상태
  • 요일별 시간 표시
  • 휴무일 표시

• 스타일링:

  • 영업 상태 배지
  • 요일별 목록

PlaceMenu : 메뉴 정보 컴포넌트

• 역할: 메뉴 정보

• Props & Interface:

  interface PlaceMenuProps {
    menu: MenuItem[];
  }
  
  

• 기능:

  • 메뉴 이미지
  • 메뉴명 및 가격
  • 이미지 없을 경우 플레이스홀더

• 스타일링:

  • 그리드 레이아웃
  • 메뉴 카드 스타일

KeywordList : 키워드 리스트 컴포넌트

• 역할: 키워드 태그 표시

• Props & Interface:

  interface KeywordListProps {
    keywords: string[];
  }
  
  

• 기능:

  • 키워드 배열을 태그로 표시
  • 가로 스크롤 (필요시)

• 스타일링:

  • 둥근 태그 스타일
  • 회색 배경
  • 간격 조정

컴포넌트 간 관계

graph TD
    A[SearchBar] -->|검색 쿼리| B[Search Page]
    B --> C[Map]
    B --> D[PlaceListBottomSheet]
    C -->|마커 클릭| E[PlacePinBottomSheet]
    D -->|장소 클릭| F[PlaceItem]
    E --> F
    F -->|상세 보기| G[Place Detail Page]
    G --> H[PlaceBasicInfo]
    G --> I[PlaceOpenHours]
    G --> J[PlaceMenu]
    K[CategoryList] -->|카테고리 선택| B

데이터 흐름

1. 검색 플로우:
   • SearchBar → 검색어 입력
   • → /search 페이지 이동
   • → searchPlaces API 호출
   • → Map + PlaceListBottomSheet 렌더링
2. 마커 클릭 플로우:
   • Map 마커 클릭
   • → bottomSheetStore 상태 변경
   • → PlacePinBottomSheet 열림
   • → PlaceItem 표시
3. 상세 페이지 플로우:
   • PlaceItem 클릭/버튼
   • → /places/[id] 이동
   • → getPlaceDetail API 호출
   • → 상세 정보 컴포넌트 렌더링

상태 관리

BottomSheetStore (Zustand)

interface BottomSheetState {
  opened: 'list' | 'pin';
  prevSnap: number | string | null;
  scrollY: number;
  lastPlaceId: number | null;

  setOpened: (opened: 'list' | 'pin') => void;
  setPrevSnap: (snap: number | string | null) => void;
  setScrollY: (scrollY: number) => void;
  setLastPlaceId: (placeId: number | null) => void;
  resetForNewSearch: () => void;
}

Local State

• SearchBar: 검색어 입력
• Map: 지도 인스턴스
• PlaceListBottomSheet: 스냅 포인트

API 연동

구현된 API

• GET /api/v1/categories - 카테고리 목록
• GET /api/v1/places/search - 장소 검색
• GET /api/v1/places/{id} - 장소 상세

타입 정의

// 위치 정보interface Location {
  type: 'Point';
  coordinates: [number, number];// [경도, 위도] - GeoJSON 표준
}

// 장소 기본 정보interface Place {
  id: number;
  name: string;
  thumbnail: string;
  distance: string;// 거리 (미터 단위)moment_count: string;// 방문 기록 수keywords: string[];// 키워드 목록location: Location;// 위치 정보
}

// 장소 상세 정보interface PlaceDetail {
  id: number;
  name: string;
  address: string | null;
  thumbnail: string | null;
  location: Location;
  keywords: string[];
  description: string;
  phone: string | null;
  menu?: Menu[];
  opening_hours: OpenHours;
}

// 영업 시간 정보interface OpenHours {
  status:
    | '영업 중'
    | '영업 종료'
    | '브레이크 타임'
    | '휴무일'
    | '영업 정보 없음'
    | '영업 여부 확인 필요';
  schedules: {
    day: 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
    hours: string | null;
    break_time: string | null;
  }[];
}

// 메뉴 정보interface Menu {
  name: string;
  price: number | null;
}

API 요청/응답 타입

// 카테고리 목록 응답
interface CategoriesResponse {
  categories: string[];
}

// 장소 검색 요청interface SearchPlacesParams {
  lat: string;// 위도lng: string;// 경도query: string | null;// 검색어category: string | null;// 카테고리
}

// 장소 검색 응답interface SearchPlacesResponse {
  total: number;// 전체 결과 수places: Place[];// 장소 목록
}

상태 관리 타입

// 바텀시트 상태type BottomSheetType = 'list' | 'pin';

interface BottomSheetState {
  opened: BottomSheetType;
  prevSnap: number | string | null;
  scrollY: number;
  lastPlaceId: number | null;

  setOpened: (opened: BottomSheetType) => void;
  setPrevSnap: (snap: number | string | null) => void;
  setScrollY: (scrollY: number) => void;
  setLastPlaceId: (placeId: number | null) => void;
  resetForNewSearch: () => void;
}

API 호출 예시

// 카테고리 목록 조회const { categories } = await getCategories();

// 장소 검색const searchResults = await searchPlaces({
  lat: '37.401179',
  lng: '127.108047',
  query: '카페',
  category: null,
});

// 장소 상세 조회const placeDetail = await getPlaceDetail('1');

커스텀 훅

useSearchBar

• 검색어 상태 관리
• 검색 실행 로직
• 유효성 검증

useBottomSheetSnapManagement

• 바텀시트 높이 관리
• 스냅 포인트 제어

useScrollRestoration

• 스크롤 위치 저장/복원
• 페이지 이동 시 위치 유지

usePlaceToast

• 토스트 메시지 표시
• 에러/성공 메시지

useGlobalFocusHandler

• 전역 포커스 이벤트
• 바텀시트 입력 문제 해결

성능 최적화

• TanStack Query 캐싱
  • staleTime: 10분
  • refetchOnWindowFocus: false
• 이미지 최적화
  • Next.js Image 컴포넌트
  • lazy loading

향후 계획

• 북마크 기능 구현
• 방문 기록 기능
• 최적화 된 렌더링 구현
• SEO 최적화 구현
• 검색 결과 정렬
• 지도 클러스터링