docs: 콜드메일 LangGraph interrupt 및 checkpoint 처리 개선 (251223)

journey/troubleshooting/251223_coldmail_langgraph_interrupt_and_checkpoint_fix.md

@@ -0,0 +1,47 @@
+# 콜드메일 LangGraph 워크플로우 interrupt 및 checkpoint 처리 개선
+
+**날짜**: 2025-12-23  
+**작성자**: happybell80  
+**관련 파일**: 
+- `rb8001/app/services/workflows/coldmail_workflow.py`
+- `rb8001/app/services/slack/coldmail_service.py`
+- `rb8001/app/router/slack_handler.py`
+
+---
+
+## 문제 상황
+
+1. **날짜, 대표 이름, PDF가 리스트에 등록되지 않음**: 사용자가 "맞음" 버튼 클릭 시 날짜, 대표 이름, PDF 파일이 Slack Lists에 등록되지 않음
+2. **워크플로우가 사용자 확인을 기다리지 않음**: LangGraph 워크플로우가 `process` 노드 후 바로 진행되어 사용자 확인을 기다리지 않음
+3. **checkpoint 없을 때 LangGraph 우회**: checkpoint가 없으면 폴백으로 직접 `process_coldmail` 호출하여 LangGraph를 우회함
+4. **레거시 코드가 워크플로우 방해**: `slack_handler.py`의 `_handle_coldmail_confirm`이 LangGraph를 거치지 않고 직접 처리
+
+## 해결 방안
+
+### 1. LangGraph interrupt 추가
+- `coldmail_workflow.py:283`: `interrupt_after=["process"]` 추가하여 process 노드 후 워크플로우 중단
+- 사용자 확인 대기 후 `confirm` 노드 실행
+
+### 2. checkpoint 없을 때 LangGraph로 처리
+- `coldmail_service.py:108-124`: checkpoint 없을 때 `initial_state` 생성하여 LangGraph로 처리
+- 폴백 로직 제거, 모든 경로를 LangGraph로 통일
+
+### 3. 레거시 코드 제거
+- `slack_handler.py:870-926`: `_handle_coldmail_confirm` 함수 제거
+- `slack_handler.py:758-835`: 실행되지 않는 레거시 코드 제거
+
+### 4. DB 경로 형식 수정
+- `coldmail_service.py:99`: `sqlite:///` 접두사 제거하여 `coldmail_briefing.py`와 동일한 형식 사용
+
+## 테스트 결과
+
+- 실제 이메일 19695(밀프레드)로 테스트 완료
+- 날짜(2025-12-21), 대표 이름(밀프레드), PDF(F0A4W2KC0M9) 모두 정상 등록됨
+
+## 교훈
+
+1. **LangGraph interrupt 활용**: `interrupt_after`로 사용자 입력 대기 지점 명시
+2. **checkpoint 없을 때도 LangGraph 사용**: `initial_state` 생성하여 워크플로우로 처리, 폴백 로직 제거
+3. **레거시 코드 정리**: 사용되지 않는 코드는 제거하여 혼란 방지
+4. **일관된 경로 형식**: 같은 기능은 동일한 형식 사용 (DB 경로 등)
+