[refactor] API 오류 정규화 및 인증 오류 처리 개선

[bom0320]

개요 💡

기존 AdminLayout에서는 useGetMyInfo 요청이 실패하면 오류 원인을 구분하지 않고 모든 경우를 로그인 만료로 처리하고 있었습니다.

이로 인해 서버 오류, 네트워크 오류, Zod 응답 검증 오류처럼 인증과 관계없는 문제에서도 Query Cache와 인증 토큰이 삭제되고 로그인 페이지로 이동할 수 있었습니다.

이에 Axios 오류와 Zod 검증 오류를 공통 AppError로 정규화하고, 실제 인증 오류에서만 세션을 정리하도록 오류 처리 구조를 개선했습니다.

작업내용 ⌨️

• 애플리케이션 공통 오류 타입 AppError 정의
• 인증·권한·잘못된 요청·리소스 없음·충돌·서버·네트워크·응답 검증·알 수 없는 오류로 분류
• Axios 오류와 Zod 검증 오류를 normalizeApiError를 통해 공통 오류 형태로 변환
• 서버 오류 응답의 message를 유지하고, 메시지가 없는 경우 기본 안내 문구를 사용하도록 처리
• 주요 조회 API의 요청·검증·Mapper 과정에서 발생한 오류를 AppError로 정규화
  • 내 정보 조회
  • 사용자 목록 조회
  • 기기 목록 조회
  • 예약 목록 조회
  • 예약 히스토리 조회
  • 대시보드 조회
  • 고장 신고 목록 조회
• 주요 Mutation API를 API 함수와 Mutation Hook으로 분리하고 오류 처리 기준 통일
  • 기기 삭제
  • 기기 상태 변경
  • 예약 삭제
  • 사용자 패널티 해제
  • 신고 상태 변경
• 예약 히스토리 API 응답에 Zod 런타임 검증 추가
• AdminLayout에서 AUTHENTICATION 오류인 경우에만 Query Cache와 인증 토큰 삭제
• 서버·네트워크·응답 검증 오류에서는 사용자 세션을 유지하고 오류 화면과 재시도 버튼 제공
• 일반 사용자의 관리자 페이지 접근 시 인증 토큰을 삭제하지 않고 앱 다운로드 페이지로 이동
• Query Cache 및 인증 쿠키 삭제 로직을 clearAuthSession으로 공통화
• Header 로그아웃 흐름에도 공통 세션 정리 로직 적용
• 기존 TanStack Query 전역 재시도 정책인 retry: false를 확인하고 유지

개선 결과 ⚙️

• 인증과 관계없는 오류로 인한 불필요한 강제 로그아웃 방지
• 실제 인증 만료인 경우에만 Query Cache와 인증 토큰 정리
• 서버·네트워크·API 계약 오류 발생 시 사용자 세션 유지
• AxiosError와 ZodError를 UI에서 직접 판단하지 않고 공통 오류 타입으로 처리
• 오류 원인에 따라 사용자 안내, 재시도, 라우팅 흐름을 분리
• API 요청 함수와 Query/Mutation Hook의 책임 분리
• 원본 오류를 cause에 유지해 HTTP 상태 코드와 Zod 검증 실패 경로 추적 가능

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
washer	Ready	Preview, Comment	Jul 23, 2026 3:07am

[LeeSangHyeok0731]

수고하셨습니다.