fix: browser 추천 태그 유사도에 retrieval alias 적용

[coconutcococode]

관련된 이슈

close #392

작업 내용

• #384는 server RecommendationScorer만 retrieval query planner의 curated English alias를 사용하도록 수정했고, browser handoff의 RecommendationTagMatcher는 한국어 canonical tag를 영어 상품 metadata에 literal substring matching하고 있었습니다.
• 기존 합성 재현에서 동일 입력이 server scorer 79.00 / FULL_ATTRIBUTE_MATCH, browser handoff tagSimilarity=0.00으로 갈렸습니다.
• BrowserRerankingHandoffService가 기존 RecommendationRetrievalQueryPlanner를 주입받아 matcher에 전달하고, matcher가 aliasFor(TagInput)을 우선 사용하도록 수정했습니다. alias가 없으면 기존 canonical name fallback을 유지합니다.
• 수정 후 한국어 canonical fixture 레귤러핏/베이지/라운드넥/니트가 영어 metadata regular-fit/beige/crewneck/knit에 4/4 match되어 browser tagSimilarity=1.00이 됩니다. 캐주얼(STYLE)은 분모에서 제외됩니다.

공유 사항

• parity 범위는 alias resolution뿐입니다. server의 COLOR 가중 score와 달리 browser는 기존 비가중 matched eligible tag count / eligible tag count를 유지합니다.
• eligible type SILHOUETTE/MATERIAL/DETAIL/COLOR, STYLE 제외, name + brand + categoryPath, lowercase substring, zero eligible=1.00 계약을 유지합니다.
• 4/4, 3/4, 2/4, 1/4, 0/4, alias 없는 canonical fallback, zero eligible, exact substring negative 회귀를 추가했습니다. fuzzy/boundary matcher는 도입하지 않았습니다.
• query planner ordering/fix: 검색어 예산 배분 시 태그된 속성 타입이 통째로 빠지지 않도록 수정 #385 budget, selector, Fashion-CLIP, imageSimilarity, 70/30, top10, price/value/FX/Pareto, persistence, Shopify provider API는 변경하지 않았습니다.
• R1.1은 RETIRED, R1_1_IMPLEMENTATION_READY=NOT_APPLICABLE입니다.
• R2는 R2_NEEDS_REVALIDATION, R2_IMPLEMENTATION_READY=NO입니다. PR A price/value는 HOLD입니다.
• production validation은 NOT_RUN입니다. main merge/deploy 및 production 요청은 실행하지 않았습니다.

검증

• TDD red: 한국어 canonical 4/4 fixture가 수정 전 assertion failure로 재현됨
• focused Java tests: PASS
• npm test --prefix scripts/poc/fashion-clip-browser: 34/34 PASS
• GRADLE_USER_HOME=/tmp/fitback-browser-alias-gradle ./gradlew clean build --no-daemon --no-watch-fs: 1003/1003 PASS
• git diff --check: PASS
• 독립 코드 리뷰: Critical 0 / Important 0 / Minor 0

체크리스트

• Reviewer에 팀원들을 선택 했나요?
• Assignees에 본인을 선택 했나요?
• Merge 하려는 브랜치가 올바르게 설정되어 있나요?
• 컨벤션을 지키고 있나요?
• 로컬에서 실행했을 때 에러가 발생하지 않나요?
• 불필요한 주석이 제거되었나요?
• 코드 스타일이 일관적인가요?
• Entity 또는 DB 변경 없음
• API/응답 schema 변경 없음
• 배포 workflow/IAM/Repository Variable/Parameter Store 변경 없음
• production validation NOT_RUN
• 민감정보 노출 없음

스크린샷 (선택)

• 없음

리뷰 요구사항 (선택)

• server/browser 점수 숫자 parity가 아니라 alias-resolution parity만 적용됐는지 확인 부탁드립니다.
• browser 비가중 ratio와 70/30 계약이 그대로인지 확인 부탁드립니다.

Summary by CodeRabbit

• 개선 사항
  • 추천 태그 매칭 시 검색 별칭을 우선 활용하도록 개선했습니다.
  • 별칭이 없는 태그는 기존 태그 이름을 사용해 안정적으로 매칭합니다.
  • 한국어 태그의 완전 일치와 부분 일치 평가를 지원합니다.
  • 검색 별칭에는 부정확한(fuzzy) 매칭을 적용하지 않도록 조정했습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 23c45228-9e7a-4e95-ad8c-2602b10ab6be

📥 Commits

Reviewing files that changed from the base of the PR and between af4adb5 and c11fa65.

📒 Files selected for processing (4)

• src/main/java/com/fitback/backend/domain/recommendation/service/BrowserRerankingHandoffService.java
• src/main/java/com/fitback/backend/domain/recommendation/service/RecommendationTagMatcher.java
• src/test/java/com/fitback/backend/domain/recommendation/service/BrowserRerankingHandoffServiceTest.java
• src/test/java/com/fitback/backend/domain/recommendation/service/RecommendationTagMatcherTest.java

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

RecommendationTagMatcher가 retrieval alias를 사용하도록 변경되었습니다. BrowserRerankingHandoffService는 RecommendationRetrievalQueryPlanner를 주입받아 매칭에 전달합니다. alias fallback, 부분 일치, false-positive 방지, zero-eligible 동작을 테스트합니다.

Changes

브라우저 추천 태그 alias 매칭

Layer / File(s)	Summary
Retrieval alias 해석 src/main/java/com/fitback/backend/domain/recommendation/service/RecommendationTagMatcher.java, src/test/java/com/fitback/backend/domain/recommendation/service/RecommendationTagMatcherTest.java	RecommendationTagMatcher.match가 RecommendationRetrievalQueryPlanner를 검증하고 alias를 매칭 기준으로 사용합니다. alias가 없으면 canonical 태그 이름을 사용합니다. alias의 이름·브랜드·카테고리 경로 재사용과 fuzzy matching 방지를 테스트합니다.
Browser handoff 연결 및 유사도 검증 src/main/java/com/fitback/backend/domain/recommendation/service/BrowserRerankingHandoffService.java, src/test/java/com/fitback/backend/domain/recommendation/service/BrowserRerankingHandoffServiceTest.java	서비스 생성자가 RecommendationRetrievalQueryPlanner를 받습니다. tagSimilarity가 planner를 RecommendationTagMatcher.match에 전달합니다. alias 완전 일치, 부분 일치 비율, 기존 STYLE 제외, zero-eligible 결과를 테스트합니다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to c11fa

The PR applies retrieval aliases to browser tag matching while preserving existing scoring and eligibility behavior. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목이 브라우저 추천 태그 유사도에 retrieval alias를 적용하는 주요 변경을 명확하고 간결하게 설명합니다.
Description check	✅ Passed	필수 섹션과 작업 내용, 검증 결과, 체크리스트, 리뷰 요구사항을 대부분 작성했습니다.
Linked Issues check	✅ Passed	[ #392 ]의 alias 재사용, fallback, eligible tag 규칙, 회귀 테스트 및 검증 요구사항을 충족합니다.
Out of Scope Changes check	✅ Passed	변경 사항은 linked issue의 alias resolution parity와 관련 테스트 범위에 한정되며, 관련 없는 코드 변경은 확인되지 않습니다.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/#392-browser-tag-alias-parity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}