---
tags: [plans, coldmail, ir, attachments, rb8001]
---

# 콜드메일 IR 분석대상 선택 정합화 계획

**작성일**: 2026-03-13  
**상태**: 완료 (2026-03-13)  
**목표**: 콜드메일 다중 PDF 첨부에서 올바른 IR 대상 문서를 선택하고, 선택 실패 시 잘못된 분석 버튼 대신 명확한 상태 메시지를 노출하도록 고정합니다.

## 관련 문서
- [콜드메일 IR 분석이 첫 번째 PDF를 잘못 선택하는 상태](../debug/260313_coldmail_ir_분석대상_오선택_디버그.md)
- [콜드메일 IR 분석대상 선택 정합화 구현 및 배포 검증](../worklog/260313_coldmail_ir_분석대상_선택_정합화_구현및배포검증.md)

## 1. 문제 정의
- 현재 콜드메일 프로세스는 첨부 PDF를 여러 개 업로드해도 후속 단계에서 `document_ids[0]`만 사용합니다.
- 그 결과 오늘 메일 `21037`처럼 회사소개서가 이미 저장돼 있어도, 첫 번째 PDF인 재무제표가 IR 분석 대상으로 고정될 수 있습니다.
- 이 상태는 `IR Deck 분석`이라는 기능명과 실제 입력 문서가 어긋난 버그입니다.

## 2. 이번 계획의 결정
- 메일을 다시 조회하는 방향으로 닫지 않습니다.
- 이미 저장된 첨부파일들 중에서 IR 분석 대상을 선택하는 로직을 추가하고, 그 선택 결과를 후속 단계 전체에 일관되게 전달합니다.
- 선택 실패 시 조용히 첫 번째 PDF로 진행하지 않습니다.
- Slack 메시지에서는 신뢰도 `%`를 노출하지 않습니다.

## 3. 범위
- 포함:
  - 첨부 업로드 결과에 파일명과 `document_id`의 대응 정보 유지
  - IR 분석 대상 선택 로직 추가
  - 선택된 문서를 IR 분석, Slack 첨부, Slack 버튼 payload에 동일 적용
  - 선택 실패 시 `메일에서 IR 자료를 찾지 못했습니다.` 상태 메시지 노출
  - Slack 메시지에서 회사명 우선 노출
  - Slack 메시지에서 정확도 `%` 제거
  - 선택 결과 로그 가시화
  - 다중 PDF 첨부 테스트 추가
- 제외:
  - 전체 이메일 저장 구조 전환
  - 첨부 업로드 실패 일반화 처리
  - 장기적 범용 문서 분류 시스템

## 4. 구현 원칙
- 선택 없는 첫 번째 PDF 고정 사용을 제거합니다.
- 선택 결과는 단일 값이 아니라 근거가 보이는 구조로 유지합니다.
- 이미 저장된 첨부가 있으면 재다운로드보다 저장된 선택 결과 재사용을 우선합니다.
- 선택 실패는 성공처럼 포장하지 않고 로그와 후속 경로에 드러냅니다.
- 콜드메일 여부와 IR 자료 존재 여부를 분리해 표시합니다.
- 사용자 메시지는 `어느 회사의 콜드메일이 왔는지`를 먼저 보여줍니다.

## 5. 구현 단계

### A. 첨부 매핑 구조 도입
- `process_naverworks_attachments()`는 단순 `document_id` 리스트 대신, 최소한 아래 정보를 유지하는 결과를 반환합니다.
  - `filename`
  - `document_id`
  - `attachment_id`
- 후속 단계가 파일명과 문서 ID의 대응을 잃지 않도록 합니다.

### B. IR 대상 선택 함수 추가
- `coldmail_processor.py` 내부 또는 별도 유틸리티에 "IR 대상 선택" 함수를 둡니다.
- 1차 선택 기준:
  - 우선 후보: `ir`, `deck`, `pitch`, `introduction`, `회사소개서`
  - 후순위 또는 제외 후보: `재무제표`, `financial`, `감사`, `부록`
- 반환값은 최소 아래를 포함합니다.
  - `selected_document_id`
  - `selected_filename`
  - `selection_reason`
- 후보가 없거나 동률 충돌이면 실패 상태를 반환합니다.

### C. 선택 결과 단일화
- 아래 경로가 모두 같은 선택 결과를 사용하도록 정리합니다.
  - IR 지표 추출
  - `IRDeckAnalyzer.analyze()`
  - Slack List 첨부 파일 다운로드
  - `coldmail_analyze_ir` 버튼 payload
- `document_ids[0]` 직접 참조는 제거합니다.

### D. 선택 실패 가시화
- 선택 실패 시 남길 로그:
  - 이메일 ID
  - 후보 파일명 목록
  - 실패 이유
- 자동 등록은 유지하되, IR 분석 버튼은 생성하지 않습니다.
- Slack에는 `메일에서 IR 자료를 찾지 못했습니다.` 상태 메시지를 남깁니다.
- 메시지 본문에는 먼저 회사명을 보여준 뒤 IR 자료 부재 상태를 붙입니다.

### E. 테스트 추가
- 최소 테스트 케이스:
  - `재무제표 + 회사소개서` 동시 첨부 시 회사소개서 선택
  - `IR + 재무제표` 동시 첨부 시 IR 선택
  - IR 후보 없음 시 선택 실패 + 버튼 미노출 + 상태 메시지 노출
  - 선택된 `document_id`가 Slack 버튼 payload와 실제 분석 입력에 동일 반영
  - Slack 메시지에 정확도 `%`가 노출되지 않음

## 6. 오늘 사례에 대한 적용 기준
- 메일 `21037` 기준으로는 `모바일콘 회사소개서_v.1.0_01 (2).pdf`에 연결된 `document_id=486bfc9e-fcc2-4229-a080-6af6fb5cc940`가 분석 대상이 되어야 합니다.
- 오늘 사례를 다시 실행하거나 동일 버튼 흐름을 재현할 때, `95bc416e-bdf1-40b3-9de2-6073c8c1b313`이 아니라 선택된 회사소개서 문서가 분석에 들어가야 합니다.

## 7. 검증 기준
- 다중 PDF 콜드메일에서 선택된 파일명과 `document_id`가 로그에 남습니다.
- Slack 첨부 파일, IR 분석 호출, 재분석 버튼 payload가 동일한 `selected_document_id`를 사용합니다.
- 오늘 사례 유형(`재무제표 + 회사소개서`)에서 재무제표가 더 이상 IR 분석 입력으로 들어가지 않습니다.
- 선택 실패 케이스에서 첫 번째 PDF로 조용히 진행하는 로그가 0건입니다.
- 선택 실패 케이스에서 Slack에는 회사명과 함께 `메일에서 IR 자료를 찾지 못했습니다.` 메시지만 남고 분석 버튼은 없습니다.
- Slack 메시지에서 신뢰도 `%` 텍스트는 0건입니다.

## 8. 후속 경계
- 전체 이메일 저장은 별도 아이디어 문서에서 다루고, 이번 계획 범위에 섞지 않습니다.
- 장기적으로는 파일명 기반 규칙만으로 충분하지 않을 수 있으므로, 이후 본문/제목/문서 텍스트까지 포함한 점수화 방식은 별도 계획으로 분리합니다.
- 콜드메일 판정과 IR 자료 존재 판정을 분리한 장기 UX 설계는 이번 계획에서 다루지 않습니다.

## 한 줄 결론
- 이번 계획은 "첫 번째 PDF" 고정 버그를 제거하고, 올바른 IR 문서를 선택할 때만 분석 버튼을 노출하며, 실패 시에는 회사명과 함께 `메일에서 IR 자료를 찾지 못했습니다.` 상태를 보여주는 작업입니다.

## 완료 메모
- 구현 및 배포 검증 완료.
- 상세 결과는 [콜드메일 IR 분석대상 선택 정합화 구현 및 배포 검증](../worklog/260313_coldmail_ir_분석대상_선택_정합화_구현및배포검증.md)에서 관리합니다.
