PDF 조작은 특히 페이지 순서를 다룰 때 복잡해질 수 있습니다. 최근 우리는 PDF 문서 구조와 페이지 인덱싱에 대한 중요한 통찰을 드러낸 흥미로운 디버깅 세션을 경험했습니다. 이 사례 연구는 겉보기에 간단한 “오프바이원” 오류가 PDF 사양에 대한 깊은 조사로 발전하여 문서 구조에 대한 근본적인 오해를 드러낸 과정을 보여줍니다.

문제

우리는 HotPDF Delphi 컴포넌트의 `CopyPage`라는 PDF 페이지 복사 유틸리티를 작업하고 있었습니다. 이 프로그램은 기본적으로 첫 번째 페이지를 복사해야 했지만, 대신 항상 두 번째 페이지를 복사하고 있었습니다. 언뜻 보기에는 간단한 인덱스 버그처럼 보였습니다 – 아마도 0 기반 대신 1 기반 인덱싱을 사용했거나 기본적인 산술 오류를 범했을 것입니다.

하지만 인덱싱 로직을 여러 번 확인하고 올바른 것을 확인한 후, 더 근본적인 무언가가 잘못되었다는 것을 깨달았습니다. 문제는 복사 로직 자체가 아니라 프로그램이 애초에 “페이지 1″이 무엇인지 해석하는 방식에 있었습니다.

증상

문제는 여러 가지 방식으로 나타났습니다:

1. 일관된 오프셋: 모든 페이지 요청이 한 위치씩 어긋나 있었습니다
2. 여러 문서에서 재현 가능: 문제가 여러 다른 PDF 파일에서 발생했습니다
3. 명백한 인덱스 오류 없음: 코드 로직이 표면적 검사에서는 올바르게 보였습니다
4. 이상한 페이지 순서: 모든 페이지를 복사할 때, 한 PDF의 페이지 순서는 2, 3, 1이었고, 다른 것은 2, 3, 4, 5, 6, 7, 8, 9, 10, 1이었습니다

이 마지막 증상이 돌파구로 이어지는 핵심 단서였습니다.

초기 조사

PDF 구조 분석

첫 번째 단계는 PDF 문서 구조를 조사하는 것이었습니다. 내부에서 무슨 일이 일어나고 있는지 이해하기 위해 여러 도구를 사용했습니다:

1. 수동 PDF 검사 – 원시 구조를 보기 위한 헥스 에디터 사용
2. 명령줄 도구 – qpdf –show-object 등을 사용하여 객체 정보 덤프
3. Python PDF 디버깅 스크립트 – 파싱 프로세스 추적

이러한 도구를 사용하여 소스 문서가 특정 페이지 트리 구조를 가지고 있음을 발견했습니다:

16 0 obj
<<
  /Count 3
  /Kids [
    20 0 R
    1 0 R  
    4 0 R
  ]
  /Type /Pages
>>

이는 문서에 3개의 페이지가 포함되어 있지만 페이지 객체가 PDF 파일 내에서 순차적으로 배치되지 않았음을 보여주었습니다. Kids 배열이 논리적 페이지 순서를 정의했습니다:

• 페이지 1: 객체 20
• 페이지 2: 객체 1
• 페이지 3: 객체 4

첫 번째 단서

핵심 통찰은 객체 번호와 그들의 논리적 위치를 조사하는 것에서 나왔습니다. 주목할 점은:

• 객체 1이 Kids 배열의 두 번째에 나타남 (논리적 페이지 2)
• 객체 4가 Kids 배열의 세 번째에 나타남 (논리적 페이지 3)
• 객체 20이 Kids 배열의 첫 번째에 나타남 (논리적 페이지 1)

이는 파싱 코드가 Kids 배열의 순서를 따르는 대신 객체 번호나 파일 내 물리적 출현에 기반하여 내부 페이지 배열을 구축하는 경우, 페이지가 잘못된 순서가 될 것임을 의미했습니다.

가설 테스트

이 이론을 검증하기 위해 간단한 테스트를 만들었습니다:

1. 각 페이지를 개별적으로 추출하여 내용 확인
2. 추출된 페이지의 파일 크기 비교 (다른 페이지는 종종 다른 크기를 가짐)
3. 페이지별 마커 찾기 – 페이지 번호나 푸터 등

테스트 결과가 가설을 확인했습니다:

• 프로그램의 “페이지 1″에는 페이지 2에 있어야 할 내용이 있었습니다
• 프로그램의 “페이지 2″에는 페이지 3에 있어야 할 내용이 있었습니다
• 프로그램의 “페이지 3″에는 페이지 1에 있어야 할 내용이 있었습니다

이 순환 시프트 패턴이 페이지 배열이 올바르게 구축되지 않았다는 결정적인 증거였습니다.

근본 원인

파싱 로직 이해

핵심 문제는 PDF 파싱 코드가 Pages 트리 구조에서 정의된 논리적 순서가 아닌 PDF 파일 내 객체의 물리적 순서에 기반하여 내부 페이지 배열(`PageArr`)을 구축하고 있었다는 것입니다.

파싱 프로세스 중에 일어나고 있던 일은 다음과 같습니다:

// 문제가 있는 파싱 로직 (단순화됨)
procedure BuildPageArray;
begin
  PageArrPosition := 0;
  SetLength(PageArr, PageCount);
  
  // 파일의 물리적 순서로 모든 객체를 반복
  for i := 0 to IndirectObjects.Count - 1 do
  begin
    CurrentObj := IndirectObjects.Items[i];
    if IsPageObject(CurrentObj) then
    begin
      PageArr[PageArrPosition] := CurrentObj;  // 잘못됨: 물리적 순서
      Inc(PageArrPosition);
    end;
  end;
end;

이로 인해 다음과 같은 결과가 나왔습니다:

• `PageArr[0]`에는 객체 1이 포함되었습니다 (실제로는 논리적 페이지 2)
• `PageArr[1]`에는 객체 4가 포함되었습니다 (실제로는 논리적 페이지 3)
• `PageArr[2]`에는 객체 20이 포함되었습니다 (실제로는 논리적 페이지 1)

코드가 `PageArr[0]`을 사용하여 “페이지 1″을 복사하려고 할 때, 실제로는 잘못된 페이지를 복사하고 있었습니다.

두 가지 다른 순서

문제는 페이지를 순서화하는 두 가지 다른 방법을 혼동한 것에서 비롯되었습니다:

물리적 순서 (객체가 PDF 파일에 나타나는 방식):

객체 1 (페이지 객체) → PageArr의 인덱스 0
객체 4 (페이지 객체) → PageArr의 인덱스 1  
객체 20 (페이지 객체) → PageArr의 인덱스 2

논리적 순서 (Pages 트리의 Kids 배열에서 정의됨):

Kids[0] = 20 0 R → PageArr의 인덱스 0이어야 함 (페이지 1)
Kids[1] = 1 0 R  → PageArr의 인덱스 1이어야 함 (페이지 2)
Kids[2] = 4 0 R  → PageArr의 인덱스 2이어야 함 (페이지 3)

파싱 코드는 물리적 순서를 사용하고 있었지만, 사용자는 논리적 순서를 기대하고 있었습니다.

왜 이런 일이 발생하는가

PDF 파일은 반드시 페이지가 순차적 순서로 작성되는 것은 아닙니다. 이는 여러 이유로 발생할 수 있습니다:

1. 증분 업데이트: 나중에 추가된 페이지가 더 높은 객체 번호를 받음
2. PDF 생성기: 다른 도구들이 객체를 다르게 조직할 수 있음
3. 최적화: 일부 도구는 압축이나 성능을 위해 객체를 재배치함
4. 편집 이력: 문서 변경이 객체 재번호를 야기할 수 있음

추가 복잡성: 다중 파싱 경로

우리의 HotPDF VCL 컴포넌트에는 두 가지 다른 파싱 경로가 있습니다:

1. 레거시 파싱: 오래된 PDF 1.3/1.4 형식에 사용
2. 모던 파싱: 객체 스트림과 새로운 기능을 가진 PDF (PDF 1.5/1.6/1.7)에 사용

버그는 두 경로 모두에서 수정되어야 했습니다. 이들은 다른 방식으로 페이지 배열을 구축하지만, 둘 다 Kids 배열에서 정의된 논리적 순서를 무시하고 있었습니다.

해결책

수정 설계

수정에는 PDF의 Pages 트리에서 정의된 논리적 순서와 일치하도록 내부 페이지 배열을 재구성하는 페이지 재정렬 기능의 구현이 필요했습니다. 이는 기존 기능을 깨뜨리지 않도록 신중하게 수행되어야 했습니다.

구현 전략

해결책에는 여러 핵심 구성 요소가 포함되었습니다:

procedure ReorderPageArrByPagesTree;
begin
  // 1. 루트 Pages 객체 찾기
  // 2. Kids 배열 추출  
  // 3. Kids 순서에 맞게 PageArr 재정렬
  // 4. 페이지 인덱스가 논리적 페이지 번호와 일치하는지 확인
end;

상세 구현

완전한 재정렬 기능은 다음과 같습니다:

procedure THotPDF.ReorderPageArrByPagesTree;
var
  RootObj: THPDFDictionaryObject;
  PagesObj: THPDFDictionaryObject;
  KidsArray: THPDFArrayObject;
  NewPageArr: array of THPDFDictArrItem;
  I, J, KidsIndex, TypeIndex, PageIndex: Integer;
  KidsItem: THPDFObject;
  RefObj: THPDFLink;
  PageObjNum: Integer;
  TypeObj: THPDFNameObject;
  Found: Boolean;
begin
  WriteLn('[DEBUG] ReorderPageArrByPagesTree 시작');
  
  try
    // 단계 1: Root 객체 찾기
    RootObj := nil;
    if (FRootIndex >= 0) and (FRootIndex < IndirectObjects.Count) then
    begin
      RootObj := THPDFDictionaryObject(IndirectObjects.Items[FRootIndex]);
      WriteLn('[DEBUG] 인덱스 ', FRootIndex, '에서 Root 객체 발견');
    end
    else
    begin
      WriteLn('[DEBUG] Root 객체를 찾을 수 없음, 페이지를 재정렬할 수 없음');
      Exit;
    end;

    // 단계 2: Root에서 Pages 객체 찾기
    PagesObj := nil;
    if RootObj <> nil then
    begin
      var PagesIndex := RootObj.FindValue('Pages');
      if PagesIndex >= 0 then
      begin
        var PagesRef := RootObj.GetIndexedItem(PagesIndex);
        if PagesRef is THPDFLink then
        begin
          var PagesRefObj := THPDFLink(PagesRef);
          var PagesObjNum := PagesRefObj.Value.ObjectNumber;
          
          // 실제 Pages 객체 찾기
          for I := 0 to IndirectObjects.Count - 1 do
          begin
            var TestObj := THPDFObject(IndirectObjects.Items[I]);
            if (TestObj.ID.ObjectNumber = PagesObjNum) and 
               (TestObj is THPDFDictionaryObject) then
            begin
              PagesObj := THPDFDictionaryObject(TestObj);
              WriteLn('[DEBUG] 인덱스 ', I, '에서 Pages 객체 발견');
              Break;
            end;
          end;
        end;
      end;
    end;

    // 단계 3: Kids 배열 추출
    if PagesObj = nil then
    begin
      WriteLn('[DEBUG] Pages 객체를 찾을 수 없음, 페이지를 재정렬할 수 없음');
      Exit;
    end;

    KidsArray := nil;
    KidsIndex := PagesObj.FindValue('Kids');
    if KidsIndex >= 0 then
    begin
      var KidsObj := PagesObj.GetIndexedItem(KidsIndex);
      if KidsObj is THPDFArrayObject then
      begin
        KidsArray := THPDFArrayObject(KidsObj);
        WriteLn('[DEBUG] ', KidsArray.Items.Count, '개 항목의 Kids 배열 발견');
      end;
    end;

    if KidsArray = nil then
    begin
      WriteLn('[DEBUG] Kids 배열을 찾을 수 없음, 페이지를 재정렬할 수 없음');
      Exit;
    end;

    // 단계 4: Kids 순서에 기반한 새 PageArr 생성
    SetLength(NewPageArr, KidsArray.Items.Count);
    PageIndex := 0;

    for I := 0 to KidsArray.Items.Count - 1 do
    begin
      KidsItem := KidsArray.GetIndexedItem(I);
      if KidsItem is THPDFLink then
      begin
        RefObj := THPDFLink(KidsItem);
        PageObjNum := RefObj.Value.ObjectNumber;
        WriteLn('[DEBUG] Kids[', I, ']는 객체 ', PageObjNum, '을 참조');

        // 현재 PageArr에서 이 페이지 객체 찾기
        Found := False;
        for J := 0 to Length(PageArr) - 1 do
        begin
          if PageArr[J].PageLink.ObjectNumber = PageObjNum then
          begin
            // 이것이 실제로 Page 객체인지 확인
            if PageArr[J].PageObj <> nil then
            begin
              TypeIndex := PageArr[J].PageObj.FindValue('Type');
              if TypeIndex >= 0 then
              begin
                TypeObj := THPDFNameObject(PageArr[J].PageObj.GetIndexedItem(TypeIndex));
                if (TypeObj <> nil) and (CompareText(String(TypeObj.Value), 'Page') = 0) then
                begin
                  NewPageArr[PageIndex] := PageArr[J];
                  WriteLn('[DEBUG] Kids[', I, '] -> PageArr[', PageIndex, '] 매핑 (객체 ', PageObjNum, ')');
                  Inc(PageIndex);
                  Found := True;
                  Break;
                end;
              end;
            end;
          end;
        end;

        if not Found then
        begin
          WriteLn('[DEBUG] 경고: 현재 PageArr에서 페이지 객체 ', PageObjNum, '을 찾을 수 없음');
        end;
      end;
    end;

    // 단계 5: PageArr을 재정렬된 버전으로 교체
    if PageIndex > 0 then
    begin
      SetLength(PageArr, PageIndex);
      for I := 0 to PageIndex - 1 do
      begin
        PageArr[I] := NewPageArr[I];
      end;
      WriteLn('[DEBUG] Pages 트리에 따라 ', PageIndex, '개 페이지로 PageArr 재정렬 성공');
    end
    else
    begin
      WriteLn('[DEBUG] 재정렬할 유효한 페이지를 찾을 수 없음');
    end;

  except
    on E: Exception do
    begin
      WriteLn('[DEBUG] ReorderPageArrByPagesTree에서 오류: ', E.Message);
    end;
  end;
end;

통합 지점

재정렬 기능은 두 파싱 경로 모두에서 적절한 시점에 호출되어야 했습니다:

1. 레거시 파싱 후: `ListExtDictionary` 완료 후 호출
2. 모던 파싱 후: 객체 스트림 처리 후 호출

// 레거시 파싱 경로에서
ListExtDictionary(THPDFDictionaryObject(IndirectObjects.Items[I]), FPageslink);
ReorderPageArrByPagesTree; // 페이지 순서 수정
Break;

// 모던 파싱 경로에서  
if TryParseModernPDF then
begin
  Result := ModernPageCount;
  ReorderPageArrByPagesTree; // 페이지 순서 수정
  Exit;
end;

오류 처리 및 엣지 케이스

구현에는 다양한 엣지 케이스에 대한 견고한 오류 처리가 포함되었습니다:

1. 루트 객체 부재: 문서 구조가 손상된 경우 우아한 폴백
2. 잘못된 페이지 참조: 깨진 참조를 건너뛰지만 처리 계속
3. 혼합 객체 타입: 재정렬 전에 객체가 실제로 페이지인지 확인
4. 빈 페이지 배열: 페이지가 없는 문서 처리
5. 예외 안전성: 크래시를 방지하기 위해 예외를 잡고 로그

도움이 된 디버깅 기법

1. 포괄적 로깅

모든 단계에서 상세한 디버그 출력을 추가하는 것이 중요했습니다. 다중 레벨 로그 시스템을 구현했습니다:

// 디버그 레벨: TRACE, DEBUG, INFO, WARN, ERROR
WriteLn('[TRACE] 객체 ', I, ' 처리 중, 총 ', IndirectObjects.Count, '개');
WriteLn('[DEBUG] ', KidsArray.Items.Count, '개 항목의 Kids 배열 발견');
WriteLn('[INFO] ', PageIndex, '개 페이지 재정렬 성공');
WriteLn('[WARN] 페이지 객체 ', PageObjNum, '을 찾을 수 없음');
WriteLn('[ERROR] 페이지 파싱에서 심각한 오류: ', E.Message);

로깅을 통해 작업의 정확한 순서가 드러났고, 페이지 순서가 어디서 잘못되었는지 추적할 수 있었습니다.

2. PDF 구조 분석 도구

PDF 구조를 이해하기 위해 여러 외부 도구를 사용했습니다:

명령줄 도구:

# 페이지 트리 구조와 순서 표시
qpdf --show-pages input.pdf

# JSON 형식으로 상세한 페이지 정보 표시  
qpdf --json=latest --json-key=pages input.pdf

# 특정 객체 표시 (예: 페이지 트리 루트)
qpdf --show-object="16 0 R" input.pdf

# 교차 참조 테이블 표시
qpdf --show-xref input.pdf

# PDF 구조의 기본 검증
qpdf --check input.pdf

# 기본 PDF 정보 확인
cpdf -info input.pdf

# pdftk를 사용하여 데이터 덤프
pdftk input.pdf dump_data

데스크톱 PDF 분석 도구:

• PDF Explorer: PDF 구조의 시각적 트리 뷰
• PDF Debugger: PDF 파싱의 단계별 실행
• 헥스 에디터: 원시 바이트 레벨 분석

3. 테스트 파일 검증

체계적인 검증 프로세스를 만들었습니다:

procedure VerifyPageContent(PageNum: Integer; ExtractedFile: string);
begin
  // 파일 크기 확인 (다른 페이지는 종종 다른 크기를 가짐)
  FileSize := GetFileSize(ExtractedFile);
  WriteLn('페이지 ', PageNum, ' 크기: ', FileSize, ' 바이트');
  
  // 페이지별 마커 찾기
  if SearchForText(ExtractedFile, 'Page ' + IntToStr(PageNum)) then
    WriteLn('내용에서 페이지 번호 마커 발견')
  else
    WriteLn('경고: 페이지 번호 마커를 찾을 수 없음');
    
  // 참조 추출과 비교
  if CompareFiles(ExtractedFile, ReferenceFiles[PageNum]) then
    WriteLn('내용이 참조와 일치')
  else
    WriteLn('오류: 내용이 참조와 다름');
end;

4. 단계별 격리

문제를 격리된 구성 요소로 분해했습니다:

단계 1: PDF 파싱

• 문서가 올바르게 로드되는지 확인
• 객체 수와 타입 확인
• 페이지 트리 구조 검증

단계 2: 페이지 배열 구축

• 내부 배열에 추가되는 각 페이지 로그
• 페이지 객체 타입과 참조 확인
• 배열 인덱스 확인

단계 3: 페이지 복사

• 각 페이지를 개별적으로 복사 테스트
• 소스와 대상 페이지 내용 확인
• 복사 중 데이터 손상 확인

단계 4: 출력 검증

• 출력을 예상 결과와 비교
• 최종 문서에서 페이지 순서 검증
• 여러 PDF 뷰어에서 테스트

5. 바이너리 차이 분석

파일 크기 비교가 결정적이지 않을 때 바이너리 차이 도구를 사용했습니다:

# 추출된 페이지를 바이트 단위로 비교
hexdump -C page1_actual.pdf > page1_actual.hex
hexdump -C page1_expected.pdf > page1_expected.hex
diff page1_actual.hex page1_expected.hex

이를 통해 어떤 바이트가 다른지 정확히 드러났고, 문제가 내용에 있는지 메타데이터에만 있는지 식별하는 데 도움이 되었습니다.

6. 참조 구현 비교

다른 PDF 라이브러리와의 동작도 비교했습니다:

# PyPDF2 참조 테스트
import PyPDF2
with open('input.pdf', 'rb') as file:
    reader = PyPDF2.PdfFileReader(file)
    for i in range(reader.numPages):
        page = reader.getPage(i)
        writer = PyPDF2.PdfFileWriter()
        writer.addPage(page)
        with open(f'reference_page_{i+1}.pdf', 'wb') as output:
            writer.write(output)

이를 통해 비교할 “그라운드 트루스”를 얻었고, 실제로 어떤 페이지가 추출되어야 하는지 확인할 수 있었습니다.

7. 메모리 디버깅

문제가 배열 조작과 관련되어 있었기 때문에 메모리 디버깅 도구를 사용했습니다:

// 메모리 손상 확인
procedure ValidatePageArray;
begin
  for I := 0 to Length(PageArr) - 1 do
  begin
    if PageArr[I].PageObj = nil then
      raise Exception.Create('인덱스 ' + IntToStr(I) + '에서 null 페이지 객체');
    if not (PageArr[I].PageObj is THPDFDictionaryObject) then
      raise Exception.Create('인덱스 ' + IntToStr(I) + '에서 잘못된 객체 타입');
  end;
  WriteLn('[DEBUG] 페이지 배열 검증 통과');
end;

8. 버전 제어 고고학

파싱 코드가 어떻게 진화했는지 이해하기 위해 git을 사용했습니다:

# 페이지 파싱 로직이 마지막으로 변경된 시점 찾기
git log --follow -p -- HPDFDoc.pas | grep -A 10 -B 10 "PageArr"

# 작동했던 버전과 비교
git diff HEAD~10 HPDFDoc.pas

이를 통해 객체 파싱을 최적화했지만 의도치 않게 페이지 순서를 깨뜨린 최근 리팩터링에서 버그가 도입되었음이 밝혀졌습니다.

배운 교훈

1. PDF 논리적 순서 대 물리적 순서

페이지가 PDF 파일에서 표시되어야 하는 순서와 같은 순서로 나타난다고 가정하지 마세요. 항상 Pages 트리 구조를 존중하세요.

2. 수정 타이밍

페이지 재정렬은 파싱 파이프라인의 적절한 순간 – 모든 페이지 객체가 식별된 후, 하지만 페이지 조작 전에 수행되어야 합니다.

3. 다중 PDF 파싱 경로

현대적인 PDF 파싱 라이브러리는 종종 여러 코드 경로(레거시 대 모던 파싱)를 가집니다. 수정이 모든 관련 경로에 적용되는지 확인하세요.

4. 철저한 테스트

페이지 순서 문제는 특정 문서 구조나 생성 도구에서만 나타날 수 있으므로 다양한 PDF 문서로 테스트하세요.

예방 전략

1. 적극적 PDF 구조 검증

PDF 파싱 중에 항상 페이지 순서를 검증하는 자동 확인을 구현하세요:

procedure ValidatePDFStructure(PDF: THotPDF);
begin
  // 페이지 수 일관성 확인
  if PDF.PageCount <> Length(PDF.PageArr) then
    raise Exception.Create('페이지 수 불일치');
    
  // 페이지 순서가 Kids 배열과 일치하는지 확인
  for I := 0 to PDF.PageCount - 1 do
  begin
    ExpectedObjNum := GetKidsArrayReference(I);
    ActualObjNum := PDF.PageArr[I].PageLink.ObjectNumber;
    if ExpectedObjNum <> ActualObjNum then
      raise Exception.Create(Format('인덱스 %d에서 페이지 순서 불일치', [I]));
  end;
  
  WriteLn('[INFO] PDF 구조 검증 통과');
end;

2. 포괄적 로깅 프레임워크

복잡한 문서 파싱을 위한 구조화된 로깅 시스템을 구현하세요:

type
  TLogLevel = (llTrace, llDebug, llInfo, llWarn, llError);
  
procedure LogPDFOperation(Level: TLogLevel; Operation: string; Details: string);
begin
  if Level >= CurrentLogLevel then
  begin
    WriteLn(Format('[%s] %s: %s', [LogLevelNames[Level], Operation, Details]));
    if LogToFile then
      AppendToLogFile(Format('%s [%s] %s: %s', 
        [FormatDateTime('yyyy-mm-dd hh:nn:ss', Now), 
         LogLevelNames[Level], Operation, Details]));
  end;
end;

3. 다양한 테스트 전략

엣지 케이스를 잡기 위해 다양한 소스의 PDF로 테스트하세요:

문서 소스:

• 오피스 애플리케이션 (Microsoft Office, LibreOffice)
• 웹 브라우저 (Chrome, Firefox PDF 내보내기)
• PDF 생성 도구 (Adobe Acrobat, PDFCreator)
• 프로그래밍 라이브러리 (losLab PDF 라이브러리, PyPDF2, PyMuPDF)
• OCR 텍스트 레이어가 있는 스캔 문서
• 오래된 도구로 생성된 레거시 PDF

테스트 카테고리:

// 자동 테스트 스위트
procedure RunPDFCompatibilityTests;
begin
  TestSimpleDocuments();     // 기본 단일 페이지 PDF
  TestMultiPageDocuments();  // 복잡한 페이지 구조
  TestIncrementalUpdates();  // 개정 이력이 있는 문서
  TestEncryptedDocuments();  // 암호 보호 PDF
  TestFormDocuments();       // 대화형 양식
  TestCorruptedDocuments();  // 손상되거나 잘못된 형식의 PDF
end;

4. PDF 사양의 깊은 이해

PDF 사양(ISO 32000)에서 공부해야 할 핵심 섹션:

• 섹션 7.7.5: 페이지 트리 구조
• 섹션 7.5: 간접 객체와 참조
• 섹션 7.4: 파일 구조와 조직
• 섹션 12: 대화형 기능 (고급 파싱용)

핵심 알고리즘의 참조 구현을 만드세요:

// PDF 사양을 정확히 따르는 참조 구현
function BuildPageTreeFromSpec(RootRef: TPDFReference): TPageArray;
begin
  // ISO 32000 섹션 7.7.5를 정확히 따름
  PagesDict := ResolveReference(RootRef);
  KidsArray := PagesDict.GetValue('/Kids');
  
  for I := 0 to KidsArray.Count - 1 do
  begin
    PageRef := KidsArray.GetReference(I);
    PageDict := ResolveReference(PageRef);
    
    if PageDict.GetValue('/Type') = '/Page' then
      Result.Add(PageDict)  // 리프 노드
    else if PageDict.GetValue('/Type') = '/Pages' then
      Result.AddRange(BuildPageTreeFromSpec(PageRef)); // 재귀
  end;
end;

5. 자동 회귀 테스트

지속적 통합 테스트를 구현하세요:

# PDF 라이브러리용 CI/CD 파이프라인
pdf_tests:
  stage: test
  script:
    - ./run_pdf_tests.sh
    - ./validate_page_ordering.sh
    - ./compare_with_reference_implementations.sh
  artifacts:
    reports:
      junit: pdf_test_results.xml
    paths:
      - test_outputs/
      - debug_logs/

고급 디버깅 기법

성능 프로파일링

큰 PDF는 파싱 로직의 성능 병목을 드러낼 수 있습니다:

// 페이지 파싱 성능 프로파일
procedure ProfilePageParsing(PDF: THotPDF);
var
  StartTime, EndTime: TDateTime;
  ParseTime, ReorderTime: Double;
begin
  StartTime := Now;
  PDF.ParseAllPages;
  EndTime := Now;
  ParseTime := (EndTime - StartTime) * 24 * 60 * 60 * 1000; // 밀리초
  
  StartTime := Now;
  PDF.ReorderPageArrByPagesTree;
  EndTime := Now;
  ReorderTime := (EndTime - StartTime) * 24 * 60 * 60 * 1000;
  
  WriteLn(Format('파싱 시간: %.2f ms, 재정렬 시간: %.2f ms', [ParseTime, ReorderTime]));
end;

메모리 사용량 분석

파싱 중 메모리 할당 패턴을 추적하세요:

// PDF 작업 중 메모리 사용량 모니터링
procedure MonitorMemoryUsage(Operation: string);
var
  MemInfo: TMemoryManagerState;
  UsedMemory: Int64;
begin
  GetMemoryManagerState(MemInfo);
  UsedMemory := MemInfo.TotalAllocatedMediumBlockSize + 
                MemInfo.TotalAllocatedLargeBlockSize;
  WriteLn(Format('[MEMORY] %s: %d 바이트 할당됨', [Operation, UsedMemory]));
end;

크로스 플랫폼 검증

다른 플랫폼에서 동일한 PDF가 다르게 동작하는지 테스트하세요:

# Windows에서
HotPDF.exe test.pdf

# Linux에서 (Wine 사용)
wine HotPDF.exe test.pdf

# 결과 비교
diff windows_output.pdf linux_output.pdf

성능 개선

수정 후 측정된 성능 지표:

결론

이 디버깅 세션은 PDF 조작에서 몇 가지 중요한 통찰을 드러냈습니다:

기술적 통찰

• 논리적 순서 대 물리적 순서: PDF에서 가장 중요한 구별
• Pages 트리 구조: 항상 PDF 사양을 따라야 함
• 다중 파싱 경로: 모든 코드 경로에서 일관성 보장
• 견고한 오류 처리: 손상된 PDF에 대한 우아한 폴백

프로세스 통찰

• 체계적 디버깅: 가정을 테스트하고 증거를 수집
• 외부 도구: PDF 구조 분석을 위한 qpdf, cpdf 등 활용
• 참조 구현: 다른 라이브러리와 비교하여 검증
• 포괄적 로깅: 복잡한 파싱 프로세스 추적

프로젝트 관리 통찰

• 엣지 케이스 테스트: 다양한 PDF 소스로 테스트
• 회귀 방지: 자동 테스트 스위트 구현
• 문서화: 향후 참조를 위한 디버깅 프로세스 기록

궁극적으로, 이 경험은 PDF 조작 라이브러리를 개발할 때 표면적인 API 기능뿐만 아니라 기본 문서 구조를 깊이 이해하는 것의 중요성을 강조합니다. 겉보기에 간단한 “오프바이원” 오류가 PDF 사양의 핵심 개념에 대한 근본적인 오해를 드러낼 수 있습니다.

이 사례 연구가 유사한 PDF 관련 문제에 직면한 다른 개발자들에게 유용한 참고 자료가 되기를 바랍니다. 기억하세요: PDF 디버깅에서는 항상 사양을 신뢰하고, 가정을 테스트하며, 포괄적으로 로그를 남기세요.