feat: bounded retrieval depth experiment 준비

[coconutcococode]

변경 사항

• production public constructor의 page1-only 기본 동작 유지
• package-private experiment 경로에서 family별 page2를 최대 1회 허용
• page1 실패 시 다음 family 진행, page2 실패 시 page1 결과 보존
• page3, retry, 신규 sort 없음
• 경계 및 failure parity 회귀 테스트 추가
• offline 실험 계획 문서 추가

검증

• develop 기준 전체 Gradle clean build 성공
• 독립 코드 리뷰 Critical/Important 0건
• git diff --check 통과

안전 경계

• production/provider 호출 0
• holdout/deploy 0
• planner/selector/scorer/category filter 변경 없음

Summary by CodeRabbit

• 새로운 기능

  • 추천 검색이 검색어별 최대 2페이지까지 추가 후보를 수집하도록 개선되었습니다.
  • 여러 페이지의 결과가 검색어 순서를 유지한 채 통합됩니다.
  • 일부 검색 실패가 발생해도 성공적으로 수집된 후보는 계속 처리됩니다.

• 버그 수정

  • 공급자 오류 발생 시 불필요한 추가 조회를 방지합니다.
  • 지원 범위를 초과하는 페이지 요청을 차단합니다.

• 문서

  • 추천 정확도와 검색 메타데이터 개선을 위한 구현 계획 및 검증 절차를 추가했습니다.

[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: a1e63a7a-af86-4323-9e99-de97dc33ea26

📥 Commits

Reviewing files that changed from the base of the PR and between b32b5aa and 401df1e.

📒 Files selected for processing (3)

• docs/superpowers/plans/2026-08-22-recommendation-accuracy-retrieval-metadata-taxonomy.md
• src/main/java/com/fitback/backend/domain/recommendation/service/RecommendationService.java
• src/test/java/com/fitback/backend/domain/recommendation/service/RecommendationServiceTest.java

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

---

📝 Walkthrough

Walkthrough

추천 정확도 개선 계획과 bounded retrieval을 추가했다. RecommendationService는 검색어별 최대 2페이지를 조회하고 부분 실패를 처리한다. 테스트는 페이지 병합, cursor 제한, 생성자 검증과 provider 실패 동작을 검증한다.

Changes

추천 정확도 검색 흐름

Layer / File(s)	Summary
정확도 분석 및 offline 실행 계획 docs/superpowers/plans/2026-08-22-recommendation-accuracy-retrieval-metadata-taxonomy.md	검색 깊이, aggregate evidence, Shopify 메타데이터, taxonomy 진단과 개인정보·NOT_JUDGED·offline 검증 규칙을 정의했다.
bounded retrieval 구현 src/main/java/com/fitback/backend/domain/recommendation/service/RecommendationService.java	검색어별 최대 페이지 수를 검증하고, cursor 기반으로 최대 1~2페이지를 조회한다. 성공 후보를 유지하며 provider 부분 실패를 누적한다.
페이지네이션 및 실패 동작 검증 src/test/java/com/fitback/backend/domain/recommendation/service/RecommendationServiceTest.java	페이지 병합, 조회 한도, 기존 public 생성자의 1페이지 동작, 쿼리별 실패와 전체 provider 실패를 검증한다. 테스트 헬퍼와 호출 횟수 검증을 추가했다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 401df

This change keeps the existing production page1-only behavior while adding a bounded package-private experiment path with regression coverage; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: maxbon449, rogody

Sequence Diagram(s)

sequenceDiagram
  participant RecommendationService
  participant ProductProvider
  participant BrowserRerankingHandoff
  RecommendationService->>ProductProvider: 검색어별 1~2페이지 cursor 조회
  ProductProvider-->>RecommendationService: 페이지 후보와 다음 cursor 반환
  RecommendationService->>BrowserRerankingHandoff: 성공한 검색어 후보 배치 전달

Loading

🚥 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%. Docstring coverage is scoped to functions touched by this diff. Analyzed 25 functions across 2 files. (1 skipped: 1 unsupported.)	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목이 bounded retrieval depth 실험 준비라는 주요 변경 사항을 명확하고 간결하게 설명합니다.
Description check	✅ Passed	주요 변경 사항과 검증 결과는 포함되어 있어 설명은 대체로 완전하지만, 이슈와 체크리스트 섹션은 누락되었습니다.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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 codex/develop-bounded-depth-20260822

---

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.}