결제 페이지 폐기하고 Spotify · YouTube · Groq 로 음악 ↔ 팝업 매칭 만들기 — POP-SPOT v1.3

// v1.3 — SpotifySearchService. 5단계 폴백 파이프라인
public Optional<Track> search(String query) {
//     ^^^^^^^^         ^^^^^ 사용자가 입력한 원문 질의 (예: "아이유 좋은날")
//     +-- null 가능성 명시. 이 5단계 모두 부족하면 empty 리턴
    return tryRaw(query)
//         ^^^^^^^^^^^^^ 1단계: 원문 그대로 Spotify 에 던짐
//                       (영문 곡이면 이게 바로 맞음. 불필요한 외부호출 없애는 일차 시도)
            .or(() -> tryGroqNormalized(query))
//          ^^                                  Optional.or — 앞이 empty 일 때만 다음 람다 실행
//                   ^^^^^^^^^^^^^^^^^^^^^^^^^  2단계: Groq 에 "이 한글 곡명·가수명을 영문 표기로" 요청
//                                              예: "아이유 좋은날" → "IU Good Day"
            .or(() -> tryEnglishOnly(query))
//                   ^^^^^^^^^^^^^^^^^^^^^^   3단계: 한글 제거·영문 토큰만 남겼 는지 재시도
//                                              (본명+영어 제목 혼합 케이스 대응)
            .or(() -> tryYoutubeSuggest(query))
//                   ^^^^^^^^^^^^^^^^^^^^^^^^^  4단계: YouTube 검색 suggestion 이 더 잘 잡아주는 경우가 있음
//                                              추천된 결과 제목을 다시 Spotify 에 넘김
            .or(() -> tryGlobal(query));
//                   ^^^^^^^^^^^^^^^^^   5단계: market=KR 없이 글로벌 카탈로그 검색
//                                        (일본·중화권 곡·기타 외국 곡 대응)
}

// v1.2 까지 — 조회 매번 YouTube Data API 호출
String videoId = youtubeApi.search(artist + " " + title);
//                          ^^^^^^ search 한 회당 100 quota units 소모
//                                  일일 한도 10,000 / 100 = 100회면 소진
//                                  많은 사용자가 같은 곡을 찾아도 구분 없이 재호출

// v1.3 — (artist, title, video_id) DB 영구 캠시. 없을 때만 API 추가
String videoId = musicTrackRepository
//                ^^^^^^^^^^^^^^^^^^^^ Spring Data JPA 레포지터·테이블명: music_track
        .findByArtistAndTitle(artist, title)
//       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 메서드명 규칙으로 자동 생성된 쿼리:
//                                            SELECT * FROM music_track WHERE artist=? AND title=?
        .map(MusicTrack::getYoutubeVideoId)
//       ^^^ Optional<MusicTrack> 에서 MusicTrack 존재 시만 내부 값 추출
//             결과: Optional<String> (레코드가 없으면 여전히 empty)
        .orElseGet(() -> {
//       ^^^^^^^^^ 캐시 미적중 시에만 람다 호출 — 지연 평가
            String fetched = youtubeApi.search(artist + " " + title);
//                                      ^^^^^^ 그제서야 YouTube Data API 호출 (100 units 소모)
            musicTrackRepository.save(
                MusicTrack.of(artist, title, fetched));
//              ^^^^^^^^^^^^^ 트랙 레코드 생성 후 적재 — 다음 동일 호출부터는 캐시 적중
            return fetched;
        });
//        ^ 결과: 캐시 적중 시 호출 한 줄로 곳바로 video_id 반환 — 외부 API 호출 0

// v1.3 — Groq 에 넘길 프롬프트. 자유 생성이 아닌 "택1" 구조
String prompt = """
//              ^^^ Text Block (Java 13+). \\n 에스케이프 없이 여러 줄 문자열
    아래 40 개 무드 중에서만 골라서 3 개 반환. 다른 단어 절대 금지.
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//  Groq 에게 "창의적으로 만들어" 가 아닌 "이 목록에서만 고르라" 명시.
//  이게 없으면 "우울한·쓸쓸한·멜랑콜리한" 등 비슷한 단어가 무한 생성돼 DB 매칭 실패
    [dreamy, energetic, retro, melancholy, ...] (40 개)
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//  이 40개는 popup 카테고리에도 동일하게 부여되어 있음
//  → Groq 답변이 "dreamy, retro, energetic" 이면 popup.mood_tags 와 바로 교집합 계산 가능
    곡 제목: %s, 가수: %s
//             ^^      ^^ 아래서 title, artist 으로 치환됨
    """.formatted(title, artist);
//      ^^^^^^^^^^ Java 15+: String::formatted. printf 처럼 %s 치환

// v1.3 — PopupCrawlOrchestrator. 매일 04:00 KST 자동 수집
@Scheduled(cron = "0 0 4 * * *", zone = "Asia/Seoul")
//         ^^^^   ^ ^ ^ ^ ^ ^   ^^^^^^^^^^^^^^^^^^^
//         |      | | | | | |   |
//         |      | | | | | |   +-- 종일제 적용 타임존. 안 적으면 서버·JVM 기본으로 실행돼
//         |      | | | | | +------- 요일 (* = 전체)
//         |      | | | | +--------- 월 (*)
//         |      | | | +----------- 일 (*)
//         |      | | +------------- 시 = 4 (04시)
//         |      | +--------------- 분 = 0
//         |      +----------------- 초 = 0  → 매일 04:00:00
//         +-------------------------- Spring 의 cron 은 6개 필드 (초까지). 리눅스 cron(5자리)과 다름
public void runOnce() {
    keywords.forEach(this::collectAndNormalize);
//  ^^^^^^^^ List<String> — 최상위 키워드 (v2.13 에서 95개로 확장됨)
//           ^^^^^^^ 경량 순차 처리 — 외부 API 속도제한도 있으니 병렬 안 함
//                   ^^^^^^^^^^^^^^^^^^^^^^^ 메서드 레퍼런스. 각 키워드마다 6단계 실행:
//                                            1) Naver 검색 API  2) Kakao 검색 API
//                                            3) Groq 정규화   4) Kakao Geocoding
//                                            5) confidence 계산  6) ≥0.8 이면 자동 게시
}