From a48797980ac08fddb8cbad61b3aea5f4186ffa47 Mon Sep 17 00:00:00 2001 From: Klaus Date: Wed, 18 Nov 2026 12:30:37 +0900 Subject: [PATCH] =?UTF-8?q?docs(i18n):=20=EA=B4=80=EB=A6=AC=EC=9E=90=20?= =?UTF-8?q?=EB=B2=88=EC=97=AD=20=EC=84=A0=ED=83=9D=20=EA=B3=84=EC=95=BD?= =?UTF-8?q?=EA=B3=BC=20=EB=B0=B0=ED=8F=AC=20=EB=B0=8F=20=EA=B2=80=EC=A6=9D?= =?UTF-8?q?=20=EA=B8=B0=EB=A1=9D=EC=9D=84=20=EC=A0=95=EB=A6=AC=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../api-contract.md | 362 ++++++ .../frontend-implementation-prompt.md | 266 +++++ docs/20261117_관리자번역후보선택/plan-task.md | 1021 +++++++++++++++++ docs/20261117_관리자번역후보선택/prd.md | 152 +++ .../reviews/design-review.md | 35 + .../reviews/implementation-review.md | 74 ++ docs/20261117_관리자번역후보선택/schema.sql | 80 ++ 7 files changed, 1990 insertions(+) create mode 100644 docs/20261117_관리자번역후보선택/api-contract.md create mode 100644 docs/20261117_관리자번역후보선택/frontend-implementation-prompt.md create mode 100644 docs/20261117_관리자번역후보선택/plan-task.md create mode 100644 docs/20261117_관리자번역후보선택/prd.md create mode 100644 docs/20261117_관리자번역후보선택/reviews/design-review.md create mode 100644 docs/20261117_관리자번역후보선택/reviews/implementation-review.md create mode 100644 docs/20261117_관리자번역후보선택/schema.sql diff --git a/docs/20261117_관리자번역후보선택/api-contract.md b/docs/20261117_관리자번역후보선택/api-contract.md new file mode 100644 index 00000000..d1ab4220 --- /dev/null +++ b/docs/20261117_관리자번역후보선택/api-contract.md @@ -0,0 +1,362 @@ +# 관리자 번역 선택 API 계약 + +> **상태: 서버 구현과 P7 자동 등록 변경의 로컬 검증·부모 직접 검토 완료.** 이 문서의 9개 endpoint와 typed DTO·오류·저장 계약을 구현했다. DEC-11에 따라 controller와 후보 worker는 활성화 설정 없이 애플리케이션 기동 시 등록된다. 기존 외부 최종 APPROVE는 P1~P5 기록이며 P7은 사용자 지시에 따라 부모가 직접 검토·빌드해 종결했다. 운영 MySQL 검증, DDL 실행과 배포는 수행하지 않았다. + +배포된 코드에서는 별도 기능 활성화 단계가 없다. 신규 writer가 작업을 생성하기 전에 세 신규 테이블과 source-language 포함 queue unique index를 준비하고, 구 writer와 in-flight 작업 종료 및 구 unique index 제거를 완료해야 한다. 애플리케이션은 DDL을 자동 적용하지 않는다. 후보 worker의 기본 fixed delay 1000ms와 기존 Redisson `lock:translation-selection` 잠금은 유지한다. + +## 1. 목적 및 문서 기준 + +이 문서는 관리자 다중 제공자 번역 후보의 생성·검토·선택·적용을 위한 서버와 프론트엔드 간 계약을 제안한다. 사용자 동작 기준은 [prd.md](prd.md), 구현 순서와 검증 기준은 [plan-task.md](plan-task.md)를 따른다. + +이 API는 기존 CONTENT 번역 응답과 `ContentTranslation.renderedPayload` 구조를 변경하지 않는다. 후보 및 승인 출처 정보는 이 제안의 신규 테이블에 저장한다. 신규 경로는 기존 ADMIN 인증 경계 아래 추가하며, 프론트엔드 구현은 범위 밖이다. + +## 2. 용어와 상태 + +| 용어 | 의미 | +|---|---| +| Request | 관리자 1회 생성 요청. 적용은 한 번의 부분 선택으로 종료한다. | +| Scope | 단일 콘텐츠 `CONTENT` 또는 하나의 시리즈 `SERIES`와 요청 생성 시점의 모든 활성 연결 콘텐츠. 시리즈의 비활성 콘텐츠는 제외한다. | +| Candidate | 원본 단위·제공자·대상 언어에 대한 신규 번역 결과 또는 그 제공자별 실패. 기존 번역 메모리와 별도다. | +| Field unit | 콘텐츠 하나의 `title`, `detail`, `tags` 전체 텍스트 후보. | +| Title group | 관리자가 번역 생성 전에 검토한 공통 제목 구간과 구성원. 그룹과 언어별 적용은 원자적이다. | +| Residual | 제목 템플릿에서 공통 구간 및 원문 literal 외의 원문 구간. 구성원 단위로 제공자 후보를 만든다. | + +### 2.1 Request 상태 + +| 상태 | 설명 | 허용 전이 | +|---|---|---| +| `PREPARING` | 대상 스냅샷과 원본 언어를 준비한다. | `REVIEW_REQUIRED`, `READY_TO_GENERATE`, `FAILED`, `CANCELLED` | +| `REVIEW_REQUIRED` | 시리즈 그룹 분석을 관리자 검토에 제공한다. 모든 항목을 개별 처리하는 결과도 검토가 필수다. | `READY_TO_GENERATE`, `CANCELLED` | +| `READY_TO_GENERATE` | 단일 콘텐츠이거나 그룹 검토가 완료됐다. | `GENERATING`, `CANCELLED` | +| `GENERATING` | 확정 manifest의 제공자별 후보 요청을 수행한다. | `READY`, `CANCELLED` | +| `READY` | 각 후보 작업이 성공 또는 실패로 종결됐다. | `APPLIED`, `CANCELLED` | +| `APPLIED` | 선택한 일부 값이 원자 적용됐고 나머지 후보는 폐기됐다. | 종료 | +| `CANCELLED` | 취소가 확정됐다. 진행 중 이미 전송된 외부 호출은 되돌릴 수 없다. | 종료 | +| `FAILED` | 후보 생성 전 준비가 복구 불가능한 오류로 실패했다. | 종료 | + +### 2.2 Candidate 상태 + +`PENDING → RUNNING → SUCCEEDED | FAILED`. 취소 또는 성공적 부분 적용으로 미선택된 작업은 `DISCARDED`로 종료한다. 제공자 실패는 해당 후보의 `FAILED`일 뿐이며 다른 제공자 결과를 대체하지 않는다. 모든 제공자가 실패해도 요청은 후보 작업 종결 후 `READY`가 된다. + +## 3. 공통 API 규칙 + +### 3.1 인증과 응답 + +- 모든 endpoint는 **`ADMIN` role** 전용이다. `CONTENT_MANAGER`, creator 관리자 role은 이 API의 권한이 아니다. +- 기존 인증 주체 및 null guard를 사용한다. 신규 controller의 권한 규칙은 기존 `@PreAuthorize("hasRole('ADMIN')")` 관례를 따른다. +- 성공과 business error는 기존 `ApiResponse` envelope(`success`, `message`, `data`, `errorProperty`)를 사용한다. Controller는 `ApiResponse.ok(...)`를 반환하고 business 오류는 `SodaException(messageKey, errorProperty)`로 전달한다. +- 오류 envelope의 HTTP 동작은 현재 `SodaExceptionHandler` 계약을 따른다. 이 기능 때문에 공통 exception handler를 바꾸지 않는다. 인증/접근 거부도 기존 Security 및 handler 동작을 유지한다. +- 이 경로의 모든 오류는 `errorProperty`에 아래 안정 코드를 전달하도록 제안한다. 사용자 표시문은 기존 message key/localization 흐름에 둔다. 제공자 raw exception/body는 반환하지 않는다. + +### 3.2 타입과 정규화 + +| 타입 | 표현 및 제약 | +|---|---| +| ID | JSON signed 64-bit integer로 제안. 기존 Kotlin/JPA `Long` 식별자 관례를 유지한다. | +| UUID | 표준 소문자 UUID 문자열. `clientRequestId`, `operationId`에 사용한다. | +| `FieldKey` | `title`, `detail`, `tags` | +| `LanguageCode` | 현재 `TranslationLanguages` 기준 `ko`, `en`, `ja`. source language는 target에서 제외한다. | +| `ProviderId` | 서버가 알려주는 기존 `TranslationProvider.providerId.code`; 고정 후보 목록을 API가 추가로 만들지 않는다. | +| Timestamp | UTC ISO-8601, 초 정밀도. 새 DB timestamp는 MySQL `TIMESTAMP` 소수초 미지정 기준으로 정규화해 DB와 응답에 같은 값을 쓴다. | +| Fingerprint | 정확한 원문·언어 fingerprint를 식별하는 불투명 버전 포함 문자열. 클라이언트가 생성하거나 수정하지 않는다. | + +선택 요청은 번역문을 보내지 않는다. 입력 경계에서 scope, ID, target language, group/range, UUID, revision, 선택의 중복 및 상호 일관성을 검증한다. 무제한 전체 결과 반환 대신 cursor page를 쓴다. + +### 3.3 공통 오류 코드 제안 + +| `errorProperty` | 의미 | +|---|---| +| `INVALID_REQUEST` | 필드, 언어, UUID, ID 또는 범위 형식이 올바르지 않음 | +| `RESOURCE_NOT_FOUND` | 요청·콘텐츠·시리즈를 찾을 수 없거나 접근 가능한 scope가 아님 | +| `EMPTY_SCOPE` | 시리즈에 현재 연결된 콘텐츠가 없음 | +| `UNSUPPORTED_SOURCE_LANGUAGE` | 감지/지정된 원본 언어가 지원되지 않음 | +| `LANGUAGE_DETECTION_FAILED` | 원본 언어를 준비할 수 없음 | +| `REVIEW_REQUIRED` | 시리즈 그룹 검토 전에 생성 요청 | +| `INVALID_GROUPING` | 중복·누락 구성원, 유효하지 않은 range 또는 서버 규칙 위반 | +| `REVISION_CONFLICT` | 편집·생성 요청 revision이 최신 값과 다름 | +| `REQUEST_NOT_READY` | 현재 상태에서 수행할 수 없는 요청 | +| `REQUEST_CLOSED` | 취소·적용·준비 실패 상태에 mutation 요청 | +| `CANDIDATE_NOT_SELECTABLE` | 다른 요청·단위·언어·제공자이거나 성공하지 않은 후보 | +| `INCOMPLETE_TITLE_GROUP` | 그룹 공통/구성원 residual 선택이 완전하지 않음 | +| `SOURCE_CHANGED` | 선택 적용 대상 필드의 원본이 생성 snapshot과 달라짐 | +| `MEMBERSHIP_CHANGED` | 선택한 제목 그룹의 현재 시리즈 구성원이 생성 snapshot과 달라짐 | +| `IDEMPOTENCY_CONFLICT` | 동일 idempotency key가 다른 body와 재사용됨 | + +오류 코드와 message key는 P3-P5 구현에 추가됐다. P5는 후보 선택 불가·불완전 그룹·원문 변경·구성원 변경의 한국어/영어/일본어 메시지를 연결했다. + +## 4. 신규 endpoint 제안 + +Base path: **`/admin/audio-content/translation-requests`** (P5 종료 시 아래 모든 경로 로컬 구현 완료) + +| Method와 경로 | 목적 | 접근 가능 상태 | +|---|---|---| +| `POST /` | 새 scope 요청 및 후보 준비 예약 | 새 요청 생성 | +| `GET /{requestId}` | 상태, 요약, revision 및 적용 영수증 조회 | 모든 상태 | +| `GET /{requestId}/contents` | snapshot 콘텐츠와 현재 값 페이지 조회 | 모든 상태 | +| `GET /{requestId}/grouping` | 제안/검토된 그룹 템플릿 조회 | `REVIEW_REQUIRED` 이후 | +| `PUT /{requestId}/grouping` | 전체 그룹/개별 목록 교체 및 리뷰 확정·수정 | `REVIEW_REQUIRED`, `READY_TO_GENERATE` | +| `POST /{requestId}/generate` | manifest 고정, 생성 작업 시작 | `READY_TO_GENERATE` | +| `GET /{requestId}/candidates` | 단위별 후보/제공자 상태 cursor 조회 | `GENERATING`, `READY`, terminal | +| `POST /{requestId}/apply` | 선택한 subset을 한 트랜잭션에 적용하고 종료 | `READY` | +| `POST /{requestId}/cancel` | 미적용 요청 취소 | 모든 nonterminal 상태 및 `READY` | + +`APPLIED` 요청은 취소할 수 없다. 같은 취소의 재시도는 이미 취소됐다는 terminal 응답을 반환한다. 그룹이나 원문 변경 후 재생성을 위한 update/restart endpoint는 제공하지 않는다. 기존 요청을 취소하고 새 요청을 생성한다. + +## 5. Request DTO와 응답 + +### 5.1 요청 생성 + +`POST /` body: + +```json +{ + "clientRequestId": "d7c2f4e1-1e4f-4ac2-a6ed-85f2f8102101", + "scope": { "type": "CONTENT", "contentId": 4102 } +} +``` + +`scope`는 다음 합 타입 중 하나다. + +```json +{ "type": "CONTENT", "contentId": 4102 } +{ "type": "SERIES", "seriesId": 981 } +``` + +Response `data`는 `TranslationSelectionRequestResponse`: + +```json +{ + "requestId": 710, + "scope": { "type": "SERIES", "seriesId": 981 }, + "status": "PREPARING", + "revision": 1, + "createdAt": "2026-11-17T07:00:00Z", + "providerManifest": [], + "targetLanguages": [], + "contentCount": 0, + "progress": { "total": 0, "terminal": 0, "succeeded": 0, "failed": 0 }, + "errorCode": null, + "applyReceipt": null +} +``` + +예시 숫자와 UUID는 schema 설명용 값이며 실제 자원이나 구현된 ID를 지칭하지 않는다. 생성 transaction에서 요청을 `PREPARING`으로 저장하며 현재 활성 series membership의 content ID 집합도 고정한다. 활성 연결 콘텐츠가 없으면 저장된 요청을 `FAILED/EMPTY_SCOPE`로 종결한다. 원본 언어와 필드 snapshot은 비동기 preparation에서 확정한다. 이 시간 구분은 최종 snapshot을 만들기 전에 이미 번역이 시작됐다는 뜻이 아니다. + +동일 feature poller가 `PREPARING` request를 lease/fence로 claim한다. 기존 source language를 사용하고 누락된 경우에만 감지한다. 감지 호출 전후 취소를 확인하며 최종 source snapshot 저장 전에 잠금 안에서 원문·언어·활성 membership을 재검증한다. 원문이 달라졌으면 해당 준비를 `FAILED/SOURCE_CHANGED`, membership이 달라졌으면 `FAILED/MEMBERSHIP_CHANGED`로 종결하고 재요청을 안내한다. 준비 중 crash는 lease 만료 후 한 번만 복구하며 두 번째 만료는 `FAILED/PREPARATION_INTERRUPTED`로 종결한다. + +Idempotency: `(authenticatedAdminId, clientRequestId)` unique. 동일 UUID와 canonical body hash면 원래 요청을 반환한다. 다른 body hash면 `IDEMPOTENCY_CONFLICT`. 클라이언트는 retry에 같은 UUID와 같은 body를 보낸다. + +### 5.2 Request 요약 조회 + +`GET /{requestId}`는 위 response를 반환한다. `PREPARING`와 `GENERATING` progress는 상태 조회 시점의 단순 snapshot이다. `READY`는 모든 candidate 작업이 terminal인 뜻이며, 일부/전부 실패도 포함한다. `APPLIED`는 receipt를 포함한다. 원시 provider 예외나 credential/요청 body는 포함하지 않는다. + +### 5.3 콘텐츠 페이지 + +`GET /{requestId}/contents?afterContentId={id}&size=50` (`size` 기본 50, 최대 100) + +Response data는 `{items: List, nextAfterContentId: Long?}`다. + +| `ContentSnapshotResponse` 필드 | 타입·의미 | +|---|---| +| `contentId`, `active`, `eligible` | `Long`, 조회 시 현재 활성 여부 `Boolean`, 해당 scope의 현재 적용 자격 `Boolean` | +| `sourceLanguage` | 고정 snapshot의 `LanguageCode` | +| `sourceFields` | `Map`; title/detail/tags가 모두 존재 | +| `sourceFingerprints`, `currentSourceFingerprints` | 고정 `Map`과 현재 `Map?` | +| `emptyFields` | `List`; 번역할 텍스트가 없어 후보를 만들지 않은 필드 | +| `currentTranslations` | `List<{targetLanguage: LanguageCode, fields: Map, approvalOrigins: Map, approvalProvenance: Map}>` | + +시리즈 scope는 생성 시 활성 member만 포함한다. `sourceLanguage`, `sourceFields`, `sourceFingerprints`는 준비 완료 시 고정된 snapshot이다. `currentTranslations`, `active`는 조회 시점 값이다. 각 item은 `currentSourceFingerprints: Map?`, `eligible: Boolean`도 반환한다. 삭제된 콘텐츠는 현재 fingerprint가 null이고 eligible=false이며 snapshot은 남는다. 프론트엔드는 변경 여부를 표시할 수 있지만 최종 적용 가능 여부는 서버가 잠금 안에서 판정한다. + +`approvalOrigins` 값은 `ADMIN` 또는 `UNKNOWN`이다. 유효한 field override row가 있는 값만 `ADMIN`으로 표시한다. 해당 승인 필드에는 `approvalProvenance: Map, providers: List<{id: String, version: String}>, approvedBy: Long, approvedAt: Timestamp}>`도 반환한다. 기존 값의 provider는 추정하지 않는다. 현재 translation row가 없으면 현재 원문 fallback을 제공한다. 마지막 페이지의 `nextAfterContentId`는 null이다. `PREPARING`에서는 아직 확정되지 않은 items를 반환하지 않는다. + +### 5.4 Grouping 읽기 및 저장 + +`GET /{requestId}/grouping`의 `data`는 아래 타입이다. `groups`와 `templates`는 저장된 현재 분석/검토 결과이며, generation 이후에는 동결된 동일 값을 반환한다. 그룹 검토 전후 모두 source text를 재구성할 수 있어야 한다. + +| 타입 | 필수 필드 | +|---|---| +| `GroupingResponse` | `requestId: Long`, `revision: Long`, `reviewed: Boolean`, `indexUnit: "UNICODE_CODE_POINT"`, `groups: List`, `individualContentIds: List`, `templates: List` | +| `TitleGroup` | `groupId: String`, `sourceLanguage: LanguageCode`, `memberContentIds: List`, `sharedParts: List` | +| `SharedPart` | `partId: String`, `sourceText: String`, `occurrences: List<{contentId: Long, startCodePoint: Int, endCodePoint: Int}>` | +| `TitleTemplate` | `contentId: Long`, `groupId: String`, `sourceFingerprint: String`, `segments: List` | +| `TitleSegment` | `segmentId: String`, `kind: LITERAL/SHARED/RESIDUAL`, `startCodePoint: Int`, `endCodePoint: Int`, `sourceText: String`, `partId: String?`, `valueIndex: Int?` | + +`segments`는 원문 순서다. SHARED의 `partId`와 `valueIndex`는 해당 그룹 `sharedParts` 배열 항목을 가리킨다. RESIDUAL의 `partId`는 null이고 `valueIndex`는 해당 콘텐츠 residual 입력 배열의 0-based 순번이다. LITERAL은 두 값이 null이며 `sourceText`를 그대로 출력한다. Grouped member의 residual 입력 순서는 segments에서 RESIDUAL만 추린 순서와 같다. 하나의 provider 후보 `translatedValues[i]`는 해당 입력 배열의 i번째 구간과 대응한다. 이 계약으로 frontend와 apply 서비스가 동일한 전체 제목 preview를 재구성한다. + +`PUT /{requestId}/grouping` body: + +```json +{ + "expectedRevision": 1, + "groups": [{ + "groupId": "g-1", + "memberContentIds": [4102, 4103], + "sharedParts": [{ + "partId": "p-1", + "occurrences": [ + { "contentId": 4102, "startCodePoint": 0, "endCodePoint": 5 }, + { "contentId": 4103, "startCodePoint": 0, "endCodePoint": 5 } + ] + }] + }], + "individualContentIds": [4104] +} +``` + +이 JSON은 제안 DTO 형태를 보여주는 예시일 뿐 특정 데이터의 결정된 값이 아니다. body는 요청 전체 scope를 빠짐/중복 없이 그룹 또는 individual에 한 번씩 배정해야 한다. 각 group은 2개 이상 멤버로 구성되고 하나의 source language만 포함한다. 각 part는 모든 group member에 같은 nonempty 원문 substring이 존재해야 한다. 서버는 offset 범위 원문으로 공통 텍스트를 유도한다. 원문 문자열 대체 입력은 받지 않는다. + +Index는 Unicode code point 기준 0부터 시작하는 inclusive start, exclusive end다. UTF-16 code unit 인덱스가 아니며 Java grapheme boundary를 자르는 범위는 거부한다. Group ID와 part ID는 요청 안에서 중복될 수 없다. 제출 성공 시 grouping을 저장하고 `revision`을 증가시킨다. 첫 확정은 `REVIEW_REQUIRED`에서 `READY_TO_GENERATE`로 전이한다. 생성 전에는 `READY_TO_GENERATE`에서도 같은 endpoint로 재수정할 수 있고 상태는 유지한다. 모든 individual도 관리자가 검토·확정해야 한다. `GENERATING` 전이 이후에는 grouping을 바꿀 수 없다. + +Group read model의 segment 타입은 `LITERAL`, `SHARED`, `RESIDUAL`이다. 원문을 순서대로 이어 붙였을 때 원문 제목과 code point 단위로 완전히 일치해야 한다. literal은 번역 대상이 아닌 공백/구두점/숫자 구간을 그대로 보존한다. 단순한 프론트엔드 수정 또는 잘못된 offset은 `INVALID_GROUPING`이다. + +공통 구간 사이의 gap에 문자가 있으면 바깥 공백·구두점만 LITERAL로 분리하고 내부 공백·구두점·숫자를 포함한 구문 전체를 하나의 RESIDUAL로 보낸다. 예를 들어 `비 오는 날`은 세 단어가 아닌 하나의 입력이다. 문자가 전혀 없는 gap은 전체를 LITERAL로 보존한다. + +## 6. 후보 생성과 조회 + +### 6.1 후보 생성 + +`POST /{requestId}/generate` body: + +```json +{ "expectedRevision": 2 } +``` + +응답은 request 요약이다. Request는 모든 콘텐츠의 `title`, `detail`, `tags` 및 해당 source language 외 현재 지원 언어(`ko`, `en`, `ja`) 전체를 대상으로 삼는다. 생성 시 field/language 선택을 받지 않는다. 등록된 모든 `TranslationProvider`가 각 nonempty generation unit을 독립적으로 새로 호출한다. 대상 언어는 provider configuration이나 기존 번역 메모리에서 추정하지 않는다. + +request 잠금 안에서 먼저 저장된 accepted generation revision과 요청 revision의 일치 여부를 확인한다. 이미 수락된 동일 요청이면 현재 state/revision이 달라졌어도 기존 결과를 반환하며 후보를 다시 만들지 않는다. 최초 generate에만 `READY_TO_GENERATE`, 현재 revision, 검토 상태를 검사하고 generation manifest와 candidate 작업을 원자 생성해 `GENERATING`으로 전이한다. 이후 grouping 수정은 허용하지 않는다. + +### 6.2 Candidate 페이지 + +`GET /{requestId}/candidates?afterCandidateId={id}&size=50` (`size` 기본 50, 최대 100) + +```json +{ + "items": [{ + "candidateId": 811, + "unit": { "kind": "FIELD", "contentId": 4102, "field": "detail" }, + "provider": { "id": "aws", "version": "translate-2017-07-01" }, + "targetLanguage": "ko", + "status": "SUCCEEDED", + "translatedValues": ["달빛 아래에서 나눈 약속입니다."], + "failureCode": null + }], + "nextAfterCandidateId": 811 +} +``` + +실패 candidate에는 `translatedValues: null`, 안정화된 `failureCode`를 제공한다. 실패 원문/외부 response/secret은 숨긴다. 동등한 translated values의 다중 provider 결과는 별도 후보 출처들을 유지한 채 응답에서 동등 그룹으로 묶어 보여줄 수 있다. 동일 후보 비교는 정확한 반환 문자열 기준이며, 원본 provenance는 UNKNOWN 허용이다. + +Unit 합 타입: + +| `kind` | 필드 | 의미 | +|---|---|---| +| `FIELD` | `contentId`, `field` | 단일 title/detail/tags 전체 문자열 후보 | +| `GROUP_COMMON` | `groupId` | 그룹 내 모든 shared title part의 순서 보존 배열 | +| `TITLE_RESIDUAL` | `groupId`, `contentId` | 해당 member의 residual segment 번역 배열 | + +각 candidate는 `inputValues: List`도 반환한다. FIELD 입력/결과는 길이 1이며 `translatedValues[0]`가 최종 해당 필드 값이다. GROUP_COMMON은 grouping.sharedParts 순서, TITLE_RESIDUAL은 해당 template의 residual 순서다. 제공자 응답의 개수가 입력과 다르거나 nonempty 입력의 결과가 공백이면 `FAILED/INVALID_PROVIDER_RESULT`이며 선택할 수 없다. 제공자 ID/version이 동결 manifest와 달라졌거나 사라지면 `FAILED/PROVIDER_CHANGED`로 기록하고 다른 provider/version으로 대체하지 않는다. 마지막 페이지의 `nextAfterCandidateId`는 null이다. + +빈 원문과 전부 literal residual은 paid call candidate가 없다. 빈 FIELD는 contents의 `emptyFields: List`로 표시하고 새 승인 대상에서 제외한다. literal-only residual은 template로 조립하고 선택 candidateId는 null이다. 후보 저장은 global translation memory를 읽거나 갱신하는 행위가 아니다. 상세 문서는 준비 실패의 `PREPARATION_INTERRUPTED`, provider 작업 실패의 `PROVIDER_FAILED`, `PROVIDER_CHANGED`, `INVALID_PROVIDER_RESULT`, `EXECUTION_INTERRUPTED`를 안정 failureCode로 사용한다. + +## 7. Apply와 cancel 계약 + +### 7.1 부분 apply + +`POST /{requestId}/apply` body: + +```json +{ + "operationId": "3b3887e6-60c5-42d7-a310-cf0cbd6d0a84", + "expectedRevision": 3, + "selections": [ + { "kind": "FIELD", "contentId": 4102, "field": "detail", "targetLanguage": "ko", "candidateId": 811 }, + { + "kind": "TITLE_GROUP", + "groupId": "g-1", + "targetLanguage": "ko", + "commonCandidateId": 901, + "residualChoices": [ + { "contentId": 4102, "candidateId": 902 }, + { "contentId": 4103, "candidateId": null } + ] + } + ] +} +``` + +예시는 합 타입 DTO 구성을 보여준다. `selections`는 비어 있으면 안 된다. client가 translated text를 보내는 자유 형식 override는 지원하지 않는다. Server는 모든 ID가 같은 request의 성공 candidate이며 unit/provider/target과 맞는지 확인한다. + +`FIELD`는 콘텐츠·필드·언어마다 하나만 선택 가능하다. `TITLE_GROUP`는 그룹+언어 선택 하나를 뜻하며 `commonCandidateId`와 모든 member residual choice를 완전하게 제공한다. residual이 전부 literal이면 그 member의 `candidateId`는 null이어야 한다. 공통 번역은 선택된 한 provider candidate가 모든 group member에 적용되고, member별 residual은 서로 다른 provider가 선택될 수 있다. 단 하나의 그룹 안에서 member를 omit하거나 공통 provider를 나눌 수 없다. 일부 구성원을 따로 적용하려면 생성 전 grouping을 수정한다. + +Apply 처리 규칙: + +1. request 행을 잠그고 저장된 operationId/body hash를 먼저 검사한다. 동일 요청의 replay면 기존 receipt를 반환한다. 새 apply에만 READY 상태와 현재 revision 검증을 적용한다. +2. 필요한 Series 부모, CONTENT 부모를 ID 오름차순으로 잠근다. 시리즈 그룹 적용은 활성 membership을 안정적으로 확인할 수 있도록 현재 연결 CONTENT 부모도 잠그며, 구성원 추가/제거는 동일 Series 잠금으로 직렬화한다. +3. 잠금 이후 최신 source·활성 membership·override·payload를 다시 읽고 최종 검증한다. 잠금 전 JPA entity나 로딩된 연관 컬렉션을 그대로 신뢰하지 않는다. FIELD는 선택 필드 fingerprint와 content 존재 여부를 검사하며, SERIES scope일 때 현재 연결·활성 자격도 요구한다. 제목 그룹은 모든 member title fingerprint/language와 고정된 활성 membership 전체를 검사한다. 선택되지 않은 다른 필드 변경은 거부 조건이 아니다. +4. 모든 선택 값을 하나의 DB transaction으로 저장한다. 실패가 하나라도 있으면 어떤 값도 적용하지 않고 request는 `READY` 상태에 남는다. +5. 적용 값만 field-scoped override와 기존 CONTENT rendered payload에 쓴다. 미선택 payload 값은 byte-for-byte 보존한다. Locale row가 없으면 미선택 필드는 현재 source fallback으로 초기화한다. +6. Request를 `APPLIED`로 닫고 선택되지 않은 candidate를 `DISCARDED`로 표시한다. 적용 결과 receipt를 저장한다. + +같은 `operationId`와 canonical request body hash는 저장된 receipt를 반환한다. 동일 operation ID를 다른 body에 재사용하면 `IDEMPOTENCY_CONFLICT`. 요청이 APPLIED인데 다른 operation ID로 호출하면 `REQUEST_CLOSED`다. Operation ID는 관리자+request 범위에서 유일하다. + +Response `ApplyTranslationSelectionResponse`의 필수 필드는 `requestId: Long`, `operationId: UUID`, `status: "APPLIED"`, `appliedAt: Timestamp`, `appliedFields: List`, `discardedCandidateCount: Int`다. `AppliedField`는 `contentId: Long`, `field: FieldKey`, `targetLanguage: LanguageCode`, `translatedValue: String`, `candidateIds: List`, `providers: List<{id: String, version: String}>`다. Group title은 공통·residual 출처를 모두 남긴다. Receipt는 override/payload와 같은 transaction에서 저장하며 재전송에도 불변이다. + +### 7.2 취소 + +`POST /{requestId}/cancel` body 없음. `PREPARING`, `REVIEW_REQUIRED`, `READY_TO_GENERATE`, `GENERATING`, `READY`를 취소할 수 있다. APPLIED에서는 `REQUEST_CLOSED`로 거부한다. Cancel은 새 revision이 없는 stale browser에서도 동작해야 한다. + +취소의 선형화 지점은 request 행 gate에서 CANCELLED를 commit하는 시점이다. 이후 새 provider chunk dispatch 승인을 금지한다. 취소보다 먼저 승인을 받은 호출은 이미 진행 중인 작업으로 취급하며, 실제 네트워크 전송이 취소 commit 뒤에 일어나더라도 비용이 발생할 수 있다. 취소 응답은 외부 호출 종료를 기다리지 않고 DB 취소 확정 후 반환한다. 늦은 응답은 candidate로 publish하거나 적용할 수 없다. Network I/O 동안 DB transaction을 유지하지 않는다. + +Phase4 transport 기술 확인: 설치된 AWS SDK 2.57.11에서 요청별 execution attribute와 `beforeTransmission`으로 SDK retry마다 같은 gate를 적용한다. AWS는 요청별 남은 15초 API-call/attempt timeout을 사용한다. Apache5의 요청별 connect/read 및 공개 요청별 retryStrategy 설정은 지원되지 않으므로 기존 공유 socket/retry 설정을 유지한다. Papago admin 경로만 기존 RestTemplate 방식으로 connect 3초/read 15초를 제한한다. 15초 dispatch budget과 read timeout을 절대적인 전체 wall-clock 중단 정밀도로 해석하지 않는다. 일반 요청에는 admin control을 적용하지 않는다. + +## 8. 프론트엔드 상호작용 명세 + +이 절은 UI 동작 계약만 정의하며 route/page/component/style을 구현하거나 시각 디자인을 지정하지 않는다. + +1. 관리자는 콘텐츠 또는 시리즈 ID로 요청을 만든다. `PREPARING`/`GENERATING` 상태는 1초 간격 polling으로 조회한다. +2. 시리즈는 grouping 분석 화면으로 전이하고 관리자가 모든 콘텐츠를 그룹 또는 개별 상태로 분류해 확정하기 전 generate action을 보내지 않는다. 원문 구간은 code point 인덱스로 변환하고 후보 생성 뒤에는 grouping 편집 대신 cancel 후 재요청을 제공한다. +3. 최초 활성 콘텐츠 snapshot의 title/detail/tags, 언어, 현재 값과 활성 자격, fingerprint 기반 변경 가능성을 request/content pages에서 검토한다. source 언어를 target language로 제시하지 않는다. +4. 생성 완료 후 field candidate를 필드·언어별로 비교한다. 제공자 이름·버전·실패 상태를 확인 가능하게 하고 같은 text 후보를 출처 손실 없이 접어 보여줄 수 있다. 기존 translation origin `UNKNOWN`을 실제 provider처럼 표기하지 않는다. +5. grouped title은 group+language로 공통 선택 하나와 member별 residual 선택을 만든다. 불완전 group은 apply할 수 없으며, 그룹 구성원의 결과를 분리하려면 새 request 전에 group을 나눈다. +6. 사용자가 apply할 선택 subset을 review한 후 operation UUID를 생성해 한번 전송한다. 성공 receipt 이후 같은 request에서 새 선택을 추가할 수 없다. server의 SOURCE_CHANGED/MEMBERSHIP_CHANGED 오류면 이전 후보 재적용 대신 새 request를 시작한다. +7. 검토 전·진행 중·READY 상태에서 cancel할 수 있음을 표시한다. 이미 전송된 외부 호출의 비용은 취소로 되돌릴 수 없다는 점과 적용 미확정 값을 유지하는 동작을 설명한다. + +Candidate 문자열은 HTML로 해석하지 않고 text로 표시한다. 화면 시각 규칙, 로딩 애니메이션, responsive layout은 본 계약의 범위가 아니다. + +## 9. 내부 데이터 및 변경 불변식 + +세 테이블과 저장 불변식, worker·writer·rollout 설계는 [plan-task.md §설계 제안](plan-task.md#설계-제안)에 정의한다. Entity/store/controller와 로컬 H2 검증은 구현했으며 운영 schema 적용과 rollout은 별도 승인 대상이다. + +필수 동작 불변식: + +- `ContentTranslation.renderedPayload`의 기존 schema, API response는 변경하지 않는다. +- 새 candidate는 `TranslationCoordinator`의 first-success fallback, translation memory 조회/갱신을 사용하지 않는다. 모든 등록 provider를 직접 독립 호출한다. +- 기존 translated payload는 명시 적용 때까지 유지한다. 관리 승인 값의 provenance는 override row에 보관하며 과거 provider는 UNKNOWN이다. +- 기존 CONTENT materializer는 Content lock 안에서 최신 원본과 override를 재조회한다. 일치하는 approval은 자동 결과보다 우선한다. 다른 리소스 materialization에는 변경을 적용하지 않는다. +- 원본 mutation은 변경된 field의 override만 제거하고 해당 locale field를 source fallback으로 바꾸며 정상 자동 번역을 schedule한다. Source language 변경은 모든 field를 변경된 것으로 취급한다. 원본이 A→B→A로 되돌아와도 삭제한 이전 approval은 살아나지 않는다. +- 제목 그룹 apply는 선택 그룹 전체 fingerprint와 고정 membership을 검증한다. 개별 field apply는 선택한 field fingerprint만 검증한다. +- 취소 gate, lease/fence, candidate publish 검사로 취소 후 새로운 outbound dispatch 승인이나 late publication/apply를 막는다. 취소 전 승인된 provider 요청에 exactly-once 과금을 보장하지 않는다. + +## 10. 계약 상태, 추적 및 검증 + +| 구분 | 상태 | +|---|---| +| PRD 인터뷰 product decisions | 확정 | +| 이 API endpoint/DTO/error contract | 승인, P1-P5 로컬 구현·집중 검증 완료 | +| persistence 및 server architecture | 로컬 구현 완료, 운영 MySQL 검증 대기 | +| Frontend implementation | 미착수, 범위 밖 | +| Backend implementation | P1~P5 및 최종 gate 보정 완료, APPROVE | + +| PRD requirement | 계약 범위 | +|---|---| +| TR-01~TR-02 | Scope 및 contents snapshot | +| TR-03~TR-06, TR-14~TR-15 | Grouping review, generation gate 및 group atomic apply | +| TR-07~TR-13 | Provider manifest, candidate 생성·조회, provenance와 언어 | +| TR-16~TR-17 | One-shot apply, omitted discard 및 cancel | +| TR-18~TR-20 | Content override, field invalidation, selected-field freshness | + +실행한 focused test·RED/GREEN·회귀 보정과 명령은 `plan-task.md`의 Progress에 기록했다. 부모가 보정된 최종 코드의 실제 HTTP 27개와 bootJar를 실행해 통과했으며 최종 gate는 APPROVE다. 전체 테스트 `./gradlew test`는 사용자가 실행한다. 실제 MySQL·provider 품질·운영 적용은 별도 검증이다. + +### 승인 및 실행 기록 — 2026-11-17 + +사용자가 설계 승인에 이어 구현 시작을 명시적으로 승인했다. 승인 당시 endpoint와 schema 구현은 없었다. 이후 P1-P5 로컬 구현·집중 검증을 완료했으며 현재 증거와 미완료 운영 검증은 [plan-task.md](plan-task.md)의 Progress 실행 ledger에서 관리한다. Production DDL/deploy/git commit은 승인·실행 범위에 포함되지 않는다. diff --git a/docs/20261117_관리자번역후보선택/frontend-implementation-prompt.md b/docs/20261117_관리자번역후보선택/frontend-implementation-prompt.md new file mode 100644 index 00000000..c16a2c25 --- /dev/null +++ b/docs/20261117_관리자번역후보선택/frontend-implementation-prompt.md @@ -0,0 +1,266 @@ +# 관리자 번역 후보 선택 프론트엔드 구현 지시 + +별도 프론트엔드 저장소에서 이 기능을 실제로 구현하라. 이 파일, 사용자가 별도로 제공하는 API 계약 파일, 그리고 네가 작업하는 프론트엔드 저장소만 근거로 삼는다. 제공된 API 계약 외의 백엔드 저장소 PRD·계획·검증 기록·소스, 다른 컴퓨터의 절대 경로, 이전 대화나 숨은 세션 지식에 의존하지 않는다. 아래 지시로 프론트엔드 저장소 안에 새로 만드는 문서는 이후 작업의 기준으로 사용한다. API 계약이 없으면 파일 위치만 물어보고 네트워크 계약을 추측하지 않는다. 계약과 아래 제품 요구가 충돌하면 충돌한 항목만 구체적으로 기록하고 해당 작업을 멈춘 뒤 질문한다. + +## 1. 목표와 경계 + +- 관리자 콘텐츠 상세와 시리즈 상세에 각각 진입 버튼을 두고, 하나의 공유 요청 생성·검토·후보 선택 workflow를 구현한다. +- 기존 프론트엔드의 접근성, 라우팅, API client, 캐시, 상태 관리, 디자인 구성요소, 테스트 관례를 재사용한다. 새 의존성 및 무관한 리팩터링은 피한다. +- 일반 관리자 화면에서 동작하는 완성 기능을 만든다. 스텁, 빈 동작, 가짜 성공, 운영용 mock fallback은 허용하지 않는다. +- 서버 API는 ADMIN 전용이며 별도 feature flag 없이 배포된 애플리케이션 기동 시 등록된다. 프론트엔드에 서버 기능 활성화 토글이나 설정 단계를 만들지 않는다. 버튼 표시만으로 해당 환경의 배포·연결 준비를 완료했다고 판단하지 않는다. +- 사용자가 제공하는 API 계약이 endpoint, DTO, envelope, 오류 및 타입의 기준이다. 아래 요약은 사용 흐름과 제품 요구를 자립적으로 전달한다. +- 서버의 9개 endpoint는 구현됐고 기존 backend 최종 검토에서 승인됐다. 이후 사용자 요청으로 활성화 플래그를 제거했다. 이 기록을 이 저장소의 구현이나 검증 결과로 주장하지 않는다. +- 운영 DDL 반영과 배포는 완료되지 않았다. 새 writer의 작업 생성 전 세 신규 테이블, 원문 언어 포함 queue unique index, 구 writer·in-flight 작업 종료 및 구 unique index 제거가 필요하다. 자동 DDL이나 별도 활성화 단계는 없다. 이 운영 전제는 백엔드 운영자가 처리하며 프론트엔드에서 실행하지 않는다. 실제 UI와 프론트엔드 구현도 아직 없다. + +## 2. 구현 전 필수 문서와 조사 + +### 2.1 저장소 파악 + +코드를 수정하기 전에 프론트엔드 저장소의 AGENTS.md, README, package/build 설정, 테스트 및 개발 명령을 읽는다. 실제 버튼이 놓일 콘텐츠 상세·시리즈 상세, 기존 API client/envelope/auth, 관리자 role 처리, base URL 환경변수, query/cache 패턴, 번역 언어 및 Unicode 유틸리티, 디자인 구성요소, 테스트 명령을 찾는다. 파일 경로와 명령은 실제 확인한 값만 쓴다. + +기존 diff를 먼저 확인해 사용자·다른 작업의 변경과 이번 변경을 구분한다. 자신이 만들지 않은 변경을 덮어쓰거나 되돌리지 않는다. + +사용자가 제공한 API 계약 파일을 찾아 읽는다. 파일명이 정해져 있다고 가정하지 않는다. 없다면 구현 전 파일 위치를 요청한다. endpoint나 DTO를 상상해 진행하지 않는다. + +### 2.2 코드 작성 전 문서 다섯 개 + +실제 프론트엔드 저장소의 기존 문서 규칙을 우선 확인한다. 아래 산출물을 그 규칙을 따르는 한 곳에 만들거나 기존 것을 재사용한다. 기존 규칙이 다른 경로를 요구하면 실제 경로를 사용하고 다섯 문서의 canonical mapping을 한 번 기록한다. 중복 계획을 만들지 않는다. + +1. `docs/20261118_관리자번역언어선택/api-contract.md` + - 제공된 계약을 의미 변경 없이 그대로 복사한다. 이미 존재하면 내용과 provenance를 확인해 재사용한다. + - 사용자 파일을 덮어쓰지 않는다. 원본 경로와 provenance는 `progress.md`에 기록하고 계약 문서 본문에는 추가하지 않는다. +2. `docs/20261118_관리자번역언어선택/prd.md` + - 이 프롬프트의 제품 요구에서 생성한다. 외부 PRD가 필요하다고 가정하지 않는다. +3. `docs/20261118_관리자번역언어선택/plan-task.md` + - 실제 발견한 프론트엔드 파일 경로, 라우트, 명령을 포함하는 작은 단계와 의존성, acceptance criteria, 증거를 쓴다. + - 체크박스와 고유 Goal ID를 사용하고 활성 Goal은 하나만 둔다. 각 작업에 정확한 경로, focused 검증과 기대 결과를 적는다. + - 알 수 없는 값은 placeholder로 채우거나 이미 확인한 것처럼 쓰지 않는다. +4. `docs/20261118_관리자번역언어선택/verification.md` + - 코드 작성 전에 검증 행렬을 만든다. 각 행은 `NOT_RUN`, `BLOCKED`, `PASS`, `FAIL` 중 하나로 표시하며 기대 assertion, 환경, 명령/증거 경로를 적는다. + - 기존 API client와 envelope, 인증, 관리자 역할, base URL 환경변수, schema availability, connectivity, Unicode 범위 도구, query/cache, 디자인 요소, 테스트 명령을 사전 조사한다. + - 사전 connectivity 확인은 안전한 read-only 요청만 사용한다. 유료 provider 요청, 생성·적용·취소 같은 mutation, 배포나 운영 변경을 사전 점검으로 실행하지 않는다. 알려진 테스트 requestId가 없으면 임의 ID나 존재하지 않는 목록 endpoint로 API 준비 완료를 판단하지 않는다. + - 실제 API 연동 준비가 확인되지 않으면 해당 항목은 `BLOCKED`로 둔다. UI와 단위 테스트 작업은 계속한다. + - fixture/mock 테스트와 실제 서버 검증을 별도 행으로 구분한다. +5. `docs/20261118_관리자번역언어선택/progress.md` + - 승인 범위, 확정 결정, 현재 및 다음 Goal, 완료 Goal, 변경 파일, 가정·결정·차단 요소, 스크린샷 경로를 기록한다. + - 실행한 정확한 명령과 결과, 실제 API 대 fixture 구분을 누적한다. 마지막 requestId는 테스트용만 허용하며 secret은 절대 기록하지 않는다. + +다섯 문서가 작성되고 최초 계획 및 검증 기준이 기록될 때까지 production code를 수정하지 않는다. 이후 각 milestone마다 계획 체크박스, progress, verification을 갱신한다. 이미 완료한 목표와 근거는 삭제하거나 과거 PASS를 현재 코드의 증거로 재사용하지 않는다. + +장기 작업 재개 시 다섯 문서를 모두 읽고 현재 diff와 테스트 산출물을 확인한다. 실제 evidence에 맞는 첫 미완료 Goal부터 이어가며, 이미 확인된 인터뷰나 완료 작업을 반복하지 않는다. 기존 계획과 사용자 지시가 다르면 사용자 지시가 우선이다. 충돌 우선순위는 사용자 지시, API HTTP 계약, 제품 요구, 실행 계획 순서다. 충돌한 작업만 멈춰 기록한다. + +## 3. API 사용 요약 + +Base path는 `/admin/audio-content/translation-requests`다. Endpoint·필드명·타입은 제공된 API 계약을 기준으로 한다. 아래 제품 동작과 실질적인 충돌이 있으면 요구사항을 임의로 바꾸지 말고 해당 항목을 기록해 확인한다. + +| Method | Path | 역할 | +|---|---|---| +| POST | `/` | CONTENT 또는 SERIES 요청 생성 | +| GET | `/{requestId}` | 상태, revision, progress, receipt 조회 | +| GET | `/{requestId}/contents` | snapshot 및 현재 데이터 cursor 조회 | +| GET | `/{requestId}/grouping` | 제목 그룹과 template 조회 | +| PUT | `/{requestId}/grouping` | 전체 grouping 검토·교체 | +| POST | `/{requestId}/generate` | 동결 manifest의 후보 생성 시작 | +| GET | `/{requestId}/candidates` | 후보 cursor 조회 | +| POST | `/{requestId}/apply` | 선택 subset을 한 번 적용 | +| POST | `/{requestId}/cancel` | 미적용 요청 취소, body 없음 | + +- 모든 호출은 ADMIN 권한을 요구한다. 기존 auth를 쓰고 role이 없으면 버튼을 숨기며 직접 진입도 차단한다. 서버 설정을 변경하지 않는다. +- 성공 및 business failure는 `success`, `message`, `data`, `errorProperty` envelope를 사용한다. HTTP 200만으로 성공 처리하지 말고 `success`도 확인한다. +- ID는 API의 signed 64-bit numeric Long과 저장소 관례를 따른다. 정밀도를 잃는 JS number 처리를 피하되, 계약/기존 repo가 정한 안전한 직렬화 방식을 사용한다. 임의 string 변환 계약을 만들지 않는다. +- 생성 body는 `clientRequestId: UUID`와 scope 합 타입 `{type: CONTENT, contentId}` 또는 `{type: SERIES, seriesId}`다. +- grouping PUT은 `expectedRevision`, 전체 `groups`(groupId, memberContentIds, sharedParts의 partId 및 contentId/startCodePoint/endCodePoint occurrences), 전체 `individualContentIds`를 보낸다. +- generate body는 `{expectedRevision}`이다. 최초 요청 body와 revision을 보존한다. +- apply body는 `operationId: UUID`, `expectedRevision`, selections 배열이다. FIELD 선택은 `kind: "FIELD"`, contentId, `field: "title" | "detail" | "tags"`, targetLanguage, candidateId를 가진다. 그룹 선택은 `kind: "TITLE_GROUP"`, groupId, targetLanguage, commonCandidateId와 모든 member의 `{contentId, candidateId: 후보 ID 또는 null}` residualChoices를 가진다. 이 표기는 타입 요약이며 실제 JSON은 계약에 맞춰 생성한다. +- 콘텐츠 페이지는 `afterContentId`, 후보 페이지는 `afterCandidateId`, 기본 size 50, 최대 100을 사용한다. `nextAfter...`가 null일 때만 끝이다. 한 페이지를 전체로 간주하지 않는다. +- 후보 ID는 고정이고 같은 ID의 상태·결과가 갱신된다. READY 진입 때 이미 읽은 페이지를 다시 받아 ID 기준으로 갱신한다. revision, cursor, 요청 ID를 임의로 섞지 않는다. + +## 4. 제품 동작과 상태 흐름 + +요청 scope는 콘텐츠 하나 또는 생성 시점의 활성 시리즈 구성원 전체다. 비활성 구성원은 제외한다. 필드는 제목, 상세, 태그다. 대상 언어는 `ko`, `en`, `ja`에서 각 콘텐츠의 source language를 제외한다. 요청 본문에서 필드·언어를 골라 서버 작업을 줄이지 않는다. + +source language가 이미 있으면 사용하며 프론트에서 재감지·전환하지 않는다. 준비 중에는 기존 번역이 보존된다. 모든 nonblank 필드, 모든 대상 언어, 서버 manifest의 모든 provider에 대해 fresh generation을 수행한다. provider 목록은 동적 manifest를 사용한다. 현재 backend context에 알려진 AWS와 Papago를 하드코딩하거나 둘만 가정하지 않는다. API key를 프론트에 두지 않고 cache flush나 startup blocking을 추가하지 않는다. + +요청 상태 전이: + +```text +PREPARING -> READY_TO_GENERATE +PREPARING -> REVIEW_REQUIRED (series) +PREPARING -> FAILED | CANCELLED +REVIEW_REQUIRED -> READY_TO_GENERATE | CANCELLED +READY_TO_GENERATE -> GENERATING | CANCELLED +GENERATING -> READY | CANCELLED +READY -> APPLIED | CANCELLED +APPLIED, FAILED, CANCELLED are terminal +``` + +- 요청 생성 시 intent마다 UUID를 한 번 만든다. 생성 POST의 결과가 불확실하고 requestId도 받지 못했다면 같은 UUID와 원래 body로 재시도한다. requestId가 있으면 기존 요청 상태를 조회할 수 있다. UUID 검색이나 생성 receipt 조회 API를 새로 가정하지 않으며 UUID를 자동 교체하지 않는다. +- `PREPARING`은 요약 조회를 polling한다. 한 요청당 중복 polling은 금지한다. 1초 간격으로 겹치지 않게 실행하고 unmount, request 변경, terminal 상태에서 멈춘다. +- 단건은 `READY_TO_GENERATE`가 되면 명시적인 generate 버튼을 제공한다. 시리즈는 분석 그룹을 조회하고 관리자가 전체 구성을 확인·확정해야 한다. 모두 개별 처리로 분류한 경우도 review PUT이 필수다. +- 시리즈 grouping은 서버 분석을 그대로 검토·수정한다. 전체 활성 scope를 빠짐없이 한 번씩 그룹 또는 individual에 배치한다. 그룹은 최소 2명, 단일 source language이며 모든 멤버가 정확히 같은 원문 substring을 가져야 한다. +- 관리자는 그룹, 공통 구간, span을 조정하고 멤버를 individual로 제외하거나 요청을 취소할 수 있다. 고정 EP 정규식, 자체 regroup 알고리즘, 서버 분석을 대체하는 프론트 분석을 만들지 않는다. +- span은 Unicode code point 기준 0-based start inclusive/end exclusive다. JavaScript UTF-16 offset과 동일하다고 가정하지 않는다. 브라우저 선택 offset은 기존 변환 유틸 또는 지원 target의 `Intl.Segmenter` 등으로 grapheme 경계를 확인하며, emoji ZWJ와 combining mark를 시험한다. 임의의 오프셋을 제출하지 않는다. +- 그룹 편집이 저장되면 최신 revision을 쓴다. `GENERATING` 진입 후 편집은 금지이며, 변경하려면 취소 후 새 요청을 만든다. +- generate 호출이 불확실하면 같은 원래 `expectedRevision`과 body를 재전송한다. accepted replay는 최신 revision으로 새 요청처럼 바꾸지 않는다. 현재 새 mutation만 최신 revision을 쓴다. +- `GENERATING`은 요약과 필요한 후보 페이지를 polling하며 progress를 표시한다. READY 진입 시 이미 읽은 후보 페이지를 갱신하고 나머지는 필요에 따라 cursor로 읽는다. 모든 후보를 매초 전부 내려받지 않는다. 선택할 그룹의 모든 구성원과 필수 후보를 확보하기 전에는 그 그룹 적용을 허용하지 않는다. polling 중 generate를 다시 보내거나 READY 상태를 자동 적용하지 않는다. +- READY는 모두 성공했다는 뜻이 아니다. 모든 후보 실패 또는 빈 결과여도 READY일 수 있다. `emptyFields`는 paid candidate가 없는 명시 상태로 표시한다. +- 생성 이후 grouping 변경은 안 된다. 재검토가 필요하면 cancel 후 새 요청을 시작한다. + +## 5. 비교, 미리보기와 적용 + +- 콘텐츠 snapshot의 제목·상세·태그, source language, 기존 번역, 현재 활성/eligible 여부, source fingerprint 변경 가능성을 보여준다. snapshot 값과 조회 시점 current 값은 구별한다. +- 후보를 필드, 대상 언어, provider 단위로 비교한다. 원문, 현재 값, AWS/Papago 등 manifest에 포함된 provider 후보를 나란히 확인할 수 있게 한다. +- 기존 번역 출처는 실제 provenance가 없으면 `UNKNOWN`으로 표시한다. 기존 값을 provider에 귀속시키지 않는다. +- 동일 문자열 dedup은 같은 unit과 target language 안에서만 허용한다. 모든 provider ID/version provenance와 실제 selectable candidateId를 보존한다. 다른 unit/언어의 문자열은 합치지 않는다. +- 선택 가능한 것은 `SUCCEEDED` 후보뿐이다. pending, running, failed, discarded는 비활성화한다. 값이 같은 provider 결과를 묶어 보여도 선택되는 실제 candidate ID를 분명히 한다. +- `FIELD`는 콘텐츠·필드·언어마다 후보 하나를 고른다. grouped title을 FIELD로 우회해 apply하지 않는다. +- `GROUP_COMMON`은 group+language 단위 공통 후보 하나를 선택하고 모든 멤버 residual 선택을 완전하게 제공한다. 전부 literal인 멤버는 candidateId null을 사용한다. residual은 멤버마다 다른 provider를 선택할 수 있다. +- 그룹의 일부 멤버만 적용하는 선택은 불가하다. 일부만 분리하려면 generation 전 grouping에서 제외한다. +- candidate의 전체 `translatedValues` 배열을 타입에 맞춰 보존한다. 임의 boolean 조합 상태로 여러 unit 타입을 섞지 않는다. +- 그룹 제목 미리보기는 API `templates.segments`의 순서대로 이어 붙인다. LITERAL은 `sourceText`, SHARED는 선택 공통 후보의 `translatedValues[valueIndex]`, RESIDUAL은 해당 멤버 선택의 같은 인덱스를 쓴다. +- 미리보기에서 trim, 공백 삽입, 값 대체, 문자열 전체 replace를 하지 않는다. residual 구문 내부 공백을 유지한다. 모든 segments를 연결한 원문 재구성이 정확한지 확인한다. +- 후보 문자열은 HTML로 해석하지 않고 text로 출력한다. 긴 제목과 큰 body가 잘리지 않게 검토·비교할 수 있어야 한다. +- 자유 형식 번역 텍스트 편집은 만들지 않는다. 원문 그룹과 spans 편집은 제공한다. +- apply 전에 선택한 그룹의 전체 구성원과 미선택 필드·언어를 포함해 정확한 영향 범위를 확인시킨다. 그룹 내부의 일부 구성원만 미선택으로 두는 적용은 허용하지 않는다. 확인 화면에 다음 문구를 그대로 표시한다: `선택한 항목만 적용하고 이 요청을 종료합니다. 선택하지 않은 후보는 폐기되며, 해당 필드의 기존 번역은 유지됩니다.` +- apply는 one-shot이며 비어 있지 않은 selections만 보낸다. `operationId`는 사용자 확정 직전에 UUID로 만든다. 적용 결과가 불확실하면 requestId로 상태·applyReceipt를 조회하거나 원래 operationId·expectedRevision·선택 body 전체를 보존해 재전송한다. polling에서 새 revision을 받았다는 이유로 재시도 body를 바꾸지 않는다. 적용 결과가 불확실한 동안 선택 편집을 잠근다. +- 성공 후 receipt를 표시하고 request를 닫는다. 생략된 값은 기존 값을 유지한다. 서버가 부분 적용을 원자적으로 처리하며, 성공한 경우에만 해당 콘텐츠/시리즈 query cache를 무효화 또는 재조회한다. 낙관적으로 원본을 덮어쓰지 않는다. +- 적용 뒤 source 변경 시 해당 필드 보호 해제는 서버가 처리한다. 이를 프론트에서 미리 처리하지 않는다. + +## 6. 취소, 오류와 복구 + +- 미적용 상태와 READY에서 취소를 제공한다. APPLIED와 FAILED는 취소하지 않는다. +- 취소는 요청 취소 확정이지 이미 전송된 provider 비용의 환불이나 외부 요청 중단을 뜻하지 않는다. UI 닫힘을 서버 취소 성공으로 간주하지 않는다. +- 화면 이탈 시 기존 앱의 unsaved draft 경고 방식을 재사용한다. requestId를 URL에 보존해 기존 요청을 재개할 수 있게 한다. history list API나 서버 draft API를 새로 만들지 않는다. +- 새로고침 뒤 local 미제출 선택은 사라질 수 있음을 알린다. 기존 저장소 draft 방식이 있다면 재사용한다. +- 안정 오류는 개별 문구/복구에 매핑한다. + - `REVISION_CONFLICT`: 최신 request/grouping을 다시 읽고 사용자 편집을 조용히 덮지 않는다. + - `INVALID_GROUPING`, `INCOMPLETE_TITLE_GROUP`: 입력을 유지하고 수정 가능하게 표시한다. + - `SOURCE_CHANGED`, `MEMBERSHIP_CHANGED`: 이전 후보를 재사용하지 말고 새 요청을 안내한다. 기존 요청은 nonterminal이면 필요 시 취소한다. + - `REQUEST_NOT_READY`, `REQUEST_CLOSED`: 상태를 다시 읽는다. + - `CANDIDATE_NOT_SELECTABLE`, `IDEMPOTENCY_CONFLICT`: 잘못된 후보를 자동 대체하지 않고 원인과 재조회 방법을 알린다. + - `EMPTY_SCOPE`, `LANGUAGE_DETECTION_FAILED`, `UNSUPPORTED_SOURCE_LANGUAGE`, `PREPARATION_INTERRUPTED`: 요청 준비 실패를 분명히 표시한다. +- HTTP 404는 원인을 확정할 수 없다. route 미배포, 네트워크·프록시 경로 또는 base URL·요청 경로를 확인하도록 “API를 사용할 수 없음, 배포·연결 경로 확인 필요”로 표시한다. 기능 OFF 상태나 활성화 설정을 원인으로 안내하지 않는다. fake success/fallback을 만들지 않는다. +- 실제 서버가 없는 경우 fixture/mock은 테스트나 명시적 개발 모드에만 격리한다. production fallback으로 쓰거나 live integration PASS라고 주장하지 않는다. + +## 7. 검증 계획과 완료 기준 + +문서 `verification.md`를 코드 전에 만들고 아래 다섯 그룹의 예상 assertion을 실제 도구와 파일 경로에 연결한다. 구현 과정의 각 검증을 실행 즉시 기록한다. 기존 실패는 그대로 보고하며 테스트를 삭제·skip·약화하지 않는다. 기대값만 echo하는 mock 테스트는 근거가 아니다. + +1. Lifecycle, idempotency, polling, cancel + - 두 scope 생성, 상태 전이, 겹치지 않는 polling과 terminal/unmount stop, 동일 UUID/body 재시도, generate replay, 취소 경계를 검증한다. +2. Grouping, coverage, Unicode, preview + - scope 완전 분류, 그룹 최소 멤버, source language 동일성, exact shared spans, emoji ZWJ/combining boundary, literal/shared/residual 연결과 내부 공백을 검증한다. +3. Field/group selection, partial apply, provenance + - selectable 상태, 모든 residual 선택, 그룹 원자성, 일부 필드 적용, 미선택 보존 문구, 같은 결과 dedup 후 provenance/candidate ID 보존, UNKNOWN 출처를 검증한다. +4. Errors, races, unknown outcome, HTTP envelope + - revision conflict 후 refresh, source/membership 변경, incomplete grouping, HTTP 200 business failure, 네트워크 불확실 retry, apply 잠금, 404 API unavailable 상태를 검증한다. +5. 기존 UI 회귀, 접근성, 화면 크기 + - 상세/시리즈 기존 동작, role guard와 직접 라우트, keyboard/focus, text escaping, 긴 제목 및 큰 body, responsive layout을 검증한다. + +실제 저장소에서 확인한 focused test, lint, typecheck, build 명령만 실행한다. 무필터 전체 테스트와 범위 밖 전체 빌드는 프로젝트 규칙이 허용하지 않으면 실행하지 않는다. 테스트 fixture 검증은 `fixture`로 표기한다. 실제 API E2E는 안전하고 승인된 비운영 테스트 환경과 식별 가능한 fixture가 있을 때만 수행한다. 운영 예시 ID를 넣거나 유료/운영 mutation을 하지 않는다. 환경이 없으면 순수 UI와 unit 작업은 진행하고 실제 연동을 `BLOCKED` 또는 미검증으로 남긴다. + +UI가 변경되면 실제 구현 화면을 desktop과 mobile에서 열어 확인하고 스크린샷 경로를 기록한다. 빈 화면, 겹침, 잘림, 읽기 어려운 상태를 확인한다. 자동 테스트만으로 수동 화면 evidence를 대신하지 않는다. + +완료는 동작 구현, 다섯 문서 갱신, 실제로 실행한 focused 검증 기록, 실제 화면 검토 및 남은 제한 보고를 모두 충족해야 한다. API 미연동을 성공으로 표현하지 않는다. 보고에는 수정 파일, 정확한 명령과 결과, fixture 대 실제 API 구분, 미검증 환경, 남은 blocker와 스크린샷 경로를 포함한다. commit, deploy, 운영 변경은 별도 명시 승인 없이는 하지 않는다. + +## 8. 진행 원칙 + +- 먼저 문서와 조사를 완료한 뒤 계획의 첫 Goal을 시작한다. 반복 인터뷰는 저장소나 계약에서 답을 찾을 수 없는 핵심 결정에만 한정하고, 질문도 그 미지수만 묻는다. +- 완료한 Goal마다 계획, progress, verification을 같은 시점에 갱신한다. 증거가 없는 체크박스나 PASS는 남기지 않는다. +- 정확한 실제 파일, 명령, 결과만 기록한다. backend 역사적 검증을 frontend evidence로 복사하지 않는다. +- 이 프롬프트를 또 다른 구현 프롬프트로 바꾸지 않는다. bootstrap 문서를 만들고 그 계획에 따라 실제 frontend 기능을 구현한다. + +## 9. 화면별 acceptance criteria + +### 콘텐츠 상세와 시리즈 상세 + +- 두 상세 화면에는 기존 권한 및 버튼 패턴에 맞는 번역 후보 선택 진입점을 둔다. +- 콘텐츠 진입은 현재 콘텐츠 ID를 CONTENT scope로 전달한다. +- 시리즈 진입은 series ID를 SERIES scope로 전달한다. 개별 활성 멤버를 프론트에서 수집해 요청 대상을 축소하지 않는다. +- 하나의 공유 workflow를 열되, 현재 상세 화면의 context와 돌아갈 위치를 잃지 않는다. +- ADMIN이 아닌 사용자는 기능 버튼을 보지 못하고, URL을 직접 열어도 인증된 기존 접근 거부 흐름을 따른다. +- 요청 진행 중 같은 요청을 여러 번 생성하는 중복 click을 막는다. 생성의 unknown outcome에서는 기존 UUID를 보존한다. + +### 준비 및 grouping 검토 + +- `PREPARING` 화면은 준비 중임을 표시하고 서버 요약을 재조회한다. 비어 있는 snapshot을 완성 데이터처럼 보여주지 않는다. +- `FAILED`에는 API의 failure code를 사람이 이해할 수 있는 상태로 나타내고 재시작은 새 요청을 통해서만 한다. +- 시리즈 `REVIEW_REQUIRED`에서 모든 snapshot 멤버를 식별하고, 그룹/개별 배정이 전체 scope를 덮는지 사용자에게 보여준다. +- 그룹 멤버, 원문 제목, 공통 span, residual과 literal 분할을 검토할 수 있어야 한다. +- 편집은 원문 구간 선택에 한정한다. 번역문을 직접 편집하는 입력창은 두지 않는다. +- span을 제출하기 직전에 code point start/end, nonempty substring, grapheme 경계, 각 멤버의 substring 동등성을 확인한다. +- 저장 중에는 중복 PUT을 막고 저장 결과의 최신 revision을 사용한다. 충돌이면 서버 최신 grouping을 읽되 사용자 변경을 자동 폐기하지 않는다. +- 검토 완료 버튼은 전체 coverage가 유효할 때만 활성화한다. 모든 individual 구성도 서버에 review PUT을 보내야 한다. +- group과 개별 처리의 제외는 서버에 저장된 후에만 확정 표시한다. + +### 후보 생성 및 비교 + +- `READY_TO_GENERATE`에서는 시작 전 scope, 필드, source/target language, 동적 provider manifest를 간단히 요약한다. +- generate 전송 이후 버튼을 잠그고, progress `total`, `terminal`, `succeeded`, `failed`를 서버 응답 기준으로 표시한다. +- `GENERATING`과 READY 간 경합에서도 상태를 최신화한다. 늦게 도착한 이전 polling 응답이 새 상태를 덮지 않도록 request identity를 확인한다. +- cursor pagination은 반복 cursor 및 중복 응답에서도 ID 기준 병합으로 안정적이어야 한다. 페이지 로드 실패를 전체 결과 완료로 표시하지 않는다. +- 후보 실패는 다른 provider의 성공을 숨기거나 대체하지 않는다. provider/version과 실패 상태를 알 수 있는 곳에 둔다. +- 같은 텍스트 결과를 묶었을 때 선택은 정확한 성공 candidate ID 하나에 연결되어야 하며, 출처 표시는 모든 동등 candidate를 포함한다. +- `emptyFields`와 literal-only residual에는 후보 선택을 요구하지 않는다. 빈 후보를 성공 상태로 만들어 apply할 수 있게 하지 않는다. +- 후보 페이지를 다시 읽을 때 현재 선택 candidate가 더 이상 selectable이 아니면 선택을 해제하고 사용자에게 알린다. + +### 적용 확인, receipt와 종료 + +- 선택 누락, 중복, 다른 언어/단위의 후보 ID는 프론트에서 제출하지 않는다. 서버 검증을 대신한다고 가정하지도 않는다. +- grouped title 미리보기는 각 그룹 멤버의 template마다 개별적으로 재구성한다. 공통 결과 하나를 모든 전체 제목으로 대체하지 않는다. +- 적용 요약은 선택된 콘텐츠·필드·언어, 공통 그룹 전체 멤버, residual source, provider provenance를 구분한다. +- 미선택 필드가 유지됨과 선택하지 않은 후보가 폐기됨을 확인 단계에서 함께 알린다. +- 확인 취소는 API 호출을 보내지 않고, 확인 후에는 operation ID 및 canonical body를 고정해 한 번 전송한다. +- 적용 실패 시 서버가 실패를 반환하면 현재 request 상태와 선택을 유지할 수 있는지 계약에 따라 처리한다. 이미 적용된 receipt를 실패로 표시하지 않는다. +- apply 응답의 immutable receipt를 보여주고, 재조회 시에도 같은 결과를 표시한다. receipt의 applied fields와 provider source를 candidate 페이지가 바뀌어도 잃지 않는다. +- 성공 이후 영향받은 content 및 series 화면의 기존 query cache만 갱신한다. 실패나 unknown outcome에서 기존 데이터를 낙관적으로 변경하지 않는다. +- 취소 요청은 서버 응답 전까지 취소 완료로 표시하지 않는다. 취소 전에 전송 승인을 받은 provider 호출은 계속될 수 있고 이미 발생한 비용을 되돌리지 못함을 사용자에게 설명한다. + +## 10. 문서와 검증 기록 형식 + +`plan-task.md`에는 저장소가 지원하는 형식을 따르되 실제 이 구현을 재개할 수 있는 정보를 남긴다. + +- 상단에 현재 상태, 현재 활성 Goal, 다음 Goal을 기록한다. +- 각 Phase에는 결과와 선행 의존성을 기록한다. +- 각 Task에는 고유 ID, 목적, 시작 조건, 완료 증거, 범위 밖, 실제 파일 경로, 테스트 우선 절차와 focused 명령을 적는다. +- 테스트 가능한 작업은 실패하는 assertion부터 작성하고 실패를 확인한 후 최소 구현, 통과 확인과 회귀를 기록한다. +- 테스트가 불가능한 작업에는 구체적인 사유와 대체 증거를 적는다. +- 하나의 Task 또는 Gate Goal만 active로 둔다. 성공한 Goal은 즉시 체크하고 그 Goal의 검증 결과를 progress에도 남긴다. +- 전체 사용자 테스트를 실행하지 않았다면 결과처럼 기록하지 않는다. 프로젝트가 지정한 사용자 실행 명령과 범위를 구분해 둔다. + +`verification.md`의 초기 표에는 적어도 다음 열을 둔다. + +| 검증 대상 | 기대 assertion | 환경·fixture | 실제 명령 또는 수동 절차 | 상태 | 증거 | +|---|---|---|---|---|---| +| 문서 bootstrap | 다섯 문서와 실제 경로가 확인됨 | local repo | 확인 후 입력 | NOT_RUN | 경로 | +| API 준비도 | auth, base URL, route/schema 사전조건을 안전하게 확인 | read-only | 실제 확인 명령 | NOT_RUN 또는 BLOCKED | 결과 | +| lifecycle 및 retry | 상태·UUID·revision 불변 | fixture 또는 승인된 test API 명시 | focused test | NOT_RUN | 결과 파일 | +| grouping 및 Unicode | coverage, span, grapheme, preview 일치 | fixture 명시 | focused test | NOT_RUN | 결과 파일 | +| apply와 provenance | 부분 적용 및 source 보존 | fixture 또는 승인된 test API 명시 | focused test | NOT_RUN | 결과 파일 | +| 오류와 UI 회귀 | envelope, 오류, role, keyboard, layout | fixture/local UI | 실제 명령·화면 확인 | NOT_RUN | 결과 및 screenshot | +| live API 통합 | 실제 서버가 있다면 read-only/승인된 test scope에서 확인 | 환경 이름과 fixture | 정확한 요청 경로 | BLOCKED 또는 NOT_RUN | 결과 | + +표의 행을 모두 실제 환경에 맞게 구체화한다. 행 예시는 완료 증거가 아니다. `PASS`는 assertion 또는 수동 관찰 evidence가 있을 때만 쓴다. `FAIL`은 문제와 재현 절차를 남기고 수정 전 기록을 보존한다. `BLOCKED`에는 무엇이 없어서 막혔는지 쓴다. + +`progress.md`는 실행 가능한 재개 노트로 작성한다. + +- 승인된 범위와 현재 단계, 다음 단계, 활성 Goal을 먼저 보여준다. +- 확정 제품 결정과 API 계약 의존성을 간결하게 적는다. +- 완료 Goal별 실제 수정 파일과 검증 결과를 연결한다. +- 각 명령은 정확한 working directory와 결과/종료 상태를 기록한다. +- fixture 테스트와 live API 검증을 구분하고, 미실행 검증을 표시한다. +- 미해결 blocker, 가정, 사용자 질문과 답, 스크린샷 경로를 누적한다. +- requestId 기록이 필요한 경우 테스트 식별자만 쓰고 토큰, cookie, authorization header, API key, 개인정보를 기록하지 않는다. + +## 11. 구현 완료 보고 형식 + +작업 종료 시 사용자에게 결과를 한국어로 짧게 보고한다. 코드 완료와 문서 완료를 구분하고 아래 정보를 빠뜨리지 않는다. + +1. 구현된 동작과 주요 진입 경로. +2. 변경 파일 목록과 다섯 문서의 실제 위치. +3. 실제 실행한 focused test, lint, typecheck, build 명령 및 각 결과. +4. fixture/mock 검증과 실제 API 검증의 구분. 운영이 아닌 실제 서버 확인이 없으면 미검증으로 표시. +5. 화면 확인의 desktop/mobile 범위와 스크린샷 경로. +6. 남은 blocker, 환경 제약, 실제로 실행하지 않은 검증. + +미완료 항목을 완료로 포장하지 않는다. 전체 검증이 불가능하더라도 안전하게 분리 가능한 UI와 테스트 구현을 마치고, 미검증 범위를 명시한다. backend 과거 검증 숫자나 리뷰 승인 문구를 frontend 성공 증거로 재사용하지 않는다. diff --git a/docs/20261117_관리자번역후보선택/plan-task.md b/docs/20261117_관리자번역후보선택/plan-task.md new file mode 100644 index 00000000..b48d7967 --- /dev/null +++ b/docs/20261117_관리자번역후보선택/plan-task.md @@ -0,0 +1,1021 @@ +# 관리자 번역 후보 선택 — 구현 계획 + + + +> **상태: P1~P5 및 P7 로컬 구현·검증 완료.** 승인된 DEC-11에 따라 활성화 플래그를 제거했고, 사용자의 직접 마무리 지시에 따라 부모가 코드·검증 기록·문서를 대조하고 최신 bootJar를 빌드해 P7-GATE를 종결했다. Production DDL/deploy는 수행하지 않았다. 후속 사용자 요청에 따른 커밋 검증은 문서 하단에 기록한다. + +| 문서 항목 | 내용 | +|---|---| +| 작성일 | 2026-11-17 | +| 요구사항 기준 | [prd.md](prd.md) | +| API 기준 | [api-contract.md](api-contract.md), 승인·9개 endpoint 구현 및 로컬 검증 완료 | +| 현재 Phase | P1~P5 및 P7 완료, 운영 적용만 별도 | +| 현재 활성 Goal | 없음 — 요청한 로컬 변경 완료 | +| 구현 시작 조건 | 충족 — 설계 승인 및 구현 시작 승인 | + +## 목표 + +관리자가 모든 제공자의 새 후보를 검토해 선택한 일부 번역만 안전하게 적용하고, 다음 자동 번역이 변경되지 않은 승인 값을 덮어쓰지 않도록 한다. + +## 현재 상태 + +| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 | +|---:|---|---:|---|---| +| 1 | 완료 | 2/2 | `P1-GATE` 완료 | snapshot·grouping 검토 보정 및 focused 검증 완료 | +| 2 | 완료 | 2/2 | `P2-GATE` 완료 | 승인·무효화·완료 경합 보정 및 독립 검토 완료 | +| 3 | 완료 | 2/2 | `P3-GATE` 완료 | 68개 focused 테스트·lint·독립 검토 PASS | +| 4 | 완료 | 2/2 | `P4-GATE` 완료 | 독립 후보·실제 전송 취소·검토 PASS | +| 5 | 완료 | 2/2 + R1 | `P5-GATE` 완료 | 최종 통합 차단 1건 보정 후 APPROVE | +| 6 | 로컬 검증/배포 준비 완료 | 로컬 범위 완료 | 운영 단계만 대기 | 운영 MySQL·DDL·배포 미실행, 별도 활성화 단계는 DEC-11로 폐기 | +| 7 | 완료 | 1/1 | `P7-GATE` 완료 | 부모 직접 검토·배포용 JAR 빌드 완료 | + +한 번에 하나의 미완료 goal만 활성화한다. Future task status는 pending이며 체크박스는 완료 증거 전까지 미체크로 둔다. 모든 Goal ID, 테스트 class, 새 source path는 계획 항목이며 실제 구현이나 존재를 뜻하지 않는다. + +## 범위 + +### 포함 + +- `CONTENT` 단일 콘텐츠 및 `SERIES` 현재 연결된 활성 콘텐츠 전체의 title/detail/tags 후보 생성. 비활성 series member는 제외한다. +- 전체 현재 supported non-source languages(`ko`, `en`, `ja`)와 등록된 각 provider의 독립 fresh call. +- 실제 제목에서 자동 제안되는 공통 span의 서버 분석, 필수 사전 리뷰, 원문 span/group 편집, 개별 처리 제외. +- Candidate persistence, 취소/생성 fencing, 한 번의 subset apply와 receipt. +- Field-scoped approval provenance 및 CONTENT materialization/원본 변경과의 동시성 불변식. +- `/admin/audio-content/translation-requests` 하위 API만. Frontend는 interaction contract까지만이며 코드 없음. + +### 제외 + +- 자유 형식의 translated text 편집, 새 provider, LLM, cloud batch, global cache flush, startup wait. +- OriginalWork 동작, 다른 리소스의 read model writer 변경, 일반 job framework 추가, 광범위 scheduler 재작성. +- 레거시 번역 값의 provider provenance 추정 또는 일괄 복구. +- 같은 request에서 나눠 적용하는 multi-round partial apply; 한번 적용하면 request가 닫히고 미선택 후보는 폐기된다. +- 이 문서 작성 단계의 source/SQL/tests/API 호출 또는 어떤 구현 변경. + +## 기술적 제약 및 제안 + +- 기술: Kotlin, Java 17, Spring Boot 2.7.14, JPA, MySQL. 신규 기능 root는 `kr.co.vividnext.sodalive.v2.contenttranslation`이며 lightweight hexagonal `application/domain/port/adapter/dto` 구조를 따른다. +- 인증: 신규 API controller는 기존 ADMIN role과 `ApiResponse.ok` / `SodaException(messageKey, errorProperty)` convention을 사용한다. 신규 endpoint는 전부 PROPOSED다. +- Existing `TranslationProvider`, AWS/Papago provider, transport/client, detection cache, `RedissonClient`는 재사용한다. Provider coordinator의 first-success fallback, memory cache 및 `ensureMemory`는 candidate 생성 경로에서 사용하지 않는다. +- `ContentTranslation.renderedPayload` schema와 기존 API response는 유지한다. 세 신규 논리 테이블만 추가한다. 별도 `fieldStates` JSON/column은 추가하지 않는다. +- CONTENT approval provenance와 보호 상태는 `ContentTranslationOverride` row로 표현한다. 과거 승인 이력이 없는 source/automatic translation provider는 `UNKNOWN`으로 반환한다. +- Shared CONTENT source builder를 `TranslationSourceExtractor`와 `AudioContentDetailTranslationService`에서 재사용한다. title/detail/tags 원문, active tag 순서, 언어/fingerprint, provider inputs, 기존 memory hash가 일치해야 한다. 기존 normalized memory hash 계산은 변경하지 않는다. +- Approval fingerprint는 원본 언어, field key, 정확한 raw 값의 versioned length-framed SHA-256이다. tags는 순서가 보존된 raw string vector를 length-frame하여 comma collision을 막는다. +- 모든 ContentTranslation write는 Content 부모 lock 아래 field merge를 한다. Source mutation entrypoint도 수정 전 같은 lock을 얻는다. Lock 순서는 request → Series → CONTENT ID 오름차순 → locale read model/override다. Provider network I/O 중 DB transaction이나 CONTENT/Series lock을 보유하지 않는다. +- 동시 dispatch/cancel은 request 행 transaction gate로 linearize한다. Gate가 network chunk dispatch를 먼저 승인한 경우 그 외부 호출은 이미 진행 중/비용 발생 가능 호출로 본다. 취소 transaction commit 이후에는 추가 승인을 내지 않고, 뒤늦은 결과를 publish하지 않는다. +- Candidate worker는 새 feature 전용 persistent candidate rows, 짧은 atomic claim/lease/fencing transaction을 사용한다. Network call 사이에도 상태/fence/deadline을 확인한다. 60초 lease, chunk 전 갱신, stale fence publish 거부, crash 복구 최대 1회 제안. Exactly-once provider billing은 보장하지 않는다. +- Provider 호출 timeout은 기존 AWS SDK와 현재 Papago transport 설정을 조사해 API call 한도를 제한한다. 제안 기본값은 connect 3초, read 15초, AWS API call 15초다. Transport별 read timeout이 API total wall-clock 상한을 보장한다고 주장하지 않으며 SDK hidden retry가 발생하지 않는지 검증한다. 새 transport나 광범위한 client 변경을 도입하지 않는다. +- Current supported languages는 `TranslationLanguages`의 `ko`, `en`, `ja`. Request와 활성 membership을 먼저 저장한 뒤 동일 feature poller가 PREPARING을 claim한다. Existing source language가 유효하면 사용한다. 누락된 경우에만 기존 `LanguageDetectionCacheService.detectWithCache`를 사용하고 최종 field snapshot 저장 전 잠금 안에서 원문·언어·활성 membership을 재검증한다. 감지 실패·미지원 language·준비 중 source 변경은 명시적 preparation failure다. +- 제목 그룹은 source language별로 분석한다. Exact substring, Unicode grapheme 경계, code point offset, lossless segment template를 사용한다. 계산 알고리즘 상세는 아래 Goal의 기술 acceptance criteria이며 제품 인터뷰 결정으로 가장하지 않는다. +- 시각 컬럼은 MySQL `TIMESTAMP` 소수초 미지정, 초 단위로 제안한다. 각 상태 변경 시각은 한 번 초 정밀도로 normalize한 동일 값을 저장과 응답에 사용한다. 운영 DDL 작성 시 테이블/모든 컬럼에 COMMENT를 붙인다. SQL 실행은 이 계획에서 하지 않는다. +- Rollout (DEC-11): controller와 후보 worker는 설정 없이 기동 시 등록하고 일반 queue는 항상 source language 포함 identity를 사용한다. 신규 writer의 작업 생성 전에 세 신규 테이블과 언어 포함 unique index를 준비하고, 구 writer/in-flight 작업을 drain한 뒤 구 unique index를 제거한다. OFF 호환 모드·추가 활성화 단계·자동 DDL은 없다. 관리자 화면 미사용을 일반 enqueue 정지로 간주하지 않는다. +- Rollback은 첫 approval 이후 override-aware code version으로만 허용한다. Legacy writer는 override를 몰라 승인을 덮어쓸 수 있다. +- 구현 Task는 TDD RED → RED 확인 → GREEN → GREEN 확인 → REFACTOR 및 직접 회귀를 수행한다. Provider test는 latch 제어와 실제 local test transport를 사용해 cancel race를 확인한다. +- Agent 검증은 각 Goal의 focused `--tests`와 영향 범위 lint/bootJar만 수행한다. 무필터 전체 테스트는 실행하지 않는다. 사용자 전체 test 명령은 `./gradlew test`다. + +## 설계 제안 + +### 모듈과 responsibility + +```text +kr.co.vividnext.sodalive.v2.contenttranslation + application/ 요청 생성·리뷰·생성·취소·apply orchestration 및 트랜잭션 경계 + domain/ source snapshot, fingerprint, segment template, title grouping policy + port/ store와 provider call gate 같이 application이 소유하는 외부 경계 + adapter/ + in/web/ ADMIN controller와 API mapping + out/persistence/ entity, repository, atomic claim 및 locking query + scheduler/ feature 전용 candidate poller + dto/ API request/response DTO +``` + +새 generalized job abstraction은 만들지 않는다. Candidate row가 provider별 durable 작업 및 결과를 함께 표현한다. 기존 일반 `TranslationJobWorker`의 범위는 좁은 CONTENT 재료화 정합성 수정과 queue repair로 제한한다. + +### 세 신규 persistence table (제안) + +| 논리 테이블 및 unique rule | 필수 데이터 | +|---|---| +| `translation_selection_request`; unique `(created_by, client_request_id)` | ID; scope type/ID; creator admin ID; client request UUID와 canonical request body SHA-256; request state와 monotonic revision; source language 및 per-content/per-field raw source snapshot/fingerprint; immutable 활성 content membership ID 목록; target language set; provider ID/version manifest; proposed/reviewed groups와 lossless segment templates; accepted generate revision; preparation attempt count/lease expiry/fence; terminal preparation error code; apply operation UUID/body hash/JSON receipt; created/updated/applied timestamps. | +| `translation_candidate`; unique `(request_id, unit_key, provider_id, target_language)` | ID/request FK; deterministic unit key 및 unit kind/field/content/group; target language; provider ID/version; `PENDING/RUNNING/SUCCEEDED/FAILED/DISCARDED`; translated output의 JSON string array; sanitized stable error code; attempt count; lease expiry; monotonically increasing fence; created/updated/terminal timestamps. | +| `content_translation_override`; unique `(content_id, locale, field_key)` | ID; content ID; locale; `title/detail/tags` field key; exact source fingerprint; approved translated text; provenance request ID; contributing candidate ID list (title common+residual 포함); approvedBy admin ID; approvedAt timestamp. | + +Timestamp columns은 기존 BaseEntity conventions에 맞는 MySQL `TIMESTAMP` seconds precision으로 만들고 `created_at`/`updated_at` 기본값·COMMENT 기준을 따른다. Candidate의 request FK는 RESTRICT로 두고 운영 중 request hard delete는 제공하지 않는다. Override는 content ID와 후보 provenance를 보존하되 기존 content 삭제 동작을 바꾸는 cascade는 추가하지 않는다. 필수 lookup/claim index: creator+clientRequestId unique; request state+lease+id; candidate request+state+lease+id; request+unit+provider+target unique; content+locale+field unique. 인덱스는 필요한 claim/read query에 한정한다. + +`request.snapshot`/review manifest/receipt는 request row의 versioned JSON document다. Candidate output은 candidate row에 독립 JSON array로 저장한다. 새 migration artifact 작성 시 logical table과 모든 컬럼의 의미 및 DDL COMMENT를 넣는다. `ContentTranslation`에는 새 metadata column을 추가하지 않는다. + +### Request 및 candidate lifecycle + +`PREPARING → REVIEW_REQUIRED` (series) 또는 `READY_TO_GENERATE` (single) → `GENERATING → READY → APPLIED`; 모든 미종결 단계에서 `CANCELLED`; prepare 실패는 terminal `FAILED`. Series는 모든 개별 항목 분석이어도 리뷰가 필수다. Reviewed grouping은 generate 전 `READY_TO_GENERATE` 상태에서도 다시 제출·수정 가능하며 generate가 manifest를 freeze한다. Admin revision은 grouping/generation/apply 같은 의미 있는 write에서만 증가하고 worker progress polling은 증가시키지 않는다. Generation manifest와 candidate rows를 하나의 transaction에 동결한다. Provider terminal failure도 candidate 상태로 남기고 모든 candidate terminal 뒤 요청을 `READY`로 전이한다. + +Apply는 선택 항목이 하나 이상인 one-shot subset다. Request → 필요한 Series → CONTENT ID 오름차순 잠금 후 최신 source/membership/override/payload를 재조회하고 선택을 검증한다. 성공 시 전체 선택과 receipt를 함께 commit한다. 검증 거부는 아무 값도 쓰지 않고 request를 READY로 둔다. Request 잠금 안에서 저장된 operation ID/body hash 또는 accepted generate revision의 replay를 상태·revision 거부보다 먼저 판별한다. 새 mutation에만 현재 상태·revision 검증을 적용한다. 취소는 stale revision 검사를 요구하지 않으며 commit 뒤 새 dispatch 승인과 late publication을 금지한다. + +PREPARING도 같은 poller가 60초 lease와 fence로 처리한다. 요청 생성 시 고정한 활성 member IDs는 바꾸지 않고, 언어 감지 후 최신 원문을 잠금 안에서 재검증해 최종 snapshot을 한 번 게시한다. 준비 중 취소·source/membership 변경이면 게시하지 않는다. Lease 만료 복구는 한 번, 두 번째 만료는 FAILED/PREPARATION_INTERRUPTED다. Provider 호출이 아직 lease를 소유하는지 chunk 직전에 검사하며, 만료된 fence가 스스로 lease를 연장하지 못한다. + +### Title grouping 및 lossless reconstruction 제안 + +- 입력은 요청 생성 시 연결된 활성 series content 전체의 원본 title을 content ID 순으로 사용한다. 비활성 콘텐츠는 제외한다. +- source language별 partition 내에서 정확히 반복되는 maximal substring 후보를 탐색한다. Unicode grapheme boundary만 후보 경계로 허용하고 API offset은 zero-based code point, end-exclusive다. +- Auto proposal은 서로 다른 두 title 이상에 exact-identical하게 존재하는 span 중 lexical boundary에 맞고 Unicode letter 2개 이상 포함인 범위로 제한한다. 숫자/구두점 전용 반복은 자동 그룹하지 않는다. +- 원본 grapheme 열의 pairwise longest-common-substring scan으로 maximal exact runs를 구한다. 동일 source-language의 전체 제목으로 각 후보를 확장하며 한 제목에서 여러 번 나오는 모호한 구간은 자동 선택하지 않는다. `spanLength × (memberCount − 1)` 내림차순, 길이 내림차순, 원문 code-point 사전순, member ID 순으로 정렬한다. 각 제목은 한 그룹에만 배정하고, 모든 member에서 겹치지 않는 추가 공통 구간만 허용한다. 모호한 제목은 individual로 남기며 새 library/LLM/EP regex는 사용하지 않는다. +- 최종 grouping은 group들+individuals가 request scope를 정확히 한 번씩 덮어야 한다. Group member는 2개 이상이고 한 source language여야 한다. 관리자가 group, 원문 spans, 개별 제외를 generation 전에 수정한다. 변경을 generation 후 반영하려면 cancel 후 새 request를 생성한다. +- Client는 각 member의 span offset을 보내지만 원문 text replacement는 보낼 수 없다. Server는 현재 snapshotted source에서 raw substring을 추출하고 모든 group member에서 동일한 문자열인지 확인한다. 겹침, 격자 boundary 분할, 누락/중복 coverage, 언어 혼합은 거부한다. +- 각 title을 `LITERAL | SHARED(part) | RESIDUAL(id)` 순서로 분할한다. 모든 source code point는 정확히 한 번만 소유되고, segment source를 concat한 값은 원문과 완전히 같아야 한다. 문자가 없는 gap은 원문 literal로 보존한다. 문자가 있는 gap은 바깥쪽 공백·구두점만 literal로 분리하고 내부 공백·구두점·숫자를 포함한 나머지 구문 전체를 하나의 RESIDUAL로 유지한다. 내부 단어마다 번역 입력을 나누지 않는다. 각 segment 유형/ID를 reviewed template에 저장한다. +- 공통 parts는 group+targetLanguage마다 하나의 provider candidate string array로 번역한다. Residual은 member 단위 string array이며 같은 request/provider/language 안에서 동일한 residual source를 deduplicate할 수 있다. 이전 memory는 읽지 않는다. 선택 후보를 같은 segment 순서로 조립하고 literal을 그대로 붙인다. +- Group+language apply는 공통 후보 1개와 모든 member residual 선택을 요구한다. 공통 provider는 그룹 전체에서 동일하고 각 구성원 residual provider는 달라도 된다. Candidate 전체를 멤버별로 따로 선택하는 기능은 없다. 개별 결과가 필요하면 generation 전에 group에서 제외하거나 새 grouping을 저장한다. +- 이 보수적 제안은 최대 반복 span을 제시할 뿐 문장 자연성을 보장하지 않는다. 관리자 전체 preview 검토 후 적용한다. + +### CONTENT source snapshot 및 override invariant + +| Source/entry point | 제안된 integration | +|---|---| +| `i18n/translation/TranslationSourceExtractor.kt` | Shared CONTENT snapshot builder를 소비하도록 CONTENT source 조립을 위임한다. Other resource extractor 변경은 하지 않는다. | +| `content/AudioContentDetailTranslationService.kt` | 자체 tags/field/detection query 조립 제거 후 shared builder 사용. Existing payload shortcut 전에 stale override를 검사한다. | +| `i18n/translation/TranslationReadModelMaterializer.kt` | CONTENT 경로만 CONTENT parent lock을 먼저 잡고 최신 source, locale payload, override를 재조회해 field merge한다. 다른 resource upsert는 불변이다. | +| `content/AudioContentService.kt` | modify title/detail/tags source mutation에서 lock 후 field change comparison/invalidation, source fallback, normal refresh scheduling. | +| `admin/content/AdminContentService.kt` | 관리자 title/detail mutation에 같은 hook. | +| `creator/admin/content/CreatorAdminContentService.kt` | creator/admin title/detail/tags mutation에 같은 hook. Delegating AI admin route는 해당 경로를 검증한다. | +| `creator/admin/content/series/CreatorAdminContentSeriesService.kt` | Membership add/remove는 Series parent lock 아래 수행해 title-group apply와 membership snapshot 검증이 직렬화된다. Order-only 변경은 membership set 변경이 아니다. | +| `content/LanguageDetectEvent.kt` 및 detection path | CONTENT source language가 미설정인 경우에만 기존 detector를 사용. 잠금 후 최신 query/language를 재검증하고 language change는 모든 override field를 invalidate. | +| `i18n/translation/TranslationJobScheduler.kt` | source language를 queue key/lookup identity에 추가. 완료 CONTENT field도 실제 현재 value stale/missing일 때만 해당 field repair 허용. | +| `i18n/translation/TranslationJobWorker.kt` | `materialize(false)`를 successful completion으로 기록하지 않고 retryable/incomplete로 취급. | + +Exact source fingerprint는 `sourceLanguage + fieldKey + exact raw field`; tags의 ordered raw vector length-frame이다. 기존 memory hash/normalizer는 유지한다. Source mutation은 모든 해당 locale의 오직 변경 field override를 제거하고 rendered field를 최신 source fallback으로 설정한 뒤 자동 refresh를 같은 transaction에서 enqueue한다. Language change는 title/detail/tags를 모두 변경으로 취급한다. 변경되지 않은 field approval은 보호된다. A→B→A 변경에서 이미 제거한 approval은 복구되지 않는다. + +Normal materializer는 lock 전에 memory를 resolve해도 좋지만 captured fingerprint를 lock 안에서 재검증한다. 현재 source와 일치하는 latest approval이 memory result보다 우선한다. 변경 field만 override invalidate/refresh한다. Detail read shortcut은 승인 fingerprint를 확인하고 stale approval을 반환하지 않는다. 동기 source mutation 시 payload fallback으로 reset하므로 direct list readers도 이전 값을 노출하지 않는다. + +유효한 override가 있는 필드는 translation memory가 없어도 승인 값으로 완성할 수 있어야 한다. 기존 resolveTranslatedFields가 모든 memory를 먼저 요구해 조기 실패하는 순서를 CONTENT에 그대로 사용하지 않는다. 승인 확인·source 재검증 후 승인 없는 필드만 memory 필요 여부를 판정한다. 후보/관리자 승인이 global memory를 채우지 않는 설계에서도 동작해야 한다. + +Group apply는 request lock → Series lock → 현재 연결 CONTENT locks ID 오름차순으로 가져온 뒤 활성 membership을 snapshot과 비교한다. 활성 상태 변경도 CONTENT lock으로 직렬화한다. Individual field는 선택된 content의 활성·연결 자격과 그 필드 fingerprint만 검사하며 무관한 필드 변경이나 다른 member의 추가는 적용을 막지 않는다. 잠금 전 관리 entity/association을 그대로 재사용하지 않는다. Concurrent explicit approvals은 같은 source에서 later committed approval wins이며 automatic writer는 valid approval을 덮어쓰지 않는다. + +### Provider cancellation 및 durability + +- 모든 등록 `TranslationProvider`를 직접 호출한다. `TranslationCoordinator` first-success fallback/translation memory는 금지한다. Provider ID/version은 manifest/candidate에 고정하고 실행 시 동일성을 검사한다. 누락 또는 version 변경은 FAILED/PROVIDER_CHANGED로 종결하며 다른 버전·provider로 대체하지 않는다. 출력 개수와 공백 검증 실패는 FAILED/INVALID_PROVIDER_RESULT다. +- Candidate worker는 feature 전용 poller와 durable candidate status를 사용한다. Existing `translation_job`에 request/provider candidate workflow를 억지로 합치지 않는다. Existing provider clients, endpoints, SDKs, parsing을 재사용한다. +- `TranslateRequest`에 선택적인 admin call control 계약을 더해 provider adapter의 **각 outbound chunk 직전** dispatch gate를 요구한다. Gate 승인은 요청 state/revision, lease 및 fence를 짧은 DB transaction으로 확인한다. 승인된 호출은 취소와 경쟁 시 in-flight로 간주한다. HTTP/network I/O 동안 transaction이나 parent content lock은 없다. +- Cancel transaction은 request 상태를 CANCELLED로 바꾸고 outstanding lease/token을 폐기한다. 취소 commit 뒤 새 chunk 승인은 거부한다. 취소 전에 승인된 chunk는 실제 전송이 취소 뒤여도 이미 진행 중인 작업에 포함한다. 취소 응답은 network 완료를 기다리지 않으며 late publication은 request/candidate/fence 재검증으로 거부한다. +- Worker claim은 atomic row lock/claim, 60초 lease, chunk 전 renew, fence token, 한 번의 expired lease recovery를 쓴다. 그 이상 exhausted candidate를 실패 종결한다. 재시작 후 이미 provider에 도달한 요청이 반복돼 비용이 다시 발생할 수 있음을 운영 문서와 API cancellation semantics에서 밝힌다. +- 기존 RedissonClient와 `lock:translation-selection` scheduler-wide lock을 사용한다. Redis dependency와 현재 ordinary TranslationJobWorker의 broad lock refactor를 추가하지 않는다. Persistent DB claim이 실제 소유권·fencing source다. +- Detection 중 cancel은 추가 translation dispatch를 막는다. 기존 detection cache를 허용하고 supported source language를 다시 무조건 감지하지 않는다. Source detect network call의 bounded/cancelable call path도 검증한다. + +## Phase 1: 공유 snapshot과 grouping domain + +**Phase 결과:** 기존 CONTENT source 조립과 feature source fingerprint가 일치하며 검토 전 제목 grouping 제안을 lossless template으로 만든다. + +**선행조건:** 충족. PRD/API/design proposal 및 로컬 구현/focused tests 승인. + +### Task 1.1 — 공유 CONTENT snapshot 경계 + +**Goal 실행 `P1-T1`:** 모든 CONTENT translation consumer가 같은 source fields/tags order를 사용한다. + +- **시작 조건:** 승인된 API design와 현재 extractor/detail 경로. +- **완료 증거:** 정확한 raw fingerprint 및 provider input 테스트, extractor와 detail source assembly 동일성 통과. +- **범위 밖:** Non-CONTENT extractor, existing memory normalization/hash 변화. + +**Files:** +- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/domain/ContentSourceSnapshot.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/ContentTranslationSourceService.kt`. +- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationSourceExtractor.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentDetailTranslationService.kt`. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/domain/ContentSourceSnapshotTest.kt`. + +**Interfaces:** consumes AudioContent/active hashtags and supported language rules; produces immutable source snapshot, provider inputs, raw field fingerprints, existing memory-hash inputs. + +- [x] **RED:** raw tags ordering/fingerprint collision and extractor/detail parity tests를 작성한다. +- [x] **RED 확인:** HTTP 태그 순서 assertion RED 및 도메인 tag-vector 경계 변이 assertion RED를 확인했다. 상세 명령은 Progress에 기록했다. +- [x] **GREEN:** CONTENT snapshot/fingerprint 조립을 공유하고 기존 normalized memory hash를 보존한다. +- [x] **GREEN 확인:** snapshot 14개와 상세 HTTP 22개 테스트 통과. +- [x] **REFACTOR:** 초기 ktlintCheck 통과, 독립 검토에서 발견한 pending 태그 순서를 RED/GREEN으로 보정했고 제한 재검토에서 ADDRESSED 판정을 받았다. + +### Task 1.2 — 반복 span 분석 및 lossless title template + +**Goal 실행 `P1-T2`:** 실제 제목의 보수적 반복 공유 span과 원문 재구성 template을 결정적으로 계산한다. + +- **시작 조건:** `P1-T1` snapshot/type contract 완료. +- **완료 증거:** Unicode/title edge cases와 complete coverage invariant 검증. +- **범위 밖:** LLM, 새 dependency, EP regex, translation 자연성 자동 평가. + +**Files:** +- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/domain/TitleGroupingAnalyzer.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/domain/TranslationSelection.kt`. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/domain/TitleGroupingAnalyzerTest.kt`. + +**Interfaces:** consumes content IDs, source language, raw title; produces deterministic proposed group, exact part ranges and `LITERAL/SHARED/RESIDUAL` segment source template. + +- [x] **RED:** 반복 구간·모호성·언어 분리·Unicode·검토 범위·재구성 행동 테스트를 작성했다. +- [x] **RED 확인:** `TitleGroupingAnalyzerTest` 21개 assertion RED를 확인했다. +- [x] **GREEN:** exact substring, Unicode grapheme boundary, deterministic conservative group assignment 및 lossless reconstruction 구현. +- [x] **GREEN 확인:** grouping 21개 + snapshot 14개 통과. +- [x] **REFACTOR:** ktlintCheck 통과, residual 구문 분할 finding을 RED/GREEN으로 보정하고 독립 재검토에서 ADDRESSED. 실제 대규모 scope 성능은 운영 검증 대상이다. + +### Phase 1 Gate — `P1-GATE` + +**완료 증거:** 같은 CONTENT source에 대해 extractor/detail/fingerprint가 일치하고 모든 title template은 원문 전체를 정확히 재생성한다. no build/DB/provider behavior claimed beyond focused evidence. + +## Phase 2: field approval과 CONTENT writer 통합 + +**Phase 결과:** 승인 값이 원본이 그대로인 동안 자동 materializer로부터 보호되고, 원본 변경 시 해당 field만 무효화된다. + +**선행조건:** `P1-GATE` 완료, `ContentTranslationOverride` persistence contract 및 MySQL schema approved. + +### Task 2.1 — Override 저장과 locked field writer + +**Goal 실행 `P2-T1`:** administrator selection과 normal CONTENT materializer가 같은 부모 lock 아래 field-scoped override를 적용한다. + +- **시작 조건:** approved 3-table schema; PRD TR-18~TR-20. +- **완료 증거:** approve, automatic materialize race, source validation 및 unchanged payload tests 통과. +- **범위 밖:** ContentTranslation JSON/schema 변경, non-CONTENT writers. + +**Files:** +- Create: `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/domain/ContentTranslationOverride.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/port/ContentTranslationOverrideStore.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/out/persistence/ContentTranslationOverrideEntity.kt`, corresponding repository/store adapter, `application/ContentTranslationWriteService.kt`. +- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationReadModelMaterializer.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/content/translation/ContentTranslationRepository.kt` only if locked query needed. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/ContentTranslationOverrideIntegrationTest.kt`. + +**Interfaces:** consumes exact source snapshot, automatic translated field values or approved candidate+provenance; produces locked merged payload and field-scoped override update. + +- [x] **RED:** `shouldProtectCurrentApprovalFromAutomaticWrite`, `shouldMaterializeApprovedFieldsWithoutSharedMemory`, `shouldRejectAutomaticResultWithStaleSource`, `shouldKeepUnselectedFieldsByteForByte`, `shouldPersistApprovalProvenance` tests를 작성한다. +- [x] **RED 확인:** `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationOverrideIntegrationTest'`에서 오래된 managed source로 materialize가 true를 반환하는 assertion 실패 확인. +- [x] **GREEN:** CONTENT-only writer obtains parent lock before current source/override/payload reads and merges only touched fields; other resource materializers unchanged. +- [x] **GREEN 확인:** 위 신규 class 9개 + `ContentTagTranslationIntegrationTest` 11개 통과. lint 마무리는 P2-T2와 함께 기록한다. +- [x] **REFACTOR:** CONTENT의 기존 late-lock upsert를 공용 field writer로 대체하고 불필요한 생성자 의존성을 제거했다. 신규 코드와 테스트는 각각 200 pure LOC 이내이며 직접 회귀와 최종 ktlintCheck 통과. 아래 Progress 참조. + +### Task 2.2 — Source mutation invalidation 및 queue repair + +**Goal 실행 `P2-T2`:** 모든 관련 source 변경이 changed-field approvals만 지우고 fallback/automatic refresh로 바꾼다. + +- **시작 조건:** `P2-T1` locked writer 사용 가능. +- **완료 증거:** content owner, ADMIN, creator-admin mutations, membership add/remove, missing-language event, detail shortcut, queue dedup 회귀 통과. +- **범위 밖:** global queue rewrite, 다른 도메인 번역 정책 변경. 공유 queue의 언어 포함 identity 전환은 기계적인 변경으로 제한하고 비-CONTENT 회귀를 검증한다. + +**Files:** +- Modify: `content/AudioContentService.kt`, `admin/content/AdminContentService.kt`, `creator/admin/content/CreatorAdminContentService.kt`, `creator/admin/content/series/CreatorAdminContentSeriesService.kt`, `content/LanguageDetectEvent.kt`, `content/AudioContentDetailTranslationService.kt`, `i18n/translation/TranslationJob.kt`, `i18n/translation/TranslationJobRepository.kt`, `i18n/translation/TranslationJobScheduler.kt`, `i18n/translation/TranslationJobWorker.kt`, `i18n/translation/ResourceTranslationJobScheduler.kt`. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/ContentTranslationSourceInvalidationIntegrationTest.kt`; direct source service/controller existing affected tests to add after verifying exact class names. + +**Interfaces:** mutation hooks consume before/after locked snapshots, enqueue standard refresh; worker consumes `materialize(false)` as incomplete rather than completed. + +- [x] **RED:** 신규 SourceInvalidation 13개, Queue 6개, Membership 7개 테스트로 필드 fallback/다른 승인 보존/A→B→A/언어 변경/상세 shortcut/완료 작업 재개/언어 identity/혼합 flag 및 활성·membership 잠금을 검증한다. +- [x] **RED 확인:** 세 mutation entrypoint 모두 이전 승인 제목을 반환하는 assertion 실패를 먼저 확인했다. 감지 provider 호출 중 transaction 존재 assertion 실패 및 worker false/승인 우선순위 변이 RED도 별도로 확인했다. +- [x] **GREEN:** 세 mutation entrypoint와 감지·상세 경로에 같은 부모 잠금/필드 무효화/fallback/enqueue를 연결하고 queue identity와 호환 exists를 적용했다. materialize false는 재시도한다. +- [x] **GREEN 확인:** 신규 36개와 AudioContentDetail HTTP 22개, AudioContentService 16개, AdminContentService 6개, worker 13개, ContentTag 11개, scheduler 3개, retry 10개가 최종 focused 실행에서 통과했다. 추가 직접 회귀 140개도 별도 focused 실행에서 통과했다. +- [x] **REFACTOR:** 모든 변경 locale payload의 해당 필드만 같은 mutation transaction에서 fallback으로 바꾼다. 기존 broad translation event 대신 changed fields만 직접 enqueue하며 새 public HTTP/API/payload metadata는 추가하지 않았다. 최종 ktlintCheck 통과. + +### Phase 2 Gate — `P2-GATE` + +검증해야 할 race: concurrent approval vs automatic writer, source update vs detail read, all three source mutation paths, AI admin delegation, `materialize(false)` and source language queue identity. H2 tests는 production MySQL locking 증거로 간주하지 않는다. + +## Phase 3: durable request lifecycle과 reviewed grouping API + +**Phase 결과:** 관리자 scope request가 안전하게 준비되고 시리즈 grouping을 반드시 리뷰·확정하기 전에는 provider call이 시작되지 않는다. + +**선행조건:** `P1-GATE`, schema DDL 승인, ADMIN/API envelope review. + +### Task 3.1 — Request persistence, preparation, idempotency + +**Goal 실행 `P3-T1`:** request snapshot과 scope idempotency가 durable하게 저장되고 source language preparation race가 안전하다. + +- **시작 조건:** `P2-GATE`; 세-table schema와 rollout design 검토 완료. 당시 OFF 호환 정책은 후속 DEC-11로 대체됐다. +- **완료 증거:** duplicate/mismatch idempotency, all-member snapshot, language detect/cancel, unsupported language tests. +- **범위 밖:** candidate provider network calls. + +**Files:** +- Create under `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/`: request/domain state; `application/TranslationSelectionRequestService.kt`, `application/ContentTranslationSourceService.kt`; `port/TranslationSelectionStore.kt`; `adapter/out/persistence/TranslationSelectionRequestEntity.kt`, repository/store adapter. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/TranslationSelectionRequestIntegrationTest.kt`. + +**Interfaces:** consumes ADMIN id, scope union, client UUID; produces request ID/status/revision and frozen source/member snapshot or terminal preparation failure. + +- [ ] **RED:** `shouldReplaySameCreationBody`, `shouldRejectReusedClientIdWithDifferentBody`, `shouldSnapshotOnlyActiveLinkedMembers`, `shouldUseValidSourceLanguageWithoutRedetection`, `shouldDetectMissingLanguageBeforeFinalSnapshot`, `shouldFailUnsupportedOrUndetectedLanguage`, `shouldRecoverPreparationOnceThenFail`, `shouldNotPublishPreparedSnapshotAfterCancelOrSourceChange` tests. +- [ ] **RED 확인:** focused class command에서 expectation failure 확인. +- [ ] **GREEN:** snapshot, idempotency unique handling, final source recheck, existing cache-backed detector 재사용 구현. +- [ ] **GREEN 확인:** `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionRequestIntegrationTest'` 통과. +- [ ] **REFACTOR:** no retry layer/new detector cache. Record duplicate collision and preparation failure API mapping. + +### Task 3.2 — Grouping review and API read model + +**Goal 실행 `P3-T2`:** series manager가 lossless proposed groups를 수정하고 완전한 전체 grouping을 확정한다. + +- **시작 조건:** `P3-T1`, `TitleGroupingAnalyzer` approved model. +- **완료 증거:** ADMIN guard, member coverage/language/span validation, expectedRevision conflict tests. +- **범위 밖:** frontend code, post-generation edits. + +**Files:** +- Create: `application/TranslationSelectionGroupingService.kt`, `adapter/in/web/AdminTranslationSelectionController.kt`, `dto/TranslationSelectionRequest.kt`, `dto/TranslationSelectionResponse.kt`. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/in/web/AdminTranslationSelectionHttpIntegrationTest.kt`. + +- [ ] **RED:** `shouldRequireAdminRole`, `shouldRejectIncompleteOrDuplicateScopeCoverage`, `shouldRejectDifferentSharedTextOrSplitGrapheme`, `shouldAcceptAllIndividualReview`, `shouldRequireReviewBeforeGenerate` tests를 작성한다. +- [ ] **RED 확인:** `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionHttpIntegrationTest'`에서 assertion failure 확인. +- [ ] **GREEN:** POST, GET, contents paging, grouping GET/PUT의 typed endpoint 제안 구현. 모든 신규 endpoint는 ADMIN role, ApiResponse/SodaException pattern 사용. +- [ ] **GREEN 확인:** 같은 focused HTTP test, 기존 admin controller security tests 및 `./gradlew ktlintCheck` 실행. +- [ ] **REFACTOR:** request types/validation only in feature package, no general framework. + +### Phase 3 Gate — `P3-GATE` + +검증: preparation 취소 이후 새 translation dispatch 승인이 없음, 활성 연결 콘텐츠 전체 포함 및 비활성 제외, invalid/deleted scope를 대체하지 않음, all-individual 결과에도 group review 필수. + +## Phase 4: per-provider candidate generation, leases, cancel gate + +**Phase 결과:** 모든 provider가 fresh independent candidate를 남기며 failures visible, cancel gate 이후 dispatch/late publication 불가. + +**선행조건:** `P3-GATE`, translation provider cancellation boundary review. + +### Task 4.1 — Candidate persistence, generation manifest, worker + +**Goal 실행 `P4-T1`:** immutable generation manifest에서 unit×provider candidate rows가 durable하고 bounded recovery로 완료된다. + +- **시작 조건:** Request API+schema ready. +- **완료 증거:** no memory reuse, every provider attempted, duplicate generate, partial provider error, lease/fence tests. +- **범위 밖:** apply and CONTENT overrides (Phase 5). + +**Files:** +- Create: `domain/TranslationCandidate.kt`, `application/TranslationSelectionGenerationService.kt`, `application/TranslationSelectionWorkerService.kt`, `adapter/out/persistence/TranslationCandidateEntity.kt`, `adapter/scheduler/TranslationSelectionWorker.kt`. +- Modify only if necessary: `i18n/translation/TranslationProvider.kt` or a feature adapter interface, plus required settings registration. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/TranslationSelectionWorkerIntegrationTest.kt`. + +**Interfaces:** `POST generate(expectedRevision)` atomically freezes all fields/languages/providers/groups and creates provider candidate tasks; worker claims one task, runs exactly one selected provider and persists candidate if its fence remains valid. + +- [x] **RED:** `shouldAttemptEveryRegisteredProviderDespiteMemory`, `shouldIsolateProviderFailures`, `shouldGenerateAllFieldsAndNonSourceSupportedLanguages`, `shouldReplayGenerateWithoutCreatingJobs`, `shouldRecoverLeaseAtMostOnce`, `shouldRejectStaleFencePublish`, `shouldReachReadyAfterTerminalProviderFailures` tests. +- [x] **RED 확인:** 실제 generate HTTP 404, worker 미처리 및 residual 중복 호출 assertion 실패를 확인했다. 실제 테스트 이름과 실행은 Progress에 기록했다. +- [x] **GREEN:** Direct provider calls without TranslationCoordinator/cache; typed terminal candidate results and durable bounded claim/fence. +- [x] **GREEN 확인:** worker 및 candidate lifecycle/lease/grouping focused 검증 통과. 아래 실행 기록 참조. +- [x] **REFACTOR:** worker-specific polling only; candidate claim query and Redisson scheduler lock `lock:translation-selection` match project lock rules. + +### Task 4.2 — Outbound cancellation gate and bounded provider calls + +**Goal 실행 `P4-T2`:** 매 outbound chunk authorization이 cancel과 선형화되고 늦은 결과는 publish되지 않는다. + +- **시작 조건:** `P4-T1` provider candidate run contract. +- **완료 증거:** first chunk in-flight / later chunk denied race, bounded timeout, failure/cancel distinction tests. +- **범위 밖:** transport migration, broad AWS/Papago cleanup, external exactly-once guarantee. + +**Files:** +- Modify only targeted: `i18n/translation/TranslateRequest.kt`, `AwsTranslationService.kt`, `PapagoTranslationService.kt`, `content/LanguageDetectionCacheService.kt` / existing provider adapters, feature request store/worker. +- Test additions after source inspection: existing AWS/Papago provider test files; new `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/TranslationSelectionCancelIntegrationTest.kt`. + +- [x] **RED:** `shouldStopBeforeNextProviderChunkAfterCancel`, `shouldAllowAlreadyAuthorizedCallToFinish`, `shouldRejectLateCompletionAfterCancel`, `shouldDistinguishCancellationFromProviderFailure`, `shouldStopTranslationAfterCancelDuringDetection`, `shouldRespectOutboundCallBound` tests. +- [x] **RED 확인:** 후보 미폐기, 실제 SDK retry 및 Papago 다음 HTTP chunk 미차단 assertion 실패를 확인했다. +- [x] **GREEN:** 각 outbound chunk/retry의 dispatch gate, Papago admin connect 3초/read 15초 및 AWS 요청별 API-call/attempt 예산 15초 구현. SDK가 지원하지 않는 요청별 socket 설정은 아래 기술 판정에 명시했다. +- [x] **GREEN 확인:** cancel/worker/실제 SDK·HTTP 전송 14개 최종 통과, 기존 AWS/Papago/provider 설정 직접 회귀 포함. 아래 명령과 결과 참조. +- [x] **REFACTOR:** network IO outside DB transaction; do not leak raw provider exception/body; document at-least-once billing risk. + +### Phase 4 Gate — `P4-GATE` + +**Gate checks:** 현재 AWS tags unchanged-result 정책은 해당 후보 실패로 표시하되 Papago 독립 호출을 막지 않음; candidate는 translation memory 불변; 기존 감지 캐시 허용·번역은 fresh; 취소 commit 이후 새 dispatch 승인 및 stale publication 금지. 이미 승인된 호출의 전송/비용은 취소가 되돌리지 않음. + +## Phase 5: atomic subset apply and server contract + +**Phase 결과:** source-current selections commit together once, title group applies all members atomically, receipt makes retries idempotent. + +**선행조건:** `P2-GATE`, `P4-GATE`. + +### Task 5.1 — Selection validation, receipt, CONTENT override apply + +**Goal 실행 `P5-T1`:** administrator can apply one valid nonempty subset once while omitted translations stay unchanged and excluded candidates discard. + +- **시작 조건:** override-aware writer and complete candidate results. +- **완료 증거:** partial, stale field, unrelated source change, group membership, full transaction rollback, replay tests. +- **범위 밖:** multiple apply rounds, freeform values, applying selected fields from another request. + +**Files:** +- Create: `application/TranslationSelectionApplyService.kt`, `domain/TranslationSelectionReceipt.kt` (or keep types inline if single use). +- Modify: request store/service, candidate repository, `ContentTranslationWriteService.kt`, ADMIN controller/DTO. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/TranslationSelectionApplyIntegrationTest.kt`. + +- [x] **RED:** 부분 적용·그룹 완전성·source/ownership·replay·rollback의 실제 DB/HTTP 테스트를 작성했다. +- [x] **RED 확인:** apply HTTP 404와 provider/source 검증 변이 assertion 실패를 확인했다. P5-R1 연결 회귀 RED도 별도 기록했다. +- [x] **GREEN:** request/Series/CONTENT 잠금 이후 선택을 검증하고 override/payload/receipt/discard를 원자 적용했다. +- [x] **GREEN 확인:** P5 및 직접 영향 집중 테스트 통과. 기본 시각 인자 proxy 결함은 overload로 수정하고 영향 42개를 재검증했다. +- [x] **REFACTOR:** concurrent approval·자동 writer·부분 승인 이후 자동 갱신까지 보정하고 최종 gate APPROVE를 받았다. + +### Task 5.2 — Complete proposed ADMIN API/error contract + +**Goal 실행 `P5-T2`:** every proposed request/candidate/apply/cancel interaction maps to typed endpoint and existing auth/error response conventions. + +- **시작 조건:** `P3-T2`, `P4-T2`, `P5-T1` service boundaries stable. +- **완료 증거:** route, role, serialization, stable errors, idempotency, stale values and pagination integration tests. +- **범위 밖:** browser app, endpoint aliases, existing controller behavior changes. + +**Files:** +- Modify: `adapter/in/web/AdminTranslationSelectionController.kt`, `dto/TranslationSelectionRequest.kt`, `dto/TranslationSelectionResponse.kt`, `i18n/SodaMessageSource.kt` and existing message resource files verified before editing. +- Test (new/proposed): `src/test/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/in/web/AdminTranslationSelectionHttpIntegrationTest.kt`. + +- [x] **RED:** ADMIN 권한·오류·paging·cancel·receipt HTTP 계약 테스트를 작성했다. +- [x] **RED 확인:** endpoint 미구현과 잘못된 언어 오류 코드 RED를 확인했다. +- [x] **GREEN:** 계약의 9개 endpoint와 typed DTO·안정 오류를 구현했다. +- [x] **GREEN 확인:** 최종 실제 HTTP 27개, ktlintCheck, bootJar 통과. +- [x] **REFACTOR:** 공통 exception handler를 바꾸지 않고 새 메시지와 feature 입력 오류를 처리했다. + +### Phase 5 Gate — `P5-GATE` + +검증: subset apply writes exactly selected values, omitted candidate is not recoverable through same request, common bundle all-or-nothing, independent selected field unaffected by unrelated source update, stale selected candidate rejected, all validation occurs before any write. + +## Phase 6: schema and writer readiness gate + +**Phase 결과:** 신규 writer가 작업을 생성하기 전에 schema와 구 writer 종료 조건을 충족하고 rollback 경로가 approval 보호를 보존한다. 별도 flag 활성화는 DEC-11로 폐기됐다. + +**선행조건:** `P1-GATE`~`P5-GATE`, implementation owner가 실제 migration location, transport timeout semantics와 production DB claim strategy를 확인. + +### Task 6.1 — rollout readiness evidence + +**Goal 실행 `P6-T1`:** 신규 writer가 승인 override를 덮어쓸 legacy writer와 구 unique index가 없는 준비된 환경에서 작업을 시작한다. + +- **Files:** `schema.sql`; `CreatorAdminContentSeriesService.kt` membership lock; deployment/operator-owned schema and rollout artifacts; plans/runbook evidence in this document or deployment-owned release record. +- **TDD 예외 사유:** Deployment order, DDL application, blue/green instance inventory are operator/runtime procedures and cannot be proven by a code unit test alone. +- **대체 검증 방법:** schema review, 설정 없는 등록 테스트, rollout checklist, MySQL-focused locking/unique claim integration evidence, environment instance inventory. + +- [x] 과거 기본 OFF controller/poller 동작을 구현·검증했다. 이 요구는 DEC-11/P7로 대체되며 당시 PASS 이력만 보존한다. +- [x] 세 신규 테이블과 queue 확장/축소 순서를 `schema.sql` artifact로 작성했다. 아래 운영 실행은 하지 않았다. +- [x] 최종 HTTP/회귀·lint·bootJar와 단일 전체 검토/차단 보정을 완료했다. 상세 증거는 Progress와 implementation-review.md에 있다. +- [ ] Expand schema before new writers start work: three tables and source-language-aware queue unique index. 구 index는 구 writer/in-flight 작업 drain 전까지 유지한다. MySQL DDL every column/table COMMENT; timestamp seconds precision. +- [ ] Drain all legacy web/worker instances, scheduled tasks, and in-flight materializers. 관리자 화면 미사용으로 일반 큐 작업을 막을 수 있다고 가정하지 않는다. +- [ ] Remove old queue unique index after legacy drain and before any new writer creates jobs; retain the language-aware index. `schema.sql`의 주석 처리된 DROP은 별도 통제된 운영 statement로 남긴다. +- [ ] Start the override-aware application only after schema/index/writer readiness is complete. Controller와 후보 worker는 기동 시 자동 등록되며 ADMIN·Redisson 잠금·기존 주기를 유지한다. 별도 기능 활성화 설정이나 미구현 worker 중지 기능은 없다. +- [ ] After first approval rollback only to override-aware build. Record operator approval and evidence; never roll back to writer that ignores overrides. +- [ ] Run MySQL integration evidence for candidate claim/fencing, Content lock freshness, group apply transaction, timestamp DB-response equality. H2 alone is insufficient. + +## 승인된 execution order와 dependencies + +다음 preflight 표는 같은 interface나 파일 경계를 공유하는 후속 작업을 묶어 충돌 지점을 드러낸다. 이는 task 순서를 바꾸거나 추가 구현 결정을 내리지 않는다. + +| 선행 작업 | 의존 작업 | 공유 interface/file 경계 | +|---|---|---| +| P1 snapshot (`P1-T1`) | P2, P3 | CONTENT source snapshot, fingerprint 및 source service | +| P1 grouping (`P1-T2`) | P3, P4, P5 | grouping/template 및 selection domain model | +| P2 writer (`P2-T1/T2`) | P5, normal worker | override-aware CONTENT writer, materializer 및 source invalidation | +| P3 request (`P3-T1/T2`) | P4, P5 | request lifecycle, store, controller/DTO contract | +| P4 candidate (`P4-T1/T2`) | P5 | candidate repository, generation manifest 및 cancellation boundary | +| P5 apply/API (`P5-T1/T2`) | P6 | apply transaction, controller/API contract 및 receipt | + +`P6-T1`의 운영 절차는 이번 승인 범위 밖이다. 로컬 구현 승인만으로 production DDL, 배포 또는 rollout 절차를 수행하지 않는다. P7의 플래그 제거 구현은 DEC-11로 이미 승인됐다. + +| 순서 | Goal | 의존성 | 산출물 | +|---:|---|---|---| +| 1 | `P1-T1` | 사용자 승인 | Shared CONTENT source snapshot | +| 2 | `P1-T2` | `P1-T1` | Group analyzer/template | +| 3 | `P1-GATE` | `P1-T1`, `P1-T2` | Source/group invariants | +| 4 | `P2-T1` | `P1-GATE`, schema approved | Override-aware CONTENT writer | +| 5 | `P2-T2` | `P2-T1` | Source invalidation/queue correction | +| 6 | `P2-GATE` | Phase 2 tasks | Writer/mutation race evidence | +| 7 | `P3-T1` | `P2-GATE` | Durable prepared request | +| 8 | `P3-T2` | `P1-GATE`, `P3-T1` | Review API | +| 9 | `P3-GATE` | Phase 3 tasks | No pre-review dispatch proof | +| 10 | `P4-T1` | `P3-GATE` | Candidate worker/fresh results | +| 11 | `P4-T2` | `P4-T1` | Chunk dispatch cancellation gate | +| 12 | `P4-GATE` | Phase 4 tasks | Provider/cancel evidence | +| 13 | `P5-T1` | `P2-GATE`, `P4-GATE` | Atomic one-shot subset apply | +| 14 | `P5-T2` | `P3-T2`, `P5-T1` | API contract implementation | +| 15 | `P5-GATE` | Phase 5 tasks | End-to-end server contract evidence | +| 16 | `P6-T1` | All gates, DEC-11 readiness | Schema/index/writer readiness evidence | + +## 검증 명령 제안 + +### 구현 파일 경로 보완 + +Task에서 줄인 기존 경로의 root는 `src/main/kotlin/kr/co/vividnext/sodalive/`이고 신규 feature 경로의 root는 `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/`다. `corresponding repository/store adapter`로 표기한 신규 파일은 아래 경로로 고정한다. 이 표는 새로 만들 파일의 제안이며 존재하는 파일이라는 뜻이 아니다. + +- `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/out/persistence/ContentTranslationOverrideRepository.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/out/persistence/JpaContentTranslationOverrideStore.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/out/persistence/TranslationSelectionRequestRepository.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/out/persistence/TranslationCandidateRepository.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/adapter/out/persistence/JpaTranslationSelectionStore.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/v2/contenttranslation/application/ContentTranslationWriteService.kt` +- `src/main/kotlin/kr/co/vividnext/sodalive/i18n/translation/TranslationCallControl.kt` +- `docs/20261117_관리자번역후보선택/schema.sql` — 향후 구현에서 작성할 MySQL DDL. 현재 문서 작업에서는 생성·실행하지 않는다. + +`ContentTranslationSourceService.kt`는 P1에서 생성하고 P3에서는 수정한다. Feature revision/selection 모델은 `domain/TranslationSelection.kt`, request/response 모델은 앞서 정한 DTO 두 파일에 둔다. 단일 사용 receipt 모델도 response DTO 파일 안에 두며 별도 `TranslationSelectionReceipt.kt`는 만들지 않는다. 공통 예외 파일은 기존 `src/main/kotlin/kr/co/vividnext/sodalive/common/SodaException.kt`와 `src/main/kotlin/kr/co/vividnext/sodalive/common/SodaExceptionHandler.kt`를 그대로 소비한다. + +각 Phase Gate의 시작 조건은 같은 Phase Task 전체 GREEN 및 회귀 완료이며, 범위 밖은 다른 Phase 기능 추가와 테스트 완화다. 완료 증거는 아래 해당 focused 명령 통과·Task별 기록·Phase 문단의 수동 불변식 대조다. P6은 실제 운영 적용 승인 전 실행하지 않고 준비·검증 계획만 전달한다. + +아래 commands는 미래 implementation checks이며 이번 문서 작업에서는 실행하지 않는다. Test class 경로와 names는 모두 proposed; implementation 시작 때 source tree와 actual Gradle test discovery에 맞춰 확정한다. + +```bash +./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.domain.ContentSourceSnapshotTest' --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.domain.TitleGroupingAnalyzerTest' +./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationOverrideIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationSourceInvalidationIntegrationTest' +./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionRequestIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionHttpIntegrationTest' +./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionWorkerIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionCancelIntegrationTest' +./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionApplyIntegrationTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' +./gradlew ktlintCheck +./gradlew bootJar +``` + +- Run a selector only after confirming the proposed test class exists. Do not claim these tests already exist. +- Add exact affected source mutation and language detection test classes only after reading their actual test files; do not fabricate existing class names. +- MySQL locking/index behavior requires integration against a suitable MySQL test database. H2 evidence alone cannot establish production behavior. +- Entire test suite is user-owned: `./gradlew test`. Do not run unfiltered `test`, `check`, `build` or `clean build` as the agent. +- 제품 test, SQL, DB, build, provider 호출과 commit은 문서 작업에서 실행하지 않는다. 문서 변경 범위와 공백 검사는 별도로 수행해 아래 기록에 남긴다. + +## Change and commit strategy + +This is a future implementation proposal, not permission to execute or commit. No commit is created by this plan. If the user separately authorizes implementation and commits, each atomic commit must contain one verified increment and its regression tests: shared snapshot/grouping; override-aware writer/invalidation; durable candidate generation/cancel; atomic apply/API; rollout/verification evidence. Do not commit intentionally failing RED work or split an invariant across commits. Use the repository's `docs/agent-guides/커밋메시지.md` and validate each proposed message using `work/scripts/check-commit-message-rules.sh` before an authorized commit. + +## 승인된 기술 결정 + +제품 인터뷰와 승인된 설계 질문은 반복하지 않는다. 다음 설계는 기존 구현 기준이며 운영 실행은 이번 범위 밖이다. + +1. 세-table logical schema, JSON snapshot boundary, raw fingerprint definition and MySQL unique/index/lock strategy. +2. Exact conservative title-span ranking and single ownership segmentation policy; code point API offset and grapheme boundary validation. +3. 60초 lease와 복구 1회, connect/read/API-call별 timeout, dispatch 승인 기준의 취소 경계. Read timeout은 전체 처리 시간 보장이 아니다. +4. All supported non-source languages × all registered provider fan-out, existing detection cache use when source language is missing, and its preparation failure behavior. +5. DEC-11의 설정 없는 등록, 신규 작업 생성 전 schema 준비·legacy writer drain·구 queue index 제거, override-aware rollback condition. + +기존 구현은 authentication handler, provider transport 재시도/timeout, series membership lock path를 기준으로 검증했다. 실제 운영 DB 검증은 별도 운영 증거이며 확정된 제품 요구사항을 약화하거나 구현 승인을 다시 요구하는 근거가 아니다. + +## Progress / 검증 기록 + +DEC-11/P7 이전의 기본 OFF, 혼합 flag 및 OFF→ON 운영 안내는 당시 검증·설계 이력으로 보존한다. 현행 정책은 설정 없는 기동 등록과 새 writer 작업 생성 전 schema/index/구 writer 종료 조건이다. 과거 PASS를 P7의 검증이나 외부 gate 승인으로 재사용하지 않는다. + +### Phase 7: 사용자 요청에 따른 자동 활성화 + +**Goal 실행 `P7-T1`:** 별도 enabled 설정 없이 관리자 번역 API와 후보 worker를 등록하고 일반 큐는 항상 원문 언어를 포함한 identity를 사용한다. + +- 시작 조건: PRD DEC-11 사용자 명시 승인. 기존 기능 전체를 다시 설계하지 않는다. +- 완료 증거: 설정 없는 controller/worker 등록 및 ADMIN 경계, 언어별 독립 작업 생성·명시 refresh의 RED/GREEN, 직접 영향 회귀·lint, 현행 문서 일치. +- 범위 밖: 운영 DB·배포·커밋, 일반 provider/후보/승인 정책 변경, 새 스위치나 default-true 호환 shim. +- 변경 파일: `AdminTranslationSelectionController.kt`, `TranslationSelectionWorker.kt`, `TranslationJobScheduler.kt`, 고아 조회가 생기는 `TranslationJobRepository.kt`, `src/main/resources/application.yml`; 직접 생성자 호출 테스트와 activation/queue 테스트. 정확한 패키지는 기존 Phase의 file map을 유지한다. +- 문서: 이 PRD/계획, `api-contract.md`, `schema.sql`, `frontend-implementation-prompt.md` 및 리뷰의 현행 정책을 수정한다. 과거 검증 기록은 삭제하지 않고 DEC-11/P7로 대체됐음을 명시한다. +- [x] **RED:** 설정 없는 실제 ADMIN endpoint/worker 등록과 서로 다른 원문 언어의 동일 source hash 작업 생성 실패를 확인했다. +- [x] **GREEN:** property·조건부 등록·legacy flag 분기를 제거하고 모든 호출자를 맞췄다. 사용이 사라진 repository 메서드/null-language 분기만 정리했다. +- [x] **GREEN 확인:** activation HTTP, polling, queue/refresh, 관련 scheduler/호출자 테스트를 `--tests`로 한정해 실행했다. +- [x] **REFACTOR/자체 대조:** ADMIN·Redisson·fixed-delay 계약 불변과 테스트 전용 격리를 확인하고 lint·문서 정합성 결과를 기록했다. 외부 검토 판정은 아래 별도 Gate다. + +운영 전제 변경: OFF 상태 배포로 구 index와 공존하는 경로는 제거한다. 새 테이블·언어 포함 unique index를 먼저 준비하고, 구 writer를 drain한 뒤 구 unique index를 제거해야 한다. 그 이후 신규 코드의 실제 작업 생성을 허용한다. 관리자 화면을 사용하지 않는다는 사실만으로 일반 큐 생성이 중지된다고 가정하지 않는다. 이 작업에서 SQL이나 배포는 실행하지 않는다. + +- 착수 기록: 2026-11-18. 플래그 production 참조는 controller/worker 조건부 등록, scheduler 분기, application.yml이며 관련 테스트와 현행 문서도 함께 변경한다. + +**완료 Gate `P7-GATE`:** 사용자가 하위 에이전트 없이 직접 마무리하도록 지시했다. 부모가 등록·권한·worker 잠금·queue identity와 테스트/문서 정합성을 직접 검토하고 bootJar 빌드 성공을 확인해 완료했다. P7 외부 리뷰 승인으로 표현하지 않는다. + +#### P7-T1 로컬 완료 증거 — 2026-11-18 + +#### P7-GATE 부모 직접 완료 — 2026-11-18 + +- 사용자의 직접 처리 지시 이후 하위 에이전트에 새 작업을 위임하지 않았다. 외부 검토의 결과를 기다리거나 승인 근거로 사용하지 않았다. +- 직접 대조: application.yml의 활성화 설정 부재, controller/worker의 조건부 등록 제거, ADMIN 권한과 Redisson/1000ms 주기 유지, scheduler의 원문 언어별 조회 및 legacy 분기 제거, repository의 non-null exact-language locking query를 확인했다. +- 검증 근거: P7 RED 4개 및 GREEN 18개 class 162개·ktlint 통과 기록과 테스트 assertions를 대조했다. 마지막 Contents HTTP XML 8개는 failures/errors/skipped 0이다. 통과한 테스트를 반복하지 않았다. +- 직접 빌드: `./gradlew --offline --no-daemon bootJar` — BUILD SUCCESSFUL in 19s, `build/libs/sodalive-0.0.1-SNAPSHOT.jar` 생성. 동일 명령을 불필요하게 한 번 더 호출한 결과는 16s/모든 task UP-TO-DATE였으며 추가 검증 증거로 계산하지 않는다. +- 직접 공백 검사: `GIT_MASTER=1 git diff --check` 통과. 최종 문서 상태를 갱신한 뒤 변경 문서의 공백을 검사한다. +- 운영 SQL·배포·커밋·전체 테스트는 실행하지 않았다. 운영 MySQL과 실제 provider는 미검증이다. 신규 작업 생성 전 schema/index와 구 writer 종료 조건은 유지한다. + +아래는 구현 담당자의 당시 완료 기록이며, 이 기록에 남은 부모 검토 대기 상태는 위 P7-GATE 직접 완료로 종결됐다. + +- [x] **Task 7.1:** 활성화 설정을 제거하고 설정 없는 API/worker 등록과 원문 언어별 독립 queue identity를 검증했다. P7-GATE는 미완료다. +- 원인과 최소 수정: controller/worker의 조건부 등록과 scheduler의 기본 false 분기가 같은 설정에 묶여 있었다. 두 annotation/import, scheduler의 `@Value`·Boolean 인자·legacy 분기, application.yml의 해당 설정을 제거했다. true 기본값, matchIfMissing, 새 활성화 스위치는 없다. +- 고아 API: `TranslationJobRepository.existsByResourceTypeAndResourceIdAndFieldKeyAndTargetLanguageAndSourceHash`를 삭제했다. `findContentFieldJobsForUpdate`는 exact force-refresh 호출이 필요하므로 유지하고 `sourceLanguage`를 non-null `String`으로 좁혀 null wildcard만 제거했다. P2의 locking current read·managed refresh와 worker의 재료화/완료 원자 transaction은 유지했다. +- 계약 교체: `TranslationSelectionDisabledHttpIntegrationTest`의 비등록/404 기대는 DEC-11로 폐기하고 `TranslationSelectionActivationHttpIntegrationTest`의 실제 ADMIN 생성·조회, USER 거부 및 worker bean 등록 2개로 교체했다. environment에도 해당 property가 없는지 확인한다. Queue의 구 unique 공존/혼합 flag 요구는 동일 언어 중복 방지·exact 언어 재개로 교체했다. Refresh의 legacy skip 요구는 다른 언어 완료 행을 보존하면서 현재 언어 refresh를 생성하는 검증으로 교체했다. Retry/완료 태그도 이전 언어 행을 보존하며 새 identity를 생성하도록 기대를 맞췄다. stale managed RUNNING·빈 consistent read 이후 commit된 exact row·현재 상태별 예산·원자 완료 경쟁 회귀는 삭제하거나 약화하지 않았다. +- 테스트 격리: 기존 선택 기능 `@Import` 설정과 local H2/fake provider, Redisson mock을 재사용했다. 이 전용 설정은 scheduling processor를 활성화하지 않으며 polling 테스트가 실제 worker를 명시 호출한다. production disable knob나 전역 isolation 변경, 실제 provider 호출은 없다. + +RED 실행 명령 (production 변경 전): + +```bash +./gradlew --offline --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.TranslationSelectionActivationHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationQueueIntegrationTest.shouldDistinguishJobsBySourceLanguage' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationRefreshIntegrationTest.shouldCreateIndependentLanguageRefreshAgainstCurrentRows' +``` + +- RED 결과: 3개 class 4개 테스트가 모두 assertion 실패, errors/skip 0. 실제 생성 HTTP expected 200 / actual 404, worker bean expected 1 / actual 0, 일반 queue expected `{ko, ja}` / actual `{ko}`, 명시 refresh expected `{ko, ja}` / actual `{ja}`. 컴파일·fixture 실패가 아니다. BUILD FAILED in 50s. + +GREEN 실행 명령: + +```bash +./gradlew --offline --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.TranslationSelectionActivationHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.TranslationSelectionContentsHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionApplyHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionReceiptHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionPollingIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionRequestIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionWorkerIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationQueueIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationRefreshIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationSourceInvalidationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobRetryIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.CompletedContentTagRepairTest' \ + --tests 'kr.co.vividnext.sodalive.v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionRefreshIntegrationTest' ktlintCheck +./gradlew --offline --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionContentsHttpIntegrationTest' +``` + +- GREEN 결과: 첫 명령은 17개 class 154개 테스트와 ktlintCheck 통과, BUILD SUCCESSFUL in 1m 43s. `TranslationSelectionContentsHttpIntegrationTest` selector는 잘못된 이름이라 매칭되지 않았다. 통과한 154개를 재실행하지 않고 실제 `AdminTranslationSelectionContentsHttpIntegrationTest`만 두 번째 명령으로 실행해 8개 통과, BUILD SUCCESSFUL in 47s. 총 18개 class 162개가 failures/errors/skipped 0이다. +- 첫 실행 직후 `build/test-results/test/TEST-*.xml`의 17개 suite와 개수를 대조했다: Activation 2, Admin HTTP 14, Apply HTTP 10, Receipt HTTP 3, Polling 2, Request 8, SelectionWorker 4, Queue 7, Refresh 7, SourceInvalidation 13, Scheduler 3, Retry 10, CompletedTags 27, CreatorCommunity 16, JobWorker 13, ContentTag 11, SelectionRefresh 4. 두 번째 실행의 Contents HTTP XML은 8개다. Gradle 후속 test 실행이 이전 XML을 덮어쓰므로 현재 result 디렉터리는 두 번째 실행 증거이며 첫 실행의 관찰 기록과 혼동하지 않는다. +- 정적 대조: `src/main` 검색에서 활성화 property·`selectionEnabled`·삭제한 exists API·null-language wildcard 참조 0건. 테스트의 enabled=true/false 주입도 모두 제거했고 property 이름은 신규 activation 테스트의 실제 environment 부재 assertion에만 남는다. API ADMIN 경계, worker lock key/lease/fixed-delay, exact-language refresh는 원래 구현을 유지했다. +- 문서: PRD/API/현재 계획/SQL 운영 주석/독립적으로 전달하는 frontend prompt와 현재 review 상태를 자동 등록 정책으로 맞췄다. 과거 검증/리뷰의 OFF 정책에는 DEC-11 supersession 안내를 붙이고 PASS 기록은 보존했다. SQL DROP은 여전히 주석 처리된 별도 운영 statement이며 실행하지 않았다. +- 자체 구조 대조: 변경은 등록·enqueue identity·기존 회귀 계약에 한정했다. 신규 helper/type escape/방어층/로그/입력 경계는 추가하지 않았다. 신규 activation 테스트는 45 pure LOC, Queue는 185, Refresh는 140이다. 기존 CompletedContentTagRepairTest는 241로 다음 증설 때 분리를 검토한다. 기존 Retry 테스트는 287로 크지만 이번 요청의 좁은 계약 교체만 수행하고 무관한 구조 정리는 하지 않았다. +- 미검증·미실행: 전체 테스트(`./gradlew test`는 사용자 실행), check/build/bootJar, 운영 MySQL RR·잠금·시각·DDL, cloud/실제 provider, 배포·커밋, 외부 reviewer. 사용자 지정 도구 범위에 따라 LSP는 호출하지 않았고 Kotlin/Java compilation과 ktlintCheck를 사용했다. Gradle 9 deprecation 안내는 남아 있다. H2 성공을 운영 MySQL 증거로 주장하지 않는다. 신규 writer의 작업 생성 전 세 테이블·언어 포함 unique index, 구 writer/in-flight 종료, 구 unique index 제거가 필요하며 P7-GATE는 부모 담당자에게 남긴다. + +### 최종 로컬 완료 및 운영 인계 — 2026-11-17 + +- P1~P5 및 P5-R1 완료. 단일 전체 gate의 TR-19 차단 한 건을 보정한 후 새 delta 검토가 APPROVE/HIGH를 반환했다. 다른 통과 범위는 재감사하지 않았다. +- 부모가 최종 코드에서 실제 HTTP 세 클래스 27개와 bootJar를 실행했다. BUILD SUCCESSFUL in 2m 7s, 종료 코드 0. 최신 XML failures/errors/skipped 0과 jar 존재를 최종 reviewer가 확인했다. +- P5-R1 신규4+직접118 회귀 및 ktlintCheck 통과. 이전 각 Phase의 RED/GREEN·실패 보정 기록은 보존하며 중복을 합산해 전체 테스트 수로 주장하지 않는다. +- Feature 기본값은 false다. schema expand → 모든 구 writer/in-flight 작업 drain → 구 queue unique index 제거 → enabled=true의 순서를 운영 담당자가 별도 승인 후 수행한다. 운영 MySQL 검증과 DDL 실행·배포·커밋은 미실행이다. +- Ruling 요약: residual 내부 구문을 하나의 입력으로 보존해 의미 손실을 막았다. AWS SDK admin retry는 request별 interceptor gate/timeout 안에서 제어하고 일반 retry 설정은 유지했다. 두 판단은 승인된 요구를 구현하는 방식이며 잘못되면 후보 품질/취소 시 비용 예측에 영향이 있으나 게시 값은 명시적 적용 전까지 보존한다. +- 전체 테스트 사용자 명령: `./gradlew test`. 실제 provider 품질·4500건 처리량·프론트엔드 화면은 이번 검증 범위 밖이다. 최종 상태·문서 공백 검사 후 종료한다. + +### P4-GATE 완료 — 2026-11-17 + +- 독립 검토 PASS. Provider manifest/version, fresh fan-out, 필드 정책을 포함한 요청 내부 dedup, linked 후보 출처, lease/fence/cancel, all-failed/zero-unit READY, 실제 SDK retry 전송 gate, 일반 호출 비간섭을 확인했다. +- 검증 증거는 최초 focused 180개 실행 중 실패 2건을 수정하고 해당 ADMIN API 13개와 실제 전송·취소·worker 14개를 통과한 이력이다. 최초 실패를 감추거나 180개 전체가 마지막 실행에서 통과했다고 표현하지 않는다. 마지막 14개 XML failures/errors/skipped 0 및 ktlint 오류 0을 검토자가 확인했다. +- 기존 API 404 기대를 구현된 REVIEW_REQUIRED/호출0 검증으로 바꾸고 AWS SDK의 실제 CBOR 프로토콜에 맞춘 로컬 fixture 수정은 검증 완화가 아니라 계약 반영이다. +- 실제 cloud·운영 DB·배포는 미실행. 다음 P5-T1/P5-T2. + +### P3-GATE 완료 — 2026-11-17 + +- 독립 검토 PASS, 수정 필요 finding 없음. ADMIN/기본 비활성 gate, ACTIVE membership, UUID 충돌 rollback 후 replay, 준비 lease/fence/cancel, source/membership current read, 전체 grouping coverage/revision, snapshot/현재 값 분리와 출처를 확인했다. +- 관련 11개 class 68개 tests의 XML failures/errors/skipped 0과 ktlint 보고서를 독립 검토자가 대조했다. 나노초 경계 DB 왕복·실제 HTTP 시각 일치 검증 포함. 재실행하지 않았다. +- 준비 시 누락 언어만 감지하며 게시 payload·approval·기존 번역 memory·일반 job은 변경하지 않는 경로가 구현됐다. +- 운영 MySQL·실제 provider·배포는 미검증/미실행이다. 다음 P4-T1/P4-T2. + +### P4 provider 경계 참고 — 2026-11-17 + +- AWS SDK 공식 `RequestOverrideConfiguration.Builder`는 요청별 `apiCallTimeout`, `apiCallAttemptTimeout`, `putExecutionAttribute`를 제공한다. `AwsRequestOverrideConfiguration.Builder` 공개 메서드에는 요청별 retry strategy가 없다. 설치된 SDK에서 compile로 확인하고 존재하지 않는 builder API를 가정하지 않는다. +- 공식 `ExecutionInterceptor.beforeTransmission`은 SDK retry마다 호출된다. 요청 execution attribute가 있을 때만 취소 gate를 실행하는 interceptor 방식은 기존 공유 client와 일반 호출 동작을 유지하면서 admin 요청의 실제 전송 재시도를 제어할 수 있다. +- Ruling: 일반 client의 retry 설정을 전역 변경하거나 새 transport를 만들지 않는다. Admin 요청의 SDK 재시도도 실제 전송 전 gate와 전체 API timeout 안에 포함시킨다. 이미 승인된 전송의 과금은 되돌릴 수 없으며 요청/후보 작업의 exactly-once는 주장하지 않는다. +- 근거: https://docs.aws.amazon.com/java/api/latest/software/amazon/awssdk/core/interceptor/ExecutionInterceptor.html 및 https://docs.aws.amazon.com/java/api/latest/software/amazon/awssdk/awscore/AwsRequestOverrideConfiguration.Builder.html . 문서 조회만 했고 실제 AWS 호출은 없다. + +### P3-T1 구현·집중 검증 — 2026-11-17 + +- 생성은 외부 호출 전에 PREPARING과 활성 member IDs를 commit한다. 관리자+UUID unique 충돌은 별도 REQUIRES_NEW 삽입 transaction이 rollback된 후 승자 요청을 읽는다. canonical scope SHA-256이 다르면 IDEMPOTENCY_CONFLICT다. 빈 활성 시리즈는 FAILED/EMPTY_SCOPE로 저장한다. +- 공유 source builder와 기존 감지 cache를 사용한다. 준비 전후 request → Series → 현재 CONTENT 오름차순 잠금 및 fresh refresh로 원문·언어·활성 membership을 검사한다. 누락 언어만 최종 게시 transaction에서 저장하며 payload/approval/일반 job을 변경하지 않는다. 초기 source baseline은 복구에도 고정한다. +- 60초 lease, 단조 fence, 복구 1회 및 두 번째 만료 PREPARATION_INTERRUPTED를 구현했다. 취소는 request gate에서 즉시 commit하며 진행 중 감지 종료를 기다리지 않는다. 만료 fence는 갱신·게시할 수 없다. feature worker는 기존 Redisson의 lock:translation-selection을 사용하고 controller와 같은 enabled property로 보호한다. +- RED: 최초 실제 HTTP 생성에서 endpoint 미구현 404 assertion 실패를 확인했다. 이후 준비 미구현 경계에서 17개 중 9개 assertion 실패를 확인했다. 테스트 설정의 중복 method-security와 JPA index column naming 오류는 RED 증거에서 제외하고 원인만 수정했다. +- GREEN: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionRequestIntegrationTest' --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionPreparationIntegrationTest'` — Request 8개, Preparation 12개, failures/errors/skipped 0. 동시 unique, timestamp 나노초 0/123456789/999999999의 실제 flush/clear 왕복, detector transaction 부재, latch 취소 및 stale fence를 포함한다. +- 저장 보완: getter를 자동 직렬화하지 않는 typed JSON에 raw source·필드 fingerprint·검증된 lossless template를 명시적으로 저장한다. 이 보완 후 재검증과 최종 lint는 P3-T2와 함께 수행한다. 생성·잠금·JSON의 주석은 rollback-only transaction 재사용, 잠금 소유권, 파생 getter 오저장 방지를 설명하는 필수 경계 기록이다. +- P3-T2에서는 summary/contents/grouping/cancel HTTP와 오류·권한을 완성한다. candidate/generate/apply endpoint는 아직 없다. parent가 P3 전체 외부 검토를 수행한다. + +### P3-T1 / P3-T2 완료 기록 — 2026-11-17 + +- [x] P3-T1: 실제 request persistence, 원자적 멱등 생성, 활성 membership 고정, 원본 언어 준비 및 취소·lease/fence·복구 검증 완료. +- [x] P3-T2: ADMIN create/summary/contents/grouping GET·PUT/cancel의 실제 HTTP, typed DTO, revision과 source range 검토 구현 및 집중 검증 완료. +- [x] P3 로컬 검증: 신규 45개와 직접 회귀 23개, 총 11개 class의 68개 테스트가 failures/errors/skipped 0. 같은 실행에서 ktlintCheck BUILD SUCCESSFUL, Kotlin/Java compilation 완료. +- [ ] P3-GATE 외부 검토: 부모 담당자가 전체 Phase 검토를 수행한다. 이 완료 기록은 운영 활성화나 외부 review sign-off가 아니다. 상단 진행 표와 기존 체크박스는 요청된 append-only 경계에 따라 수정하지 않았다. + +실제 endpoint는 `/admin/audio-content/translation-requests`의 POST, GET `/{requestId}`, GET `/{requestId}/contents`, GET·PUT `/{requestId}/grouping`, POST `/{requestId}/cancel`이다. Controller와 worker 모두 `sodalive.translation-selection.enabled`의 명시적 true에서만 등록되므로 기본값은 비활성이다. `/generate`, candidate 및 apply endpoint는 추가하지 않았다. 미래 상태와 DDL 예약 컬럼만 존재한다. + +그룹 read model은 분석 시 확정한 raw shared text, code point exclusive-end range와 lossless template/valueIndex를 저장한 typed JSON을 그대로 반환한다. PUT은 기존 P1 validate를 사용하고 IllegalArgumentException을 INVALID_GROUPING으로 바꾼다. 전체 scope 누락·중복, 언어 혼합, 다른 raw shared text, grapheme 분할을 거부한다. 모두 individual인 series도 REVIEW_REQUIRED를 거쳐 확정하며 revision은 재검토마다 증가한다. GENERATING 이후 편집은 거부한다. + +콘텐츠 페이지는 기본 50, 최대 100, Long ID cursor다. 동결 원문/fingerprint와 현재 fingerprint·활성·연결 자격을 구분한다. 삭제된 원문의 snapshot을 보존하고 현재 fingerprint는 null, eligible은 false다. 현재 source fingerprint에 일치하는 override만 ADMIN 출처와 실제 provenance를 반환하며 나머지는 UNKNOWN이다. 현재 locale payload가 없으면 현재 source fallback을 사용한다. 일부 필드의 원문 변경은 다른 필드의 approval provenance를 숨기지 않는다. + +추가 RED/GREEN: 기존 cache detector는 첫 제공자 실행 중 취소돼도 다음 감지 제공자를 호출했다. `TranslationSelectionDetectionDispatchIntegrationTest`에서 fallback 호출 expected 0 / actual 1을 확인했다. 기존 `detectWithCache(query)` 계약을 유지하고 `detectWithCache(query, authorizeDispatch)` overload를 추가해 각 감지 제공자 직전 짧은 request/source/lease gate를 실행한다. 네트워크 중 transaction/부모 잠금은 없고 취소 전 승인된 호출만 in-flight로 취급한다. 이 경계는 후보 번역 호출 구현이 아니다. P3 HTTP 최초 RED는 미구현 GET/PUT/cancel 경로에서 12개 assertion 실패였다. 최초 lint의 새 파일 포맷/import 오류는 apply_patch로 수정했고 마지막 실행은 깨끗하다. + +최종 실행 명령: + +```bash +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelection*IntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.*IntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' \ + --tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderCacheEndToEndTest' \ + --tests 'kr.co.vividnext.sodalive.admin.content.AdminContentControllerSecurityTest' ktlintCheck +``` + +신규 class별 최종 결과는 Request 8, Preparation 12, DetectionDispatch 1, Polling 2, Admin HTTP 13, Contents HTTP 8, Disabled HTTP 1이다. 기존 회귀는 Cache 2, Metadata transaction 10, Provider cache E2E 5, Admin security 6이다. Timestamp 검증은 나노초 0/123456789/999999999의 23:59:59를 실제 H2 flush/clear·재조회와 HTTP `2026-11-17T23:59:59Z`까지 정확히 비교한다. H2의 이 결과를 MySQL locking/timestamp 증거로 주장하지 않는다. + +P4가 소비할 실제 경계: + +1. `application/TranslationSelectionRequestService`: `create(adminId: Long, clientRequestId: UUID, scope: TranslationSelectionScope): TranslationSelectionRequest`, `get(requestId: Long)`, `cancel(requestId: Long)`. 조회는 작업을 dispatch하지 않는다. +2. `port/TranslationSelectionStore`: `find(requestId)`, `findCreation(adminId, clientRequestId)`, `lock(requestId)`, `nextPreparation(now)`, `save(request)`. lock/claim/save의 transaction은 호출 application이 소유한다. lock은 PESSIMISTIC_WRITE와 refresh로 현재 managed 상태도 갱신한다. +3. `application/TranslationSelectionPreparationService`: `prepareNext(): Boolean`, `claimNext(): TranslationPreparationClaim?`, `processPrepare(claim: TranslationPreparationClaim)`. Claim은 requestId/fence/고정 sources다. 만료된 claim은 자신의 lease를 되살릴 수 없다. 복구 한도를 소진한 row를 FAILED로 닫은 경우 claimNext는 null이다. +4. `domain/SelectionRequestSnapshot`: version, immutable memberContentIds, preparationSources, 확정 contents 및 sourceFingerprints, grouping의 groups/individualContentIds/templates, reviewed, providerManifest, targetLanguages. `SelectionTitleTemplate.template()`은 기존 P1 TitleTemplate/render 계약으로 복원한다. P4는 accepted generation revision과 후보 progress의 실제 처리를 추가해야 한다. +5. `application/ContentTranslationSourceService.lockScope(scope)`는 호출자의 request transaction 안에서 Series → 현재 CONTENT 오름차순 잠금을 얻고 활성 콘텐츠만 반환한다. 새 source 조립 없이 기존 `AudioContent.toContentSourceSnapshot()`을 사용한다. `adapter/scheduler/TranslationSelectionWorker`는 기존 Redisson `lock:translation-selection` 안에서 현재 PREPARING만 처리하며 P4가 같은 poller를 확장한다. + +자체 구조 대조: 새 production 파일 최대 169 pure LOC, 새 테스트 최대 181 pure LOC다. 파일별 책임은 요청 저장/준비/검토/조회/HTTP/polling으로 한정한다. 새 내부 Any map·type suppression·retry framework·일반 자동 번역 fallback을 추가하지 않았다. source와 JSON/API 입력의 경계에서 검증하고 기존 P1 분석 정책, P2 override writer와 detector cache를 재사용한다. 테스트 HTTP helper의 method/path/body/actor는 실제 wire 입력이라 네 인자를 유지하며 별도 가짜 config 객체를 만들지 않았다. 기존 대형 SodaMessageSource는 필요한 여섯 message key만 추가했다. + +미실행: 전체 테스트/full check/build/bootJar, 운영 또는 실제 DB/DDL, 실제 provider/cloud, 배포·활성화, git/commit/delegation/worktree 및 외부 검토. LSP 도구가 없어 Kotlin/Java compilation과 lint로 검사했다. 기존 AudioContentServiceTest의 불필요한 !! 및 donation/presence 테스트의 unchecked cast 경고, Gradle 9 deprecation은 변경 범위 밖이라 그대로 남겼다. P1 domain 파일은 수정하지 않아 전용 재검증을 하지 않았다. 전체 테스트 사용자 실행 명령은 `./gradlew test`다. 승인된 P3에서 중단한다. + +### P2-GATE 완료 — 2026-11-17 + +- 최초 독립 검토의 materialize/complete 간 refresh 유실을 같은 transaction 완료 처리로 보정했다. 후속 RR snapshot 변형은 명시적 CONTENT refresh의 locking current read와 managed refresh로 보정했다. +- 제한 재검토 최종 판정: ADDRESSED, 해당 P2 finding 잔여 없음. Content → job 잠금 순서와 provider transaction 분리는 유지한다. +- 검증 이력: 초기 관련 focused 257개, 완료 경합 보정 관련 44개, RR 보정 신규 7개+관련 46개 통과. 각 수정 범위에 맞춰 실행했으며 마지막 ktlintCheck 통과. 이 수치를 서로 다른 고유 테스트 총합으로 주장하지 않는다. +- 실제 MySQL RR은 실행하지 않았고 H2 가시성 모사는 별도 한계로 기록한다. P2-GATE는 코드·기능 검증 완료이며 운영 적용 승인이 아니다. 다음 P3-T1/P3-T2. + +### P1-T2 구현 검증 — 2026-11-17 + +- 상태: 그룹 분석·검토 검증·템플릿 조립 구현 및 focused GREEN 완료, 작업 범위 독립 검토 중. +- 구현: `TitleGroupingAnalyzer.analyze`, `TitleGroupingReview.validate`, `TitleTemplate.render`; 언어별 실제 반복 구간 탐색, 전체 scope 분할/범위 검증, 원문을 보존하는 Unicode code-point/grapheme template. +- RED: 도메인 테스트 21개가 미구현 정책 때문에 assertion 실패했다. +- GREEN: `TitleGroupingAnalyzerTest` 21개 + `ContentSourceSnapshotTest` 14개 통과, `ktlintCheck` 통과. 부모가 grouping XML의 failures/errors/skipped 0을 확인했다. +- 검토 초점: multiword residual 입력이 의미 문맥을 유지하는지, 손실 없는 재구성과 provider 입력 경계가 함께 맞는지 확인한다. +- 미실행: 전체 테스트, DB, 실제 provider, HTTP 회귀(이번 변경은 domain 3파일만). +- Ruling: 의미 있는 residual gap은 내부 공백/구두점을 포함한 하나의 번역 입력으로 유지한다. 단어별 분해는 실제 문맥을 소실하므로 금지한다. 바깥 구분자만 literal로 보존한다. 잘못된 판단이면 제목 분석 후보 품질에 영향이 있지만 사용자 원문·게시 번역은 적용 전까지 바뀌지 않는다. + +### P1-T2 보정 및 P1-GATE 완료 — 2026-11-17 + +- RED: 두 residual 구문을 기대했으나 다섯 단어 입력으로 나뉘는 assertion 실패를 확인했다. +- 수정: 문자 있는 gap은 바깥 구분자만 literal로 두고 내부 공백·구두점·숫자·grapheme를 포함한 구문을 하나의 residual로 유지한다. +- GREEN: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.domain.TitleGroupingAnalyzerTest' --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.domain.ContentSourceSnapshotTest'` — 21+14개 통과. `./gradlew ktlintCheck` 통과. +- 독립 제한 재검토: 기존 fragmentation 지적 ADDRESSED, 잔여 지적 없음. Snapshot 14개/HTTP 22개 검증과 함께 P1-GATE 완료. +- 다음: P2-T1 승인 저장과 CONTENT writer 연동. 제품 커밋·운영 DB·provider 호출 없음. + +### P1-T1 구현 검증 — 2026-11-17 + +- 상태: 구현·집중 검증 완료, 작업 범위 독립 검토 진행 중. +- 변경: `ContentSourceSnapshot`과 `AudioContent.toContentSourceSnapshot()`을 추가하고 CONTENT extractor/상세 서비스의 원문 조립을 공유했다. 활성 태그의 연관 ID 순서를 고정하고 정확한 원문·언어·태그 벡터의 length-framed fingerprint를 추가했다. 생성자 주입/API 계약은 유지했다. +- RED: `AudioContentDetailTranslationHttpIntegrationTest.shouldShareOrderedActiveSourceAcrossExtractorAndDetail`가 기존 태그 순서 차이로 assertion 실패했다. 별도 tag-vector collision 변이에서도 도메인 테스트 2개가 assertion 실패했으며 변이는 복구했다. 새 타입 미구현 컴파일 실패는 RED 증거로 세지 않았다. +- GREEN: `./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.domain.ContentSourceSnapshotTest' --tests 'kr.co.vividnext.sodalive.content.AudioContentDetailTranslationHttpIntegrationTest' ktlintCheck` — BUILD SUCCESSFUL, 도메인 13개/HTTP 22개 모두 통과. 부모가 Gradle XML의 failures/errors/skipped 0을 확인했다. +- 한계: H2·테스트 provider 기준이다. 전체 테스트/운영 DB/실제 provider/배포/커밋은 실행하지 않았다. LSP 도구가 없어 Kotlin compile과 lint로 검사했다. +- 다음: P1-T1 독립 검토 종료 후 P1-T2 제목 분석을 구현한다. 같은 통과 테스트를 변경 없이 반복 실행하지 않는다. + +### P1-T1 검토 보정 및 완료 — 2026-11-17 + +- 검토: nullable tag ID를 null-first로 정렬하면 영속화 전후 원문이 바뀌는 1건을 발견했다. +- RED: `ContentSourceSnapshotTest.shouldAppendPendingTagsAndKeepSnapshotStableAfterIdAssignment`가 null-first 순서 때문에 assertion 실패. +- 수정: 저장 ID는 오름차순, pending은 nullsLast 안정 정렬로 뒤에 두어 삽입 순서를 유지한다. +- GREEN: snapshot 및 상세 HTTP 두 focused class 재실행 — BUILD SUCCESSFUL 38s, 14+22개 모두 통과. 이 보정 후 lint 재실행은 P1 grouping 검증에서 함께 수행한다. +- 재검토: 같은 두 위치만 읽어 ADDRESSED, 추가 지적 없음. P1-T1 완료, 다음 P1-T2. 제품 커밋·운영 반영은 없다. + +### 문서 제안 작성 — 2026-11-17 + +- 상태: 기술 설계 초안, 사용자 검토 대기. +- 무엇을: 기존 PRD를 인터뷰 결정에 맞게 보정하고 신규 API 및 구현 계획 제안 2개를 작성. +- 어떻게: `sample-prd.md`, `sample-plan-task.md`, 작업/문서유지보수/코드/테스트/실행명령어 guides, 기존 CONTENT translation/provider/admin/mutation/read path sources를 읽어 문서에 반영했다. +- 검증: 문서 간 정합성만 확인. tests, build, SQL, provider, API, DB 및 Git commands는 실행하지 않았다. +- 남은 항목: architecture/API proposal 사용자 검토, 운영 DB/MySQL locking 및 provider timeout behavior unverified, 모든 implementation tasks 미착수. +- 다음 행동: 사용자가 제안 설계를 검토하고 구현 기준을 승인한 뒤 `P1-T1`부터 시작. + +### 설계 검토와 후속 인터뷰 반영 — 2026-11-17 + +- 단일 독립 검토에서 제품 결정/제안 혼동, apply 검증 잠금 순서, queue index 호환, 취소 경계, preview DTO, PREPARING 복구, replay/provider-version 검증을 지적했다. [검토 기록](reviews/design-review.md)에 근거와 보정을 남겼다. +- 후속 인터뷰에서 활성 series member만 포함하고 한 번의 부분 적용 후 요청을 종료하기로 확정했다. 자유 번역문 입력 제외는 사용자 거부 결정이 아닌 이번 요청 범위 제한이다. +- 검토 지적을 PRD/API/계획에 반영했다. MySQL·외부 provider·실제 UI는 실행하지 않았고 구현 체크박스는 모두 미완료다. + +### 문서 검증 — 2026-11-17 + +- 네 문서 각각 `GIT_MASTER=1 git diff --no-index --check /dev/null "문서 경로"`를 실행했다. 모두 종료 코드 0, 공백 오류 출력 없음. 대상은 `prd.md`, `api-contract.md`, `plan-task.md`, `reviews/design-review.md`다. +- `GIT_MASTER=1 git status --short --untracked-files=all` 확인 결과 이 디렉터리의 위 Markdown 네 파일만 신규 파일로 표시됐다. 제품 source·설정·테스트 변경은 없다. +- 이 기록 추가 후 계획 문서의 공백 검사만 다시 수행한다. 다른 문서의 통과한 검사는 반복하지 않는다. +- 문서 전용 범위이므로 Gradle 테스트·빌드·운영 DB·provider 호출은 실행하지 않았다. 향후 구현의 테스트 명령은 제안이며 실행 성공을 주장하지 않는다. + +### P2-T1 / P2-T2 구현·검증 완료 — 2026-11-17 + +- 상태: 두 구현 Goal 완료, 활성 구현 Goal 없음. Phase 2에서 중단한다. `P2-GATE`는 외부 최종 검토 전이므로 통과 판정하지 않는다. 상단 상태 표의 갱신은 부모 담당자의 범위로 남긴다. +- 승인 저장: `ContentTranslationOverride` domain/port/JPA entity/repository/store와 `ContentTranslationWriteService`를 추가했다. 승인 문자열, 정확한 fingerprint, request/candidate/provider/admin 출처와 UTC 초 승인 시각을 override row 하나에 보관한다. 후보/request FK나 해당 테이블/API, ContentTranslation metadata column은 없다. +- 쓰기 경계: `lockContent(contentId: Long): AudioContent?`, `lockContent(content: AudioContent)`, `approve(contentId: Long, locale: String, approvals: List): List`, `materialize(contentId: Long, locale: String): Boolean`, `hasCurrentApproval(contentId: Long, locale: String, fieldKey: String): Boolean`. approve는 REQUIRED transaction으로 외부 그룹 transaction에 참여하며 선택하지 않은 payload 문자열을 보존한다. CONTENT materializer는 부모 lock과 refresh 뒤 최신 source/override/payload를 읽고, 승인 없는 필드에만 기존 memory를 요구한다. 잠금 중 provider 호출은 없다. +- 변경 경계: `ContentTranslationSourceInvalidationService.lock(content)`, `invalidateChanged(content, before: ContentSourceSnapshot)`, `invalidateStale(content)`; `ContentTranslationLanguageService.detectMissing(contentId, expectedQuery: String? = null)`. 호출자는 source 수정 전에 부모를 잠그고 before/after를 비교한다. 변경 필드만 전체 locale에서 승인 해제/fallback/enqueue하며 언어 변경은 세 필드 전부다. 이미 삭제한 승인은 A→B→A에서도 살아나지 않는다. 감지 뒤 잠금 안에서 원문을 다시 검사하며 기존 payload shortcut도 stale 승인을 제거한다. +- 외부 호출: 기존 감지 cache의 hash/provider/winner 정책은 유지하고 DB 조회·publish만 짧은 transaction으로 분리했다. 세 수정 서비스의 표지 업로드는 부모 lock 이전에 transaction을 suspend하여 수행한다. 실제 테스트 provider/uploader callback에서 active transaction 부재를 확인했다. 기존 활성 변경(delete/uploadComplete/scheduled publish/admin/creator)과 Series add/remove에도 같은 부모 잠금과 refresh를 적용했다. +- Queue: sourceLanguage 포함 unique/단건 lookup/active lookup/claim grouping을 적용했다. `enabled=false`에서는 exact lookup 실패 후 legacy key EXISTS로 구 index 충돌을 피한다. 다중 언어 row와 혼합 flag, 두 unique index 공존을 H2에서 검증했다. 완료된 일반 CONTENT 필드는 명시적 source invalidation signal일 때만 재개하며 기존 태그 repair와 비-CONTENT 완료 정책은 유지한다. 승인된 재실행 필드는 worker가 paid call을 생략한다. +- RED: 첫 override 테스트에서 stale managed source로 materialize가 true를 반환하는 assertion 실패 1개; 세 source 수정 진입점에서 기존 승인 제목이 남는 assertion 실패 3개; 감지 provider의 active transaction assertion 실패를 확인했다. 승인 우선순위와 worker false 처리를 각각 제거한 변이에서도 2개 assertion 실패를 확인하고 원래 구현을 복구했다. 타입/테스트 fixture 오류와 JPA column naming 오류는 RED 증거에 포함하지 않았다. +- 수정 중 실패: H2 fixture의 HashTag가 BaseEntity가 아닌 점과 명시적 column naming을 보정했다. 감지 테스트의 query는 shared snapshot과 동일한 전체 query로 고쳤다. HTTP 감지 후 enqueue 기대와 legacy event assertion은 새 계약에 따라 실제 DB의 정확한 필드/언어/행 수 assertion으로 교체했다. 테스트 삭제/skip/비교 완화는 없다. 초기 compile 포함 120초, 최종 compile/test/lint 결합 240초 제한 실행은 완료 판정하지 않았으며, 후자는 종료 후 실행 중 JVM이 없음을 확인하고 focused test와 lint를 분리해 완료했다. +- 최종 GREEN: 아래 최종 명령에서 11개 class, 117개 테스트 전부 failures/errors/skipped 0. 신규 Override 10개(나노초 0/123456789/999999999의 23:59:59 flush/clear 왕복 포함), SourceInvalidation 13개, Membership 7개, Queue 6개. parent lock을 보유한 상태의 approval/automatic 경쟁과 실제 override read 경계의 PESSIMISTIC_WRITE도 확인했다. + +```bash +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.*IntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.content.AudioContentDetailTranslationHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.content.AudioContentServiceTest' \ + --tests 'kr.co.vividnext.sodalive.admin.content.AdminContentServiceTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobRetryIntegrationTest' +./gradlew ktlintCheck +``` + +- 추가 직접 회귀 GREEN: `./gradlew --no-daemon test`에 각 아래 class를 `--tests`로 명시하여 실행했다. 같은 통과 검사를 변경 없이 반복하지 않았다. + - `i18n.translation.CompletedContentTagRepairTest` 27개. + - `content.LanguageDetectionCacheServiceTest` 2개, `i18n.translation.LanguageDetectionProviderTest` 7개, `content.MetadataLanguageDetectTransactionTest` 10개, `i18n.translation.MetadataTranslationHttpIntegrationTest` 4개. + - `i18n.translation.AudioContentReadRetryTest` 1개, `i18n.translation.LanguageProviderCacheEndToEndTest` 5개. + - `v2.api.admin.aicharacter.content.LegacyCreatorAdminAudioContentCharacterizationTest` 13개, `AiCharacterAdminAudioContentUpdateTest` 19개, `v2.api.admin.aicharacter.series.LegacyCreatorAdminSeriesCharacterizationTest` 7개. Legacy producer 테스트는 관련 없는 scheduled consumer를 mock하여 외부 provider 실행을 격리하고 실제 queue 쓰기를 검증했다. + - `content.CreatorCommunityLanguageDetectTest` 12개, `CreatorCommunityLanguageDetectionCacheConcurrencyTest` 2개, `v2.creator.channel.community.translation.CreatorCommunityTranslationServiceTest` 16개, `content.ContentSeriesDetailTranslationHttpIntegrationTest` 15개. +- 최종 lint: `./gradlew ktlintCheck` BUILD SUCCESSFUL. LSP diagnostics 도구는 제공되지 않아 focused 실행의 Kotlin/Java compilation과 ktlint를 근거로 사용했다. 기존 Kotlin 경고 및 Gradle 9 deprecation, embedded Redis 종료 시 reconnect warning은 숨기지 않았다. 신규 파일은 production 최대 112 pure LOC, 테스트 최대 168 pure LOC이며 기존 대형 서비스는 요청된 경계만 수정했다. +- 운영 artifact: `schema.sql`은 override table만 생성하고 모든 컬럼/테이블 COMMENT를 포함한다. provenance는 plain ID/list metadata의 TEXT JSON으로 저장한다. 별도 expand SQL은 source-language unique를 추가하면서 구 index를 유지한다. 구 writer/in-flight 작업 drain 후 별도 승인으로 구 index를 삭제하고 그 뒤 enabled=true로 바꾸는 순서 및 override-aware rollback 제한을 주석으로 남겼다. 이 주석은 SQL 실행 순서를 잘못 적용하지 않기 위한 필수 운영 조건이다. 운영 SQL은 실행하지 않았다. +- 미실행: 전체 테스트 및 full check/build, production/MySQL locking·timestamp·DDL, 실제 provider/cloud 호출, 배포, git/commit/worktree, 외부 reviewer. H2 증거를 production MySQL 검증으로 간주하지 않는다. P1 builder는 변경하지 않아 P1 전용 테스트는 재실행하지 않았다. 전체 테스트는 사용자가 `./gradlew test`로 실행한다. Phase 3~5 기능은 추가하지 않았다. + +### P2 Gate finding 보정 — 재료화와 작업 완료의 원자적 commit — 2026-11-17 + +- 범위: 외부 검토에서 확인한 단일 경쟁 조건만 수정했다. Phase를 추가하지 않았으며 `P2-GATE` 판정은 부모 담당자에게 남긴다. +- 원인: worker의 materializer transaction이 CONTENT 잠금을 해제한 다음 completeJob의 별도 transaction이 실행됐다. 그 사이 raw title에 공백을 추가하면 정확한 fingerprint는 달라지지만 normalized job hash는 같다. 무효화는 payload를 source fallback으로 바꾼 후 RUNNING job을 유지하고, 이전 worker가 뒤늦게 COMPLETED로 바꾸어 refresh를 잃었다. +- RED: `ContentTranslationQueueIntegrationTest.shouldKeepRefreshWhenRawSourceChangesDuringWorkerCompletion`을 먼저 추가했다. 실제 Spring materializer proxy가 반환한 직후 latch로 worker를 멈추고, 실제 repository와 invalidation service로 `원문 제목` → `원문 제목 ` 변경을 commit시켰다. 기존 worker에서 `expected PENDING but was COMPLETED` assertion 실패 1개를 확인했다. 서비스 결과나 repository 쓰기를 가짜로 대체하지 않았고 sleep은 사용하지 않았다. +- 수정: `TranslationJobWorker.processNextGroup`의 materialize + 성공 작업 completeJob 호출을 기존 transactionTemplate의 한 executeWithoutResult로 감쌌다. materializer의 REQUIRED와 completeJob의 기존 REQUIRED template이 같은 transaction에 참여하므로 CONTENT 부모 잠금은 payload와 COMPLETED 상태가 함께 commit될 때까지 유지된다. provider/ensureMemory loop는 이 transaction 밖에 그대로 둔다. 동일한 최소 wrapper를 모든 resource의 성공 경로에 적용하되 resource별 재료화 로직, 완료 조건, 부분 실패 경로와 재시도 정의는 바꾸지 않았다. +- 잠금 순서: claim transaction은 job lock을 해제한 뒤 종료된다. 이후 materialization/completion은 CONTENT 부모 → payload/override → job 순서이며, source invalidation의 CONTENT 부모 → job 순서와 일치한다. job lock을 보유한 채 CONTENT를 다시 잠그는 경로를 추가하지 않았다. 실패하거나 materialize가 false이면 이 transaction이 rollback된 후 기존 failJob transaction으로 재시도 상태를 저장한다. +- GREEN: 같은 latch 테스트는 worker transaction이 열려 있으면 원문 수정 시작까지만 기다려 잠금 획득을 경쟁시킨다. 수정 commit 후 동일 en job ID/hash가 PENDING으로 남고 payload는 정확한 공백 포함 source fallback이다. 다음 실제 worker 실행에서 English title로 복구되고 해당 job이 COMPLETED가 되는 것까지 검증했다. 실제 테스트 provider callback의 active transaction 부재와 총 호출 1회도 확인했다. +- focused 검증: 아래 명령의 Queue 7개, SourceInvalidation 13개, Worker 13개, ContentTag 11개, 총 44개 테스트가 failures/errors/skipped 0이다. 첫 결합 실행에서 테스트는 모두 통과했으나 신규 테스트의 미사용 import 1개로 lint가 실패했다. 해당 import만 제거하고 `./gradlew ktlintCheck`를 실행해 BUILD SUCCESSFUL을 확인했다. 통과한 테스트는 반복 실행하지 않았다. + +```bash +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationQueueIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationSourceInvalidationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' ktlintCheck +./gradlew ktlintCheck +``` + +- 변경 파일: `i18n/translation/TranslationJobWorker.kt`, `v2/contenttranslation/application/ContentTranslationQueueIntegrationTest.kt` 및 이 Progress 기록뿐이다. 테스트 조율은 기존 materializer 호출 경계에서 실제 Spring proxy에 위임하며 production 전용 test seam은 추가하지 않았다. +- 미실행: 이전 257개 전체 회귀의 재실행, 전체 테스트/full check/build, 운영 DB/MySQL·cloud/provider, git 및 외부 검토. 검증은 H2 기준이며 전체 테스트 사용자 명령은 `./gradlew test`다. 새 API, provider 코드, DDL 및 승인·무효화 정책 변경은 없다. + +### P2 Gate 동일 finding 보정 — 강제 refresh의 current read — 2026-11-17 + +- 범위: 같은 lost-refresh finding의 REPEATABLE READ 변형만 보정했다. 앞선 worker의 materialize/COMPLETED 원자적 transaction은 그대로 유지했다. 새 Phase나 Gate 통과 판정은 추가하지 않는다. +- 원인: source mutation의 잠금 전 비잠금 조회가 만든 consistent-read snapshot 때문에 worker 완료 commit 이후에도 scheduler의 plain lookup은 이전 RUNNING 또는 빈 결과를 볼 수 있었다. 잠금 조회로 row를 다시 찾아도 같은 persistence context의 managed 상태는 별도로 오래될 수 있다. 비활성 호환 모드의 legacy EXISTS 역시 이전 빈 snapshot을 사용하면 다른 언어 row를 놓칠 수 있다. +- 수정: 명시적 CONTENT invalidation 경로에만 `TranslationJobRepository.findContentFieldJobsForUpdate`의 PESSIMISTIC_WRITE 조회를 사용한다. exact sourceLanguage로 현재 row를 찾은 뒤 `EntityManager.refresh(job, PESSIMISTIC_WRITE)`로 managed 상태도 다시 읽는다. 그 잠금 아래 현재 FAILED/COMPLETED만 PENDING으로 전환하고 retry/error/nextRetryAt을 초기화한다. managed entity를 직접 갱신하므로 같은 persistence context에도 PENDING이 남는다. 현재 PENDING/RUNNING의 상태와 예산은 보존한다. +- 뒤늦게 나타난 row: locking query 자체가 이전 plain snapshot에 없던 row의 존재 여부를 판단한다. exact row가 없고 enabled=false이면 같은 current locking query에만 sourceLanguage=null을 전달해 legacy key의 모든 언어 row 존재를 확인한다. 리스트의 존재만 판단하므로 다중 언어 row에도 안전하며 잘못된 insert를 생략한다. exact 언어 row가 있으면 다른 언어 row는 변경하지 않는다. 일반 enqueue와 비-CONTENT의 기존 plain lookup/조건부 UPDATE 정책은 유지했다. +- 잠금/외부 호출: 기존 source invalidation의 Content 부모 → job 순서를 유지하며 job lock은 source mutation transaction 끝까지 보유한다. provider 코드나 network 경계는 바꾸지 않았고 새 경로는 DB 조회/갱신만 한다. 전역 isolation 변경, context 전체 clear, 재시도 계층 또는 오류 suppression은 없다. +- RED: 신규 `ContentTranslationRefreshIntegrationTest` 7개 중 3개 assertion 실패를 구현 전에 확인했다. 실제 별도 transaction에서 완료를 commit한 뒤에도 stale managed RUNNING이 재개되지 않는 경우, 이전 plain 조회가 빈 결과인 exact job이 뒤늦게 commit된 경우는 expected PENDING / actual COMPLETED였다. legacy plain EXISTS가 이전 false를 반환하는 경우에는 다른 언어 job이 있는데도 추가 insert가 발생했다. 나머지 현재 상태별 4개는 기존 동작 확인이었다. +- 검증 경계: managed RUNNING 회귀는 실제 H2/JPA의 stale persistence context와 별도 transaction commit을 사용한다. 뒤늦은 exact/legacy row 두 회귀는 H2를 MySQL RR로 가장하지 않고, 기존 plain-read 메서드에만 이전 null/false를 유지시켜 그 visibility 경계를 모사한다. locking query, refresh, source invalidation 및 모든 repository 쓰기는 실제 Spring/JPA/H2를 사용하고 DB 상태를 assert한다. sourceLanguage가 다른 완료 row가 그대로 남는 것과 같은 managed 객체가 PENDING으로 바뀌는 것도 검증했다. production 전용 test seam, sleep 또는 mock write는 없다. +- GREEN: 아래 한 번의 focused 실행에서 Refresh 7개, Queue 7개, SourceInvalidation 13개, Scheduler 3개, Retry 10개, Worker 13개, 총 53개가 failures/errors/skipped 0이며 ktlintCheck도 BUILD SUCCESSFUL이다. 기존 latch 기반 완료 경쟁/후속 refresh, materialize false 재시도와 provider transaction 부재 회귀도 포함한다. + +```bash +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationRefreshIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationQueueIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationSourceInvalidationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobSchedulerTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobRetryIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' ktlintCheck +``` + +- 변경 파일: production은 TranslationJobScheduler/TranslationJobRepository 두 파일, 신규 회귀는 ContentTranslationRefreshIntegrationTest 한 파일이다. EntityManager 생성자 주입에 따라 기존 직접 생성 테스트 6파일의 호출 인자만 맞췄다. 이 Progress 외 기존 문서/체크리스트/Gate는 변경하지 않았다. +- 한계: 실제 MySQL REPEATABLE READ 실행, 운영 isolation 설정 확인, 운영 DB/DDL·cloud/provider, 전체 테스트/full check/build 및 이전 전체 focused 회귀 재실행은 하지 않았다. H2 통과를 MySQL RR production proof로 주장하지 않는다. 전체 테스트 사용자 명령은 `./gradlew test`이며 최종 P2 Gate는 부모 검토 대상이다. + +### P4-T1 / P4-T2 구현 및 로컬 검증 완료 — 2026-11-17 + +- 실제 API: `POST /admin/audio-content/translation-requests/{requestId}/generate`의 `{expectedRevision}`와 `GET /{requestId}/candidates?afterCandidateId=&size=50`을 기존 ADMIN controller에 추가했다. 최대 page size는 100이며 조회는 dispatch하지 않는다. 요약 progress는 실제 candidate 상태 집계다. acceptedGenerateRevision replay는 terminal/current revision 거부보다 먼저 판정한다. 모든 individual인 series도 기존 grouping review가 필수다. +- Request 잠금 아래 source snapshot/grouping은 보존하고 generationUnits/provider ID·version/대상별 후보를 같은 transaction에 동결한다. FIELD는 nonblank title/detail/tags 전체 문자열, GROUP_COMMON은 sharedParts 순서 배열, TITLE_RESIDUAL은 member template의 residual 순서 배열이다. literal-only residual과 빈 필드는 paid 작업이 없다. 세 source 언어별 non-source target 전체를 검증했다. +- `TranslationCandidate`/`TranslationCandidateStore`/JPA candidate entity가 작업과 결과를 영속화한다. 고정 unit/provider/language unique, 60초 lease, claim attempt 최대 2, 만료/stale fence의 renew/publish 거부 및 EXECUTION_INTERRUPTED 종결을 구현했다. 모든 후보 terminal이면 전부 실패해도 READY이며 zero-work도 즉시 READY다. 일반 job retry나 전역 cache/framework는 추가하지 않았다. +- 모든 등록 provider를 직접 호출한다. 기존 memory가 있어도 fresh 호출하며 동일 번역 결과의 제공자 출처는 별도 candidate로 남는다. provider 변경/소실은 PROVIDER_CHANGED, count/blank/unchanged AWS tags는 INVALID_PROVIDER_RESULT, provider 예외는 PROVIDER_FAILED다. 외부 예외 원문은 저장·반환하지 않고 current payload/override/translation memory는 변경하지 않는다. +- Ruling: 정확히 같은 입력 배열은 같은 request/provider/version/source/target/kind/field 정책 안에서 선행 candidate ID로 연결한다. 각 member의 unit/input/source 소유권은 독립 row로 보존하고 선행 성공·실패를 같은 transaction에 종결 복사한다. 기존 memory나 다른 요청을 읽지 않는다. 잘못된 판단이면 중복 비용이나 candidate provenance에 영향을 주므로 group 공통 순서, residual 중복 호출 8→6, member 소유권을 실제 H2·fake provider로 확인했다. +- Lock 순서는 request gate → candidate ID 오름차순이다. 선행 candidate보다 나중에 생성한 linked rows만 함께 잠근다. Worker의 짧은 REQUIRES_NEW transaction은 READ_COMMITTED로 제한해 잠금 대기 전의 RR 집계 snapshot이 마지막 READY 전이를 누락하지 않게 했다. 전역 isolation은 바꾸지 않았다. Cancel은 같은 request gate에서 모든 후보를 DISCARDED로 만들고 결과/lease를 폐기하며 fence를 증가시킨다. 취소 commit 이후 새 전송 승인 및 늦은 게시를 거부한다. Network 동안 DB transaction을 유지하지 않는다. +- 같은 Redisson `lock:translation-selection` poller가 candidate 한 건과 preparation 한 건을 처리한다. Preparation은 finally에서 수행하므로 만료 candidate의 복구 소진이 다른 요청 준비를 막지 않는다. 실제 scheduler 검증을 추가했다. DB claim이 실행 소유권의 기준이며 분산 lock만으로 소유권을 추정하지 않는다. +- `TranslateRequest.callControl: TranslationCallControl?`는 기본 null이다. 실제 AWS Translate/Comprehend 공유 client에 요청 execution attribute가 있을 때만 동작하는 `AwsTranslationCallInterceptor.beforeTransmission`을 등록했다. 매 SDK retry를 gate로 검사하며 일반 호출 retry는 유지한다. 실제 SDK + localhost HTTP에서 첫 500 응답 중 cancel DB commit 후 network count 1, 일반 호출은 500→200으로 count 2를 확인했다. Papago translation 각 chunk와 detection도 전송 직전에 gate를 확인한다. 기존 detector callback/cache와 일반 fallback 정책은 유지한다. +- Ruling: 설치된 SDK 2.57.11은 요청별 apiCallTimeout/apiCallAttemptTimeout/putExecutionAttribute를 지원하며 공개 요청별 retryStrategy 및 Apache5 connect/read override를 제공하지 않는다. 따라서 AWS는 기존 공유 transport의 socket 설정을 유지하고 요청별 남은 15초 API/attempt budget으로 제한한다. Papago만 기존 RestTemplate 방식의 admin 전용 transport에 configurable connect 3000ms/read 15000ms를 적용한다. 정상 일반 transport/retry는 바꾸지 않고 새 dependency/client-per-call은 도입하지 않는다. 이 판단이 틀리면 AWS socket 수치 보장에 영향이 있으며 해당 수치를 보장했다고 주장하지 않는다. Papago read timeout도 절대 total wall-clock 15초 보장이 아니다. +- 실제 HTTP timeout 테스트는 Papago 100ms read, AWS 150ms API budget의 짧은 설정으로 응답 보류를 종결하는 것을 확인한다. SDK timeout의 절대 중단 정밀도나 이미 승인된 전송의 과금 취소는 보장하지 않는다. Crash 복구는 이미 청구된 호출을 한 번 더 보낼 수 있다. + +TDD/검증 기록: + +1. 최초 WorkerIntegrationTest에서 미구현 generate HTTP expected 200 / actual 404를 확인했다. 생성 구현 후 worker 미처리의 READY / GENERATING 실패를 확인했고, 취소 미폐기 2개와 residual 중복 호출 expected 6 / actual 8도 RED 후 수정했다. 실제 SDK retry/Papago chunk 제어 테스트는 기대한 제어 예외가 발생하지 않는 RED를 먼저 확인했다. 중간 테스트 Kotlin 문법 오류와 120초 compile timeout은 RED 증거로 세지 않는다. +2. 관련 focused 180개 실행에서 178개가 통과하고 2개가 실패했다. 실패는 P3의 Phase4 이전 404 기대와 AWS local fake의 JSON 응답이었다. 첫 테스트는 실제 REVIEW_REQUIRED 오류·호출 0 검증으로 갱신했다. 두 번째는 실제 SDK가 `Accept: application/cbor`를 사용하는 것을 확인하고 이미 설치된 shaded CBORFactory로 wire 응답을 고쳤다. 제품 SDK/transport는 바꾸지 않았다. +3. 수정한 ADMIN HTTP class 13개가 통과했다. 마지막 직접 회귀는 ControlledProvider 5개, ControlledDetection 2개, Cancel 3개, Worker 4개로 총 14개 failures/errors/skipped 0이다. 마지막 Worker에는 새 복구 소진/preparation 진행 검증 1개가 포함된다. 초기 180개와 이를 합친 고유 범위는 181개이나, 181개 단일 일괄 GREEN 실행으로 표현하지 않는다. 이미 통과한 기능은 반복 실행하지 않았다. +4. 최종 `./gradlew --no-daemon ktlintCheck` BUILD SUCCESSFUL. Kotlin/Java 및 테스트 compilation 완료. 신규 핵심 파일은 WorkerService 158 pure LOC, GenerationService 124, 실제 provider HTTP test 182이며 추가 범용 framework/Any escape/type suppression은 없다. DTO·source 정책·영속 adapter·worker의 책임을 분리하고 P1/P2/P3 경계를 재사용했다. 기존 테스트의 !!/unchecked cast 경고와 Gradle 9 deprecation은 변경 범위 밖으로 남겼다. + +실행 명령: + +```bash +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelection*IntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.*IntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.Controlled*HttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsTranslationServiceTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.PapagoTranslationServiceTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsLanguageDetectionProviderTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.PapagoLanguageDetectionProviderTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsLanguageProviderConfigurationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageDetectionProviderTest' \ + --tests 'kr.co.vividnext.sodalive.content.LanguageDetectionCacheServiceTest' \ + --tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.LanguageProviderCacheEndToEndTest' \ + --tests 'kr.co.vividnext.sodalive.admin.content.AdminContentControllerSecurityTest' +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.ControlledProviderHttpIntegrationTest.shouldPreserveOrdinarySdkRetries' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionHttpIntegrationTest' +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.Controlled*HttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionCancelIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionWorkerIntegrationTest' +./gradlew --no-daemon ktlintCheck +``` + +P5 인계 계약: + +- `TranslationSelectionGenerationService.generate(requestId, expectedRevision): TranslationSelectionRequest`, `TranslationSelectionCandidateQueryService.page(requestId, afterCandidateId, size): TranslationCandidatesResponse`. +- `TranslationSelectionRequest.acceptedGenerateRevision`, `snapshot.generationUnits`, 기존 raw `snapshot.contents`/fingerprints/grouping/templates/providerManifest/targetLanguages를 소비한다. Worker progress는 admin revision을 올리지 않는다. +- `TranslationCandidate`: candidateId/requestId/unit/provider/targetLanguage/status/translatedValues/failureCode/attempt/leaseUntil/fence/terminalAt/linkedCandidateId. Unit은 FIELD/GROUP_COMMON/TITLE_RESIDUAL 및 실제 field/content/group/inputValues/sourceLanguage를 보존한다. P5는 성공 후보의 자기 unit/provenance를 검증하고 기존 P2 writer에 전달할 수 있다. +- `TranslationCandidateStore`의 find/page/lock/progress/save/discard와 request gate를 재사용한다. `TranslationSelectionWorkerService`는 claimNext/runNext/process/authorize/publish를 제공한다. `schema.sql`에 COMMENT와 FK RESTRICT를 포함한 candidate DDL만 작성했으며 실행하지 않았다. + +미실행/지시 이탈: P5 apply/approval endpoint, 전체 test/check/build/bootJar, 운영 MySQL/DDL·실제 AWS/Papago·배포·git/commit 및 reviewer는 실행하지 않았다. H2를 MySQL locking 증거로 주장하지 않는다. LSP 도구가 없어 compilation/lint를 사용했다. 사용자용 전체 테스트 명령은 `./gradlew test`다. SDK 서명 확인에 읽기 전용 explore 하위 에이전트를 1회 사용한 것은 이번 요청의 위임 금지 위반이며 세션 중 고지했다. 해당 agent는 SDK만 읽었고 source/test를 수정하지 않았다. 이후 구현·검증은 직접 수행했다. 승인된 Phase4에서 중단한다. + +### P5-T1 / P5-T2 로컬 구현 및 검증 완료 — 2026-11-17 + +- [x] P5-T1 RED: 실제 HTTP `/apply` 미구현 404를 확인했다. Provider manifest와 exact raw fingerprint 검증을 각각 제거한 변이에서는 provider version, raw 공백 변경, 원본 언어 변경의 3개 assertion 실패를 확인하고 원래 구현을 복구했다. +- [x] P5-T1 GREEN: FIELD 및 TITLE_GROUP의 one-shot subset을 request → Series → CONTENT 오름차순 잠금 안에서 검증하고 payload·override·receipt·미선택 후보 폐기를 한 transaction으로 저장했다. 불완전 그룹, 후보 소유권·성공 상태·frozen manifest/input/언어 불일치, 선택 원문 또는 활성 membership 변경은 쓰기 없이 거부한다. +- [x] P5-T1 직접 회귀: 콘텐츠·언어 bundle별 approve 1회로 합쳐 미선택 문자열을 보존하며 없는 locale은 현재 원문 fallback으로 초기화한다. Group은 기존 reviewed template.render로 선언된 shared 배열 순서와 원문 배치를 보존한다. Literal-only member에는 common ID만 기록한다. 선택 alias는 복사된 결과와 자기 ID를 유지하며 미선택 leader의 폐기와 독립적이다. +- [x] P5-T2 RED/GREEN: HTTP CONTENT 전체 흐름, 여러 그룹·개별 제목이 섞인 SERIES 전체 흐름, cancel, 불완전 그룹의 무쓰기 거부, stable typed errors, ADMIN guard, 원문 변경 후에도 불변인 receipt GET/replay를 확인했다. 지원하지 않는 `fr`의 INVALID_REQUEST 기대가 CANDIDATE_NOT_SELECTABLE로 실패한 뒤 입력 경계에서 보정했다. +- [x] P5-T2 검증: 관련 고유 170개 케이스를 검증했다. 최초 170개 실행에서 20개 실패가 있었으며 아래 원인을 수정한 뒤 해당 5개 class 42개가 failures/errors/skipped 0으로 통과했다. 나머지 128개는 앞 실행의 통과 증거를 유지하고 반복하지 않았다. 단일 실행의 170개 GREEN으로 표현하지 않는다. 마지막 `ktlintCheck`는 BUILD SUCCESSFUL이다. +- [ ] P5-GATE 부모 최종 검토: 사용자의 지시에 따라 외부 reviewer를 호출하지 않았다. 전체 QA/build 및 최종 review 판정은 부모 담당자에게 인계한다. 기존 상단 표·체크박스와 이전 완료 기록은 변경하지 않았다. + +실제 경계: + +1. `TranslationSelectionApplyService.apply(requestId: Long, adminId: Long, body: ApplyTranslationSelectionRequest): TranslationSelectionApplyReceipt`는 REQUIRED transaction을 소유한다. Body는 `operationId`, `expectedRevision`, sealed `TranslationSelectionChoice.Field/TitleGroup`이며 residual choice는 `contentId`, nullable `candidateId`다. 번역문 입력이나 Any payload는 없다. +2. Request 잠금 안에서 operation/body SHA-256 replay를 상태·revision보다 먼저 판정한다. FIELD/group/residual의 의미상 집합 순서만 canonical 정렬하며 중복 자체는 제거하지 않는다. 다른 operation은 terminal에서 REQUEST_CLOSED, 같은 operation의 다른 body는 IDEMPOTENCY_CONFLICT다. 요청 생성자 소유권을 추가하지 않고 ADMIN acting member ID를 provenance에 저장한다. +3. 최종 판정은 기존 `ContentTranslationSourceService.lockScope(scope)` 이후의 새 source/활성 연결 목록으로 한다. FIELD는 자기 필드와 현재 자격만 검사하여 다른 필드 수정·다른 member 추가를 허용한다. 선택 TITLE_GROUP은 전체 frozen ACTIVE series membership과 모든 member의 title/language를 검사한다. 잠금 전 managed source/tag 연관이 남은 경우와 원문 수정 commit을 기다린 경우도 실제 H2 transaction으로 검증했다. +4. `ContentTranslationWriteService.approve(contentId, locale, approvals)`를 유지하고 명시적 `approvedAt: LocalDateTime`을 받는 overload를 추가했다. Apply는 한 번 초 정밀도로 정규화한 시각을 모든 bundle 및 receipt에 전달한다. `TranslationCandidateStore.discardUnselected(requestId, selectedIds: Set, now): Int`는 선택 ID를 보존하고 논리 폐기 개수를 반환하며 기존 discard-all은 cancel만 사용한다. +5. 기존 예약 컬럼 apply_operation_id/apply_body_hash/apply_receipt/applied_at을 domain/JPA/typed JSON converter/response에 연결했다. 새 DDL·중복 컬럼은 없다. Snapshot provider version은 apply에서 변경하지 않는다. Receipt는 최종 필드 값·실제 candidate IDs/providers·초 정밀도 시각·폐기 수를 같은 transaction에 저장하고 원본 변경 뒤에도 그대로 반환한다. + +회귀 수정 기록: + +- 최초 넓힌 focused 실행의 20개 실패 원인은 새 시각 인자의 Kotlin default expression `nowProvider()`였다. 생성된 static approve$default가 Spring CGLIB proxy의 미초기화 backing field를 읽어 NPE가 발생했다. 실패 stack은 `ContentTranslationWriteService.approve$default`와 기존 3인자 호출을 직접 가리켰다. Timestamp 자체나 기존 테스트를 완화하지 않았다. +- 기본 인자 expression을 제거하고 기존 3인자 transactional 메서드 안에서 clock을 읽어 4인자 overload로 전달했다. 시각을 명시한 apply 경로와 기존 호출의 transaction 참여를 유지한다. 직접 영향 42개에는 Override 10, SourceInvalidation 13, Queue 7, 기존 feature Worker 4, Contents HTTP 8이 포함된다. +- 초기 compile/test 결합 240초 timeout은 성공이나 RED 증거로 세지 않았고 실행 프로세스 종료 후 더 긴 한도의 focused 명령으로 완료했다. 중간 lint의 새 코드 포맷·미사용 import를 apply_patch로 수정했다. 마지막 잔여 if branch brace도 수정하고 최종 lint가 통과했다. + +집중 검증 명령과 증거: + +```bash +# 최초 관련 170개: 150 통과, 20 실패. 아래 42개 보정 재검증과 함께 해석한다. +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelection*IntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.*IntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationOverrideIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationSourceInvalidationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationQueueIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' ktlintCheck +# 보정 후 42개 및 ktlintCheck: BUILD SUCCESSFUL, failures/errors/skipped 0. +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationOverrideIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationSourceInvalidationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationQueueIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionWorkerIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.adapter.in.web.AdminTranslationSelectionContentsHttpIntegrationTest' ktlintCheck +``` + +- 신규 P5 케이스는 56개: Apply 20, Group 15, Concurrency 7, Apply HTTP 10, Receipt HTTP 3, 기존 Admin HTTP에 추가한 CONTENT 전체 흐름 1이다. 기존 ADMIN guard의 세 역할은 apply도 검사하도록 확장했다. Group HTTP는 공통 Papago+member별 AWS/Papago 출처, 여러 그룹·언어·개별 제목, 일부 언어 미선택, 불완전 요청 실패 후 같은 operation의 정상 적용을 확인한다. +- CountDownLatch로 두 관리자 요청의 later-commit-wins와 일반 materializer 경쟁, apply/cancel 양쪽 commit 순서, source mutation 대기를 제어했다. 실제 DB payload·override·candidate 상태·receipt를 확인하며 mock 반환값을 assertion하지 않는다. 외부 transaction rollback은 네 저장 결과를 모두 되돌린다. +- 나노초 0/123456789/999999999의 23:59:59 입력을 실제 flush/clear·재조회에 통과시켰고 override/applied_at/receipt와 HTTP GET·POST replay가 정확히 `2026-11-17T23:59:59Z`에 일치했다. 현재 source를 이후 바꿔도 영수증은 불변이다. +- 구조 대조: 새 production 최대 197 pure LOC, 새 테스트 최대 197 pure LOC다. 기존 Admin HTTP는 231 pure LOC로 경고 구간이며 다음 증설 시 동작별 HTTP class로 분리한다. 기존 대형 SodaMessageSource는 네 필수 message key만 수정했다. 책임은 적용 orchestration/typed 입력/영속화/HTTP로 나누고 P1 render·P2 writer·P3 lockScope를 재사용했다. 불필요한 fallback/retry/helper/type suppression/새 로그는 추가하지 않았다. 승인 시각의 네 번째 인자는 여러 bundle과 receipt의 같은 확정 시각을 보장하기 위한 실제 호출 입력이다. + +변경 파일: production root는 `src/main/kotlin/kr/co/vividnext/sodalive/`, test root는 `src/test/kotlin/kr/co/vividnext/sodalive/`다. + +```text +production (11) +v2/contenttranslation/application/TranslationSelectionApplyService.kt (new) +v2/contenttranslation/application/ContentTranslationWriteService.kt +v2/contenttranslation/dto/ApplyTranslationSelectionRequest.kt (new) +v2/contenttranslation/dto/TranslationSelectionResponse.kt +v2/contenttranslation/domain/TranslationSelectionRequest.kt +v2/contenttranslation/port/TranslationCandidateStore.kt +v2/contenttranslation/adapter/in/web/AdminTranslationSelectionController.kt +v2/contenttranslation/adapter/out/persistence/JpaTranslationCandidateStore.kt +v2/contenttranslation/adapter/out/persistence/JpaTranslationSelectionStore.kt +v2/contenttranslation/adapter/out/persistence/TranslationSelectionRequestEntity.kt +i18n/SodaMessageSource.kt +tests (9) +v2/contenttranslation/application/TranslationSelectionApplyIntegrationTest.kt (new) +v2/contenttranslation/application/TranslationSelectionApplyGroupIntegrationTest.kt (new) +v2/contenttranslation/application/TranslationSelectionApplyConcurrencyIntegrationTest.kt (new) +v2/contenttranslation/application/TranslationSelectionApplyTestSupport.kt (new) +v2/contenttranslation/application/TranslationSelectionTestConfiguration.kt +v2/contenttranslation/adapter/in/web/AdminTranslationSelectionHttpIntegrationTest.kt +v2/contenttranslation/adapter/in/web/AdminTranslationSelectionApplyHttpIntegrationTest.kt (new) +v2/contenttranslation/adapter/in/web/AdminTranslationSelectionReceiptHttpIntegrationTest.kt (new) +v2/contenttranslation/adapter/in/web/TranslationSelectionApplyHttpTestSupport.kt (new) +docs (2) +docs/20261117_관리자번역후보선택/api-contract.md +docs/20261117_관리자번역후보선택/plan-task.md +``` + +미실행: 전체 test/check/build/bootJar, 변경하지 않은 provider transport tests의 재실행, 실제 cloud/provider, production/MySQL/DDL, 배포·활성화, git/commit/delegation, 외부 최종 검토. LSP diagnostics 도구가 없어 Kotlin/Java compilation 및 lint를 사용했다. 기존 다른 테스트의 !!/unchecked cast와 Gradle 9 deprecation은 범위 밖이다. H2 결과는 MySQL isolation/잠금 증거가 아니며 부모 P6 QA/build/final review와 운영 검증으로 인계한다. 전체 테스트 사용자 명령은 `./gradlew test`다. + +### P5-R1 최종 Gate 회귀 보정 — 부분 적용 뒤 변경 필드 자동 재료화 — 2026-11-18 + +**목표:** P5 subset apply가 만든 기존 locale payload에서 일반 원문 수정으로 예약된 필드만 게시하고 실제 게시된 job만 완료한다. P2의 엄격한 전체 재료화, 새 payload 완성 조건, 부모 잠금 및 재료화/작업 완료의 같은 transaction을 유지한다. + +- [x] RED: `TranslationSelectionRefreshIntegrationTest`를 실제 apply → `AudioContentService.modifyAudioContent` → 일반 `TranslationJobWorker`로 실행해 3개 assertion 실패를 확인했다. title/detail만 승인한 뒤 tags memory가 없는 경우 제목은 `Edited title` 대신 `수정 제목`에 머물렀다. title/tags 변경 중 tags provider가 실패한 경우도 제목이 게시되지 않았고, locale payload가 없는 경우에는 게시 없이 title job이 COMPLETED가 됐다. +- [x] GREEN: 기존 writer에 `materialize(contentId, locale, fields: Set)` overload를 추가했다. 기존 locale의 명시 필드만 현재 승인/메모리로 계산하고 기존 merge로 저장한다. Locale row가 없으면 모든 필드를 요구한다. 기존 2인자 materialize 및 기존 resource materialize는 전체 필드 조건을 유지한다. +- [x] Worker 연결: `TranslationReadModelMaterializer.materializeContentFields(resourceId, targetLanguage, fieldKeys)`로 CONTENT 성공 job의 필드 집합을 전달한다. 일부 provider 실패에도 성공 필드를 먼저 실제 게시한 뒤 같은 transaction에서 그 job만 완료한다. 게시 불가 시 성공 job도 재시도하며 provider 실패 job은 기존 실패 정책을 따른다. CONTENT 이외 분기와 provider I/O 경계는 변경하지 않았다. +- [x] 직접 회귀: 신규 4개, 기존 Queue 7개, Worker 13개가 통과했다. 추가 영향 범위 Apply 20, Override 10, SourceInvalidation 13, 기존 Refresh 7, CONTENT 상세 HTTP 22, ContentTag 11, SERIES 상세 HTTP 15개가 통과했다. 서로 다른 두 focused 실행의 합계 122개이며 전체 suite 성공을 뜻하지 않는다. +- [x] 최종 lint: `ktlintCheck` BUILD SUCCESSFUL. 첫 GREEN 실행은 테스트 24개가 통과했으나 새 테스트의 assert 줄바꿈으로 lint만 실패했다. 해당 포맷을 수정하고 나머지 98개 실행과 함께 최종 lint를 통과했다. 이미 통과한 24개는 반복 실행하지 않았다. +- [ ] 부모의 delta 최종 검토: 이 수정의 외부 재검토와 관리 HTTP 27개/bootJar 새 검증은 부모 담당자 범위다. 이 단위에서 수행하지 않았다. + +수정 경계와 불변식: + +- Production은 `v2/contenttranslation/application/ContentTranslationWriteService.kt`, `i18n/translation/TranslationReadModelMaterializer.kt`, `i18n/translation/TranslationJobWorker.kt` 세 파일만 변경했다. SourceInvalidation의 changed-field-only enqueue, 상세 shortcut, provider, queue identity, DTO/DDL은 변경하지 않았다. 새 framework/flag/cache 채움은 없다. +- Writer는 CONTENT 부모 잠금과 refresh 이후 source와 locale 존재를 current locking read로 확인한다. 현재 source와 정확히 일치하는 field approval만 사용한다. 선택하지 않은 payload는 다른 메모리가 없거나 있어도 byte-for-byte 유지한다. 두 인자 전체 재료화는 기존 payload에서도 미준비 tags memory를 허용하지 않는다. +- 신규 테스트 `v2/contenttranslation/application/TranslationSelectionRefreshIntegrationTest.kt`의 4개는 missing tags memory와 현재 detail 승인 보존, cached-but-unselected tags의 정확한 문자열 보존, provider 부분 실패 시 기존 payload의 성공 필드 게시, 새 payload 미완성 시 job 미완료를 확인한다. Fake provider callback에서 일반 번역 I/O 중 transaction 부재를 검사하고 DB payload/override/jobs/memory를 assert한다. H2의 claim syntax만 기존 test 관례대로 `skip locked` 없이 실행하며 claim 결과와 모든 DB 쓰기는 실제 구현이다. +- 기존 `ContentTranslationQueueIntegrationTest`의 latch를 새 CONTENT 재료화 호출 경계에 연결하여 source mutation과 materialize/complete의 같은 transaction 회귀를 유지했다. `TranslationJobWorkerTest`는 기존 mock/verify의 CONTENT 호출 signature만 5곳 변경했으며 assertion을 삭제하거나 약화하지 않았다. +- 구조 대조: writer 128, worker 118, materializer 216, 신규 테스트 126 pure LOC다. Materializer 216과 기존 Queue test 209는 경고 구간이며 다음 증설 시 책임별 분리를 검토한다. 기존 WorkerTest 285는 줄 수를 늘리지 않고 호출 signature만 맞췄다. 단일 차단 수정 범위 밖의 파일 분리는 하지 않았다. 새 약한 타입/Any/예외 suppression/로그/중복 writer는 없고, job의 기존 문자열 field key는 materializer 경계에서 enum set으로 변환한다. + +실행 명령: + +```bash +# RED: 3개 assertion 실패, production 변경 전. +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionRefreshIntegrationTest' +# GREEN: 신규 4 + Queue 7 + Worker 13 = 24개 통과. 이 실행의 lint 포맷 오류는 아래 최종 실행에서 보정했다. +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionRefreshIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationQueueIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobWorkerTest' ktlintCheck +# 직접 영향 98개, failures/errors/skipped 0 및 최종 ktlintCheck 통과. +./gradlew --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.TranslationSelectionApplyIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationOverrideIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationSourceInvalidationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.application.ContentTranslationRefreshIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.content.AudioContentDetailTranslationHttpIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' \ + --tests 'kr.co.vividnext.sodalive.content.ContentSeriesDetailTranslationHttpIntegrationTest' ktlintCheck +``` + +미실행: 전체 test/check/build/bootJar, 부모 소유 관리 HTTP 27개 재실행, 실제 provider/cloud/production DB, Git/commit/delegation 및 외부 재검토. LSP diagnostics 도구가 없어 실제 Kotlin/Java compilation과 lint로 검사했다. 운영 MySQL 잠금/isolation은 H2 결과로 보증하지 않는다. 기존 Gradle 9 deprecation은 그대로다. 전체 테스트 사용자 명령은 `./gradlew test`다. + +### 사용자 요청에 따른 커밋 전 검증 — 2026-11-18 + +- `/Users/klaus/.agent-commands/commit-with-validation.md`와 저장소 커밋 규칙에 따라 기존 변경을 확인했다. 구현 코드는 추가로 수정하지 않았다. +- 아래 명령으로 관리자 번역 선택 기능과 실제 로컬 provider HTTP 전송 제어를 검증했다. + +```bash +./gradlew --offline --no-daemon test \ + --tests 'kr.co.vividnext.sodalive.v2.contenttranslation.*' \ + --tests 'kr.co.vividnext.sodalive.i18n.translation.Controlled*HttpIntegrationTest' \ + ktlintCheck +``` + +- 결과: BUILD SUCCESSFUL in 2m 4s. HTML 테스트 보고서 기준 218개, 실패 0, ignored 0. `ktlintCheck`는 UP-TO-DATE이며 `git diff --check`도 통과했다. +- 구현 커밋: `a3c76a1b` 제공자 호출 제어, `9d8bc914` 관리자 후보 선택·필드 승인 보호. 두 커밋 모두 ktlint hook 및 커밋 전·후 메시지 검증 PASS. 문서와 DDL은 별도 문서 커밋으로 기록한다. +- 전체 테스트와 운영 MySQL·실제 cloud 호출·DDL·배포는 실행하지 않았다. 기존 직접 영향 회귀와 bootJar 증거는 위 실행 이력을 유지한다. 전체 테스트 사용자 실행 명령은 `./gradlew test`다. diff --git a/docs/20261117_관리자번역후보선택/prd.md b/docs/20261117_관리자번역후보선택/prd.md new file mode 100644 index 00000000..8d993054 --- /dev/null +++ b/docs/20261117_관리자번역후보선택/prd.md @@ -0,0 +1,152 @@ +# 관리자 번역 후보 선택 및 시리즈 제목 그룹화 PRD + +## 문서 정보 + +| 항목 | 내용 | +|---|---| +| 문서 상태 | 서버 구현 및 DEC-11 플래그 제거·로컬 검증·부모 직접 검토 완료, 운영 적용 미실행 | +| 작성일 | 2026-11-17 | +| 최종 수정일 | 2026-11-18 | +| 대상 제품 | 관리자 다중 제공자 번역 후보 선택 및 시리즈 제목 그룹화 | +| 작성자·결정권자 | 제품 결정권자: 사용자 인터뷰 확인 사항 | +| 관련 API Contract | [api-contract.md](api-contract.md), 9개 endpoint 구현 완료 | +| 관련 구현 계획 | [plan-task.md](plan-task.md), P1~P5 완료, P7 자동 등록 변경 및 별도 운영 전제 | +| 관련 review | [설계 검토](reviews/design-review.md), [구현 검토·QA](reviews/implementation-review.md) | + +### 요구사항 상태 + +이 문서는 제품 동작에 대한 인터뷰 확정사항을 기록한다. API 계약과 기술 설계 제안은 사용자가 승인했으며 서버 구현과 focused tests를 시작하도록 명시적으로 승인했다. 승인 범위는 로컬 서버 구현과 focused tests이며 production DDL/deploy/git commit은 포함하지 않는다. 승인된 활성-only series 구성원, one-shot subset apply, 자유 형식 번역문 제외 결정을 유지한다. + +## 1. 개요 + +관리자는 단일 콘텐츠 또는 시리즈의 현재 활성 구성원 전체를 대상으로 번역 후보를 검토하고 선택할 수 있어야 한다. 시리즈에서는 실제 제목을 분석해 반복되는 공통 제목 구간을 묶고, 공통 구간과 개별 제목의 번역을 분리해 관리한다. 선택한 값만 적용하며, 기존 자동 번역과 관리자의 필드별 수정 상태를 보존한다. + +## 2. 문제 + +관련 에피소드 제목의 번역이 서로 일관되지 않을 수 있다. 기존 단일 번역 흐름만으로는 여러 번역 제공자의 결과를 비교하거나 시리즈 제목의 공통 부분을 함께 검토하기 어렵다. 관리자가 결과를 검토하기 전에 자동으로 값을 덮어쓰면 원치 않는 번역 변경이 발생할 수 있다. + +## 3. 목표 + +- 관리자가 번역 제공자별 후보를 비교하고 대상 필드에 적용할 후보를 선택한다. +- 시리즈 구성원 제목에서 공통 구간과 개별 구간을 검토하고, 공통 구간 번역을 그룹 단위로 적용한다. +- 분석·생성 결과를 검토하고 명시적으로 선택하기 전까지 기존 번역 결과를 유지한다. +- 일부 필드만 적용할 수 있고, 미선택 필드는 현재 값을 유지한다. + +## 4. 범위 제외 + +- 자유 형식의 번역문을 직접 입력·편집하는 기능은 현재 요청에 포함되지 않아 설계에서 제외한다. 이는 별도 인터뷰에서 거부된 기능이라는 뜻이 아니다. 원문 그룹과 구간(span)을 조정하는 편집은 포함한다. +- 전역 초기화 기능, 새 번역 제공자 추가, 원작 관련 동작, 용어집 또는 LLM 시스템 도입. +- 프론트엔드 코드 구현과 UI 시각 스타일 규격. +- 실제 운영 환경에서의 번역 정확도 및 처리량 보장. 현재 근거가 확인되지 않았으며 제품 요구 확정을 막는 질문으로 취급하지 않는다. + +## 5. 사용자와 권한 + +| 사용자 | 목표 | 주요 작업 | +|---|---|---| +| 관리자 | 번역 결과의 일관성과 정확성을 통제 | 대상 선택, 분석 검토·수정, 필드별 후보 선택, 취소 및 적용 | + +이 기능은 기존 관리자 권한 경계 안에서 제공한다. 인증·인가의 구체적인 계약은 기존 시스템과의 연동 설계에서 확인한다. + +## 6. 핵심 흐름 + +1. 관리자가 단일 콘텐츠 또는 시리즈를 선택한다. 시리즈 대상은 요청 생성 시점의 현재 활성 구성원 전체다. +2. 시스템이 시리즈 제목을 분석해 반복되는 공유 구간과 각 제목의 고유 구간을 제시한다. 고정된 EP 표기 규칙을 전제로 하지 않는다. +3. 관리자는 생성 전에 분석 결과를 검토하고, 원문 그룹과 구간을 조정하거나 특정 콘텐츠를 그룹에서 제외해 개별 처리 대상으로 바꿀 수 있다. 생성 뒤에는 그룹을 수정할 수 없으며, 수정하려면 요청을 취소하고 새 요청을 만든다. +4. 시스템은 제목·상세·태그와 원본 언어를 제외한 지원 언어에 대해 등록된 각 제공자를 독립적으로 새로 호출한다. 이전 결과는 적용 전까지 유지한다. +5. 관리자는 제공자 출처를 확인하고 적용할 후보의 필드와 언어를 선택한다. 같은 후보는 제공자 출처를 모두 보존한 채 묶어 표시할 수 있다. 제공자별 실패도 결과에 표시한다. +6. 관리자는 검토 또는 생성 중 취소하거나 선택한 일부 후보를 한 번에 적용한다. 적용에서 생략한 후보는 폐기되고, 미선택 번역 값은 그대로 둔다. + +## 7. 기능 요구사항 + +### 7.1 대상과 분석 + +| ID | 상태 | 요구사항 | 수용 기준 | +|---|---|---|---| +| TR-01 | 확정 | 단일 콘텐츠 대상은 해당 콘텐츠의 제목, 상세, 태그 번역 필드를 처리할 수 있어야 한다. | 선택한 단일 콘텐츠의 세 필드를 번역 후보 대상으로 지정할 수 있다. | +| TR-02 | 확정 | 시리즈 대상은 현재 연결된 활성 구성원 전체의 제목, 상세, 태그 번역 필드를 포함해야 한다. 비활성 구성원은 제외한다. | 요청 생성 시 활성 연결 콘텐츠를 빠짐없이 포함하고 비활성 콘텐츠는 후보 생성과 제목 분석에서 제외한다. | +| TR-03 | 확정 | 시리즈 제목 분석은 실제 제목들을 바탕으로 반복되는 공유 구간과 고유 구간을 식별해야 한다. | 임의의 제목 형식에 적용할 수 있으며 고정된 EP 번호 parsing 규칙을 요구하지 않는다. | +| TR-04 | 확정 | 관리자는 번역 후보 생성을 시작하기 전에 그룹 분석 결과를 검토하고 원문 그룹과 구간(span)을 수정할 수 있어야 한다. | 생성 전에 분석을 검토하고 수정한 그룹·구간을 기준으로 다음 단계에 진입할 수 있다. 생성 이후 그룹 수정은 취소 후 새 요청에서만 가능하다. | +| TR-05 | 확정 | 관리자는 후보 생성을 시작하기 전에 콘텐츠를 공통 제목 그룹에서 제외해 개별 처리 대상으로 바꿀 수 있어야 한다. | 제외된 콘텐츠의 제목은 공통 그룹 적용 대상이 되지 않고 개별 후보로 처리된다. 생성 이후 변경은 취소 후 새 요청에서 가능하다. | +| TR-06 | 확정 | 단일 콘텐츠 번역을 먼저 해야 시리즈 번역을 시작할 수 있다는 순서 제약을 두지 않는다. | 시리즈 대상 처리를 단일 콘텐츠 처리 완료 여부에 종속하지 않는다. | + +### 7.2 후보 생성과 검토 + +| ID | 상태 | 요구사항 | 수용 기준 | +|---|---|---|---| +| TR-07 | 확정 | 제목·상세·태그 전체와 원본 언어를 제외한 지원 대상 언어에 대해 등록된 모든 제공자를 각각 새로 호출해야 한다. | 후보 생성은 일부 필드·언어만 선택하도록 요구하지 않는다. 기존 후보를 재사용해 새 요청을 생략하지 않는다. 각 제공자 결과는 출처와 연결된다. | +| TR-08 | 확정 | 새 결과가 생성되는 동안 기존 번역 결과를 유지해야 한다. | 관리자가 새 후보를 선택해 적용하기 전에는 기존 결과가 바뀌지 않는다. | +| TR-09 | 확정 | 후보는 필드별로 제공자를 선택할 수 있어야 한다. | 제목, 상세, 태그 등 각 필드의 선택이 다른 필드 선택에 종속되지 않는다. | +| TR-10 | 확정 | 동일한 후보 텍스트를 제공자 출처를 보존한 채 묶어 표시할 수 있어야 한다. | 묶인 후보의 모든 제공자 출처를 확인할 수 있다. 동일 결과라는 이유로 출처 정보를 버리지 않는다. | +| TR-11 | 확정 | 제공자 실패를 관리자에게 표시해야 한다. | 실패한 제공자와 실패 상태를 확인할 수 있고, 다른 제공자의 후보는 계속 검토할 수 있다. | +| TR-12 | 확정 | 기존 번역의 제공자 출처가 알려져 있지 않을 수 있음을 허용해야 한다. | 출처 불명인 기존 값에 특정 제공자를 추정해 표시하지 않는다. | +| TR-13 | 확정 | 원본 언어가 사용 가능하면 그 값을 사용하고, 정확한 원본 언어를 일상적으로 다시 감지하지 않는다. | 기존 원본 언어 정보를 사용할 수 있는 상황에서 매번 재감지를 요구하지 않는다. | + +### 7.3 적용, 취소 및 데이터 보존 + +| ID | 상태 | 요구사항 | 수용 기준 | +|---|---|---|---| +| TR-14 | 확정 | 공통 제목 후보의 선택과 적용은 그룹 및 언어 단위로 하나의 불가분 작업이어야 한다. | 공통 제목 그룹의 특정 언어에 대해 선택한 공통 후보가 해당 그룹에 함께 적용된다. | +| TR-15 | 확정 | 관리자는 후보 생성 전에 개별 콘텐츠를 공통 그룹에서 제외할 수 있어야 한다. | 제외한 콘텐츠는 공통 후보 적용에서 빠지고 나머지 그룹 구성원은 그룹 단위 적용을 유지한다. 생성 후 그룹 편집은 취소와 새 요청이 필요하다. | +| TR-16 | 확정 | 관리자는 생성된 전체 후보 중 일부만 선택해 한 번 적용할 수 있어야 한다. 적용은 요청을 닫고 나머지 후보를 폐기한다. | 미선택 필드·언어 값은 기존 값을 유지한다. 요청을 닫은 뒤 누락 후보를 같은 요청에서 다시 적용할 수 없다. | +| TR-17 | 확정 | 관리자는 분석, 제공자 요청 실행, 결과 검토 단계까지 취소할 수 있어야 한다. | 각 단계에서 적용을 확정하지 않고 취소할 수 있다. 이미 비용이 발생한 진행 중 외부 요청은 취소로 되돌릴 수 없음을 사용자 흐름에서 알 수 있어야 한다. | +| TR-18 | 확정 | 관리자가 적용한 값은 해당 필드의 관리자 재정의로 보호되어야 한다. | 보호는 필드 단위이며 적용하지 않은 필드에는 새 보호 상태를 만들지 않는다. | +| TR-19 | 확정 | 보호된 필드의 원본이 변경되면 그 필드의 관리자 재정의만 해제하고 일반 자동 번역을 재개해야 한다. | 원본 변경 시 해당 필드만 보호가 해제된다. 변경되지 않은 다른 필드의 관리자 값은 계속 보호된다. | +| TR-20 | 확정 | 후보 생성 후 원본이 변경된 필드에는 해당 필드의 이전 후보를 적용할 수 없어야 한다. | 원본 변경 후 해당 필드의 후보 적용이 거부되거나 무효임을 검토 흐름에서 분명히 확인할 수 있다. | + +## 8. 수용 기준 + +- 관리자는 단일 콘텐츠의 제목·상세·태그와 시리즈의 현재 활성 연결 콘텐츠 전체의 같은 번역 필드를 대상으로 선택할 수 있다. +- 실제 제목이 정해진 EP 형식과 다르더라도 공유 구간과 고유 구간을 검토할 수 있으며, 관리자는 후보 생성 전 그룹과 구간을 수정하거나 항목을 개별 처리로 제외할 수 있다. +- 모든 등록 제공자가 각자 새로 요청되며, 제공자별 결과·실패와 후보 출처가 구분되고, 같은 후보가 묶여도 출처가 보존된다. +- 새 후보를 선택하기 전의 기존 번역은 유지되고, 관리자는 필드별로 선택할 수 있다. +- 후보 생성은 모든 세 필드와 원본 언어를 제외한 지원 언어를 대상으로 한다. 공통 제목 후보는 그룹 및 언어 단위로 적용되며, 개별 제외와 일부 선택 적용이 가능하다. +- 한 번의 일부 적용 후 요청이 닫히고 미선택 후보는 폐기된다. +- 분석·요청 실행·검토 중 취소할 수 있다. 취소는 이미 비용이 발생한 진행 중 제공자 요청을 되돌리지 않는다. +- 적용된 필드의 관리자 보호는 원본 변경 시 그 필드에 한해 해제되고, 다른 변경되지 않은 필드는 보호 상태를 유지한다. +- 후보 생성 후 원본이 변경된 필드에는 이전 후보를 적용할 수 없다. + +## 9. 미결 기술 설계와 확인 경계 + +제품 동작 요구와 후속 설계/API 계약은 승인되었으며 9개 서버 endpoint를 구현했다. [plan-task.md](plan-task.md)에 단계별 검증과 최종 gate 보정을 기록했다. DEC-11에 따라 API와 후보 worker는 별도 설정 없이 기동 시 등록한다. 새 writer의 작업 생성 전 스키마·구 writer 종료·구 index 제거가 필요하며 프론트엔드 코드는 이번 범위 밖이다. + +다음은 인터뷰에서 사용자가 선택한 제품 동작이 아니라 기술 제안이다: 제목 구간 분석·경계 규칙, 비동기 작업·부분 실패 표현, source freshness 검증, 관리자 재정의 저장과 materializer 연동, endpoint 및 프론트엔드 interaction. 세부 운영 정확도와 처리량은 실측 전까지 검증되지 않았으며 현재 제품 질문을 열어두는 이유는 아니다. + +기존 번역의 제공자 출처는 불명일 수 있다. 제품 요구는 출처를 추정하지 않는 것이며, 기존 데이터의 출처 복구나 일괄 보정은 범위에 포함하지 않는다. + +## 10. 요구사항 상태 및 준비도 + +| 구분 | 상태 | +|---|---| +| 제품 요구사항 | 인터뷰 결정으로 확정 | +| 기술 설계 및 기존 시스템 연동 | 구현·로컬 검증 완료 | +| API 계약 | 9개 endpoint 구현, 실제 HTTP 검증 완료 | +| 구현 계획/TASK | P1~P5 및 P7-T1 로컬 구현·검증 완료, P7-GATE 대기, 운영 checklist 별도 | +| 구현 | P1~P5 최종 gate APPROVE, P7 별도 검토 대기, 운영 DDL/배포 미실행 | + +요구사항 명확도 점수는 인터뷰 단계의 휴리스틱 평가다. 모호성 0.10, 목표 0.95, 범위 0.95, 제약 0.90, 성공 기준 0.90, 기존 맥락 0.75. 이 점수는 기술 설계 완료나 구현 착수를 뜻하지 않는다. + +## 11. 인터뷰 결정 로그 + +| 날짜 | ID | 상태 | 결정 | 영향 | +|---|---|---|---|---| +| 2026-11-17 | DEC-01 | 정정 전 제안 | 단일 콘텐츠는 제목·상세·태그, 시리즈는 연결 콘텐츠의 같은 필드를 대상으로 한다. 초안의 비활성 포함은 사용자 확인 없이 추가된 제안이었으며 DEC-09로 정정한다. | TR-01, TR-02 | +| 2026-11-17 | DEC-02 | 확정 | 모든 필드와 원본 언어 외 지원 언어의 후보 생성을 요청하고, 등록된 제공자를 독립적으로 새로 호출한다. 적용 전까지 기존 값을 유지한다. 같은 후보는 출처를 보존해 묶을 수 있고, 실패를 표시한다. 기존 출처는 알 수 없을 수 있다. | TR-07~TR-12 | +| 2026-11-17 | DEC-03 | 확정 | 원본 언어가 사용 가능하면 사용하고, 맞는 값을 일상적으로 재감지하지 않는다. | TR-13 | +| 2026-11-17 | DEC-04 | 확정 | 제목은 고정 EP parsing이 아니라 실제 제목의 반복 공유 구간과 고유 구간을 분석한다. 생성 전에 관리자가 원문 그룹·구간을 수정하고 항목을 개별 처리로 제외할 수 있다. | TR-03~TR-06 | +| 2026-11-17 | DEC-05 | 확정 | 후보 생성은 전체 대상 필드·지원 언어를 포함한다. 관리자는 필드별 후보를 선택하며 공통 제목은 그룹 및 언어 단위로 함께 선택·적용한다. 개별 제외는 생성 전에 한다. | TR-07, TR-09, TR-14, TR-15 | +| 2026-11-17 | DEC-06 | 확정·보완 | 일부 선택 적용과 적용 전 취소를 허용한다. 미선택 번역 값은 유지하며 이미 전송된 요청 비용은 되돌릴 수 없다. 한 번 적용 후 종료 정책은 후속 DEC-10에서 별도로 확정했다. | TR-16, TR-17 | +| 2026-11-17 | DEC-07 | 확정 | 적용된 관리자 보호는 필드별이다. 원본 변경 시 변경된 필드만 보호를 풀고 자동 번역을 재개하며, 변경되지 않은 필드는 보호한다. 후보 생성 후 원본이 바뀐 필드에는 해당 필드의 이전 후보를 적용할 수 없다. | TR-18~TR-20 | +| 2026-11-17 | DEC-08 | 확정 | 이번 문서 범위는 요구사항과 별도 제안 설계다. 설계/API 계약/계획은 사용자 검토 전 제안 상태이고 구현은 시작하지 않는다. | 문서 상태, 후속 문서 링크 | +| 2026-11-17 | DEC-09 | 확정 | 추가 인터뷰에서 시리즈는 활성 콘텐츠만 포함하기로 선택했다. 비활성 콘텐츠는 제목 분석·후보 생성에서 제외한다. | TR-02, DEC-01 정정 | +| 2026-11-17 | DEC-10 | 확정 | 추가 인터뷰에서 한 번 적용하면 요청을 종료하고 미선택 후보는 폐기하기로 선택했다. 다른 결과를 적용하려면 새 요청을 생성한다. | TR-16, DEC-06 보완 | +| 2026-11-18 | DEC-11 | 확정 | 사용자가 enabled=false 설정을 제거하고 배포 시 바로 사용할 수 있도록 요청했다. 활성화 property와 controller/worker 조건부 등록, 해당 플래그의 일반 큐 legacy 호환 분기를 제거한다. ADMIN 권한·기존 worker 잠금·주기는 유지한다. | P7-T1, 이전 OFF→ON 운영 안내 대체 | + +DEC-11부터 관리자 번역 기능은 설정 없이 애플리케이션 기동 시 등록한다. 스키마가 자동으로 변경되지는 않는다. 신규 writer가 작업을 생성하기 전 신규 테이블·언어 포함 unique index를 준비하고, 구 writer/in-flight 작업 종료 및 구 unique index 제거를 완료해야 한다. 운영 변경은 이번 코드 수정의 실행 범위가 아니다. 이전 실행 기록의 기본 OFF 안내는 당시 상태이며 현재 정책은 DEC-11이다. + +## 12. 승인 및 실행 기록 + +| 날짜 | 상태 | 기록 | +|---|---|---| +| 2026-11-17 | 설계 승인 및 구현 승인 | 사용자가 설계 승인 후 구현 시작을 명시적으로 선택했다. 승인은 로컬 서버 구현과 focused tests에 한정되며 production DDL/deploy/git commit은 승인 범위가 아니다. 활성-only series 구성원, one-shot subset apply, 자유 형식 번역문 제외 결정을 유지한다. 실행 기준은 기존 plan의 Progress 실행 ledger이며 새 계획이나 workspace를 만들지 않는다. 현재 workspace는 기존 test branch이고 P1 구현 담당자가 source와 plan을 읽는다. 이 문서 갱신 시점에 완료된 구현 Goal은 없다. | +| 2026-11-17 | 로컬 구현 완료 | P1~P5·최종 gate 보정 완료. 마지막 실제 HTTP 27개와 bootJar 통과, 관련 회귀와 ktlintCheck 통과, 최종 제한 검토 APPROVE. 운영 적용은 실행하지 않았다. | +| 2026-11-18 | DEC-11 로컬 구현·검증 완료 | P7-T1의 등록·언어 identity RED 4개 assertion 실패 후 플래그·legacy 분기·고아 조회를 제거했다. 직접 영향 18개 class 162개 테스트와 ktlintCheck 통과. P7-GATE는 부모 검토 대기이며 운영 DDL·배포·커밋은 미실행이다. | diff --git a/docs/20261117_관리자번역후보선택/reviews/design-review.md b/docs/20261117_관리자번역후보선택/reviews/design-review.md new file mode 100644 index 00000000..4bc4d784 --- /dev/null +++ b/docs/20261117_관리자번역후보선택/reviews/design-review.md @@ -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 검증에서 확인한다. diff --git a/docs/20261117_관리자번역후보선택/reviews/implementation-review.md b/docs/20261117_관리자번역후보선택/reviews/implementation-review.md new file mode 100644 index 00000000..59ff894a --- /dev/null +++ b/docs/20261117_관리자번역후보선택/reviews/implementation-review.md @@ -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 행의 재검증 대기 표기는 이 후속 판정으로 종결하며, 운영 검증 대기는 해결했다고 표시하지 않는다. diff --git a/docs/20261117_관리자번역후보선택/schema.sql b/docs/20261117_관리자번역후보선택/schema.sql new file mode 100644 index 00000000..b12e50d8 --- /dev/null +++ b/docs/20261117_관리자번역후보선택/schema.sql @@ -0,0 +1,80 @@ +-- Schema artifact for the implemented admin translation selection feature. +-- Do not execute against production without operator approval; no automatic DDL is performed by the application. +-- DEC-11: API and candidate worker register at startup without an activation flag. +-- Before new writers create any jobs, prepare all three tables and the language-aware unique index, +-- drain every legacy writer and in-flight job, then complete the separate old-index removal below. +CREATE TABLE content_translation_override ( + id BIGINT NOT NULL AUTO_INCREMENT COMMENT '승인 override 식별자', + content_id BIGINT NOT NULL COMMENT '기존 콘텐츠 식별자, 삭제 cascade 없음', + locale VARCHAR(10) NOT NULL COMMENT '승인 대상 언어', + field_key VARCHAR(10) NOT NULL COMMENT 'TITLE, DETAIL, TAGS 중 승인 필드', + source_fingerprint VARCHAR(67) NOT NULL COMMENT '원본 언어와 정확한 필드 원문의 버전 포함 fingerprint', + approved_text TEXT NOT NULL COMMENT '관리자가 선택한 번역 문자열', + provenance TEXT NOT NULL COMMENT 'JSON 출처: requestId, candidateIds 목록, providers id/version 목록, approvedBy; 후보 FK 없음', + approved_at TIMESTAMP NOT NULL COMMENT 'UTC 초 정밀도로 한 번 정규화한 승인 시각', + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각', + updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각', + PRIMARY KEY (id), + UNIQUE KEY uk_content_translation_override_field (content_id, locale, field_key) +) COMMENT='콘텐츠 언어별 필드 승인과 출처, 전역 번역 메모리와 독립'; + +-- Expand: keep uk_translation_job_resource_field_target_hash until every old writer and in-flight job is drained. +ALTER TABLE translation_job + ADD UNIQUE KEY uk_translation_job_resource_field_target_hash_language + (resource_type, resource_id, field_key, target_language, source_hash, source_language); + +-- Contract (separate operator-approved step after legacy drain, required before new writers start work): +-- ALTER TABLE translation_job DROP INDEX uk_translation_job_resource_field_target_hash; +-- New writers always use exact source-language identity; there is no legacy-index compatibility mode. +-- After the first approval, rollback only to an override-aware application version. No DDL in this file was executed. + +-- Request state, reviewed source/group snapshots, and the atomic apply receipt. +CREATE TABLE translation_selection_request ( + id BIGINT NOT NULL AUTO_INCREMENT COMMENT '관리자 번역 선택 요청 식별자', + created_by BIGINT NOT NULL COMMENT '생성한 관리자 식별자', + client_request_id VARCHAR(36) NOT NULL COMMENT '관리자 범위 생성 멱등 UUID', + body_hash VARCHAR(64) NOT NULL COMMENT '버전 포함 canonical scope 본문 SHA-256', + scope TEXT NOT NULL COMMENT 'CONTENT 또는 SERIES 및 Long 식별자의 typed JSON', + status VARCHAR(24) NOT NULL COMMENT 'PREPARING REVIEW_REQUIRED READY_TO_GENERATE GENERATING READY APPLIED CANCELLED FAILED', + revision BIGINT NOT NULL COMMENT '관리자 의미 변경 revision, 최초 1', + snapshot LONGTEXT NOT NULL COMMENT '버전 JSON: 고정 활성 member IDs, 준비 원문, 확정 원문, reviewed 원문 그룹, provider ID/version manifest, 대상 언어, generation units', + preparation_attempt INT NOT NULL COMMENT '준비 실행 횟수, 최초 실행과 복구 1회까지', + preparation_lease_until TIMESTAMP NULL COMMENT '준비 소유권 UTC 초 만료 시각, lease 60초', + preparation_fence BIGINT NOT NULL COMMENT '오래된 실행의 게시와 갱신을 거부하는 단조 fence', + error_code VARCHAR(40) NULL COMMENT '준비 실패 안정 코드, 외부 예외 본문 없음', + accepted_generate_revision BIGINT NULL COMMENT '후속 후보 생성에서 수락한 revision', + apply_operation_id VARCHAR(36) NULL COMMENT '후속 one-shot 적용 멱등 UUID', + apply_body_hash VARCHAR(64) NULL COMMENT '후속 적용 canonical 본문 SHA-256', + apply_receipt LONGTEXT NULL COMMENT '후속 적용과 동일 transaction에 저장할 버전 JSON 영수증', + applied_at TIMESTAMP NULL COMMENT '후속 적용 UTC 초 확정 시각', + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각', + updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각', + PRIMARY KEY (id), + UNIQUE KEY uk_translation_selection_creation (created_by, client_request_id), + KEY ix_translation_selection_prepare (status, preparation_lease_until, id) +) COMMENT='관리자 번역 선택 요청과 고정 원문 및 그룹 검토, 일반 번역 작업과 독립'; + +CREATE TABLE translation_candidate ( + id BIGINT NOT NULL AUTO_INCREMENT COMMENT '제공자별 후보 식별자', + request_id BIGINT NOT NULL COMMENT '동결 manifest를 소유한 관리자 번역 요청', + unit_key VARCHAR(160) NOT NULL COMMENT '요청 안의 결정적 FIELD GROUP_COMMON TITLE_RESIDUAL 단위 키', + unit LONGTEXT NOT NULL COMMENT 'JSON: kind, sourceLanguage, 정확한 inputValues 순서, field/content/group 소유권', + provider_id VARCHAR(20) NOT NULL COMMENT '동결된 제공자 ID, fallback 대체 없음', + provider_version VARCHAR(80) NOT NULL COMMENT '동결된 제공자 버전, dispatch 시 일치 검사', + target_language VARCHAR(10) NOT NULL COMMENT 'source를 제외한 ko en ja 대상 언어', + status VARCHAR(16) NOT NULL COMMENT 'PENDING RUNNING SUCCEEDED FAILED DISCARDED', + translated_values LONGTEXT NULL COMMENT '입력 인덱스와 일치하는 JSON 번역 문자열 배열, 실패/폐기는 NULL', + failure_code VARCHAR(40) NULL COMMENT '안정 실패 코드, 외부 응답/예외 원문은 저장하지 않음', + attempt INT NOT NULL COMMENT '실제 provider 작업 claim 횟수, 최대 2, linked 결과는 별도 전송 없음', + lease_until TIMESTAMP NULL COMMENT '소유권 UTC 초 만료, 60초 lease, 만료 fence의 연장 금지', + fence BIGINT NOT NULL COMMENT 'claim/취소의 단조 fencing token', + linked_candidate_id BIGINT NULL COMMENT '같은 요청 제공자 언어 원문 배열의 선행 후보, 단위 소유권은 이 row에 보존', + terminal_at TIMESTAMP NULL COMMENT '성공 실패 폐기의 UTC 초 확정 시각', + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각', + updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각', + PRIMARY KEY (id), + UNIQUE KEY uk_translation_candidate_unit (request_id, unit_key, provider_id, target_language), + KEY ix_translation_candidate_claim (request_id, status, lease_until, id), + CONSTRAINT fk_translation_candidate_request FOREIGN KEY (request_id) + REFERENCES translation_selection_request (id) ON DELETE RESTRICT +) COMMENT='관리자 요청별 fresh provider 후보와 durable 실행 결과, 게시 번역 및 전역 memory와 독립';