docs(i18n): 태그 번역 정책과 복구 검증 결과를 기록한다
This commit is contained in:
@@ -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 검증은 포함하지 않는다.
|
||||||
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user