[FEATURE] Clerk 토큰 기반 보호 API 요청 구조 공통화

[kbh0218]

📝 기능 설명

이미 구현된 Clerk 기반 구글 로그인 흐름을 바탕으로, 백엔드 보호 API를 호출할 때 사용할 공통 요청 구조를 정리합니다.

현재 프론트엔드에는 Clerk OAuth 로그인과 로그인 후 /api/v1/auth/me를 호출하는 회원 동기화 흐름이 구현되어 있습니다.
다만 /auth/me는 새로 구현해야 할 로그인 API가 아니라, 백엔드에서 Clerk JWT를 검증하고 해당 Clerk 사용자를 내부 member와 매핑했는지 확인하는 기존 동기화/확인용 API입니다.

백엔드에서는 인증이 필요한 API 요청이 들어오면 Spring Security의 Clerk JWT 인증 흐름을 통해 clerk_id 기준 member를 조회하거나 생성합니다.
따라서 이후 analyses, saved-links 등 보호 API를 연동할 때 핵심은 /auth/me를 새로 연동하는 것이 아니라, Clerk getToken()으로 받은 토큰을 모든 보호 API 요청에 일관되게 포함하는 구조를 만드는 것입니다.

이번 작업에서는 기존 로그인/회원 동기화 흐름은 유지하되, API base URL, Clerk 토큰 주입, { data: ... } 응답 래퍼 처리, 에러 처리 방식을 공통화하여 이후 분석 요청과 저장 링크 API 연동의 기반을 마련합니다.

📋 구현할 Task

• 현재 Clerk 기반 구글 로그인 및 세션 유지 흐름을 확인했는가?
• 기존 /api/v1/auth/me 호출 위치와 역할을 확인했는가?
• /auth/me를 새로 연동하는 작업이 아니라, 기존 member 확인/동기화 흐름으로 유지할지 검토했는가?
• /auth/me 사전 호출에 의존하지 않아도 보호 API 요청에 Clerk 토큰이 일관되게 포함되는 구조인지 확인했는가?
• 기존 services/auth-api.ts의 역할과 유지해야 할 동작을 확인했는가?
• 기존 api/terms.ts의 base URL, 응답 파싱, 에러 처리 방식을 확인했는가?
• API base URL 설정을 공통으로 사용할 수 있도록 정리했는가?
• Clerk getToken()으로 받은 토큰을 보호 API 요청 헤더에 재사용 가능하게 주입했는가?
• 인증이 필요한 API와 인증이 필요 없는 API 호출 방식을 구분했는가?
• 백엔드의 { data: ... } 응답 래퍼를 공통으로 처리할 수 있는 타입 또는 유틸을 정리했는가?
• 공통 API 요청에서 성공 응답과 에러 응답을 일관되게 처리하도록 구성했는가?
• 약관 API처럼 인증이 필요 없는 API가 공통 구조와 충돌 없이 동작하는지 확인했는가?
• 이후 분석 요청, polling, 저장 링크 API 연동에서 재사용 가능한 구조인지 확인했는가?

📎 추가 내용

• 이미 구현된 흐름

  • Clerk 기반 Google OAuth 로그인
  • 로그인 후 /api/v1/auth/me 호출
  • 탭 진입 시 세션 기준 회원 동기화 확인

• /api/v1/auth/me의 현재 역할

  • 새로 구현해야 할 로그인 API가 아님
  • Clerk JWT가 백엔드에서 유효하게 검증되는지 확인
  • 백엔드 내부 member 확인/동기화 흐름을 확인
  • 필요한 경우 publicId를 확인하는 용도

• 관련 파일

  • services/auth-api.ts
  • api/terms.ts
  • app/(auth)/login.tsx
  • app/(tabs)/_layout.tsx

• 백엔드 인증 방식

  • Clerk JWT
  • Header: Authorization: Bearer {token}
  • 인증이 필요한 API 요청 시 백엔드에서 Clerk JWT를 검증하고 내부 member를 조회/생성

• 백엔드 응답 형태

  • 성공 응답: { data: ... }
  • 프론트에서는 body.data 기준으로 파싱 필요

• 작업 목적

  • 이미 구현된 Clerk 인증 흐름을 유지하면서 보호 API 통신 구조를 공통화
  • /auth/me를 새 로그인 API처럼 다루지 않고, 기존 member 확인/동기화 흐름으로 유지할지 검토
  • 이후 분석 요청, 저장 링크, 북마크/삭제 API 연동의 기반 마련