깊은 문서에서 미리보기 샘플이 0개 추출되던 버그 수정

문서 샘플 미리보기 범위를 전체 문서에 걸쳐 적절히 분산시킨 작업이다. 깊은 문서(deep docs)에서 0개 엔드포인트만 추출되던 버그를 고쳐서, 이제 여러 페이지에서 균형 있게 샘플을 뽑아낼 수 있게 했다.

깊은 문서에서 샘플이 안 나오던 문제

처음 미리보기 로직을 구현할 때는 간단했다. 문서의 첫 몇 페이지나 특정 위치에서만 샘플을 추출하는 방식인데, 이게 페이지 수가 적당한 문서에선 괜찮지만 수백 페이지 이상의 깊은 문서에 닿으면 처참해진다. 샘플 로직이 고정된 범위(예: 첫 10페이지)만 보고 있으면, 나머지 부분은 완전히 무시되거든. 결과적으로 긴 문서를 업로드했을 때 추출된 엔드포인트가 0개가 되는 현상이 발생했다.

이건 단순한 버그가 아니라 사용자 경험에 직결된 문제다. 특히 B2B 같은 대규모 문서를 다루는 시나리오에서 "업로드했는데 아무것도 안 뽑혔다"는 느낌은 제품 신뢰도를 깎아먹는다. 팀 내에서도 초기 QA 때는 짧은 샘플 PDF로 테스트했어서 이 케이스를 놓쳤던 것 같다.

전체 문서에 걸친 샘플링 전략

이번 수정은 문서 길이에 관계없이 전체 범위에서 균등하게 샘플 페이지를 뽑도록 변경했다. 페이지 수가 100인지 1000인지 상관없이, 문서를 여러 구간으로 나눈 뒤 각 구간에서 대표 샘플을 선택하는 방식이다.

구체적으로 src/lib/pdf.ts 쪽에서 샘플링 로직이 핵심인데, 대략 이런 방향:

// Before: 첫 10페이지만 샘플링 (깊은 문서에서 범위 부족)
const samplePages = document.pages.slice(0, 10);

// After: 문서 전체를 N개 구간으로 나눠서 각 구간에서 샘플 추출
const totalPages = document.pages.length;
const buckets = 5; // 5개 구간
const samplePages = [];
for (let i = 0; i < buckets; i++) {
  const start = Math.floor((i / buckets) * totalPages);
  const end = Math.floor(((i + 1) / buckets) * totalPages);
  const mid = Math.floor((start + end) / 2);
  samplePages.push(document.pages[mid]);
}

이렇게 하면 문서가 아무리 길어도 처음부터 끝까지 고르게 커버할 수 있다.

멀티레이어 영향 범위

이 수정이 단순히 "샘플링 함수 하나" 개선으로 끝나지 않는 이유는 파일 4개를 건드렸다는 데 있다. API 추출 로직, 프론트엔드 UI, 국제화까지 영향이 이어진다는 뜻이다.

src/app/api/extract/route.ts는 직접 샘플 페이지를 받아서 엔드포인트 추출을 수행하는데, 이제 페이지들이 전체 문서에 분산돼 있으니 추출 결과의 다양성도 늘어난다. 깊은 문서의 초반부, 중간부, 말미에 각각 다른 API 패턴이 있다면, 이전엔 초반부 것들만 나왔겠지만 이제는 골고루 보인다.

src/app/home-client.tsx 쪽 미리보기 UI도 생각해야 할 부분이다. 사용자가 "이 문서에서 뽑힌 샘플은 어디서 온 걸까?" 하고 궁금할 때, 문서 전체에서 고르게 선택됐다는 걸 보여주면 신뢰도가 올라간다. 필요하면 "페이지 123, 456, 789에서 샘플 추출됨" 식으로 표시할 수도 있다.

회고와 배운 점

이 케이스는 "짧은 문서로만 테스트했을 때 놓칠 수 있는 버그"의 전형이다. 팀의 테스트 전략 차원에서도 배운 게 있는데, 초기 개발 때부터 "매우 깊은 시나리오" 시나리오를 의도적으로 포함해야 한다는 점이다. 페이지 수가 2배, 5배, 10배 차이 날 때 동작이 달라지는 함수들을 찾아내려면, 단위 테스트에서도 이런 경계값을 명시적으로 테스트하는 게 좋다.

또 비슷한 구조의 작업들(텍스트 추출, 이미지 샘플링 등)도 같은 함정에 빠질 가능성이 있어서, 이번 수정 방식을 팀 가이드로 문서화해 두려고 한다. "문서 범위를 다루는 로직은 고정 범위 대신 동적 분배로 설계하자" 정도의 체크리스트 항목.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.