docs: Gmail 아이템 시스템 통합 트러블슈팅 문서 추가

- robeing-monitor metadata 파싱 버그 해결
- UUID to string 변환 버그 수정
- 전체 시스템 통합 테스트 결과
- 데이터 타입 방어적 처리 교훈

troubleshooting/250820_happybell80_Gmail아이템시스템통합.md

@@ -0,0 +1,133 @@
+# Gmail 아이템 시스템 통합 및 robeing-monitor 버그 수정
+
+## 작성일: 2025-08-20
+## 작성자: happybell80  
+## 관련 서비스: robeing-monitor, rb10508_micro, skill-email
+
+---
+
+## 오전 12시 30분
+
+### robeing-monitor metadata 파싱 버그
+
+#### 문제 상황
+- robeing-monitor의 `/api/items/gmail` 엔드포인트에서 metadata 필드 처리 오류
+- PostgreSQL에서 조회한 metadata가 string 타입인데 dict로 가정하고 `.get()` 호출
+- `AttributeError: 'str' object has no attribute 'get'` 에러 발생
+
+#### 원인 분석
+- gmail_tokens 테이블의 metadata 컬럼이 JSONB 타입이지만, asyncpg가 string으로 반환하는 경우 발생
+- 또는 데이터 저장 시 JSON string으로 저장된 경우
+
+#### 해결 과정
+```python
+# app/api/items.py 90번째 줄 근처
+# metadata가 string인 경우 JSON 파싱
+if isinstance(metadata, str):
+    try:
+        metadata = json.loads(metadata)
+    except json.JSONDecodeError:
+        metadata = {}
+```
+
+#### 결과
+- metadata 타입에 관계없이 안전하게 처리
+- email 필드 정상 추출
+
+---
+
+## 오전 12시 45분
+
+### robeing-monitor UUID to string 변환 버그
+
+#### 문제 상황  
+- ItemResponse 생성 시 user_id가 UUID 타입 그대로 전달
+- Pydantic 모델이 string을 기대하는데 UUID 객체가 전달되어 직렬화 문제 발생
+
+#### 해결 과정
+```python
+# app/api/items.py 99번째 줄
+item = ItemResponse(
+    id=row['id'],
+    user_id=str(row['user_id']),  # UUID → string 변환
+    robeing_id=row['robeing_id'],
+    # ...
+)
+```
+
+#### 결과
+- UUID 타입 안전하게 string으로 변환
+- API 응답 정상 반환
+
+---
+
+## 오전 12시 50분
+
+### 전체 Gmail 아이템 시스템 통합 테스트
+
+#### 테스트 시나리오
+1. Gmail OAuth 인증 → 토큰 DB 저장
+2. robeing-monitor로 아이템 조회
+3. rb10508_micro에서 이메일 발송 요청
+4. skill-email로 요청 전달
+5. 대화형 응답 처리
+
+#### 테스트 결과
+✅ **성공한 부분:**
+- Gmail OAuth 토큰 정상 저장 (user_id UUID로 정규화)
+- robeing-monitor API 정상 작동
+  - metadata 파싱 성공
+  - capabilities 정확히 계산 (send, read, modify)
+  - is_equipped 상태 정확
+- rb10508_micro ↔ skill-email 연동
+  - channel_id 정상 전달
+  - Gemini API로 이메일 정보 추출
+  - 대화형 처리 (누락된 필드 요청)
+
+⚠️ **개선 필요 사항:**
+- skill-email이 여전히 파일 기반 토큰 사용 중
+- "종태님" 같은 한국어 이름 → 이메일 매핑 미구현
+- 대화형 응답 메시지 다양화 필요
+
+---
+
+## 교훈
+
+### 1. 데이터 타입 방어적 처리
+- DB에서 받은 데이터 타입을 항상 체크
+- JSONB 컬럼도 string으로 올 수 있음을 가정
+- isinstance() 체크와 try-except로 안전하게 처리
+
+### 2. UUID 처리 주의사항  
+- PostgreSQL UUID 타입은 Python UUID 객체로 반환
+- API 응답이나 JSON 직렬화 시 str() 변환 필수
+- Pydantic 모델에서 자동 변환되지 않음
+
+### 3. 단계적 통합 테스트
+- 각 서비스 개별 테스트 후 통합 테스트
+- 로그를 통한 데이터 흐름 추적
+- 문제 발생 지점 정확히 파악
+
+### 4. 환경변수 우선순위
+- .env 파일에 설정해도 코드에서 사용하지 않으면 무의미
+- TOKEN_PROVIDER=database 설정했지만 코드는 FileCredentialsProvider 사용
+- 환경변수와 코드 로직 일치 확인 필수
+
+---
+
+## 관련 커밋
+- robeing-monitor: `8eec70b` - metadata string 파싱 버그 수정
+- robeing-monitor: `e89d802` - UUID to string 변환 버그 수정  
+- skill-email: `75efb4f` - Gemini API 통합 (8003 서비스 대체)
+- rb10508_micro: `18f06c7` - channel_id 속성 추가
+
+---
+
+## 다음 단계
+1. skill-email DBCredentialsProvider 구현
+2. Gmail 아이템 장착/해제 UI 개선
+3. 대화형 이메일 작성 고도화
+
+---
+
+**문서 끝**