파트너 포털 헤더 아이콘 이름 오류 수정

partner-portal 헤더에서 정보 칩 아이콘 이름이 잘못 렌더링되는 버그를 수정했다. 변경 파일은 뷰/스타일 1개. 겉으로는 단순한 픽스처럼 보이지만, 이런 작은 버그가 왜 생기는지, 어떻게 방지할 수 있는지 정리해두려고 한다.

아이콘 이름 하나가 왜 문제가 되나

UI 컴포넌트 라이브러리를 쓸 때 아이콘은 문자열 이름으로 참조하는 경우가 많다. <Icon name="user-check" /> 같은 식으로. 이 이름이 라이브러리에 실제로 존재하는 심볼과 정확히 매핑되어야 하는데, 매핑이 어긋나면 빈 공간이 나오거나, fallback 아이콘이 나오거나, 콘솔에 warning이 조용히 쌓인다.

파트너 포털 헤더의 정보 칩은 상태나 카테고리를 시각적으로 구분하는 역할을 한다. 아이콘이 틀리면 그냥 "좀 이상하다"로 끝나는 게 아니라, 포털을 쓰는 파트너가 현재 상태를 잘못 읽을 수 있다. 금융/결제 도메인에서 포털을 운영하다 보면 숫자보다 상태 지시자를 더 먼저 보는 경우가 생각보다 많아서, 시각적 정확성이 가볍지 않다.

이번 버그의 원인은 특정 엣지 케이스에서 아이콘 이름이 잘못된 값으로 결정되는 로직이었다. 그 경로만 타면 렌더링이 빗나가는 식. 기존 로직에서 해당 케이스가 처리되지 않고 넘어가고 있었고, 평상시엔 괜찮다가 조건이 맞아야만 드러나는 종류의 버그였다.

아이콘 이름 오류는 정적 분석으로 잡기 애매한 편이다. 타입스크립트를 쓴다면 아이콘 이름을 리터럴 유니온 타입으로 강제하는 방법이 있다.

// 아이콘 이름을 열거형으로 제한하면 컴파일 타임에 오타나 잘못된 값을 잡을 수 있다
type IconName = 'check-circle' | 'x-circle' | 'info' | 'alert-triangle'

interface IconProps {
  name: IconName
  size?: number
}

이렇게 하면 존재하지 않는 이름을 넘기는 순간 빌드가 실패한다. 런타임에서 조용히 빈 공간이 되는 것보다 훨씬 낫다. 다만 아이콘 셋이 수백 개라면 유니온 타입 관리 자체가 피곤해지기 때문에, 아이콘 라이브러리 쪽에서 타입을 익스포트하는 구조를 별도로 만들거나, 빌드 시점에 자동 생성하는 방식이 현실적이다. 트레이드오프가 있어서 규모에 맞는 방법을 골라야 한다.

수정 접근 방식

증상만 보고 바로 코드 고치는 게 아니라, 먼저 어떤 조건에서 재현되는지 확정했다. 재현 조건이 명확해지면 수정 범위가 자연히 좁아진다. "될 것 같다"로 머지하면 비슷한 조건에서 또 터진다.

이번 수정은 뷰/스타일 파일 1개였지만, 비슷한 패턴이 있는 부분은 함께 확인했고 위험한 케이스는 묶어서 처리했다. 단순히 보고된 케이스만 픽스하면 바로 옆에서 같은 원인으로 다른 증상이 나올 가능성이 남는다.

수정 전에는 현재 동작 상태를 메모해두고, 수정 후 같은 케이스로 다시 확인하는 게 습관으로 자리 잡은 지 오래됐다. 관련 화면이 있으면 수치나 상태 표시를 cross-check하는 것도 포함해서.

작은 버그에서 꺼내 쓸 수 있는 것

사내 서비스를 만들다 보면 화면에 버튼 하나 추가하는 것처럼 보이는 작업도, 뒤로는 SQL 집계, 상태 머신, 예외 처리, 화면 렌더링, 권한 체크가 전부 엮여 있다는 걸 계속 체감하게 된다. 어느 하나만 빠뜨려도 숫자가 어긋나거나 특정 사용자에게 이상한 화면이 나온다. 이번 건은 아이콘 이름이라 렌더링 영역에 국한됐지만, 같은 원인 구조가 더 중요한 데이터 흐름에 있었다면 영향 범위가 달랐을 거다.

금융/결제 도메인에서는 숫자 하나가 틀리면 파트너 신뢰가 흔들릴 수 있어서, "대충 맞는 것 같다"로 넘어가는 선택지가 애초에 없다. 꼼꼼함이 옵션이 아니라 기본값이어야 하는 이유가 거기 있다. 엣지 케이스를 따지는 게 당장은 귀찮아 보여도, 같은 버그로 나중에 다시 돌아오는 시간 비용이 훨씬 크다는 걸 경험할수록 더 실감한다.

커밋 단위도 이번에 다시 생각했다. 작은 버그라도 논리적으로 독립된 단위로 쪼개서 커밋하면, 나중에 어떤 변경에서 회귀가 생겼는지 추적할 때 시간을 아낄 수 있다. 커밋 메시지는 "무엇을 바꿨다"보다 "왜 바꿨다"를 담으려고 의식적으로 신경 쓰는 중이다. fix: 헤더 칩 아이콘 이름 수정보다 fix: 엣지 케이스에서 아이콘 이름이 잘못 결정되는 로직 수정이 나중에 git log를 뒤졌을 때 훨씬 유용하다. "무엇"은 diff를 보면 알지만 "왜"는 메시지에 없으면 영원히 모른다.