# 콜드메일 확인 버튼 UX 개선 및 IR Deck 종합 결론 형식 개선

**날짜**: 2026-01-26
**작성자**: happybell80
**관련 파일**: 
- `rb8001/app/services/slack/coldmail_service.py`
- `rb8001/app/services/workflows/coldmail_workflow.py`
- `frontend-ir-valuation/src/pages/ir-valuation.tsx`

---

## 배경

### 문제 1: 콜드메일 "맞음" 버튼 UX
- 사용자가 "맞음" 버튼 클릭 시 즉시 피드백 없음
- LangGraph 워크플로우 재개 및 리스트 등록 처리 중 진행 상황 확인 불가
- 처리 완료까지 오랜 시간 소요 (이메일 상세 조회, 첨부파일 처리, DB 저장, Slack API 호출 등)

### 문제 2: IR Deck 종합 결론 형식
- 현재 형식: 요약 → 핵심 리스크 → 핵심 강점 순서
- 사용자가 핵심 결론을 파악하기 위해 전체를 읽어야 함
- 결론을 앞부분에 배치하여 핵심 내용을 먼저 확인할 수 있도록 개선 필요

---

## Phase 1: 콜드메일 "맞음" 버튼 UX 개선

### 목표
"맞음" 버튼 클릭 시 즉시 피드백 제공 및 처리 진행 상황 표시

### 구현 계획

#### 1.1 interactive.py에서 channel, message_ts 전달
- **파일**: `rb8001/app/router/slack/interactive.py:96-105`
- **변경 사항**:
  - `handle_coldmail_confirm` 호출 시 `channel`, `message_ts` 파라미터 추가
  - IR 분석 버튼과 동일한 패턴으로 `payload.container.channel_id`, `payload.message.ts` 추출
  - `handle_coldmail_confirm(action, user_id, confirmed, channel, message_ts)` 시그니처 변경

#### 1.2 즉시 피드백 메시지 전송
- **파일**: `rb8001/app/services/slack/coldmail_service.py:56-156`
- **참고 패턴 확인 완료**: `coldmail_service.py:174-206` (IR 분석 버튼 로딩 메시지)
- **변경 사항**:
  - `handle_coldmail_confirm` 함수 시작 시 IR 분석 버튼과 동일한 패턴으로 "로빙 중…" 메시지 전송
  - 메시지 형식: `{"type": "context", "elements": [{"type": "mrkdwn", "text": ":robot_face: 로빙 중…"}]}`
  - 동일 스레드(`message_ts`를 `thread_ts`로 사용)에 메시지 전송하여 컨텍스트 유지
  - 메시지 타임스탬프(`loading_ts`) 저장하여 이후 업데이트에 사용
  - `skill-slack`의 `/api/v1/send` 엔드포인트 사용 (`skill-slack/app/api/endpoints/messages.py:19-64`)

#### 1.3 워크플로우 상태에 loading_ts 저장
- **파일**: `rb8001/app/services/workflows/coldmail_workflow.py:28-37, 161-197`
- **변경 사항**:
  - `ColdmailState`에 `loading_ts: str`, `loading_channel: str` 필드 추가 (옵션)
  - `handle_coldmail_confirm`에서 `Command(resume=...)`에 `loading_ts`, `loading_channel` 포함하여 전달
  - **검증 완료**: `test_coldmail_interrupt_return_pattern.py:133`에서 `Command(resume=...)` 패턴 확인
  - `wait_confirmation_node:185-190`에서 `decision` (interrupt 반환값)에서 `loading_ts`, `loading_channel` 추출하여 상태에 저장
  - 기존 `confirmed_email_id` 저장 패턴과 동일한 방식으로 구현 (`wait_confirmation_node:190` 참고)

#### 1.4 처리 완료 후 메시지 업데이트
- **파일**: `rb8001/app/services/workflows/coldmail_workflow.py:200-241`
- **API 스펙 확인 완료**: `skill-slack/app/api/endpoints/messages.py:66-105` (`/api/v1/update`)
- **변경 사항**:
  - `confirm_node`에서 상태의 `loading_ts`, `loading_channel`을 읽어서 메시지 업데이트
  - 리스트 등록 완료 후 "로빙 중…" 메시지를 "리스트 등록 완료" 메시지로 업데이트
  - 메시지 형식: `{"type": "context", "elements": [{"type": "mrkdwn", "text": "✅ 리스트 등록 완료"}]}`
  - `skill-slack`의 `/api/v1/update` 엔드포인트 사용
  - 요청 형식: `{"channel": loading_channel, "ts": loading_ts, "text": "리스트 등록 완료", "blocks": [...]}`
  - 최종 요약 메시지는 기존대로 `send_node`에서 전송

#### 1.5 에러 처리
- 워크플로우 재개 실패 시 "로빙 중…" 메시지를 에러 메시지로 업데이트
- 폴백 처리 시에도 동일한 피드백 제공
- `loading_ts`가 없으면 업데이트 생략 (에러 없이 진행)

### 참고 패턴
- IR 분석 버튼: `coldmail_service.py:158-206` (로딩 메시지 전송 패턴)
- 뉴스 게시: `news_service.py:13-54` (진행 상황 업데이트 패턴)
- interactive.py IR 분석 호출: `interactive.py:120` (`channel`, `message_ts` 전달 패턴)
- skill-slack 엔드포인트: `skill-slack/app/api/endpoints/messages.py:19-105` (`/send`, `/update` API 스펙)

### 검증 완료 사항
- **LangGraph Command(resume=...) 패턴**: `test_coldmail_interrupt_return_pattern.py:133`에서 검증됨
- **상태 전달 메커니즘**: `wait_confirmation_node:185-190`에서 `decision` (interrupt 반환값)에서 데이터 추출하여 상태에 저장하는 패턴 확인
- **기존 패턴 재사용**: `confirmed_email_id` 저장 방식(`wait_confirmation_node:190`)과 동일하게 `loading_ts`, `loading_channel` 저장 가능

### 주의 사항
- `action`에서 `channel`, `message_ts` 추출 시 `payload.channel.id`, `payload.message.ts` 경로 사용 (`interactive.py:63-64` 참고)
- `Command(resume=...)`에 포함된 값은 `wait_confirmation_node`의 `interrupt()` 반환값(`decision`)으로 전달됨
- `wait_confirmation_node`에서 `decision`을 파싱하여 상태에 저장해야 `confirm_node`에서 접근 가능
- `skill-slack`의 `/api/v1/update`는 `ts` 필수, `channel`, `text`, `blocks` 사용 가능

---

## Phase 2: IR Deck 종합 결론 형식 개선

### 목표
종합 결론 섹션에서 핵심 내용을 먼저 표시하여 사용자가 빠르게 파악 가능하도록 개선

### 구현 계획

#### 2.1 프론트엔드 형식 변경
- **파일**: `frontend-ir-valuation/src/pages/ir-valuation.tsx:515-539`
- **현재 코드 확인 완료**: 
  - 519-521줄: `result.summary` 먼저 출력
  - 524-530줄: `result.investment_opinion.risks` (핵심 리스크)
  - 532-537줄: `result.investment_opinion.strengths` (핵심 강점)
- **변경 사항**:
  - 현재 순서: 요약 → 핵심 리스크 → 핵심 강점
  - 변경 순서: **요약(결론) → 핵심 강점 → 핵심 리스크**
  - 532-537줄 (강점)을 524-530줄 (리스크) 앞으로 이동
  - 요약 문단은 이미 맨 앞에 있으므로 유지

#### 2.2 마크다운 형식 유지
- 기존 마크다운 형식 유지 (## 헤더, 리스트 등)
- 섹션 순서만 변경하여 기존 스타일과 호환성 유지
- 코드 변경: 단순 블록 순서 변경만 필요 (약 2-3줄 수정)

---

## 구현 순서

1. Phase 1.1: `interactive.py`에서 `channel`, `message_ts` 전달 추가
2. Phase 1.2: `handle_coldmail_confirm` 시그니처 변경 및 즉시 피드백 메시지 전송 구현
3. Phase 1.3: `ColdmailState`에 `loading_ts`, `loading_channel` 필드 추가
4. Phase 1.4: `Command(resume=...)`에 `loading_ts`, `loading_channel` 포함하여 전달
5. Phase 1.5: `wait_confirmation_node`에서 `decision`에서 `loading_ts`, `loading_channel` 추출하여 상태에 저장
6. Phase 1.6: `confirm_node`에서 상태의 `loading_ts`, `loading_channel`을 읽어서 메시지 업데이트 구현
7. Phase 1.7: 에러 처리 추가
8. Phase 2.1: IR Deck 종합 결론 형식 변경

---

## 테스트 전략 (TDD 원칙)

### TDD 원칙 준수
- **Red → Green → Refactor 순서**: 테스트 먼저 작성(Red) → 구현(Green) → 리팩터
- **기대 행동 확정**: 테스트에서 기대 행동을 먼저 명시한 뒤 구현
- **pytest 자동 테스트**: `tests/test_*.py` 형식, `pytest`로 실행 가능
- **E2E 테스트 필수**: 단위 테스트뿐만 아니라 실제 사용 시나리오 테스트

### Phase 1 테스트 계획

#### 1.1 즉시 피드백 메시지 전송 테스트
- **파일**: `rb8001/tests/test_coldmail_confirm_ux.py`
- **테스트 케이스**:
  - `test_handle_coldmail_confirm_sends_loading_message`: "맞음" 버튼 클릭 시 즉시 "로빙 중…" 메시지 전송 확인
  - `test_loading_message_in_same_thread`: 동일 스레드(`thread_ts`)에 메시지 전송 확인
  - `test_loading_ts_stored`: 메시지 타임스탬프(`loading_ts`) 저장 확인
- **모킹**: `skill-slack` API 호출 모킹 (`aiohttp.ClientSession`)

#### 1.2 워크플로우 상태 저장 테스트
- **테스트 케이스**:
  - `test_command_resume_includes_loading_info`: `Command(resume=...)`에 `loading_ts`, `loading_channel` 포함 확인
  - `test_wait_confirmation_node_extracts_loading_info`: `wait_confirmation_node`에서 `decision`에서 `loading_ts` 추출하여 상태에 저장 확인
  - `test_loading_ts_saved_to_state`: `ColdmailState`에 `loading_ts`, `loading_channel` 저장 확인
- **모킹**: LangGraph 워크플로우 상태 모킹
- **참고**: 기존 `test_coldmail_interrupt_return_pattern.py:133` 패턴 재사용

#### 1.3 메시지 업데이트 테스트
- **테스트 케이스**:
  - `test_confirm_node_reads_loading_info_from_state`: `confirm_node`에서 상태의 `loading_ts`, `loading_channel` 읽기 확인
  - `test_confirm_node_updates_loading_message`: `confirm_node`에서 "로빙 중…" 메시지를 "리스트 등록 완료"로 업데이트 확인
  - `test_update_message_api_call`: `skill-slack`의 `/api/v1/update` 엔드포인트 호출 확인
- **모킹**: `skill-slack` API, `process_coldmail` 함수

#### 1.4 에러 처리 테스트
- **테스트 케이스**:
  - `test_workflow_resume_failure_updates_message`: 워크플로우 재개 실패 시 에러 메시지 업데이트 확인
  - `test_fallback_processing_feedback`: 폴백 처리 시 피드백 제공 확인
  - `test_no_loading_ts_skips_update`: `loading_ts`가 없으면 업데이트 생략 확인

#### 1.5 E2E 테스트
- **파일**: `rb8001/tests/e2e/test_coldmail_confirm_ux_flow.py`
- **테스트 케이스**:
  - `test_full_confirm_flow`: "맞음" 버튼 클릭 → "로빙 중…" 메시지 → 리스트 등록 → 메시지 업데이트 → 최종 요약 전체 플로우 확인
- **실제 환경**: 실제 Slack API 호출 또는 통합 테스트 환경

### Phase 2 테스트 계획

#### 2.1 프론트엔드 형식 변경 테스트
- **파일**: `frontend-ir-valuation/src/pages/ir-valuation.test.tsx` (또는 E2E 테스트)
- **테스트 케이스**:
  - `test_conclusion_section_order`: 종합 결론 섹션 순서 확인 (요약 → 강점 → 리스크)
  - `test_summary_displayed_first`: 요약(결론)이 맨 앞에 표시되는지 확인
- **실제 환경**: 브라우저에서 실제 렌더링 확인

### 테스트 작성 원칙 참고
- **문서**: `DOCS/book/300_architecture/315_테스트_작성_원칙.md`
- **재사용성**: 공통 모킹 로직은 `tests/conftest.py`에 fixtures로 추출
- **실제 테스트**: 코드 수정 후 추측하지 말고 실제로 테스트 (curl, Slack 직접 사용)
- **컨테이너 테스트**: 새 테스트 파일 추가 시 `docker cp` 또는 컨테이너 재빌드 필요

---

## 검증 방법

### 콜드메일 UX 개선
- "맞음" 버튼 클릭 시 즉시 "로빙 중…" 메시지 확인
- 리스트 등록 완료 후 메시지 업데이트 확인
- 최종 요약 메시지 정상 전송 확인
- **실제 Slack 환경에서 E2E 테스트 수행**

### IR Deck 형식 개선
- 프론트엔드에서 종합 결론 섹션 순서 확인
- 요약(결론)이 맨 앞에 표시되는지 확인
- 핵심 강점 → 핵심 리스크 순서 확인
- **실제 브라우저에서 렌더링 확인**

---

## 구현 가능성 최종 확인

### Phase 1: 콜드메일 UX 개선
- ✅ **Slack 메시지 형식 확인 완료**: "로빙 중…" 메시지 패턴 (`coldmail_service.py:177-184`)
- ✅ **API 엔드포인트 확인 완료**: `/api/v1/send`, `/api/v1/update` 스펙 확인
- ✅ **LangGraph 상태 전달 검증 완료**: `Command(resume=...)` 패턴 테스트로 검증
- ✅ **기존 패턴 재사용 가능**: IR 분석 버튼, `confirmed_email_id` 저장 패턴과 동일
- **구현 가능**: 모든 기술적 요구사항 확인 완료, 즉시 구현 가능

### Phase 2: IR Deck 종합 결론 형식 개선
- ✅ **프론트엔드 코드 확인 완료**: `ir-valuation.tsx:515-539` 현재 구조 파악
- ✅ **변경 범위 최소화**: 단순 블록 순서 변경만 필요 (약 2-3줄 수정)
- ✅ **마크다운 형식 유지**: 기존 스타일과 호환성 유지
- **구현 가능**: 매우 간단한 변경, 즉시 구현 가능

### 종합 평가
- **타당성**: 95% (Phase 1: 95%, Phase 2: 95%)
- **실행 가능 상태**: ✅ 즉시 구현 가능
- **예상 작업 시간**: Phase 1 약 2-3시간, Phase 2 약 10분

---

## 참고 문서
- `DOCS/journey/troubleshooting/260121_coldmail_multi_confirm_loop_fix.md`: 콜드메일 확인 워크플로우
- `DOCS/journey/scenarios/ir_deck_evaluation_scenario.md`: IR Deck 평가 시나리오
- `DOCS/journey/ideas/250828_slack_message_formatting_guide.md`: Slack 메시지 포맷팅 가이드
