docs(recommendation): 추천 배너 언어 필터 계획을 기록한다

feat(recommendation): 추천 배너 언어 필터를 적용한다
2026-08-19 17:10:42 +09:00 · 2026-08-19 17:10:05 +09:00
17 changed files with 785 additions and 18 deletions
@@ -0,0 +1,518 @@
+# 추천 탭 배너 접속 국가별 언어 필터 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+| 문서 항목 | 내용 |
+|---|---|
+| 상태 | 구현 완료 |
+| 작성일 | 2026-08-19 |
+| 요구사항 기준 | `docs/20260819_추천탭_배너_접속국가별_언어필터/prd.md` |
+| API 기준 | 기존 공개 API 계약 유지 |
+| 현재 Phase | Phase 2: 언어 필터 limit 선행 회귀 테스트 보완 완료 |
+| 현재 활성 Goal | 없음 |
+
+## 목표
+
+메인 홈 추천과 메인 콘텐츠 추천에서 로그인 여부와 기존 강제 국가 매핑을 반영해 일본은 일본어, 그 외 국가는 한국어 배너만 조회한다.
+
+## Architecture
+
+기존 `MemberContentPreferenceService.resolveCountryCode`가 비로그인 사용자까지 처리하도록 입력만 확장하고 강제 국가 매핑과 국가 정규화를 재사용한다. 두 추천 application 진입점에서 국가를 `Lang.JA` 또는 `Lang.KO`로 변환해 기존 port에 전달하며, 두 QueryDSL Repository가 `content_banner.lang`을 정렬·limit 전 조회 조건으로 적용한다.
+
+## Tech Stack
+
+Kotlin, Java 17, Spring Boot 2.7.14, JPA/QueryDSL, JUnit 5, Mockito, Gradle Wrapper
+
+## Global Constraints
+
+- `JP`는 `Lang.JA`, 그 외 국가와 국가 정보 누락은 `Lang.KO`로 고정한다.
+- 로그인 회원의 기존 강제 KR/JP 매핑은 요청 헤더보다 우선한다.
+- `Accept-Language`, DB 스키마, 공개 API endpoint/DTO/응답 스키마를 변경하지 않는다.
+- 기존 탭·성인·활성·차단·대상 유효성·정렬·limit 조건을 유지한다.
+- 신규 dependency, 언어 resolver abstraction과 메모리 후처리를 추가하지 않는다.
+- 모든 구현 Task는 RED → GREEN → REFACTOR 순서로 진행한다.
+
+---
+
+## 현재 상태
+
+| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
+|---:|---|---:|---|---|
+| 1 | 완료 | `3/3` | 없음 | 없음 |
+| 2 | 완료 | `1/1` | 없음 | 없음 |
+
+- 동시에 하나의 미완료 goal만 운용한다.
+- 구현 완료 즉시 해당 Task 체크박스와 현재 상태를 갱신한다.
+- 실제 검증 결과는 기존 기록을 덮어쓰지 않고 `Progress`에 누적한다.
+
+## 범위
+
+### 포함
+
+- 로그인·비로그인 사용자 공통 국가 코드 판정
+- 홈 추천 `tab_id IS NULL` 배너의 `KO`/`JA` 필터
+- 콘텐츠 추천 `tab_id = 2` 배너의 `KO`/`JA` 필터
+- application → port → persistence 언어 전달
+- focused application/Repository 테스트와 직접 영향 controller/E2E 회귀
+
+### 제외
+
+- `Lang.EN`을 선택하는 국가 정책
+- 배너 외 추천 섹션의 국가·언어 필터
+- 관리자/v1 배너 조회 변경
+- DB 데이터·스키마, API 계약과 dependency 변경
+- 기존 배너 정책의 리팩터링
+
+## 파일 구조
+
+| 책임 | 파일 |
+|---|---|
+| 공통 국가 판정 | `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceService.kt`, `MemberContentPreferenceCountryResolver.kt` |
+| 홈 application 언어 선택·전달 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`, `v2/recommendation/application/HomeRecommendationQueryService.kt` |
+| 홈 port·조회 조건 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt`, `v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt` |
+| 콘텐츠 추천 application 언어 선택·전달 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/application/AudioRecommendationQueryService.kt` |
+| 콘텐츠 추천 port·조회 조건 | `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/port/out/AudioRecommendationQueryPort.kt`, `v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt` |
+
+## Phase 1: 접속 국가별 배너 언어 필터
+
+**Phase 결과:** 두 추천 API가 판정 국가에 대응하는 한 언어의 배너만 기존 정책대로 반환한다.
+
+**선행조건:** 승인된 PRD `BANNER-LANG-001~006`.
+
+**Phase 완료 조건:** `P1-T1`~`P1-T3`과 `P1-GATE` 완료, 실제 검증 결과 누적.
+
+### 구현 항목
+
+#### Task 1.1 로그인·비로그인 공통 국가 판정 (`P1-T1`)
+
+**Goal 실행 `P1-T1`:** 기존 강제 국가 매핑을 유지하면서 비로그인 사용자도 동일한 정규화와 기본값으로 국가 코드를 판정한다.
+
+- **시작 조건:** PRD `BANNER-LANG-003`, `BANNER-LANG-004` 확정.
+- **완료 증거:** nullable 회원 국가 판정 테스트가 RED 후 GREEN이고 기존 강제 KR/JP 매핑 테스트가 통과한다.
+- **범위 밖:** 국가를 배너 언어로 변환하거나 배너를 조회하는 로직.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceCountryResolver.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceIntegrationTest.kt`
+
+**Interfaces:**
+
+- Consumes: `CountryContext.countryCode`, 기존 강제 KR/JP 회원 ID 매핑.
+- Produces: `MemberContentPreferenceService.resolveCountryCode(member: Member?): String` — 정규화한 국가 코드이며 null·blank는 `KR`.
+
+- [x] **RED:** 비로그인 `JP`, 소문자/공백 포함 JP, 헤더 누락을 검증하는 테스트를 추가한다.
+
+```kotlin
+countryContext.setCountryCode(" jp ")
+assertEquals("JP", service.resolveCountryCode(null))
+
+countryContext.setCountryCode(null)
+assertEquals("KR", service.resolveCountryCode(null))
+```
+
+- [x] **RED 확인:** 아래 focused test를 실행해 현재 `Member` non-null 계약 때문에 컴파일이 실패하는지 확인한다.
+
+```bash
+./gradlew test --tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest"
+```
+
+**Expected:** `resolveCountryCode(null)` 호출의 타입 불일치로 실패한다.
+
+- [x] **GREEN:** 기존 helper가 nullable 회원을 받고, non-null 회원만 기존 ID 필수 조건을 검사하도록 최소 변경한다.
+
+```kotlin
+fun resolveCountryCode(member: Member?): String {
+    if (member != null) requireMemberId(member)
+    return resolveCountryCodeWithForcedMapping(member, countryContext.countryCode)
+}
+
+fun resolveCountryCodeWithForcedMapping(member: Member?, requestCountryCode: String?): String {
+    val memberId = member?.id
+    if (memberId != null && FORCED_KR_MEMBER_IDS.contains(memberId)) {
+        return "KR"
+    }
+    if (memberId != null && FORCED_JP_MEMBER_IDS.contains(memberId)) {
+        return "JP"
+    }
+    return requestCountryCode
+        ?.trim()
+        ?.takeIf { it.isNotBlank() }
+        ?.uppercase()
+        ?: "KR"
+}
+```
+
+- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 비로그인과 기존 강제 매핑 테스트가 모두 통과하는지 확인한다.
+- [x] **REFACTOR:** 이번 변경에서 생긴 중복만 정리하고 공개 국가 정책 메서드를 추가하지 않는다. focused test를 재실행해 결과를 `Progress`에 기록한다.
+
+#### Task 1.2 홈 추천 배너 언어 필터 (`P1-T2`)
+
+**Goal 실행 `P1-T2`:** 홈 추천 배너가 판정 국가에 맞는 `JA` 또는 `KO`만 DB에서 조회한다.
+
+- **시작 조건:** `P1-T1` 완료, PRD `BANNER-LANG-001`, `BANNER-LANG-005` 확정.
+- **완료 증거:** facade·query service 전달 테스트와 홈 Repository 언어 필터 테스트가 RED 후 GREEN이다.
+- **범위 밖:** 콘텐츠 추천 탭 배너와 홈의 다른 추천 섹션.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacadeTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryServiceTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
+
+**Interfaces:**
+
+- Consumes: `MemberContentPreferenceService.resolveCountryCode(member: Member?): String`.
+- Produces: `findHomeBanners(..., lang: Lang = Lang.KO)` application/port 계약과 QueryDSL `audioContentBanner.lang.eq(lang)` 조건.
+
+- [x] **RED:** facade가 `JP`를 `Lang.JA`, 그 외를 `Lang.KO`로 전달하고 query service가 `Lang`을 port에 위임하는 테스트를 추가한다.
+
+```kotlin
+Mockito.doReturn("JP").`when`(preferenceService).resolveCountryCode(member)
+
+facade.getHomeRecommendations(member)
+
+assertEquals(Lang.JA, queryPort.bannerLang)
+```
+
+- [x] **RED:** 홈 Repository fixture helper에 `lang: Lang = Lang.KO`를 추가하고 같은 조건의 KO/JA 배너 중 요청 언어만 반환하는 테스트를 추가한다.
+
+```kotlin
+val koBanner = saveBanner("ko.png", AudioContentBannerType.LINK, 1, isActive = true, lang = Lang.KO)
+val jaBanner = saveBanner("ja.png", AudioContentBannerType.LINK, 2, isActive = true, lang = Lang.JA)
+
+assertEquals(listOf(koBanner.thumbnailImage), repository.findHomeBanners(20, lang = Lang.KO).map { it.thumbnailImage })
+assertEquals(listOf(jaBanner.thumbnailImage), repository.findHomeBanners(20, lang = Lang.JA).map { it.thumbnailImage })
+```
+
+- [x] **RED 확인:** 아래 focused test를 실행해 `Lang` 전달 계약과 Repository 조건이 없어 발생하는 컴파일/assertion 실패를 확인한다.
+
+```bash
+./gradlew test \
+  --tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" \
+  --tests "kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest" \
+  --tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest"
+```
+
+- [x] **GREEN:** facade에서 국가를 언어로 변환해 전달한다. service와 port 시그니처 끝에는 기본값 `Lang.KO`인 인자를 추가하고 Repository override는 같은 `Lang` 인자를 받는다.
+
+```kotlin
+val bannerLang = if (memberContentPreferenceService.resolveCountryCode(member) == "JP") Lang.JA else Lang.KO
+
+queryService.findHomeBanners(
+    limit = HOME_BANNER_LIMIT,
+    memberId = member?.id,
+    includeAdultBanners = includeAdult,
+    lang = bannerLang
+)
+```
+
+```kotlin
+.where(
+    audioContentBanner.isActive.isTrue,
+    audioContentBanner.tab.isNull,
+    audioContentBanner.lang.eq(lang),
+    includeAdultBannerCondition(includeAdultBanners),
+    activeBannerTargetCondition(memberId, bannerCreator, seriesOwner)
+)
+```
+
+- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 언어 전달·필터와 기존 홈 배너 조건이 통과하는지 확인한다.
+- [x] **REFACTOR:** 국가→언어 변환을 별도 abstraction으로 만들지 않고 한 줄 정책으로 유지한다. 이번 Task가 만든 중복만 정리하고 focused test 결과를 `Progress`에 기록한다.
+
+#### Task 1.3 콘텐츠 추천 배너 언어 필터 (`P1-T3`)
+
+**Goal 실행 `P1-T3`:** 콘텐츠 추천 배너가 판정 국가에 맞는 `JA` 또는 `KO`만 DB에서 조회한다.
+
+- **시작 조건:** `P1-T1` 완료, PRD `BANNER-LANG-002`, `BANNER-LANG-005` 확정.
+- **완료 증거:** query service 전달 테스트와 콘텐츠 추천 Repository 언어 필터 테스트가 RED 후 GREEN이다.
+- **범위 밖:** 홈 추천 배너와 오디오 추천의 배너 외 섹션.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/application/AudioRecommendationQueryService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/port/out/AudioRecommendationQueryPort.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/application/AudioRecommendationQueryServiceTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`
+
+**Interfaces:**
+
+- Consumes: `MemberContentPreferenceService.resolveCountryCode(member: Member?): String`.
+- Produces: `AudioRecommendationQueryPort.findBanners(..., lang: Lang = Lang.KO)`와 QueryDSL `audioContentBanner.lang.eq(lang)` 조건.
+
+- [x] **RED:** 기존 `shouldUseStoredPreferenceForMemberAdultVisibility`에 JP 국가 stub과 배너 호출 검증을 추가하고, 비로그인 조립 테스트는 `Lang.KO` 전달을 검증하도록 보강한다.
+
+```kotlin
+Mockito.doReturn("JP").`when`(preferenceService).resolveCountryCode(member)
+
+service.getRecommendations(member)
+
+Mockito.verify(queryPort).findBanners(
+    AudioRecommendationQueryService.BANNER_LIMIT,
+    member.id,
+    true,
+    Lang.JA
+)
+```
+
+- [x] **RED:** 콘텐츠 추천 Repository fixture helper에 `lang: Lang = Lang.KO`를 추가하고 동일 탭의 KO/JA 배너가 요청 언어별로 분리되는 테스트를 추가한다.
+
+```kotlin
+val koBanner = saveBanner(
+    "ko.png",
+    AudioContentBannerType.LINK,
+    1,
+    link = "https://ko.test",
+    tab = recommendationTab,
+    lang = Lang.KO
+)
+val jaBanner = saveBanner(
+    "ja.png",
+    AudioContentBannerType.LINK,
+    2,
+    link = "https://ja.test",
+    tab = recommendationTab,
+    lang = Lang.JA
+)
+
+assertEquals(listOf("https://cdn.test/${koBanner.thumbnailImage}"), repository.findBanners(20, null, false, Lang.KO).map { it.imageUrl })
+assertEquals(listOf("https://cdn.test/${jaBanner.thumbnailImage}"), repository.findBanners(20, null, false, Lang.JA).map { it.imageUrl })
+```
+- [x] **RED 확인:** 아래 focused test를 실행해 `Lang` 인자와 Repository 필터가 없어 발생하는 컴파일/assertion 실패를 확인한다.
+
+```bash
+./gradlew test \
+  --tests "kr.co.vividnext.sodalive.v2.content.recommendation.application.AudioRecommendationQueryServiceTest" \
+  --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest"
+```
+
+- [x] **GREEN:** `getRecommendations`에서 국가를 언어로 변환해 배너 호출에만 전달한다. port에는 기본값 `Lang.KO`인 인자를 추가하고 Repository override는 같은 `Lang` 인자를 받는다.
+
+```kotlin
+val bannerLang = if (memberContentPreferenceService.resolveCountryCode(member) == "JP") Lang.JA else Lang.KO
+
+banners = queryPort.findBanners(BANNER_LIMIT, memberId, canViewAdultContent, bannerLang)
+```
+
+```kotlin
+.where(
+    audioContentBanner.isActive.isTrue,
+    audioContentBanner.tab.id.eq(2L),
+    audioContentBanner.lang.eq(lang),
+    adultBannerCondition(canViewAdultContent),
+    activeBannerTargetCondition(memberId, bannerCreator, seriesOwner)
+)
+```
+
+- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 언어 필터와 기존 탭·성인·차단 조건이 함께 통과하는지 확인한다.
+- [x] **REFACTOR:** 배너 외 오디오 추천 로직을 변경하지 않는다. 이번 Task가 만든 중복만 정리하고 focused test 결과를 `Progress`에 기록한다.
+
+### 완료 조건
+
+- [x] `P1-T1`~`P1-T3`의 체크박스와 완료 증거가 모두 충족됐다.
+- [x] `BANNER-LANG-001~006`이 구현 또는 명시적 제외로 추적된다.
+- [x] 공개 API와 DB 스키마 변경이 없다.
+- [x] 실제 검증 결과가 `Progress`에 기록됐다.
+
+### 검증 방법
+
+#### Phase 1 Gate
+
+**Goal 실행 `P1-GATE`:** 두 추천 API의 국가별 배너 언어 필터와 기존 배너 정책의 비회귀를 최종 판정한다.
+
+- **시작 조건:** `P1-T1`~`P1-T3` 완료.
+- **완료 증거:** 아래 focused/영향 범위 test, lint, 문서 명령과 수동 검증 통과 및 `Progress` 기록.
+- **범위 밖:** Gate 통과를 위한 test 삭제·skip·완화와 관련 없는 코드 수정.
+
+```bash
+./gradlew test \
+  --tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" \
+  --tests "kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest" \
+  --tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" \
+  --tests "kr.co.vividnext.sodalive.v2.content.recommendation.application.AudioRecommendationQueryServiceTest" \
+  --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationControllerTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
+./gradlew ktlintCheck
+./gradlew tasks --all
+git diff --check
+```
+
+**Expected:** 모든 명령이 exit code `0`으로 끝난다. JP 판정은 두 API에서 JA 배너만, 그 외 판정은 KO 배너만 반환하며 기존 탭·성인·활성·차단·대상 유효성·정렬·limit와 응답 스키마가 유지된다.
+
+수동 검증:
+
+- [x] `git diff --name-only`에 계획된 production/test 파일과 이 작업 문서 이외의 변경이 없는지 확인한다.
+- [x] `git diff`에서 endpoint, request/response DTO, DB 스키마, dependency와 `Accept-Language` 사용이 추가되지 않았는지 확인한다.
+- [x] 두 Repository 모두 `lang` 조건이 `orderBy`와 `limit`보다 앞선 `where`에 있는지 확인한다.
+
+전체 회귀 `./gradlew test`는 변경이 국가 판정과 두 배너 조회 경로에 한정되고 위 명령이 application, persistence, controller/E2E를 포함하므로 기본 생략한다. focused test로 영향 범위를 판단할 수 없는 실패가 발생하거나 공통 국가 판정 변경의 회귀 범위가 확대되면 전체 회귀를 실행하고 결과를 `Progress`에 기록한다.
+
+## 실행 순서와 의존성
+
+| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
+|---:|---|---|---|---|
+| 1 | `P1-T1` | 승인된 PRD | 아니요 | 기존 국가 정규화·강제 매핑 테스트와 구현을 다시 대조 |
+| 2 | `P1-T2` | `P1-T1` | 아니요 | 홈 application/port/repository 계약을 한 단계씩 대조 |
+| 3 | `P1-T3` | `P1-T1` | 아니요 | 콘텐츠 추천 application/port/repository 계약을 한 단계씩 대조 |
+| 4 | `P1-GATE` | `P1-T1`~`P1-T3` | 아니요 | 실패를 소유한 Task에 회귀 수정 Goal 추가 |
+
+```text
+P1-T1 → P1-T2 → P1-T3 → P1-GATE
+```
+
+## 변경 금지 항목
+
+- 기존 완료 문서와 검증 기록을 삭제하거나 덮어쓰지 않는다.
+- 공개 endpoint, request/response DTO와 API envelope를 변경하지 않는다.
+- DB schema, 배너 데이터, 관리자/v1 배너 API를 변경하지 않는다.
+- `Accept-Language`나 회원 저장 언어를 국가 판정 대신 사용하지 않는다.
+- 조회 후 컬렉션 filter로 언어를 제거하지 않는다.
+- 신규 dependency, enum, 공통 abstraction과 관련 없는 리팩터링을 추가하지 않는다.
+- test를 삭제·skip·완화하지 않는다.
+
+## 의사결정 및 중단 규칙
+
+- PRD와 구현이 충돌하면 `prd.md`의 Decision Log와 이 계획을 먼저 갱신한 뒤 구현한다.
+- `CloudFront-Viewer-Country` 또는 기존 강제 국가 매핑 정책을 바꿔야 하면 범위 확장으로 보고 사용자 승인 전 중단한다.
+- `Lang.EN`, 다른 국가별 언어 또는 배너 외 추천 섹션이 필요해지면 별도 요구사항으로 분리한다.
+- 공개 API, DB schema 또는 관리자/v1 조회 변경이 필요해지면 사용자 승인 전 진행하지 않는다.
+- 체크박스, test와 `Progress` 기록이 모두 충족된 뒤에만 Goal을 완료 처리한다.
+
+## Progress
+
+### 2026-08-19 문서 작성
+
+- 사용자 인터뷰로 `JP → JA`, 그 외 국가 → `KO` 정책과 로그인 회원의 기존 강제 국가 매핑 적용을 확정했다.
+- PRD와 구현 계획만 작성했으며 production/test 코드는 변경하지 않았다.
+- placeholder 검색과 `git diff --check`에서 문제가 없음을 확인했다.
+- `./gradlew tasks --all`은 최초 sandbox의 Gradle wrapper lock 접근 제한으로 실패했으며, 승인된 동일 명령 재실행에서 `BUILD SUCCESSFUL`을 확인했다.
+
+### 2026-08-19 P1-T1 완료
+
+- RED: `./gradlew test --tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest"` 실행 결과 `resolveCountryCode(null)` 4곳이 `Member` non-null 타입 불일치로 `:compileTestKotlin FAILED`가 됨을 확인했다.
+- GREEN/REFACTOR: `MemberContentPreferenceService.resolveCountryCode`와 `resolveCountryCodeWithForcedMapping`만 nullable 회원을 받도록 최소 변경했다. 같은 focused test 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+
+### 2026-08-19 P1-T2 완료
+
+- RED: 홈 facade/service/repository 테스트에 `Lang` 전달과 `content_banner.lang` 조건 기대를 추가한 뒤 focused test를 실행했고, `findHomeBanners`의 `lang` 파라미터 부재로 `:compileTestKotlin FAILED`가 됨을 확인했다.
+- GREEN/REFACTOR: 홈 facade에서 `JP`만 `Lang.JA`, 그 외 `Lang.KO`를 한 줄로 선택해 service/port/repository에 전달하고, QueryDSL `where`에 `audioContentBanner.lang.eq(lang)`을 추가했다. 같은 focused test 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+
+### 2026-08-19 P1-T3 완료
+
+- RED: 콘텐츠 추천 service/repository 테스트에 `Lang.KO` 기본 전달, `JP`의 `Lang.JA` 전달, 추천 탭 배너 언어 분리 기대를 추가한 뒤 focused test를 실행했고, `findBanners`의 `Lang` 인자 부재로 `:compileTestKotlin FAILED`가 됨을 확인했다.
+- GREEN/REFACTOR: `AudioRecommendationQueryService.getRecommendations`에서 배너 호출에만 `JP → Lang.JA`, 그 외 `Lang.KO`를 전달하고, QueryDSL `where`에 `audioContentBanner.lang.eq(lang)`을 추가했다. 같은 focused test 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+
+### 2026-08-19 P1-GATE 완료
+
+- Phase Gate focused/controller/E2E 명령 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+- `./gradlew ktlintCheck`는 최초 실행에서 테스트 import 순서 2곳으로 실패했고, import 정렬 후 재실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+- `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL`을 확인했다.
+- `git diff --check` 실행 결과 출력 없이 통과했다.
+- `git diff --name-only`와 diff 검토로 계획된 production/test 파일 및 이 작업 문서 외 변경이 없고, 공개 endpoint/request/response DTO, DB 스키마, dependency, `Accept-Language` 정책이 추가되지 않았음을 확인했다.
+- 두 Repository 모두 `audioContentBanner.lang.eq(lang)` 조건이 `where` 안에서 `orderBy`와 `limit`보다 먼저 적용됨을 확인했다.
+- Reviewer Gate에서 요구사항 차단 이슈 없음으로 승인받았다.
+
+## Decision Log
+
+| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
+|---|---|---|---|---|---|
+| 2026-08-19 | `DEC-001` | 확정 | 공통 국가 판정을 먼저 nullable 회원까지 확장한 뒤 두 배너 경로가 소비한다. | 기존 강제 매핑·정규화 재사용과 중복 방지 | `P1-T1`~`P1-T3` |
+| 2026-08-19 | `DEC-002` | 확정 | 두 port의 `lang`은 기존 직접 호출 호환을 위해 기본값 `Lang.KO`를 사용한다. | 비JP 정책과 기존 KO fixture 일치 | `P1-T2`, `P1-T3` |
+| 2026-08-19 | `DEC-003` | 확정 | 국가→언어 변환은 두 application 진입점의 한 줄 정책으로 두고 별도 abstraction을 만들지 않는다. | 사용처가 두 곳뿐인 고정 정책의 최소 구현 | `P1-T2`, `P1-T3` |
+
+## 발견된 문제
+
+### 2026-08-19 2차 리뷰
+
+- production 호출 흐름과 QueryDSL 조건에는 요구사항 차단 문제가 없다.
+- 두 Repository 언어 테스트가 `limit = 20`으로 배너 2개를 모두 수용해 `BANNER-LANG-005`의 "다른 언어 배너가 limit을 차지하지 않음" 회귀를 직접 방어하지 못하는 테스트 공백을 확인했다.
+
+## Phase 2: 언어 필터 limit 선행 회귀 테스트 보완
+
+**Phase 결과:** 두 Repository 테스트가 언어 조건이 제거되거나 limit 이후로 밀리는 회귀를 직접 검출한다.
+
+**선행조건:** `P1-GATE` 완료와 2차 리뷰 테스트 공백 확정.
+
+**Phase 완료 조건:** `P2-T1`과 `P2-GATE` 완료, mutation RED와 복구 후 GREEN 결과 누적.
+
+### 구현 항목
+
+#### Task 2.1 언어 필터가 limit보다 먼저 적용되는 회귀 테스트 (`P2-T1`)
+
+**Goal 실행 `P2-T1`:** 낮은 `orders`의 반대 언어 배너가 있어도 `limit = 1` 조회는 요청 언어 배너를 반환함을 두 Repository에서 검증한다.
+
+- **시작 조건:** PRD `BANNER-LANG-005`, 2차 리뷰 결과 확정.
+- **완료 증거:** 두 테스트가 정상 구현에서 통과하고, 각 Repository의 언어 조건 제거 mutation에서 의도한 assertion 실패를 보인 뒤 복구 후 다시 통과한다.
+- **범위 밖:** production query, 배너 정렬 정책, API 계약 변경.
+- **TDD 예외 사유:** production 동작은 이미 올바르고 이번 보완은 기존 테스트가 특정 회귀를 검출하는지 확인하는 테스트 전용 변경이다.
+- **대체 검증 방법:** 테스트를 먼저 보강한 뒤 각 Repository의 `audioContentBanner.lang.eq(lang)`을 일시 제거해 실패를 확인하고 즉시 복구한 뒤 같은 테스트의 통과를 확인한다.
+
+**Files:**
+
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepositoryTest.kt`
+- Mutation 후 원상 복구 확인: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
+- Mutation 후 원상 복구 확인: `src/main/kotlin/kr/co/vividnext/sodalive/v2/content/recommendation/adapter/out/persistence/DefaultAudioRecommendationQueryRepository.kt`
+
+- [x] **RED:** 각 언어 테스트에서 `orders = 1`인 반대 언어와 `orders = 2`인 요청 언어를 만들고 `limit = 1` 결과가 요청 언어 한 건인지 검증한다.
+- [x] **RED 확인:** 홈 Repository의 언어 조건을 일시 제거하고 홈 단일 테스트가 반대 언어를 반환해 실패하는지 확인한 뒤 원상 복구한다.
+- [x] **RED 확인:** 콘텐츠 추천 Repository의 언어 조건을 일시 제거하고 콘텐츠 추천 단일 테스트가 반대 언어를 반환해 실패하는지 확인한 뒤 원상 복구한다.
+- [x] **GREEN:** production 변경 없이 두 테스트의 최종 fixture와 `limit = 1` assertion만 유지한다.
+- [x] **GREEN 확인:** 아래 두 focused test class가 통과하는지 확인한다.
+- [x] **REFACTOR:** 테스트 이름·fixture 중복만 최소 정리하고 production diff가 Phase 1 구현과 동일한지 확인한다.
+
+```bash
+./gradlew test \
+  --tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" \
+  --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest"
+```
+
+### Phase 2 Gate (`P2-GATE`)
+
+- **시작 조건:** `P2-T1` 완료.
+- **완료 증거:** Phase 1 Gate focused/controller/E2E 테스트, `ktlintCheck`, `tasks --all`, `git diff --check` 통과와 재리뷰 결과 기록.
+- **범위 밖:** 새 production 동작과 관련 없는 테스트 확장.
+
+```bash
+./gradlew test \
+  --tests "kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceIntegrationTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.home.application.HomeRecommendationFacadeTest" \
+  --tests "kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryServiceTest" \
+  --tests "kr.co.vividnext.sodalive.v2.recommendation.adapter.out.persistence.DefaultHomeRecommendationQueryRepositoryTest" \
+  --tests "kr.co.vividnext.sodalive.v2.content.recommendation.application.AudioRecommendationQueryServiceTest" \
+  --tests "kr.co.vividnext.sodalive.v2.content.recommendation.adapter.out.persistence.DefaultAudioRecommendationQueryRepositoryTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.home.HomeRecommendationControllerTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationControllerTest" \
+  --tests "kr.co.vividnext.sodalive.v2.api.content.recommendation.adapter.in.web.AudioRecommendationEndToEndTest"
+./gradlew ktlintCheck
+./gradlew tasks --all
+git diff --check
+```
+
+**Expected:** 모든 명령이 exit code `0`으로 끝나고, 두 언어 테스트는 반대 언어가 더 낮은 `orders`여도 요청 언어 배너를 한 건 반환한다.
+
+## Phase 2 Progress
+
+### 2026-08-19 `P2-T1` 완료
+
+- 테스트 보완: 두 Repository 언어 테스트를 `limit = 1`로 강화하고 이름을 limit 선행 동작이 드러나도록 변경했다.
+- 홈 mutation RED: `DefaultHomeRecommendationQueryRepository`의 언어 조건을 일시 제거한 단일 테스트가 `DefaultHomeRecommendationQueryRepositoryTest.kt:276`에서 assertion 실패함을 확인하고 즉시 복구했다.
+- 콘텐츠 추천 mutation RED: `DefaultAudioRecommendationQueryRepository`의 언어 조건을 일시 제거한 단일 테스트가 `DefaultAudioRecommendationQueryRepositoryTest.kt:126`에서 assertion 실패함을 확인하고 즉시 복구했다.
+- GREEN: 복구 후 두 Repository focused test class를 함께 실행해 `BUILD SUCCESSFUL`을 확인했다.
+
+### 2026-08-19 `P2-GATE` 완료
+
+- Phase 1 Gate와 같은 focused/application/Repository/controller/E2E 테스트 9개 class를 실행해 `BUILD SUCCESSFUL`을 확인했다.
+- `./gradlew ktlintCheck`와 `./gradlew tasks --all`이 각각 `BUILD SUCCESSFUL`로 끝났다.
+- `git diff --check` 결과 오류가 없고, 두 production Repository에 `audioContentBanner.lang.eq(lang)`이 복구된 상태임을 확인했다.
+- 최종 독립 재리뷰에서 최초 Important 이슈 해소와 Critical/Important/Minor 추가 이슈 없음 판정을 받았다.
+- 전체 회귀 `./gradlew test`는 실행하지 않았다. 변경이 두 기존 Repository 테스트의 limit 경계 강화에 한정되고 Phase Gate가 직접 영향 application/persistence/controller/E2E 범위를 포함하므로 생략했다.
@@ -0,0 +1,113 @@
+# 추천 탭 배너 접속 국가별 언어 필터 PRD
+
+## 문서 정보
+
+| 항목 | 내용 |
+|---|---|
+| 문서 상태 | 구현 기준 확정 |
+| 작성일 | 2026-08-19 |
+| 최종 수정일 | 2026-08-19 |
+| 대상 제품 | 메인 홈 추천 탭, 메인 콘텐츠 추천 탭 |
+| 작성자·결정권자 | 사용자 |
+| 관련 API Contract | 신규 없음. 기존 공개 API 계약 유지 |
+| 관련 구현 계획 | `docs/20260819_추천탭_배너_접속국가별_언어필터/plan-task.md` |
+| 관련 기존 문서 | `docs/20260805_추천탭_배너_조회조건/prd.md`, `docs/20260529_메인_홈_추천_API/prd.md`, `docs/20260623_메인_콘텐츠_추천_탭_API/prd.md` |
+
+## 1. Overview
+
+메인 홈 추천 API와 메인 콘텐츠 추천 API에서 접속 국가에 맞는 언어의 배너만 반환한다. 로그인 회원은 기존 강제 국가 매핑을 포함한 국가 판정 결과를 사용하고, 비로그인 사용자는 `CloudFront-Viewer-Country` 요청 헤더를 기준으로 판정한다.
+
+## 2. Problem Statement
+
+- 두 추천 API의 현재 배너 QueryDSL 조회에는 `content_banner.lang` 조건이 없다.
+- 그 결과 한국어·일본어·영어 배너가 같은 응답에 섞일 수 있다.
+- 언어 필터가 조회 후 적용되면 다른 언어 배너가 limit을 차지해 필요한 배너가 누락될 수 있다.
+
+문제를 해결했다는 판단은 두 API가 배너 정렬과 limit 적용 전에 확정된 언어 조건을 적용하고, 기존 배너 조회 조건과 공개 응답 스키마를 유지하는 것으로 한다.
+
+## 3. Goals
+
+- 접속 국가 판정 결과가 `JP`이면 `Lang.JA` 배너만 반환한다.
+- `JP` 이외의 국가와 국가 정보가 없는 경우에는 `Lang.KO` 배너만 반환한다.
+- 로그인 회원은 `MemberContentPreferenceService.resolveCountryCode`의 기존 강제 국가 매핑을 유지한다.
+- 비로그인 사용자도 요청 국가를 판정할 수 있도록 동일한 국가 정규화와 기본값 정책을 사용한다.
+- 언어 조건을 DB 조회 단계에서 정렬·limit보다 먼저 적용한다.
+
+## 4. Non-Goals
+
+- `Lang.EN` 배너를 반환하는 국가 정책을 추가하지 않는다.
+- `Accept-Language`를 배너 언어 판정에 사용하지 않는다.
+- `CloudFront-Viewer-Country` 헤더 계약이나 `CountryInterceptor`를 변경하지 않는다.
+- 공개 API endpoint, request/response DTO와 응답 스키마를 변경하지 않는다.
+- 기존 배너의 탭·성인·활성·차단·대상 유효성·정렬·limit 정책을 변경하지 않는다.
+- DB 스키마, 배너 데이터, 관리자 배너 API와 기존 v1 배너 조회를 변경하지 않는다.
+- 배너 이외의 추천 섹션에 국가 또는 언어 필터를 추가하지 않는다.
+
+## 5. 대상 사용자와 국가 판정
+
+| 사용자 | 국가 판정 | 언어 선택 |
+|---|---|---|
+| 강제 JP 매핑 로그인 회원 | 기존 강제 매핑 결과 `JP` | `Lang.JA` |
+| 강제 KR 매핑 로그인 회원 | 기존 강제 매핑 결과 `KR` | `Lang.KO` |
+| 일반 로그인 회원 | 정규화한 `CloudFront-Viewer-Country`, 누락 시 `KR` | `JP`이면 `JA`, 그 외 `KO` |
+| 비로그인 사용자 | 정규화한 `CloudFront-Viewer-Country`, 누락 시 `KR` | `JP`이면 `JA`, 그 외 `KO` |
+
+국가 코드는 기존 정책처럼 앞뒤 공백을 제거하고 대문자로 정규화한다.
+
+## 6. 핵심 조회 흐름
+
+1. `CountryInterceptor`가 `CloudFront-Viewer-Country`를 `CountryContext`에 저장한다.
+2. `HomeRecommendationFacade.getHomeRecommendations`와 `AudioRecommendationQueryService.getRecommendations`가 회원과 요청 국가로 국가 코드를 판정한다.
+3. 국가 코드가 `JP`이면 `Lang.JA`, 그 외에는 `Lang.KO`를 선택한다.
+4. 선택한 `Lang`을 기존 application → port → persistence 경로로 전달한다.
+5. Repository가 `content_banner.lang = :lang`을 기존 조건과 함께 적용한 뒤 정렬하고 limit을 적용한다.
+
+## 7. 기능 요구사항
+
+| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
+|---|---|---|---|---|
+| `BANNER-LANG-001` | 확정 | `GET /api/v2/home/recommendations`는 판정 국가가 `JP`이면 `JA`, 그 외에는 `KO` 홈 배너만 반환한다. | `tab_id IS NULL`인 활성 배너 중 선택 언어와 일치하는 배너만 응답한다. | `P1-T2` |
+| `BANNER-LANG-002` | 확정 | `GET /api/v2/audio/recommendations`는 판정 국가가 `JP`이면 `JA`, 그 외에는 `KO` 콘텐츠 추천 배너만 반환한다. | `tab_id = 2`인 활성 배너 중 선택 언어와 일치하는 배너만 응답한다. | `P1-T3` |
+| `BANNER-LANG-003` | 확정 | 로그인 회원의 국가 판정은 기존 강제 KR/JP 매핑을 요청 헤더보다 우선한다. | 강제 JP 회원은 비JP 헤더에서도 `JP`, 강제 KR 회원은 JP 헤더에서도 `KR`로 판정된다. | `P1-T1` |
+| `BANNER-LANG-004` | 확정 | 비로그인 사용자는 요청 국가를 정규화해 사용하고, 헤더가 없거나 비어 있으면 `KR`로 판정한다. | `JP`·`jp`·공백 포함 JP는 `JP`, null·blank는 `KR`로 판정된다. | `P1-T1` |
+| `BANNER-LANG-005` | 확정 | 언어 필터는 정렬·limit 전에 DB 조회 조건으로 적용한다. | 다른 언어 배너가 limit을 차지하지 않고, Repository 테스트가 언어별 결과를 검증한다. | `P1-T2`, `P1-T3` |
+| `BANNER-LANG-006` | 확정 | 기존 배너 조회 정책과 공개 API 계약을 유지한다. | 기존 탭·성인·활성·차단·대상 유효성·정렬·limit 테스트와 controller/E2E 회귀가 통과한다. | `P1-GATE` |
+
+## 8. API 계약
+
+| Method | Path | 변경 내용 |
+|---|---|---|
+| `GET` | `/api/v2/home/recommendations` | 응답 스키마 변경 없이 접속 국가별 배너 언어 조회 조건만 추가한다. |
+| `GET` | `/api/v2/audio/recommendations` | 응답 스키마 변경 없이 접속 국가별 배너 언어 조회 조건만 추가한다. |
+
+- 신규 request header는 추가하지 않는다.
+- 기존 `CloudFront-Viewer-Country` 처리 경로를 재사용한다.
+- 배너가 없으면 기존처럼 빈 목록을 반환한다.
+
+## 9. 성능과 품질 요구사항
+
+- `content_banner.lang` 조건은 QueryDSL `where`에 포함하고 메모리 후처리를 사용하지 않는다.
+- 신규 dependency, 캐시, 공통 resolver abstraction을 추가하지 않는다.
+- 기존 `Lang`, `CountryContext`, `MemberContentPreferenceService`를 재사용한다.
+- application 전달 테스트와 두 Repository 조회 테스트를 TDD로 보강한다.
+- 직접 영향 controller/E2E 회귀와 `ktlintCheck`를 Phase Gate에서 검증한다.
+
+## 10. 성공 기준
+
+- [x] 강제 매핑을 포함한 판정 국가가 `JP`이면 두 API의 배너가 모두 `JA`로 제한된다. (`BANNER-LANG-001~003`)
+- [x] 일반 국가와 국가 정보가 없는 경우 두 API의 배너가 모두 `KO`로 제한된다. (`BANNER-LANG-001`, `BANNER-LANG-002`, `BANNER-LANG-004`)
+- [x] 다른 언어 배너가 정렬·limit 대상에 포함되지 않는다. (`BANNER-LANG-005`)
+- [x] 기존 배너 필터와 공개 응답 계약이 유지된다. (`BANNER-LANG-006`)
+
+## 11. Open Questions
+
+- 없음.
+
+## 12. Decision Log
+
+| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·Goal |
+|---|---|---|---|---|---|
+| 2026-08-19 | `DEC-001` | 확정 | `JP`는 `JA`, 그 외 국가는 `KO` 배너만 조회한다. | 사용자 인터뷰 답변 B | `BANNER-LANG-001`, `BANNER-LANG-002`, `BANNER-LANG-005` |
+| 2026-08-19 | `DEC-002` | 확정 | 로그인 회원은 기존 강제 국가 매핑을 포함한 국가 판정을 사용한다. | 사용자 인터뷰 답변 B | `BANNER-LANG-003`, `P1-T1` |
+| 2026-08-19 | `DEC-003` | 확정 | 비로그인은 요청 국가를 사용하고 국가 정보가 없으면 기존 기본값 `KR`을 사용한다. | 승인된 설계 | `BANNER-LANG-004`, `P1-T1` |
+| 2026-08-19 | `DEC-004` | 확정 | 언어 필터는 Repository 조회 조건으로 적용한다. | limit 이전 필터링과 기존 QueryDSL 패턴 유지 | `BANNER-LANG-005`, `P1-T2`, `P1-T3` |
@@ -5,8 +5,8 @@ import kr.co.vividnext.sodalive.member.Member
 private val FORCED_KR_MEMBER_IDS = setOf(16L, 17L, 17958L, 44144L)
 private val FORCED_JP_MEMBER_IDS = setOf(2L, 29721L, 32050L, 37543L, 40850L)

-fun resolveCountryCodeWithForcedMapping(member: Member, requestCountryCode: String?): String {
-    val memberId = member.id
+fun resolveCountryCodeWithForcedMapping(member: Member?, requestCountryCode: String?): String {
+    val memberId = member?.id
    if (memberId != null && FORCED_KR_MEMBER_IDS.contains(memberId)) {
        return "KR"
    }
@@ -157,8 +157,8 @@ class MemberContentPreferenceService(
        return getStoredPreference(member).isAdult
    }

-    fun resolveCountryCode(member: Member): String {
-        requireMemberId(member)
+    fun resolveCountryCode(member: Member?): String {
+        if (member != null) requireMemberId(member)
        return resolveCountryCodeWithForcedMapping(member, countryContext.countryCode)
    }

@@ -1,6 +1,7 @@
 package kr.co.vividnext.sodalive.v2.api.home.application

 import kr.co.vividnext.sodalive.event.EventItem
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.v2.api.common.dto.RecommendationBannerResponse
@@ -46,6 +47,7 @@ class HomeRecommendationFacade(
        return runCatching {
            val now = LocalDateTime.now()
            val includeAdult = resolveAdultVisibility(member)
+            val bannerLang = if (memberContentPreferenceService.resolveCountryCode(member) == "JP") Lang.JA else Lang.KO

            HomeRecommendationResponse(
                lives = queryService.findLiveRecommendations(
@@ -56,7 +58,8 @@ class HomeRecommendationFacade(
                banners = queryService.findHomeBanners(
                    limit = HOME_BANNER_LIMIT,
                    memberId = member?.id,
-                    includeAdultBanners = includeAdult
+                    includeAdultBanners = includeAdult,
+                    lang = bannerLang
                )
                    .map { RecommendationBannerResponse.from(it.toBanner()) },
                recentlyActiveCreators = queryService.findRecentlyActiveCreators(
@@ -15,6 +15,7 @@ import kr.co.vividnext.sodalive.creator.admin.content.series.QSeries.series
 import kr.co.vividnext.sodalive.creator.admin.content.series.QSeriesContent.seriesContent
 import kr.co.vividnext.sodalive.event.EventItem
 import kr.co.vividnext.sodalive.event.QEvent.event
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.QMember
 import kr.co.vividnext.sodalive.member.QMember.member
 import kr.co.vividnext.sodalive.member.block.QBlockMember
@@ -40,7 +41,12 @@ class DefaultAudioRecommendationQueryRepository(
    @Value("\${cloud.aws.cloud-front.host}")
    private val cloudFrontHost: String
 ) : AudioRecommendationQueryRepository {
-    override fun findBanners(limit: Int, memberId: Long?, canViewAdultContent: Boolean): List<RecommendationBanner> {
+    override fun findBanners(
+        limit: Int,
+        memberId: Long?,
+        canViewAdultContent: Boolean,
+        lang: Lang
+    ): List<RecommendationBanner> {
        val bannerCreator = QMember("audioRecommendationBannerCreator")
        val seriesOwner = QMember("audioRecommendationSeriesOwner")
        val randomTieBreaker = Expressions.numberTemplate(Double::class.java, "function('rand')")
@@ -64,6 +70,7 @@ class DefaultAudioRecommendationQueryRepository(
            .where(
                audioContentBanner.isActive.isTrue,
                audioContentBanner.tab.id.eq(2L),
+                audioContentBanner.lang.eq(lang),
                adultBannerCondition(canViewAdultContent),
                activeBannerTargetCondition(memberId, bannerCreator, seriesOwner)
            )
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.v2.content.recommendation.application

+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.v2.content.recommendation.domain.AudioCard
@@ -24,6 +25,7 @@ class AudioRecommendationQueryService(
        val canViewAdultContent = canViewAdultContent(member)
        val visibility = if (canViewAdultContent) AudioRecommendationVisibility.ALL else AudioRecommendationVisibility.SAFE
        val memberId = member?.id
+        val bannerLang = if (memberContentPreferenceService.resolveCountryCode(member) == "JP") Lang.JA else Lang.KO
        val newAndHotSectionType = newAndHotSectionType(visibility)
        val mostCommentedSectionType = mostCommentedSectionType(visibility)
        val recommendedAudioSectionType = recommendedAudioSectionType(visibility)
@@ -44,7 +46,7 @@ class AudioRecommendationQueryService(
        )

        return AudioRecommendations(
-            banners = queryPort.findBanners(BANNER_LIMIT, memberId, canViewAdultContent),
+            banners = queryPort.findBanners(BANNER_LIMIT, memberId, canViewAdultContent, bannerLang),
            originalSeries = queryPort.findOriginalSeries(ORIGINAL_SERIES_LIMIT, memberId, canViewAdultContent, now),
            latestAudios = queryPort.findLatestAudios(LATEST_AUDIO_LIMIT, memberId, canViewAdultContent, now),
            newAndHotAudios = queryPort.findAudioCardsByIds(
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.v2.content.recommendation.port.out

+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.v2.common.domain.RecommendationBanner
 import kr.co.vividnext.sodalive.v2.content.recommendation.domain.AudioCard
 import kr.co.vividnext.sodalive.v2.content.recommendation.domain.AudioRecommendationVisibility
@@ -9,7 +10,12 @@ import kr.co.vividnext.sodalive.v2.recommendation.port.out.RecommendationSnapsho
 import java.time.LocalDateTime

 interface AudioRecommendationQueryPort {
-    fun findBanners(limit: Int, memberId: Long?, canViewAdultContent: Boolean): List<RecommendationBanner>
+    fun findBanners(
+        limit: Int,
+        memberId: Long?,
+        canViewAdultContent: Boolean,
+        lang: Lang = Lang.KO
+    ): List<RecommendationBanner>
    fun findOriginalSeries(limit: Int, memberId: Long?, canViewAdultContent: Boolean, now: LocalDateTime): List<OriginalSeries>
    fun findLatestAudios(limit: Int, memberId: Long?, canViewAdultContent: Boolean, now: LocalDateTime): List<AudioCard>
    fun findFreeAudios(limit: Int, memberId: Long?, canViewAdultContent: Boolean, now: LocalDateTime): List<AudioCard>
@@ -20,6 +20,7 @@ import kr.co.vividnext.sodalive.event.QEvent.event
 import kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.QCreatorCommunity.creatorCommunity
 import kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.comment.QCreatorCommunityComment.creatorCommunityComment
 import kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.like.QCreatorCommunityLike.creatorCommunityLike
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.live.room.QLiveRoom.liveRoom
 import kr.co.vividnext.sodalive.member.MemberKind
 import kr.co.vividnext.sodalive.member.MemberRole
@@ -88,7 +89,8 @@ class DefaultHomeRecommendationQueryRepository(
    override fun findHomeBanners(
        limit: Int,
        memberId: Long?,
-        includeAdultBanners: Boolean
+        includeAdultBanners: Boolean,
+        lang: Lang
    ): List<HomeBannerRecommendationRecord> {
        val bannerCreator = QMember("bannerCreator")
        val seriesOwner = QMember("seriesOwner")
@@ -116,6 +118,7 @@ class DefaultHomeRecommendationQueryRepository(
            .where(
                audioContentBanner.isActive.isTrue,
                audioContentBanner.tab.isNull,
+                audioContentBanner.lang.eq(lang),
                includeAdultBannerCondition(includeAdultBanners),
                activeBannerTargetCondition(memberId, bannerCreator, seriesOwner)
            )
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.v2.recommendation.application

+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.v2.common.domain.CreatorActivityType
 import kr.co.vividnext.sodalive.v2.recommendation.domain.RecommendationSnapshotWindowPolicy
 import kr.co.vividnext.sodalive.v2.recommendation.domain.RecommendedSectionType
@@ -44,9 +45,10 @@ class HomeRecommendationQueryService(
    fun findHomeBanners(
        limit: Int = DEFAULT_BANNER_LIMIT,
        memberId: Long? = null,
-        includeAdultBanners: Boolean = false
+        includeAdultBanners: Boolean = false,
+        lang: Lang = Lang.KO
    ): List<HomeBannerRecommendationRecord> {
-        return queryPort.findHomeBanners(limit, memberId, includeAdultBanners)
+        return queryPort.findHomeBanners(limit, memberId, includeAdultBanners, lang)
    }

    fun findRecentlyActiveCreators(
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.v2.recommendation.port.out

+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.v2.common.domain.CreatorActivityType
 import java.time.LocalDateTime

@@ -14,7 +15,8 @@ interface HomeRecommendationQueryPort {
    fun findHomeBanners(
        limit: Int,
        memberId: Long? = null,
-        includeAdultBanners: Boolean = false
+        includeAdultBanners: Boolean = false,
+        lang: Lang = Lang.KO
    ): List<HomeBannerRecommendationRecord>

    fun findRecentlyActiveCreators(
@@ -207,6 +207,22 @@ class MemberContentPreferenceIntegrationTest @Autowired constructor(
        assertEquals("KR", service.resolveCountryCode(member))
    }

+    @Test
+    @DisplayName("비로그인 사용자의 국가 코드는 접속 국가 헤더를 정규화하고 없으면 KR로 계산된다")
+    fun shouldResolveCountryCodeForAnonymousUser() {
+        countryContext.setCountryCode("JP")
+        assertEquals("JP", service.resolveCountryCode(null))
+
+        countryContext.setCountryCode(" jp ")
+        assertEquals("JP", service.resolveCountryCode(null))
+
+        countryContext.setCountryCode(null)
+        assertEquals("KR", service.resolveCountryCode(null))
+
+        countryContext.setCountryCode(" ")
+        assertEquals("KR", service.resolveCountryCode(null))
+    }
+
    private fun saveMember(seed: String): Member {
        return memberRepository.saveAndFlush(
            Member(
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.v2.api.home.application

+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.v2.recommendation.application.HomeRecommendationQueryService
@@ -56,6 +57,27 @@ class HomeRecommendationFacadeTest {
        assertTrue(queryPort.bannerIncludeAdultBanners)
    }

+    @Test
+    @DisplayName("홈 추천은 JP 국가 판정이면 JA 배너 조회를 요청한다")
+    fun shouldPassJaToHomeBannerQueryForJapan() {
+        val member = Member(password = "password", nickname = "jp-member").apply { id = 11L }
+        Mockito.doReturn("JP").`when`(preferenceService).resolveCountryCode(member)
+
+        facade.getHomeRecommendations(member)
+
+        assertTrue(queryPort.bannerLang == Lang.JA)
+    }
+
+    @Test
+    @DisplayName("홈 추천은 JP 이외 국가 판정이면 KO 배너 조회를 요청한다")
+    fun shouldPassKoToHomeBannerQueryForNonJapan() {
+        Mockito.doReturn("KR").`when`(preferenceService).resolveCountryCode(null)
+
+        facade.getHomeRecommendations(null)
+
+        assertTrue(queryPort.bannerLang == Lang.KO)
+    }
+
    private fun firstAudio(price: Int, isPointAvailable: Boolean): HomeFirstAudioContentRecord {
        return HomeFirstAudioContentRecord(
            contentId = price.toLong() + 1,
@@ -74,6 +96,7 @@ class HomeRecommendationFacadeTest {
    private class FakeHomeRecommendationQueryPort : HomeRecommendationQueryPort {
        var firstAudioContents: List<HomeFirstAudioContentRecord> = emptyList()
        var bannerIncludeAdultBanners: Boolean = false
+        var bannerLang: Lang? = null

        override fun findLiveRecommendations(
            offset: Long,
@@ -85,9 +108,11 @@ class HomeRecommendationFacadeTest {
        override fun findHomeBanners(
            limit: Int,
            memberId: Long?,
-            includeAdultBanners: Boolean
+            includeAdultBanners: Boolean,
+            lang: Lang
        ): List<HomeBannerRecommendationRecord> {
            bannerIncludeAdultBanners = includeAdultBanners
+            bannerLang = lang
            return emptyList()
        }

@@ -12,6 +12,7 @@ import kr.co.vividnext.sodalive.content.main.tab.AudioContentMainTab
 import kr.co.vividnext.sodalive.content.theme.AudioContentTheme
 import kr.co.vividnext.sodalive.creator.admin.content.series.Series
 import kr.co.vividnext.sodalive.creator.admin.content.series.SeriesContent
+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.MemberRole
 import kr.co.vividnext.sodalive.member.block.BlockMember
@@ -96,6 +97,38 @@ class DefaultAudioRecommendationQueryRepositoryTest @Autowired constructor(
        assertEquals(visibleCreator.id, safeBanners.first().creatorId)
    }

+    @Test
+    @DisplayName("콘텐츠 추천 배너는 언어 필터를 limit보다 먼저 적용한다")
+    fun shouldFilterBannersByLangBeforeLimit() {
+        val recommendationTab = saveContentRecommendationTab()
+        val koBanner = saveBanner(
+            "ko-audio-banner.png",
+            AudioContentBannerType.LINK,
+            1,
+            link = "https://ko.test",
+            tab = recommendationTab,
+            lang = Lang.KO
+        )
+        val jaBanner = saveBanner(
+            "ja-audio-banner.png",
+            AudioContentBannerType.LINK,
+            2,
+            link = "https://ja.test",
+            tab = recommendationTab,
+            lang = Lang.JA
+        )
+        flushAndClear()
+
+        assertEquals(
+            listOf("https://cdn.test/${koBanner.thumbnailImage}"),
+            repository.findBanners(1, null, false, Lang.KO).map { it.imageUrl }
+        )
+        assertEquals(
+            listOf("https://cdn.test/${jaBanner.thumbnailImage}"),
+            repository.findBanners(1, null, false, Lang.JA).map { it.imageUrl }
+        )
+    }
+
    @Test
    @DisplayName("오리지널 시리즈는 활성 원본 시리즈를 최신순으로 반환하고 성인/차단 조건을 적용한다")
    fun shouldFindOriginalSeriesWithVisibilityConditions() {
@@ -404,11 +437,13 @@ class DefaultAudioRecommendationQueryRepositoryTest @Autowired constructor(
        isAdult: Boolean = false,
        creator: Member? = null,
        link: String? = null,
-        tab: AudioContentMainTab? = null
+        tab: AudioContentMainTab? = null,
+        lang: Lang = Lang.KO
    ): AudioContentBanner {
        val banner = AudioContentBanner(
            thumbnailImage = thumbnailImage,
            type = type,
+            lang = lang,
            isAdult = isAdult,
            isActive = isActive,
            orders = orders
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.v2.content.recommendation.application

+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.MemberRole
 import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
@@ -77,7 +78,7 @@ class AudioRecommendationQueryServiceTest {
            0,
            AudioRecommendationQueryService.RECOMMENDED_AUDIO_LIMIT
        )
-        Mockito.verify(queryPort).findBanners(AudioRecommendationQueryService.BANNER_LIMIT, null, false)
+        Mockito.verify(queryPort).findBanners(AudioRecommendationQueryService.BANNER_LIMIT, null, false, Lang.KO)
        Mockito.verify(queryPort).findLatestAudios(
            eqValue(AudioRecommendationQueryService.LATEST_AUDIO_LIMIT),
            Mockito.isNull(),
@@ -140,6 +141,7 @@ class AudioRecommendationQueryServiceTest {
    fun shouldUseStoredPreferenceForMemberAdultVisibility() {
        val member = member(id = 10L)
        Mockito.doReturn(true).`when`(preferenceService).canViewAdultContent(member)
+        Mockito.doReturn("JP").`when`(preferenceService).resolveCountryCode(member)
        stubFallback(
            RecommendedSectionType.NEW_AND_HOT_AUDIO_ALL,
            0,
@@ -150,6 +152,7 @@ class AudioRecommendationQueryServiceTest {
        service.getRecommendations(member)

        Mockito.verify(preferenceService).canViewAdultContent(member)
+        Mockito.verify(queryPort).findBanners(AudioRecommendationQueryService.BANNER_LIMIT, member.id, true, Lang.JA)
        Mockito.verify(preferenceService, Mockito.never()).initializeDefaultPreference(member)
        verifyFallback(
            RecommendedSectionType.NEW_AND_HOT_AUDIO_ALL,
@@ -262,6 +262,23 @@ class DefaultHomeRecommendationQueryRepositoryTest @Autowired constructor(
        assertEquals(listOf(homeBanner.thumbnailImage), banners.map { it.thumbnailImage })
    }

+    @Test
+    @DisplayName("홈 배너는 언어 필터를 limit보다 먼저 적용한다")
+    fun shouldFilterHomeBannersByLangBeforeLimit() {
+        val koBanner = saveBanner("ko-home-banner.png", AudioContentBannerType.LINK, 1, true, lang = Lang.KO)
+        val jaBanner = saveBanner("ja-home-banner.png", AudioContentBannerType.LINK, 2, true, lang = Lang.JA)
+        flushAndClear()
+
+        assertEquals(
+            listOf(koBanner.thumbnailImage),
+            repository.findHomeBanners(limit = 1, lang = Lang.KO).map { it.thumbnailImage }
+        )
+        assertEquals(
+            listOf(jaBanner.thumbnailImage),
+            repository.findHomeBanners(limit = 1, lang = Lang.JA).map { it.thumbnailImage }
+        )
+    }
+
    @Test
    @DisplayName("홈 배너는 성인 콘텐츠 조회가 불가능하면 비성인 배너만 반환한다")
    fun shouldExcludeAdultHomeBannersWhenAdultContentIsNotVisible() {
@@ -2693,12 +2710,13 @@ class DefaultHomeRecommendationQueryRepositoryTest @Autowired constructor(
        event: Event? = null,
        series: Series? = null,
        tab: AudioContentMainTab? = null,
-        link: String? = null
+        link: String? = null,
+        lang: Lang = Lang.KO
    ): AudioContentBanner {
        val banner = AudioContentBanner(
            thumbnailImage = thumbnailImage,
            type = type,
-            lang = Lang.KO,
+            lang = lang,
            isAdult = isAdult,
            isActive = isActive,
            orders = orders
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.v2.recommendation.application

+import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.v2.common.domain.CreatorActivityType
 import kr.co.vividnext.sodalive.v2.recommendation.domain.RecommendedSectionType
 import kr.co.vividnext.sodalive.v2.recommendation.port.out.HomeAiCharacterRecommendationRecord
@@ -93,6 +94,16 @@ class HomeRecommendationQueryServiceTest {
        assertEquals(20, port.bannerLimit)
        assertEquals(100L, port.bannerMemberId)
        assertEquals(true, port.bannerIncludeAdultBanners)
+        assertEquals(Lang.KO, port.bannerLang)
+        assertEquals(port.banners, banners)
+    }
+
+    @Test
+    @DisplayName("홈 배너 추천은 언어 조건을 조회 포트에 위임한다")
+    fun shouldDelegateHomeBannerLang() {
+        val banners = service.findHomeBanners(lang = Lang.JA)
+
+        assertEquals(Lang.JA, port.bannerLang)
        assertEquals(port.banners, banners)
    }

@@ -966,6 +977,7 @@ class HomeRecommendationQueryServiceTest {
        var bannerLimit: Int? = null
        var bannerMemberId: Long? = null
        var bannerIncludeAdultBanners: Boolean? = null
+        var bannerLang: Lang? = null
        var activeCreatorLimit: Int? = null
        var activeCreatorMemberId: Long? = null
        var activeCreatorIncludeAdultActivities: Boolean? = null
@@ -1068,11 +1080,13 @@ class HomeRecommendationQueryServiceTest {
        override fun findHomeBanners(
            limit: Int,
            memberId: Long?,
-            includeAdultBanners: Boolean
+            includeAdultBanners: Boolean,
+            lang: Lang
        ): List<HomeBannerRecommendationRecord> {
            bannerLimit = limit
            bannerMemberId = memberId
            bannerIncludeAdultBanners = includeAdultBanners
+            bannerLang = lang
            return banners
        }
Author	SHA1	Message	Date
klaus	2ad30f9069	docs(recommendation): 추천 배너 언어 필터 계획을 기록한다	2026-08-19 17:10:42 +09:00
klaus	1731b3a8c1	feat(recommendation): 추천 배너 언어 필터를 적용한다	2026-08-19 17:10:05 +09:00