From ab30cae7cd4131df2f0d521bfbd55f78de6665e1 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Mon, 26 Jan 2026 10:27:05 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=BD=9C=EB=93=9C=EB=A9=94=EC=9D=BC=20?= =?UTF-8?q?=ED=99=95=EC=9D=B8=20=EB=B2=84=ED=8A=BC=20UX=20=EA=B0=9C?= =?UTF-8?q?=EC=84=A0=20=EB=B0=8F=20IR=20Deck=20=EC=A2=85=ED=95=A9=20?= =?UTF-8?q?=EA=B2=B0=EB=A1=A0=20=ED=98=95=EC=8B=9D=20=EA=B0=9C=EC=84=A0=20?= =?UTF-8?q?=EC=99=84=EB=A3=8C=20=EB=AC=B8=EC=84=9C=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 트러블슈팅 문서 작성 (260126_coldmail_confirm_ux_improvement.md) - 계획 문서 archive로 이동 --- ...ux_and_ir_conclusion_format_improvement.md | 236 ++++++++++++++++++ .../260126_coldmail_confirm_ux_improvement.md | 95 +++++++ 2 files changed, 331 insertions(+) create mode 100644 journey/plans/archive/260126_coldmail_confirm_ux_and_ir_conclusion_format_improvement.md create mode 100644 journey/troubleshooting/260126_coldmail_confirm_ux_improvement.md diff --git a/journey/plans/archive/260126_coldmail_confirm_ux_and_ir_conclusion_format_improvement.md b/journey/plans/archive/260126_coldmail_confirm_ux_and_ir_conclusion_format_improvement.md new file mode 100644 index 0000000..958abdb --- /dev/null +++ b/journey/plans/archive/260126_coldmail_confirm_ux_and_ir_conclusion_format_improvement.md @@ -0,0 +1,236 @@ +# 콜드메일 확인 버튼 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 메시지 포맷팅 가이드 diff --git a/journey/troubleshooting/260126_coldmail_confirm_ux_improvement.md b/journey/troubleshooting/260126_coldmail_confirm_ux_improvement.md new file mode 100644 index 0000000..818c76d --- /dev/null +++ b/journey/troubleshooting/260126_coldmail_confirm_ux_improvement.md @@ -0,0 +1,95 @@ +# 콜드메일 확인 버튼 UX 개선 및 IR Deck 종합 결론 형식 개선 + +**날짜**: 2026-01-26 +**작성자**: happybell80 +**관련 파일**: +- `rb8001/app/router/slack/interactive.py` +- `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, 106-114` +- **변경**: `handle_coldmail_confirm` 호출 시 `channel`, `message_ts` 파라미터 추가 + +#### 1.2 즉시 피드백 메시지 전송 +- **파일**: `rb8001/app/services/slack/coldmail_service.py:56-94` +- **변경**: 함수 시작 시 IR 분석 버튼과 동일한 패턴으로 "로빙 중…" 메시지 전송 +- **메시지 형식**: `{"type": "context", "elements": [{"type": "mrkdwn", "text": ":robot_face: 로빙 중…"}]}` +- **스레드**: `message_ts`를 `thread_ts`로 사용하여 동일 스레드에 전송 + +#### 1.3 워크플로우 상태에 loading_ts 저장 +- **파일**: `rb8001/app/services/workflows/coldmail_workflow.py:28-37, 185-197` +- **변경**: + - `ColdmailState`에 `loading_ts: str`, `loading_channel: str` 필드 추가 (옵션) + - `handle_coldmail_confirm`에서 `Command(resume=...)`에 `loading_ts`, `loading_channel` 포함 + - `wait_confirmation_node`에서 `decision`에서 추출하여 상태에 저장 + +#### 1.4 처리 완료 후 메시지 업데이트 +- **파일**: `rb8001/app/services/workflows/coldmail_workflow.py:202-270` +- **변경**: `confirm_node`에서 리스트 등록 완료 후 "로빙 중…" 메시지를 "✅ 리스트 등록 완료"로 업데이트 +- **API**: `skill-slack`의 `/api/v1/update` 엔드포인트 사용 + +#### 1.5 에러 처리 +- **파일**: `rb8001/app/services/slack/coldmail_service.py:175-200, 154-200` +- **변경**: 워크플로우 재개 실패 시 에러 메시지 업데이트, 폴백 처리 시에도 피드백 제공 + +### Phase 2: IR Deck 종합 결론 형식 개선 + +#### 2.1 프론트엔드 형식 변경 +- **파일**: `frontend-ir-valuation/src/pages/ir-valuation.tsx:515-539` +- **변경**: 섹션 순서 변경 (요약 → 강점 → 리스크) +- **코드**: 532-537줄(강점)을 524-530줄(리스크) 앞으로 이동 + +--- + +## 구현 완료 + +- **rb8001 커밋**: `d21361e` (feat: 콜드메일 확인 버튼 UX 개선) +- **frontend-ir-valuation 커밋**: `db88293` (feat: IR Deck 종합 결론 형식 개선) +- **테스트**: `test_coldmail_confirm_ux.py` 6개 테스트 모두 통과 +- **기존 테스트**: `test_coldmail_interrupt_return_pattern.py` 4개 테스트 모두 통과 (회귀 테스트 통과) + +--- + +## 교훈 + +### LangGraph 상태 전달 패턴 재사용 +- `Command(resume=...)`에 포함된 값은 `wait_confirmation_node`의 `interrupt()` 반환값(`decision`)으로 전달됨 +- 기존 `confirmed_email_id` 저장 패턴과 동일하게 `loading_ts`, `loading_channel` 저장 가능 +- **교훈**: 기존 검증된 패턴을 재사용하면 구현 복잡도 감소 및 안정성 향상 + +### 즉시 피드백의 중요성 +- 사용자 액션에 대한 즉시 피드백이 없으면 진행 상황을 알 수 없어 불안감 발생 +- IR 분석 버튼의 "로빙 중…" 패턴을 재사용하여 일관된 UX 제공 +- **교훈**: 긴 처리 시간이 필요한 작업은 반드시 즉시 피드백 제공 + +### TDD 원칙 준수 +- 테스트 먼저 작성(Red) → 구현(Green) → 리팩터 순서로 진행 +- 기존 테스트 패턴 재사용으로 테스트 작성 시간 단축 +- **교훈**: TDD 방식으로 진행하면 구현 전에 기대 행동을 명확히 하고, 회귀 테스트도 자동화 가능 + +--- + +## 참고 문서 +- 계획 문서: `DOCS/journey/plans/260126_coldmail_confirm_ux_and_ir_conclusion_format_improvement.md` +- 관련 트러블슈팅: `260121_coldmail_multi_confirm_loop_fix.md`, `260121_coldmail_interrupt_state_preservation_fix.md`