트러블슈팅: 파일 그래프 시각화 도구 개발 과정 문서화

docs/troubleshooting/250722_happybell80_파일그래프시각화개발.md

@@ -0,0 +1,88 @@
+# 파일 그래프 시각화 도구 개발
+
+## 오후 9시 45분
+
+### 파일 그래프 시각화 도구 개발
+
+#### 문제 상황
+Python 프로젝트의 파일 간 의존성과 함수 호출 관계를 시각화하는 도구 개발 중 여러 문제 발생
+
+#### 주요 이슈 및 해결
+
+1. **슬라이더 컨트롤 문제**
+   - 증상: 물리 시뮬레이션 설정 슬라이더가 클릭되지 않음
+   - 원인: `::before` 의사 요소가 슬라이더를 덮고 있었음
+   - 해결: `pointer-events: none` 추가
+   ```css
+   #customControlPanel::before {
+       pointer-events: none;
+   }
+   ```
+
+2. **함수 필터링 일관성 문제**
+   - 증상: `AssertionError: non existent node 'app/services/robing_brain.py::__init__'`
+   - 원인: 첫 번째 패스에서만 `__init__` 함수 제외하고 두 번째 패스에서는 누락
+   - 해결: 모든 패스에서 일관되게 함수 필터링 적용
+   ```python
+   # 첫 번째 패스
+   if node.name != '__init__' and not node.name.startswith('_'):
+       self.functions[rel_path].append(node.name)
+   
+   # 두 번째 패스에서도 동일하게 적용
+   if current_func == '__init__' or current_func.startswith('_'):
+       continue
+   ```
+
+3. **포트 충돌 문제**
+   - 증상: `OSError: [Errno 98] Address already in use`
+   - 원인: 이미 사용 중인 포트에 서버 실행 시도
+   - 해결: 다른 포트 사용 또는 기존 프로세스 종료
+
+4. **프로세스 종료 오류**
+   - 증상: `pkill -f "python3 -m http.server 3300"` 실행 시 Error
+   - 원인: 이미 종료된 프로세스를 종료하려고 시도
+   - 해결: 오류 무시하고 진행 (정상적인 상황)
+
+#### 구현된 기능
+
+1. **다단계 시각화**
+   - 파일 노드: 원형, 크기는 연결 수의 로그에 비례 (최소 16)
+   - 함수 노드: 작은 원형 (크기 8), 주황색 투명도 50%
+   - Import 연결: 회색 실선
+   - 함수 호출: 빨간색 점선
+   - 파일-함수 포함: 회색 점선
+
+2. **함수 필터링**
+   - `__init__` 함수 제외
+   - `_`로 시작하는 내부 함수 제외
+   - 결과: 131개 → 82개로 감소
+
+3. **자동 서버 실행**
+   ```python
+   subprocess.Popen(['python3', '-m', 'http.server', '3300'], 
+                   stdout=subprocess.DEVNULL, 
+                   stderr=subprocess.DEVNULL)
+   ```
+
+#### 교훈
+
+1. **CSS 레이어링 주의**
+   - 장식적 요소(`::before`, `::after`)는 항상 `pointer-events: none` 설정
+   - z-index만으로는 클릭 이벤트 문제 해결 안 됨
+
+2. **AST 분석 시 일관성**
+   - 함수 필터링은 모든 분석 단계에서 동일하게 적용
+   - 노드 추가 전 해당 노드 존재 여부 확인 필수
+
+3. **에러 처리 전략**
+   - 프로세스 종료 실패는 대부분 이미 종료된 경우
+   - 무시하고 진행해도 되는 에러와 반드시 처리해야 하는 에러 구분
+
+4. **시각화 원칙**
+   - 주요 정보(파일)는 크고 명확하게
+   - 보조 정보(함수)는 작고 투명하게
+   - 색상과 크기로 계층 구조 표현
+
+5. **개발 습관**
+   - 반복되는 실수는 README.md에 개발 주의사항으로 문서화
+   - 트러블슈팅 문서 작성으로 같은 실수 방지