17 KiB
메타데이터 자동 번역 신속 반영 구현 계획
| 항목 | 내용 |
|---|---|
| 상태 | 구현·기능 검증·독립 리뷰 완료 |
| 작성일 | 2026-11-16 |
| 요구사항 | prd.md |
| 현재 활성 Goal | 없음 |
| 다음 Goal | 없음 |
목표와 제약
기존 DB 큐에서 감지 후 작업 등록, 최초+5회 재시도, 요청 시 실패 재개, AWS 번역 우선과 1초 워커를 제공한다.
Kotlin 1.6.21, Java 17, Spring Boot 2.7.14와 기존 패키지/스키마/API/캐시를 유지한다.
새 worktree, 커밋, 배포, 외부 유료 호출은 만들지 않는다. 시작 작업 트리는 깨끗했고 현재 브랜치는 test다.
단일 구현 Goal 안에서 파일이 겹치지 않는 작업을 분담하며, Gradle 실행은 부모가 직렬로 관리한다.
전체 테스트는 사용자 실행 ./gradlew test이며 에이전트는 기능별 테스트, ktlintCheck, bootJar만 실행한다.
Phase 1: 번역 수명주기와 요청 연결
- Task 1.1: 순서·재시도·신속 처리 구현
Goal P1-T1: 감지 성공부터 실패 소진 후 재요청까지 번역 상태가 요구사항대로 이어진다.
- 시작 조건: MT-001~007 확정, PRD와 이 계획 준비.
- 완료 증거: 아래 RED/GREEN, 트랜잭션 저장/롤백과 재개 검증, 기능별 회귀 통과.
- 범위 밖: 감지 자체 새 재시도, 외부 API/브로커 추가, 운영 데이터 일괄 변경, 응답 스키마 변경.
작업 A: 공통 큐와 워커
파일:
src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobScheduler.ktsrc/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobRepository.ktsrc/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobWorker.ktsrc/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobSchedulerTest.ktsrc/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobWorkerTest.kt- 같은 테스트 패키지의 DB 재시도 통합 테스트.
계약: 기존 scheduleMissingTranslation 시그니처를 유지한다. 기존 FAILED 행만 원자적으로 재개하고 현재 원문 해시를 사용한다. 진행 중 작업과 완료 작업은 요청으로 초기화하지 않는다. 워커는 최초 실행 뒤 5회 재시도하며 1/5/15/15/15분 지연을 사용한다. 기본 fixedDelay는 1000ms이며 5개 그룹 처리와 SKIP LOCKED claim을 유지한다.
재개 DB 경계는 TranslationJobRepository.restartFailedJob(jobId: Long, now: LocalDateTime): Int 조건부 update다.
id와 FAILED 조건으로 4개 필드를 함께 변경하며 persistence context를 자동 clear하지 않는다.
- RED: 기존 행의 상태별 재개, 동시 재개, 5회 재시도 경계와 1초 설정의 실패 테스트 작성.
- RED 확인:
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest'에서 의도한 assertion 실패 확인. - GREEN: 기존 상태 전이와 DB 경합 경계에서 최소 구현.
- GREEN 확인: 동일 focused 테스트와 추가 DB 통합 테스트 통과.
- REFACTOR: 새 중복만 정리하고 캐시/부분 실패 회귀를 기능별 실행.
작업 B: 언어 감지와 콘텐츠 수정
파일:
src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.ktsrc/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentService.ktsrc/main/kotlin/kr/co/vividnext/sodalive/creator/admin/content/CreatorAdminContentService.kt- 직접 생성자를 쓰는 해당 기능의 테스트 fixture.
src/test/kotlin/kr/co/vividnext/sodalive/content/의 감지 트랜잭션 통합 테스트 및 관련 관리자 수정 테스트.
계약: 일반 메타데이터 감지 성공 후 ResourceTranslationJobScheduler를 같은 트랜잭션에서 직접 호출한다. 커뮤니티의 기존 revision/hash 검증과 after-commit 경로는 보존한다. 관리자 제목/설명 변경과 크리에이터 관리자 태그 없는 제목/설명 변경도 커밋 후 번역 이벤트를 발행한다.
- RED: 실제 DB로 감지 후 작업 존재/롤백, 태그 없는 관리자 텍스트 수정의 작업 요청 누락을 재현.
- RED 확인: 해당 신규 감지 테스트와 관련 관리자 기능 테스트에서 의도한 실패 확인.
- GREEN: 기존 서비스/리스너에 최소 연결 수정.
- GREEN 확인: 감지·관리자 수정 focused 테스트 통과.
- REFACTOR: 커뮤니티 감지/동시성 기능 회귀를 별도 실행하고 기존 보호 확인.
작업 C: 공급자 기본 순서
파일:
src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/LanguageProviderOrder.ktsrc/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/LanguageProviderSpringConfigurationTest.kt- 필요한 production 기본값 소유 테스트.
docs/20261109_감지번역공급자공통화/provider-guide.md
계약: 번역 AWS/Papago, 감지 Papago/AWS. 기존 캐시와 fallback 유지.
- RED: 기본 Spring 설정에서 실제 coordinator가 AWS 번역을 선택하고 감지는 Papago를 선택하는 실패 테스트.
- RED 확인:
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderSpringConfigurationTest'의 선택 결과 실패 확인. - GREEN: production 순서와 현재 가이드 변경.
- GREEN 확인: 같은 테스트 및 provider/coordinator 관련 기능 회귀 통과.
- REFACTOR: 과거 이력은 보존하고 현재 실행 안내만 정합성 확인.
작업 D: 조회 시 실패 재개
파일:
src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.ktsrc/main/kotlin/kr/co/vividnext/sodalive/content/series/ContentSeriesService.ktsrc/main/kotlin/kr/co/vividnext/sodalive/content/theme/AudioContentThemeService.ktsrc/main/kotlin/kr/co/vividnext/sodalive/content/category/CategoryService.ktsrc/main/kotlin/kr/co/vividnext/sodalive/chat/character/controller/ChatCharacterController.ktsrc/main/kotlin/kr/co/vividnext/sodalive/chat/original/service/OriginalWorkTranslationService.ktsrc/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/community/translation/application/CreatorCommunityTranslationService.kt- 해당 기능의 기존/신규 focused 테스트.
최종 HTTP/DB 연결 확인 파일:
src/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/MetadataTranslationHttpIntegrationTest.kt.
실제 관리자 controller multipart 요청과 Spring 서비스/이벤트/DB를 실행하고 동일 FAILED 행 재개와 필드별 작업 저장을 검증한다.
외부 공급자는 호출하지 않고 비동기 executor를 테스트에서 동기 실행하여 커밋 후 동작을 결정적으로 확인한다.
계약: 기존 번역 요청 진입점에서 현재 원문과 대상 locale의 FAILED를 재개한다. 이전 번역 행이 있어도 요청이 전달된다. 원문 fallback과 기존 번역 응답을 유지하고, 관계없는 목록 전체에 번역 요청을 추가하지 않는다.
추가 공통 파일: src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/ResourceTranslationJobScheduler.kt.
읽기 전용 상위 트랜잭션에서도 저장 가능한 restartFailedResourceTranslations(resourceType, resourceIds: Collection<Long>, targetLanguage)
REQUIRES_NEW 진입점을 사용한다. FAILED 후보가 없으면 원문을 불필요하게 추출하지 않으며, 현재 원문에 해당하는 작업만 재개한다.
커뮤니티 쓰기 잠금 안에서는 이 REQUIRES_NEW 읽기 진입점을 호출하지 않고 기존 REQUIRED 예약으로 처리한다.
계획 검토에서 제안된 모든 projection/list의 광범위한 변경은 채택하지 않고 PRD의 기존 번역 요청 경계로 한정한다.
- RED: 이전 번역이 존재하는 상태에서도 조회가 현재 원문의 FAILED를 재개하는 실패 테스트.
- RED 확인: 변경 기능의 focused 테스트에서 의도한 실패 확인.
- GREEN: 기존 요청 분기의 예약 위치를 조정한다.
- GREEN 확인: 각 기능 focused 테스트 통과.
- REFACTOR: 실제 DB 재개 주기와 기존 응답 유지 확인.
Phase 1 Gate
Goal P1-GATE: MT-001~007과 직접 영향 기능의 검증/리뷰 증거를 판정한다.
-
시작 조건: P1-T1의 구현과 focused RED/GREEN 완료.
-
TDD 예외 사유: Gate는 기존 구현 검증/리뷰이며 새 동작을 추가하지 않는다.
-
완료 증거: 기능별 테스트, lint/bootJar, DB 동작 QA, 단일 독립 리뷰와 문서 갱신.
-
범위 밖: 전체 테스트, 실 AWS/Papago/IAM 및 운영 MySQL/배포 검증.
-
번역 공통 패키지 및 언어 감지 캐시 기능 회귀.
-
콘텐츠/관리자 수정·시리즈·테마·카테고리·캐릭터/원작·커뮤니티의 직접 영향 기능별 회귀.
-
./gradlew --no-daemon ktlintCheck bootJar통과. -
실제 트랜잭션의 저장/롤백, 실패 소진 후 조회/수정 재개, 캐시 재사용 QA.
-
한 명의 리뷰어가 요구사항/동시성/테스트 증거 검토, 지적 사항 해결.
-
PRD/계획 완료 상태와 미검증 범위 기록.
검증 기록
후속 Goal P1-T2: 감지도 AWS 우선으로 전환
- 시작 조건: 사용자가 기존 감지 캐시 유지와 AWS/Papago 순서를 승인했다.
- 완료 증거: Spring 기본 감지 AWS 선택, 실제 AWS adapter SDK 응답 처리, AWS 실패 시 Papago, 기존 Papago 캐시 무호출 재사용.
- 범위 밖: 감지 알고리즘/confidence/지원 언어/캐시 무효화/번역·재시도 재설계.
- production 파일:
src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/LanguageProviderOrder.kt. - 테스트 파일: 같은 i18n/translation 테스트 패키지의
LanguageProviderSpringConfigurationTest.kt,LanguageProviderIdTest.kt,LanguageDetectionProviderTest.kt,LanguageProviderCacheEndToEndTest.kt. - 문서: 기존 PRD 및
docs/20261109_감지번역공급자공통화/provider-guide.md. - RED: 기본 설정의 AWS 감지와 fallback/cache 회귀 기대를 작성하고 의도한 실패 확인.
- GREEN: detectionOrder만 AWS/Papago로 변경하고 관련 감지·설정·캐시 테스트 통과.
- REFACTOR: 현재 가이드 갱신, ktlintCheck/bootJar, 후속 delta 리뷰와 임시 자원 정리.
- 검증 명령:
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProvider*Test' --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageDetectionProviderTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsLanguageDetectionProviderTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.PapagoLanguageDetectionProviderTest' --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest'.
후속 회귀 Goal P1-R1: 다른 원문 언어의 FAILED 보존
-
시작 조건: gate reviewer가 MT-003의 현재 원문 한정 재개 누락을 확인했다.
-
완료 증거: 같은 해시/다른 원문 언어 작업은 직접 예약과 번역 행 없는 조회 모두에서 재개되지 않는다.
-
범위 밖: 작업 고유 키/스키마 변경, 이전 언어 데이터 변환, materializer 재설계.
-
파일:
src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobScheduler.kt,src/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobRetryIntegrationTest.kt,src/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/OriginalWorkReadRetryTest.kt. -
RED: 두 경로의 다른 원문 언어 FAILED 보존 회귀 테스트 추가.
-
RED 확인: 두 테스트 클래스에서 FAILED 기대/PENDING 실제 실패 확인.
-
GREEN: FAILED 재개 조건에 정규화된 현재 원문 언어 일치 추가.
-
GREEN 확인: 두 테스트 클래스 및 직접 영향 scheduler/read/HTTP 테스트 통과.
-
REFACTOR: lint/build 및 차단 사항 delta 재검토 완료.
-
2026-11-16 기준 상태: Java 17.0.15, 작업 트리 깨끗함, 기존 브랜치 test에서 작업한다.
-
구현 전
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderSpringConfigurationTest': exit 0, 16초. 기존 Gradle 9 호환성 deprecation 안내가 출력됐다. -
전체 테스트는 미실행이며 사용자 실행 명령은
./gradlew test다. -
2026-11-16 RED: worker/scheduler/retry DB/provider Spring/provider ID/coordinator 43건 중 14건이 의도한 assertion으로 실패했다. 기본 600000ms, 조기 FAILED, 기존 FAILED 미재개, Papago 우선이 각 실패 원인이며 컴파일은 성공했다.
-
2026-11-16 공급자 GREEN:
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderSpringConfigurationTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderIdTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationCoordinatorTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderCacheEndToEndTest': exit 0, 37초. 기본 AWS 선택, Papago 감지 유지, fallback와 실제 H2 캐시/조회 결과 보존을 확인했다. -
2026-11-16 연결 RED와 큐 GREEN:
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest' --tests 'kr.co.vividnext.sodalive.v2.api.admin.aicharacter.content.LegacyCreatorAdminAudioContentCharacterizationTest.shouldRequestTranslationAfterCommitWhenMetadataIsUpdatedWithoutTags*' --tests 'kr.co.vividnext.sodalive.i18n.translation.*ReadRetryTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobRetryIntegrationTest': exit 1, 감지 10건·조회 10건·관리자 수정 8건이 의도한 assertion으로 실패했다. 같은 실행의 worker 13건/scheduler 3건/retry DB 9건은 모두 통과했다. H2에서 기존 FAILED 재개, 동시 요청, RUNNING 선점 뒤 오래된 요청 보호, 자동 재개 금지를 확인했다. H2 claim은 운영 쿼리의 SKIP LOCKED 옵션만 제거한 테스트이며 MySQL 잠금 동작 검증이 아니다. -
2026-11-16 연결 GREEN: 감지 10건, 조회 15건, 관리자 수정 8건, HTTP 1건 통과. 이후 번역/감지 회귀 191건과 직접 영향 기능 회귀 67건(HTTP 1건 중복)을 실행해 총 257개 고유 사례에서 실패/오류/skip 0을 확인했다.
-
2026-11-16 최종 lint/build: 첫 main/test 인자 줄바꿈 위반을 변경 부분에서 수정한 뒤 ktlintCheck/bootJar 및 직접 수정 기능 49건을 함께 실행해 exit 0을 확인했다. HTTP test는 이벤트 발행을 끊는 변이로 DB assertion RED도 확인하고 원상 복구했다.
-
정확한 회귀 명령·QA 관찰값·원본 증거 경로·H2/Redis 로그 한계는 검증 기록에 보존한다. 현재 단일 독립 reviewer 판정 대기다.
-
2026-11-16 P1-R1: reviewer가 일반 예약 경로에서 이전 원문 언어의 FAILED도 재개하는 누락을 확인했다. 직접 scheduler와 번역 행 없는 원작 조회 2건의 RED를 확인하고 원문 언어 일치 guard를 추가했다. 직접 영향 74건과 ktlintCheck/bootJar는 exit 0이며 추가 2건을 포함한 고유 검증 사례는 259건이다. delta 재검토 대기.
-
2026-11-16 최종 Gate: 동일 독립 reviewer가 P1-R1 수정과 RED/GREEN/XML 74건 및 lint/build 증거를 대조해 APPROVE했다. 차단 사항 없음. 전체 테스트와 운영 MySQL/외부 공급자 검증은 별도이며 커밋·배포는 하지 않았다.
-
2026-11-16 P1-T2: 감지 AWS 우선 변경 전 기본값/실제 SDK adapter/기존 캐시 관련 7개 assertion RED를 확인했다. detectionOrder 한 줄 변경 후 명시된 감지·공급자·캐시 기능 테스트 49건(8개 클래스, 실패/오류/skip 0) 및 ktlintCheck/bootJar가 exit 0이다. 후속 delta 리뷰 대기.
-
2026-11-16 P1-T2 최종: 독립 reviewer APPROVE. 현재 가이드의 잔여 PAPAGO 우선 테스트 설명도 AWS로 정정했다. 이전 기능 검증 기록과 완료 상태를 보존하며, 후속 감지 변경까지 완료했다.
-
2026-11-16 커밋 전 검증: 사용자 커밋 요청에 따라 번역·감지 및 직접 영향 기능을 함께 재실행했다. 33개 클래스 261건의 실패/오류/skip 0, ktlintCheck/bootJar는 UP-TO-DATE, 전체 명령은 exit 0(2분 3초)이다. 정확한 명령은 검증 기록의 커밋 전 재검증 절에 남긴다. 전체 테스트는 미실행이며 사용자 실행 명령은
./gradlew test다.