파트너 상세에서 후불 청구서로 바로 이동하는 기능 추가

admin-partner 영역에 작은 기능을 하나 추가했다. 파트너 상세 화면에서 해당 파트너의 후불 청구서로 바로 이동하는 링크다. 변경된 파일은 내부 클래스 하나, 뷰/스타일 하나. 숫자만 보면 별거 아닌 것 같지만, 실제로 손대야 하는 레이어는 그보다 훨씬 많았다.

왜 이게 필요했나

파트너 상세 화면은 말 그대로 파트너의 기본 정보를 보여주는 곳이다. 그런데 운영 쪽에서 파트너를 확인할 때 가장 자주 필요한 정보가 "이 파트너 후불 청구서 어떻게 됐어?"였다. 기존 흐름은 파트너 상세 → 메뉴로 나가기 → 청구서 목록 → 해당 파트너 검색 → 필터링 순이었고, 클릭 수가 꽤 됐다. 반복적으로 쓰이는 경로가 이렇게 길면 사람이 지치고 실수가 생긴다. 내부 도구라고 UX를 무시하면 결국 운영 효율이 떨어지고, 정작 더 많은 문의가 들어온다.

단순히 링크 하나 추가하는 것처럼 보여도, 화면이 렌더링할 데이터가 기존 API 응답에 없으면 백엔드부터 손대야 한다. 이번에도 그랬다. 파트너 상세 API가 후불 청구서 식별자를 내려주지 않고 있었고, 그걸 먼저 뚫어야 했다. 단순 UI 추가가 아니라 쿼리 레벨부터 설계해서 정합성을 맞췄다고 한 이유가 이것이다.

구현 흐름

내부 클래스에 메서드를 추가하고, SQL 매퍼에 쿼리를 작성하고, 화면에서 받아 렌더링했다. 순서대로 쓰면 간단해 보이는데, 레이어마다 확인해야 할 게 있었다.

쿼리 쪽에서 제일 먼저 확인한 건 파트너-청구서 관계가 1:1인지 1:N인지였다. 무제한 파트너의 경우 청구 주기나 계약 구조에 따라 청구서가 여러 개일 수 있어서, 화면에 무엇을 보여줄지 정책을 먼저 정해야 했다. 가장 최근 것으로 결정했고, 쿼리에 정렬 조건과 LIMIT를 명시했다.

-- 예시 구조 (실제 테이블명/컬럼명은 내부 컨벤션)
SELECT invoice_id, status, billing_date
FROM partner_invoices
WHERE partner_id = #{partnerId}
  AND billing_type = 'POSTPAID'
ORDER BY billing_date DESC, invoice_id DESC
LIMIT 1

LIMIT 1을 걸 때 주의할 게 있다. 같은 billing_date를 가진 레코드가 두 개 이상이면 결과가 비결정적이 된다. 타이브레이커로 invoice_id DESC를 추가해서 최신 삽입 기준으로 고정했다. 작은 디테일이지만, 이게 빠지면 같은 화면이 실행할 때마다 다른 청구서를 가리킬 수 있다.

화면 쪽은 비교적 단순했다. 청구서 ID가 있으면 링크를 렌더링하고, 없으면(신규 파트너거나 청구서가 아직 생성 안 된 케이스) 텍스트로 "-"를 찍었다. 권한 체크는 파트너 상세 진입 시점에서 이미 걸려 있어서 별도로 추가하지 않았는데, 이건 그냥 넘긴 게 아니라 확실히 확인하고 결정한 것이다. 권한 레이어를 중복으로 깔 필요는 없지만, 없다고 착각하고 넘겼다가 구멍이 생기면 더 큰 문제가 된다.

금융 도메인에서 데이터를 다룰 때

파트너 상세에서 보이는 청구서 링크가 실제 청구서 목록에서 필터링되는 결과와 일치해야 한다. 당연해 보이는데, 쿼리 조건이 미묘하게 달라서 숫자가 맞지 않는 경우가 생각보다 자주 나온다. 한쪽은 status != 'CANCELLED'를 제외하고 다른 쪽은 포함하거나, 타임존 처리가 달라서 날짜 경계에서 한 건 차이가 나는 식이다.

이번에 새로 추가한 쿼리는 기존 청구서 목록 쿼리의 필터 조건을 맞춰서 작성했다. 확인한 항목을 정리하면 이렇다.

검증은 직접 화면에서 했다. 청구서가 있는 파트너, 청구서가 하나도 없는 파트너, 청구서가 여러 개인 파트너 세 케이스를 골라서 링크가 맞는 화면으로 이동하는지, 청구서 목록 필터 결과와 숫자가 일치하는지 cross-check했다.

사내 어드민을 만들다 보면, 기능 하나를 추가할 때마다 느끼는 게 있다. "이게 왜 없었지?"보다 "이게 이렇게 엮여 있었구나"가 더 자주 나온다. SQL 집계, 상태 머신, 예외 처리, 화면 렌더링, 권한 체크가 전부 물려 있어서 어느 하나만 빠뜨려도 특정 케이스에서 이상한 화면이 나오거나 숫자가 틀린다.

금융/결제 도메인은 특히 그렇다. 숫자 하나가 화면마다 다르게 보이면, 운영팀은 어느 쪽을 믿어야 할지 모르게 되고, 그 신뢰 회복이 코드 고치는 것보다 훨씬 오래 걸린다. "대충 맞는 것 같다"는 판단은 나중에 반드시 다시 돌아온다. 꼼꼼함이 선택이 아니라 기본값이어야 하는 이유다.

개발 방식 면에서 요즘 지키려는 루틴이 몇 가지 있다. 변경 전 현재 동작을 메모하거나 수치를 기록해두고, 수정 후 같은 케이스로 확인하는 것. 관련 화면이 있으면 숫자 cross-check까지. 커밋 메시지는 "무엇을" 보다 "왜"를 담으려 한다. 나중에 git log 볼 때 코드는 diff로 보이는데, 이유는 메시지에 없으면 맥락을 잃는다.

작은 커밋을 논리 단위로 쪼개는 습관도 계속 유지 중이다. 이번엔 백엔드 클래스/쿼리 추가, 뷰 연동, 스타일 조정을 레이어 단위로 나눠 커밋했다. 문제가 생겼을 때 어느 변경에서 깨졌는지 찾기 훨씬 쉬워지고, 리뷰할 때도 한 커밋에서 너무 많은 맥락을 추적하지 않아도 된다.