docs(i18n): 콘텐츠 태그 미번역 복구 요구사항과 계획을 기록한다

This commit is contained in:
2026-11-17 09:56:00 +09:00
parent ba7bc81ac7
commit cd4667813a
2 changed files with 28 additions and 0 deletions
@@ -134,6 +134,23 @@ REQUIRES_NEW 진입점을 사용한다. FAILED 후보가 없으면 원문을 불
## 검증 기록
### 후속 Goal P1-T3: 콘텐츠 태그 미번역 fallback과 기존 완료 작업 복구
- 시작 조건: MT-008/009 및 Papago 동일 결과 성공 정책 확정.
- 완료 증거: AWS 동일/쉼표 공백 결과와 캐시 배제, Papago 결과 저장, 기존 완료 작업 재개 후 재요청 안정성, 비대상 필드 보호.
- 범위 밖: 일반 문장 번역 품질 판단, # 제거/태그 형식 변경, AWS 실계정 비교, 운영 일괄 재번역, 원문 hash 변경.
- 공통 결과 검증 파일: `i18n/translation/{TranslateRequest,TranslationCoordinator,SourceTextNormalizer,TranslationJobWorker,TranslationReadModelMaterializer}.kt` (루트 `src/main/kotlin/kr/co/vividnext/sodalive/`).
- 캐시 갱신 파일: 같은 패키지의 `TranslationMemory.kt`. 기존 AWS 미번역 캐시가 있는데 새 AWS 결과가 정상인 경우 같은 행의 번역 텍스트만 갱신한다. 정상 캐시와 Papago 확인 결과는 덮어쓰지 않는다.
- 복구 파일: 같은 패키지의 `TranslationJobScheduler.kt`, `TranslationJobRepository.kt`, `ResourceTranslationJobScheduler.kt` 및 직접 생성자 fixture.
- scoped flag: `TranslateRequest.rejectUnchangedAwsResult: Boolean = false`, `TranslationCoordinator.findCached(..., rejectUnchangedAwsResult: Boolean = false)`. worker/materializer에서 CONTENT/tags만 true로 전달한다.
- 비교 함수: `SourceTextNormalizer.hasSameCommaSeparatedText(first: String, second: String): Boolean`; 기존 normalize를 각 쉼표 요소에 적용하고 순서대로 비교한다. 기존 normalize/hash 동작은 그대로다.
- 복구 판단: 현재 job 언어/hash 일치, CONTENT/tags/COMPLETED, 저장된 content_translation tags가 원문과 동일한 경우만 검사한다. scoped cache가 저장된 rendered tags와 정확히 같으면 이미 확인된 정상 결과로 보존하고, 그 외에는 조건부 COMPLETED→PENDING으로 복구한다. 작업 ID를 보존하고 retryCount/error/nextRetryAt를 초기화한다.
- 현재 원문 태그가 비어 있지 않은데 저장된 응답 행 또는 tags가 누락된 완료 작업도 워커 재조립 대상으로 처리한다. 캐시가 있으면 외부 호출 없이 복구하며 정상 번역된 응답은 유지한다.
- read 복구는 기존 ResourceTranslationJobScheduler 재개 경계에서 COMPLETED CONTENT/tags 후보만 추가 조회해 현재 source와 대조한다. 다른 리소스/필드와 PENDING/RUNNING을 초기화하지 않는다.
- [x] **RED:** coordinator의 scoped 동일 결과/캐시, 실제 worker+materializer 경계, 이전 완료 작업과 Papago 동일 결과 보존 회귀를 작성하고 실패 확인.
- [x] **GREEN:** 최소 결과 판정과 조건부 완료 작업 복구 구현, 같은 focused 테스트 통과.
- [x] **REFACTOR:** 직접 영향 번역/감지/read/관리자/커뮤니티 테스트, ktlintCheck/bootJar, DB 시나리오와 단일 gate 리뷰 완료.
### 후속 Goal P1-T2: 감지도 AWS 우선으로 전환
- 시작 조건: 사용자가 기존 감지 캐시 유지와 AWS/Papago 순서를 승인했다.
@@ -174,4 +191,11 @@ REQUIRES_NEW 진입점을 사용한다. FAILED 후보가 없으면 원문을 불
- 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 P1-T3 forward RED: H2 JSON을 로딩하는 fixture cleanup 실패를 bulk cleanup으로 고친 뒤, ContentTagTranslationIntegrationTest 8건 중 6건이 AWS 원문 동일 결과/캐시를 성공으로 인정하는 원인으로 실패했다. 설정 오류를 RED 증거로 간주하지 않았다.
- 2026-11-16 P1-T3 forward GREEN: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationCoordinatorTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest'`: exit 0, 29건. 콘텐츠 태그에만 적용한 판정과 Papago 결과 저장/캐시 조립을 확인했다.
- 2026-11-16 P1-T3 repair RED: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.CompletedContentTagRepairTest'`: 27건 중 11건이 COMPLETED 재개 누락으로 실패했다. 정상 번역/다른 필드/다른 언어/진행 상태/Papago 동일 결과 보호 16건은 통과했다.
- 2026-11-16 P1-T3 repair GREEN: 완료 작업 복구 27건과 forward 9건 통과. 이후 기존 미번역 AWS 캐시 뒤 정상 AWS 결과 갱신 실패를 추가 RED로 확인하고 같은 캐시 행의 translatedText만 갱신했다.
- 2026-11-16 P1-T3 최종 검증: 공통 회귀 232건 통과 후 새 조건문 braces lint 3건을 수정했다. 조회→worker→재조회 연속 DB 사례까지 추가한 최종 직접 영향 회귀 104건과 ktlintCheck/bootJar가 exit 0이다. 고유 사례 277건이며 명령/증거/한계는 [태그 fallback 검증 기록](reviews/tag-fallback-review.md)에 있다. 독립 리뷰 대기.
- 2026-11-16 P1-T3 최종 Gate: 단일 독립 reviewer가 MT-008/009와 전체 태그 처리/캐시/완료 복구/경합 보호 및 실행 증거를 확인해 APPROVE했다. 차단 사항 없음. 이번 태그 후속 변경은 커밋·배포하지 않았다.
- 2026-11-16 커밋 전 검증: 사용자 커밋 요청에 따라 번역·감지 및 직접 영향 기능을 함께 재실행했다. 33개 클래스 261건의 실패/오류/skip 0, ktlintCheck/bootJar는 UP-TO-DATE, 전체 명령은 exit 0(2분 3초)이다. 정확한 명령은 [검증 기록](reviews/verification.md)의 커밋 전 재검증 절에 남긴다. 전체 테스트는 미실행이며 사용자 실행 명령은 `./gradlew test`다.
- 2026-11-17 P1-T3 커밋 전 재검증: 번역 패키지와 직접 영향 감지·커뮤니티·OSIV 기능 32개 클래스 277건을 실행해 실패/오류/skip 0을 확인했다. ktlintCheck/bootJar는 UP-TO-DATE, 명령은 exit 0(1분 17초), `git diff --check`도 통과했다. 정확한 명령은 [태그 검증 기록](reviews/tag-fallback-review.md)의 커밋 전 재검증 절에 남긴다. 전체 테스트와 실제 외부 공급자·운영 MySQL은 미검증이며 전체 테스트는 사용자 실행 `./gradlew test`로 구분한다.
@@ -24,6 +24,8 @@
| MT-005 | 번역을 빠르게 반영한다. | 워커 기본 fixedDelay는 1000ms, 실행당 최대 5개 그룹을 유지한다. 실제 완료 시간은 대기량과 외부 API 처리 시간에 좌우된다. |
| MT-006 | 콘텐츠 수정과 기존 조회 흐름을 연결한다. | 일반 관리자 제목/상세 수정과 크리에이터 관리자 태그 없는 제목/상세 수정도 작업을 요청한다. 기존 번역 응답이 남아 있어도 관련 조회 요청은 현재 원문의 FAILED 작업을 재개할 수 있다. |
| MT-007 | 기존 계약과 경쟁 처리를 유지한다. | ko/en/ja, 공개 API/원문 fallback, provider별 캐시, SKIP LOCKED 작업 claim, 커뮤니티 revision 보호를 유지한다. job 등록/재개와 워커의 상태 경쟁을 DB 조건 또는 잠금으로 보호한다. |
| MT-008 | 콘텐츠 태그의 AWS 미번역 결과는 Papago로 넘긴다. | CONTENT/tags에 한정하여 원문과 NFC/공백 정규화 및 쉼표 요소별 trim 후 같은 AWS 결과를 거부한다. 새 응답과 캐시에 같은 기준을 적용한다. Papago 동일 결과는 사용자 승인에 따라 성공이다. |
| MT-009 | 기존 잘못 완료된 콘텐츠 태그를 요청 시 복구한다. | 현재 원문/언어에 해당하는 COMPLETED 태그 중 저장된 응답이 원문과 동일하고 유효 캐시 결과와 일치하지 않는 작업을 기존 조회/수정 요청에서 재개한다. 정상 번역 및 Papago로 확인된 동일 결과는 반복 재개하지 않는다. 운영 일괄 변경은 하지 않는다. |
## 구현 결정
@@ -47,3 +49,5 @@
- 2026-11-16: 기존 DB 큐와 1초 워커, 동일 트랜잭션 작업 등록안을 제시했다. 사용자가 재시도는 5회로 제한하고 소진 후 조회/수정 요청 때 다시 5회로 재개하도록 확정했다.
- 2026-11-16: 구현 후 기능별 고유 사례 259건, ktlintCheck/bootJar를 검증했다. 독립 리뷰의 원문 언어 일치 누락을 회귀 테스트로 보완한 뒤 APPROVE 판정을 받았다. 상세 명령과 미검증 범위는 [검증 기록](reviews/verification.md)에 있다.
- 2026-11-16 후속 승인: 사용자가 감지도 AWS 우선으로 변경하는 데 동의했다. 초기의 Papago 우선 감지 정책을 정정하고, 기존 감지 캐시는 그대로 재사용한다. P1-T2로 검증한다.
- 2026-11-16 태그 후속: 사용자가 AWS가 쉼표 공백만 바꾸는 태그를 성공 처리하는 문제를 보고하고 Papago fallback을 요청했다. Papago도 같은 값을 반환하면 성공으로 인정하기로 선택했다. 원문 해시/일반 텍스트 정책은 변경하지 않는다.
- 2026-11-16 태그 후속 완료: 신규/기존 AWS 미번역 캐시와 완료 작업 복구를 구현했다. 고유 기능 사례 277건, lint/build 및 단일 독립 리뷰 APPROVE를 확인했다. [태그 검증 기록](reviews/tag-fallback-review.md).