From f7f6ab6864d7dcfb2c38b858d8747cfc7e25fa89 Mon Sep 17 00:00:00 2001 From: Klaus Date: Tue, 17 Nov 2026 09:56:34 +0900 Subject: [PATCH] =?UTF-8?q?docs(i18n):=20=ED=83=9C=EA=B7=B8=20=EB=B2=88?= =?UTF-8?q?=EC=97=AD=20=EC=A0=95=EC=B1=85=EA=B3=BC=20=EB=B3=B5=EA=B5=AC=20?= =?UTF-8?q?=EA=B2=80=EC=A6=9D=20=EA=B2=B0=EA=B3=BC=EB=A5=BC=20=EA=B8=B0?= =?UTF-8?q?=EB=A1=9D=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../provider-guide.md | 4 + .../reviews/tag-fallback-review.md | 100 ++++++++++++++++++ docs/agent-guides/실행명령어.md | 1 + 3 files changed, 105 insertions(+) create mode 100644 docs/20261116_메타데이터번역신속반영/reviews/tag-fallback-review.md diff --git a/docs/20261109_감지번역공급자공통화/provider-guide.md b/docs/20261109_감지번역공급자공통화/provider-guide.md index 1e768cd3..101c2f7c 100644 --- a/docs/20261109_감지번역공급자공통화/provider-guide.md +++ b/docs/20261109_감지번역공급자공통화/provider-guide.md @@ -99,6 +99,10 @@ coordinator/cache/worker의 DB 조회·저장 접점에서만 `providerId.code` ## 캐시와 오류 계약 +콘텐츠의 `tags` 작업은 원문과 쉼표 요소별 정규화 결과가 같은 AWS 응답을 성공으로 인정하지 않고 Papago로 넘긴다. +같은 AWS 캐시도 이 필드의 worker/materializer에서는 사용하지 않는다. Papago가 원문과 같은 값을 반환하면 성공으로 인정한다. +일반 제목/본문과 다른 리소스의 필드에는 이 추가 판정을 적용하지 않으며, 원문 hash와 저장 캐시는 일괄 변경하지 않는다. + 감지는 정규화/hash/normalization version을 기존과 같이 사용하고 adapter에는 원래 query를 전달한다. 설정된 모든 공급자의 캐시를 순서대로 조회한 뒤, 유효 캐시가 하나도 없을 때만 외부 호출을 시작한다. 저장은 실제 성공 공급자로 `insertIfAbsent`하고 이어지는 locking read의 승자를 반환한다. diff --git a/docs/20261116_메타데이터번역신속반영/reviews/tag-fallback-review.md b/docs/20261116_메타데이터번역신속반영/reviews/tag-fallback-review.md new file mode 100644 index 00000000..709c112d --- /dev/null +++ b/docs/20261116_메타데이터번역신속반영/reviews/tag-fallback-review.md @@ -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 검증은 포함하지 않는다. diff --git a/docs/agent-guides/실행명령어.md b/docs/agent-guides/실행명령어.md index 29282bbb..8d6326e1 100644 --- a/docs/agent-guides/실행명령어.md +++ b/docs/agent-guides/실행명령어.md @@ -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.AwsLanguageProviderConfigurationTest' ./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.i18n.translation.*ReadRetryTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.MetadataTranslationHttpIntegrationTest' ./gradlew bootJar