Add: 뉴스 스킬 이식 트러블슈팅 문서

- company-x_homepage의 뉴스 기능을 RO-BEING 스킬로 이식
- 마이크로서비스 아키텍처 전환 과정 문서화
- 주요 이슈와 해결 방법 정리
- 교훈 섹션 포함

docs/troubleshooting/250726_happybell80_뉴스스킬이식.md

@@ -0,0 +1,176 @@
+# 뉴스 스킬 이식 작업
+
+## 배경
+company-x_homepage의 뉴스 수집 기능을 RO-BEING의 독립적인 마이크로서비스 스킬로 이식
+
+## 작업 시간
+- 시작: 2025년 7월 26일 오후 3시
+- 완료: 2025년 7월 26일 오후 4시 48분
+
+## 주요 작업 내용
+- Google News 검색 기능을 FastAPI 기반 마이크로서비스로 전환
+- ChromaDB를 활용한 벡터 저장소 통합
+- RO-BEING 스킬 아키텍처에 맞는 HTTP API 구현
+
+## 프로젝트 이식 과정에서 발생한 이슈와 해결 방법
+
+### 1. 프로젝트 구조 차이점
+
+**문제**: company-x_homepage는 단순 스크립트 구조였으나, ivada_robeing은 마이크로서비스 아키텍처 필요
+
+**해결**:
+- 독립적인 skill_news 마이크로서비스로 구현
+- FastAPI 기반 RESTful API 구조로 변경
+- Docker 컨테이너화로 독립성 확보
+
+### 2. 데이터 저장소 통합
+
+**문제**: 기존 파일 기반 저장 vs RO-BEING의 ChromaDB/PostgreSQL 구조
+
+**해결**:
+- NewsDataManager를 ChromaDB 기반으로 재작성
+- 벡터 임베딩을 활용한 유사도 검색 기능 추가
+- 메타데이터를 JSON으로 저장하여 호환성 유지
+
+### 3. 비동기 처리 패턴
+
+**문제**: 동기식 스크립트 vs FastAPI의 비동기 패턴
+
+**해결**:
+- 모든 서비스 메서드를 async/await 패턴으로 변경
+- BackgroundTasks를 활용한 비동기 파이프라인 구현
+- asyncio 기반 동시성 처리
+
+### 4. 환경변수 관리
+
+**문제**: 각 프로젝트의 서로 다른 환경변수 체계
+
+**해결**:
+- 공통 환경변수는 유지
+- 프로젝트별 특화 변수는 기본값 제공
+- .env.example 파일로 문서화
+
+### 5. Playwright 브라우저 설정
+
+**문제**: Docker 환경에서 Playwright 실행 시 한글 렌더링 문제
+
+**해결**:
+```dockerfile
+# 한글 폰트 설치
+RUN apt-get update && apt-get install -y \
+    fonts-nanum \
+    fonts-nanum-coding \
+    fonts-nanum-extra
+```
+
+### 6. 모듈 임포트 구조
+
+**문제**: 상대경로 vs 절대경로 임포트 충돌
+
+**해결**:
+- 패키지 구조로 정리 (`app` 디렉토리)
+- `__init__.py` 파일 추가
+- 상대 임포트 사용 (`from ..models import NewsArticle`)
+
+### 7. API 응답 모델
+
+**문제**: 딕셔너리 기반 데이터 vs Pydantic 모델
+
+**해결**:
+- 모든 데이터 구조를 Pydantic 모델로 정의
+- 타입 안정성 확보
+- API 문서 자동 생성
+
+### 8. 중복 검사 로직
+
+**문제**: 파일 기반 중복 검사 vs 데이터베이스 기반
+
+**해결**:
+- ChromaDB의 메타데이터 쿼리 활용
+- URL과 제목 기반 OR 조건 검색
+- 효율적인 인덱싱
+
+### 9. 로깅 시스템
+
+**문제**: print 문 vs 구조화된 로깅
+
+**해결**:
+- Python logging 모듈 사용
+- 로그 레벨별 관리
+- 파일 및 콘솔 동시 출력
+
+### 10. 네트워크 통합
+
+**문제**: 독립 실행 vs RO-BEING 네트워크 통합
+
+**해결**:
+```yaml
+networks:
+  robeing-network:
+    external: true
+```
+
+## 일반적인 문제 해결
+
+### Playwright 오류
+```bash
+# 브라우저 재설치
+docker exec -it robeing-skill-news playwright install chromium
+```
+
+### ChromaDB 초기화
+```bash
+# 데이터 삭제 후 재시작
+rm -rf ./data/chroma
+docker-compose restart skill-news
+```
+
+### 메모리 부족
+```bash
+# Docker 리소스 제한 조정
+docker-compose down
+# docker-compose.yml에 리소스 제한 추가
+```
+
+### API 응답 없음
+```bash
+# 로그 확인
+docker logs robeing-skill-news -f --tail 100
+```
+
+### 의존성 충돌
+```bash
+# 컨테이너 재빌드
+docker-compose build --no-cache skill-news
+```
+
+## 성능 최적화 팁
+
+1. **배치 처리**: 여러 기사를 한 번에 처리
+2. **캐싱**: ChromaDB의 벡터 캐싱 활용
+3. **비동기 처리**: 동시에 여러 URL 스크래핑
+4. **리소스 관리**: Playwright 브라우저 재사용
+
+## 디버깅 명령어
+
+```bash
+# 실시간 로그 모니터링
+docker logs -f robeing-skill-news
+
+# 컨테이너 접속
+docker exec -it robeing-skill-news bash
+
+# API 테스트
+curl http://localhost:8505/health
+
+# Python 디버깅
+docker exec -it robeing-skill-news python -m pdb main.py
+```
+
+## 교훈
+
+1. **마이크로서비스 아키텍처의 중요성**: RO-BEING의 스킬 시스템은 독립성을 강조하므로, 처음부터 HTTP API 기반으로 설계하는 것이 중요
+2. **타입 안정성**: Pydantic 모델을 사용하여 데이터 검증을 철저히 하면 런타임 에러를 크게 줄일 수 있음
+3. **환경변수 문서화**: .env.example 파일을 통해 필요한 환경변수를 명확히 문서화하면 배포 시 실수를 방지할 수 있음
+4. **벡터 DB 활용**: ChromaDB를 통한 의미 기반 검색은 단순 키워드 매칭보다 훨씬 강력한 기능 제공
+5. **비동기 처리**: FastAPI의 BackgroundTasks를 활용하면 긴 작업도 효율적으로 처리 가능