PDF 영수증 섹션 추가로 컴플라이언스 문서 완성

PDF 다운로드 기능에 영수증 섹션을 추가하고, 관련 SQL 쿼리의 컬럼 alias를 한글로 정리한 작업이었다.

왜 이 작업이 필요했나

사내 서비스에서 PDF 형태로 문서를 내보내는 기능은 이미 존재했다. 그런데 기존 PDF에는 핵심적인 영수증 섹션이 빠져 있었고, 실제 운영자나 담당자 입장에서 이 PDF만 뽑아서 제출하거나 보관하기엔 정보가 부족한 상태였다. 컴플라이언스 관점에서 문서 한 장으로 이력이 설명돼야 하는데, 영수증 정보가 빠진 채로 발급된다는 건 결국 "쓸 수 없는 문서"나 다름없다.

팀 내에서도 이 부분이 오래된 숙제였다. 기능은 돌아가는데 정작 외부에 내보낼 때 쓸 수 없는 것들 — 이런 게 레거시 시스템에는 생각보다 많다. 리더 입장에서 이런 이슈는 우선순위 조율이 가장 어렵다. 서비스가 터지는 버그도 아니고, 그렇다고 무기한 미룰 수도 없는 것들. 이번엔 컴플라이언스 요건이 명확했기 때문에 타이밍을 잡아서 직접 처리했다.

무엇을 바꿨나

변경된 파일은 크게 세 영역이다.

SQL 코드 alias를 한글로 바꾼 것도 작은 일처럼 보이지만 나름 이유가 있었다. 기존에 영문 alias가 섞여 있던 상태라, 레포트 렌더링 시 컬럼 이름이 그대로 라벨로 노출되는 구조였다. 한글 alias로 통일하면 별도 매핑 테이블이나 하드코딩된 한글 라벨 없이도 화면/PDF 출력이 자연스럽게 맞아떨어진다. 유지보수 시에도 쿼리 한 곳만 보면 되니까.

-- before
SELECT
    rcpt_no     AS receiptNo,
    pay_amt     AS payAmount,
    pay_dt      AS payDate

-- after
SELECT
    rcpt_no     AS 영수증번호,
    pay_amt     AS 결제금액,
    pay_dt      AS 결제일시

물론 이 방식이 항상 정답은 아니다. 영문 alias를 유지하면서 별도 메시지 프로퍼티나 리소스 파일로 라벨을 관리하는 게 더 체계적인 경우도 있다. 하지만 이 프로젝트의 구조상 레포트 매퍼와 출력 라벨이 1:1로 묶여 있어서, 한글 alias가 오히려 일관성을 높이고 혼선을 줄이는 선택이었다.

PDF 영수증 섹션 붙이는 작업, 생각보다 신경 쓸 게 많다

PDF 생성 자체는 유틸 클래스가 이미 있었으니 "섹션 하나 추가"처럼 들릴 수 있다. 그런데 실제로 해보면 신경 쓸 포인트가 꽤 된다.

• 데이터 누락 케이스: 영수증 정보가 없는 경우(취소, 환불, 미결제 등)를 어떻게 처리할지 — 섹션 자체를 숨길지, 빈 섹션으로 두고 "정보 없음"을 표기할지
• 레이아웃 깨짐: 기존 PDF 구조에 섹션을 끼워 넣으면 페이지 넘침, 여백 붕괴가 쉽게 일어남
• 쿼리 타이밍: 영수증 데이터를 PDF 생성 시점에 새로 조회할지, 이미 조회된 데이터를 재활용할지 — N+1이 발생하지 않도록 주의
• 출력 인코딩: 한글이 포함된 PDF는 폰트 설정을 잘못 건드리면 깨진 문자가 나옴

이번 작업에서도 레이아웃 부분에서 한 번 삽질했다. 영수증 테이블이 예상보다 로우가 많은 케이스에서 페이지가 넘어가면서 다음 섹션 헤더가 이상한 위치에 렌더링됐다. 유틸 클래스 쪽을 조금 손봐서 섹션 단위로 페이지 브레이크를 제어하도록 처리했다.

회고

컴플라이언스 성격의 기능은 "일단 돌아간다"로 끝내면 안 된다. 실제로 문서로서의 기능을 해야 하고, 그 문서가 어떤 맥락에서 쓰이는지까지 팀이 이해하고 있어야 한다. 이번 작업을 하면서 팀원들한테도 "이 PDF가 어디에 쓰이는 문서인지"를 같이 설명했다. 코드만 고치는 게 아니라 맥락을 공유하는 게 결국 더 나은 리뷰와 더 적은 재작업으로 이어진다.

SQL alias 한글화도 마찬가지다. 누군가 처음 볼 때 receiptNo보다 영수증번호가 훨씬 빠르게 읽힌다. 가독성은 코드 퀄리티의 일부다.

끝.