From 7f14b107d12cc09e249ba10f4a0b92f6889e729d Mon Sep 17 00:00:00 2001
From: Claude-51124 <claude@51124.local>
Date: Tue, 2 Dec 2025 02:08:20 +0900
Subject: [PATCH] docs: add async rule for long-running HTTP tasks

---
 .../300_architecture/311_FastAPI_구조_원칙.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md
index e7313a0..58fc4a8 100644
--- a/book/300_architecture/311_FastAPI_구조_원칙.md
+++ b/book/300_architecture/311_FastAPI_구조_원칙.md
@@ -229,7 +229,20 @@ utils
 - 호출 횟수 미검토 시 API 할당량 초과(429 에러) 발생 가능
 - 단일 프롬프트로 통합 가능한 작업은 반드시 통합하여 호출 횟수 최소화
 
-## 14. 모범 사례 참고
+## 14. 장기 작업(LLM/RAG 등) 처리 원칙
+
+**핵심 원칙**: HTTP 요청으로 노출되는 장기 작업(LLM, RAG, 대용량 PDF 처리 등)은 동기식으로 붙잡지 말고, 항상 "즉시 ID 반환 + 비동기 백그라운드 작업 + 후속 조회/웹훅" 패턴으로 설계한다.
+
+### 권장 패턴
+- `POST /api/.../start` → 백그라운드 작업 등록, 즉시 `job_id` 또는 `evaluation_id` 반환
+- `GET /api/.../{id}` → 상태/결과 조회 (프론트는 폴링 또는 SSE/WebSocket 사용)
+- 필요 시 웹훅/이벤트로 완료 알림 (Slack, 이메일 등)
+
+### 금지 사항
+- ❌ Nginx `proxy_read_timeout`에 의존해 60초 이상 동기식으로 응답을 붙잡는 설계
+- ❌ LLM/RAG/외부 API 호출이 여러 단계로 이어지는 워크플로우를 단일 HTTP 요청에 모두 묶는 방식
+
+## 15. 모범 사례 참고
 
 본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다: