From 0f4a9cb7d63284ec627682a9620d9a73380ec58c Mon Sep 17 00:00:00 2001 From: htlee Date: Fri, 17 Apr 2026 11:51:35 +0900 Subject: [PATCH 1/2] =?UTF-8?q?fix(db):=20candidate=5Fsource=20=EC=BB=AC?= =?UTF-8?q?=EB=9F=BC=20VARCHAR(30)=E2=86=92(100)=20=ED=99=95=EC=9E=A5=20(V?= =?UTF-8?q?031)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit gear_group_parent_candidate_snapshots.candidate_source 의 VARCHAR(30) 제약 때문에 prediction gear_correlation 스테이지가 매 사이클 실패하던 문제 해소. 원인: - prediction/algorithms/gear_parent_inference.py:875 의 candidate_source = ','.join(sorted(meta['sources'])) 가 복수 source 라벨 (CORRELATION/EPISODE/LABEL/LINEAGE/MATCH) 을 쉼표 join 하며 최대 약 39자. VARCHAR(30) 초과 시 psycopg2.errors.StringDataRightTruncation 을 유발해 _insert_candidate_snapshots 전체 ROLLBACK. 발견 경위: - Phase 0-1 (PR #83) 의 stage_runner + logger.exception 전환 후 journal 에 찍힌 풀 스택트레이스로 드러남. 기존에는 logger.warning 한 줄 ("gear correlation failed: ...") 만 남아 원인 특정 불가. 영향 범위: - 백엔드 JPA 엔티티 미참조 → 재빌드·재배포 불필요 - Flyway 자동 적용 (백엔드 기동 시) - prediction 재기동만 필요 (기존 코드 그대로, 이제 INSERT 성공 기대) 검증: - 재배포 후 journalctl 에서 'gear correlation failed' 로그 사라짐 확인 - kcg.gear_group_parent_candidate_snapshots 에 최근 15분 건수 증가 확인 --- .../V031__alter_candidate_source_length.sql | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 backend/src/main/resources/db/migration/V031__alter_candidate_source_length.sql diff --git a/backend/src/main/resources/db/migration/V031__alter_candidate_source_length.sql b/backend/src/main/resources/db/migration/V031__alter_candidate_source_length.sql new file mode 100644 index 0000000..ba80302 --- /dev/null +++ b/backend/src/main/resources/db/migration/V031__alter_candidate_source_length.sql @@ -0,0 +1,20 @@ +-- V031: gear_group_parent_candidate_snapshots.candidate_source VARCHAR(30) → VARCHAR(100) +-- +-- 원인: prediction/algorithms/gear_parent_inference.py 의 _rank_candidates 가 +-- candidate_source = ','.join(sorted(meta['sources'])) (line 875) +-- 로 여러 source 라벨(CORRELATION / EPISODE / LABEL / LINEAGE / MATCH 등) 을 쉼표로 +-- join 해 저장한다. 모든 source 가 맞춰지면 약 39자(5개 라벨 + 쉼표) 에 달해 +-- VARCHAR(30) 를 초과하며 psycopg2.errors.StringDataRightTruncation 을 유발. +-- +-- 영향: prediction 사이클의 gear_correlation 스테이지에서 `_insert_candidate_snapshots` +-- 실패 → `gear_group_parent_candidate_snapshots` 테이블 갱신 전체 스킵. +-- Phase 0-1 의 사이클 스테이지 에러 격리 덕분에 후속 스테이지(pair_detection / +-- per-vessel analysis / upsert_results / 출력 모듈들)는 정상 완주. +-- +-- 대안 검토: +-- (A) VARCHAR(100) — 여유치. 채택. +-- (B) TEXT — 제약 없음. 컬럼 의미가 "짧은 라벨 집합" 이라 VARCHAR 가 자연스러움. +-- (C) 코드에서 [:30] trim — 의미 손실(source 목록 절단). 부적합. + +ALTER TABLE kcg.gear_group_parent_candidate_snapshots + ALTER COLUMN candidate_source TYPE VARCHAR(100); From 2b25dc1c92718235ff821e21e3e8e8f3742c1d1d Mon Sep 17 00:00:00 2001 From: htlee Date: Fri, 17 Apr 2026 11:52:08 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=EB=A6=B4=EB=A6=AC=EC=A6=88=20?= =?UTF-8?q?=EB=85=B8=ED=8A=B8=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/RELEASE-NOTES.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/RELEASE-NOTES.md b/docs/RELEASE-NOTES.md index 0fdcb41..5da5714 100644 --- a/docs/RELEASE-NOTES.md +++ b/docs/RELEASE-NOTES.md @@ -4,6 +4,9 @@ ## [Unreleased] +### 수정 +- **gear_group_parent_candidate_snapshots.candidate_source VARCHAR(30)→(100) 확장 (V031)** — prediction `gear_parent_inference` 가 여러 source 라벨을 쉼표로 join 한 값(최대 ~39자)이 VARCHAR(30) 제약을 넘어 매 사이클 `StringDataRightTruncation` 으로 gear correlation 스테이지 전체가 실패하던 기존 버그. Phase 0-1 (PR #83) 의 `logger.exception` 전환으로 풀 stacktrace 가 journal 에 찍히면서 원인 특정. backend JPA 엔티티 미참조로 재빌드 불필요, Flyway 자동 적용, prediction 재기동만으로 해소 + ### 변경 - **Prediction 5분 사이클 스테이지 에러 경계 도입 (Phase 0-1)** — `prediction/pipeline/stage_runner.py` 신설해 `run_stage(name, fn, required=False)` 유틸 제공. `scheduler.py run_analysis_cycle()` 의 출력 6모듈(violation_classifier / event_generator / kpi_writer / stats_aggregate_hourly / stats_aggregate_daily / alert_dispatcher)을 한 try/except 로 묶던 구조를 스테이지별 독립 실행으로 분리, 한 모듈이 깨져도 다른 모듈이 계속 돌아가도록 개선. `upsert_results` 는 required=True 로 실패 시 사이클 abort. 내부 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 로 실패 지점 즉시 특정 가능. (docs/prediction-analysis.md P1 권고)