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)
AnalysisResult 에 lat/lon 필드 + to_db_tuple 반영 + upsert_results SQL
컬럼 추가. 분류 파이프라인(last_row) / 경량 분석(all_positions) 두 경로
모두 분석 시점의 선박 위치를 함께 기록해 프론트 미니맵에서 특이운항
판별 위치를 실제 항적 위에 표시할 수 있게 한다.
배포 후 첫 사이클 8173/8173 lat/lon non-null 확인.
버그: all_ais 를 vessel_dfs(classification 통과 500척)만 대상으로 구성 →
허가선 906척 중 실제 AIS 존재 866척(upper bound 95.8%) 임에도 매칭률
9.4% 에 머물렀던 진짜 원인.
수정: vessel_store._tracks 전체에서 중국 MID(412/413/414) 활성 선박을
대상으로 match_ais_to_registry 호출. 매칭률 upper bound 95.8% 까지 회복 기대.
검증: 이번 AIS 실제 샘플 조사로 판명:
- AIS 고유 정규화 이름 411,908 개
- 허가선 정규화 이름 904 개
- 교집합 866 개 (95.8%)
→ 정규화 로직은 정상 작동. 문제는 호출 범위였음.
버그 원인: 초기 정규화가 선박번호(suffix)까지 제거 → '浙岭渔20865' → '浙岭渔' 로
축약 → 동명이 수십 개 발생 → len(unassigned)>1 조건에 전부 탈락 → FUZZY=0건.
중국/한국 어선명은 업체명+선박번호가 고유 식별자이므로 숫자 자체는 보존해야 함.
정규화는 공백/구두점/대소문자/'NO.' 마커만 통일:
'ZHE LING YU 20865' ↔ 'zhelingyu20865' ↔ 'ZHE-LING-YU-20865' 모두 일치
FUZZY 매칭 key 는 name_en 만 등록 (AIS 보고 이름이 영문이 주류).
두 가지 근본 버그를 동시에 해결:
1. Join key 버그 — raw AIS timestamp(ms 단위) inner join 은 두 선박 간 우연히
일치하는 확률이 거의 0. vessel_store._tracks 의 time_bucket(5분 리샘플)
컬럼을 우선 사용. _pair_join_key() 헬퍼로 fallback 지원.
2. AND 게이트 0건 문제 — 스펙 100%(2h 연속 + 500m + SOG 2-4 + sog_delta 0.5 +
cog 10°)를 전부 요구하면 실제 공조 페어를 놓침. Tier 분류로 재설계:
- STRONG : 스펙 100% (24 cycles, 기존 조건)
- PROBABLE: 800m / SOG 1.5-5 / sog_delta 1.0 / cog 20° / 12 cycles + 0.6 ratio
- SUSPECT : 동일 완화 조건 / 6 cycles + 0.3 ratio (플래그만)
G-06 판정은 STRONG/PROBABLE 만. SUSPECT 는 약한 신호로 노출.
거부 사유 카운터(REJECT_COUNTERS) + tier 카운트를 사이클별 로그 출력.
'조건이 엄격한건지 실제 페어가 없는건지' 원인 구분 가능.
피드백 메모리: feedback_detection_tier.md
- pair_trawl._ensure_sog_cog(): _trajectory_similarity 진입 시 sog/cog 없으면
vessel_store._compute_sog_cog() 로 haversine 계산 (tracks + timestamp 만 있으면 OK)
- pool 을 vessel_store._tracks 전체(55k)로 원복: 한국 440xxx/러시아 273xxx 페어 탐색 가능
- base 필터 중국 MID 확장: 412 → 412/413/414 (본토/홍콩/마카오)
- df_targets groupby 우회 제거 (불필요한 결합)
버그: vessel_store._tracks 는 raw_sog 만 보유 → _trajectory_similarity 가
sog/cog 컬럼 부재로 항상 0 반환 → candidates=0.
df_targets(select_analysis_targets 결과, 412* 전체 8k+ 에 sog/cog 계산)
를 mmsi 별로 groupby 하여 pool_tracks dict 생성. base 확장 필터의
sog 컬럼도 동일하게 적용.
첫 사이클 로그: base=512, pool=54825 → candidates=0 (2026-04-16 09:25).
수정 후 재검증 예정.
- V018 마이그레이션: prediction_events.features JSONB 컬럼 추가
- VesselAnalysis 직접 조회 API 5개 신설 (/api/analysis/*)
- vessels 목록 (필터: mmsi, zone, riskLevel, isDark)
- vessels/{mmsi} 최신 분석 (features 포함)
- vessels/{mmsi}/history 분석 이력
- dark 베셀 목록 (MMSI 중복 제거)
- transship 의심 목록
- PredictionEvent entity에 features JSONB 필드 추가
- EnforcementController vesselMmsi 필터 파라미터 추가
- event_generator.py INSERT에 features 컬럼 추가
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
AnalysisResult.to_db_tuple이 기존에 features dict 값을 모두 float로
변환했는데, dark_suspicion 구조를 넣으면서 dark_patterns(list) 등
비스칼라 타입이 포함되어 upsert 실패 (float argument not a list).
_sanitize 재귀 함수로 JSON 호환 타입(str/int/float/bool/list/dict/None)을
그대로 보존하도록 변경.
16:00 cron 1차 분석 결과, lightweight path가 6,500척 중 5,250척(80%)을
dark로 판정. 좌표 검증 결과 모두 30~37°N/122~125°E (동중국해/서해)로
한국 AIS 수신소 도달 한계 영역에 위치하여 정상 운항 중에도 20~24h 통째로
수신이 끊기는 자연 gap이 발생.
핫픽스: lightweight path에서 dark 판정 직후 마지막 위치가
북위 32~39.5, 동경 124~132 (한반도 + EEZ + 접속수역 여유 포함) 밖이면
dark를 False로 강제. 한국 측 관심 영역의 dark 탐지는 그대로 유지.
근본 개편(STATIONARY 정박 필터, 진입 후 단절 패턴, gap 임계값 재조정 등)은
12시간 추적 데이터 수집 후 내일 진행.
분석 사이클 완료 후 자동 실행되는 출력 파이프라인:
- event_generator: 분석결과 → 이벤트 자동 생성 (7개 룰, 카테고리별 dedup)
- violation_classifier: 위반 유형 라벨링 (EEZ/DARK/MMSI/TRANSSHIP/GEAR/RISK)
- kpi_writer: 실시간 KPI 6개 갱신 (오늘 기준 카운트)
- stats_aggregator: hourly/daily/monthly 사전 집계 (UPSERT)
- alert_dispatcher: CRITICAL/HIGH 이벤트 자동 알림 생성
scheduler.py에 출력 모듈 통합 (분석 8단계 완료 후 실행, non-fatal)
DB 연동 테스트 통과 (alerts 8건 생성, KPI tracking_active=2)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
