Add: PlantUML 시퀀스 다이어그램 생성기 트러블슈팅 문서

troubleshooting/250804_happybell80_시퀀스다이어그램생성기.md

@@ -0,0 +1,84 @@
+# 2025년 8월 4일 - PlantUML 시퀀스 다이어그램 자동 생성기 개발
+
+## 오후 2시 1분
+
+### PlantUML 기반 시퀀스 다이어그램 자동 생성기 구현
+
+#### 배경
+- FastAPI 프로젝트의 API 호출 흐름을 자동으로 분석하여 PlantUML 시퀀스 다이어그램 생성
+- 로빙 프로젝트의 복잡한 호출 관계를 시각화하기 위한 도구 필요
+
+#### 구현 내용
+
+1. **AST 기반 Python 코드 분석기**
+   - FastAPI 라우터 자동 탐지
+   - 함수 호출 관계 추적
+   - import alias 매핑 지원
+
+2. **PlantUML 생성기**
+   - 분석된 호출 흐름을 PlantUML 형식으로 변환
+   - 참여자 자동 식별 및 메시지 흐름 생성
+
+3. **개선 사항**
+   - 불필요한 호출 필터링 (1109개 → 388개로 감소)
+   - 무의미한 참여자 제거 (json, logger, data 등)
+   - 파일명에 프로젝트명 포함으로 구분 명확화
+
+#### 문제점과 한계
+
+1. **AST 정적 분석의 한계**
+   - 함수 내부의 로컬 import 처리 불가
+   - 인스턴스 메서드 호출 추적 어려움
+   - 동적으로 생성되는 라우트 감지 불가
+
+2. **깊은 호출 체인 추적 실패**
+   ```python
+   # 예: slack_service._process_message() 내부의 
+   # RobeingBrain.process_request() 호출을 추적하지 못함
+   ```
+
+3. **프레임워크별 차이**
+   - rb10408: Slack Bolt 데코레이터 기반 라우팅 인식 못함
+   - 각 프로젝트의 구조적 차이로 인한 분석 정확도 차이
+
+#### 프로젝트별 분석 결과
+
+| 프로젝트 | 라우트 수 | 함수 호출 수 | 특징 |
+|---------|----------|------------|------|
+| rb8001 | 14개 | 388개 | 원본 구조, 많은 서비스 |
+| rb10408_test | 14개 | 127개 | Slack Bolt, 가장 경량 |
+| rb10508_test | 16개 | 443개 | 가장 복잡, 테스트 기능 |
+| rb10508_micro | 12개 | 169개 | 핵심만 구현 |
+
+#### 사용법
+
+```bash
+# uv로 실행 (Python 패키지 관리)
+uv run python main.py --path ../rb8001 --list-routes
+uv run python main.py --path ../rb8001 --route /events --output generated
+```
+
+#### 교훈
+
+1. **정적 분석 vs 동적 분석**
+   - 정적 분석만으로는 실제 런타임 동작을 완벽히 파악하기 어려움
+   - 동적 트레이싱이나 프로파일링 도구와 병행 필요
+
+2. **도메인 지식의 중요성**
+   - 프로젝트 구조를 알면 휴리스틱으로 정확도 향상 가능
+   - 범용 도구보다 특화된 도구가 더 실용적일 수 있음
+
+3. **uv 패키지 매니저 활용**
+   - pip 대체로 빠른 속도와 자동 의존성 관리
+   - `uv run` 명령으로 가상환경 자동 관리
+
+4. **완벽보다는 실용성**
+   - 100% 정확한 분석보다 80% 수준의 유용한 결과가 더 가치있음
+   - 기본적인 호출 흐름 파악만으로도 프로젝트 이해에 도움
+
+#### 향후 개선 방향
+
+1. 동적 분석 도구 통합
+2. 프레임워크별 특화 분석기 개발
+3. 실행 시점 트레이싱 기능 추가
+4. 수동 호출 관계 정의 기능