aimond/site11
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a9024ef9a1b8e77d4e442662ea80316a61f93642
site11/services/news-engine-console/README.md
jungwoo choi a09ea72c00 docs: Update project documentation to reflect Phase 1 completion 
- Add PROGRESS.md: Comprehensive progress tracking document
  * Phase 1 Backend completion status (37 endpoints ✅)
  * Testing results (100% pass rate, 8/8 tests)
  * Technical achievements and bug fixes documented
  * Pydantic v2 migration details
  * Next steps for Phase 2 (Frontend)

- Update README.md: Reflect Phase 1 completion
  * Mark backend implementation as complete (✅)
  * Update all 37 API endpoints documentation
  * Update project structure with completion markers
  * Update quick start guide with accurate credentials
  * Add environment variables documentation
  * Include MongoDB collection schemas
  * Add git commit history

- Update TODO.md: Comprehensive implementation plan update
  * Mark Phase 1 as complete (2025-11-04)
  * Update API endpoints section (37 endpoints complete)
  * Add Pydantic v2 migration section
  * Add testing completion section (100% success)
  * Add documentation completion section
  * Update checklist with Phase 1 completion
  * Add current status summary for next session
  * Move advanced features to Phase 4

Phase 1 Backend is now 100% complete with all features tested
and documented. Ready to proceed to Phase 2 (Frontend).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-04 20:43:43 +09:00

450 lines
13 KiB
Markdown
Raw Blame History

# 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 메시지 형식
<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
Reference in New Issue View Git Blame Copy Permalink