feat(S15P11A705-339): 단어형 질의의 본문 문자열 검색과 RRF 병합 (검증 게이트 통과)

[colosair]

요약

검색 고도화 트랙의 back 몫을 dev 에 반영한다. 본문에 질의 문자열이 그대로 있는 기록을 찾아 벡터 결과와 합치는 경로를 추가했다. 기본 꺼짐 플래그 뒤에 있어 이 병합으로 검색 동작은 바뀌지 않는다.

3레포(docs·back·ai)를 같은 이름의 통합 브랜치에서 함께 준비해 한 번에 릴리스한다. docs 계약 개정(3c28c01)은 병합 완료, ai 는 ai#118 로 함께 올라가 있다.

Jira

• S15P11A705-339 (검색 고도화 — back 문자열 병합)
• https://ssafy.atlassian.net/browse/S15P11A705-339

변경 사항

• LexicalContextRepository(신설) — core.context 에서 요청자 소유·삭제되지 않은 본문의 부분일치를 찾는다. 기록당 대표 Context 하나를 고르고, LIKE 문법 글자(%·_·\)는 이스케이프해 글자로 취급한다.
• LexicalSearchProperties(신설) — pinlog.search.lexical.enabled(기본 false) · word-query-max-chars(기본 5, ai 의 같은 뜻 설정과 일치해야 한다).
• RecordSearchService — FastAPI 응답을 기록 단위로 정리한 직후 병합 단계를 넣었다. 단어형 질의에서만 문자열 매치를 조회해 RRF(k=60)로 재정렬하고, size 절단은 재정렬 뒤 한 번만 한다. 문자열 후보도 기존 Core 재검증을 그대로 지난다.
• backend-ci.yml — 통합 브랜치를 트리거에 추가(검색 고도화 작업 PR 의 base 가 dev 가 아니었다).
• IntegrationContainerSupport — 테스트 컨테이너 postgres 연결 한도 상향. 컨텍스트가 늘며 기본 한도(100)를 넘겨 기동이 실패했다.
• 문서 — 구현 리포트 BI-43, 작업 로그.

검증

• 테스트 우선으로 진행 — 신규 12건 중 병합을 요구하는 6건이 구현 전 실패(RED)함을 확인한 뒤 구현, 전건 통과(GREEN)
• 회귀 — ./gradlew clean check --no-daemon 통과. RecordSearchApiTests 에 「기본값 꺼짐 = 현행 동일」 계약 1건 추가
• 검증 게이트 5기준 전량 통과 — back+ai 를 함께 띄워 사용자와 같은 경로(쿠키 인증·CSRF 포함)로 측정. 특히 신한 회복은 이 문자열 경로의 몫이며 전체 경로에서 실증했다. 증거는 ai 레포 .search/gate_*.json

리뷰 포인트

1. 기본 꺼짐이 안전 근거다. 플래그가 false 인 상태가 현행과 동일함을 계약 테스트와 게이트 기준 ④가 이중으로 고정한다.
2. 문자열 단독 항목의 similarity 는 0.0 이다. 벡터 컷을 통과하지 못해 실을 코사인이 없다. 응답 계약상 숫자가 필수이고(front 스키마), 0.0 은 실제 코사인이 만들 수 없는 값이라 구분 표지도 된다. 벡터 후보의 값은 원 코사인 그대로다.
3. 실측을 런타임에 그대로 옮길 수 없던 3지점(문자열 목록의 순위 기준·문자열 단독 후보의 점수 항·similarity 대체값)의 판단과 근거는 BI-43 에 적었다. 전부 「컷 탈락 후보의 코사인이 FastAPI 밖으로 나오지 않는다」에서 나온 제약이다.
4. 병합 방식은 merge commit 이다. 통합 브랜치에 여러 작업이 쌓여 있어 squash 하면 단위별 이력이 사라진다. 조직 표준이 squash 를 「GitHub 이 강제하지 않는 운영 convention」으로 분류한다.

미결 / 후속

• 이 병합은 운영 배포를 유발한다(이미지 발행 → infra 자동 갱신 → Argo CD). 플래그가 꺼져 있어 동작은 불변이지만, 되돌릴 때는 dev revert PR 이 유일한 정상 경로다(infra values 만 되돌리면 자동화가 다시 앞으로 민다).
• 문자열 매치의 의미 검증(어절 중간 시작 일치·동형어)은 이 코퍼스에서 사례를 만들 수 없어 운영 데이터 재평가 조건으로 남는다.

🤖 Generated with Claude Code