pharmacy-pos-qr-system/docs/kakao-troubleshooting.md

카카오 OAuth 트러블슈팅 가이드

에러 코드 목록

KOE101 - 앱 관리자 설정 오류 / 플랫폼키 에러

원인: KAKAO_CLIENT_ID(REST API 키)가 비어있거나 잘못된 값

해결:

1. backend/.env 파일이 존재하는지 확인
2. KAKAO_CLIENT_ID 값이 올바른지 확인
3. 카카오 개발자 콘솔 > 앱 > 플랫폼 키 > REST API 키에서 확인

# backend/.env
KAKAO_CLIENT_ID=caad27ac4bc92d8dc83bdd6aae744811

KOE205 - Invalid scope

원인: 요청한 OAuth scope가 앱에서 허용되지 않음

해결:

• name, phone_number scope는 비즈앱 심사 후 동의항목에서 별도 활성화 필요
• 기본 scope만 사용: profile_nickname,profile_image,account_email
• 파일: backend/services/kakao_client.py > get_authorization_url() > scope 파라미터

동의항목 활성화 경로:

카카오 개발자 콘솔 > 카카오 로그인 > 동의항목

scope	비즈앱 필요	현재 상태
profile_nickname	X	사용 중
profile_image	X	사용 중
account_email	X	사용 중
name	O	미사용 (비즈앱 심사 필요)
phone_number	O	미사용 (비즈앱 심사 필요)

KOE320 - authorization code not found

원인: 카카오 authorization code가 만료되었거나 이미 사용됨

해결:

• code는 1회용이며 발급 후 수 분 내 사용해야 함
• 브라우저 새로고침으로 같은 code를 재사용하면 발생
• 사용자에게 다시 카카오 로그인하도록 안내

UnboundLocalError: kakao_client

원인: 콜백 핸들러에서 kakao_client 변수가 초기화되기 전에 접근

상황: 마이페이지 카카오 조회 시, 콜백 함수 상단의 purpose == 'mypage' 분기에서 kakao_client 변수가 아직 할당되지 않은 상태에서 사용

해결: get_kakao_client() 함수를 직접 호출

# 잘못된 코드
if state_data.get('purpose') == 'mypage':
    return _handle_mypage_kakao_callback(code, kakao_client)  # UnboundLocalError

# 올바른 코드
if state_data.get('purpose') == 'mypage':
    return _handle_mypage_kakao_callback(code, get_kakao_client())

ModuleNotFoundError: No module named 'requests'

원인: requests 라이브러리 미설치

해결:

pip install requests

카카오 개발자 콘솔 주의사항

Redirect URI 위치 (2025년 12월 개편)

현재 경로 (2025.12~):

앱 > 플랫폼 키 > REST API 키 클릭 > 리다이렉트 URI

혼동하기 쉬운 위치:

• 카카오 로그인 > 일반 - 여기에는 더 이상 Redirect URI 없음 (Webhook만 있음)
• 카카오 로그인 > 고급 > 로그아웃 리다이렉트 URI - 로그아웃용이므로 혼동 주의

자세한 설정 가이드: kakao-oauth-setup.md

Client Secret 위치

앱 > 플랫폼 키 > REST API 키 클릭 > 클라이언트 시크릿

활성화 상태 확인 필수. 비활성화 시 토큰 교환 실패.

환경변수 체크리스트

# backend/.env (git에 포함되지 않음)
KAKAO_CLIENT_ID=<REST API 키>
KAKAO_CLIENT_SECRET=<클라이언트 시크릿 코드>
KAKAO_REDIRECT_URI=https://mile.0bin.in/claim/kakao/callback

로컬 개발 환경 주의사항

로컬(192.168.0.14:7001)에서 테스트 시:

1. 카카오 버튼 클릭 → 카카오 로그인 화면 (정상)
2. 로그인 후 https://mile.0bin.in/claim/kakao/callback로 리다이렉트됨
3. 로컬이 아닌 운영 서버로 돌아감

로컬에서 완전한 테스트를 하려면:

• KAKAO_REDIRECT_URI를 http://192.168.0.14:7001/claim/kakao/callback로 변경
• 카카오 콘솔에도 해당 URI 등록 필요
• 테스트 후 반드시 원래 값으로 복원

데이터 흐름

카카오 적립 (QR 스캔 → 카카오 로그인)

QR 스캔 → /claim?t=txn:nonce
  → "카카오로 적립하기" 클릭
  → /claim/kakao/start?t=txn:nonce
  → state={t, csrf} 인코딩 → 카카오 OAuth
  → /claim/kakao/callback
  → phone_number 없음 → claim_kakao_phone.html (전화번호 입력)
  → POST /api/claim/kakao (세션의 kakao_data + 폼의 phone)
  → get_or_create_user → link_kakao_identity → claim_mileage
  → 성공 화면

카카오 마이페이지 조회

/my-page → "카카오로 조회하기" 클릭
  → /my-page/kakao/start
  → state={purpose:"mypage", csrf} 인코딩 → 카카오 OAuth
  → /claim/kakao/callback (동일 콜백 URL 재사용)
  → purpose=="mypage" 감지 → _handle_mypage_kakao_callback()
  → find_user_by_kakao_id(kakao_id)
  → 유저 발견 → /my-page?phone=xxx 리다이렉트
  → 유저 없음 → "카카오 계정에 연결된 적립 정보가 없습니다" 에러

customer_identities 테이블 매핑

카카오 적립 시:
  kakao_id="12345678" + phone="01021307390"
  → users 테이블: user_id=7
  → customer_identities: {user_id=7, provider="kakao", provider_id="12345678"}

카카오 조회 시:
  kakao_id="12345678"
  → customer_identities에서 user_id=7 조회
  → users 테이블에서 phone="01021307390" 조회
  → /my-page?phone=01021307390

---

작성일: 2026-02-25 관련 문서: kakao-oauth-setup.md