From 95e5c2e11f2a3338721c72bbc1fd2139d348d7b4 Mon Sep 17 00:00:00 2001 From: klaus Date: Fri, 30 Oct 2026 12:23:14 +0900 Subject: [PATCH] =?UTF-8?q?docs(subbanner):=20=EA=B5=AC=ED=98=84=20?= =?UTF-8?q?=EA=B3=84=ED=9A=8D=EA=B3=BC=20=EA=B2=80=EC=A6=9D=20=EA=B2=B0?= =?UTF-8?q?=EA=B3=BC=EB=A5=BC=20=EA=B8=B0=EB=A1=9D=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/20261029_추천_서브_배너/plan-task.md | 142 ++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/20261029_추천_서브_배너/plan-task.md diff --git a/docs/20261029_추천_서브_배너/plan-task.md b/docs/20261029_추천_서브_배너/plan-task.md new file mode 100644 index 00000000..a3746df2 --- /dev/null +++ b/docs/20261029_추천_서브_배너/plan-task.md @@ -0,0 +1,142 @@ +# 추천 서브 배너 구현 계획 + +> 실행 방식: 현재 checkout에서 전문 작업을 분리하여 진행한다. worktree를 만들지 않는다. Gradle 실행은 반드시 직렬화한다. + +**Goal:** 홈·콘텐츠 추천의 지정 위치에서 전체 너비·원본 비율 서브 배너를 5초마다 전환하고 안전한 링크로 이동한다. +**Architecture:** 공통 `v2/widget/subbanner` 데이터·링크 정책과 전용 가변 높이 View를 두 추천 화면에서 사용한다. 기존 정사각형 `BannerView`는 수정하지 않는다. +**Tech Stack:** Kotlin, XML Views, RecyclerView, Coil 2.7, Retrofit/RxJava3/Gson, JUnit4/Robolectric. +**Spec:** [prd.md](prd.md) +**상태:** 구현·관련 회귀·코드 리뷰 완료, 최종 전체 회귀 및 실제 화면 QA 제한. 작성일 2026-10-29, 최종 갱신 2026-10-30. + +## 범위와 제약 + +- 사용자 제공 JSON 이름 `id`, `placement`, `imageUrl`, `webUrl`, `androidDeepLink`, `iosDeepLink`를 그대로 사용한다. +- 기존 추천 GET 안에서 처리하고 별도 endpoint/query·운영 fixture·날짜 필드/기간 타이머·의존성을 추가하지 않는다. +- 외부 URI 검증과 실행 실패 처리 외의 추측성 fallback/추상화는 추가하지 않는다. +- 레거시 및 기존 메인 배너 구현은 수정하지 않는다. 신규 코드는 v2 하위에 둔다. +- 자동 테스트는 app/src/test의 정책·매핑·요청·상태·타이머·콜백 로직이다. 레이아웃 속성 assertion 및 androidTest는 추가하지 않는다. +- 연결된 사용자 기기 데이터 삭제나 로그인 상태 변경은 금지한다. 실제 화면 검증 가능 여부와 제약을 별도로 기록한다. + +## 현재 상태 + +| Phase | 결과 | 상태 | +|---|---|---| +| 1 | 단일 추천 응답·익명 헤더·안전한 링크 | 구현·focused 검증 완료 | +| 2 | 가변 높이 캐러셀 및 화면 삽입 | 구현·focused 검증 완료 | +| 3 | 통합 검증 및 리뷰 | 코드 승인·관련 검증 완료, 전체 회귀/실제 화면 QA 제한 | + +## Review Focus + +- 선택하지 않은 이미지 또는 이전 목록의 늦은 callback이 현재 높이를 바꾸지 않는다. +- 초기 높이가 0이어도 이미지 로딩을 시작하고 성공 시 표시한다. +- 다른 탭으로 전환하거나 detach/stop하면 자동 전환이 중지된다. +- 서브 배너만 있는 응답을 Empty로 처리하지 않으며 refresh 실패와 빈 성공 응답을 구별한다. +- ID 정밀도, URI 원문, 익명 Authorization 생략과 기존 follow 인증을 보존한다. + +## Phase 1 + +**결과:** 두 GET에서 올바른 서브 배너 목록을 얻고 Android 우선 링크를 안전하게 실행한다. + +#### Task 1.1 공통 계약 및 데이터·링크 통합 + +- **시작 조건:** PRD 확정 및 기존 테스트 baseline 통과. +- **범위:** `v2/widget/subbanner/SubBannerModels.kt`, `SubBannerLinkPolicy.kt`; 양쪽 추천 data API/Models/Repository, model Mappers/UiState, HomeRecommendationViewModel/ContentMainViewModel. +- **테스트:** `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/subbanner/` 계약/링크/API 테스트, 기존 home/content 테스트 및 필요 시 ContentMainViewModelTest. +- **Interfaces:** `SubBannerPlacement` enum; `SubBannerResponse`의 공개 6필드; `SubBannerItem(id: Long, imageUrl: String, androidDeepLink: String?, webUrl: String?)`; `toSubBannerItems(placement)`; `SubBannerLinkPolicy.launch(context, item): Boolean`; 각 Content의 `subBanners: List`. +- **완료 증거:** S1/S3/S4 focused 테스트 성공. ID 9007199254740993 및 Long.MAX_VALUE JSON 정밀도, 링크 8조합, URI 원문/금지 scheme/실패 fallback, 실제 Retrofit 경계의 GET path/header/요청 횟수/오류 검증. +- [x] **RED:** 계약·필터·링크·익명 GET·에러/empty 회귀 테스트 작성. +- [x] **RED 확인:** 변경 전 동작의 불일치를 focused 테스트로 확인. +- [x] **GREEN:** DTO/정책/매핑/state 및 GET의 nullable 헤더를 최소 변경한다. follow 인증은 그대로 둔다. +- [x] **GREEN 확인:** focused 테스트 통과. +- [x] **REFACTOR:** 새 코드 중복 및 관련 회귀만 확인. + +검증 명령: `./gradlew :app:testDebugUnitTest --tests '*SubBanner*Test' --tests '*HomeRecommendationViewModelTest' --tests '*AudioRecommendationsMapperTest' --tests '*ContentMainViewModelTest' --console=plain` + +**검증 기록:** RED 최초 16개 중 6개 실패, 확장 계약/링크 RED 37개 중 18개 실패 후 동일 focused 명령 GREEN 51개 성공. 부모가 최종 XML에서 6개 suite의 tests 합계 51, failures/errors/skipped 모두 0 확인. 실제 Retrofit interceptor로 GET 경로/횟수/헤더 및 HTTP 오류를 검증했고, Gson에서 ACTION_VIEW까지 Robolectric Context 실행을 확인했다. 잘못된 개별 ID가 추천 전체 파싱을 실패시키지 않도록 전용 DTO 역직렬화가 숫자 문자열을 정수로 정확히 검증한다. Home follow 인증은 변경하지 않았다. 테스트의 비동기 저장소 초기화 경쟁은 token mock과 looper flush로 격리했으며 기존 assertion은 유지했다. + +## Phase 2 + +**결과:** 지정된 두 화면에서 배너가 잘리지 않고 현재 원본 비율로 전환된다. + +#### Task 2.1 전용 가변 높이 캐러셀과 두 화면 연결 + +- **시작 조건:** Task 1.1의 모델 인터페이스 확정. UI 작업과 데이터 작업의 파일 소유권은 분리하며 테스트 실행은 직렬화. +- **생성:** `v2/widget/subbanner/SubBannerView.kt`, 필요 최소 presentation state/adapter, `res/layout/view_sub_banner.xml`, `item_sub_banner.xml`. +- **수정:** `v2/main/home/HomeMainFragment.kt`, `v2/main/content/ContentMainFragment.kt`, `res/layout/fragment_v2_main_home.xml`, `fragment_v2_main_content.xml`. +- **테스트:** 공통 subbanner의 presentation/콜백/타이머 로컬 테스트. 기존 banner 테스트는 불변. +- **Interfaces:** `SubBannerView.setItems(List)`, `setOnBannerClickListener`; 필요 시 명시적 lifecycle/release API. 전체 wrapper를 숨겨 추가 margin도 제거한다. +- **완료 증거:** S2와 인접 회귀. 현재 이미지의 natural 비율만 적용, 초기 이미지 요청 bootstrap, stale callback 무시, rebind/detach 취소, 5000ms 전환, 단일/빈 목록 정지, 숨김/stop 정지. +- [x] **RED:** presentation/타이머·이미지 실패 격리 테스트 작성. +- [x] **RED 확인:** 미구현 동작의 의도한 실패 확인. +- [x] **GREEN:** full-width fitCenter 및 현재 이미지별 높이, 지정 위치·48dp 간격, 빈 컴포넌트 숨김, 안전한 클릭 연결. +- [x] **GREEN 확인:** 신규 및 기존 banner/home/content 회귀 테스트 통과. +- [x] **REFACTOR:** 요청/타이머/리스너 수명주기 정리 확인. + +**검증 기록:** 컴파일 가능한 no-op 상태 stub으로 RED 14개 중 10개 실패 확인. 실제 Coil callback과 RecyclerView 로컬 driver를 포함한 신규 UI 테스트 40개 및 기존 회귀를 합쳐 19 suite/259개 통과, `assembleDebug` 성공. `app/build/reports/subbanner-phase2-state-red.log`, `subbanner-phase2-final-green.log`에 실행 증거를 남겼다. 현재 이미지 요청만 시작하고 실패 항목을 건너뛰며 전체 실패 시 중단한다. 같은 정상 목록은 초기화하지 않고 실패가 있었던 목록은 새 바인딩 시 재시도한다. 레이아웃 속성 assertion이나 계측 테스트는 추가하지 않았다. + +이미지 실패는 해당 이미지에 국한한다. 원본 비율을 모르는 동안 임의의 고정 비율을 만들지 않는다. 전체 이미지가 실패해도 나머지 추천 콘텐츠가 유지되어야 한다. + +## Phase 3 + +#### Task 3.1 통합 검증 및 단일 리뷰 + +- **시작 조건:** Phase 1/2 구현 완료. +- **범위:** 변경 파일 전부 확인, 테스트/빌드/lint, 가능한 실제 UI 검증, 단일 전문 리뷰, 본 문서 기록. +- **TDD 예외 사유:** 검증·리뷰·문서 Task. 코드를 수정하면 해당 회귀 Task를 먼저 추가한다. +- [x] focused 및 기존 관련 회귀 테스트 통과. +- [x] `./gradlew :app:testDebugUnitTest --console=plain` 전체 local suite 실행. +- [x] `./gradlew :app:assembleDebug :app:lintDebug --console=plain` 실행. +- [x] 지원되는 진단 실행, 미지원 도구와 대체 컴파일 검증 명시. +- [x] 실제 표시·전환·빈 목록 검증 증거 확보 또는 환경 차단 명시. +- [x] `reviews/phase3-sub-banner-review.md`에 단일 리뷰와 확정 발견사항/수정 증거 기록. +- [x] 소유 QA 자원 정리 및 최종 결과 기록(공유 ADB 로그 보존 예외는 아래 기록). + +#### Task 3.2 REV-P3-001 전환 중 목록 교체 재진입 회귀 수정 + +- **시작 조건:** 최종 리뷰에서 setItems의 새 state 설정 뒤 stopScroll의 IDLE callback이 이전 adapter 위치를 새 선택에 적용하는 경로 발견. 실행 재현을 먼저 확인한다. +- **대상:** `v2/widget/subbanner/SubBannerView.kt`, `app/src/test/java/kr/co/vividnext/sodalive/v2/widget/subbanner/SubBannerImageRequestTest.kt`. +- **수정 범위:** 목록 교체 구간의 이전 스크롤 callback을 차단하여 state/adapter/currentPosition/이미지 요청을 일관되게 초기화한다. 동일 정상 목록 no-op는 유지한다. +- **회귀 테스트:** 실제 RecyclerView의 두 번째→세 번째 SETTLING 도중 다른 3개 목록을 전달하여 새 첫 번째 선택·이미지 요청·실제 adapter 위치·클릭 payload가 일치한다. +- **완료 증거:** 수정 전 RED, 최소 수정 후 같은 테스트 GREEN, 관련 subbanner/main banner/home/content 회귀, 기존 리뷰어의 delta 승인. +- [x] **RED:** 재현 테스트 작성 및 실행 실패 확인(재현되지 않으면 근거를 검토해 판정). +- [x] **GREEN:** callback 재진입 최소 수정 및 해당 테스트 성공. +- [x] **REFACTOR:** 관련 회귀와 delta 리뷰 완료. + +**검증 기록:** `SubBannerImageRequestTest` 10개 중 신규 테스트가 expected id=4/actual id=5로 실패했다. 목록 교체 구간의 `replacingItems` guard와 dragging 초기화를 적용한 뒤 10개 모두 성공했다. 관련 16 suite/237 tests와 assembleDebug 성공, 동일 리뷰어의 delta 판정 APPROVE. 로그는 `app/build/reports/subbanner-review-fix-red.log`, `subbanner-review-fix-green.log`, `subbanner-review-fix-focused-build.log`. + +#### Task 3.3 신규 코드 진단 정리 + +- **시작 조건:** ktlintMainSourceSetCheck 성공, ktlintTestSourceSetCheck에서 이번 추가 테스트의 argument wrapping 오류 확인. +- **대상:** 신규 subbanner 테스트 및 이번 변경의 HomeRecommendationViewModelTest/ContentMainViewModelTest/AudioRecommendationsMapperTest 추가 부분. 신규 경고의 `SubBannerLinkPolicy.kt`, `item_sub_banner.xml`, `SubBannerAdapter.kt`. +- **수정 범위:** 테스트 의미·assertion을 유지한 줄바꿈 정리, 테스트 blockingGet 결과를 검증에 사용, 기존 URI 원문 보존을 유지한 KTX 사용, 런타임 이미지 설명을 동일 XML 값으로 이동. 기존 미수정 코드의 진단은 제외한다. +- **TDD 예외 사유:** 형식 및 동등한 표현 정리. 기존 테스트 유지와 focused 재실행으로 검증한다. +- [x] 신규/변경 테스트의 신규 ktlint 오류 제거 및 기존 test source 오류 구분. +- [x] 신규 Android lint 경고 정리 후 focused 회귀 성공. + +**검증 기록:** 소유 변경 파일의 ktlint/Android lint 진단 0건. 전체 Android lint는 기존 32 errors/798 warnings, 신규 경고 9건 제거. 강제 전체 ktlint 재검사에서 기존 main 196건/186파일, test 26건/2파일이 남았다. test 잔여는 `CreatorChannelFanTalkFragmentLayoutTest.kt` 20건 및 `ChatRepositoryTest.kt` 6건이며 변경하지 않았다. 앞서 main 성공은 증분 task 결과였고 강제 재검사에서는 기존 오류가 확인되었으므로 전체 ktlint 통과로 해석하지 않는다. + +## Progress + +- 2026-10-29: 사용자 요청과 코드 조사로 위치·간격 및 기존 배너의 정사각형 제약 확인. 원본 비율별 가변 높이/5초/빈 컴포넌트 숨김과 worktree 미사용 승인. +- 계획 agent의 wire-key 미정 언급은 최초 제공 계약으로 해소됨. 키 이름을 다시 질문하지 않는다. UI는 visual-engineering에 위임하며 기존 BannerView를 변경하지 않는다. + +## Verification Log + +- 변경 전 baseline: `:app:testDebugUnitTest --tests '*HomeRecommendationViewModelTest' --tests '*AudioRecommendationsMapperTest' --tests 'kr.co.vividnext.sodalive.v2.widget.banner.*'` 성공. 첫 실행은 120초 도구 timeout, 후속 600초 제한 실행은 BUILD SUCCESSFUL. +- Java 런타임은 `/Users/klaus/Applications/Android Studio.app/Contents/jbr/Contents/Home`의 JAVA_HOME을 명시한다. +- 본 세션에는 `lsp_diagnostics` 도구가 제공되지 않는다. Kotlin 컴파일·lint를 대체 증거로 쓰고 LSP 성공을 주장하지 않는다. +- 테스트 서버의 두 추천 GET을 Authorization 없이 curl로 조회: 모두 HTTP 200/success:true이나 `data`에 `subBanners` 키 자체가 없음(`hasSubBanners:false`). 계약을 변경하지 않고 기존 응답 호환은 유지한다. 실서버 다중 배너 노출은 검증할 수 없어 명시적 fixture 증거와 구별한다. +- 사용자 연결 기기는 기존 앱이 설치되어 있어 수정하지 않는다. 소유 임시 경로의 신규 AVD `SubBannerQA`(port 5580)로 화면 확인을 준비한다. 기존 사용자 AVD는 수정하지 않는다. +- 화면 QA 환경 제한: 새 AVD가 앱 설치 전부터 `System UI isn't responding` 상태이고 boot completion이 오지 않았다. software GPU와 host GPU/4 cores 방식으로 시도했으나 안정적인 부팅을 확보하지 못해 두 소유 emulator 프로세스를 종료했다. 이 결과를 앱 UI 실패나 통과로 간주하지 않는다. 기존 연결 기기를 임의 변경하지 않는다. +- 통합 명령 `:app:testDebugUnitTest :app:assembleDebug :app:lintDebug --console=plain`: 224 suite/1,814 tests, failures/errors/skipped 모두 0. assembleDebug 성공. lintDebug는 32 errors/807 warnings로 실패했다. 오류는 미수정 FacebookActivity 참조, 기존 Media3 opt-in, 기존 XML 제약/tint 및 문자열 포맷 등이며 변경 diff에 해당 오류 코드 수정은 없다. 전체 lint 통과로 주장하지 않는다. +- 신규 lint 경고는 SubBannerApiTest의 반환값 미사용 7건, URI KTX 제안 1건, XML contentDescription 1건(실제 holder bind에서 제공)이다. 최종 리뷰에서 동작 결함과 구별해 판단한다. +- Phase 1 독립 리뷰 결과 APPROVE, 확정 blocker 없음. 최종 통합 리뷰 재개 시 기존 리뷰 session이 사라져 이전 승인과 검증 증거를 전달한 대체 리뷰어 한 명으로 이어간다. 병렬 리뷰 패널은 만들지 않는다. +- `:app:assembleDebug tasks --all` exit 0, BUILD SUCCESSFUL. `git diff --check` 통과. 자식 작업 임시 root와 소유 AVD 부재를 부모가 재확인했다. +- `:app:ktlintMainSourceSetCheck :app:ktlintTestSourceSetCheck --continue`: main 성공, test 실패. 이번 신규 테스트의 argument wrapping은 Task 3.3에서 정리하며 나머지 기존 실패는 수정하지 않는다. +- 2026-10-30 최종 수정 후 부모 검증: `:app:testDebugUnitTest --tests '*SubBanner*Test' --tests '*HomeRecommendationViewModelTest' --tests '*ContentMainViewModelTest' --tests '*AudioRecommendationsMapperTest' --tests 'kr.co.vividnext.sodalive.v2.widget.banner.*' --tests '*HomeMainFragment*Test' --tests '*ContentMainFragment*Test' :app:assembleDebug --no-daemon --max-workers=2 --console=plain` exit 0, **19 suite/260 tests**, failures/errors/skipped 모두 0, BUILD SUCCESSFUL. +- [blocked] 최종 수정 후 전체 suite는 완료되지 않았다. 첫 실행은 `Gradle Test Executor 33` exit 1, 새 daemon/2 workers/상세 로그 실행도 `Gradle Test Executor 1` exit 1로 종료했다. 두 번째 실행에서 미수정 `V2AuthFlowTest.kt:844`의 isAdultContentVisible assertion 실패도 관찰했다. JVM crash dump/명시적 OOM 근거는 발견하지 못했고 원인은 확정하지 않았다. 수정 전 전체 1,814개 성공 기록은 보존하되 최신 전체 성공으로 재사용하지 않는다. 세 번째 전체 재시도나 범위 밖 인증 코드 수정은 하지 않았다. +- [blocked] 실제 화면 QA 및 실제 서버 다중 배너 노출은 앞서 기록한 AVD/응답 제약으로 미검증이다. 관련 로컬 driver 결과를 실제 기기 시각 QA 성공으로 대체하지 않는다. +- 최종 코드 리뷰: REV-P3-001 수정 확인 후 **APPROVE**, 신규 차단 사항 없음. 이는 코드 승인이고 전체 suite/시각 QA 제한을 해소한 판정은 아니다. +- 자원 정리: 소유 emulator 2개 PID 종료, AVD 및 세 자식 임시 root 부재 확인. 부모의 임시 캡처·실행 로그·에뮬레이터 설정·notepad도 제거했다. 테스트/build/lint 증거와 오류 요약은 app/build 보고서와 본 문서에 남겼다. +- [blocked] 공유 ADB 정리 예외: 이 작업에서 시작된 ADB PID 77369에 다른 로컬 클라이언트의 연결 5개가 있어 서버를 종료하지 않았다. 사용자 연결을 끊지 않기 위해 `/var/folders/yh/8xsbvpsj5wg2qnxzxdp11_gm0000gn/T/opencode/sub-banner-ulw.4LleIT/adb.501.log`와 부모 폴더만 보존한다. 해당 서버가 종료된 뒤 삭제할 수 있다. 공유 Gradle/SDK 캐시는 삭제하지 않았다. +- 2026-10-30 커밋 전 검증: 위 최종 관련 회귀·`:app:assembleDebug` 명령을 같은 JAVA_HOME, `--no-daemon --max-workers=2 --console=plain`으로 실행하여 exit 0, BUILD SUCCESSFUL 확인. 테스트 task는 UP-TO-DATE로 기존 결과를 재사용했으며 결과 XML 19 suite/260 tests의 failures/errors/skipped가 모두 0임을 확인했다. `git diff --check` 통과. 전체 suite·lint·실제 화면 QA는 이번 커밋 작업에서 재실행하지 않았으며 기존 제한은 유지한다.