⚙️ [기능추가][Auth][API연동] 백엔드 Auth API 연동 (소셜 로그인·토큰·닉네임·탈퇴)

[EM-H20]

📝 현재 문제점

• 현재 앱의 인증 플로우는 Firebase Auth 클라이언트 SDK 수준에서만 동작하고, 백엔드 서버와 연동되어 있지 않음
• 백엔드 Auth API 스펙(docs/api-specs/01_auth.md)이 확정되었으나 앱에는 아직 연동되지 않아 서버가 발급하는 JWT(Access/Refresh Token) 기반 인증이 불가능
• 신규 가입·기존 로그인 분기, Refresh Token Rotation, 디바이스 세션 관리, 닉네임 관리 등 후속 기능이 모두 블록된 상태
• 회원 탈퇴 시 서버 측 유저 데이터를 정리하는 플로우가 없어 운영·개인정보 요구사항에 대응 불가

🛠️ 해결 방안 / 제안 기능

• Firebase ID Token을 백엔드에 전달하여 서버 JWT를 발급받는 로그인 플로우 연동
• Refresh Token Rotation 기반 토큰 재발급 파이프라인 구축 (만료 시 자동 재발급, 실패 시 로그아웃)
• 디바이스 단위 세션 관리 (deviceId·deviceType·fcmToken 포함) 및 로그아웃 시 서버 세션 정리
• 신규 유저 여부(isNewUser)에 따라 닉네임 설정 화면으로 분기
• 닉네임 중복 확인 / 변경 API 연동 및 유효성(2~10자, 한글·영문·숫자) 처리
• 회원 탈퇴 API 연동 및 로컬 데이터 초기화 플로우 완성
• JWT는 Flutter Secure Storage에 저장, Dio AuthInterceptor로 자동 첨부
• 401(INVALID_REFRESH_TOKEN) 응답 시 강제 로그아웃 → 로그인 화면 이동

⚙️ 작업 내용

API 연동 대상 (총 6개)

• POST /api/auth/login — 소셜 로그인 (신규/기존 자동 분기, 201/200 응답 처리)
• POST /api/auth/logout — 로그아웃 (Refresh Token 서버 삭제 + 로컬 토큰 제거)
• POST /api/auth/reissue — 토큰 재발급 (Access + Refresh 동시 갱신)
• DELETE /api/auth/withdraw — 회원 탈퇴
• GET /api/auth/check-nickname — 닉네임 중복 확인
• PATCH /api/auth/nickname — 닉네임 변경

레이어별 작업

• Data Layer
  • auth_remote_datasource.dart (Retrofit) — 6개 엔드포인트 정의
  • Request/Response DTO (Freezed + JsonSerializable): LoginRequest, LoginResponse, TokenPair, ReissueRequest, NicknameRequest, CheckNicknameResponse 등
  • auth_repository_impl.dart — DTO ↔ Entity 변환, 예외 처리
• Domain Layer
  • user_entity.dart, token_entity.dart — 도메인 모델 정의
  • UseCase: SocialLoginUseCase, LogoutUseCase, ReissueTokenUseCase, WithdrawUseCase, CheckNicknameUseCase, UpdateNicknameUseCase
• Presentation Layer
  • auth_provider.dart — 인증 상태 관리 (initial / loading / authenticated / unauthenticated / error)
  • 신규 유저 분기 처리 → 닉네임 설정 화면 라우팅
• Infrastructure
  • AuthInterceptor — Access Token 자동 첨부 + 401 시 재발급 큐잉
  • DeviceInfoService — deviceId(UUID), deviceType(IOS/ANDROID) 수집 및 Secure Storage 영속
  • FcmTokenService 연동 확인 (로그인 요청 본문에 fcmToken 포함)
• Secure Storage 키 정의
  • accessToken, refreshToken, deviceId, userId, nickname
• 에러 처리
  • INVALID_ID_TOKEN, UNSUPPORTED_PLATFORM, INVALID_REFRESH_TOKEN, INVALID_NICKNAME_FORMAT, NICKNAME_DUPLICATED 별 UX 분기
• 테스트
  • UseCase·Repository 단위 테스트 (Mock DataSource)
  • AuthInterceptor 재발급 플로우 테스트
  • 80% 이상 커버리지

📋 검증 기준

• Google / Apple 소셜 로그인 각각 신규·기존 유저 플로우 정상 동작
• 로그인 성공 후 Secure Storage에 토큰·유저 정보 정상 저장
• Access Token 만료 시 Refresh 자동 재발급 (사용자 재로그인 없이 이어서 동작)
• Refresh Token 만료/무효 시 자동 로그아웃 및 로그인 화면 이동
• 로그아웃 시 서버 세션·로컬 토큰 모두 정리
• 회원 탈퇴 후 재로그인 시 신규 유저로 재가입 처리
• 닉네임 형식·중복 검증이 서버 응답 코드에 맞게 UI에 반영
• flutter analyze 경고 0개, flutter test 전체 통과

💡 추가 요청 사항

• JWT 만료 시간·Refresh 정책은 백엔드와 최종 확인 필요
• 403 / 5xx 등 공통 에러는 docs/api-specs/00_common.md 규칙에 따라 전역 에러 핸들러에서 처리
• 로그인·토큰 관련 이벤트는 민감 정보가 로그에 남지 않도록 LoggingInterceptor에서 마스킹
• iOS 시뮬레이터의 FCM 토큰 미발급 이슈는 기존 가드 로직 유지 (빈 값 or dev placeholder 정책 백엔드와 협의)
• 관련 스펙: docs/api-specs/01_auth.md, docs/api-specs/00_common.md

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: 이름
• 디자인: 이름

[EM-H20]

Guide by SUH-LAB

브랜치

20260423_#71_백엔드_Auth_API_연동_소셜_로그인_토큰_닉네임_탈퇴

커밋 메시지

백엔드 Auth API 연동 (소셜 로그인·토큰·닉네임·탈퇴) : feat : {변경 사항에 대한 설명} https://github.com/SpaceStudyShip/SpaceStudyShip-FE/issues/71