sodalive-backend-spring-boot/docs/20261109_파파고번역길이분할/prd.md

파파고 번역 요청 길이 분할 PRD

항목	내용
상태	구현·기능 범위 검증 완료
작성일	2026-11-09
범위 승인	사용자: 파파고 번역만 요청당 길이 제한에 맞춰 분할 호출
구현 계획	plan-task.md

목적과 범위

현재 PapagoTranslationService는 각 필드를 한 번에 전송하여 5,000자를 넘으면 번역에 실패한다. 서비스 내부에서 긴 원문을 순서대로 분할 호출하고 결과를 하나로 합쳐 기존 호출자가 그대로 사용하게 한다. AWS 추가, 언어 감지, DB 구조, 워커 재시도 정책, 공개 API, 새 의존성은 변경하지 않는다.

요구사항

ID	요구사항과 수용 기준
PC-001	각 HTTP 요청의 text는 최대 5,000 UTF-16 코드 단위이다. 5,000 이하는 한 번, 5,001 이상은 여러 번 호출한다.
PC-002	분할은 원문 순서와 모든 문자를 보존하며 유효한 서로게이트 쌍을 끊지 않는다. 요청 텍스트를 결합하면 원문과 정확히 같다.
PC-003	각 입력 텍스트의 번역 조각을 순서대로 구분자 없이 결합하여 기존 TranslateResult의 텍스트별 대응을 유지한다.
PC-004	어느 조각이든 HTTP 오류 또는 빈 번역 결과이면 부분 번역을 성공 결과로 반환하지 않는다. 기존 워커가 실패로 판단할 빈 결과를 반환하고 이후 조각은 호출하지 않는다.
PC-005	빈 입력 목록, 동일 언어, 미지원 언어의 기존 무호출 동작 및 짧은 텍스트 호출 형식을 유지한다.

기술 결정과 한계

• 공식 문서는 요청당 최대 5,000 characters를 명시하지만 Unicode 계산 방식은 명시하지 않는다. 구현은 보수적으로 UTF-16 길이를 제한하고 서로게이트 경계만 조정한다.
• 길이 기준 고정 분할을 사용한다. 문장 분석, 문맥 품질 보정, 조각 캐시, 병렬 호출은 이번 범위가 아니다.
• 모든 조각 성공 후에만 기존 전체 원문 기준 번역 캐시에 저장할 수 있도록 한다.
• 분할 시 HTTP 호출 수가 증가하며 중간 실패 후 기존 워커 재시도에서는 앞선 조각도 다시 호출될 수 있다.
• 원문과 자격증명을 오류 로그나 문서에 기록하지 않는다.

검증 기준

• 실제 서비스의 HTTP 요청 경계에서 5,000/5,001/10,001자, 한글, 이모지, 여러 입력, 중간 오류와 빈 응답을 검증한다.
• 기존 번역 워커·스케줄러 회귀 테스트와 bootJar를 실행한다. 전체 테스트는 저장소 정책대로 사용자 실행이다.
• 실제 유료 Papago 호출 대신 가짜 자격증명과 로컬 HTTP 서버를 사용하며 실서비스 번역 품질 검증과 구분한다.

근거

• Papago Text Translation 요청 규격
• Papago 오류 코드: N2MT08, text parameter exceeds max length.