중계결제 바텀시트에 브랜드 이용안내 노출 기능 추가

relay-pay 영역에 기능 하나를 추가했다. 중계결제 바텀시트에 브랜드 이용안내를 노출하는 것. 변경된 파일은 SQL 매퍼 1개, 뷰/스타일 1개. 파일 수만 보면 작은 작업이지만 실제로는 쿼리 설계부터 화면 렌더링까지 수직으로 한 줄을 다 뚫은 작업이었다.

중계결제 바텀시트는 사용자가 결제 전 최종 확인하는 지점이다. 여기서 브랜드별 이용안내를 보여주려면, 기존 API 응답에 해당 데이터가 없었기 때문에 쿼리 레벨부터 새로 설계해야 했다. 단순 UI 추가였으면 컴포넌트 하나 끼워 넣고 끝이었겠지만, 없던 데이터를 만들어야 한다는 게 포인트였다.

설계할 때 생각한 것들

금융/결제 도메인 특성상 데이터 정합성이 가장 먼저였다. 새 필드 하나를 추가할 때 기존 집계나 상태값이 틀어지면 다른 화면의 숫자까지 영향을 받는다. 그래서 이번 작업에서도 쿼리를 작성하고 나서 실행 계획을 먼저 확인했다.

고려한 항목들을 정리하면:

• 기존 결제 집계 데이터와의 정합성 유지 - 새 조인이 기존 row를 뻥튀기하거나 누락시키지 않는지
• 실시간 갱신 필요 여부 - 브랜드 이용안내 텍스트는 세션 중 바뀔 일이 거의 없어서 폴링보다 초기 로드 시 한 번 가져오는 방식으로 결정
• 예외 케이스 방어 - 브랜드 이용안내가 등록되지 않은 케이스, NULL, 권한 없는 접근 모두 방어 분기 처리
• 성능 영향도 - 기존 쿼리에 조인 하나가 추가되는 구조라 실행 계획 확인 후 인덱스 타는지 검증

쿼리 쪽 변경은 대략 이런 구조였다. 기존 매퍼에 메서드 하나를 추가하고, 브랜드 이용안내 텍스트를 가져오는 SELECT를 붙였다.

<!-- SQL 매퍼 예시 패턴 -->
<select id="selectBrandUsageGuide" parameterType="map" resultType="BrandUsageGuideDto">
    SELECT
        b.brand_id,
        b.usage_guide,
        b.guide_updated_at
    FROM brand_usage_guide b
    WHERE b.brand_id = #{brandId}
      AND b.use_yn = 'Y'
</select>

NULL이 올 수 있는 필드라 서비스 레이어에서 Optional로 감싸고, 뷰에는 가이드 텍스트가 있을 때만 영역 자체를 렌더링하도록 조건 분기를 뒀다. 없으면 없는 대로 화면에 빈 블록이 뜨는 게 아니라 아예 노출하지 않는 방식.

검증 방법

구현 후 검증은 두 단계로 했다.

첫 번째는 브랜드 이용안내가 있는 케이스와 없는 케이스를 직접 바텀시트에서 열어 확인. 텍스트가 정상적으로 뜨는지, 없는 케이스는 해당 영역이 아예 숨겨지는지.

두 번째는 cross-check. 이 기능을 추가하면서 결제 집계 화면의 숫자가 변하거나 기존 데이터가 깨지면 안 되기 때문에, 변경 전에 스크린샷으로 수치를 기록해두고 변경 후 같은 화면을 열어 비교했다. 숫자가 하나라도 다르면 원인을 추적해야 한다는 기준으로.

작업 후기

사내 결제 서비스를 다루다 보면 "기능 하나 추가"가 얼마나 여러 레이어를 건드리는지 매번 실감한다. 바텀시트에 텍스트 하나 보여주는 것도 쿼리, 매퍼, 서비스, 뷰, 스타일이 다 연결된다. 어느 한 레이어에서 방어가 빠지면 특정 브랜드에서만 이상한 화면이 나오거나 NULL 에러가 터진다.

금융/결제 도메인에서 "대충 맞는 것 같다"는 선택지가 없다. 숫자가 1원이라도 다르거나 이용안내 내용이 잘못 노출되면 신뢰 문제로 직결된다. 그래서 꼼꼼함이 기본값이어야 한다는 걸 팀 전체가 공유하고 있고, 이번 작업도 그 기준으로 진행했다.

커밋은 논리적으로 독립된 단위로 쪼갰다. 쿼리 추가, 서비스 메서드 연결, 뷰 렌더링 이렇게 세 커밋. 파일 두 개 고쳤는데 커밋을 왜 세 번 하냐 싶을 수 있는데, 나중에 특정 변경에서 버그가 발생했을 때 어느 커밋이 원인인지 바로 좁혀지는 게 이 습관의 이유다. 커밋 메시지도 "무엇을 했다"보다 "왜 했다"를 담으려고 노력한다. 3개월 후에 git log를 볼 때 의도가 남아있어야 하니까.