docs: Gmail refresh_token 컬럼/JSONB 불일치 문제 트러블슈팅 문서 추가

troubleshooting/250109_happybell80_gmail_refresh_token_불일치.md

@@ -0,0 +1,49 @@
+# Gmail refresh_token 컬럼/JSONB 불일치 문제
+
+**작성일**: 2025-01-09  
+**작성자**: happybell80  
+**영향 서비스**: skill-email, auth-server  
+
+## 문제 상황
+Gmail 토큰 테이블에서 refresh_token이 두 곳에 저장:
+- `refresh_token` 컬럼 (오래된 무효 토큰)
+- `token_data` JSONB (실제 유효 토큰)
+
+## 발견 과정
+```python
+# refresh_token 컬럼 토큰 테스트
+토큰: 1//0g53CfEfA9Pw6...
+결과: 400 invalid_grant (만료/무효)
+
+# token_data JSONB 토큰 테스트  
+토큰: 1//0glv3xMaPHgvW...
+결과: 200 OK (정상 작동)
+```
+
+## 코드 분석
+### skill-email/services/db_credentials_provider.py
+- 63번줄: `refresh_token,` (컬럼 직접 조회)
+- 166번줄: `refresh_token = %s,` (컬럼 업데이트)
+- 문제: 오래된 컬럼 사용으로 토큰 갱신 실패 가능
+
+### auth-server/app/api/gmail_refresh.py  
+- 74번줄: `token_data.get('refresh_token')` (JSONB 사용)
+- 정상: 이미 JSONB만 사용 중
+
+## 해결 방안
+```sql
+-- 1. skill-email 코드 수정 (4줄)
+-- 63번: refresh_token → token_data->>'refresh_token' as refresh_token
+-- 166번: refresh_token = %s, 삭제
+-- 173번: creds.refresh_token, 삭제
+
+-- 2. DB 데이터 동기화 (선택)
+UPDATE gmail_tokens
+SET refresh_token = token_data->>'refresh_token'
+WHERE slack_user_id = 'U0925SXQFDK';
+```
+
+## 교훈
+- 레거시 컬럼과 JSONB 병행 사용 시 동기화 필수
+- 코드 마이그레이션 시 모든 서비스 일괄 수정
+- 토큰 갱신 실패 시 저장 위치 불일치 확인