어드민 패널 인증을 팀 대시보드 구조로 전환

웹 어드민 패널의 인증 방식을 email+key 기반에서 팀 대시보드 중심으로 전환했다. 단순해 보이지만 이 작업 뒤에는 관리 인터페이스의 구조 전환이라는 꽤 큰 의도가 담겨 있었다.

관리 대시보드의 패러다임 전환

처음 웹 어드민 패널은 개별 사용자(email+key) 기반으로 설계됐었다. 초기 개발 단계에서는 단순함이 장점이었다. 하지만 조직이 성장하면서 몇 가지 문제가 드러났다. 개별 계정 관리가 증가하고, 여러 팀원이 동시에 같은 리소스에 접근할 때 권한 충돌이나 감시 추적이 복잡해지는 식이다. 결국 현대적인 어드민 시스템처럼 팀 단위의 대시보드 구조로 넘어가야 한다는 결론에 도달했다.

이 변경은 단순히 로그인 방식을 바꾸는 것이 아니라, 세션 관리 / 권한 모델 / UI 라우팅 전반에 영향을 준다. 그래서 한 번에 여러 파일을 만지게 됐다.

변경 범위와 각 파일의 역할

네 개 파일이 모두 관련된 이유는 로그인→세션→UI 렌더링→데이터 표시 라는 전체 흐름이 한 방향으로 연결되어 있기 때문이다. 한 곳에서 팀 개념을 도입하면 다른 곳에서도 그에 맞게 따라가야 한다.

세션 설계의 전환점

email+key 방식의 문제점을 좀 더 구체적으로 보면:

• 감시 추적성 부족: 누가 언제 어떤 변경을 했는지 추적할 때, 개별 key만으로는 팀 컨텍스트가 없다
• 권한 충돌: 같은 팀 내 여러 인원이 어드민에 접근할 때, 누가 주 관리자인지 부관리자인지 구분이 모호함
• 확장성: 팀 레벨의 정책(MFA 강제, API quota 등)을 적용하려면 구조적으로 막힘

팀 대시보드로 넘어가면서 세션 토큰 구조도 바뀐다. 이제 토큰 페이로드에 팀 ID + 사용자 ID + 역할 정보가 포함된다. 이렇게 하면 권한 검증이 간단해지고, 감시 로그에도 "어느 팀의 누가" 라는 맥락이 자동으로 붙는다.

// 이전: email+key 토큰
{ email: "[email protected]", key: "sk_..." }

// 이후: 팀-기반 토큰
{ teamId: "team_123", userId: "user_456", role: "admin" }

테스트 추가의 신호

team-usage.test.ts 가 변경 목록에 들어간 것도 의미심장하다. 이제 어드민 대시보드는 단순히 "누군가 들어갔다" 가 아니라 각 팀의 사용량 메트릭을 표시해야 한다는 뜻이다. 팀별 API 호출 수, 저장된 데이터 크기, 월간 활성 사용자 수 같은 것들이 대시보드의 핵심 기능이 된다. 테스트를 먼저 작성(또는 함께 작성)함으로써 "이 통계 기능이 정확하게 팀을 기준으로 집계되는가"를 검증한다는 신호다.

운영 관점에서의 이점

이런 전환이 왜 필요했나 하면, 결국 스케일의 문제다. 초기에는 개발자 2-3명이 직접 key를 들고 들어갔다. 하지만 팀이 커지고 고객사가 늘어나면서:

• 새로운 팀원 온보딩할 때마다 key를 새로 발급하고 공유하는 비효율
• 누군가 퇴사했을 때 그 사람의 모든 활동 흔적을 정리하기 어려움
• 팀 단위의 정책을 통일적으로 적용하기 어려움

팀 대시보드 구조라면 이런 문제들이 자연스럽게 풀린다. 팀을 만들고, 팀에 멤버를 추가/제거하고, 팀별 권한을 설정하는 식으로 훨씬 체계적이 된다.

회고: 구조 전환의 타이밍

이런 작업을 할 때 항상 고민하는 부분이 언제 하느냐 다. 너무 늦으면 나중에 더 많은 코드를 뜯어고쳐야 하고, 너무 빠르면 불필요한 복잡성을 미리 안게 된다. 이번 경우엔 팀이 5명을 넘어가고 고객 관리 요청이 들어오면서 자연스럽게 신호가 왔다. 개발자들도 "어? 이건 팀 개념으로 해야 하지 않나?" 라고 생각하기 시작했다는 게 좋은 신호였다.

변경 파일 4개가 모두 서로 영향을 주는 것도 흥미로운 부분이다. 이렇게 여러 계층에 걸쳐 변경이 필요하면, 한 번에 모두 묶어서 머지하는 게 맞다. 부분적으로 배포하다가 세션은 팀 기반인데 UI는 여전히 email+key 용으로 되어 있는 식의 불일치를 만들 수 있기 때문이다.

🛒 이 글과 어울리는 추천 상품

• 모니터암 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.