docs: Add troubleshooting doc for 2025-12-16 coldmail IR analysis improvements

journey/troubleshooting/251216_coldmail_ir_analysis_improvements.md

@@ -0,0 +1,80 @@
+# 콜드메일 IR 분석 개선 및 프론트엔드 UX 향상
+
+**날짜**: 2025-12-16
+**작성자**: Auto
+**관련 파일**: 
+- `rb8001/app/services/ir_deck_analyzer.py`
+- `rb8001/app/services/slack/coldmail_service.py`
+- `rb8001/app/router/slack_handler.py`
+- `rb8001/app/services/coldmail_processor.py`
+- `frontend-ir-valuation/src/pages/ir-valuation.tsx`
+
+---
+
+## 작업 개요
+
+콜드메일 IR Deck 분석 기능 개선 및 프론트엔드 UX 향상 작업 수행.
+
+---
+
+## 주요 변경 사항
+
+### 1. IR Deck 분석 성능 개선 (09fd553, b361c96)
+- **병렬 처리 도입**: `ir_deck_analyzer.py`에서 페이지별 분석을 `asyncio.gather`로 병렬 실행
+- **성능 향상**: 약 4.9배 속도 개선
+- 수정: `app/services/ir_deck_analyzer.py`
+
+### 2. 콜드메일 IR 분석 아키텍처 개선 (a9af970)
+- **skill-slack API 전환**: `WebClient` 직접 호출 대신 skill-slack API 사용
+- **원칙 준수**: rb8001(brain) → skill-slack(hand) 위임 아키텍처 준수
+- 수정: `app/router/slack_handler.py`, `app/services/slack/coldmail_service.py`
+
+### 3. IR 분석 요청 방식 변경 (3a6e8d5)
+- **예/아니오 버튼 도입**: 자동 분석 대신 사용자 확인 후 분석
+- 수정: `app/router/slack_handler.py`, `app/services/coldmail_processor.py`
+
+### 4. thread_ts 처리 개선 (e5fad1d)
+- **조건부 포함**: `thread_ts`는 유효할 때만 포함하여 `invalid_thread_ts` 에러 방지
+- 수정: `app/services/slack/coldmail_service.py`
+
+### 5. 콜드메일 처리 개선 (211a822)
+- **email_metadata 업데이트**: 회사명, 연락처 정확히 저장
+- **Slack Lists 업데이트**: 기존 아이템 수정 방식으로 개선
+- **대규모 리팩토링**: Slack 라우터/서비스 모듈화, Claude 핸들러 제거
+- 수정: 24개 파일 (2,272줄 추가, 182줄 삭제)
+
+### 6. JSON 추출 유틸리티 도입 (af475de, 1ed63d1)
+- **중복 코드 제거**: JSON 추출 로직을 `app/utils/json_extractor.py`로 통합
+- 수정: 10개 파일 (273줄 추가, 158줄 삭제)
+
+### 7. 프론트엔드 UX 개선 (frontend-ir-valuation)
+- **복사 버튼 기능**: assistant 메시지 복사 기능 구현 (3a19e42, 9e26bfc, f36683d)
+- **스크롤 개선**: 자동 스크롤 제거, 수동 스크롤 버튼 추가 (aa69654)
+- **사이드바 기본 접힘**: 기본 상태를 접힌 상태로 변경 (6be3caa)
+- **URL 파라미터 로딩**: evaluation_id로 결과 자동 로딩 (c1869bb, f166e74)
+- **자동 배포**: Gitea Actions 워크플로우 추가 (0fcabf0)
+- 수정: `src/pages/ir-valuation.tsx`, `.gitea/workflows/deploy.yml`
+
+---
+
+## 구현 완료
+
+- **총 커밋**: 20개 (rb8001: 12개, frontend-ir-valuation: 8개)
+- **코드 변경량**: 약 3,000줄 추가, 400줄 삭제
+
+---
+
+## 교훈
+
+### 성능 개선 시 병렬 처리 고려
+- 페이지별 독립적인 분석 작업은 `asyncio.gather`로 병렬 처리하면 성능 대폭 향상 가능
+- I/O 바운드 작업의 경우 병렬 처리 효과 큼
+
+### 아키텍처 원칙 준수
+- skill-slack API 사용으로 서비스 간 책임 분리 명확화
+- rb8001은 비즈니스 로직, skill-slack은 Slack API 호출 담당
+
+### 사용자 경험 개선
+- 자동 분석보다 사용자 확인 후 분석이 더 나은 UX 제공
+- 프론트엔드 세부 기능(복사, 스크롤, 사이드바) 개선으로 사용성 향상
+