Metadata-Version: 2.4
Name: collector-hj3415
Version: 0.2.2
Summary: Collector runtime utilities for hj3415
Keywords: collector,scheduler,ops
Author-email: Hyungjin Kim <hj3415@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: pymongo>=4.8
Requires-Dist: typer>=0.12
Requires-Dist: db2-hj3415
Requires-Dist: logging-hj3415
Requires-Dist: pydantic>=2.12
Requires-Dist: pydantic-settings>=2.12

# collector-hj3415

`collector-hj3415`는 수집(collector) 작업 운영에 필요한 공통 유틸리티를 제공하는 **파이썬 라이브러리 패키지**입니다.  
MongoDB 상태 확인, 배치 실행 이력 기록, Telegram 실패 알림, 일/주간 메일 리포트 기능을 공통으로 묶어 재사용할 수 있습니다.

## 1) 프로젝트 기능 (사용자 관점)

- MongoDB 준비 상태를 확인해, 수집 잡 시작 전에 연결 가능 여부를 점검합니다.
- 현재 UTC 시각(`asof`)을 생성해 잡 실행 기준 시점을 통일합니다.
- 잡 실행 결과(성공/실패, 실행 시간, 메시지)를 `job_runs` 컬렉션에 저장합니다.
- 동일 장애 메시지에 대해 쿨다운을 적용해 Telegram 알림 중복 폭주를 줄입니다.
- 누적된 실행 이력을 바탕으로 일간/주간 요약 메일을 발송합니다.

## 2) 프로젝트 구조 (쉽게 보기)

```text
packages/collector-hj3415/
├─ src/collector_hj3415/
│  ├─ cli.py          # 핵심 기능 + CLI 엔트리포인트
│  ├─ __main__.py     # python -m collector_hj3415 실행 진입점
│  └─ __init__.py
├─ pyproject.toml     # 패키지 메타데이터/의존성 정의
└─ README.md
```

- 실제 기능 구현은 대부분 `cli.py`에 있습니다.
- 콘솔 스크립트 엔트리 등록은 없고, `python -m collector_hj3415.cli ...` 형태로 실행합니다.

## 3) 설치

프로젝트 루트 기준:

```bash
pip install -e ./packages/collector-hj3415
```

또는 배포된 wheel/tar.gz가 있다면 일반 `pip install` 방식으로 설치할 수 있습니다.

## 4) CLI 사용법

기본 형식:

```bash
python -m collector_hj3415.cli <command> [options]
```

### 4.1 MongoDB 준비 대기

```bash
python -m collector_hj3415.cli wait-mongo --timeout-sec 90
```

- 지정 시간 내 `ping` 성공 시 `0`, 실패 시 `1`을 반환합니다.

### 4.2 현재 UTC 시각 생성

```bash
python -m collector_hj3415.cli gen-asof-utc
```

- ISO-8601 UTC 문자열을 출력합니다.

### 4.3 Universe 존재 여부 확인

```bash
python -m collector_hj3415.cli universe-exists --universe krx300
```

- `universe_latest` 컬렉션에서 `_id=krx300` 존재 시 `0`, 없으면 `1` 반환.

### 4.4 잡 실행 결과 기록

```bash
python -m collector_hj3415.cli record-job-run \
  --job-name scraper_daily_c101 \
  --status ok \
  --started-epoch 1711700000 \
  --ended-epoch 1711700100 \
  --message "completed"
```

### 4.5 Telegram 실패 알림 (쿨다운 포함)

```bash
python -m collector_hj3415.cli notify-telegram-failure \
  --job-name scraper_daily_c101 \
  --message "failed with exit=1"
```

- `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` 미설정 시 전송 없이 `0` 반환.
- 쿨다운 중이면 `2` 반환.
- 전송 실패 시 `1` 반환.

### 4.6 일간/주간 메일 리포트 발송

```bash
python -m collector_hj3415.cli send-report daily
python -m collector_hj3415.cli send-report weekly
```

- MongoDB `job_runs` 데이터를 집계해 메일 본문을 만들고 SMTP로 전송합니다.

## 5) 테스트 실행

### 5.1 Smoke Test (Mocking)

개발 환경에서 외부 의존성 없이 로직의 정상 동작을 확인하기 위해 `pytest`를 사용할 수 있습니다.

```bash
# 패키지 루트에서 실행
cd packages/collector-hj3415
pytest tests/test_cli.py
```

### 5.2 Integration Test (Real Network)

실제 MongoDB, Telegram, SMTP 서버와의 연동을 확인하기 위한 테스트입니다. `src/collector_hj3415/.env` 파일에 유효한 설정이 있어야 합니다.

```bash
# 패키지 루트에서 실행
cd packages/collector-hj3415
pytest tests/test_cli_integration.py -v
```

- **MongoDB**: 설정된 `MONGO_URI`로 실제 연결 및 데이터 기록을 테스트합니다.
- **Telegram**: 실제 Bot Token과 Chat ID를 사용하여 메시지를 전송합니다.
- **SMTP**: 설정된 메일 서버를 통해 실제 메일 발송을 테스트합니다. (실패 시 skip 처리됨)

## 6) 다른 프로젝트에서 임포트해서 사용하기

`collector` 하위 배치 프로젝트에서 공통으로 사용하는 방식입니다.

### 5.1 파이썬 코드에서 직접 호출

```python
from collector_hj3415.cli import wait_mongo, record_job_run
import time

if wait_mongo(timeout_sec=60) != 0:
    raise SystemExit("MongoDB is not ready")

started = int(time.time())
# ... 실제 작업 수행 ...
ended = int(time.time())

record_job_run(
    job_name="my_batch_job",
    status="ok",
    started_epoch=started,
    ended_epoch=ended,
    message="done",
)
```

### 5.2 셸 스크립트에서 모듈 CLI 호출

```bash
python3 -m collector_hj3415.cli wait-mongo --timeout-sec 90
python3 -m collector_hj3415.cli record-job-run \
  --job-name "my_job" \
  --status "fail" \
  --started-epoch "$started" \
  --ended-epoch "$ended" \
  --message "error message"
```

## 6) 환경변수 설정

아래 값들은 미지정 시 기본값으로 동작합니다.

| 변수명 | 기본값 | 설명 |
|---|---|---|
| `MONGO_URI` | `mongodb://mongo:27017` | MongoDB 연결 URI |
| `MONGO_DB_NAME` | `hj3415` | DB 이름 |
| `SERVICE_NAME` | `collector` | 서비스/잡 소속 이름 |
| `JOB_RUNS_COLLECTION` | `job_runs` | 잡 실행 이력 컬렉션 |
| `JOB_ALERTS_COLLECTION` | `job_alerts` | Slack 알림 쿨다운 상태 컬렉션 |
| `ALERT_COOLDOWN_MIN` | `60` | 동일 알림 메시지 쿨다운(분) |
| `TELEGRAM_BOT_TOKEN` | 빈 값 | Telegram Bot API Token |
| `TELEGRAM_CHAT_ID` | 빈 값 | Telegram Chat ID |
| `SMTP_HOST` | 빈 값 | SMTP 호스트 (미설정 시 메일 발송 스킵) |
| `SMTP_PORT` | `587` | SMTP 포트 |
| `SMTP_USE_TLS` | `true` | TLS 사용 여부 |
| `SMTP_USERNAME` | 빈 값 | SMTP 사용자 |
| `SMTP_PASSWORD` | 빈 값 | SMTP 비밀번호 |
| `MAIL_FROM` | `collector@localhost` 또는 `SMTP_USERNAME` | 발신자 주소 |
| `MAIL_TO_DAILY` | 빈 값 | 일간 리포트 수신자(쉼표 구분) |
| `MAIL_TO_WEEKLY` | 빈 값 | 주간 리포트 수신자(쉼표 구분) |

예시:

```bash
export MONGO_URI="mongodb://localhost:27017"
export MONGO_DB_NAME="hj3415"
export SERVICE_NAME="collector-scraper-daily"
export TELEGRAM_BOT_TOKEN="123456789:ABCDEF..."
export TELEGRAM_CHAT_ID="987654321"
export ALERT_COOLDOWN_MIN="60"

export SMTP_HOST="smtp.gmail.com"
export SMTP_PORT="587"
export SMTP_USE_TLS="true"
export SMTP_USERNAME="bot@example.com"
export SMTP_PASSWORD="app-password"
export MAIL_FROM="collector@example.com"
export MAIL_TO_DAILY="ops@example.com,dev@example.com"
export MAIL_TO_WEEKLY="ops@example.com"
```

## 참고

이 패키지는 단독 애플리케이션이 아닌 **라이브러리 성격의 공통 모듈**이므로, Dockerfile/docker-compose 조합 사용법은 이 문서에서 다루지 않습니다.

