멀티시스템 조회 범위 식별자 미전파

targetSysId 전파 누락이 여러 조회 흐름에서 조용히 문제를 일으키고 있었다.

왜 이 수정이 필요했나

운영 중에 특정 조회 기능에서 targetSysId 값이 GLOBAL로 내려가야 하는 상황임에도 불구하고, 하위 호출까지 전파가 되지 않는 케이스가 있었다. 처음엔 단순 조회 결과 불일치 정도로 보였는데, 파고들수록 web 레이어에서 파라미터를 담은 시점과 실제 쿼리 매퍼에 넘어가는 시점 사이에 값이 소실되거나 기본값으로 덮이는 구조적인 흐름이 있었다.

targetSysId는 멀티 시스템 환경에서 어느 시스템 범위의 데이터를 대상으로 할지 구분하는 식별자다. 이 값이 GLOBAL이면 전체 시스템 범위, 특정 값이면 그 시스템에 종속된 데이터만 처리한다. 이게 제대로 전파되지 않으면 조회 결과가 범위 초과이거나 범위 미달이거나 두 가지 중 하나가 된다. 둘 다 컴플라이언스 측면에서 허용할 수 없는 상태다.

무엇을 바꿨나

변경이 일어난 파일은 크게 두 곳이다.

web 레이어에서는 targetSysId가 명시적으로 넘어오지 않는 케이스에 GLOBAL을 기본값으로 세팅하고, 이후 서비스 호출 체인 전체에 그 값이 따라가도록 VO나 Map 구조에 확실히 심어두는 방식으로 수정했다. 보통 이런 류의 전파 누락은 중간 레이어에서 새 객체를 만들거나 파라미터를 재조립할 때 특정 필드를 빠뜨리는 패턴에서 발생한다. 코드 리뷰 때 체크리스트에 "조회 맥락 파라미터가 모든 하위 호출까지 내려가는가"를 항목으로 박아두는 이유가 이 때문이다.

쿼리 매퍼 쪽에서는 페이징 처리 방식과 인터페이스가 기능마다 미묘하게 달랐던 부분을 통일했다. 어떤 쿼리는 pageIndex / pageSize 조합을 쓰고, 어떤 쿼리는 rowIndex / pageUnit을 쓰는 식으로 제각각이었는데, 이게 web 레이어에서 공통 페이징 VO를 쓰는 구조와 맞지 않아 특정 상황에서 전체 건수를 가져오거나 페이징이 무시되는 문제로 이어지고 있었다.

<!-- 변경 전 패턴 (개별 쿼리마다 파라미터 명세가 달랐음) -->
<if test="pageUnit != null">
  LIMIT #{pageUnit} OFFSET #{firstIndex}
</if>

<!-- 변경 후 통일 패턴 -->
<if test="pageSize != null">
  LIMIT #{pageSize} OFFSET #{pageIndex}
</if>

작아 보이는 차이지만 공통 VO와 파라미터 명세가 어긋나면 MyBatis가 조용히 null을 넘기거나 0을 넘겨서 쿼리가 의도와 다르게 동작한다. 로그에는 에러가 안 찍히니 더 잡기 까다롭다.

팀 관점에서 남기는 메모

이 작업은 기능 추가가 아니라 기존 흐름의 일관성을 맞추는 작업이었다. 팀 내에서 이런 수정은 우선순위 책정이 애매해지는 경우가 많다. 급하게 터진 것도 아니고, 눈에 딱 보이는 장애도 아니니까. 그런데 컴플라이언스 관련 조회에서 범위가 어긋나는 건 기능 버그보다 훨씬 조용하게 신뢰를 깎는다.

• targetSysId 같은 맥락 파라미터는 서비스 진입점에서 한 번 명확히 결정되어야 하고
• 결정된 값은 이후 호출 체인에서 절대 재정의되거나 소실되지 않는 구조로 만들어야 하며
• SQL 레이어의 인터페이스는 공통 페이징 VO 기준으로 일치시켜야 한다

멤버 서비스 담당 팀원들한테도 이번 패턴 공유하고, 다른 조회 기능들도 같은 관점에서 셀프 리뷰 한 번 돌아보도록 요청해뒀다. 누락된 전파 포인트 추가로 두어 개 나올 것 같다.

끝.