From 309f794168cb6da62e2c72c287750da4ca913acc Mon Sep 17 00:00:00 2001 From: Klaus Date: Mon, 16 Nov 2026 21:46:00 +0900 Subject: [PATCH] =?UTF-8?q?docs(i18n):=20=EB=A9=94=ED=83=80=EB=8D=B0?= =?UTF-8?q?=EC=9D=B4=ED=84=B0=20=EB=B2=88=EC=97=AD=20=EC=8B=A0=EC=86=8D=20?= =?UTF-8?q?=EB=B0=98=EC=98=81=20=EC=9A=94=EA=B5=AC=EC=82=AC=ED=95=AD?= =?UTF-8?q?=EA=B3=BC=20=EA=B3=84=ED=9A=8D=EC=9D=84=20=EA=B8=B0=EB=A1=9D?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../plan-task.md | 177 ++++++++++++++++++ docs/20261116_메타데이터번역신속반영/prd.md | 49 +++++ 2 files changed, 226 insertions(+) create mode 100644 docs/20261116_메타데이터번역신속반영/plan-task.md create mode 100644 docs/20261116_메타데이터번역신속반영/prd.md diff --git a/docs/20261116_메타데이터번역신속반영/plan-task.md b/docs/20261116_메타데이터번역신속반영/plan-task.md new file mode 100644 index 00000000..9342fb41 --- /dev/null +++ b/docs/20261116_메타데이터번역신속반영/plan-task.md @@ -0,0 +1,177 @@ +# 메타데이터 자동 번역 신속 반영 구현 계획 + +| 항목 | 내용 | +|---|---| +| 상태 | 구현·기능 검증·독립 리뷰 완료 | +| 작성일 | 2026-11-16 | +| 요구사항 | [prd.md](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: 번역 수명주기와 요청 연결 + +- [x] **Task 1.1: 순서·재시도·신속 처리 구현** + +**Goal P1-T1:** 감지 성공부터 실패 소진 후 재요청까지 번역 상태가 요구사항대로 이어진다. + +- 시작 조건: MT-001~007 확정, PRD와 이 계획 준비. +- 완료 증거: 아래 RED/GREEN, 트랜잭션 저장/롤백과 재개 검증, 기능별 회귀 통과. +- 범위 밖: 감지 자체 새 재시도, 외부 API/브로커 추가, 운영 데이터 일괄 변경, 응답 스키마 변경. + +### 작업 A: 공통 큐와 워커 + +파일: +- `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobScheduler.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobRepository.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobWorker.kt` +- `src/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationJobSchedulerTest.kt` +- `src/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하지 않는다. + +- [x] **RED:** 기존 행의 상태별 재개, 동시 재개, 5회 재시도 경계와 1초 설정의 실패 테스트 작성. +- [x] **RED 확인:** `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest'`에서 의도한 assertion 실패 확인. +- [x] **GREEN:** 기존 상태 전이와 DB 경합 경계에서 최소 구현. +- [x] **GREEN 확인:** 동일 focused 테스트와 추가 DB 통합 테스트 통과. +- [x] **REFACTOR:** 새 중복만 정리하고 캐시/부분 실패 회귀를 기능별 실행. + +### 작업 B: 언어 감지와 콘텐츠 수정 + +파일: +- `src/main/kotlin/kr/co/vividnext/sodalive/content/LanguageDetectEvent.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentService.kt` +- `src/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 경로는 보존한다. +관리자 제목/설명 변경과 크리에이터 관리자 태그 없는 제목/설명 변경도 커밋 후 번역 이벤트를 발행한다. + +- [x] **RED:** 실제 DB로 감지 후 작업 존재/롤백, 태그 없는 관리자 텍스트 수정의 작업 요청 누락을 재현. +- [x] **RED 확인:** 해당 신규 감지 테스트와 관련 관리자 기능 테스트에서 의도한 실패 확인. +- [x] **GREEN:** 기존 서비스/리스너에 최소 연결 수정. +- [x] **GREEN 확인:** 감지·관리자 수정 focused 테스트 통과. +- [x] **REFACTOR:** 커뮤니티 감지/동시성 기능 회귀를 별도 실행하고 기존 보호 확인. + +### 작업 C: 공급자 기본 순서 + +파일: +- `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/LanguageProviderOrder.kt` +- `src/test/kotlin/kr/co/vividnext/sodalive/i18n/translation/LanguageProviderSpringConfigurationTest.kt` +- 필요한 production 기본값 소유 테스트. +- `docs/20261109_감지번역공급자공통화/provider-guide.md` + +계약: 번역 AWS/Papago, 감지 Papago/AWS. 기존 캐시와 fallback 유지. + +- [x] **RED:** 기본 Spring 설정에서 실제 coordinator가 AWS 번역을 선택하고 감지는 Papago를 선택하는 실패 테스트. +- [x] **RED 확인:** `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderSpringConfigurationTest'`의 선택 결과 실패 확인. +- [x] **GREEN:** production 순서와 현재 가이드 변경. +- [x] **GREEN 확인:** 같은 테스트 및 provider/coordinator 관련 기능 회귀 통과. +- [x] **REFACTOR:** 과거 이력은 보존하고 현재 실행 안내만 정합성 확인. + +### 작업 D: 조회 시 실패 재개 + +파일: +- `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/content/series/ContentSeriesService.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/content/theme/AudioContentThemeService.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/content/category/CategoryService.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/chat/character/controller/ChatCharacterController.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/chat/original/service/OriginalWorkTranslationService.kt` +- `src/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, targetLanguage)` +REQUIRES_NEW 진입점을 사용한다. FAILED 후보가 없으면 원문을 불필요하게 추출하지 않으며, 현재 원문에 해당하는 작업만 재개한다. +커뮤니티 쓰기 잠금 안에서는 이 REQUIRES_NEW 읽기 진입점을 호출하지 않고 기존 REQUIRED 예약으로 처리한다. +계획 검토에서 제안된 모든 projection/list의 광범위한 변경은 채택하지 않고 PRD의 기존 번역 요청 경계로 한정한다. + +- [x] **RED:** 이전 번역이 존재하는 상태에서도 조회가 현재 원문의 FAILED를 재개하는 실패 테스트. +- [x] **RED 확인:** 변경 기능의 focused 테스트에서 의도한 실패 확인. +- [x] **GREEN:** 기존 요청 분기의 예약 위치를 조정한다. +- [x] **GREEN 확인:** 각 기능 focused 테스트 통과. +- [x] **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/배포 검증. + +- [x] 번역 공통 패키지 및 언어 감지 캐시 기능 회귀. +- [x] 콘텐츠/관리자 수정·시리즈·테마·카테고리·캐릭터/원작·커뮤니티의 직접 영향 기능별 회귀. +- [x] `./gradlew --no-daemon ktlintCheck bootJar` 통과. +- [x] 실제 트랜잭션의 저장/롤백, 실패 소진 후 조회/수정 재개, 캐시 재사용 QA. +- [x] 한 명의 리뷰어가 요구사항/동시성/테스트 증거 검토, 지적 사항 해결. +- [x] 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`. +- [x] **RED:** 기본 설정의 AWS 감지와 fallback/cache 회귀 기대를 작성하고 의도한 실패 확인. +- [x] **GREEN:** detectionOrder만 AWS/Papago로 변경하고 관련 감지·설정·캐시 테스트 통과. +- [x] **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`. +- [x] **RED:** 두 경로의 다른 원문 언어 FAILED 보존 회귀 테스트 추가. +- [x] **RED 확인:** 두 테스트 클래스에서 FAILED 기대/PENDING 실제 실패 확인. +- [x] **GREEN:** FAILED 재개 조건에 정규화된 현재 원문 언어 일치 추가. +- [x] **GREEN 확인:** 두 테스트 클래스 및 직접 영향 scheduler/read/HTTP 테스트 통과. +- [x] **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 로그 한계는 [검증 기록](reviews/verification.md)에 보존한다. 현재 단일 독립 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초)이다. 정확한 명령은 [검증 기록](reviews/verification.md)의 커밋 전 재검증 절에 남긴다. 전체 테스트는 미실행이며 사용자 실행 명령은 `./gradlew test`다. diff --git a/docs/20261116_메타데이터번역신속반영/prd.md b/docs/20261116_메타데이터번역신속반영/prd.md new file mode 100644 index 00000000..2b80ac87 --- /dev/null +++ b/docs/20261116_메타데이터번역신속반영/prd.md @@ -0,0 +1,49 @@ +# 메타데이터 자동 번역 신속 반영 PRD + +| 항목 | 내용 | +|---|---| +| 작성일 | 2026-11-16 | +| 상태 | 구현·기능 검증·독립 리뷰 완료 | +| 구현 계획 | [plan-task.md](plan-task.md) | +| 결정권자 | 사용자 | + +## 목적과 현재 문제 + +콘텐츠, 시리즈, 테마 등 기존 메타데이터 번역의 작업 등록 누락과 10분 대기를 줄인다. +언어 감지 결과 저장 전 별도 비동기 번역 이벤트가 실행될 수 있고, 관리자 콘텐츠 수정에는 이벤트 미발행 경로가 있다. +기존 FAILED 작업은 같은 원문으로 요청해도 재개되지 않으며, 워커는 기본 10분 간격이다. + +## 확정 요구사항 + +| ID | 요구사항 | 수용 기준 | +|---|---|---| +| MT-001 | 언어 감지 성공 후 번역 작업을 등록한다. | 기존 일반 메타데이터 감지 경로는 감지된 languageCode와 translation_job을 같은 트랜잭션에 저장한다. 작업 등록 실패 시 언어 저장도 롤백한다. 커뮤니티의 기존 revision/hash 검증은 보존한다. | +| MT-002 | 최초 번역 후 최대 5회 재시도한다. | 한 주기는 최초 시도 1회와 재시도 5회, 총 6회다. 6번째 실패 후 FAILED로 멈춘다. 자동 재시도 지연은 1분, 5분, 이후 15분이다. | +| MT-003 | 소진 후 조회/수정 요청으로 다시 최대 5회 재시도한다. | 현재 원문에 해당하는 기존 FAILED 행을 PENDING, retryCount=0, lastErrorMessage=null, nextRetryAt=요청 시각으로 재개한다. PENDING/RUNNING/COMPLETED는 요청으로 초기화하지 않는다. 중복 요청이 실행 중 재시도 예산을 늘리지 않는다. | +| MT-004 | AWS 감지와 번역을 먼저 사용한다. | 새 외부 감지·번역은 모두 AWS 다음 Papago다. 기존 Papago 포함 유효 캐시를 우선 재사용한다. | +| MT-005 | 번역을 빠르게 반영한다. | 워커 기본 fixedDelay는 1000ms, 실행당 최대 5개 그룹을 유지한다. 실제 완료 시간은 대기량과 외부 API 처리 시간에 좌우된다. | +| MT-006 | 콘텐츠 수정과 기존 조회 흐름을 연결한다. | 일반 관리자 제목/상세 수정과 크리에이터 관리자 태그 없는 제목/상세 수정도 작업을 요청한다. 기존 번역 응답이 남아 있어도 관련 조회 요청은 현재 원문의 FAILED 작업을 재개할 수 있다. | +| MT-007 | 기존 계약과 경쟁 처리를 유지한다. | ko/en/ja, 공개 API/원문 fallback, provider별 캐시, SKIP LOCKED 작업 claim, 커뮤니티 revision 보호를 유지한다. job 등록/재개와 워커의 상태 경쟁을 DB 조건 또는 잠금으로 보호한다. | + +## 구현 결정 + +- 새 메시지 브로커, 외부 API, 의존성, DB 스키마를 추가하지 않고 기존 scheduler/worker를 사용한다. +- 최초 시도와 별도로 재시도 5회를 부여하는 것으로 사용자 문구를 해석한다. 이 해석은 실행 시작 시 사용자에게 명시했다. +- 감지 실패 시 번역은 실행하지 않는다. 감지 자체의 새 재시도 시스템과 운영 데이터 일괄 복구는 이번 범위가 아니다. +- 기존 번역을 즉시 삭제하지 않고 작업 완료 시 교체한다. 원문 변경 후 조회 fallback 계약은 유지한다. +- 조회/수정은 기존 번역 기능 진입점에서 처리한다. 관계없는 모든 목록 API에 새 번역 작업 생성을 강제하지 않는다. +- 주기적 워커는 FAILED를 자동으로 되살리지 않는다. 현재 원문에 대한 명시적인 조회/수정 요청만 새 주기를 연다. + +## 검증 + +- 재시도 경계, 소진 후 요청 재개, 진행 중 작업 예산 보존, 동시 요청, 1초 설정과 AWS 우선/fallback/cache를 검증한다. +- 실제 DB 트랜잭션으로 언어 감지 이후 job 저장과 실패 시 롤백을 검증한다. +- 관련 콘텐츠/시리즈/테마 및 직접 영향받는 번역 조회 기능을 기능별로 검증한다. +- 실제 유료 AWS/Papago 호출, 운영 DB/배포, 전체 테스트는 실행하지 않는다. 전체 테스트는 사용자 명령 `./gradlew test`로 구분한다. + +## 결정 기록 + +- 2026-11-16: 사용자가 언어 감지 후 번역, FAILED 재시도, AWS 번역 우선, 빠른 반영을 요청했다. +- 2026-11-16: 기존 DB 큐와 1초 워커, 동일 트랜잭션 작업 등록안을 제시했다. 사용자가 재시도는 5회로 제한하고 소진 후 조회/수정 요청 때 다시 5회로 재개하도록 확정했다. +- 2026-11-16: 구현 후 기능별 고유 사례 259건, ktlintCheck/bootJar를 검증했다. 독립 리뷰의 원문 언어 일치 누락을 회귀 테스트로 보완한 뒤 APPROVE 판정을 받았다. 상세 명령과 미검증 범위는 [검증 기록](reviews/verification.md)에 있다. +- 2026-11-16 후속 승인: 사용자가 감지도 AWS 우선으로 변경하는 데 동의했다. 초기의 Papago 우선 감지 정책을 정정하고, 기존 감지 캐시는 그대로 재사용한다. P1-T2로 검증한다.