daiso 1.0.4 → 1.0.6

package/dist/pages/promptReferenceText.js

@@ -0,0 +1,137 @@
+/**
+ * 프롬프트 응답/사용 팁 섹션
+ */
+export function buildPromptReferenceText(baseUrl) {
+    return `## 응답 형식
+
+### 성공 응답
+\`\`\`json
+{
+  "success": true,
+  "data": { ... },
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 30
+  }
+}
+\`\`\`
+
+### 에러 응답
+\`\`\`json
+{
+  "success": false,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "에러 메시지"
+  }
+}
+\`\`\`
+
+### 에러 코드
+| 코드 | 설명 |
+|------|------|
+| MISSING_QUERY | 검색어가 누락됨 |
+| MISSING_PARAMS | 필수 파라미터 누락 |
+| MISSING_PRODUCT_ID | 제품 ID 누락 |
+| MISSING_STORE_CODE | 매장 코드 누락 |
+| NOT_FOUND | 결과를 찾을 수 없음 |
+| SEARCH_FAILED | 검색 실패 |
+| FETCH_FAILED | 데이터 조회 실패 |
+| DISPLAY_LOCATION_FAILED | 진열 위치 조회 실패 |
+| OLIVEYOUNG_STORE_SEARCH_FAILED | 올리브영 매장 조회 실패 |
+| OLIVEYOUNG_PRODUCT_SEARCH_FAILED | 올리브영 상품 조회 실패 |
+| OLIVEYOUNG_INVENTORY_CHECK_FAILED | 올리브영 재고 조회 실패 |
+| MEGABOX_THEATER_SEARCH_FAILED | 메가박스 지점 조회 실패 |
+| MEGABOX_MOVIE_LIST_FAILED | 메가박스 영화 목록 조회 실패 |
+| MEGABOX_SEAT_LIST_FAILED | 메가박스 좌석 조회 실패 |
+| LOTTECINEMA_THEATER_SEARCH_FAILED | 롯데시네마 지점 조회 실패 |
+| LOTTECINEMA_MOVIE_LIST_FAILED | 롯데시네마 영화 목록 조회 실패 |
+| LOTTECINEMA_SEAT_LIST_FAILED | 롯데시네마 좌석 조회 실패 |
+| CGV_THEATER_SEARCH_FAILED | CGV 극장 조회 실패 |
+| CGV_MOVIE_SEARCH_FAILED | CGV 영화 목록 조회 실패 |
+| CGV_TIMETABLE_FETCH_FAILED | CGV 시간표 조회 실패 |
+| GS25_STORE_SEARCH_FAILED | GS25 매장 조회 실패 |
+| GS25_PRODUCT_SEARCH_FAILED | GS25 상품 조회 실패 |
+| GS25_INVENTORY_CHECK_FAILED | GS25 재고 조회 실패 |
+| LOTTEMART_STORE_SEARCH_FAILED | 롯데마트 매장 조회 실패 |
+| LOTTEMART_PRODUCT_SEARCH_FAILED | 롯데마트 상품 조회 실패 |
+| SEVENELEVEN_INVENTORY_CHECK_FAILED | 세븐일레븐 재고 조회 실패 |
+
+---
+
+## 사용 팁
+
+1. **한글 검색어**: URL 인코딩이 자동으로 처리됩니다
+2. **페이지네이션**: 결과가 많을 경우 page 파라미터 사용
+3. **브랜드 고정**: 사용자가 "다이소에서", "GS25에서"처럼 브랜드를 명시하면 품목상 어색해 보여도 먼저 그 브랜드에서 실제 검색/조회하고, 결과가 없을 때만 다른 브랜드 대안을 짧게 제안합니다.
+   - 금지: "핫식스는 다이소가 아니라 편의점 상품이라서 조회할 수 없습니다"처럼 사전 판단으로 검색을 거부
+   - 원칙: 브랜드가 명시되면 일단 해당 브랜드에서 실제 조회 후, 결과가 없을 때만 다른 브랜드 제안
+   - 확장 해석: "안산 중앙역 주변 다이소 찾아주시고 핫식스 재고 찾아주세요"처럼 브랜드가 앞부분에만 나와도 뒤 요청 전체를 다이소 기준으로 처리
+4. **이미지 적극 표시**:
+   - **규칙 1**: MCP/REST 응답에 \`imageUrl\`이 있으면 반드시 마크다운 이미지로 렌더링하세요.
+   - **규칙 2**: 사용자가 따로 요청하기 전까지 이미지를 임의로 생략하지 마세요.
+   - **규칙 3**: 이미지가 여러 개이면 첫 번째만 대표로 보여주지 말고 각 항목의 이미지를 전부 표시하세요.
+   - **규칙 4**: "길어서 일부만 표시", "대표 이미지만 표시", "나머지는 생략" 같은 동작을 하지 마세요.
+   - **규칙 5**: 텍스트 요약보다 이미지 표시 의무가 우선이며, 이미지가 있으면 답변 길이 때문에라도 빼지 마세요.
+   - **규칙 6**: \`imageUrl\`에 query string이 있으면 \`?l=ko\` 같은 쿼리를 절대 삭제하거나 정규화하지 말고, 마크다운 이미지 src에 전체 URL을 그대로 사용하세요.
+   - **규칙 7**: 이미지 src를 비교하거나 캐시 키를 판단할 때도 hostname + pathname만 쓰지 말고 query string까지 포함한 전체 URL을 기준으로 취급하세요.
+5. **재고 확인 워크플로우**:
+   - 먼저 /api/daiso/products로 제품 검색
+   - 결과에서 원하는 제품의 id 확인
+   - /api/daiso/inventory에 해당 id로 재고 조회
+   - 진열 위치가 필요하면 재고 응답의 storeCode를 확인한 뒤 /api/daiso/display-location에 productId + storeCode로 조회
+   - 다이소 재고 조회는 storeCode가 필요하지 않습니다.
+6. **최소 정보 요청 처리**:
+   - 사용자가 상품명만 주면 먼저 상품 검색 도구로 후보를 찾고, 응답의 productId/itemCode/pluCd를 다음 단계에 전달합니다.
+   - 사용자가 위치를 대강 말하면 keyword/storeKeyword에 그대로 넣어 먼저 조회하고, 결과가 없을 때만 공백 제거, 역/점 접미어 제거 같은 변형을 시도합니다.
+   - 도구가 productId, itemCode, storeCode 같은 내부 ID를 요구하면 사용자에게 바로 ID를 요구하지 말고, 검색/재고 응답에서 먼저 확인합니다.
+   - "근처", "주변"처럼 위치가 없는 표현만 있으면 기본 좌표 결과를 단정하지 말고 사용자의 지역/역명/좌표를 물어봅니다.
+7. **상품명 단계 검색**:
+   - 재고 검색은 어떤 서비스이든 검색어 전체를 먼저 그대로 조회하고, 실패할 때만 공백/브랜드어 제거, 표기 변형, 더 짧은 핵심어 순으로 단계적으로 넓혀서 다시 시도합니다.
+   - 너무 넓은 축약어로만 매칭된 경우에는 확정 상품처럼 단정하지 말고, 추정 매칭임을 짧게 밝힌 뒤 재고를 안내합니다.
+   - 위치/브랜드/상품명은 한 인자에 섞지 말고 가능한 한 분리해서 도구에 전달합니다.
+8. **위치 기반 재고**: lat, lng 파라미터로 가까운 매장 우선 조회
+9. **롯데마트 상품 조회**: /api/lottemart/products는 keyword와 함께 storeCode 또는 storeName이 필요합니다.
+10. **세븐일레븐 재고 조회**: /api/seveneleven/inventory에 keyword + storeKeyword를 함께 주면 매장별 수량을 바로 확인할 수 있습니다.
+11. **이마트24 재고 조회**: /api/emart24/inventory는 pluCd + storeKeyword 조합도 지원하므로, 상품 선택 뒤 매장 코드를 다시 모으지 않아도 됩니다.
+12. **올리브영 재고 해석**: inventory.products[].storeInventory.stores[]가 있으면 그 매장별 stockLabel과 remainQuantity를 우선 사용하고, inStock는 그 주변 매장 기준 결과로 해석합니다.
+13. **올리브영 상품 이미지 표시**: /api/oliveyoung/products 또는 oliveyoung_search_products 결과에 imageUrl이 있으면 목록형 답변에서도 각 상품 이미지를 생략하지 말고 모두 렌더링합니다. 특히 \`?l=ko\` 같은 query string을 삭제하지 말고 전체 URL 그대로 마크다운 이미지 src에 넣습니다.
+
+---
+
+## MCP 지원 서비스
+
+MCP를 지원하는 AI 에이전트(Claude 등)는 더 풍부한 기능을 사용할 수 있습니다.
+MCP 연결 정보: ${baseUrl}/mcp
+
+지원 도구:
+- daiso_search_products: 제품 검색
+- daiso_find_stores: 매장 검색
+- daiso_check_inventory: 재고 확인
+- daiso_get_price_info: 가격 정보 조회
+- daiso_get_display_location: 진열 위치 조회
+- lottemart_find_nearby_stores: 롯데마트 주변 매장 탐색
+- lottemart_search_products: 롯데마트 상품 검색
+- gs25_find_nearby_stores: GS25 주변 매장 탐색
+- gs25_search_products: GS25 상품 검색
+- gs25_check_inventory: GS25 재고 조회
+- seveneleven_search_products: 세븐일레븐 상품 검색
+- seveneleven_search_stores: 세븐일레븐 매장 검색
+- seveneleven_check_inventory: 세븐일레븐 재고 조회
+- seveneleven_get_search_popwords: 세븐일레븐 인기 검색어 조회
+- seveneleven_get_catalog_snapshot: 세븐일레븐 카탈로그 조회
+- oliveyoung_search_products: 올리브영 상품 검색
+- oliveyoung_find_nearby_stores: 올리브영 주변 매장 탐색
+- oliveyoung_check_inventory: 올리브영 재고 파악
+- megabox_find_nearby_theaters: 메가박스 주변 지점 탐색
+- megabox_list_now_showing: 메가박스 영화 목록 조회
+- megabox_get_remaining_seats: 메가박스 잔여 좌석 조회
+- lottecinema_find_nearby_theaters: 롯데시네마 주변 지점 탐색
+- lottecinema_list_now_showing: 롯데시네마 영화 목록 조회
+- lottecinema_get_remaining_seats: 롯데시네마 잔여 좌석 조회
+- cgv_find_theaters: CGV 극장 검색
+- cgv_search_movies: CGV 영화 검색
+- cgv_get_timetable: CGV 시간표 조회
+`;
+}

package/dist/pages/promptRetailCinemaText.js

@@ -0,0 +1,274 @@
+/**
+ * 프롬프트 리테일/영화 API 섹션
+ */
+export function buildPromptRetailCinemaText(baseUrl) {
+    return `### 6-1. 롯데마트 매장/상품 조회
+
+**설명**: 롯데마트 계열 매장 검색과 특정 매장 기준 상품 가격/재고 조회를 제공합니다.
+
+**URL**:
+- ${baseUrl}/api/lottemart/stores?keyword={키워드}
+- ${baseUrl}/api/lottemart/products?keyword={검색어}&storeName={매장명}
+
+**선택 파라미터**:
+- area: 지역 (예: 서울, 경기, 제주)
+- brandVariant: lottemart, toysrus, max, bottlebunker, mealguru, grandgrocery
+- lat: 위도 (선택)
+- lng: 경도 (선택)
+- limit: 최대 결과 수 (기본값: 20)
+- storeCode 또는 storeName: 상품 검색 대상 매장
+- pageLimit: 추가 조회할 최대 페이지 수 (기본값: 3)
+- source: 상품 검색 경로 (auto, legacy, zetta). 빠른 검색이나 헬스체크에는 zetta 권장
+
+**예시**:
+- ${baseUrl}/api/lottemart/stores?keyword=잠실&area=서울&limit=10
+- ${baseUrl}/api/lottemart/stores?area=경기&brandVariant=lottemart&limit=10
+- ${baseUrl}/api/lottemart/products?keyword=콜라&storeName=강변점&area=서울
+- ${baseUrl}/api/lottemart/products?keyword=우유&storeCode=2301&pageLimit=2&source=zetta
+
+---
+
+### 6-2. GS25 매장/상품/재고 조회
+
+**설명**: GS25 매장 탐색, 상품 키워드 검색, 재고 조회를 제공합니다.
+
+**URL**:
+- ${baseUrl}/api/gs25/stores?keyword={키워드}
+- ${baseUrl}/api/gs25/products?keyword={검색어}
+- ${baseUrl}/api/gs25/inventory?keyword={검색어}
+- ${baseUrl}/api/gs25/inventory?itemCode={상품코드}
+
+**선택 파라미터(공통)**:
+- lat: 위도 (선택)
+- lng: 경도 (선택)
+- limit / storeLimit: 최대 결과 수
+- serviceCode: 서비스 코드 (기본값: 01)
+
+**예시**:
+- ${baseUrl}/api/gs25/stores?keyword=강남&limit=10
+- ${baseUrl}/api/gs25/products?keyword=오감자&limit=20
+- ${baseUrl}/api/gs25/inventory?keyword=오감자&storeKeyword=강남&storeLimit=10
+- ${baseUrl}/api/gs25/inventory?itemCode=8801056038861&storeKeyword=안산%20중앙역&storeLimit=10
+
+---
+
+### 6-3. 세븐일레븐 상품/매장/재고/인기검색어/카탈로그 조회
+
+**설명**: 세븐일레븐 상품 검색, 매장 검색, 재고 수량 조회, 인기 검색어, 카탈로그 스냅샷을 제공합니다.
+
+**URL**:
+- ${baseUrl}/api/seveneleven/products?query={검색어}
+- ${baseUrl}/api/seveneleven/stores?keyword={매장키워드}
+- ${baseUrl}/api/seveneleven/inventory?keyword={검색어}
+- ${baseUrl}/api/seveneleven/popwords?label={라벨}
+- ${baseUrl}/api/seveneleven/catalog?includeIssues={true|false}&includeExhibition={true|false}&limit={개수}
+
+**선택 파라미터**:
+- page: 페이지 번호 (기본값: 1)
+- size: 페이지당 결과 수 (기본값: 20)
+- sort: 정렬 기준 (기본값: recommend)
+- storeKeyword: 매장명/지역 키워드
+- storeLimit: 최대 매장 수 (기본값: 20)
+- timeoutMs: 요청 제한 시간 (기본값: 20000)
+- label: 인기 검색어 라벨 (기본값: home)
+
+**예시**:
+- ${baseUrl}/api/seveneleven/products?query=삼각김밥&size=20
+- ${baseUrl}/api/seveneleven/stores?keyword=안산%20중앙역&limit=10
+- ${baseUrl}/api/seveneleven/inventory?keyword=핫식스&storeKeyword=안산%20중앙역&storeLimit=10
+- ${baseUrl}/api/seveneleven/popwords?label=home
+- ${baseUrl}/api/seveneleven/catalog?includeIssues=true&includeExhibition=true&limit=10
+
+---
+
+### 7. 메가박스 주변 지점 찾기
+
+**설명**: 사용자 좌표 또는 위치 키워드 기준으로 메가박스 지점을 거리순으로 조회합니다.
+
+**URL**: ${baseUrl}/api/megabox/theaters?lat={위도}&lng={경도}
+
+**선택 파라미터**:
+- keyword: 위치 키워드 (예: 안산 중앙역, 강남역)
+- lat: 위도 (기본값: 37.5665)
+- lng: 경도 (기본값: 126.978)
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- areaCode: 지역 코드 (기본값: 11, 서울)
+- limit: 최대 결과 수 (기본값: 10)
+
+**예시**:
+- ${baseUrl}/api/megabox/theaters?keyword=안산%20중앙역&limit=5
+- ${baseUrl}/api/megabox/theaters?lat=37.4982&lng=127.0264
+- ${baseUrl}/api/megabox/theaters?areaCode=11&limit=5
+
+---
+
+### 8. 메가박스 영화/회차 목록
+
+**설명**: 날짜/지점 조건으로 메가박스 영화와 상영 회차를 조회합니다. theaterId가 없고 위치 키워드/좌표가 있으면 가장 가까운 지점을 먼저 선택합니다.
+
+**URL**: ${baseUrl}/api/megabox/movies?playDate={YYYYMMDD}
+
+**선택 파라미터**:
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- theaterId: 지점 ID (예: 1372)
+- movieId: 영화 ID (예: 25104500)
+- keyword: 위치 키워드 (예: 안산 중앙역, 강남역)
+- lat: 위도
+- lng: 경도
+- areaCode: 지역 코드 (기본값: 11)
+
+**예시**:
+- ${baseUrl}/api/megabox/movies?playDate=20260315&keyword=안산%20중앙역
+- ${baseUrl}/api/megabox/movies?playDate=20260304&theaterId=1372
+- ${baseUrl}/api/megabox/movies?playDate=20260304&movieId=25104500
+
+---
+
+### 9. 메가박스 잔여 좌석 조회
+
+**설명**: 영화/지점/날짜 기준으로 회차별 잔여 좌석 수를 조회합니다. theaterId가 없고 위치 키워드/좌표가 있으면 가장 가까운 지점을 먼저 선택합니다.
+
+**URL**: ${baseUrl}/api/megabox/seats?playDate={YYYYMMDD}
+
+**선택 파라미터**:
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- theaterId: 지점 ID
+- movieId: 영화 ID
+- keyword: 위치 키워드 (예: 안산 중앙역, 강남역)
+- lat: 위도
+- lng: 경도
+- areaCode: 지역 코드 (기본값: 11)
+- limit: 최대 결과 수 (기본값: 50)
+
+**예시**:
+- ${baseUrl}/api/megabox/seats?playDate=20260315&keyword=안산%20중앙역
+- ${baseUrl}/api/megabox/seats?playDate=20260304&theaterId=1372
+- ${baseUrl}/api/megabox/seats?playDate=20260304&movieId=25104500&limit=20
+
+---
+
+### 10. CGV 극장 검색
+
+**설명**: 지역 코드 또는 위치 키워드 기준으로 CGV 극장 목록을 조회합니다.
+
+**URL**: ${baseUrl}/api/cgv/theaters?playDate={YYYYMMDD}
+
+**선택 파라미터**:
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- regionCode: 지역 코드 (예: 01)
+- keyword: 위치 키워드 (예: 안산 중앙역, 강남역)
+- lat: 위도
+- lng: 경도
+- limit: 최대 결과 수 (기본값: 30)
+
+**예시**:
+- ${baseUrl}/api/cgv/theaters?playDate=20260304&regionCode=01
+- ${baseUrl}/api/cgv/theaters?playDate=20260315&keyword=안산%20중앙역
+- ${baseUrl}/api/cgv/theaters?playDate=20260304&limit=10
+
+---
+
+### 11. CGV 영화 검색
+
+**설명**: 날짜/극장 조건으로 CGV 영화 목록을 조회합니다. theaterCode가 없으면 keyword 또는 lat,lng 기준으로 가장 가까운 극장을 먼저 선택합니다.
+
+**URL**: ${baseUrl}/api/cgv/movies?playDate={YYYYMMDD}
+
+**선택 파라미터**:
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- theaterCode: 극장 코드 (예: 0056)
+- keyword: 위치 키워드 (예: 안산 중앙역, 강남역)
+- lat: 위도
+- lng: 경도
+
+**예시**:
+- ${baseUrl}/api/cgv/movies?playDate=20260304&theaterCode=0056
+- ${baseUrl}/api/cgv/movies?playDate=20260315&keyword=안산%20중앙역
+
+---
+
+### 12. CGV 시간표 조회
+
+**설명**: 날짜/극장/영화 조건으로 CGV 상영 시간표를 조회합니다. theaterCode가 없으면 keyword 또는 lat,lng 기준으로 가장 가까운 극장을 먼저 선택합니다. 잔여 좌석은 각 회차의 \`remainingSeats\` 필드로 함께 내려옵니다.
+
+**URL**: ${baseUrl}/api/cgv/timetable?playDate={YYYYMMDD}
+
+**선택 파라미터**:
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- theaterCode: 극장 코드 (예: 0056)
+- movieCode: 영화 코드
+- keyword: 위치 키워드 (예: 안산 중앙역, 강남역)
+- lat: 위도
+- lng: 경도
+- limit: 최대 결과 수 (기본값: 50)
+
+**예시**:
+- ${baseUrl}/api/cgv/timetable?playDate=20260304&theaterCode=0056
+- ${baseUrl}/api/cgv/timetable?playDate=20260315&keyword=안산%20중앙역
+- ${baseUrl}/api/cgv/timetable?playDate=20260304&movieCode=200001
+
+---
+
+### 13. 롯데시네마 주변 지점 찾기
+
+**설명**: 위치 키워드 또는 사용자 좌표 기준으로 롯데시네마 지점을 거리순으로 조회합니다.
+
+**URL**: ${baseUrl}/api/lottecinema/theaters?keyword={위치키워드}
+
+**선택 파라미터**:
+- keyword: 위치 키워드 (예: 안산 중앙역, 잠실역)
+- lat: 위도 (keyword가 없을 때 기본값: 37.5665)
+- lng: 경도 (keyword가 없을 때 기본값: 126.978)
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- limit: 최대 결과 수 (기본값: 10)
+
+**예시**:
+- ${baseUrl}/api/lottecinema/theaters?keyword=안산%20중앙역
+- ${baseUrl}/api/lottecinema/theaters?lat=37.5133&lng=127.1042
+
+---
+
+### 14. 롯데시네마 영화/회차 목록
+
+**설명**: 날짜/지점/영화 조건으로 롯데시네마 영화와 상영 회차를 조회합니다. theaterId가 없으면 위치 키워드 기준 최근접 지점을 선택할 수 있습니다.
+
+**URL**: ${baseUrl}/api/lottecinema/movies?playDate={YYYYMMDD}
+
+**선택 파라미터**:
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- theaterId: 지점 ID (예: 1016)
+- movieId: 대표 영화 코드 (예: 23816)
+- keyword: 위치 키워드 (예: 안산 중앙역)
+- lat: 위도 (theaterId가 없을 때 사용)
+- lng: 경도 (theaterId가 없을 때 사용)
+
+**예시**:
+- ${baseUrl}/api/lottecinema/movies?playDate=20260315&keyword=안산%20중앙역
+- ${baseUrl}/api/lottecinema/movies?playDate=20260310&theaterId=1016
+- ${baseUrl}/api/lottecinema/movies?playDate=20260310&theaterId=1016&movieId=23816
+
+---
+
+### 15. 롯데시네마 잔여 좌석 조회
+
+**설명**: 영화/지점/날짜 기준으로 회차별 잔여 좌석 수를 조회합니다. theaterId가 없으면 위치 키워드 기준 최근접 지점을 선택할 수 있습니다.
+
+**URL**: ${baseUrl}/api/lottecinema/seats?playDate={YYYYMMDD}
+
+**선택 파라미터**:
+- playDate: 조회 날짜 (YYYYMMDD, 기본값: 오늘)
+- theaterId: 지점 ID
+- movieId: 대표 영화 코드
+- keyword: 위치 키워드 (예: 안산 중앙역)
+- lat: 위도 (theaterId가 없을 때 사용)
+- lng: 경도 (theaterId가 없을 때 사용)
+- limit: 최대 결과 수 (기본값: 50)
+
+**예시**:
+- ${baseUrl}/api/lottecinema/seats?playDate=20260315&keyword=안산%20중앙역
+- ${baseUrl}/api/lottecinema/seats?playDate=20260310&theaterId=1016&movieId=23816
+
+---
+
+`;
+}

package/dist/services/cgv/client.js

@@ -113,7 +113,12 @@ export async function fetchCgvTimetable(params) {
     const timetableBySite = await fetchTimetableBySite(playDate, theaterCode, params);
     if (timetableBySite.length > 0) {
         if (params.movieCode) {
-            return timetableBySite.filter((item) => item.movieCode === params.movieCode);
+            const filteredByMovie = timetableBySite.filter((item) => item.movieCode === params.movieCode);
+            if (filteredByMovie.length > 0) {
+                return filteredByMovie;
+            }
+            const timetableByMovieCode = await fetchTimetableByMovieCode(playDate, theaterCode, params.movieCode, params);
+            return timetableByMovieCode.length > 0 ? timetableByMovieCode : timetableBySite;
         }
         return timetableBySite;
     }

package/dist/services/cgv/index.js

@@ -18,9 +18,9 @@ class CgvService {
     metadata = CGV_METADATA;
     getTools() {
         return [
-            createFindTheatersTool(this.options.zyteApiKey),
-            createSearchMoviesTool(this.options.zyteApiKey),
-            createGetTimetableTool(this.options.zyteApiKey),
+            createFindTheatersTool(this.options.zyteApiKey, this.options.googleMapsApiKey),
+            createSearchMoviesTool(this.options.zyteApiKey, this.options.googleMapsApiKey),
+            createGetTimetableTool(this.options.zyteApiKey, this.options.googleMapsApiKey),
         ];
     }
 }

package/dist/services/cgv/location.js

@@ -0,0 +1,235 @@
+/**
+ * CGV 위치 해석 및 근처 극장 조회 보조 모듈
+ */
+import { fetchJson } from '../../utils/http.js';
+import { fetchCgvTheaters } from './client.js';
+const DEFAULT_TIMEOUT_MS = 15000;
+const USER_GEOCODE_CACHE_TTL_MS = 60 * 60 * 1000;
+const THEATER_GEOCODE_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_CANDIDATE_THEATERS = 12;
+const LOCATION_STOPWORDS = new Set([
+    'cgv',
+    '극장',
+    '영화',
+    '주변',
+    '근처',
+    '오늘',
+    '상영',
+    '시간표',
+    '좌석',
+    '잔여',
+    '찾아',
+    '주세요',
+    '주세요요',
+    '역',
+]);
+const BRAND_PATTERN = /\b(?:cgv|씨지브이)\b/giu;
+const TRAILING_INTENT_PATTERN = /\s+(?:극장|영화관|영화|상영작|시간표|좌석|잔여좌석|남은좌석|목록|찾고|찾아|찾아서|알려|보여|추천|조회|확인|해주세요|해줘).*/u;
+const userGeocodeCache = new Map();
+const theaterGeocodeCache = new Map();
+function calculateDistanceKm(lat1, lng1, lat2, lng2) {
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLng = toRad(lng2 - lng1);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return 6371 * c;
+}
+function isValidCoordinate(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function normalizeWhitespace(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function normalizeText(text) {
+    return text.replace(/\s+/g, '').toLowerCase();
+}
+function sanitizeLocationKeyword(keyword) {
+    const trimmed = normalizeWhitespace(keyword);
+    if (trimmed.length === 0) {
+        return '';
+    }
+    let sanitized = normalizeWhitespace(trimmed.replace(BRAND_PATTERN, ' '));
+    const nearbyMatch = sanitized.match(/^(.+?)\s*(?:근처|주변)\s*(?:극장|영화관)?(?:\s.*)?$/u);
+    if (nearbyMatch?.[1]) {
+        sanitized = normalizeWhitespace(nearbyMatch[1]);
+    }
+    else {
+        sanitized = normalizeWhitespace(sanitized.replace(TRAILING_INTENT_PATTERN, ''));
+    }
+    return sanitized || trimmed;
+}
+function extractLocationTokens(...values) {
+    const tokens = new Set();
+    for (const value of values) {
+        const matches = (value || '').match(/[0-9A-Za-z가-힣]+/g) || [];
+        for (const match of matches) {
+            const normalized = normalizeText(match);
+            if (normalized.length < 2 || LOCATION_STOPWORDS.has(normalized)) {
+                continue;
+            }
+            tokens.add(normalized);
+        }
+    }
+    return [...tokens];
+}
+function scoreTheaterName(theaterName, tokens) {
+    const normalized = normalizeText(theaterName);
+    return tokens.reduce((score, token) => (normalized.includes(token) ? score + 1 : score), 0);
+}
+async function geocodeAddress(query, options, cacheKey, ttlMs, cache) {
+    const apiKey = (options.googleMapsApiKey || '').trim();
+    const trimmedQuery = query.trim();
+    if (apiKey.length === 0 || trimmedQuery.length === 0) {
+        return null;
+    }
+    const cached = cache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+    }
+    const endpoint = new URL('https://maps.googleapis.com/maps/api/geocode/json');
+    endpoint.searchParams.set('address', trimmedQuery);
+    endpoint.searchParams.set('key', apiKey);
+    const body = await fetchJson(endpoint.toString(), {
+        method: 'GET',
+        timeout: options.timeout || DEFAULT_TIMEOUT_MS,
+        headers: { Accept: 'application/json' },
+    });
+    const firstResult = body.status === 'OK' ? body.results?.[0] : null;
+    const latitude = firstResult?.geometry?.location?.lat;
+    const longitude = firstResult?.geometry?.location?.lng;
+    const value = typeof latitude === 'number' && typeof longitude === 'number'
+        ? {
+            latitude,
+            longitude,
+            formattedAddress: firstResult?.formatted_address || null,
+        }
+        : null;
+    cache.set(cacheKey, {
+        expiresAt: Date.now() + ttlMs,
+        value,
+    });
+    return value;
+}
+export async function resolveCgvLocation(params, options = {}) {
+    const keyword = sanitizeLocationKeyword((params.keyword || '').trim());
+    const hasCoordinates = isValidCoordinate(params.latitude) && isValidCoordinate(params.longitude);
+    if (hasCoordinates) {
+        return {
+            keyword: keyword.length > 0 ? keyword : null,
+            latitude: params.latitude,
+            longitude: params.longitude,
+            geocodeUsed: false,
+            formattedAddress: null,
+        };
+    }
+    if (keyword.length === 0) {
+        return {
+            keyword: null,
+            latitude: null,
+            longitude: null,
+            geocodeUsed: false,
+            formattedAddress: null,
+        };
+    }
+    const geocoded = await geocodeAddress(keyword, options, `user:${keyword}`, USER_GEOCODE_CACHE_TTL_MS, userGeocodeCache);
+    return {
+        keyword,
+        latitude: geocoded?.latitude ?? null,
+        longitude: geocoded?.longitude ?? null,
+        geocodeUsed: Boolean(geocoded),
+        formattedAddress: geocoded?.formattedAddress ?? null,
+    };
+}
+async function geocodeCgvTheater(theater, options) {
+    const cleanName = theater.theaterName.replace(/^CGV\s*/i, '').trim();
+    const geocoded = await geocodeAddress(`대한민국 CGV ${cleanName}`, options, `theater:${theater.theaterCode}:${cleanName}`, THEATER_GEOCODE_CACHE_TTL_MS, theaterGeocodeCache);
+    return geocoded
+        ? {
+            latitude: geocoded.latitude,
+            longitude: geocoded.longitude,
+            address: geocoded.formattedAddress,
+        }
+        : null;
+}
+function pickCandidateTheaters(theaters, tokens) {
+    if (tokens.length === 0) {
+        return theaters.slice(0, MAX_CANDIDATE_THEATERS);
+    }
+    const scored = theaters
+        .map((theater) => ({ theater, score: scoreTheaterName(theater.theaterName, tokens) }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || left.theater.theaterName.localeCompare(right.theater.theaterName))
+        .map((item) => item.theater);
+    return scored.slice(0, MAX_CANDIDATE_THEATERS);
+}
+export async function fetchCgvNearbyTheaters(params, options = {}) {
+    const limit = Math.max(1, params.limit || 10);
+    const timeout = params.timeout || DEFAULT_TIMEOUT_MS;
+    const theaters = await fetchCgvTheaters({
+        playDate: params.playDate,
+        regionCode: params.regionCode,
+        timeout,
+        zyteApiKey: options.zyteApiKey,
+    });
+    const location = await resolveCgvLocation(params, options);
+    const tokens = extractLocationTokens(location.keyword, location.formattedAddress);
+    const hasGoogleKey = (options.googleMapsApiKey || '').trim().length > 0;
+    if (tokens.length === 0 && !hasGoogleKey) {
+        return {
+            ...location,
+            playDate: params.playDate,
+            regionCode: params.regionCode || null,
+            count: 0,
+            theaters: [],
+        };
+    }
+    const candidates = pickCandidateTheaters(theaters, tokens);
+    const resolvedCandidates = await Promise.all(candidates.map(async (theater) => {
+        const geocoded = await geocodeCgvTheater(theater, options);
+        const distanceKm = geocoded && location.latitude !== null && location.longitude !== null
+            ? Number(calculateDistanceKm(location.latitude, location.longitude, geocoded.latitude, geocoded.longitude).toFixed(2))
+            : null;
+        return {
+            ...theater,
+            latitude: geocoded?.latitude ?? null,
+            longitude: geocoded?.longitude ?? null,
+            distanceKm,
+            address: geocoded?.address ?? null,
+        };
+    }));
+    const sorted = resolvedCandidates.sort((left, right) => {
+        const leftDistance = left.distanceKm ?? Number.POSITIVE_INFINITY;
+        const rightDistance = right.distanceKm ?? Number.POSITIVE_INFINITY;
+        return leftDistance - rightDistance || left.theaterName.localeCompare(right.theaterName);
+    });
+    return {
+        ...location,
+        playDate: params.playDate,
+        regionCode: params.regionCode || null,
+        count: sorted.slice(0, limit).length,
+        theaters: sorted.slice(0, limit),
+    };
+}
+export async function resolveCgvNearestTheater(params, options = {}) {
+    const nearby = await fetchCgvNearbyTheaters({
+        ...params,
+        limit: 1,
+        timeout: params.timeout,
+    }, options);
+    return {
+        location: {
+            keyword: nearby.keyword,
+            latitude: nearby.latitude,
+            longitude: nearby.longitude,
+            geocodeUsed: nearby.geocodeUsed,
+            formattedAddress: nearby.formattedAddress,
+        },
+        theater: nearby.theaters[0] || null,
+    };
+}
+export function __testOnlyClearCgvLocationCaches() {
+    userGeocodeCache.clear();
+    theaterGeocodeCache.clear();
+}