docs(i18n): 태그 번역 정책과 복구 검증 결과를 기록한다

This commit is contained in:
2026-11-17 09:56:34 +09:00
parent 55669c4465
commit f7f6ab6864
3 changed files with 105 additions and 0 deletions
@@ -99,6 +99,10 @@ coordinator/cache/worker의 DB 조회·저장 접점에서만 `providerId.code`
## 캐시와 오류 계약 ## 캐시와 오류 계약
콘텐츠의 `tags` 작업은 원문과 쉼표 요소별 정규화 결과가 같은 AWS 응답을 성공으로 인정하지 않고 Papago로 넘긴다.
같은 AWS 캐시도 이 필드의 worker/materializer에서는 사용하지 않는다. Papago가 원문과 같은 값을 반환하면 성공으로 인정한다.
일반 제목/본문과 다른 리소스의 필드에는 이 추가 판정을 적용하지 않으며, 원문 hash와 저장 캐시는 일괄 변경하지 않는다.
감지는 정규화/hash/normalization version을 기존과 같이 사용하고 adapter에는 원래 query를 전달한다. 감지는 정규화/hash/normalization version을 기존과 같이 사용하고 adapter에는 원래 query를 전달한다.
설정된 모든 공급자의 캐시를 순서대로 조회한 뒤, 유효 캐시가 하나도 없을 때만 외부 호출을 시작한다. 설정된 모든 공급자의 캐시를 순서대로 조회한 뒤, 유효 캐시가 하나도 없을 때만 외부 호출을 시작한다.
저장은 실제 성공 공급자로 `insertIfAbsent`하고 이어지는 locking read의 승자를 반환한다. 저장은 실제 성공 공급자로 `insertIfAbsent`하고 이어지는 locking read의 승자를 반환한다.
@@ -0,0 +1,100 @@
# 콘텐츠 태그 미번역 fallback 검증 및 리뷰
## 범위와 판정 기준
2026-11-16 P1-T3, MT-008/009. 콘텐츠 `tags`에 한정해 AWS가 원문을 그대로 반환하거나 쉼표 요소의 공백만 바꾼 경우 Papago를 사용한다.
사용자는 Papago도 같은 값을 반환하면 성공으로 인정한다고 명시했다. 일반 제목/본문과 다른 리소스 태그에는 적용하지 않는다.
기존 AWS 캐시를 일괄 삭제하지 않으며 현재 콘텐츠 조회/수정 시 해당 완료 작업만 복구한다.
실제 AWS에서 # 문자가 원인인지는 검증하지 않았다. 보고된 응답 형태를 외부 공급자 대역으로 재현하고 실제 coordinator/worker/JPA 동작을 검증했다.
## QA 증거
| 시나리오 | 실행/저장 경계 | 결과 |
|---|---|---|
| AWS 원문 동일·쉼표 공백 결과 | ContentTagTranslationIntegrationTest, 실제 worker/coordinator/materializer/H2 | Papago 호출 및 Papago 결과 저장, job COMPLETED |
| 기존 AWS 미번역 캐시 | 같은 테스트 | AWS 캐시를 무시하고 Papago 결과로 content_translation 조립 |
| AWS 캐시만 있는 조립 | 같은 테스트 | materialize=false, 잘못된 응답 행 생성 없음 |
| Papago 동일 결과 | 같은 테스트 | provider=papago, 동일 태그 저장 및 COMPLETED |
| AWS 정상 결과/일반 제목 | 같은 테스트 | 기존 AWS 성공 정책 유지, Papago 미호출 |
| Papago 장애 | 같은 테스트 | 잘못된 AWS 결과로 완료하지 않고 PENDING/retryCount=1, 캐시·응답 저장 없음 |
| 기존 잘못된 AWS 캐시 뒤 정상 AWS 결과 | 같은 테스트 | 같은 cache ID의 translatedText 갱신 및 정상 응답 조립 |
| 과거 완료 작업 복구 | CompletedContentTagRepairTest, H2 | 같은 작업 ID를 조건부 COMPLETED→PENDING, count0/error null/due now |
| 정상/비대상/경합 보호 | 같은 테스트 | Papago 확인 동일 태그, 정상 AWS 번역, 다른 원문/언어/리소스/필드, PENDING/RUNNING 보호 |
| 조회→worker→재조회 연속 흐름 | ContentTagTranslationIntegrationTest.shouldRepairCompletedTagsOnceAcrossReadWorkerAndRead | 동일 ID 복구 후 Papago 동일 결과를 저장하고 다음 조회에서는 COMPLETED 유지 |
연속 흐름의 실제 테스트 출력:
```text
Tag repair QA: same job=3, AWS unchanged rejected, Papago identical accepted, next read remains COMPLETED
```
최종 XML: `build/test-results/test/TEST-kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest.xml`.
태그 원문 추출은 이 통합 테스트의 고정 fixture이며 worker/coordinator/repository/materializer는 실제 구현이다.
공급자 응답만 통제하고 H2 JSON의 문자열 감싸기 차이는 테스트에서 JSON 객체로 맞춘다. 운영 저장 변환은 변경하지 않았다.
## RED/GREEN
- 최초 테스트 cleanup이 H2 JSON 변환으로 실패한 것은 setup 문제로 분류하고 bulk cleanup으로 수정했다.
- forward 8건 중 6건 RED: AWS 동일 결과/캐시가 성공으로 처리되는 assertion 실패. 구현 후 forward/coordinator/worker 29건 GREEN.
- completed repair 27건 중 11건 RED: 현재 COMPLETED 중복 가드로 재개되지 않음. 구현 후 27건 GREEN.
- cache refresh 추가 RED 1건: 정상 AWS 결과가 와도 기존 미번역 캐시가 갱신되지 않음. 같은 행의 translatedText 갱신으로 GREEN.
- 일반 회귀 실행은 번역 패키지+감지 원자성+감지 캐시 232건 모두 통과했으나 lint에서 새 multiline 조건 braces 누락이 발견됐다. 변경 줄만 수정했다.
## 실행 명령
공통 회귀:
```bash
./gradlew --no-daemon ktlintCheck bootJar test \
--tests 'kr.co.vividnext.sodalive.i18n.translation.*' \
--tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest' \
--tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' --continue
```
테스트 232건은 실패/오류/skip 0, 이 실행의 비정상 종료 원인은 위 lint 3건이었다.
보완 후 직접 영향 회귀 및 최종 lint/build:
```bash
./gradlew --no-daemon ktlintCheck bootJar test \
--tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' \
--tests 'kr.co.vividnext.sodalive.i18n.translation.CompletedContentTagRepairTest' \
--tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationCoordinatorTest' \
--tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' \
--tests 'kr.co.vividnext.sodalive.i18n.translation.MetadataTranslationHttpIntegrationTest' \
--tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' \
--tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectionCacheConcurrencyTest' \
--tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' \
--tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityTranslationEndToEndTest' \
--tests 'kr.co.vividnext.sodalive.osiv.OsivLazyLoadingRegressionTest'
```
exit 0, 10개 클래스 104건 실패/오류/skip 0. 두 실행의 중복을 제외한 고유 기능 검증은 277건이다.
최종 `git diff --check`도 통과했다. Kotlin 컴파일·ktlint를 사용했으며 LSP 도구는 제공되지 않았다.
## 미검증과 최종 상태
- 실제 AWS/Papago 호출·번역 품질/과금/IAM 및 운영 MySQL 잠금은 미검증이다. 원문 동일 판정은 번역 품질 전반이나 일부 태그만 미번역인 상황을 판정하지 않는다.
- 전체 테스트는 사용자 실행 `./gradlew test`로 구분한다. 운영 DB 일괄 변경과 커밋/배포는 하지 않았다.
- 단일 독립 gate review APPROVE. MT-008/009, 태그 전용 결과/캐시 판정, 같은 캐시 행 갱신, 완료 작업 조건부 복구, Papago 동일 결과의 반복 재개 방지, 상태 경쟁 보호와 104건 최종 XML/lint/build 증거를 확인했다. 차단 사항 없음.
- 정리 완료: reviewer가 원본 실행 로그를 확인한 뒤 소유 임시 루트 `tag-fallback.UmKdRY`와 하위 로그/메모를 삭제하고 경로 부재를 확인했다. 소유 Gradle test worker/Redis 프로세스 없음, 공유 캐시 보존. 검증 이력은 이 문서와 계획에 유지한다.
## 2026-11-17 커밋 전 재검증
사용자 커밋 요청에 따라 태그 처리와 직접 영향 기능을 재검증했다.
```bash
./gradlew --no-daemon ktlintCheck bootJar test \
--tests 'kr.co.vividnext.sodalive.i18n.translation.*' \
--tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest' \
--tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' \
--tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectTest' \
--tests 'kr.co.vividnext.sodalive.content.CreatorCommunityLanguageDetectionCacheConcurrencyTest' \
--tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' \
--tests 'kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.CreatorCommunityTranslationEndToEndTest' \
--tests 'kr.co.vividnext.sodalive.osiv.OsivLazyLoadingRegressionTest'
```
- exit 0, 1분 17초. XML 32개 클래스 277건, 실패/오류/skip 0.
- 테스트는 실행됐고 ktlintCheck/bootJar는 UP-TO-DATE다. `git diff --check`도 통과했다.
- 전체 테스트는 미실행이며 사용자 실행 명령은 `./gradlew test`다. 실제 AWS/Papago 및 운영 MySQL 검증은 포함하지 않는다.
+1
View File
@@ -23,6 +23,7 @@
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsTranslationServiceTest' ./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsTranslationServiceTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsLanguageProviderConfigurationTest' ./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsLanguageProviderConfigurationTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobRetryIntegrationTest' ./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobRetryIntegrationTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.CompletedContentTagRepairTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest' ./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.*ReadRetryTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.MetadataTranslationHttpIntegrationTest' ./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.*ReadRetryTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.MetadataTranslationHttpIntegrationTest'
./gradlew bootJar ./gradlew bootJar