NAVER Search API 기반 장소 검색 fallback 경로 추가

[vkehfdl1]

배경

• 사용자 위치 근처의 술집 조회 #20 의 1차 범위는 Kakao Local API 기반 (a) 지역명/역명 -> 좌표 변환 + (b) 좌표 주변 술집 후보 검색 으로 진행한다.
• 다만 Kakao upstream 장애, quota 초과, 또는 결과 품질 보강이 필요할 때를 대비해 NAVER 경로를 fallback/보조 채널로 설계해둘 필요가 있다.

목표

• k-skill-proxy 에 NAVER Search API 지역 검색 기반 fallback 경로를 추가할 수 있도록 설계/구현한다.
• 1차 목표는 영업중/메뉴/수용인원 enrichment 가 아니라 후보 장소 fallback 이다.

범위

• NAVER Search API 지역 검색 연동
• 프록시 서버 env 기반 키 주입 (NAVER_CLIENT_ID, NAVER_CLIENT_SECRET 등)
• Kakao 실패/비가용/정책적 fallback 시 NAVER 경로 사용
• 응답 스키마를 Kakao 경로와 공통 정규화

비범위

• NAVER Maps 유료 상품 기반 고급 좌표/경로 기능
• 영업시간/메뉴/수용인원 상세 enrichment

기대 결과

• Kakao 경로가 실패해도 제한된 품질의 NAVER 기반 후보 검색이 가능하다.
• 클라이언트에는 API 키가 노출되지 않는다.
• 프록시 레벨에서 rate limit / cache / allowlist 정책을 유지한다.

관련 이슈

• Relates to 사용자 위치 근처의 술집 조회 #20

[vkehfdl1]

• AI-understood issue summary

  • 이 이슈는 k-skill-proxy 에 NAVER Search API 기반 장소 검색 fallback 경로를 추가해, Kakao Local API 가 실패하거나 비가용/정책적 fallback 이 필요한 경우에도 최소한의 후보 장소 검색을 지속할 수 있게 하려는 작업으로 이해했습니다. 핵심은 enrichment 가 아니라 후보 장소 fallback 이며, 프록시 서버에서 NAVER 키를 env 로 주입하고, 결과를 Kakao 경로와 공통 스키마로 정규화하는 것입니다.

• Why this issue is needed

  • 현재 1차 범위가 Kakao Local API 에 집중되어 있어 upstream 장애, quota 초과, 혹은 특정 검색어에서 품질 편차가 생기면 전체 후보 탐색 체인이 약해질 수 있습니다.
  • 프록시 레벨 fallback 을 미리 설계해 두면 클라이언트 쪽 분기 없이도 가용성을 높일 수 있고, API 키 비노출 / allowlist / cache / rate limit 같은 기존 프록시 통제 지점을 그대로 유지할 수 있습니다.
  • 사용자 위치 근처의 술집 조회 #20 과의 관계상 “좌표 주변 술집 후보 검색” 기능을 운영 가능한 수준으로 만들기 위한 방어선으로 의미가 있습니다.

• Why this issue may not be needed

  • Kakao 경로만으로도 실제 트래픽/품질 요구를 충분히 만족한다면, 초기 단계에서 fallback 공급자를 추가하는 것은 운영 복잡도와 테스트 범위를 늘릴 수 있습니다.
  • NAVER Search API 의 결과 형식/품질이 Kakao 와 다를 수 있어, 성급한 공통화가 오히려 품질 기대치를 흐리게 만들 가능성도 있습니다.
  • 따라서 “항상 이중화”보다는, Kakao 실패 유형과 fallback 발동 조건을 명확히 정의할 때 가장 가치가 큽니다.

• Expected Outcome

  • Kakao 경로 실패/비가용 시에도 프록시가 NAVER 지역 검색으로 제한적 후보 목록을 반환합니다.
  • NAVER 자격 증명은 서버 env (NAVER_CLIENT_ID, NAVER_CLIENT_SECRET) 로만 주입되고 클라이언트에는 노출되지 않습니다.
  • NAVER 결과는 공통 응답 스키마로 정규화되어 클라이언트 소비 계약이 유지됩니다.
  • fallback 경로도 기존 프록시 정책(rate limit / cache / allowlist) 아래에서 동작합니다.

• Concise implementation plan

  1. k-skill-proxy 에 NAVER Search API 클라이언트 모듈을 추가하고 env 기반 자격 증명 로딩을 구현합니다.
  2. Kakao 검색 경로의 실패 유형(예: upstream error, timeout, quota, empty-with-policy-trigger)을 분류하고 fallback 진입 조건을 명시합니다.
  3. NAVER 응답을 현재 Kakao 정규화 스키마에 맞춰 변환하되, 좌표/주소/이름 등 공통 필드 중심으로만 매핑합니다.
  4. 프록시 레벨 cache / rate limit / allowlist 체인에 NAVER 경로를 편입합니다.
  5. Kakao 성공, Kakao 실패 후 NAVER fallback 성공, 양쪽 모두 실패하는 경우를 포함한 테스트를 추가합니다.
  6. 문서에 필요한 env, fallback 동작 조건, 품질 한계를 함께 정리합니다.

• Agent Signature

  • Posted by Codex for issue triage/review.