docs(i18n): 관리자 번역 선택 계약과 배포 및 검증 기록을 정리한다
This commit is contained in:
@@ -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·배포·커밋은 미실행이다. |
|
||||
Reference in New Issue
Block a user