refactor(prediction): 사이클 스테이지 에러 경계 도입 (Phase 0-1) #83

htlee · 2026-04-17T11:29:42+09:00

htlee 코멘트됨,

2026-04-17 11:29:42 +09:00

소유자

변경 사항

docs/prediction-analysis.md P1 최우선 권고 반영 — Phase 0-1

prediction 5분 분석 사이클의 에러 격리 개선. 기존에는 아래 문제가 있었습니다:

scheduler.py:720-745 에서 출력 5모듈이 한 try/except 로 묶여 한 모듈 실패 시 5개 전부 스킵
내부 try/except 가 logger.warning("X failed: %s", e) 한 줄만 남겨 journalctl 에서 stacktrace 없이 원인 특정 불가
13시간 upsert 공백 사고(PR #73 배경) 같은 침묵 실패가 재현될 위험 구조적으로 존재

주요 변경

prediction/pipeline/stage_runner.py 신설
- run_stage(name, fn, *args, required=False, **kwargs) 유틸
- required=True → 예외 re-raise (상위 사이클 try/except 가 잡음)
- required=False → logger.exception 으로 stacktrace 보존 + None 반환
- 스테이지 지속시간도 함께 로깅
prediction/scheduler.py run_analysis_cycle() 스테이지 분리
- 출력 6모듈을 각각 run_stage() 로 독립 실행:
  violation_classifier / event_generator / kpi_writer / stats_aggregate_hourly / stats_aggregate_daily / alert_dispatcher
- upsert_results + cleanup_old 도 run_stage 로 래핑 (upsert 는 required=True — 실패 시 사이클 abort)
- 내부 try/except 의 logger.warning 을 logger.exception 으로 업그레이드 (6개 지점)

운영 효과

한 출력 모듈 실패가 나머지 5개를 블록하지 않음 → 이벤트 생성·KPI 갱신·경보 송출이 독립 회복
journalctl -u kcg-ai-prediction 에서 실패 스테이지명 + stacktrace 가 직접 보임
Phase 1 (Model Registry + DAG Executor) 의 기반 — 향후 각 모델도 동일 run_stage 로 감싸짐

테스트

python3 -m ast scheduler.py + stage_runner.py 문법 통과
run_stage smoke test: 정상 실행 / required=False 흡수 / required=True 재raise 3가지 시나리오
(운영 전 필수) make dev-prediction 한 사이클 실행 → "stage X ok in Ns" 로그 확인
(운영 전 필수) 의도적 raise 삽입 → 해당 스테이지만 failed, 나머지는 ok 확인

범위 밖 (다음 MR)

Phase 0-2: ILLEGAL_FISHING_PATTERN 전용 탐지 페이지
Phase 0-3: Transshipment 전용 탐지 페이지
Phase 1: 모델 Registry + DAG Executor 기반 인프라

## 변경 사항 **docs/prediction-analysis.md P1 최우선 권고 반영 — Phase 0-1** prediction 5분 분석 사이클의 에러 격리 개선. 기존에는 아래 문제가 있었습니다: - `scheduler.py:720-745` 에서 출력 5모듈이 한 `try/except` 로 묶여 한 모듈 실패 시 5개 전부 스킵 - 내부 try/except 가 `logger.warning("X failed: %s", e)` 한 줄만 남겨 journalctl 에서 stacktrace 없이 원인 특정 불가 - 13시간 upsert 공백 사고(PR #73 배경) 같은 침묵 실패가 재현될 위험 구조적으로 존재 ### 주요 변경 1. **`prediction/pipeline/stage_runner.py` 신설** - `run_stage(name, fn, *args, required=False, **kwargs)` 유틸 - `required=True` → 예외 re-raise (상위 사이클 try/except 가 잡음) - `required=False` → `logger.exception` 으로 stacktrace 보존 + None 반환 - 스테이지 지속시간도 함께 로깅 2. **`prediction/scheduler.py run_analysis_cycle()` 스테이지 분리** - 출력 6모듈을 각각 `run_stage()` 로 독립 실행: `violation_classifier` / `event_generator` / `kpi_writer` / `stats_aggregate_hourly` / `stats_aggregate_daily` / `alert_dispatcher` - `upsert_results` + `cleanup_old` 도 `run_stage` 로 래핑 (upsert 는 `required=True` — 실패 시 사이클 abort) - 내부 try/except 의 `logger.warning` 을 `logger.exception` 으로 업그레이드 (6개 지점) ### 운영 효과 - 한 출력 모듈 실패가 나머지 5개를 블록하지 않음 → 이벤트 생성·KPI 갱신·경보 송출이 독립 회복 - `journalctl -u kcg-ai-prediction` 에서 실패 스테이지명 + stacktrace 가 직접 보임 - Phase 1 (Model Registry + DAG Executor) 의 기반 — 향후 각 모델도 동일 `run_stage` 로 감싸짐 ## 관련 이슈 - docs/prediction-analysis.md §2 사이클 시퀀스 / §7 P1 권고 구조적 개선 제안 (PR #82, develop) ## 테스트 - [x] `python3 -m ast scheduler.py` + `stage_runner.py` 문법 통과 - [x] `run_stage` smoke test: 정상 실행 / required=False 흡수 / required=True 재raise 3가지 시나리오 - [ ] (운영 전 필수) make dev-prediction 한 사이클 실행 → "stage X ok in Ns" 로그 확인 - [ ] (운영 전 필수) 의도적 raise 삽입 → 해당 스테이지만 failed, 나머지는 ok 확인 ## 범위 밖 (다음 MR) - Phase 0-2: ILLEGAL_FISHING_PATTERN 전용 탐지 페이지 - Phase 0-3: Transshipment 전용 탐지 페이지 - Phase 1: 모델 Registry + DAG Executor 기반 인프라

htlee added 2 commits 2026-04-17 11:29:43 +09:00

refactor(prediction): 사이클 스테이지 에러 경계 도입 (Phase 0-1) 197da13826

docs/prediction-analysis.md P1 권고 반영. 5분 사이클의 각 스테이지를
한 try/except 로 뭉친 기존 구조를 스테이지 단위로 분리해 실패 지점을
명시적으로 특정하고 부분 실패 시에도 후속 스테이지가 계속 돌아가도록 개선.

- prediction/pipeline/stage_runner.py 신설
  - run_stage(name, fn, *args, required=False, **kwargs) 유틸
  - required=True 면 예외 re-raise (상위 사이클 try/except 가 잡도록)
  - required=False 면 logger.exception 으로 stacktrace 보존 + None 반환
  - 지속시간 로깅 포함

- prediction/scheduler.py run_analysis_cycle() 수정
  - 출력 단계 6모듈을 각각 run_stage() 로 분리:
    violation_classifier / event_generator / kpi_writer /
    stats_aggregate_hourly / stats_aggregate_daily / alert_dispatcher
  - upsert_results / cleanup_old 도 run_stage 로 래핑 (upsert 는 required=True)
  - 내부 try/except 의 logger.warning → logger.exception 으로 업그레이드
    (fetch_dark_history, gear collision event promotion, group polygon,
     gear correlation, pair detection, chat cache)
  - 스테이지 실패 시 journalctl -u kcg-ai-prediction 에서 stacktrace 로
    원인 바로 특정 가능 (기존은 "failed: X" 한 줄만 남아 디버깅 불가)

검증:
- python3 -c "import ast; ast.parse(...)" scheduler.py / stage_runner.py 통과
- run_stage smoke test (정상/실패 흡수/required 재raise 3가지) 통과

범위 밖 (후속):
- Phase 0-2 ILLEGAL_FISHING_PATTERN 전용 페이지 (다음 MR)
- Phase 0-3 Transshipment 전용 페이지 (다음 MR)

docs: 릴리즈 노트 업데이트 a32d09f75a

claude-bot 이 변경사항을 승인하였습니다. 2026-04-17 11:30:16 +09:00

claude-bot left a comment

멤버

Phase 0-1 사이클 스테이지 에러 경계 승인 (via /mr skill, docs/prediction-analysis.md P1 권고 반영)

htlee merged commit 3e29bc9995 into develop

2026-04-17 11:30:17 +09:00

htlee 삭제된 브랜치 feature/phase0-cycle-error-boundary

2026-04-17 11:30:17 +09:00

htlee 커밋

2026-04-17 11:30:19 +09:00

에서 이 이슈 언급