docs(i18n): 연관 콘텐츠 제목 번역 요구사항과 검증 결과를 기록한다

This commit is contained in:
2026-11-17 13:17:11 +09:00
parent 0796b2b4fb
commit 9cadaa919b
3 changed files with 171 additions and 2 deletions
@@ -2,7 +2,7 @@
| 항목 | 내용 |
|---|---|
| 상태 | 상세 조회 동기 번역 포함 구현·기능 검증·독립 리뷰 완료 |
| 상태 | 연관 콘텐츠 제목 번역 포함 구현·기능 검증·독립 리뷰 완료 |
| 작성일 | 2026-11-16 |
| 요구사항 | [prd.md](prd.md) |
| 현재 활성 Goal | 없음 |
@@ -327,3 +327,69 @@ REQUIRES_NEW 진입점을 사용한다. FAILED 후보가 없으면 원문을 불
- 2026-11-17 P2-GATE 리뷰: 단일 Oracle reviewer APPROVE. MT-011~014 충족, API/DB/worker 정책 보존과 실제 HTTP/DB 실패·경합 증거를 확인했고 차단 사항이 없다. 구매 전 translated.detail이 전체 payload인 기존 계약을 변경하지 않았음을 확인했다. 운영 MySQL JSON/1062/잠금 및 실제 공급자 지연은 미검증 범위다. 신규 테스트 명령 예시는 `docs/agent-guides/실행명령어.md`에 추가했다.
- 2026-11-17 P2-GATE 정리 완료: 부모 QA runner/test worker/Gradle wrapper가 없고 HTTP 포트 58600에 listener가 없음을 확인했다. 검증 결과와 응답 발췌를 문서에 보존한 뒤 부모 RUN_TMP의 Java/init script·class·로그·notepad를 삭제하고 디렉터리 부재를 확인했다(exit 0). 구현자 임시 root 2개도 제거했으며 공유 캐시/기존 IDE daemon은 건드리지 않았다. 커밋·배포는 하지 않았다.
- 2026-11-17 P2 커밋 전 재검증: 사용자 커밋 요청에 따라 상세 동기 번역·번역 패키지·감지·OSIV 직접 영향 범위 30개 클래스 277건을 재실행해 실패/오류/skip 0을 확인했다. `ktlintCheck`와 `bootJar`는 UP-TO-DATE, 전체 명령은 exit 0(2분 22초), `git diff --check`도 통과했다. 정확한 명령은 [동기 상세 검증 기록](reviews/synchronous-detail-review.md)의 커밋 전 재검증 절에 남긴다. 전체 테스트·실제 공급자·운영 MySQL은 미검증이며 전체 테스트는 사용자 실행 `./gradlew test`다.
## Phase 3: 상세 연관 콘텐츠의 저장된 번역 제목
**목표:** 상세의 이전화/다음화와 두 추천 목록에서 요청 언어에 맞는 저장된 제목이 표시된다.
**설계:** 기존 조회 결과의 ID를 모아 ContentTranslationRepository로 한 번 조회하고 OtherContentResponse를 copy한다.
원문 기반 탐색·정렬과 DTO 스키마를 보존하며, 공통 서비스나 새 의존성을 추가하지 않는다.
**기준:** PRD MT-015~016. 기존 상세 번역 작업의 연속 수정이므로 문서를 재사용한다.
- [x] **Task 3.1: 연관 콘텐츠 제목 번역 누락 수정**
**Goal P3-T1:** 네 응답 필드의 title은 현재 언어의 비어 있지 않은 저장 번역이며 없으면 기존 원문이다.
- 시작 조건: 사용자 최소 범위 승인, 기존 코드 및 HTTP 테스트 확인.
- 완료 증거: 실제 결함의 RED, 동일 HTTP 테스트 GREEN, 직접 영향 회귀.
- 범위 밖: 새 번역 생성, 공급자/작업 큐 변경, navigation 정렬 변경, DTO 확장, 전체 테스트.
Files:
- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.kt`
- Test: `src/test/kotlin/kr/co/vividnext/sodalive/content/AudioContentDetailTranslationHttpIntegrationTest.kt`
- Test configuration: `src/test/kotlin/kr/co/vividnext/sodalive/content/ContentDetailTranslationTestConfiguration.kt`
Interfaces: `findByContentIdInAndLocale(contentIds, locale)`와 기존 `OtherContentResponse(contentId, title, coverUrl)`를 사용한다.
- [x] **RED:** 기존 HTTP 테스트를 먼저 실행한 뒤 네 필드의 번역 선택과 fallback 회귀를 같은 테스트 클래스에 추가한다.
- [x] **RED 확인:** 새 번역 시나리오가 원문 제목 반환 assertion으로 실패함을 확인한다.
- [x] **GREEN:** getDetail에서 중복 제거한 관련 ID의 번역을 일괄 조회하고 비어 있지 않은 제목만 응답에 적용한다.
- [x] **GREEN 확인:** 같은 HTTP 테스트를 실행해 모든 필드가 기대 번역 또는 원문인 것을 확인한다.
- [x] **REFACTOR:** 직접 영향 기능 테스트 및 Kotlin 컴파일/ktlint 검증을 수행한다. 새 추상화나 무관한 정리는 하지 않는다.
### 시나리오 계약
1. 저장된 en/ja 제목: 실제 `GET /audio-content/{id}?timezone=UTC`를 en→ja→en으로 호출할 때 네 필드의 제목이 각 locale 값과 정확히 일치한다. ID·순서·coverUrl은 변하지 않는다.
2. fallback: 번역 없음·다른 locale만 존재·빈 제목·공백 제목에서 해당 항목은 원문이다. 연관 콘텐츠 때문에 공급자 호출 또는 번역 job이 추가되지 않는다.
3. 인접 회귀: 시리즈 없는 콘텐츠는 previousContent/nextContent가 null이고 관련 콘텐츠가 없으면 목록은 비어 있다. 본문 상세 번역과 기존 언어 감지·실패 복구 테스트는 통과한다.
### Phase 3 Gate
**Goal P3-GATE:** 승인된 네 필드의 HTTP 동작과 최소 변경 범위를 독립 검토하고 종료한다.
- 시작 조건: P3-T1 완료.
- 완료 증거: 아래 focused tests, 실제 HTTP JSON 관찰, lint/build, 단일 리뷰 판정과 임시 자원 정리 기록.
- 범위 밖: 운영 데이터 변경, 전체 테스트, 유료 공급자 호출.
- TDD 예외 사유: Gate는 구현이 아니라 결과 검증이다.
- 대체 검증 방법: HTTP 응답/테스트 결과/변경 diff 대조.
```bash
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.AudioContentDetailTranslationHttpIntegrationTest' --tests 'kr.co.vividnext.sodalive.content.AudioContentServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.AudioContentReadRetryTest' --console=plain
./gradlew --no-daemon ktlintCheck bootJar --console=plain
```
- [x] 실제 HTTP 응답에서 세 시나리오의 결과를 확인하고 기록한다.
- [x] 직접 영향 테스트와 ktlintCheck/bootJar 결과를 기록한다. LSP 도구가 제공되지 않으면 Kotlin 컴파일/ktlint 대체 사실을 명시한다.
- [x] 단일 독립 리뷰에서 차단 사항이 없음을 확인한다.
- [x] 작업 소유 임시 파일과 QA 자원을 정리하고 문서 상태를 갱신한다.
- 종료 조건: 위 시나리오가 실제 HTTP로 확인되고 관련 테스트 통과, 가능한 진단/빌드의 결과 및 한계 기록, 리뷰 승인과 임시 자원 정리가 끝나면 즉시 종료한다.
- 전체 테스트는 사용자 실행 `./gradlew test`이며 기능 범위 완료와 구분한다.
### P3 진행 기록
- 2026-11-17 조사/승인: 네 projection이 원문 title을 반환하고 상세 조립에 번역 적용이 없음을 확인했다. 기존 목록의 batch lookup 및 blank fallback을 재사용한다. 사용자가 저장된 번역만 적용하는 범위를 승인했다. 시작 작업 트리는 깨끗하다.
- 2026-11-17 baseline: 기존 `AudioContentDetailTranslationHttpIntegrationTest` 15건 통과(exit 0, 29초).
- 2026-11-17 P3-T1 RED: 테스트만 추가한 뒤 같은 HTTP 클래스 21건 중 1건 실패(exit 1, 38초). `shouldLocalizeRelatedTitlesForEachRequestedLanguageWithoutChangingNavigation`에서 previousContent의 기대 제목 `en 가 이전` 대신 `가 이전` 반환을 확인했다. ID와 coverUrl은 일치했다.
- 2026-11-17 P3-T1 GREEN: 위 Gate의 세 클래스 focused 명령 exit 0(51초). 상세 HTTP 21건, AudioContentServiceTest 16건, AudioContentReadRetryTest 1건으로 38건 전부 통과(실패/오류/skip 0). 부모가 XML 세 파일을 직접 확인했다. en→ja→en, 네 필드의 fallback·ID·cover·null/빈 목록, distinct 배치 1회/빈 경우 0회, 관련 공급자 호출·job 추가 없음이 검증됐다. 랜덤 추천 목록은 ID별로 대조하고, 각 요청의 순서는 서비스 map이 보존한다.
- 2026-11-17 lint/build 1차: `./gradlew --no-daemon ktlintCheck bootJar --console=plain` exit 1(25초). 신규 HTTP 테스트 두 표현식의 130자 초과 및 인자 줄바꿈 오류로 ktlintTestSourceSetCheck 실패. 제품 로직의 실패는 아니며 bootJar 성공으로 기록하지 않는다. 해당 표현식의 포맷만 수정하고 재검증한다.
- 2026-11-17 P3-GATE 부모 QA/lint/build: 인자 줄바꿈만 수정 후 `./gradlew --no-daemon -I "$TMPDIR/qa.init.gradle" runRelatedContentQa ktlintCheck bootJar --console=plain` exit 0(50초). Kotlin 테스트 재컴파일, ktlintCheck 및 bootJar 성공. 임시 Java HttpClient에서 실제 Tomcat 포트 59748로 GET 5회를 호출해 en→ja→en, 혼합 fallback, 빈 관계와 본문 번역 보존을 확인했다. 기존 38건의 동작 검증은 그대로 유효하며 포맷 수정 후 실제 HTTP QA로 추가 확인했다. 상세 증거는 [연관 콘텐츠 검증 기록](reviews/related-content-title-review.md)에 보존한다.
- 2026-11-17 P3-GATE 리뷰: 단일 Oracle reviewer APPROVE(신뢰도 높음), 차단 사항 없음. 네 필드의 요청 언어/fallback·조회 계약·번역 부작용 없음과 XML/실제 HTTP 증거를 확인했다. 부모가 QA PID 85049 부재, TCP 59748 listener 없음, 구현자 임시 root 부재를 확인했다.
- 2026-11-17 P3-GATE 완료: 실제 응답 및 리뷰 결과를 문서에 보존한 뒤 부모 `content-translation.TfjAph` root의 QA Java/init script·class·보고서와 별도 ulw 노트를 삭제했다(exit 0). 경로 부재를 확인했으며 공유 캐시와 작업 외 파일은 유지했다. 전체 테스트·운영 MySQL·실제 공급자/인증·배포는 미검증이다. 전체 테스트는 사용자 실행 `./gradlew test`다. 커밋은 하지 않았다.
- 2026-11-17 P3 커밋 전 재검증: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.AudioContentDetailTranslationHttpIntegrationTest' --tests 'kr.co.vividnext.sodalive.content.AudioContentServiceTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.AudioContentReadRetryTest' ktlintCheck bootJar --console=plain` exit 0(1분 1초). XML 세 파일에서 38건(21/16/1) 성공, 실패/오류/skip 0을 확인했다. `ktlintCheck`와 `bootJar`는 UP-TO-DATE이며 `git diff --check`도 통과했다. 전체 테스트·운영 MySQL·실제 공급자/인증·배포는 미검증이며 전체 테스트는 사용자 실행 `./gradlew test`다.