docs(i18n): 관리자 번역 선택 계약과 배포 및 검증 기록을 정리한다
This commit is contained in:
@@ -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<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:
|
||||
|
||||
```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<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:
|
||||
|
||||
```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<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:
|
||||
|
||||
```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<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을 구현하거나 시각 디자인을 지정하지 않는다.
|
||||
|
||||
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은 승인·실행 범위에 포함되지 않는다.
|
||||
Reference in New Issue
Block a user