feat: 카카오 로그인 마이페이지 조회 + scope/env 수정 + 트러블슈팅 문서
- 마이페이지에 카카오 로그인 조회 기능 추가 (/my-page/kakao/start) - 콜백 핸들러에 purpose=mypage 분기 추가 (동일 콜백 URL 재사용) - my_page_login.html에 "카카오로 조회하기" 버튼 추가 - my_page.html 헤더에 카카오 조회 버튼 추가 - OAuth scope에서 name, phone_number 제거 (비즈앱 심사 미완료) - KOE101/KOE205/KOE320 등 에러별 트러블슈팅 문서 작성 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
thug0bin
168
docs/kakao-troubleshooting.md
Normal file
168
docs/kakao-troubleshooting.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# 카카오 OAuth 트러블슈팅 가이드
|
||||
|
||||
## 에러 코드 목록
|
||||
|
||||
### KOE101 - 앱 관리자 설정 오류 / 플랫폼키 에러
|
||||
|
||||
**원인**: `KAKAO_CLIENT_ID`(REST API 키)가 비어있거나 잘못된 값
|
||||
|
||||
**해결**:
|
||||
1. `backend/.env` 파일이 존재하는지 확인
|
||||
2. `KAKAO_CLIENT_ID` 값이 올바른지 확인
|
||||
3. 카카오 개발자 콘솔 > 앱 > 플랫폼 키 > REST API 키에서 확인
|
||||
|
||||
```bash
|
||||
# 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()` 함수를 직접 호출
|
||||
```python
|
||||
# 잘못된 코드
|
||||
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` 라이브러리 미설치
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
pip install requests
|
||||
```
|
||||
|
||||
## 카카오 개발자 콘솔 주의사항
|
||||
|
||||
### Redirect URI 위치 (2025년 12월 개편)
|
||||
|
||||
**현재 경로** (2025.12~):
|
||||
```
|
||||
앱 > 플랫폼 키 > REST API 키 클릭 > 리다이렉트 URI
|
||||
```
|
||||
|
||||
**혼동하기 쉬운 위치**:
|
||||
- `카카오 로그인 > 일반` - 여기에는 더 이상 Redirect URI 없음 (Webhook만 있음)
|
||||
- `카카오 로그인 > 고급 > 로그아웃 리다이렉트 URI` - 로그아웃용이므로 혼동 주의
|
||||
|
||||
자세한 설정 가이드: [kakao-oauth-setup.md](./kakao-oauth-setup.md)
|
||||
|
||||
### Client Secret 위치
|
||||
|
||||
```
|
||||
앱 > 플랫폼 키 > REST API 키 클릭 > 클라이언트 시크릿
|
||||
```
|
||||
|
||||
활성화 상태 확인 필수. 비활성화 시 토큰 교환 실패.
|
||||
|
||||
## 환경변수 체크리스트
|
||||
|
||||
```bash
|
||||
# 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](./kakao-oauth-setup.md)
|
||||
Reference in New Issue
Block a user