파트너 포털 정산 대기 상세

partner-portal 영역에 정산 대기 상세 기능을 추가했다. 겉으로는 뷰/스타일 파일 하나 변경이지만, 그 앞단에서 쿼리 설계부터 다시 했고 대시보드 잔액 계산 로직까지 함께 손봤음.

왜 쿼리 레벨부터 설계했나

기존 대시보드는 잔액 합계를 보여주고 있었는데, 파트너 입장에서 "이 숫자가 어떻게 구성된 건지"를 들여다볼 방법이 없었다. 정산 대기 상태에 있는 건들이 각각 얼마인지, 어느 시점에 묶인 건지. 화면에서 못 보니까 문의가 생기고, 문의가 생기면 내부에서 DB 직접 조회해서 답해야 하는 구조였음.

그냥 기존 API 응답에 필드 하나 더 얹는 방식도 고려했다. 빠르긴 한데, 그렇게 하면 집계 기준이 분산된다. 대시보드 잔액은 A 쿼리, 상세 내역은 B 쿼리인데 집계 조건이 미묘하게 달라지면 숫자가 안 맞는 사태가 생김. 금융/결제 도메인에서 화면마다 숫자가 다르게 나오면 신뢰 문제로 직결되기 때문에, 처음부터 같은 집계 기준을 공유하게끔 쿼리 레벨에서 정리하고 시작했다.

실행 계획도 먼저 확인했다. 정산 대기 건은 상태 컬럼 + 날짜 범위로 필터링하는 구조인데, 인덱스를 제대로 타지 않으면 파트너 수가 늘수록 대시보드 로딩이 느려지는 문제가 된다. 지금은 데이터 규모가 크지 않더라도 설계 시점에 실행 계획 체크하는 게 습관이 됐음.

구현 흐름

백엔드 API 엔드포인트를 새로 뚫고, 프론트는 JSP + AJAX로 연동하는 구조다. 스택이 레거시에 가깝지만 기존 포털 전체가 이 패턴으로 돼 있어서 일관성을 유지하는 게 맞다고 봤음.

// 정산 대기 내역 조회 - 페이지 진입 시 즉시 호출
function loadSettlementPending() {
  $.ajax({
    url: '/partner/api/settlement/pending',
    type: 'GET',
    success: function(res) {
      if (res.code === '0000') {
        renderPendingList(res.data);
        updateDashboardBalance(res.data.totalAmount);
      }
    },
    error: function() {
      // 에러 시 기존 잔액 유지, 상세 영역만 빈 상태 표시
    }
  });
}

실시간 갱신 여부도 결정해야 했다. 폴링을 걸어서 자동 갱신할 수도 있는데, 정산 대기 상태는 배치나 어드민 처리 시점에 바뀌는 거라 사용자가 화면 보는 동안 실시간으로 바뀔 일이 거의 없다. 폴링 넣으면 서버 부하만 올라가고 사용자 경험에 실질적인 이득이 없음. 그래서 페이지 진입 시 1회 조회로 결정했다.

권한 인터셉터 통과 확인도 빠뜨리면 안 된다. 포털 특성상 파트너마다 접근 가능한 데이터 범위가 다르고, 신규 엔드포인트는 인터셉터 설정에서 누락되기 쉬운 구멍이 생긴다. 직접 다른 파트너 계정으로 로그인해서 내 데이터가 보이는지 확인했음.

사이드바 메뉴 활성화 처리도 작은 것 같지만 UX에서 꽤 중요하다. 어느 메뉴에 있는지 모르면 사용자가 길을 잃음.

검증에서 신경 쓴 부분

금융 도메인에서 cross-check를 제대로 안 하면 "대충 맞는 것 같다"로 넘어가게 된다. 그게 나중에 반드시 돌아온다는 걸 경험으로 알고 있어서, 기능 하나 배포할 때마다 관련된 모든 숫자를 직접 눈으로 확인하는 루틴을 유지하고 있음.

예외 케이스는 정상 케이스보다 더 꼼꼼하게 봐야 한다. 빈 데이터일 때 에러가 터지거나, NULL이 집계 함수에서 예상치 못하게 동작하거나, 권한 체크가 뚫리거나. 이런 케이스는 QA 단계에서 잡기보다 설계 시점에 방어 코드를 먼저 넣는 게 훨씬 낫다.

사내 서비스 기능 하나가 화면 버튼 하나로 끝나는 경우가 없다는 걸 이번에도 다시 체감했다. SQL 집계 조건, 상태값 관리, 예외 처리, 화면 렌더링, 권한 체크가 전부 엮여 있고, 어느 하나라도 기준이 달라지면 숫자가 맞지 않거나 특정 사용자에게 이상한 화면이 보인다.

커밋도 논리 단위로 쪼개서 남겼다. 쿼리 변경, API 추가, 프론트 연동, 권한 처리를 각각 커밋으로 분리했음. 나중에 뭔가 깨졌을 때 어느 변경에서 문제가 생겼는지 추적하려면 이게 훨씬 편하다. 커밋 메시지도 "무엇을 바꿨다"보다 "왜 바꿨는지"에 무게를 두려고 했고, 이번 작업은 "집계 기준 분산 방지를 위해 대시보드 잔액 쿼리와 상세 조회를 동일 기준으로 통합"이 핵심 이유였다.