# Coldmail IR 분석 실패 해결 - 중복 파일 처리 개선

**날짜**: 2025-10-16
**작성자**: Claude (51124 서버 전담)
**커밋**: skill-rag-file cea055c
**관련 파일**: skill-rag-file/app/api/upload.py:60-79

---

## 문제 상황

Coldmail 브리핑 워크플로우에서 동일 PDF 재업로드 시 `400 - File already exists` 에러로 전체 IR 분석 실패.

**연쇄 효과**: PDF 업로드 실패 → document_id = None → RAG 검색 0건 → IR 분석 "N/A" → Slack Lists API 에러

---

## 원인 분석

**위치**: skill-rag-file/app/api/upload.py:67-71

**기존 동작**:
- 중복 파일 발견 시 HTTPException 발생
- document_id 반환 없음
- 멱등성 미보장: 동일 요청 재실행 시 결과 달라짐

---

## 해결 방안

**위치**: skill-rag-file/app/api/upload.py:60-79

**변경 내용**:
1. select(TeamDocument.id) → select(TeamDocument): 전체 레코드 조회
2. HTTPException 제거 → 기존 document_id 반환
3. FileUploadResponse 반환: 기존 document와 동일 응답
4. INFO 로그 추가: 중복 감지 기록

**핵심 로직**:
- existing_doc = result.scalar_one_or_none()
- if existing_doc: return FileUploadResponse(document_id=existing_doc.id, ...)

---

## 구현 완료

**배포**: 2025-10-16
- 커밋 해시: cea055c
- 상태: skill-rag-file 컨테이너 재시작 완료 (healthy)

---

## 효과

### 멱등성 보장

**Before**: 1차 성공, 2차 400 에러
**After**: 1차/2차/3차 모두 동일 document_id 반환

### Coldmail 워크플로우 안정성

PDF 업로드 → document_id 항상 획득 → RAG 검색 정상 → IR 분석 정확 → Slack 전송 성공

### 재시도 안전성

- 1차 시도: 파일 저장 + 벡터 생성 (느림)
- 2차 시도: 기존 document_id 즉시 반환 (빠름)

---

## 검증 계획

### 내일 실전 검증 (2025-10-17 09:05)

**Coldmail 브리핑 실행 시 확인**:
1. PDF 업로드 성공 여부
2. IR 분석 실제 데이터 반환 확인
3. Slack Lists 전송 성공 확인

**로그 체크**:
- rb8001: docker logs rb8001 --since "2025-10-17T09:00:00" | grep -iE "upload|document_id"
- skill-rag-file: docker logs skill-rag-file --since "2025-10-17T09:00:00" | grep "File already exists"

---

## 교훈

### 멱등성은 필수

**원칙**: 동일 요청을 여러 번 실행해도 결과가 같아야 함

**적용**:
- POST 요청이라도 리소스 생성/조회에는 멱등성 필요
- 중복 체크 시 에러가 아닌 기존 리소스 반환
- 네트워크 불안정, 재시도 상황에서 안전성 보장

### Cascading Failure 방지

**원인**: 한 단계 실패가 전체 워크플로우 실패로 연쇄

**해결**:
- 각 단계의 실패 격리
- 재시도 가능한 설계
- Graceful degradation (부분 성공 허용)

### 에러 메시지의 의미

"File already exists"는 에러가 아니라 상태 확인 메시지:
- 이미 존재하는 리소스 정보 반환
- 클라이언트는 정상 처리 가능