# Phase 2 운영 Runbook

## 1. 목적

이 문서는 운영자가 Phase 2 수집 파이프라인을 실행, 점검, 재시도, 복구할 때 따르는 절차를 정의합니다.

## 2. 일일 운영 루틴

### 장 전 / 오전

- SEC submissions poll 정상 동작 여부 확인
- 전일 FINRA 파일 수집 완료 여부 확인
- FRED 최신 observation lag 확인
- source freeze 설정이 의도치 않게 켜져 있지 않은지 확인

### 장 후

- Alpaca daily bars 적재 완료 여부 확인
- SEC 신규 filing 유입량 점검
- 실패 잡 및 quarantine 건수 확인
- 데이터 품질 검증 리포트 확인

## 3. 기본 확인 명령

예시 명령은 프로젝트 CLI 이름에 맞게 조정합니다.

```bash
python -m apps.ops.show_recent_runs --limit 20
python -m apps.ops.show_failed_runs --since 24h
python -m apps.ops.show_checkpoints
python -m apps.ops.show_quarantine --since 7d
```

## 4. 특정 source 수동 실행

### SEC poll

```bash
python -m apps.collector.sec_collector.main --mode poll --run-id MANUAL_SEC_POLL_001
```

### Alpaca daily backfill

```bash
python -m apps.collector.alpaca_collector.main \
  --mode backfill \
  --symbols AAPL,MSFT,NVDA \
  --start-date 2026-01-01 \
  --end-date 2026-01-31
```

### FRED sync

```bash
python -m apps.collector.fred_collector.main --mode poll
```

### FINRA fetch

```bash
python -m apps.collector.finra_collector.main --mode poll
```

## 5. 실패 시 대응 절차

### 5.1 단일 run 실패

1. `job_runs`에서 상태와 오류 유형 확인
2. raw 파일이 쓰였는지 확인
3. checkpoint가 잘못 전진했는지 확인
4. retriable 이면 동일 파라미터로 재시도
5. terminal 이면 source payload와 schema drift 여부 확인

### 5.2 같은 잡이 연속 실패

1. source freeze 여부 확인
2. 환경변수/자격정보/네트워크 상태 확인
3. 최근 코드 변경 사항 확인
4. 원문 payload 1건을 replay 하여 문제 재현
5. 필요 시 해당 job freeze 후 다른 source는 계속 진행

## 6. Quarantine 처리

### 확인 항목

- 어떤 source인가
- 어떤 object type인가
- 언제부터 발생했는가
- 동일 원인 반복인가

### 절차

1. quarantine raw와 sidecar 열람
2. schema violation 또는 필수 필드 누락 원인 파악
3. 파서/정규화 로직 수정 필요 여부 판단
4. 수정 후 replay 수행
5. 정상 결과 확인 시 quarantine 해제 또는 새 run으로 재처리

## 7. Checkpoint 복구

### 증상

- 이미 처리한 데이터를 계속 다시 가져옴
- 새 데이터가 안 들어옴
- 특정 source만 오래 lag 발생

### 절차

1. 현재 checkpoint 값 백업
2. 최근 성공 run 기준 정상 위치 확인
3. 필요한 경우 checkpoint reset 실행
4. 작은 범위 backfill로 검증
5. 문제 없으면 정상 poll 재개

주의:
- checkpoint reset은 운영자 수동 승인 후에만 수행
- reset 전 snapshot 기록 필수

## 8. Replay 절차

Replay는 raw를 다시 해석하거나 구조화할 때 사용합니다.

예:

```bash
python -m apps.collector.sec_collector.main \
  --mode replay \
  --raw-path data/raw/sec/2026-03-12/.../filing.txt
```

확인할 것:
- replay run_id가 따로 생성되었는가
- 외부 API 호출이 발생하지 않았는가
- structured row가 기대한 대로 갱신되었는가

## 9. 데이터 이상 탐지 시 판단 기준

### SEC

- 특정 대형 종목 filing이 비정상적으로 누락됨
- filing_date 또는 accession 누락
- 99.1 artifact가 갑자기 전부 사라짐

### Alpaca

- 전일 bars가 없거나 너무 적음
- OHLC 순서 이상
- volume이 0 또는 과도하게 작음

### FRED

- 최신 observation이 지나치게 오래 갱신되지 않음
- series metadata가 바뀜

### FINRA

- 파일 헤더 형식 변경
- symbol row 급감
- ratio 계산 불가 행 급증

## 10. 일시적 중단(Freeze/Drain)

### Freeze

신규 실행을 즉시 막습니다.

### Drain

현재 실행만 마무리하고 다음 스케줄부터 멈춥니다.

사용 예:
- source 응답 포맷 변화 의심
- 저장 계층 장애
- 코드 배포 직후 이상 발견

## 11. 운영자가 반드시 남겨야 하는 기록

- 문제 발생 시각
- 영향 받은 source/job
- 영향 범위(날짜/심볼/CIK)
- 임시 조치
- 영구 수정 필요 여부
- replay/backfill 수행 여부

## 12. 운영 종료 체크

- 실패 run이 남아 있지 않은가
- checkpoint lag가 허용 범위 내인가
- quarantine 신규 건이 있는가
- raw/staging/structured count가 대체로 합리적인가
- 다음 배치를 막는 freeze가 켜져 있지 않은가