관리자 로그인과 2FA 화면의 용어 일관성 개선

관리자 로그인과 2FA 화면에서 같은 개념을 다른 단어로 표현하고 있었다. 한쪽에선 "인증 코드", 다른 쪽에선 "확인 번호". 기능적으로 같은 걸 가리키는데 화면마다 달랐다. 사용자 입장에선 사소해 보일 수 있지만, 관리자 로그인 플로우는 보안 맥락이 강한 영역이라 용어가 흔들리면 "내가 지금 맞는 걸 입력하고 있는 건가?" 하는 불안감을 만든다. 특히 2FA 같은 단계는 사용자가 실패할 때 다시 천천히 화면을 읽는다. 그 순간 용어가 일관되지 않으면 UX 이탈보다 더 안 좋은 신뢰 문제로 번진다.

변경 파일은 뷰 1개, 스타일 1개. 커밋 범위는 작지만 이유를 제대로 이해하고 고쳐야 했다.

왜 UI 용어 불일치가 버그가 되는가

코드 로직 버그처럼 눈에 확 띄지 않아서 방치되기 쉬운 유형이 UI 텍스트 불일치다. 기능은 동작하고, 콘솔에 에러도 없으니 테스트도 통과한다. 그런데 관리자 입장에서 로그인 화면에서 배운 단어와 2FA 화면에서 쓰는 단어가 달라지면 맥락이 끊긴다.

인증 플로우는 특히 단계가 이어지는 구조라, 앞 단계에서 쓴 단어가 다음 단계에서도 그대로 이어져야 한다. 이게 깨지는 케이스는 주로 두 가지다.

• 화면마다 다른 개발자가 텍스트를 작성했을 때
• 처음엔 통일돼 있었지만 기능 추가나 디자인 변경 과정에서 한쪽만 바뀌었을 때

이번 케이스는 후자였다. 어느 시점에 2FA 화면 쪽 텍스트만 수정되면서 로그인 화면과 달라진 상태로 방치됐다.

수정 자체는 간단하다. 하지만 단순히 텍스트 한 줄 바꾸는 게 아니라, 어느 쪽 표현이 정답인지 먼저 기준을 잡아야 한다. 임의로 한쪽으로 통일하면 다른 화면이나 도움말 문서와 또 어긋날 수 있다.

// 수정 전 - 화면마다 달랐던 레이블
// login.blade.php
<label>인증 코드를 입력하세요</label>

// 2fa.blade.php
<label>확인 번호 6자리를 입력하세요</label>

// 수정 후 - 기준 용어로 통일
// login.blade.php
<label>인증 코드 6자리를 입력하세요</label>

// 2fa.blade.php
<label>인증 코드 6자리를 입력하세요</label>

프로젝트 내에서 "정답 용어"를 어떻게 정하느냐는 팀마다 다르지만, 일반적으로 디자인 시스템이나 카피 가이드라인이 있으면 거기서 가져오고, 없으면 실제 사용자에게 더 익숙한 표현을 선택하면서 어딘가에 기록해두는 게 낫다. 나중에 "왜 이 단어야?" 소모전을 방지하기 위해.

엣지 케이스를 끝까지 따라간 이유

원문에 "엣지 케이스가 처리되지 않아 특정 상황에서 잘못된 결과를 반환"한다는 표현이 있는데, UI 텍스트 수정이지만 이 원칙은 유효하다. 화면 렌더링과 프론트 스크립트 양쪽을 봤을 때, 스크립트 쪽에서 특정 조건 분기에서만 다른 메시지를 보여주는 로직이 있었고, 거기서도 용어가 통일돼 있지 않았다. 단순히 정적 텍스트만 고쳤으면 그 분기에서 나오는 동적 메시지는 여전히 다른 단어를 쓸 뻔했다.

버그 수정할 때 습관적으로 체크하는 건 이렇다.

엣지 케이스를 꼼꼼히 따지는 게 귀찮아 보여도, 나중에 같은 버그로 다시 오는 시간 비용이 훨씬 크다. 그래서 범위를 좁게 보지 않고 연관된 파일까지 다 확인하는 걸 루틴으로 만들어 두었다.

내부 서비스에서 "사소한 것"을 대하는 태도

사내 서비스를 만들다 보면 기능 하나가 화면에 버튼 하나 추가하는 것으로 끝나지 않는다는 걸 계속 체감한다. SQL 집계, 상태 머신, 예외 처리, 화면 렌더링, 권한 체크가 모두 엮여 있어서 어느 하나만 빠뜨려도 숫자가 맞지 않거나 특정 사용자에게 이상한 화면이 나타난다.

관리자 도구는 특히 사용자가 "이 화면이 틀릴 수도 있다"는 가능성을 처음에는 잘 떠올리지 못한다. 서비스를 쓰는 내부 팀이 화면을 신뢰하고 의사결정을 하기 때문에, 잘못된 텍스트나 수치 하나가 운영 실수로 이어질 수 있다. 권한 체크가 엮인 로그인·2FA 화면이면 더욱 그렇다. "대충 맞는 것 같다"로 넘어가면 나중에 반드시 다시 돌아온다.

개발 방식으로는 변경 전 현재 동작을 스크린샷이나 수치로 메모해두고, 수정 후 같은 케이스로 재확인한다. 관련 화면이 있으면 숫자나 상태를 cross-check한다. 커밋 메시지는 "무엇을" 보다 "왜"를 담으려 노력한다. 이번 커밋도 단순히 "텍스트 수정"이 아니라 어떤 용어 기준을 따랐고 어느 분기까지 영향을 봤는지를 메시지에 남겼다.

작은 커밋을 자주 하면 나중에 어느 변경에서 문제가 생겼는지 추적하기 훨씬 쉽다. 논리적으로 독립된 단위로 쪼개는 습관은 지금도 유지 중이고, 이번 뷰/스타일 파일 변경도 한 커밋에 묶되 내용적으로 하나의 목적에 집중하도록 범위를 잡았다.