장소, 경로 및 북마크/일정 일괄 조회 API 적용을 통한 초기 로딩 성능 최적화

[minbros]

설명

백엔드 PR #132(장소 및 경로 벌크 조회 API 추가 및 비동기 가상 스레드 최적화)가 적용됨에 따라, 프론트엔드 화면 초기 진입 시 발생하는 API N+1 병목을 완화하고 로딩 성능을 최적화하기 위해 신규 일괄(벌크) 조회 API 및 파라미터를 적용해야 합니다.

기대 동작

1. 일정 및 일정 아이템 일괄 조회 (일정 벌크 조회)

• 방 초기 진입 시 각 일정의 장소 항목(아이템) 목록을 한 번에 받아오도록 적용합니다.
• API: GET /rooms/{roomId}/schedules?includeItems=true
• 동작: includeItems=true 쿼리 파라미터를 전달하면 전체 일자별 일정 목록과 각 일정 하위의 장소 아이템 목록(items 배열)을 N+1 조회 없이 한 번에 조회합니다.

2. 북마크 카테고리 구분 없는 전체 조회 (북마크 벌크 조회)

• 보관함 초기 로딩 시 카테고리별로 API를 여러 번 쪼개서 호출하지 않고 전체 목록을 일괄 조회합니다.
• API: GET /rooms/{roomId}/bookmarks
• 동작: categoryId 쿼리 파라미터를 전달하지 않고(생략) 호출하면, 카테고리 필터링 없이 방의 전체 보관함 항목을 한 번에 정렬된 결과로 응답받습니다.

3. 장소 미리보기 벌크 조회 적용

• 방 초기 로딩 또는 여러 후보지를 카드 형태로 노출할 때, 기존 단건 API(GET /places/{googlePlaceId}/preview) 대신 벌크 API를 사용합니다.
• API: POST /places/previews/batch
• Request Body: {"googlePlaceIds": ["ChIJ...", ...]} (최대 100개)
• 참고: 개별 장소의 외부 API 조회 실패 시 status/errorCode 형태의 부분 실패 응답이 포함되므로 예외 처리가 필요합니다.

4. 장소 사진 관련 벌크 조회 적용

• 여러 장소의 사진 및 URL 조회를 단건 대신 벌크로 일괄 처리합니다.
• 대표 사진 이름 벌크 조회 API: POST /places/photo-names/batch
  • Request Body: {"googlePlaceIds": ["ChIJ...", ...]} (최대 100개)
• 사진 URL 벌크 조회 API: POST /places/photos/batch
  • Request Body: {"photoNames": ["places/.../photos/...", ...]} (최대 100개)

5. 일정 경로(이동 정보) 벌크 조회 적용

• 일자별 일정의 구간 경로를 단건 API 대신 한 번에 조회하여 지도와 타임라인에 표시합니다.
• API: POST /rooms/{roomId}/schedules/{scheduleId}/routes/batch
• Request Body:

  {
    "items": [
      { "itemId": 1, "travelMode": "WALKING" },
      { "itemId": 2, "travelMode": "DRIVING" }
    ]
  }

  (최대 25개 구간)
• 참고: 마지막 항목이거나 경로 없음 등 구간별 결과 상태(status/errorCode)에 대한 렌더링 예외 처리가 필요합니다.

6. Rate Limit에 대응한 프론트엔드 측 캐싱 권장

• 백엔드에 사용자/API별 속도 제한(Rate Limit)이 엄격하게 적용되어 있습니다. (예: 사진 관련 API 분당 30회 제한 등)
• 따라서 프론트엔드에서는 한 번 조회한 사진 URL(photoUrl)을 컴포넌트 리렌더링이나 탭 전환 시마다 중복 요청하지 않아야 합니다.
• React Query 등 상태 관리 도구의 캐시를 적극 활용하여, 동일한 photoName에 대해서는 새로고침 전까지 기존 URL을 재사용하도록 구현해야 합니다.

참고

• 백엔드 PR: feat: 장소 및 경로 벌크 조회 API 추가 및 비동기 가상 스레드 최적화 backend-server#132

[song9252]

1. 일정 및 일정 아이템 일괄 조회

반영됨 (초기 진입·새로고침)

방에 들어가거나 일정을 다시 맞출 때 GET …/schedules?includeItems=true를 방 단위 1회 호출합니다. 응답의 items를 room-schedules 캐시에 그대로 보관하고, 일차별 schedule-items 캐시(장소 카드용)까지 한 번에 시딩합니다.

의도적으로 벌크가 아닌 경우

원격 STOMP로 항목이 바뀌거나, 리오더·일차 간 이동 같은 뮤테이션 직후 동기화는 해당 일차만 GET …/schedules/{scheduleId}/items로 맞춥니다.
즉, “처음 방 들어올 때 N+1 제거”는 벌크로 처리하고, “이후 변경분”은 영향 일차만 단건 목록 API로 갱신하는 구조입니다.

2. 북마크 전체 일괄 조회

반영됨 (초기·공통 캐시)

GET …/bookmarks(categoryId 없음)로 방 전체 북마크를 한 번 받아 room-bookmarks-all 캐시에 넣고, 카테고리별 캐시도 함께 시딩합니다. 맵 핀, 북마크 폴더 목록, 일정에 북마크에서 추가하는 모달 등이 이 공통 캐시를 공유합니다.

아직 카테고리 단건 GET이 남는 경우

특정 폴더 상세 화면의 useRoomBookmarks는 여전히 GET …/bookmarks?categoryId=를 쓸 수 있습니다. 다만 최근 변경으로 본인이 장소를 추가할 때는 POST 응답으로 캐시만 패치하고 GET 재호출은 하지 않습니다.
원격 탭에서의 변경은 STOMP invalidate 후 필요 시 다시 조회합니다.

3. 장소 미리보기 벌크 조회

반영됨 (일정·방 초기 로딩 중심)

일정 hydrate 시 해당 방의 모든 googlePlaceId를 모아 POST …/places/previews/batch로 한꺼번에 시딩합니다. 캐시에 없는 ID만 보내고, in-flight 중복도 막습니다. batch miss·부분 실패 시에는 단건 GET …/preview로 보강하는 경로도 있습니다.

벌크를 쓰지 않는 화면

북마크 UI(폴더 상세, 맵 핀, 일정에 북마크 추가 모달)는 의도적으로 단건 preview로 복구했습니다. 북마크 1건 추가 시 전체 ID에 batch를 다시 돌리던 문제를 없애기 위함입니다.
PlaceDetailPanel 자체 상세는 기존처럼 단건 preview/detail 경로를 사용합니다.
정리하면, “방·일정 카드 대량 노출”은 batch, “북마크·단일 장소 패널”은 단건 위주입니다.

4. 장소 사진 관련 벌크 조회

반영됨

일정 hydrate 후 수집한 photoName에 대해 POST …/places/photos/batch로 URL을 시딩합니다.
장소 검색 결과, 채팅 히스토리 사진 warm-up, 여러 photoName을 한꺼번에 쓰는 훅 등에서도 photo-names / photos batch를 사용합니다.
chunk 단위(최대 100개)로 나눠 호출하도록 되어 있습니다.
단건이 남는 경우

개별 컴포넌트의 usePlacePhotoUrlQuery는 캐시 miss 시 단건 requestPlacePhotoUrl fallback이 있습니다. 대부분은 batch 시딩 후 캐시만 읽습니다.

5. 일정 경로(이동 정보) 벌크 조회

반영됨 (페이지 진입·새로고침, 일차당 1회)

일차별로 DRIVING 구간을 POST …/schedules/{scheduleId}/routes/batch로 최초 1회 시딩합니다. batch가 끝날 때까지 타임라인의 경로 쿼리를 막아, 진입 직후 개별 GET …/route가 먼저 나가지 않게 했습니다. 응답의 status/errorCode도 파싱해 실패 구간은 null 등으로 처리합니다.

벌크를 쓰지 않는 경우

리오더, 장소 추가·삭제, 일차 간 이동 등 변경 이후에는 영향 받은 구간만 기존처럼 개별 GET …/route로 갱신합니다. 변경 때마다 일차 전체 batch를 다시 호출하지 않습니다.
도보·대중교통 등 DRIVING이 아닌 수단은 처음부터 단건 route API를 사용합니다.

6. Rate Limit 대응 캐싱

반영됨

사진 URL: staleTime: Infinity, refetchOnMount/WindowFocus 끔 → 동일 photoName은 새로고침 전까지 재요청하지 않음.
preview: React Query 캐시 + batch in-flight dedup.
일정·북마크 목록: hydrate 후 staleTime: Infinity로 불필요 refetch 억제.
경로: batch·sessionStorage 시딩 후 캐시 우선, 명시 invalidate 때만 재조회.
최근 북마크 mutation/STOMP 정리로 invalidate 폭주도 줄여, rate limit에 걸릴 여지를 추가로 낮췄습니다.