Feat/6 kakao local enrichment

[KyungminPark-steck]

✨ 무엇을 바꿨나요?

LLM이 추출한 상호명/주소를 기반으로 Kakao Local API에서 실제 장소 후보를 검색하고, 최종 선택된 장소를 job_results에 저장하도록 worker pipeline을 확장했습니다.

/jobs/{jobId}/result 응답에서도 Kakao 장소 후보와 최종 선택 장소를 반환합니다.

🔗 관련 이슈

Closes #6

💡 왜 바꿨나요?

이전 단계에서는 caption에서 store_name, address를 추출해 extraction_result로 저장하는 데까지 연결했습니다.

이번 단계에서는 추출된 상호명/주소를 실제 Kakao Local 장소 정보와 연결해, Spring Boot 서버가 사용할 수 있는 확정 장소 정보를 제공해야 합니다.

팀 논의에 따라 caption의 주소는 검색 힌트로 사용하고, 실제 저장되는 장소 정보는 Kakao Local API 응답 기준으로 확정합니다.

📝 주요 변경 사항

• job_results에 Kakao 장소 결과 저장 컬럼 추가
  • place_candidates JSONB
  • selected_place JSONB
• JobRepository.upsert_job_result()에서 장소 후보/최종 장소 저장
• JobRepository.get_job_result()에서 장소 후보/최종 장소 조회
• /jobs/{jobId}/result 응답에 아래 필드 추가
  • place_candidates
  • selected_place
• Kakao Local API 응답 매핑 확장
  • kakao_place_id
  • place_name
  • category_name
  • category_group_code
  • category_group_name
  • address_name
  • road_address_name
  • x
  • y
  • place_url
  • phone
• worker pipeline에 Kakao Local enrichment 단계 연결
• KAKAO_REST_API_KEY 기반 Kakao client 생성 로직 추가
• kakao_min_place_confidence=0.7 설정 추가
• 관련 repository/schema/API/worker/Kakao client 테스트 추가

🔎 Kakao 검색 전략

처음에는 단순히 전체 주소 + 상호명으로 검색하고, 실패하면 상호명 단독으로 fallback하는 방식을 생각했습니다.

하지만 실제 Kakao Local smoke 결과에서 문제가 있었습니다.

예를 들어 금돈옥 케이스에서:

text
LLM 추출 상호명: 금돈옥
LLM 추출 주소: 서울 서초구 방배로 23길 31-6

=> 단순 fallback으로 금돈옥만 검색하면 금돈옥 청담점이 먼저 잡힐 수 있었습니다.

그래서 주소를 완전히 버리지 않고, 한국 주소 접미사 패턴을 이용해 검색 힌트를 단계적으로 넓히는 방식으로 수정했습니다.

예:서울 서초구 방배로 23길 31-6

에서 다음 순서로 검색합니다.

1. 서울 서초구 방배로 23길 31-6 + 금돈옥
2. 서울 서초구 + 금돈옥
3. 서울 서초구 방배로23길 + 금돈옥
4. 금돈옥

주소 파싱은 무거운 주소 parser를 넣지 않고, 다음 접미사를 기준으로 보수적으로 처리했습니다.

구/군: 지역 힌트
동/읍/면/리/가: 동네 힌트
로/길: 도로명 힌트

또한 검색된 후보의 주소가 추출 주소와 다르더라도 버리지는 않기로 했습니다. 대신 confidence 기준을 두어 너무 약한 후보만 제외합니다.

kakao_min_place_confidence = 0.7

⚠️ 실패/예외 처리 정책

1. KAKAO_REST_API_KEY가 없으면 Kakao client를 비활성화하고 warning 로그를 남깁니다.
2. Kakao 인증/설정 오류는 error 로그를 남기되 job 전체 실패로 전파하지 않습니다.
3. Kakao 검색 실패 또는 결과 없음은 job 성공으로 처리합니다.

이 경우:
place_candidates=[]
selected_place=null

🧪 테스트

..venv\Scripts\python.exe -m pytest
결과:

53 passed

🧪 실제 Kakao Local smoke

로컬 artifact의 HF extraction 결과를 기반으로 실제 Kakao Local API를 호출해 확인했습니다.

생성 artifact:

artifacts/kakao_local_enrichment_samples.json
요약:

total=9
selected_count=6
error_count=0

올바르게 선택된 장소 예시:
#2 커먼맨션 | FD6 | x=126.97001457793 | y=37.5727427657281
#3 문보핫팟 | FD6 | x=127.05109755722185 | y=37.52529073455959
#4 요리미치 | FD6 | x=127.07641826816246 | y=37.55899426771555
#5 금돈옥 방배점 | FD6 | x=126.989198471873 | y=37.4866454677104
#6 한사발포차 양재점 | FD6 | x=127.03577238878559 | y=37.485523295753126
#7 인바이트 | CE7 | x=126.908674235964 | y=37.55588334709647
#1, #8, #9는 Kakao Local 문제가 아니라 LLM이 상호명을 잘못 추출한 케이스였습니다.

#1 실제: 후루사토 / LLM: 안주 오마카세집
#8 실제: 방울과꼬막 / LLM: 한우사골칼국수
#9 실제: 호이식 / LLM: 한옥 닭 칼국수
이 부분은 다음 이슈에서 caption marker fallback으로 보완할 예정입니다.