k-parent-festival-finder

name	k-parent-festival-finder
description	대한민국 부모를 위한 가족 축제·행사 찾기 스킬. 한국관광공사 TourAPI searchFestival로 날짜·지역 기준 축제를 검색하고, 가족(아이) 동반 적합도를 정리해 추천한다. "이번 주말 가족 축제", "다음 달 우리 동네 행사", "아이랑 갈 만한 봄 축제" 같은 요청에 사용. 시작·종료일이 있는 명명된 축제·행사 전용이며, 상시 놀거리·실내 장소는 k-parent-play-finder, 여행 코스는 k-parent-travel-recommender.

k-parent-festival-finder

날짜와 지역으로 진행 중/예정 축제를 찾아, 아이 동반 가족 관점에서 정리해 추천하는 스킬.

데이터 소스 (deterministic package)

• k-parent-source-tourapi
  • searchFestival({ eventStartDate, eventEndDate, areaCode, sigunguCode }) → /searchFestival2
  • 반환 항목: { contentId, title, addr, startDate, endDate, image, mapx, mapy, tel, areaCode }

환경변수: KSKILL_TOURAPI_KEY (data.go.kr serviceKey). 없으면 status: missing_config 에러.

데이터 계약 (envelope & 정규화)

• 응답 봉투: response.body.items.item — 배열 또는 단일 객체 모두 처리(extractItems).
• 날짜는 YYYYMMDD → YYYY-MM-DD로 정규화(startDate/endDate).
• eventStartDate는 YYYYMMDD 형식 필수. 누락 시 함수가 에러를 던진다.
• areaCode는 TourAPI 지역코드(예: 1=서울). 시군구는 sigunguCode.

신선도 (freshness)

• 각 축제의 source.freshness.status 확인. stale이면 일정 변동 가능성을 안내.
• 축제 일정/운영은 변동이 잦으므로 결과에 항상 공식 출처(주최/관광공사) 확인 안내 포함.

워크플로

1. 기간 결정: 사용자가 "이번 주말/다음 달" 등으로 말하면 오늘 날짜(시스템 제공) 기준으로 eventStartDate(YYYYMMDD) 계산. 종료일 필터가 필요하면 eventEndDate.
2. 지역 결정: 지역명 → areaCode 매핑(필요 시 사용자 확인). 전국이면 areaCode 생략 후 결과를 지역별로 묶음.
3. searchFestival(...) 호출(키 없으면 오프라인 불가 → 사용자에게 키 발급 안내).
4. 가족 적합도(family suitability) 정리 — 각 축제에 대해:
   • 제목/주소/카테고리로 아이 동반 적합도 추정(예: "어린이/가족/체험" 키워드). 단정하지 말고 추정 표기.
   • 기간(startDate~endDate)과 현재 날짜 비교해 진행중/예정/종료 표시.
   • 위치(mapx/mapy)와 주소, 연락처(tel), 대표 이미지.
   • 비용/입장료는 데이터에 없으면 "확인 필요(공식)", 임의 생성 금지.
5. 정렬: 시작일 임박 순 또는 거리(좌표) 순.

가드레일 (approval)

• 조회·추천만 수행. 예매/티켓 구매/신청은 실행하지 않는다.
• 결제·신청·예약·취소는 normalizeActionCandidate 후보로만 제시하고 명시적 승인 후 공식 사이트로 핸드오프.
• 아동 개인정보를 입력·저장하지 않는다.

관련 문서

• docs/features/k-parent-festival-finder.md