docs: add unresolved rb8001 issues summary (2025-10-19)

troubleshooting/251019_claude_rb8001_미해결_이슈_정리.md

@@ -0,0 +1,95 @@
+# rb8001 미해결 이슈 정리
+
+**날짜**: 2025-10-19  
+**작성자**: Claude (51124)  
+**작성 원칙**: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수  
+**참고**: `CLAUDE.md`의 트러블슈팅 작성 규칙 및 범위
+
+---
+
+## 개요
+
+로그 분석 및 기존 트러블슈팅 문서 검토 결과, 아래 5개 문제는 문서화는 되어 있으나 “최종 해결”이 확인되지 않았거나 운영 코드에 반영되지 않았습니다. 각 항목에 근거(로그/문서)와 제안 조치를 함께 정리합니다.
+
+---
+
+## 1) Gemini 429(쿼터) 초과 대응 미흡
+
+- 증상: 429 You exceeded your current quota, rate limit 에러 다수 발생  
+  - 로그 근거: `rb8001/logs/rb8001.log:46714`, `rb8001/logs/rb8001.log:46949`, `rb8001/logs/rb8001.log:46626`
+- 관련 문서: `DOCS/troubleshooting/251002_emotion_circular_reference_fix.md`(배경 언급), `DOCS/troubleshooting/250915_rate_limiting_미구현.md`(Gateway 기준 해결)
+- 현황: Gateway 레이트 리미팅은 해결로 표기(51123)이나, rb8001의 LLM 호출 레벨에서 백오프/모델 폴백/캐싱 적용에 대한 “코드 반영” 기록 미확인
+- 제안 조치(코드):
+  - `rb8001/app/llm/gemini_handler.py`의 `chat()` 내 429 대응(지수 백오프, 제한 재시도, 폴백 모델 `settings.GEMINI_FALLBACK_MODEL`) 추가  
+  - 응답 캐싱(동일 요청 1분 내 재사용) 고려
+
+---
+
+## 2) gRPC + uvloop BlockingIOError 로그 노이즈
+
+- 증상: `BlockingIOError: [Errno 11] Resource temporarily unavailable` (gRPC PollerCompletionQueue)  
+  - 로그 근거: `rb8001/logs/rb8001.log:43161` (또는 52995/54247 근처)  
+- 관련 문서: `DOCS/troubleshooting/251016_grpc_uvloop_blocking_error.md`  
+- 현황: 문서에서 “로깅 레벨 억제” 권고까지 있으나, uvloop 제거/채널 재사용 등 기능적 완화는 “미구현”으로 표기
+- 제안 조치(코드):
+  - `rb8001/app/core/logger.py`에서 gRPC 로거 CRITICAL 유지 확인, 필요 시 `asyncio` 로거 WARNING  
+  - 고비용 구간에서 uvloop 비활성화 검토(`rb8001/main.py` 초기부) 또는 gRPC 채널 재사용 확인(분류기/LLM 호출부)
+
+---
+
+## 3) `/complete`의 user_id='external_service'로 인한 감정/대화 저장 오류
+
+- 증상: emotion_readings/user 로그 저장 시 invalid UUID 오류 및 conversation 저장 시 NULL 유발  
+  - 로그 근거: `rb8001/logs/rb8001.log:53672`, `rb8001/logs/rb8001.log:53691` 등  
+- 코드 근거: `rb8001/main.py:156` — `/complete` 엔드포인트가 `user_id="external_service"` 고정
+- 관련 문서: `DOCS/troubleshooting/251016_emotion_analysis_test_results.md`(원인 정리), `DOCS/troubleshooting/251016_troubleshooting_summary.md`(system UUID 정책 제안)
+- 현황: 원인/대응 원칙은 문서화되었으나, `/complete`의 사용자 식별 처리 수정 내역 미확인
+- 제안 조치(코드):
+  - `rb8001/main.py:146-174` 내 `/complete`에서  
+    1) 헤더 `X-User-Id`가 있으면 해당 UUID 사용  
+    2) 없으면 시스템 전용 UUID로 대체(문서 제안) 또는 저장 스킵  
+  - DB 저장 경로에서 비-UUID는 확실히 건너뛰기(log INFO)
+
+---
+
+## 4) skill-email 연동 준비 미완료 (토큰/스키마)
+
+- 증상: 8501 연동 500, 토큰/스키마 부재로 이메일 조회 실패  
+  - 로그 근거: `rb8001/logs/rb8001.log:251`, `rb8001/logs/rb8001.log:300` — `relation "gmail_tokens" does not exist`, 500 재시도 후 실패  
+- 관련 문서: `DOCS/troubleshooting/250817_email_skill_integration_status.md`(현황/TODO), `DOCS/troubleshooting/250909_slack_briefing_failure.md`(토큰/브리핑 이슈)
+- 현황: 설계/DB 테이블 초안까지만 있고, 실제 테이블 생성/배포/검증 기록 미확인
+- 제안 조치: 
+  - 51123 DB에 `gmail_token`(또는 합의된 테이블명) 생성 및 skill-email에서 참조  
+  - rb8001 → skill-email 페이로드 스키마 합의/검증 스크립트 추가
+
+---
+
+## 5) 이벤트 루프 오용(“Cannot run the event loop while another loop is running”)
+
+- 증상: rb8001에서 비동기 호출 패턴 오류  
+  - 로그 근거: `rb8001/logs/rb8001.log:45947`, `rb8001/logs/rb8001.log:46104`
+- 관련 문서: `DOCS/troubleshooting/250805-06_happybell80_AI응답개선Phase1-5.md`(rb10508 기준 해결 패턴), rb8001 전용 최종 반영 문서 미확인
+- 현황: 원인/패턴은 정리되었으나 rb8001 내 동기 API 호출을 run_in_executor로 감싸는 등 일관 반영 내역 미확인
+- 제안 조치(코드):
+  - 동기 라이브러리 호출부(예: LLM SDK 동기 메서드, 파일 IO)를 `asyncio.get_running_loop().run_in_executor(...)`로 래핑  
+  - `asyncio.gather()`에는 awaitable만 전달하는지 점검
+
+---
+
+## 교훈
+
+- UUID 원칙 준수: 시스템/외부 호출에도 일관된 사용자 식별 정책 필요
+- 외부 API는 쿼터/레이트리밋/폴백을 “코드 레벨”에서 강제
+- 성능 개선 도구(uvloop) 도입 시 의존성(gRPC) 호환성 사전 검증
+- 스킬 간 계약(API 스키마/테이블)은 명시적 문서+검증 스크립트로 관리
+
+---
+
+## 다음 단계(요약)
+
+1. `/complete` 사용자 식별 수정: `rb8001/main.py:146-174`  
+2. Gemini 429 대응 로직 추가: `rb8001/app/llm/gemini_handler.py`  
+3. skill-email 토큰 테이블 생성/연동 검증(51123)  
+4. run_in_executor 적용 범위 점검과 수정  
+5. gRPC+uvloop 충돌 완화(필요 시 uvloop 비활성화 범위 축소/조정)
+