SCENARIO_MEDIA_CYCLE_FK_20260523

• 문서 작성자: 덱스PM
• 문서 오너: 덱스PM
• 작성일: 2026-05-23
• 상태: Open

이슈 개요

api의 Alembic drift 정리 과정에서 media와 scenarios 사이에 순환 FK(circular foreign key) 경고가 확인되었다.

현재 상태에서는 서비스 기동이나 alembic check를 직접 실패시키지는 않지만, SQLAlchemy/Alembic autogenerate가 테이블 정렬 순서를 안정적으로 계산하지 못하는 구조라는 점에서 향후 migration 유지보수 리스크가 있다.

현재 관측 사실

1. alembic check는 최종적으로 No new upgrade operations detected. 상태를 확보했다.
2. 다만 실행 중 아래 경고가 계속 관측되었다.
   • Cannot correctly sort tables; there are unresolvable cycles between tables "media, scenarios"
3. 이는 drift clean과 별개로, schema dependency graph 자체에 순환성이 있다는 뜻이다.

왜 중요한가

1. 새 migration autogenerate 시 결과 해석이 더 까다로워진다.
2. Alembic/SQLAlchemy 버전 업 시 현재 warning이 더 엄격한 오류로 승격될 가능성이 있다.
3. FK 방향이 얽혀 있으면 schema evolution, backfill, drop/change 순서 설계가 어려워진다.

추정 원인

• scenarios가 media를 참조하는 FK를 가짐
• 동시에 media 또는 연관 구조가 다시 scenarios를 참조하는 경로가 존재함

정확한 dependency 경로와 실제 제품상 필요성은 추가 분해가 필요하다.

처리 목표

1. 실제 FK 그래프를 명확히 문서화한다.
2. 어떤 참조가 도메인상 반드시 필요한지 구분한다.
3. 순환을 끊는 리팩터링 옵션을 제시한다.
4. 운영 영향이 낮은 방식으로 구조 개선 순서를 결정한다.

우선 검토할 해결 방향

옵션 A. 대표 미디어 참조를 별도 연결 테이블로 분리

• 장점: FK 방향 단순화 가능
• 단점: 조회/쓰기 코드 수정 범위 증가

옵션 B. 한쪽 FK를 느슨한 참조 키로 낮추고 애플리케이션 레벨 검증으로 대체

• 장점: schema cycle 해소가 빠름
• 단점: DB 레벨 무결성 일부 약화

옵션 C. 현재 구조 유지 + migration 운영 규칙만 강화

• 장점: 즉시 코드 변경 최소화
• 단점: 구조 부채를 그대로 안고 감

처리 원칙

1. Alembic clean 상태를 다시 깨지 않도록 단계적으로 접근한다.
2. 실제 사용 중인 API/화면/배치 영향도를 먼저 확인한다.
3. 구조 변경이 필요한 경우, schema 수정과 데이터 backfill 계획을 함께 문서화한다.

종료 조건

1. 순환 FK 실제 경로 파악 완료
2. 유지/개선 판단 완료
3. 필요 시 migration 및 코드 수정 완료
4. alembic check clean 유지 확인
5. 결과를 decision/report에 남긴 뒤 이슈 종료