# News Engine Console 뉴스 파이프라인 관리 및 모니터링 통합 콘솔 시스템 ## 프로젝트 개요 News Engine Console은 뉴스 파이프라인의 전체 lifecycle을 관리하고 모니터링하는 통합 관리 시스템입니다. ### 핵심 기능 1. **키워드 관리** ✅ - 파이프라인 키워드 CRUD, 활성화/비활성화, 통계 2. **파이프라인 모니터링** ✅ - 파이프라인별 처리 수량, 활용도 통계, 로그 조회 3. **파이프라인 제어** ✅ - 시작/중지/재시작, 설정 관리 4. **사용자 관리** ✅ - User CRUD, 역할 기반 권한 (Admin/Editor/Viewer) 5. **애플리케이션 관리** ✅ - OAuth2/JWT 기반 Application CRUD 6. **시스템 모니터링** ✅ - 서비스 헬스체크, 메트릭, 로그 수집, 데이터베이스 통계 ## 현재 상태 ### ✅ Phase 1 완료! (2025-01-04) - **Backend API**: 37개 엔드포인트 모두 구현 완료 - **테스트**: 100% 통과 (8/8 테스트 스위트) - **문서화**: 완전한 API 문서 (2,058 lines) - **서버**: localhost:8101 실행 중 ## 기술 스택 ### Backend ✅ - **Framework**: FastAPI (Python 3.11) - **Database**: MongoDB with Motor (async driver) - **Cache**: Redis (planned) - **Authentication**: JWT + OAuth2 Password Flow - **Validation**: Pydantic v2 - **Server**: Uvicorn (ASGI) ### Frontend ⏳ (예정) - React 18 + TypeScript - Material-UI v7 - React Query - Recharts (통계 차트) ### Infrastructure - Docker - Kubernetes - MongoDB (news_engine_console_db) - Redis ## 프로젝트 구조 ``` services/news-engine-console/ ├── README.md # 이 파일 ├── TODO.md # 상세 구현 계획 ├── PROGRESS.md # 진행 상황 추적 ├── API_DOCUMENTATION.md # ✅ 완전한 API 문서 (2,058 lines) ├── backend/ # ✅ Backend 완성 │ ├── Dockerfile # ✅ Docker 설정 │ ├── requirements.txt # ✅ Python 의존성 │ ├── main.py # ✅ FastAPI 앱 엔트리 │ ├── .env # 환경 변수 │ ├── test_api.py # ✅ 종합 테스트 (700+ lines) │ ├── test_motor.py # ✅ MongoDB 연결 테스트 │ ├── fix_objectid.py # ✅ ObjectId 변환 헬퍼 │ └── app/ │ ├── api/ # ✅ API 라우터 (5개) │ │ ├── keywords.py # ✅ 8 endpoints │ │ ├── pipelines.py # ✅ 11 endpoints │ │ ├── users.py # ✅ 11 endpoints │ │ ├── applications.py # ✅ 7 endpoints │ │ └── monitoring.py # ✅ 8 endpoints │ ├── core/ # ✅ 핵심 설정 │ │ ├── config.py # ✅ Pydantic Settings │ │ ├── database.py # ✅ MongoDB (Motor) │ │ ├── auth.py # ✅ JWT 인증 │ │ └── security.py # ✅ Password hashing │ ├── models/ # ✅ Pydantic v2 모델 (4개) │ │ ├── user.py # ✅ │ │ ├── keyword.py # ✅ │ │ ├── pipeline.py # ✅ │ │ └── application.py # ✅ │ ├── schemas/ # ✅ Request/Response 스키마 (4개) │ │ ├── user.py # ✅ │ │ ├── keyword.py # ✅ │ │ ├── pipeline.py # ✅ │ │ └── application.py # ✅ │ └── services/ # ✅ 비즈니스 로직 (5개) │ ├── user_service.py # ✅ 312 lines │ ├── keyword_service.py # ✅ 240+ lines │ ├── pipeline_service.py # ✅ 330+ lines │ ├── application_service.py # ✅ 254 lines │ └── monitoring_service.py # ✅ 309 lines ├── frontend/ # ⏳ TODO (Phase 2) │ └── src/ │ ├── api/ │ ├── components/ │ ├── pages/ │ └── types/ └── k8s/ # ⏳ TODO (Phase 2) ├── namespace.yaml ├── backend-deployment.yaml ├── frontend-deployment.yaml └── service.yaml ``` ## API 엔드포인트 (37개) ### 🔐 Authentication - `POST /api/v1/users/login` - OAuth2 Password Flow 로그인 ### 👤 Users API (11 endpoints) - `GET /api/v1/users/me` - 현재 사용자 정보 - `GET /api/v1/users/` - 사용자 목록 (admin) - `GET /api/v1/users/stats` - 사용자 통계 (admin) - `GET /api/v1/users/{user_id}` - 특정 사용자 조회 - `POST /api/v1/users/` - 사용자 생성 (admin) - `PUT /api/v1/users/{user_id}` - 사용자 수정 - `DELETE /api/v1/users/{user_id}` - 사용자 삭제 (admin) - `POST /api/v1/users/{user_id}/toggle` - 활성화/비활성화 (admin) - `POST /api/v1/users/change-password` - 비밀번호 변경 ### 🏷️ Keywords API (8 endpoints) - `GET /api/v1/keywords/` - 키워드 목록 (필터, 정렬, 페이지네이션) - `GET /api/v1/keywords/{keyword_id}` - 키워드 상세 - `POST /api/v1/keywords/` - 키워드 생성 - `PUT /api/v1/keywords/{keyword_id}` - 키워드 수정 - `DELETE /api/v1/keywords/{keyword_id}` - 키워드 삭제 - `POST /api/v1/keywords/{keyword_id}/toggle` - 상태 토글 - `GET /api/v1/keywords/{keyword_id}/stats` - 키워드 통계 ### 🔄 Pipelines API (11 endpoints) - `GET /api/v1/pipelines/` - 파이프라인 목록 - `GET /api/v1/pipelines/{pipeline_id}` - 파이프라인 상세 - `POST /api/v1/pipelines/` - 파이프라인 생성 - `PUT /api/v1/pipelines/{pipeline_id}` - 파이프라인 수정 - `DELETE /api/v1/pipelines/{pipeline_id}` - 파이프라인 삭제 - `GET /api/v1/pipelines/{pipeline_id}/stats` - 통계 조회 - `POST /api/v1/pipelines/{pipeline_id}/start` - 시작 - `POST /api/v1/pipelines/{pipeline_id}/stop` - 중지 - `POST /api/v1/pipelines/{pipeline_id}/restart` - 재시작 - `GET /api/v1/pipelines/{pipeline_id}/logs` - 로그 조회 - `PUT /api/v1/pipelines/{pipeline_id}/config` - 설정 수정 ### 📱 Applications API (7 endpoints) - `GET /api/v1/applications/` - 애플리케이션 목록 - `GET /api/v1/applications/stats` - 애플리케이션 통계 (admin) - `GET /api/v1/applications/{app_id}` - 애플리케이션 상세 - `POST /api/v1/applications/` - 애플리케이션 생성 - `PUT /api/v1/applications/{app_id}` - 애플리케이션 수정 - `DELETE /api/v1/applications/{app_id}` - 애플리케이션 삭제 - `POST /api/v1/applications/{app_id}/regenerate-secret` - Secret 재생성 ### 📊 Monitoring API (8 endpoints) - `GET /api/v1/monitoring/health` - 시스템 상태 - `GET /api/v1/monitoring/metrics` - 시스템 메트릭 - `GET /api/v1/monitoring/logs` - 활동 로그 - `GET /api/v1/monitoring/database/stats` - DB 통계 (admin) - `GET /api/v1/monitoring/database/collections` - 컬렉션 통계 (admin) - `GET /api/v1/monitoring/pipelines/performance` - 파이프라인 성능 - `GET /api/v1/monitoring/errors/summary` - 에러 요약 ## 로컬 개발 환경 설정 ### Prerequisites - Python 3.11+ - MongoDB (localhost:27017) - Redis (localhost:6379) - 선택사항 ### Backend 실행 ```bash cd services/news-engine-console/backend # 환경 변수 설정 및 서버 실행 MONGODB_URL=mongodb://localhost:27017 \ DB_NAME=news_engine_console_db \ python3 -m uvicorn main:app --host 0.0.0.0 --port 8101 --reload ``` **접속**: - API: http://localhost:8101/ - Swagger UI: http://localhost:8101/docs - ReDoc: http://localhost:8101/redoc ### 테스트 실행 ```bash cd services/news-engine-console/backend # 전체 테스트 (37개 엔드포인트) python3 test_api.py # MongoDB 연결 테스트 python3 test_motor.py ``` **테스트 결과**: ``` Total Tests: 8 ✅ Passed: 8/8 (100%) Success Rate: 100.0% ``` ## 환경 변수 ```env # MongoDB MONGODB_URL=mongodb://localhost:27017 DB_NAME=news_engine_console_db # Redis (선택사항) REDIS_URL=redis://localhost:6379 # JWT SECRET_KEY=dev-secret-key-change-in-production-please-use-strong-key ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=30 # Service SERVICE_NAME=news-engine-console API_V1_STR=/api/v1 PORT=8101 # CORS ALLOWED_ORIGINS=["http://localhost:3000","http://localhost:3100"] ``` ## 데이터베이스 ### MongoDB 컬렉션 **users** - 사용자 정보 ```json { "_id": "ObjectId", "username": "string (unique)", "email": "string (unique)", "hashed_password": "string", "full_name": "string", "role": "admin|editor|viewer", "disabled": false, "created_at": "datetime", "last_login": "datetime" } ``` **keywords** - 파이프라인 키워드 ```json { "_id": "ObjectId", "keyword": "string", "category": "people|topics|companies", "status": "active|inactive", "pipeline_type": "rss|translation|all", "priority": 1-10, "metadata": {}, "created_at": "datetime", "updated_at": "datetime", "created_by": "string" } ``` **pipelines** - 파이프라인 설정 및 상태 ```json { "_id": "ObjectId", "name": "string", "type": "rss_collector|translator|image_generator", "status": "running|stopped|error", "config": {}, "schedule": "string (cron)", "stats": { "total_processed": 0, "success_count": 0, "error_count": 0, "last_run": "datetime", "average_duration_seconds": 0.0 }, "last_run": "datetime", "next_run": "datetime", "created_at": "datetime", "updated_at": "datetime" } ``` **applications** - OAuth2 애플리케이션 ```json { "_id": "ObjectId", "name": "string", "client_id": "string (unique)", "client_secret": "string (hashed)", "redirect_uris": ["string"], "grant_types": ["string"], "scopes": ["string"], "owner_id": "string", "created_at": "datetime", "updated_at": "datetime" } ``` ## 역할 기반 권한 | 역할 | 권한 | |------|------| | **Admin** | 모든 기능 접근 | | **Editor** | 키워드/파이프라인 관리, 모니터링 조회 | | **Viewer** | 조회만 가능 | ## API 문서 완전한 API 문서는 [`API_DOCUMENTATION.md`](./API_DOCUMENTATION.md) 파일을 참조하세요. **문서 포함 내용**: - 모든 37개 엔드포인트 상세 설명 - Request/Response JSON 스키마 - cURL 명령어 예제 - 에러 코드 및 처리 방법 - Python, Node.js, Browser 통합 예제 - 권한 매트릭스 ## Git 커밋 히스토리 ```bash # 최근 커밋 f4c708c - docs: Add comprehensive API documentation 1d461a7 - test: Fix Pydantic v2 compatibility and testing 52c857f - feat: Complete backend implementation 07088e6 - feat: Implement backend core functionality 7649844 - feat: Initialize News Engine Console project ``` ## 다음 단계 (Phase 2) ### Frontend 개발 (React + TypeScript) 1. ⏳ 프로젝트 초기화 (Vite + React + TypeScript) 2. ⏳ Material-UI v7 레이아웃 3. ⏳ Dashboard 페이지 (통계 요약) 4. ⏳ Keywords 관리 페이지 5. ⏳ Pipelines 제어 페이지 6. ⏳ Users 관리 페이지 7. ⏳ Applications 관리 페이지 8. ⏳ Monitoring 대시보드 9. ⏳ 실시간 업데이트 (WebSocket/SSE) ### 배포 1. ⏳ Frontend Dockerfile 2. ⏳ Docker Compose 설정 3. ⏳ Kubernetes 매니페스트 4. ⏳ CI/CD 파이프라인 상세 계획은 [`TODO.md`](./TODO.md)를 참조하세요. ## 빠른 시작 가이드 ### 1. MongoDB 관리자 사용자 생성 ```bash # MongoDB 연결 mongosh mongodb://localhost:27017 # 데이터베이스 선택 use news_engine_console_db # 관리자 사용자 생성 (test_api.py에서 자동 생성됨) # username: admin # password: admin123456 ``` ### 2. 백엔드 서버 시작 ```bash cd services/news-engine-console/backend MONGODB_URL=mongodb://localhost:27017 \ DB_NAME=news_engine_console_db \ python3 -m uvicorn main:app --host 0.0.0.0 --port 8101 --reload ``` ### 3. 로그인 테스트 ```bash # 로그인 curl -X POST http://localhost:8101/api/v1/users/login \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'username=admin&password=admin123456' # 응답에서 access_token 복사 # 인증된 요청 curl -X GET http://localhost:8101/api/v1/users/me \ -H 'Authorization: Bearer {access_token}' ``` ### 4. Swagger UI 사용 브라우저에서 http://localhost:8101/docs 접속하여 인터랙티브하게 API 테스트 ## 문제 해결 ### 포트 충돌 ```bash # 8101 포트 사용 중인 프로세스 확인 lsof -i :8101 # 프로세스 종료 kill -9 {PID} ``` ### MongoDB 연결 실패 ```bash # MongoDB 상태 확인 brew services list | grep mongodb # 또는 docker ps | grep mongo # MongoDB 시작 brew services start mongodb-community # 또는 docker start mongodb ``` ## 기여 가이드 1. 기능 구현 전 `TODO.md` 확인 2. API 엔드포인트 추가 시 `API_DOCUMENTATION.md` 업데이트 3. 테스트 코드 작성 및 실행 4. Commit 메시지 규칙 준수 ```bash # Commit 메시지 형식 : 🤖 Generated with Claude Code Co-Authored-By: Claude # type: feat, fix, docs, test, refactor, style, chore ``` ## 라이선스 Part of Site11 Platform - Internal Use --- **최종 업데이트**: 2025-01-04 **Phase**: Phase 1 Complete ✅ → Phase 2 Pending ⏳ **버전**: Backend v1.0.0 **작성자**: Site11 Development Team