Kakao OAuth 로그인/회원가입 요구사항 (웹)

1. 목적 및 범위

목적: 백엔드(apps/dha-sleep-api)의 Kakao OAuth 인증 엔드포인트를 검증하고, 내부 운영·QA 사용자가 SleepZ 웹에서 Kakao 계정으로 로그인/회원가입을 수행할 수 있도록 한다.
범위: Next.js 15 + React + Tailwind + shadcn/ui 기반의 App Router 프로젝트. 로그인 페이지 UI, Kakao OAuth 리다이렉션 흐름, 백엔드 토큰 교환, 신규 사용자 프로필 초기화까지 포함한다.
비범위: 다중 계정, 소셜 계정 연결 해제, 모바일 앱 로그인, 사용자 역할 할당 이후 화면. 해당 기능은 추후 문서화한다.

시나리오	설명	주요 이해관계자
S1. 기존 사용자의 Kakao 로그인	이미 SleepZ 계정이 있는 사용자가 Kakao 계정으로 로그인	운영/QA
S2. 신규 사용자의 Kakao 회원가입	SleepZ에 처음 접속한 사용자가 Kakao 계정으로 회원가입 후 기본 프로필을 완성	운영/QA, 온보딩 담당자
S3. 인증 실패 대응	Kakao 인증 오류 또는 토큰 교환 실패 시 사용자에게 안내	운영/QA

구성 요소
- 서비스 로고 및 간단한 소개 텍스트
- 지금 Kakao로 시작하기 버튼 (shadcn/ui 버튼 컴포넌트 변형)
- 로그인 관련 공지/지원 링크 영역
상호작용
- 버튼 클릭 시 Kakao OAuth 권한 요청 URL로 리다이렉트 (302)
- 로딩 상태에서 스피너 또는 처리 중... 텍스트 노출
접근성
- 버튼은 키보드 포커스 가능, aria-label="카카오 계정으로 로그인" 지정
- Tailwind/색상 대비는 WCAG 2.1 AA 기준 유지

Route 구조: App Router app/auth/kakao/callback/route.ts
처리 단계
1. code 및 state 쿼리 파라미터 유효성 검증
2. 백엔드 API(/auth/oauth/kakao/exchange)로 POST 요청 (code, redirectUri 전달)
3. 응답 내 accessToken, refreshToken, requiresProfileSetup 확인
4. 상태에 따라 리다이렉션 및 쿠키 설정
  - requiresProfileSetup = false → JWT 쿠키 설정 후 /dashboard
  - requiresProfileSetup = true → appToken 쿠키(sleepz_app_token) 유지 상태로 /onboarding/profile
5. 교환 실패 시 /login으로 리다이렉트하며 실패 배너 노출
UI
- 처리 중 화면: shadcn Skeleton 또는 Spinner + 카카오 인증을 확인하는 중입니다. 문구
- 오류 화면(딥 링크): retry 버튼 제공 (/login 이동)

신규 가입자의 최소 프로필 수집
- 필드: 이름(필수), 소속 조직/팀(선택), 연락 이메일(선택)
- 신규 사용자: POST /auth/oauth/kakao/provisioning/complete 호출(Authorization: Bearer appToken) → 성공 시 /login?reason=session-required&provisioning=submitted
- 기존 사용자: PUT /users/profile 호출 → 성공 시 /dashboard

단계	메서드/엔드포인트	요청 바디	성공 응답	오류 처리
Kakao 코드 교환	`POST /auth/oauth/kakao/exchange`	`{ code, redirectUri }` + `Authorization: Bearer {appToken}`	`{ accessToken?, refreshToken?, requiresProfileSetup, user }`	4xx: 오류 코드에 따른 메시지 매핑
온보딩 제출	`POST /auth/oauth/kakao/provisioning/complete`	`{ name, organization?, email? }` + `Authorization: Bearer {appToken}`	`{ status, message, next }`	400: 세션 만료/재사용
(기존) 프로필 업데이트	`PUT /users/profile`	`{ name, organization?, email? }`	`{ userId }`	400: 필드 검증 오류, 401: 토큰 만료

토큰 저장: Next.js 서버 액션 또는 Route Handler에서 HttpOnly 쿠키 설정 (sleepz_access_token, sleepz_refresh_token, sleepz_app_token)
인증 헤더: Kakao 교환/온보딩 시 Authorization: Bearer {appToken}, 보호 API 호출 시 Authorization: Bearer {accessToken}
토큰 만료 대응: 401 수신 시 /login으로 리다이렉트 + 토스트 알림

NEXT_PUBLIC_KAKAO_CLIENT_ID
NEXT_PUBLIC_KAKAO_REDIRECT_URI (배포 환경 별도 설정)
KAKAO_CLIENT_SECRET (백엔드 전용, FE에서 접근 금지)
DHA_SLEEP_WEB_APP_TOKEN_COOKIE (선택): App Token 쿠키명 (기본값: sleepz_app_token)
.env.development 예시는 별도 dev-env.md 문서에 기록

성공 흐름: Kakao → 콜백 → 토큰 교환 → (기존: 세션 쿠키 저장) / (신규: appToken 유지) → 온보딩 제출 → /login 재진입
Kakao 인증 거부: error=access_denied 수신 시 /login?error=kakao_denied로 리다이렉트, 배너 문구 "카카오 인증이 취소되었습니다."
백엔드 오류 코드 대응 (예시)
- KAKAO_TOKEN_EXCHANGE_FAILED: "카카오 인증 서버와 통신 중 문제가 발생했습니다. 잠시 후 다시 시도해주세요."
- USER_ACCOUNT_LOCKED: "해당 계정은 잠겨 있습니다. 관리자에게 문의하세요."
- KAKAO_PROVISIONING_SESSION_INVALID: "온보딩 세션이 만료되었습니다. 다시 카카오 로그인을 진행해주세요."
네트워크 타임아웃: 10초 이상 응답 없을 경우 /login으로 복귀 + 재시도 버튼 노출

카카오 테스트 계정으로 로그인 성공 (기존 사용자)
신규 사용자 흐름에서 appToken 쿠키 유지 및 /onboarding/profile 이동 확인
온보딩 폼 제출 시 202 응답과 /login?reason=session-required&provisioning=submitted 리다이렉트 확인
의도적으로 state 불일치 발생 시 예외 처리 검증
브라우저 새로고침/뒤로가기 시 JWT/appToken 쿠키가 기대한 경로에만 영향 주는지 확인
반복 클릭 및 네트워크 지연 상태에서 로딩 UI가 중복 노출되지 않는지 확인