site11/services/news-engine-console

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 실행

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

테스트 실행

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%

환경 변수

# 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 - 사용자 정보

{
  "_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 - 파이프라인 키워드

{
  "_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 - 파이프라인 설정 및 상태

{
  "_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 애플리케이션

{
  "_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 파일을 참조하세요.

문서 포함 내용:

• 모든 37개 엔드포인트 상세 설명
• Request/Response JSON 스키마
• cURL 명령어 예제
• 에러 코드 및 처리 방법
• Python, Node.js, Browser 통합 예제
• 권한 매트릭스

Git 커밋 히스토리

# 최근 커밋
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를 참조하세요.

빠른 시작 가이드

1. MongoDB 관리자 사용자 생성

# MongoDB 연결
mongosh mongodb://localhost:27017

# 데이터베이스 선택
use news_engine_console_db

# 관리자 사용자 생성 (test_api.py에서 자동 생성됨)
# username: admin
# password: admin123456

2. 백엔드 서버 시작

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. 로그인 테스트

# 로그인
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 테스트

문제 해결

포트 충돌

# 8101 포트 사용 중인 프로세스 확인
lsof -i :8101

# 프로세스 종료
kill -9 {PID}

MongoDB 연결 실패

# 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 메시지 규칙 준수

# Commit 메시지 형식
<type>: <subject>

<body>

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

# 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