!신청 사랑하긴 그 긴거 : 개떡같이 말해도 찰떡같이 알아듣는 LLM 기반 신청곡 매칭 로직

!신청곡 아이유 조은날
!sr IU/좋은날
신청 밤편지요
잠깐 오는 비 신청할게요
버즈 그 신나는 노래 아무거나
여러분의 등록금이 펑펑 이거 신청해요

신청이 완료되었습니다        <- 봇 응답
수강신청 망했어              <- 잡담
!출첵                       <- 다른 명령어
갱신 신청했는데 자꾸 해외나가고  <- 문의
신청자가 170명이 넘은건에 대하여 <- 잡담

var standardRequestPrefixes = []string{
	"!노래신청",
	"!신청곡",
	"!곡신청",
	"!신청",
	"!sr",
}

separators: []string{"-", "/", "\u2013", "\u2014"},

private static readonly TIER1_PREFIXES = [
  '!노래신청', // 5
  '!신청곡',   // 4
  '!곡신청',   // 4
  '!신청',     // 3
];

private static readonly TIER2B_WHITELIST = ['!sr'];

private static readonly TIER2A_NOISE_PREFIXES = [
  '신청이 완료',   // 봇 응답
  '신청 실패',     // 봇 응답
  '신청자',        // 잡담
  '신청창',        // 잡담
  '신청은',        // 잡담
  '신청을',        // 잡담
  '신청에',        // 잡담
  '신청도',        // 잡담
  '신청이용',      // 잡담
  '신청이야',      // 잡담
  '신청한사람',    // 잡담
  '신청해야',      // 잡담
  '신청햇',        // 잡담
  '신청할꺼',      // 잡담
  '신청할까',      // 잡담
  '신청해서',      // 잡담
  '신청하고',      // 잡담 (애매: "신청하고 싶다" 등은 신청 의도지만 prefix로는 무시)
];

reason: noise.startsWith('신청이 완료') || noise === '신청 실패'
  ? 'bot_message'
  : 'noise_word',

const after = message.substring('신청'.length);
if (after === '' || /^[\s,!?.]/u.test(after)) {

// separator(하이픈 / 슬래시 / en dash / em dash) 포함 시 신청 의도 강함 → tier2b 진입.
// `!출첵 / !멤버 / !공지`처럼 단어 단독 명령어는 separator 없으니 통과 안 함.
// `!아이유 - 밤편지`, `!IU/좋은날`, `!10cm-봄이 좋냐` 모두 cover.
// separator 양쪽에 한 글자 이상 있어야 함 (`!--` 같은 노이즈 제외).
const after = message.substring(1).trim();
const hasSeparator = /\S[-/\u2013\u2014]\S|\S [-/\u2013\u2014] \S/.test(after);
if (hasSeparator && after.length >= 3) {

!출첵            -> ignored (구분자 없는 단어 하나짜리 명령)
!멤버            -> ignored
!공지            -> ignored
!투표 1          -> ignored
!프로필          -> ignored
!sql injection   -> ignored (!sr 아닌 다른 명령)
!아이유 - 밤편지  -> tier2b
!BTS / Dynamite  -> tier2b
!10cm-봄이 좋냐   -> tier2b

private static readonly TIER3_REQUEST_VERBS = [
  '신청합니다',
  '신청이요',
  '신청해주세요',
  '신청 부탁',
  '신청부탁',
  '신청드려요',
  '신청드립니다',
  '신청해도',
  '신청가능',
  '신청할게요',
  '신청할께요',
  '신청해요',
  '신청곡 해도',
  '신청곡 가능',
  '신청곡 부탁',
  '신청곡 받',
];

private static readonly TIER3_NOISE_SUBSTRINGS = [
  '<음표 그림문자> 신청',
  '신청이 완료',
  '신청 실패',
  '신청곡 리스트에 추가',
  '신청곡 양식',
  '수강신청',
  '가입신청',
  '교환신청',
  '산재신청',
  '현피신청',
  '재입고 알림신청',
  '재입고알림신청',
  '갱신 신청',
  '면허신청',
  '청구신청',
  '환불신청',
];

export type TierClassificationReason =
  | 'request_command_prefix'      // 채널의 requestCommand(`!신청` 등)
  | 'exclam_request_variant'      // `!신청곡 / !노래신청 / !곡신청 / !sr`
  | 'request_word_prefix'         // `신청 ...`
  | 'exclam_whitelisted_command'  // `!sr` 같은 신청 alias 명령
  | 'request_word_contained'      // 메시지 중간에 `신청` + 신청 동사
  | 'bot_message'                 // 봇 응답
  | 'noise_word'                  // `수강신청`, `갱신 신청` 등
  | 'no_signal';                  // 매칭 신호 없음

// Step 1: YouTube URL (Tier 1만)
if (tier === 'tier1') { ... }

// Step 4: GlobalSong cross-streamer alias (Tier 1/2만)
if (tier !== 'tier3') { ... }

// Step 5: 자모 단위 fuzzy (Tier 1/2만), 결과는 LLM 컨텍스트에도 사용
if (tier !== 'tier3') { ... }

// Step 6: LLM context-rich matcher (Tier 1만)
if (tier === 'tier1' && this.llmMatcher.isConfigured()) { ... }

export const TIER_THRESHOLDS: Record<Exclude<MatchTier, 'ignored'>, number> = {
  tier1: 0.5,
  tier2a: 0.7,
  tier2b: 0.7,
  tier3: 0.95,
};

function tierBase(tier: MatchTier): number {
  const base: Record<MatchTier, number> = {
    tier1: 0.85,
    tier2a: 0.85,
    tier2b: 0.85,
    tier3: 0.95,
    ignored: 0,
  };
  return base[tier];
}

private normalizeText(text: string): string {
  if (!text) return '';
  return text
    .normalize('NFKC')
    .toLowerCase()
    .replace(/[\s\-_]/g, '')
    .replace(
      /[^\w가-힣ᄀ-ᇿㄱ-ㅣぁ-んァ-ヺー〜一-鿿㐀-䶿]/g,
      '',
    );
}

private indexSongs(songs: ...) {
  return songs.map((song) => ({
    song,
    normTitle: this.normalizeText(song.title),
    normArtist: this.normalizeText(song.artist.name),
  }));
}

private isRandomKeyword(normalized: string): boolean {
  return normalized === '랜덤' || normalized === 'random';
}

const titleAliases = song.globalSong.aliases?.map((a) => a.normAliasTitle) ?? [];
if (!titleAliases.includes(normTitle)) continue;

if (normArtist) {
  const artistAliases = song.globalSong.globalArtist?.aliases?.map((a) => a.normAlias) ?? [];
  if (!artistAliases.includes(normArtist)) continue;
}

const swapExact = indexed.find(
  (item) =>
    item.normTitle === normalizedArtist &&
    item.normArtist === normalizedTitle,
);

const partialScored = indexed
  .map((item) => ({
    item,
    score:
      this.calculateSimilarity(item.normArtist, normalizedArtist) * 0.4 +
      this.calculateSimilarity(item.normTitle, normalizedTitle) * 0.6,
  }))
  .filter((x) => x.score > 0.3)
  .sort((a, b) => b.score - a.score)
  .slice(0, 5);

if (partialScored.length === 1) {
  // 자동 매칭
} else if (
  partialScored.length > 1 &&
  partialScored[0].score - partialScored[1].score >= 0.3
) {
  // 자동 매칭
} else if (partialScored.length > 1) {
  // candidates만 반환, matched: false
}

score:
  this.calculateSimilarity(item.normArtist, normalizedTitle) * 0.4 +
  this.calculateSimilarity(item.normTitle, normalizedArtist) * 0.6,

let score = 0;
if (normTitle === normalized) score = 1.0;
else if (normTitle.includes(normalized))
  score = normalized.length / normTitle.length;
else if (normArtist === normalized) score = 0.5;
else if (normArtist.includes(normalized))
  score = 0.3 * (normalized.length / normArtist.length);

if (normalized.length >= 4) {
  const lyricsResult = await this.matchByLyrics(channelId, normalized);
  ...
}

private async matchByLyrics(channelId: number, normalized: string) {
  const hits = await this.prisma.song.findMany({
    where: { channelId, lyricsText: { contains: normalized } },
    select: { id: true },
    take: 11,
  });
  if (hits.length === 0 || hits.length > 10) return { matched: false };
  if (hits.length === 1) { /* 자동 매칭 */ }
  // 2-10 hits: return candidates without auto-matching
}

const matchedCat = allSongs
  .flatMap((s) => s.songCategories)
  .find((sc) => sc.category.name === keyword);

private calculateSimilarity(str1: string, str2: string): number {
  if (str1 === str2) return 1;
  if (!str1 || !str2) return 0;

  // 포함 관계 확인
  if (str1.includes(str2) || str2.includes(str1)) {
    const shorter = str1.length < str2.length ? str1 : str2;
    const longer = str1.length < str2.length ? str2 : str1;
    return shorter.length / longer.length;
  }

  // Levenshtein 거리 기반 유사도
  const distance = this.levenshteinDistance(str1, str2);
  const maxLength = Math.max(str1.length, str2.length);
  return 1 - distance / maxLength;
}

private levenshteinDistance(str1: string, str2: string): number {
  const m = str1.length;
  const n = str2.length;
  if (m === 0) return n;
  if (n === 0) return m;

  const dp: number[][] = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
  for (let i = 0; i <= m; i++) dp[i][0] = i;
  for (let j = 0; j <= n; j++) dp[0][j] = j;

  for (let i = 1; i <= m; i++) {
    for (let j = 1; j <= n; j++) {
      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
      dp[i][j] = Math.min(
        dp[i - 1][j] + 1,
        dp[i][j - 1] + 1,
        dp[i - 1][j - 1] + cost,
      );
    }
  }
  return dp[m][n];
}

const HANGUL_BASE = 0xac00; // '가'
const HANGUL_END = 0xd7a3;  // '힣'

const CHO = ['ㄱ','ㄲ','ㄴ','ㄷ','ㄸ','ㄹ','ㅁ','ㅂ','ㅃ','ㅅ','ㅆ','ㅇ','ㅈ','ㅉ','ㅊ','ㅋ','ㅌ','ㅍ','ㅎ'];
const JUNG = ['ㅏ','ㅐ','ㅑ','ㅒ','ㅓ','ㅔ','ㅕ','ㅖ','ㅗ','ㅘ','ㅙ','ㅚ','ㅛ','ㅜ','ㅝ','ㅞ','ㅟ','ㅠ','ㅡ','ㅢ','ㅣ'];
const JONG = ['','ㄱ','ㄲ','ㄳ','ㄴ','ㄵ','ㄶ','ㄷ','ㄹ','ㄺ','ㄻ','ㄼ','ㄽ','ㄾ','ㄿ','ㅀ','ㅁ','ㅂ','ㅄ','ㅅ','ㅆ','ㅇ','ㅈ','ㅊ','ㅋ','ㅌ','ㅍ','ㅎ'];

function decomposeChar(ch: string): string {
  const code = ch.charCodeAt(0);
  if (code < HANGUL_BASE || code > HANGUL_END) return ch;
  const idx = code - HANGUL_BASE;
  const cho = Math.floor(idx / (21 * 28));
  const jung = Math.floor((idx % (21 * 28)) / 28);
  const jong = idx % 28;
  return CHO[cho] + JUNG[jung] + JONG[jong];
}

expect(decomposeJamo('밤편지')).toBe('ㅂㅏㅁㅍㅕㄴㅈㅣ');
expect(decomposeJamo('가')).toBe('ㄱㅏ');      // 종성 없음
expect(decomposeJamo('값')).toBe('ㄱㅏㅄ');    // 겹받침은 한 글자로
expect(decomposeJamo('IU 좋은날')).toBe('IU ㅈㅗㅎㅇㅡㄴㄴㅏㄹ');

export function jamoSimilarity(a: string, b: string): number {
  const ja = decomposeJamo(a);
  const jb = decomposeJamo(b);
  if (!ja || !jb) return 0;
  const dist = levenshtein(ja, jb);
  const maxLen = Math.max(ja.length, jb.length);
  return 1 - dist / maxLen;
}

it('자모 단위 1글자 오타에 강함', () => {
  const sim = jamoSimilarity('박편지', '밤편지');
  expect(sim).toBeGreaterThan(0.85);
});

it('완전 다른 문자열 → 낮은 점수', () => {
  expect(jamoSimilarity('아이유', 'BTS')).toBeLessThan(0.3);
});

export function chosungMatch(query: string, target: string): boolean {
  if (!/^[ㄱ-ㅎ]+$/u.test(query)) return false;
  const targetChosung = extractChosung(target).replace(/[^ㄱ-ㅎ]/g, '');
  return targetChosung === query;
}

const EN_TO_KO_MAP: ReadonlyMap<string, string> = new Map([
  ['bts', '방탄소년단'], ['iu', '아이유'], ['exo', '엑소'],
  ['twice', '트와이스'], ['blackpink', '블랙핑크'], ['nct', '엔시티'],
  ['ive', '아이브'], ['lesserafim', '르세라핌'], ['newjeans', '뉴진스'],
  ['aespa', '에스파'], ['gidle', '여자아이들'], ['itzy', '있지'],
  ['stray kids', '스트레이키즈'], ['straykids', '스트레이키즈'], ['skz', '스트레이키즈'],
  ['day6', '데이식스'], ['exid', '이엑스아이디'], ['shinee', '샤이니'],
  ['snsd', '소녀시대'], ['mamamoo', '마마무'], ['fromis_9', '프로미스나인'],
  ['oasis', '오아시스'], ['radiohead', '라디오헤드'], ['queen', '퀸'],
]);

/** Jamo fuzzy DoS 방어, Levenshtein O(m×n)이라 입력 길이 cap. */
private static readonly JAMO_INPUT_MAX_CHARS = 80;

const titleScore = jamoSimilarity(cleanTitle, sTitle);
const artistScore = cleanArtist ? jamoSimilarity(cleanArtist, sArtist) : 0;
const score = cleanArtist ? titleScore * 0.7 + artistScore * 0.3 : titleScore;

.filter((x) => x.score > 0.5) // LLM 컨텍스트로 더 많이 보내기 위해 임계값 낮춤
.sort((a, b) => b.score - a.score)
.slice(0, 10);

const top = scored[0];
const next = scored[1];
const accept = top.score >= 0.85 || (next && top.score - next.score >= 0.05);

const jamoMatch = await this.tryJamoFuzzy(...);
if (jamoMatch) {
  jamoTop = jamoMatch.allCandidates;   // accept와 무관하게 항상 보관
  if (jamoMatch.accept) {
    return this.finalize(...);
  }
}

// 1) GlobalSongAlias.normAliasTitle == normTitle
return { ..., via: 'global_song_alias', score: 0.92 };

// 2) GlobalSong.normTitle == normTitle (alias는 없지만 정규 제목 일치)
return { ..., via: 'global_song_title', score: 0.88 };

// 매치 안 되면 첫 항목 (호출자가 confidence 낮춰 후처리)
return { songId: songs[0].id, globalSongId: songs[0].globalSongId! };

잠깐 오는 비            -> 소나기
무슨 한강다리 해도       -> 양화대교
배털기웃으              -> 베텔기우스
여러분의 등록금이 펑펑    -> 불꽃놀이 (하현상)
버즈 그 신나는 노래      -> 버즈의 업템포 곡 중 아무거나

You match Korean live-stream chat messages to a song in the streamer's songbook (channel_songs).
Reply ONLY with compact JSON: {"matched_song_id":number|null,"confidence":0.0-1.0,"reasoning":"<short>"}.

MATCH AGGRESSIVELY in these cases: pick a song from channel_songs whenever a plausible candidate exists:
1. Typos / fuzzy spelling: 조은날→좋은날, 박편지→밤편지, 배털기웃으→베텔기우스, 라이오테→라이언테.
2. Abbreviated or fragment title (chorus only, first phrase only, partial line).
3. Artist or title omitted / partial.
4. Thematic / topical / paraphrase references: match by what the song is about or a paraphrased
   equivalent. Prefer semantic match over single-word overlap:
   - "무슨 한강다리 해도" → 양화대교 (Han River bridge)
   - "잠깐 오는 비" → 소나기 (NOT "비가 오는 날엔": single-word "비" overlap;
     "잠깐 오는 비" is the literal definition of 소나기)
   - "쏟아지는 비" → 폭우 / 소나기 (paraphrase, not "빗속에서")
   - "첫눈 오는 날" → 첫눈 (direct, not "눈이 오던 날")
   - "부산 노래" → 부산갈매기
   - "벚꽃 노래" → 봄날, 벚꽃엔딩 등 (pick any matching, see #5)
   IMPORTANT: When two candidates exist, one with shared keyword, one with semantic/paraphrase
   match, choose the semantic match unless the keyword candidate is overwhelmingly closer in form.
5. Vague mood/style/artist descriptions: pick ANY song that matches the description
   (random tie-break OK):
   - "버즈 그 신나는 노래" → pick any uptempo 버즈 song from songbook
   - "잔잔한 발라드" → pick any ballad
   - "신해철꺼 아무거나" → pick any 신해철 song
   This is intentional: viewers often delegate the choice to the streamer.
6. Pronunciation-based matches (Korean phonetic transliteration of foreign titles/artists):
   - "배털기웃으" → 베텔기우스 (Betelgeuse, similar pronunciation)
   - "예스터데이" / "예스떼이" → Yesterday
7. Lyrics-fragment requests: viewers quote a remembered lyric line:
   - "여러분의 등록금이 펑펑" → 불꽃놀이 (하현상) if the lyrics contain that line.
   - Use lyrics_hits as primary evidence here.

CONFIDENCE GUIDE:
- Exact / near-exact title match (typos, abbreviation, fragment): 0.85-1.0
- Clear thematic / lyrics reference with one strong candidate: 0.7-0.9
- Vague description with multiple plausible candidates → pick one: 0.55-0.7
- Genuinely ambiguous between unrelated songs (or songbook has nothing close): null

Use cross_streamer_aliases and lyrics_hits as supporting evidence, but matched_song_id MUST be
a song from channel_songs (the streamer's own songbook).
NO markdown fences, NO prose outside the JSON.

'잠깐 오는 비'  ->  소나기 (0.95)
'쏟아지는 비'   ->  소나기 (0.92)
'새벽 안개'     ->  null   (오탐 없음)

this.http = axios.create({
  baseURL: 'https://openrouter.ai/api/v1',
  timeout: 8_000,
  headers: {
    'HTTP-Referer': configService.get('OPENROUTER_SITE_URL') ?? 'https://meloming.com',
    'X-Title': 'Meloming Song Matcher',
  },
});

this.model =
  configService.get('FUZZY_CHAT_DETECTION_LLM_MODEL') ??
  'anthropic/claude-haiku-4.5';

const requestBody = {
  model: this.model,
  user: 'backend:song-request-v2',
  messages: [ /* ... */ ],
  temperature: 0.1,
  max_tokens: 250,
};

private static readonly LLM_CHANNEL_SONGS_MAX = 500;

if (allSongs.length > SongMatcherV2Service.LLM_CHANNEL_SONGS_MAX) {
  const keepIds = new Set<number>();
  jamoTop.forEach((j) => keepIds.add(j.songId));
  v1Candidates?.forEach((c) => keepIds.add(c.id));
  if (crossHit) keepIds.add(crossHit.songId);

  // 같은 artist의 곡 모두 포함
  if (artistQuery) {
    const artistMatches = allSongs.filter((s) =>
      s.artist.name.toLowerCase().includes(artistQuery.toLowerCase()),
    );
    artistMatches.forEach((s) => keepIds.add(s.id));
  }

  scoped = allSongs.filter((s) => keepIds.has(s.id));
  // 빈 경우 fallback: 무조건 cap 만큼 자름 (id 오름차순)
  if (scoped.length === 0) {
    scoped = allSongs.slice(0, SongMatcherV2Service.LLM_CHANNEL_SONGS_MAX);
  }
}

fuzzyHints: jamoTop.length
  ? jamoTop.map((j) => ({
      songId: j.songId,
      score: Number(j.score.toFixed(3)),
      via: 'jamo',
    }))
  : undefined,

const trimmed = payload.trim();
const candidates: string[] = [];
if (trimmed.length >= 6 && trimmed.length <= 60) {
  candidates.push(trimmed);
}
if (trimmed.length > 60) {
  candidates.push(trimmed.slice(0, 30));
}
const tokens = trimmed.split(/\s+/).filter((t) => t.length >= 4);
for (const t of tokens.slice(0, 3)) {
  candidates.push(t);
}

const idx = matched ? body.indexOf(matched) : 0;
const start = Math.max(0, idx - 20);
const snippet = body.slice(start, start + 80);

const norm = normalizeText(titleQuery);
if (!norm || norm.length < 2) return [];

const aliases = await this.prisma.globalSongAlias.findMany({
  where: { normAliasTitle: { contains: norm.slice(0, 20) } },
  select: { /* ... */ },
  take: 10,
});

messages: [
  {
    role: 'system',
    content: [
      { type: 'text', text: systemPrompt },
      {
        type: 'text',
        text: `\n\n[CHANNEL ${ctx.channelId} SONGBOOK]\n${channelSongsBlob}`,
        cache_control: { type: 'ephemeral' },
      },
    ],
  },
  {
    role: 'user',
    content: perMessageBlob,
  },
],

const cached = usage.prompt_tokens_details?.cached_tokens ?? 0;
const promptUncached = (usage.prompt_tokens ?? 0) - cached;
if (promptUncached > 0) {
  this.metrics.songMatcherV2LlmTokensTotal.inc({ type: 'prompt' }, promptUncached);
}
if (cached > 0) {
  this.metrics.songMatcherV2LlmTokensTotal.inc({ type: 'cached_prompt' }, cached);
}
if ((usage.completion_tokens ?? 0) > 0) {
  this.metrics.songMatcherV2LlmTokensTotal.inc({ type: 'completion' }, usage.completion_tokens ?? 0);
}

// 환각 방지: LLM이 채널 노래책에 없는 song_id를 반환하면 reject
if (matchedSongId !== null) {
  const known = ctx.channelSongs.some((s) => s.songId === matchedSongId);
  if (!known) {
    this.logger.warn(
      `LLM hallucinated song_id=${matchedSongId} not in channel ${ctx.channelId} songbook, rejecting`,
    );
    return {
      matchedSongId: null,
      confidence: 0,
      reasoning: `LLM returned id ${matchedSongId} not in songbook`,
      raw,
    };
  }
}

let cleaned = raw.trim();
cleaned = cleaned.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '');
let parsed: unknown;
try {
  parsed = JSON.parse(cleaned);
} catch {
  const start = cleaned.indexOf('{');
  const end = cleaned.lastIndexOf('}');
  if (start === -1 || end === -1 || end <= start) {
    return { matchedSongId: null, confidence: 0, raw };
  }
  try {
    parsed = JSON.parse(cleaned.slice(start, end + 1));
  } catch {
    return { matchedSongId: null, confidence: 0, raw };
  }
}

const matchedSongId =
  typeof idVal === 'number' && Number.isInteger(idVal) ? idVal : null;
const confidence =
  typeof o.confidence === 'number' ? Math.max(0, Math.min(1, o.confidence)) : 0;

private redact(s: string): string {
  if (!this.apiKey) return s;
  return s.split(this.apiKey).join('***');
}

if (llmResult.matchedSongId !== null && llmResult.confidence >= 0.5) {
  const song = await this.v1.getSongById(input.channelId, llmResult.matchedSongId);
  if (song) {
    const result = this.finalize(
      tier,
      classification.reason,
      threshold,
      song,
      Math.min(0.95, llmResult.confidence),
      trace,
      v1Result.candidates,
    );

return {
  matched: false,
  candidates: v1Result.candidates,
  tier,
  reason: classification.reason,
  confidence:
    v1Result.candidates && v1Result.candidates.length > 0 ? 0.4 : 0,
  threshold,
  autoAcceptable: false,
  trace,
};

// Step 1: v1 직접 호출 (기존 동작과 동일, DB only, ~50ms).
const v1MatchId = await this.tryV1Match(matchChannelId, dto.rawArtist, dto.rawTitle);
if (v1MatchId !== undefined) {
  this.metrics.songMatcherV2OutcomesTotal.inc({ outcome: 'v1_match', tier: 'unknown' });
  return v1MatchId;
}

// Step 2: v1 실패 → v2 시도 (Tier 1이면 LLM까지 + 5-8s 가능).
const v2Enabled =
  (this.config.get<string>('SONG_MATCHER_V2_FALLBACK') ?? 'true') === 'true';
if (!v2Enabled) {
  this.metrics.songMatcherV2OutcomesTotal.inc({
    outcome: 'v1_no_match_v2_disabled',
    tier: 'unknown',
  });
  return undefined;
}

// 랜덤 신청은 백엔드가 노래책에서 곡을 추출하므로 매칭 자체가 불필요. LLM 비용 회피.
if (dto.requestType === 'RANDOM') return undefined;

export interface MatchStepTrace {
  step: string;
  algorithm:
    | 'exact' | 'alias' | 'fuzzy_levenshtein' | 'fuzzy_jamo'
    | 'fuzzy_chosung' | 'fuzzy_romanize' | 'lyrics_contains'
    | 'lyrics_semantic' | 'global_song_cross_alias' | 'youtube_url'
    | 'llm_extract' | 'category' | 'random';
  matched: boolean;
  songId?: number;
  score?: number;
  candidates?: Array<{ songId: number; score: number; title: string; artist: string }>;
  note?: string;
}

note: `no candidate above 0.5 for title="${cleanTitle}"`

note: `top=${top.score.toFixed(3)}${next ? ` next=${next.score.toFixed(3)}` : ''} accept=${!!accept}`

note:
  (llmResult.reasoning ? `reason="${llmResult.reasoning}" ` : '') +
  `channel_songs=${llmCtx.channelSongs.length} ` +
  `cross_aliases=${llmCtx.crossAliases?.length ?? 0} ` +
  `lyrics_hits=${llmCtx.lyricsHits?.length ?? 0}`,

meloming_song_matcher_v2_outcomes_total{outcome,tier}
  // v1_match / v2_rescue / both_no_match / error / v1_no_match_v2_disabled
meloming_song_matcher_v2_latency_seconds{tier,llm_called}
  // buckets: 0.05, 0.1, 0.25, 0.5, 1, 2, 4, 8, 15
meloming_song_matcher_v2_llm_calls_total{matched}
meloming_song_matcher_v2_rescues_total{tier}
meloming_song_matcher_v2_llm_tokens_total{type}
  // prompt / cached_prompt / completion

help: 'v1 missed but v2 caught, direct measure of v2 improvement',