32 KiB
관리자 번역 선택 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, 구현 순서와 검증 기준은 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는
ADMINrole 전용이다.CONTENT_MANAGER, creator 관리자 role은 이 API의 권한이 아니다. - 기존 인증 주체 및 null guard를 사용한다. 신규 controller의 권한 규칙은 기존
@PreAuthorize("hasRole('ADMIN')")관례를 따른다. - 성공과 business error는 기존
ApiResponse<T>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:
{
"clientRequestId": "d7c2f4e1-1e4f-4ac2-a6ed-85f2f8102101",
"scope": { "type": "CONTENT", "contentId": 4102 }
}
scope는 다음 합 타입 중 하나다.
{ "type": "CONTENT", "contentId": 4102 }
{ "type": "SERIES", "seriesId": 981 }
Response data는 TranslationSelectionRequestResponse:
{
"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<ContentSnapshotResponse>, nextAfterContentId: Long?}다.
ContentSnapshotResponse 필드 |
타입·의미 |
|---|---|
contentId, active, eligible |
Long, 조회 시 현재 활성 여부 Boolean, 해당 scope의 현재 적용 자격 Boolean |
sourceLanguage |
고정 snapshot의 LanguageCode |
sourceFields |
Map<FieldKey, String>; title/detail/tags가 모두 존재 |
sourceFingerprints, currentSourceFingerprints |
고정 Map<FieldKey, String>과 현재 Map<FieldKey, String>? |
emptyFields |
List<FieldKey>; 번역할 텍스트가 없어 후보를 만들지 않은 필드 |
currentTranslations |
List<{targetLanguage: LanguageCode, fields: Map<FieldKey, String>, approvalOrigins: Map<FieldKey, ADMIN/UNKNOWN>, approvalProvenance: Map<FieldKey, ApprovalProvenance>}> |
시리즈 scope는 생성 시 활성 member만 포함한다. sourceLanguage, sourceFields, sourceFingerprints는 준비 완료 시 고정된 snapshot이다. currentTranslations, active는 조회 시점 값이다. 각 item은 currentSourceFingerprints: Map<FieldKey, String>?, eligible: Boolean도 반환한다. 삭제된 콘텐츠는 현재 fingerprint가 null이고 eligible=false이며 snapshot은 남는다. 프론트엔드는 변경 여부를 표시할 수 있지만 최종 적용 가능 여부는 서버가 잠금 안에서 판정한다.
approvalOrigins 값은 ADMIN 또는 UNKNOWN이다. 유효한 field override row가 있는 값만 ADMIN으로 표시한다. 해당 승인 필드에는 approvalProvenance: Map<FieldKey, {requestId: Long, candidateIds: List<Long>, 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<TitleGroup>, individualContentIds: List<Long>, templates: List<TitleTemplate> |
TitleGroup |
groupId: String, sourceLanguage: LanguageCode, memberContentIds: List<Long>, sharedParts: List<SharedPart> |
SharedPart |
partId: String, sourceText: String, occurrences: List<{contentId: Long, startCodePoint: Int, endCodePoint: Int}> |
TitleTemplate |
contentId: Long, groupId: String, sourceFingerprint: String, segments: List<TitleSegment> |
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:
{
"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:
{ "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)
{
"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<String>도 반환한다. 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<FieldKey>로 표시하고 새 승인 대상에서 제외한다. 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:
{
"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 처리 규칙:
- request 행을 잠그고 저장된 operationId/body hash를 먼저 검사한다. 동일 요청의 replay면 기존 receipt를 반환한다. 새 apply에만 READY 상태와 현재 revision 검증을 적용한다.
- 필요한 Series 부모, CONTENT 부모를 ID 오름차순으로 잠근다. 시리즈 그룹 적용은 활성 membership을 안정적으로 확인할 수 있도록 현재 연결 CONTENT 부모도 잠그며, 구성원 추가/제거는 동일 Series 잠금으로 직렬화한다.
- 잠금 이후 최신 source·활성 membership·override·payload를 다시 읽고 최종 검증한다. 잠금 전 JPA entity나 로딩된 연관 컬렉션을 그대로 신뢰하지 않는다. FIELD는 선택 필드 fingerprint와 content 존재 여부를 검사하며, SERIES scope일 때 현재 연결·활성 자격도 요구한다. 제목 그룹은 모든 member title fingerprint/language와 고정된 활성 membership 전체를 검사한다. 선택되지 않은 다른 필드 변경은 거부 조건이 아니다.
- 모든 선택 값을 하나의 DB transaction으로 저장한다. 실패가 하나라도 있으면 어떤 값도 적용하지 않고 request는
READY상태에 남는다. - 적용 값만 field-scoped override와 기존 CONTENT rendered payload에 쓴다. 미선택 payload 값은 byte-for-byte 보존한다. Locale row가 없으면 미선택 필드는 현재 source fallback으로 초기화한다.
- 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<AppliedField>, discardedCandidateCount: Int다. AppliedField는 contentId: Long, field: FieldKey, targetLanguage: LanguageCode, translatedValue: String, candidateIds: List<Long>, 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을 구현하거나 시각 디자인을 지정하지 않는다.
- 관리자는 콘텐츠 또는 시리즈 ID로 요청을 만든다.
PREPARING/GENERATING상태는 1초 간격 polling으로 조회한다. - 시리즈는 grouping 분석 화면으로 전이하고 관리자가 모든 콘텐츠를 그룹 또는 개별 상태로 분류해 확정하기 전 generate action을 보내지 않는다. 원문 구간은 code point 인덱스로 변환하고 후보 생성 뒤에는 grouping 편집 대신 cancel 후 재요청을 제공한다.
- 최초 활성 콘텐츠 snapshot의 title/detail/tags, 언어, 현재 값과 활성 자격, fingerprint 기반 변경 가능성을 request/content pages에서 검토한다. source 언어를 target language로 제시하지 않는다.
- 생성 완료 후 field candidate를 필드·언어별로 비교한다. 제공자 이름·버전·실패 상태를 확인 가능하게 하고 같은 text 후보를 출처 손실 없이 접어 보여줄 수 있다. 기존 translation origin
UNKNOWN을 실제 provider처럼 표기하지 않는다. - grouped title은 group+language로 공통 선택 하나와 member별 residual 선택을 만든다. 불완전 group은 apply할 수 없으며, 그룹 구성원의 결과를 분리하려면 새 request 전에 group을 나눈다.
- 사용자가 apply할 선택 subset을 review한 후 operation UUID를 생성해 한번 전송한다. 성공 receipt 이후 같은 request에서 새 선택을 추가할 수 없다. server의 SOURCE_CHANGED/MEMBERSHIP_CHANGED 오류면 이전 후보 재적용 대신 새 request를 시작한다.
- 검토 전·진행 중·READY 상태에서 cancel할 수 있음을 표시한다. 이미 전송된 외부 호출의 비용은 취소로 되돌릴 수 없다는 점과 적용 미확정 값을 유지하는 동작을 설명한다.
Candidate 문자열은 HTML로 해석하지 않고 text로 표시한다. 화면 시각 규칙, 로딩 애니메이션, responsive layout은 본 계약의 범위가 아니다.
9. 내부 데이터 및 변경 불변식
세 테이블과 저장 불변식, worker·writer·rollout 설계는 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 |
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의 Progress 실행 ledger에서 관리한다. Production DDL/deploy/git commit은 승인·실행 범위에 포함되지 않는다.