compliance PDF 필드 어긋남을 5개 섹션 일괄 정정

PDF 렌더링 결과물에서 데이터가 칸을 벗어나거나 엉뚱한 필드에 찍히는 버그를 발견해서, Java 매퍼 클래스 5개 섹션을 한 번에 정정한 작업이다.

왜 이게 문제였나

compliance 도메인 특성상 PDF 출력은 단순 화면 표시가 아니다. 법적·행정적 효력을 갖는 문서인 경우가 많기 때문에, 필드 하나가 어긋나면 내용 오독이나 검수 실패로 직결된다. 그런데 이번에 확인된 건 단순히 한 섹션이 틀린 게 아니라 5개 섹션에 걸쳐 동일한 패턴의 어긋남이 있었다는 점이다.

이런 류의 버그는 보통 다음 시나리오 중 하나에서 발생한다.

• PDF 양식 템플릿을 갱신하면서 필드 좌표/순서가 바뀐 반면, Java 매퍼 클래스는 이전 버전 기준으로 유지된 경우
• 기획 변경으로 DB 컬럼이나 DTO 필드 순서가 변경됐는데, 매퍼만 업데이트가 누락된 경우
• 최초 매퍼 작성 시 섹션별 인덱스를 하드코딩해 두고, 이후 섹션이 추가되면서 offset이 밀린 경우

이번 케이스는 세 번째 패턴에 가까웠다. 섹션 구조가 일부 확장되면서 이후 섹션의 필드 순번이 전부 한 칸씩 밀려 있었고, 그게 5개 섹션에 도미노처럼 영향을 준 상태였다.

작업 내용 — 5섹션 일괄 정정

변경 대상은 egovframework 기반 유틸리티 레이어 내부에 있는 PDF 매퍼 클래스다. eGovFramework 구조에서 PDF 매퍼는 보통 iTextPDF 혹은 별도 라이브러리를 래핑해서 필드명 또는 인덱스 기반으로 값을 주입하는 방식으로 작성된다. 대략 아래 같은 패턴이다.

// 필드 인덱스 기반 매핑 (문제가 발생하기 쉬운 패턴)
pdfField[10] = dto.getApproverName();   // 원래 9였어야 함
pdfField[11] = dto.getApproverDate();   // 원래 10였어야 함
// ...이하 5섹션 동일하게 밀려 있던 상태

// 정정 후 — 인덱스 재정렬
pdfField[9]  = dto.getApproverName();
pdfField[10] = dto.getApproverDate();

단순해 보이지만, 5개 섹션을 "일괄"로 건드린다는 건 변경 라인 수가 적지 않다는 뜻이다. 각 섹션마다 필드가 수 개~십수 개씩 있었을 테니, 실질적으로 수십 라인의 인덱스 또는 필드명을 정정한 셈이다.

이런 작업에서 내가 늘 강조하는 건 한 섹션씩 순차적으로 확인하고 커밋 단위를 명확히 끊어라는 것인데, 이번엔 오히려 5섹션을 한 커밋으로 묶었다. 이유는 간단하다. 섹션 간 의존성이 있기 때문에 중간 상태로 배포되면 오히려 부분적으로만 고쳐진 PDF가 나가는 게 더 위험하다. compliance 문서는 "절반만 맞는 것"이 "전부 틀린 것"보다 더 나쁜 결과를 낼 수 있어서, 원자적으로 묶는 게 맞다고 판단했다.

회고 — 이런 버그를 팀 차원에서 어떻게 막을 것인가

팀 리더 입장에서 이 버그가 찜찜한 이유는 코드 리뷰에서 걸렸어야 할 사안이라는 점이다. 필드 매핑 어긋남은 사람이 보면 숫자 하나 차이라 놓치기 쉽지만, 구조적으로 막는 방법은 분명히 있다. 다음 스프린트에서 매퍼 클래스 전반의 하드코딩 인덱스를 상수화하는 작업을 태스크로 올려 두었다.

PDF 관련 버그는 QA 단계에서 눈으로 찾는 경우가 많은데, 그게 반복되면 QA 리소스가 낭비된다. 자동화 테스트로 커버하거나, 아니면 적어도 "템플릿이 바뀌면 매퍼를 반드시 같이 리뷰한다"는 팀 규칙을 명문화하는 것이 장기적으로 훨씬 낫다.

끝.