feat(S15P11A705-403): 검색 결과 LLM 관련도 재판정 4번째 신호 추가

[colosair]

요약

배포 직후 사용자가 발견한 검색 순위 오류(문장형 질의에 포함된 고유명사가 재작성·문자열 검색·키워드 재정렬 세 신호 모두의 사각지대에 걸려 관련 기록이 무관한 기록보다 낮은 순위로 나온 사례)를 교정하는 4번째 검색 신호다. 도메인 스키마 변경 없음.

Jira

미발급. 사용자가 실배포 버그를 직접 지시해 시작한 작업이다.

변경 사항

• app/schema/relevance.py — 요청/응답 스키마. candidates는 contextId·placeName·body, 응답은 4단계 라벨(VERY_RELEVANT~NOT_RELEVANT)
• app/client/relevance_client.py — rewrite_client.py를 본뜬 벤더 체인 전용 클라이언트. 후보 전체를 한 번의 호출로 판정하고, 요청 밖 contextId·미지 라벨은 개별 항목만 버린다(전체 재시도로 승격하지 않는다)
• app/api/internal/v1/search.py — POST /internal/v1/search/judge 신설
• app/core/config.py — search_relevance_judge_enabled(기본 false)·타임아웃·재시도 설정
• app/main.py — 클라이언트 조립·app.state 등록

설계 결정

ai(FastAPI)는 Context 본문을 저장하지 않는다(ai.context_embedding·ai.context_keyword 모두 텍스트 컬럼 없음). 그래서 back이 3신호 병합까지 끝난 최종 후보(본문 포함)를 이 엔드포인트에 보내는 구조로 갔다. "FastAPI는 본문을 반환하지 않는다"는 계약은 ai→back 응답 방향의 조항이라 이 요청(back→ai) 방향을 막지 않는다 — ContextProcessRequest.text가 이미 같은 방향의 선례다. 상세 근거는 Team-PinLog/docs PR #56(같은 트랙).

테스트 / 검증

• tests/test_relevance_client.py 6건(단일 호출·폴백·스키마 위반 영구화·연결 실패·요청 밖 id 제거·미지 라벨 제거)
• tests/test_search_relevance_judge_endpoint.py 5건(응답 조립·인증·5xx 매핑·빈 후보 422)
• pytest -q 전량 530건 통과(기존 519건 + 신규 11건, 회귀 없음)
• ruff check 통과
• tools/check_docs_index.py 통과
• 커버리지 게이트: relevance_client.py line 89% / branch 100%, relevance.py line 100%

미결 / 후속

• 기본 꺼짐 — back이 플래그를 켜기 전까지 기존 검색 동작에 영향 없음. 켜는 결정은 별도.
• 사용자가 보고한 정확한 사례(개인 배포 데이터)는 로컬 시딩 데이터에 없어 그대로 재현하지 못했다. 같은 실패 모양(본문에 질의어가 명시된 후보 vs 없는 후보)의 테스트 픽스처로 대체 검증했다.