거래명세서 인쇄 상태값 홀딩을 발행으로 통일

partner-portal 거래명세서 인쇄 기능에서 상태값이 간헐적으로 '홀딩'으로 표시되는 버그를 잡았다. 수정은 뷰/스타일 파일 한 개. 변경 범위는 작지만 짚어둘 게 있어서 기록한다.

왜 상태값 하나가 문제가 됐나

거래명세서 인쇄 화면에서 출력되는 상태값은 크게 두 갈래다. 세금계산서 발행 흐름에서 정상적으로 처리된 건은 '발행', 아직 처리되지 않은 건은 '홀딩'. 문제는 특정 조건에서 이미 처리가 끝난 건인데도 화면이 '홀딩'을 그대로 유지하는 경우가 있었다는 점이다.

파트너가 인쇄를 눌렀을 때 문서 위에 '홀딩'이 찍혀 있으면, 그 문서를 수신하는 쪽에서는 아직 처리 중인 건으로 읽을 수밖에 없다. 실제 처리 상태와 인쇄 결과물이 다르면 신뢰 문제로 번진다. 금액 한 자리가 아니라 상태 레이블 하나도 마찬가지다.

원인을 파고드니, 렌더링 단에서 상태값을 결정하는 조건 분기에 엣지 케이스가 하나 빠져 있었다. 대부분의 경우에는 정상 동작하고, 특정 처리 경로를 타는 건에서만 조건이 맞지 않아 '발행'으로 전환되지 못하고 '홀딩'이 남아 있었다. 화면 렌더링과 프론트 스크립트 양쪽을 같이 건드린 이유가 거기 있다. 스크립트에서 상태 판단 로직을 수정하고, 뷰에서 그 값을 받아 표시하는 부분도 함께 정리했다.

버그를 수정할 때 내가 보는 것들

증상만 픽스하면 비슷한 패턴의 버그가 다른 경로에서 다시 올라온다. 그래서 수정할 때 항상 같은 흐름을 밟는다.

이번에는 '홀딩'이 표시되는 케이스를 직접 재현한 뒤 수정, 다시 같은 경로로 인쇄를 눌러서 '발행'으로 바뀌는 걸 확인했다. 거기서 끝내지 않고 관련 거래 목록 화면에서 상태값을 비교해서 양쪽이 맞는지도 봤다.

조건 분기 처리 패턴을 보면, 이런 식으로 엣지 케이스를 명시적으로 열거하는 게 나중에 읽기 편하다.

function resolveDisplayStatus(status, processedAt) {
  if (status === 'issued' && processedAt) return '발행';
  if (status === 'holding') return '홀딩';
  // 처리 완료됐지만 status 갱신이 늦은 케이스
  if (processedAt && status !== 'cancelled') return '발행';
  return '홀딩';
}

원문에서 마지막 분기가 없었던 것이 이번 버그의 핵심이었다. processedAt이 찍혀 있는데 status가 갱신되지 않은 경우를 처리하지 않고 있었다. 실제 코드는 이 예시와 다르지만 구조적으로 같은 문제였다.

금융/결제 도메인에서 꼼꼼함이 기본값이어야 하는 이유

사내 서비스를 만들다 보면 기능 하나가 단순히 화면에 버튼 하나 추가하는 것으로 끝나지 않는다. SQL 집계, 상태 머신, 예외 처리, 화면 렌더링, 권한 체크가 모두 엮여 있어서 어느 하나만 빠뜨려도 숫자가 맞지 않거나 특정 사용자에게 이상한 화면이 나온다.

특히 거래 관련 문서는 금액과 상태값이 곧 합의 내용이다. 화면에서 '발행'으로 보이는 문서를 인쇄했는데 종이에 '홀딩'이 찍혀 있으면, 파트너는 무엇을 믿어야 할지 모른다. 이런 불일치가 한 번 쌓이면 나중에는 매번 확인 전화가 오거나, 더 나쁜 경우엔 그냥 시스템을 신뢰하지 않게 된다. "대충 맞는 것 같다"로 넘기면 반드시 다시 돌아온다.

개발 방식으로는 수정 전에 현재 동작을 메모나 스크린샷으로 남겨두는 습관을 유지하고 있다. 수정 후에 같은 케이스로 확인하고, 관련 화면이 있으면 숫자 cross-check. 커밋 메시지는 "무엇을"보다 "왜"를 담으려고 한다. 이번은 fix: 거래명세서 인쇄 시 발행 완료 건 상태값 홀딩 잔류 수정 정도로 남겼다.

작은 커밋을 자주 하면 문제가 생겼을 때 어느 변경에서 깨졌는지 찾기 훨씬 쉽다. 그래서 논리적으로 독립된 단위로 쪼개는 습관을 계속 유지 중이다. 이번처럼 뷰와 스크립트를 동시에 건드리더라도, 로직 수정과 스타일 정리는 커밋을 나눌 수 있으면 나눈다.

엣지 케이스를 꼼꼼히 따지는 게 귀찮아 보여도, 나중에 같은 버그로 다시 오는 시간 비용이 훨씬 크다. 오늘 10분 더 쓰는 게 다음 달 두 시간짜리 디버깅을 막는다.