docs: 원칙 문서 보완 - DB 스키마 변경 동기화, LLM 호출 최적화, 트러블슈팅 경로 수정

book/300_architecture/311_FastAPI_구조_원칙.md

@@ -1,7 +1,7 @@
 # FastAPI 프로젝트 구조 원칙
 
 **작성일**: 2025-09-17
-**수정일**: 2025-10-02 (모범 사례 반영)
+**수정일**: 2025-12-01 (DB 스키마 변경 원칙, LLM 호출 최적화 원칙 추가)
 
 ## 1. 계층 분리 원칙
 
@@ -120,6 +120,28 @@ utils
 - ❌ JSONB 저장 시 dict 직접 전달 (json.dumps() 필수)
 - ❌ 프로덕션 요청 경로에서 직접 DB 연결 재사용
 
+## 6-1. DB 스키마 변경 시 동기화 필수
+
+**핵심 원칙**: ORM 모델, DDL, Repository 코드를 동시에 수정해야 함
+
+### 필수 동기화 항목
+1. **ORM 모델** (`state/{도메인}_repository.py` 또는 `models/{도메인}_model.py`)
+   - 컬럼 타입, nullable 여부, 기본값 등
+2. **DDL** (`_ensure_tables()` 또는 마이그레이션 스크립트)
+   - CREATE TABLE, ALTER TABLE 문
+3. **Repository 코드** (`state/{도메인}_repository.py`)
+   - INSERT/UPDATE 시 필드 처리 로직
+
+### 체크리스트
+- [ ] ORM 모델 수정 완료
+- [ ] DDL 수정 완료 (기존 DB 마이그레이션 스크립트 작성)
+- [ ] Repository 코드 수정 완료 (`.get()` 사용 등)
+- [ ] 테스트 작성 및 검증 완료
+
+### 교훈
+- 한 곳만 수정 시 런타임 에러(KeyError 등) 또는 스키마 불일치 발생
+- 스키마 변경 시 3곳(ORM/DDL/Repository) 동시 점검 필수
+
 ## 7. 파일 크기 제한
 
 - **한 파일 최대 300줄 권장**
@@ -143,6 +165,9 @@ utils
 - [ ] 비즈니스 로직이 router에 있지 않은가?
 - [ ] 순환 import 가능성은 없는가?
 - [ ] 핵심 파일은 300줄 이하로 유지할 수 있는가?
+- [ ] DB 스키마 변경 시 ORM/DDL/Repository 동시 수정 확인
+- [ ] LLM 호출 횟수 계산 및 최적화 검토
+- [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`)
 
 ## 10. 예외 상황
 
@@ -180,7 +205,31 @@ utils
 - ❌ 코드에서 `os.getenv()` 직접 호출 (Pydantic Settings 사용)
 - ❌ `docker-compose.yml`의 `environment:` 섹션에 하드코딩된 값
 
-## 13. 모범 사례 참고
+## 13. LLM 호출 최적화 원칙
+
+**핵심 원칙**: 호출 횟수 계산 및 최적화 사전 검토 필수
+
+### 필수 검토 사항
+1. **호출 횟수 계산**: 페이지/문서당 LLM 호출 횟수 사전 계산
+2. **API 할당량 확인**: 사용하는 LLM API의 할당량 제한 확인 (RPM, RPD 등)
+3. **통합 가능 여부**: 단일 프롬프트로 통합 가능한 작업은 반드시 통합
+
+### 최적화 방법
+- **단일 호출 통합**: 여러 개별 호출을 하나의 프롬프트로 통합
+- **배치 처리**: 가능한 경우 여러 항목을 한 번에 처리
+- **캐싱**: 동일한 입력에 대한 결과 캐싱
+
+### 체크리스트
+- [ ] LLM 호출 횟수 계산 완료
+- [ ] API 할당량 제한 확인 완료
+- [ ] 통합 가능한 호출 통합 완료
+- [ ] 테스트로 호출 횟수 검증 완료
+
+### 교훈
+- 호출 횟수 미검토 시 API 할당량 초과(429 에러) 발생 가능
+- 단일 프롬프트로 통합 가능한 작업은 반드시 통합하여 호출 횟수 최소화
+
+## 14. 모범 사례 참고
 
 본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다:
 

book/300_architecture/312_문서_작성_원칙.md

@@ -1,7 +1,7 @@
 # 문서 작성 원칙
 
 **작성일**: 2025-10-13
-**수정일**: 2025-11-28 (핵심 원칙 명확화, 중복 내용 정리)
+**수정일**: 2025-12-01 (트러블슈팅 문서 경로 수정)
 **참고**: CLAUDE.md, 311_FastAPI_구조_원칙.md
 
 ---
@@ -10,7 +10,7 @@
 
 ### 트러블슈팅 문서
 
-**경로**: `DOCS/troubleshooting/`
+**경로**: `DOCS/journey/troubleshooting/`
 **파일명**: `yymmdd_주제.md` (예: 251013_coldmail_ir_analyzer_fix.md)
 **규칙**:
 - 주제별 파일 분리 (날짜 중복 허용)
@@ -146,7 +146,7 @@
 ### 필수 항목
 1. **원인**: 왜 문제가 발생했는가
 2. **교훈**: 다음에 어떻게 방지할 것인가
-3. **원칙**: 위반한 원칙이 있는가
+3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`)
 
 ### 올바른 예시
 ```markdown