docs(i18n): 관리자 번역 선택 계약과 배포 및 검증 기록을 정리한다

This commit is contained in:
2026-11-18 13:21:10 +09:00
parent 9d8bc9149b
commit a48797980a
7 changed files with 1990 additions and 0 deletions
@@ -0,0 +1,35 @@
# 관리자 번역 후보 설계 검토
> 이 문서는 2026-11-17 설계 검토 이력이다. DR-03의 OFF 호환 모드와 flag 전환 정책은 2026-11-18 PRD DEC-11/P7로 대체됐다. 현재는 기동 시 자동 등록하며, 새 writer 작업 생성 전에 세 테이블·언어 포함 unique index 준비, 구 writer/in-flight 종료, 구 index 제거가 필요하다. 아래 과거 판정은 보존한다.
## 범위와 판정
- 일자: 2026-11-17.
- 대상: [PRD](../prd.md), [API 계약](../api-contract.md), [구현 계획](../plan-task.md).
- 독립 검토: Oracle 한 차례, 문서와 관련 기존 코드 읽기만 수행.
- 판정: 아래 지적 보정 후 설계 산출물 수용 가능. 제품 구현 완료 또는 사용자 구현 승인을 의미하지 않는다.
## 지적 및 반영
| ID | 중요도 | 확인한 문제 | 보정 내용 |
|---|---|---|---|
| DR-01 | 높음 | 비활성 포함·한 번 적용 후 종료를 인터뷰 확정으로 잘못 기록 | 후속 인터뷰에서 활성 콘텐츠만 포함, 한 번 적용 후 종료를 직접 확인했다. PRD DEC-09/10으로 정정했다. 자유 번역문 입력 제외는 요청 범위 제안으로 구분했다. |
| DR-02 | 높음 | API apply 설명이 source 검증 후 잠금을 획득 | request → Series → CONTENT 잠금 후 최신 source·membership·override·payload를 재조회·검증하도록 통일했다. |
| DR-03 | 높음 | source-language-aware lookup과 구 unique index가 혼재하면 insert 충돌 | 새 코드의 disabled 호환 모드는 exact-language 조회 후 legacy-key exists 확인으로 기존 mismatch skip을 보존한다. 구 writer 제거와 구 index 삭제 후에만 enabled=true로 활성화한다. 호환 모드도 단일 row legacy 조회를 하지 않는다. |
| DR-04 | 중간 | 취소의 실제 전송/dispatch 승인 기준 및 network 대기 설명 충돌 | DB 취소 commit 이후 새 승인·게시 금지로 통일했다. 이미 승인된 호출은 in-flight이고, 취소 응답은 network 종료를 기다리지 않는다. |
| DR-05 | 중간 | grouping/segment/candidate 배열 대응 및 preview 계약 부족 | GroupingResponse/TitleTemplate/TitleSegment, code-point index, shared/residual valueIndex, input/output cardinality, receipt 타입을 정의했다. |
| DR-06 | 중간 | PREPARING의 durable 실행·재시작·취소가 불명확 | 요청과 활성 member IDs를 먼저 저장하고 동일 poller가 preparation lease/fence를 claim한다. 복구 1회, snapshot 게시 전 취소·source 검증, 반복 만료의 명시 실패를 정의했다. |
| DR-07 | 중간 | replay 우선순위 및 frozen provider version 검사가 누락 | 저장된 generation revision/apply operation replay를 최신 revision 거부보다 먼저 확인하고 provider ID/version 변경은 명시 실패로 처리한다. |
## 추가 정합성 보정
- CONTENT materializer는 유효한 관리자 override가 있으면 해당 필드의 shared memory가 없어도 승인 값을 사용할 수 있도록 순서를 명시했다.
- API의 잘못된 계획 anchor, source snapshot/현재 값 구분, 삭제·비활성화 후 자격 검증을 보완했다.
- 위 수정은 문서만 변경했다. 신규 endpoint, DDL, source, test는 구현하지 않았다.
## 검증 범위
- 부모 에이전트가 세 문서를 읽고 요구사항·API·계획을 대조했다.
- 공백 검사와 최종 변경 파일 확인 결과는 구현 계획의 문서 검증 기록에 남긴다.
- 실행하지 않음: 애플리케이션/테스트/빌드, 운영 DB·MySQL 잠금 검증, 실제 AWS·파파고 호출, 프론트엔드 QA.
- 남은 항목: 사용자 기술 설계 검토와 별도 구현 승인. 실제 제목 분석 정확도·처리량·provider timeout은 계획의 focused 검증에서 확인한다.
@@ -0,0 +1,74 @@
# 관리자 번역 선택 구현 검토 및 QA
## 범위와 현재 판정
- 목표: 관리자 단건/활성 시리즈 콘텐츠의 provider별 새 후보 비교·선택, 제목 공통 구간 검토, 취소, 부분 원자 적용 및 필드별 승인 보호.
- 범위: 서버 코드·API 계약·DDL 배포 준비. 실제 프론트엔드·운영 DB 반영·배포·커밋은 제외한다.
- P1~P4 작업별 검토와 P5를 포함한 단일 전체 gate, 차단 한 건 보정 후 새 delta 검토를 완료했다.
- P1~P5 최종 판정: **APPROVE / HIGH**. 후속 DEC-11/P7은 사용자 지시에 따라 부모가 직접 코드·검증 기록·문서를 검토하고 최신 bootJar를 빌드해 완료했다. P7의 외부 승인으로 표현하지 않는다. 운영 MySQL/cloud 검증은 수행하지 않았다.
> 아래 2026-11-17 검증·판정은 당시 이력이다. 기본 OFF 및 flag 전환 정책은 PRD DEC-11/P7로 대체됐으며 기존 PASS 기록은 재작성하지 않는다.
- 후속 P7-T1 로컬 증거: 등록·언어 identity RED 4개 실패 후 직접 영향 18개 class 162개 테스트 및 ktlintCheck 통과. 부모가 직접 검토하고 `./gradlew --offline --no-daemon bootJar`의 BUILD SUCCESSFUL 및 JAR 생성을 확인했다. 상세 명령·이력·한계는 `plan-task.md` P7-GATE 기록에 있다.
## 최종 트리에서 부모 에이전트가 실행한 검증
```bash
./gradlew --no-daemon test \
--tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionHttpIntegrationTest' \
--tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionApplyHttpIntegrationTest' \
--tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionReceiptHttpIntegrationTest' \
bootJar
```
- 결과: BUILD SUCCESSFUL in 50s, 종료 코드 0. 실제 로컬 HTTP 서버와 H2/fake providers를 사용한 14+10+3 = 27개 테스트, 실패/오류/skip 0.
- 마지막 writer overload 수정 이후 최종 HTTP 흐름을 부모가 직접 실행했다. 브라우저 수동 QA나 실제 AWS/Papago 번역 품질 검증으로 표현하지 않는다.
- 산출물: `build/libs/sodalive-0.0.1-SNAPSHOT.jar` 생성 확인.
- 증거 root: `build/test-results/test/`. 아래 A/B/C는 그 디렉터리의 XML 파일이다.
- A: `TEST-kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionHttpIntegrationTest.xml`
- B: `TEST-kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionApplyHttpIntegrationTest.xml`
- C: `TEST-kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionReceiptHttpIntegrationTest.xml`
## 실제 HTTP QA 행렬
| 시나리오 | 실행/기대 | 관찰 결과 | 판정·증거 |
|---|---|---|---|
| 단건 전체 흐름 | 생성→준비→후보 생성→일부 선택→receipt/출처 재조회 | 선택 필드만 적용되고 출처·receipt가 조회됨 | PASS, A의 실제 HTTP 전체 흐름 case |
| 시리즈 여러 그룹·개별 제목 | 그룹 수정·검토→생성→공통 후보+member별 residual 선택 | 그룹별 동일 공통 표기, 선택 언어와 개별 제목만 반영, 미선택 폐기 | PASS, B의 multiple groups case |
| 잘못된 그룹 선택 | member residual 누락 후 apply | INCOMPLETE_TITLE_GROUP, override 0건, 정상 선택 재전송은 성공 | PASS, B multiple groups case |
| 원문 변경·후보 오류 | 후보 생성 후 raw 공백 변경, 없는 candidate, 잘못된 언어/ID | SOURCE_CHANGED/CANDIDATE_NOT_SELECTABLE/INVALID_REQUEST, 승인 쓰기 0건 | PASS, B의 오류 9개 parameter cases |
| 사전 검토·편집 제약 | series 검토 전 generate, all-individual review, 생성 후 편집 | REVIEW_REQUIRED/호출0, 검토 revision 증가, 생성 후 편집 거부 | PASS, A의 review cases |
| 권한 | CONTENT_MANAGER/CREATOR/USER로 관리 action | ADMIN 외 역할 거부 | PASS, A의 role 3개 cases |
| 취소 | revision 없이 취소 후 재전송 및 취소된 request apply | 같은 terminal 취소 결과, REQUEST_CLOSED, 적용 없음 | PASS, A cancel 및 B closed case |
| Unicode/원문 재구성 | code-point/grapheme 범위와 template 조회 | raw 원문·residual 구문 보존, 잘못된 범위 거부 | PASS, A template/group cases |
| 시각/재전송 불변성 | 나노초 0/123456789/999999999, DB flush/clear, 원문 변경 뒤 receipt 조회 | DB·HTTP 시각은 초 정밀도로 일치, receipt/replay 불변 | PASS, C 3개 cases |
| P5 부분 적용 후 일반 자동 갱신 회귀 | 실제 title/detail apply→일반 title 수정→일반 worker; tags memory 없음·캐시 존재 및 provider 부분 실패 | 성공 title 게시·job 완료, detail 승인·미선택 tags 바이트 보존, 새 payload는 완성 전 job 미완료 | 로컬 회귀 PASS, `TranslationSelectionRefreshIntegrationTest` 3개 RED→4개 GREEN; 직접 회귀 118개 및 최종 lint 통과. 부모 delta 검토·관리 HTTP/bootJar 새 검증 대기. `plan-task.md` P5-R1 참조 |
| 실행 산출물 | bootJar | JVM 실행용 jar 생성 | PASS, `build/libs/sodalive-0.0.1-SNAPSHOT.jar` |
## 기존 집중 회귀 증거
- 필드 승인 보호·원문 변경·동시 materializer·queue refresh: plan-task.md P2 기록과 해당 통합 테스트.
- PREPARING 복구·취소·활성 scope·기본 비활성: P3 68개 focused 증거 및 독립 PASS.
- Provider별 fresh 후보·linked dedup·lease/fence·실제 SDK HTTP retry 취소: P4 기록 및 독립 PASS.
- P5 추가 source/group/cancel/apply concurrency와 transaction rollback: P5 56개 신규 cases를 포함한 관련 170개 검증 이력. 최초 20개 실패의 원인과 직접 영향 42개 재검증을 구분해 기록했다.
- 전체 테스트를 실행하지 않았다. 사용자 전체 테스트 명령은 `./gradlew test`다.
## 운영 한계
- H2 테스트는 운영 MySQL REPEATABLE READ·DDL·잠금·timestamp 검증의 대체물이 아니다.
- DEC-11에 따라 API와 후보 worker는 설정 없이 기동 시 등록된다. 신규 writer 작업 생성 전 세 테이블·언어 포함 queue unique index를 준비하고 구 writer/in-flight 작업 종료 및 구 queue unique index 제거를 완료해야 한다. 자동 DDL이나 기능 활성화 단계는 없다.
- 이미 전송 승인을 받은 provider 호출은 취소 이후에도 비용이 발생할 수 있다. 요청별 timeout은 절대적인 실시간 중단 보장이 아니다.
- 운영 DDL 실행·배포 및 커밋은 수행하지 않았다.
## 최종 gate 보정 후 HTTP 재검증
- 최초 전체 gate는 TR-19의 부분 승인 후 자동 갱신 결함 한 건으로 REJECT했다. 기존 payload의 명시된 필드만 재료화하는 경계를 추가하고 신규 전체 payload의 엄격한 완료 조건은 유지했다.
- 수정자는 실제 apply → 일반 원문 수정 → 일반 worker의 RED 3개를 확인했다. 신규 회귀 4개와 직접 영향 118개가 통과했고 lint도 통과했다. 자세한 범위는 `plan-task.md` P5-R1에 기록했다.
- 부모가 보정 후 위와 동일한 실제 HTTP 세 클래스 및 `bootJar` 명령을 직접 실행했다. 결과: BUILD SUCCESSFUL in 2m 7s, 종료 코드 0. 테스트와 jar는 보정된 최종 코드 기준이다.
- 최종 판정은 보정 delta와 현재 증거의 새 제한 검토 결과를 아래에 추가한다. 기존 전체 검토에서 통과한 다른 범위를 다시 확대 검토하지 않는다.
### 최종 판정 기록
- 새 Oracle의 delta 검토: APPROVE, HIGH. 기존 locale의 명시 필드만 갱신하고 신규/전체 payload의 엄격한 완료 조건은 유지함을 확인했다. CONTENT 게시와 job 완료의 동일 transaction, provider 부분 실패 및 비-CONTENT 분기 보존도 확인했다.
- 최신 HTTP XML 14+10+3=27개 오류/실패/skip 0, jar 존재를 검토자가 확인했다. 회귀 4+118와 lint의 근거는 P5-R1 기록으로 구분했다.
- 모든 로컬 차단 finding은 해결됐다. 위 QA 행의 재검증 대기 표기는 이 후속 판정으로 종결하며, 운영 검증 대기는 해결했다고 표시하지 않는다.