fix(db): candidate_source 컬럼 VARCHAR(30)→(100) 확장 (V031) #84

htlee · 2026-04-17T11:52:40+09:00

htlee 코멘트됨,

2026-04-17 11:52:40 +09:00

소유자

변경 사항

gear_group_parent_candidate_snapshots.candidate_source VARCHAR(30) → (100) 확장 (V031)

원인

prediction/algorithms/gear_parent_inference.py:875
의 candidate_source = ','.join(sorted(meta['sources'])) 가 여러 source 라벨
(CORRELATION / EPISODE / LABEL / LINEAGE / MATCH) 을 쉼표 join — 5개 전부 결합 시 ~39자
기존 컬럼 VARCHAR(30) 제약 → psycopg2.errors.StringDataRightTruncation
_insert_candidate_snapshots 전체 ROLLBACK → gear correlation 스테이지 실패

발견 경위

PR #83 (Phase 0-1) 의 stage_runner + logger.exception 전환 후 journal 에 풀 stacktrace 노출
이전: logger.warning("gear correlation failed: ...") 한 줄만 찍혀 원인 특정 불가했음
즉 Phase 0-1 의 직접적 부산물 — 잠복 기존 버그를 가시화

영향

사이클 자체는 Phase 0-1 에러 격리로 완주 (PR #83 배포 후 analysis cycle: 7912 vessels, 7912 upserted, 545.53s 확인)
다만 gear_group_parent_candidate_snapshots 테이블 갱신은 스킵되던 상태
이 fix 로 해당 테이블의 후보 스냅샷 기록이 복원됨

수정안 결정

VARCHAR(100) 채택 (여유치)
대안: TEXT — 짧은 라벨 집합 의미상 VARCHAR 가 자연스러움
대안: 코드쪽 [:30] trim — source 절단으로 의미 손실, 부적합

배포 절차

백엔드 JPA 엔티티 미참조 (grep GearGroupParentCandidateSnapshot backend/: 0건) → 재빌드 불필요
Flyway 자동 적용 (kcg-ai-backend 재기동 시)
prediction 재기동만으로 해소 (기존 코드 그대로, 이제 INSERT 성공)

테스트

V031 SQL 문법 검토 (단일 ALTER TABLE ... ALTER COLUMN ... TYPE VARCHAR(100))
(운영) 백엔드 재기동 → flyway_schema_history 에 V031 적용 확인
(운영) prediction 재기동 → journalctl -u kcg-ai-prediction 에서 "gear correlation failed" 로그 사라짐 확인
(운영) SELECT count(*) FROM kcg.gear_group_parent_candidate_snapshots WHERE observed_at > now() - interval '15 min'; > 0 확인

관련

PR #83 (Phase 0-1 stage_runner 도입) 이 이 버그를 가시화
docs/prediction-analysis.md 의 사이클 에러 격리 권고의 실제 효과 예시

## 변경 사항 **`gear_group_parent_candidate_snapshots.candidate_source` VARCHAR(30) → (100) 확장 (V031)** ### 원인 - [`prediction/algorithms/gear_parent_inference.py:875`](prediction/algorithms/gear_parent_inference.py#L875) 의 `candidate_source = ','.join(sorted(meta['sources']))` 가 여러 source 라벨 (`CORRELATION` / `EPISODE` / `LABEL` / `LINEAGE` / `MATCH`) 을 쉼표 join — 5개 전부 결합 시 ~39자 - 기존 컬럼 VARCHAR(30) 제약 → `psycopg2.errors.StringDataRightTruncation` - `_insert_candidate_snapshots` 전체 ROLLBACK → gear correlation 스테이지 실패 ### 발견 경위 - PR #83 (Phase 0-1) 의 `stage_runner` + `logger.exception` 전환 후 journal 에 풀 stacktrace 노출 - 이전: `logger.warning("gear correlation failed: ...")` 한 줄만 찍혀 원인 특정 불가했음 - 즉 Phase 0-1 의 직접적 부산물 — 잠복 기존 버그를 가시화 ### 영향 - 사이클 자체는 Phase 0-1 에러 격리로 **완주** (PR #83 배포 후 `analysis cycle: 7912 vessels, 7912 upserted, 545.53s` 확인) - 다만 `gear_group_parent_candidate_snapshots` 테이블 갱신은 스킵되던 상태 - 이 fix 로 해당 테이블의 후보 스냅샷 기록이 복원됨 ### 수정안 결정 - **VARCHAR(100)** 채택 (여유치) - 대안: `TEXT` — 짧은 라벨 집합 의미상 VARCHAR 가 자연스러움 - 대안: 코드쪽 `[:30]` trim — source 절단으로 의미 손실, 부적합 ### 배포 절차 - 백엔드 JPA 엔티티 **미참조** (`grep GearGroupParentCandidateSnapshot backend/`: 0건) → 재빌드 불필요 - Flyway 자동 적용 (kcg-ai-backend 재기동 시) - prediction 재기동만으로 해소 (기존 코드 그대로, 이제 INSERT 성공) ## 테스트 - [x] V031 SQL 문법 검토 (단일 `ALTER TABLE ... ALTER COLUMN ... TYPE VARCHAR(100)`) - [ ] (운영) 백엔드 재기동 → `flyway_schema_history` 에 V031 적용 확인 - [ ] (운영) prediction 재기동 → `journalctl -u kcg-ai-prediction` 에서 "gear correlation failed" 로그 사라짐 확인 - [ ] (운영) `SELECT count(*) FROM kcg.gear_group_parent_candidate_snapshots WHERE observed_at > now() - interval '15 min';` > 0 확인 ## 관련 - PR #83 (Phase 0-1 `stage_runner` 도입) 이 이 버그를 가시화 - docs/prediction-analysis.md 의 사이클 에러 격리 권고의 실제 효과 예시

htlee added 2 commits 2026-04-17 11:52:40 +09:00

fix(db): candidate_source 컬럼 VARCHAR(30)→(100) 확장 (V031) 0f4a9cb7d6

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분 건수 증가 확인

docs: 릴리즈 노트 업데이트 2b25dc1c92

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

claude-bot left a comment

멤버

V031 candidate_source 확장 승인 (via /mr skill, stage_runner 로 드러난 기존 버그 fix)

htlee merged commit 2e674ccc5b into develop

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

htlee 삭제된 브랜치 fix/candidate-source-length

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

htlee 커밋

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

에서 이 이슈 언급

Merge pull request 'fix(db): candidate_source 컬럼 VARCHAR(30)→(100) 확장 (V031)' (#84) from fix/candidate-source-length into develop

"로그인하여 이 대화에 참여"

No reviewers

레이블 없음

마일스톤 없음

담당자 없음

참여자 2명

알림

마감일

기한이 올바르지 않거나 범위를 벗어났습니다. 'yyyy-mm-dd'형식을 사용해주십시오.

마감일이 설정되지 않았습니다.

의존성

No dependencies set.

Reference: gc/kcg-ai-monitoring#84