# 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. 수동 호출 관계 정의 기능