From c6a7fe935c5f2878be811b451c600204667ea06d Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Tue, 2 Dec 2025 02:21:00 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EC=9B=90=EC=B9=99=20=EB=AC=B8=EC=84=9C?=
 =?UTF-8?q?=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8=20-=20=EC=98=A4?=
 =?UTF-8?q?=EB=8A=98=EC=9D=98=20=EA=B5=90=ED=9B=88=20=EB=B0=98=EC=98=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 312_문서_작성_원칙.md: CLAUDE.md → AGENTS.md 참조 변경
- 313_React_구조_원칙.md: 배열/객체 필드 검증 필수 원칙 추가 (Array.isArray 체크 예시)
- 311_FastAPI_구조_원칙.md: Nginx 타임아웃 설정 확인 필수 원칙 추가 (HTTP/HTTPS 블록 모두 적용)
---
 .../311_FastAPI_구조_원칙.md              | 16 ++++++++++++-
 .../312_문서_작성_원칙.md               |  6 ++---
 .../313_React_구조_원칙.md                | 23 ++++++++++++++++++-
 3 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md
index 58fc4a8..c286e7a 100644
--- a/book/300_architecture/311_FastAPI_구조_원칙.md
+++ b/book/300_architecture/311_FastAPI_구조_원칙.md
@@ -1,7 +1,7 @@
 # FastAPI 프로젝트 구조 원칙
 
 **작성일**: 2025-09-17
-**수정일**: 2025-12-01 (DB 스키마 변경 원칙, LLM 호출 최적화 원칙 추가)
+**수정일**: 2025-12-02 (Nginx 타임아웃 설정 확인 필수 원칙 추가)
 
 ## 1. 계층 분리 원칙
 
@@ -242,6 +242,20 @@ utils
 - ❌ Nginx `proxy_read_timeout`에 의존해 60초 이상 동기식으로 응답을 붙잡는 설계
 - ❌ LLM/RAG/외부 API 호출이 여러 단계로 이어지는 워크플로우를 단일 HTTP 요청에 모두 묶는 방식
 
+### Nginx 타임아웃 설정 확인 필수
+
+**핵심 원칙**: 장기 작업을 위한 프록시 엔드포인트는 HTTP/HTTPS 블록 모두에 충분한 타임아웃 설정 필요
+
+**필수 확인 사항**:
+- Nginx 설정 파일에서 `/rb8001/` 또는 해당 프록시 경로의 `location` 블록 확인
+- `proxy_read_timeout`, `proxy_connect_timeout`, `proxy_send_timeout` 설정 확인
+- HTTP(port 80)와 HTTPS(port 443) 블록 모두에 동일한 타임아웃 설정 적용
+- 권장 값: `proxy_read_timeout 300s; proxy_connect_timeout 75s; proxy_send_timeout 300s;`
+
+**교훈**:
+- HTTP 블록에 타임아웃 설정 누락 시 HTTPS만 설정되어 있어도 HTTP 요청에서 504 Gateway Timeout 발생 가능
+- 프록시 타임아웃은 백엔드 작업 시간보다 충분히 길게 설정 (백엔드 작업 시간 + 여유분)
+
 ## 15. 모범 사례 참고
 
 본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다:
diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md
index 5b3524b..fd1bace 100644
--- a/book/300_architecture/312_문서_작성_원칙.md
+++ b/book/300_architecture/312_문서_작성_원칙.md
@@ -1,8 +1,8 @@
 # 문서 작성 원칙
 
 **작성일**: 2025-10-13
-**수정일**: 2025-12-01 (트러블슈팅 문서 경로 수정)
-**참고**: CLAUDE.md, 311_FastAPI_구조_원칙.md
+**수정일**: 2025-12-02 (CLAUDE.md → AGENTS.md 참조 변경)
+**참고**: AGENTS.md, 311_FastAPI_구조_원칙.md
 
 ---
 
@@ -198,6 +198,6 @@
 
 ## 8. 참고 문서
 
-- CLAUDE.md: 전체 개발 가이드
+- AGENTS.md: 전체 개발 가이드
 - 311_FastAPI_구조_원칙.md: 코드 구조 원칙
 - troubleshooting/ 폴더: 트러블슈팅 예시
diff --git a/book/300_architecture/313_React_구조_원칙.md b/book/300_architecture/313_React_구조_원칙.md
index 4d1b7d3..a905026 100644
--- a/book/300_architecture/313_React_구조_원칙.md
+++ b/book/300_architecture/313_React_구조_원칙.md
@@ -1,7 +1,7 @@
 # React 프론트엔드 구조 원칙
 
 **작성일**: 2025-11-29
-**수정일**: 2025-12-01 (환경별 코드 분리, 에러 처리, 데이터 검증 원칙 추가)
+**수정일**: 2025-12-02 (배열/객체 필드 검증 필수 원칙 추가)
 **참고**: 311_FastAPI_구조_원칙.md, 312_문서_작성_원칙.md
 
 ## 1. 컴포넌트 설계 원칙
@@ -155,6 +155,27 @@ src/
 - 데이터 누락 시 사용자에게 명확한 안내 메시지 제공
 - 예상치 못한 데이터 구조에 대한 폴백 처리
 
+### 배열/객체 필드 검증 필수
+
+**문제**: 백엔드가 배열을 예상했지만 `null` 또는 `undefined`를 반환할 경우 `TypeError: Cannot read property 'map' of null` 발생
+
+**해결책**:
+- 배열 필드: `Array.isArray(data.field) ? data.field : []` 또는 `data.field ?? []`
+- 객체 필드: 옵셔널 체이닝(`?.`) 사용
+- 기본값 설정: `const items = result.page_evaluations ?? [];`
+
+**예시**:
+```typescript
+// ❌ 금지: 직접 map 사용
+result.page_evaluations.map(...)
+
+// ✅ 권장: Array.isArray 체크
+const evaluations = Array.isArray(result.page_evaluations) 
+  ? result.page_evaluations 
+  : [];
+evaluations.map(...)
+```
+
 ## 11. 체크리스트
 
 코드 작성 전/후 확인: