drawNET Bug Report - 2026-03-22 🐞

이 문서는 2026년 3월 22일 발생한 버그 및 장애와 그에 따른 조치 사항을 기록합니다.

현상: 오브젝트 스튜디오(Object Studio) 접속 시 다국어 파일(i18n.js)과 파비콘(favicon.ico)을 찾을 수 없다는 404 에러와 함께 UI의 버튼 글자가 번역되지 않은 상태(Raw Key)로 노출됨.
원인:
1. 경로 오표기: static/js/modules/studio/ 디렉토리 내의 renderer.js와 actions.js에서 ../../i18n.js 경로를 사용함. 실제 파일은 ../i18n.js(static/js/modules/i18n.js)에 위치해 있어 상대 경로 계산 오류 발생.
2. 파비콘 링크 누락: studio.html 파일에 명시적인 파비콘 링크가 없어 브라우저가 기본값인 /favicon.ico를 호출함.
조치:
1. renderer.js 및 actions.js의 임포트 경로를 ../i18n.js로 일괄 수정하여 다국어 모듈 로딩 정상화.
2. studio.html 상단에 통합 로고(logo.svg)를 파비콘으로 사용하는 링크 태그 추가.
3. 스튜디오 전체 리소스 로딩 상태를 재점검하여 누락된 정적 파일이 없음을 확인.

현상: 도움말 버튼(help-btn) 클릭 시 도움말 모달(Help Modal)이 열리지 않고, 브라우저 콘솔에 Uncaught (in promise) ReferenceError: t is not defined 에러가 발생하며 인터페이스가 멈추는 현상.
원인:
1. 마크다운 렌더러 라이브러리(marked.js) 통합을 위한 help_modal.js 리팩토링 과정에서 실수로 상단의 import { t } from '../i18n.js'; 구문을 삭제함.
2. 모달 템플릿 코드 내에서 다국어 번역 함수인 ${t('help_center')} 등을 호출할 때 해당 함수가 정의되지 않아 런타임 에러가 발생함.
조치:
1. static/js/modules/ui/help_modal.js 파일 상단에 누락된 t 함수 임포트 구문을 즉시 복구함.
2. 모달 내의 모든 t() 호출부가 정상적으로 바인딩되었는지 검증하고, 모달이 정상적으로 팝업되는 것을 확인함.
3. 향후 리팩토링 시 필수 의존성(Dependency) 누락 여부를 체크하도록 코드 리뷰 프로세스 보강.

현상: PPTX 내보내기 시 "객체별 상세 내용 및 주석 목록" 슬라이드에서 실제 노드(오브젝트)는 보이지 않고, UUID 형태의 이름을 가진 선(edge)들만 대거 나열되는 현상.
원인:
1. 상세 목록 필터가 description 속성이 있는 객체만 찾도록 되어 있어, 설명이 없는 일반 노드들은 모두 제외됨.
2. 수동 경로 오프셋(routing_offset)이 있는 엣지들이 필터에 포함되면서, 라벨이 없는 일반 엣지들이 UUID와 함께 노출됨.
조치:
1. 상세 목록 필터를 개선하여 모든 일반 노드를 포함하도록 수정 (단, 그룹은 설명이 있을 때만 포함).
2. 엣지는 사용자 정의 라벨이나 설명이 있을 때만 포함하도록 변경하여 무의미한 항목 제거.
3. 라벨이 없는 엣지의 경우 UUID 대신 [시작노드] -> [대상노드] 형태의 읽기 쉬운 이름을 자동 생성하도록 보완.

현상: 왼쪽 에셋 라이브러리 상단의 필터(패키지 관리) 아이콘을 클릭해도 아무런 반응이 없는 것처럼 보이는 현상.
원인:
1. selector.js에서 모달 팝업 생성 시 modal.style.display = 'flex'만 사용함.
2. 공통 CSS(modal.css)에서 .modal-overlay는 기본적으로 opacity: 0이며 .active 클래스가 있어야만 화면에 표시되도록 정의되어 있어 시각적으로 숨겨진 상태였음.
3. 구형 코드인 static/js/modules/assets.js 파일이 잔류하여 디버깅 및 유지보수에 혼선을 줌.
조치:
1. selector.js의 모달 제어 로직을 classList.add('active') 및 remove('active') 방식으로 변경하여 CSS 애니메이션 및 가시성 확보.
2. 사용되지 않는 구형 assets.js 파일을 삭제하여 모듈 구조 단순화.

현상: 선(edge) 속성창에서 시작/대상 호버 하이라이트가 표시된 상태에서 색상이나 스타일을 변경하면 하이라이트가 즉시 사라짐.
원인: renderProperties() 시작 부분에 unhighlight()가 포함되어 있어, 속성 변경에 따른 리렌더링 발생 시마다 하이라이트가 강제로 초기화됨.
조치:
1. renderProperties() 내부의 상시 unhighlight() 호출 제거.
2. 선택된 객체가 변경될 때 발생하는 selection:changed 이벤트 핸들러에서만 unhighlight()를 호출하도록 로직 위치 변경.
3. 이를 통해 동일 객체의 속성을 수정하는 동안에는 시각적 하이라이트가 유지되도록 정합성 확보.

현상: 선(edge) 선택 시 브라우저 콘솔에 renderProperties start 로그가 무한히 출력되며 성능이 저하되는 현상.
원인:
1. 선 선택 시 호출되는 unhighlight()가 노드의 attr을 수정함.
2. attr 수정이 cell:change:attrs 이벤트를 발생시킴.
3. 해당 이벤트 리스너가 다시 renderProperties()를 호출하여 무한 루프가 발생함.
조치:
1. unhighlight 및 highlight 호출 시 모든 속성 변경에 { silent: true } 옵션을 부여하여 불필요한 이벤트 전파 차단.
2. cell:change 이벤트 리스너에서 options.silent 플래그를 확인하여 내부적인 시각 효과 변경 시에는 리렌더링을 건너뛰도록 개선.

현상: 엣지 속성창에서 시작/대상 선택 상자에 마우스를 올렸을 때 나타나는 노드 강조(테두리)가 사이드바를 닫거나 선택을 바꿔도 사라지지 않고 유지됨.
원인: 하이라이트 제거 로직(unhighlight)이 오직 mouseleave 이벤트에만 바인딩되어 있어, 사이드바를 닫거나 다른 객체로 전환 시 이벤트가 트리거되지 않음.
조치:
1. unhighlight 로직을 모듈 레벨 함수로 분리.
2. 사이드바 닫기 버튼, 적용 버튼 클릭 시 및 속성창 리렌더링(renderProperties) 시작 시점에 항상 unhighlight를 호출하도록 보강하여 잔상 방지.

현상: 새로 생성된 선(edge)이 기존 그룹의 배경 뒤로 숨어서 보이지 않거나 선택이 어려운 현상.
원인: 선 생성 시 레이어 오프셋이 적용되지 않은 기본 z-index(30)가 부여되어, 이미 레이어 가중치(101, 201 등)를 받은 그룹보다 낮게 배치됨.
조치:
1. layers.js에 중앙 집중형 z-index 계산 함수(calculateCellZIndex)를 도입하여 레이어 오프셋과 객체 타입별 우선순위(노드>선>그룹)를 통합 관리.
2. 선 및 노드 생성 시(config.js, 스타일 매핑 모듈) 즉시 해당 함수를 호출하여 초기 z-index를 올바르게 할당하도록 구조 개선.

아카이브 관리자: drawNET AI Assistant