Claude-51124 f0d9890110 Refactor troubleshooting docs to follow documentation principles

Changes:
- 251016_coldmail_duplicate_file_fix.md: 298줄 → 111줄
- 251016_troubleshooting_summary.md: 184줄 → 109줄

Applied principles (312_문서_작성_원칙.md):
- Removed excessive code blocks
- Kept file:line references only
- Removed emojis
- Reduced to ~100 lines per document
- Kept core information and lessons learned

2025-10-16 16:23:20 +09:00

2.9 KiB

Raw Blame History

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

변경 내용:

select(TeamDocument.id) → select(TeamDocument): 전체 레코드 조회
HTTPException 제거 → 기존 document_id 반환
FileUploadResponse 반환: 기존 document와 동일 응답
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 브리핑 실행 시 확인:

PDF 업로드 성공 여부
IR 분석 실제 데이터 반환 확인
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"는 에러가 아니라 상태 확인 메시지:

이미 존재하는 리소스 정보 반환
클라이언트는 정상 처리 가능

2.9 KiB Raw Blame History