docs: 콜드메일 처리 시스템 개선 기록

journey/troubleshooting/251216_coldmail_processing_improvements.md

@@ -0,0 +1,57 @@
+# 콜드메일 처리 시스템 개선
+
+**날짜**: 2025-12-16  
+**작성자**: Claude  
+**관련 파일**: 
+- `rb8001/app/services/coldmail_processor.py`
+- `rb8001/app/services/workflows/coldmail_workflow.py`
+- `rb8001/app/router/slack_handler.py`
+
+---
+
+## 문제
+
+1. **신뢰도 판단 부족**: 모든 콜드메일을 동일하게 처리하여 오탐 시 사용자 혼란
+2. **회사명/대표명 추출 불완전**: 제목/발신자 기반 휴리스틱만 사용, 이메일 본문 정보 미활용
+3. **Slack Lists 통합 미흡**: 사용자 확인 없이 자동 등록, IR 분석 결과 업데이트 불가
+4. **JSON 파싱 중복 코드**: 9개 위치에서 유사한 JSON 파싱 로직 반복
+
+## 해결
+
+### 1. 신뢰도 기반 자동 처리
+- 신뢰도 95% 이상: 자동으로 Slack Lists 등록
+- 신뢰도 95% 미만: 확인 버튼만 전송, 사용자 확인 후 등록
+- `_filter_confidence` 필드를 이메일 객체에 추가하여 워크플로우 전체에서 활용
+
+### 2. 회사명/대표명 추출 개선
+- **회사명 추출 로직 강화**:
+  - 작은따옴표 패턴 추가 (`'온앤온'` 형태)
+  - 일반 이메일 도메인 제외 (gmail.com, naver.com 등)
+  - 괄호 패턴 지원 (`[회사명]`, `(회사명)`)
+- **LLM 기반 본문 파싱 추가**: `extract_company_info_from_email_body()` 함수로 이메일 본문에서 정보 추출
+- **우선순위**: LLM 본문 파싱 → IR 분석 → 휴리스틱
+
+### 3. Slack 인터랙티브 버튼 연동
+- "맞음"/"아님" 확인 버튼으로 사용자 검증
+- "이 기업을 분석해 드릴까요?" 버튼으로 IR Deck 분석 요청
+- 확인 버튼 클릭 시 `skip_email_detail=True`로 중복 API 호출 방지
+- IR 분석 백그라운드 실행 후 웹 프론트엔드 링크 제공
+
+### 4. JSON 추출 유틸리티 함수 도입
+- `app/utils/json_extractor.py` 추가: 범용 JSON 추출 함수
+- 7개 파일, 9개 위치에서 중복 코드 제거 (90줄 절약)
+- 다양한 LLM 응답 형식 자동 처리 (코드 블록, 설명 텍스트 등)
+
+## 교훈
+
+1. **신뢰도 기반 분기**: LLM 필터링 결과의 신뢰도를 활용하여 사용자 개입 최소화
+2. **우선순위 명확화**: 여러 소스에서 정보 추출 시 우선순위 정의 (LLM → IR → 휴리스틱)
+3. **사용자 확인 프로세스**: 불확실한 경우 확인 버튼으로 검증 후 처리
+4. **유틸리티 함수 우선**: 중복 코드는 공통 유틸리티 함수로 추출하여 재사용
+5. **API 호출 최적화**: 이미 조회한 데이터는 재사용 (`skip_email_detail`, `document_id` 재사용)
+
+## 관련 문서
+
+- JSON 추출 유틸리티: `app/utils/json_extractor.py`
+- 콜드메일 워크플로우: `app/services/workflows/coldmail_workflow.py`
+