docs: FastAPI 구조 원칙 문서 정리 (중복/불필요 표현 제거, 명확성 개선)

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

@@ -19,7 +19,7 @@
 | 계층 | 역할 | 금지 사항 |
 |------|------|----------|
 | **router/** | HTTP 요청/응답 처리만 | DB 직접 접근, 비즈니스 로직 |
-| **services/llm/** | 비즈니스 로직 구현 | DB 직접 연결 (state를 통해서만) |
+| **services/** | 비즈니스 로직 구현 | DB 직접 연결 (state를 통해서만) |
 | **state/** | DB CRUD만 | 비즈니스 로직 포함 |
 
 ## 2. 폴더 구조 규칙
@@ -43,7 +43,7 @@
 
 ### 폴더 명명 규칙
 - `router/` 또는 `api/`: HTTP 처리
-- `services/`: 도메인 로직
+- `services/`: 비즈니스 로직
 - `state/` 또는 `repositories/`: Repository 패턴으로 CRUD 캡슐화
 - `models/`: SQLAlchemy 등 ORM 모델
 - `schemas/`: Pydantic 요청/응답 스키마 (models와 분리)
@@ -62,7 +62,7 @@
 
 ### state/ (Repository 패턴)
 - `database.py`: 통합 DB 접근
-- `{도메인}_repository.py`: 도메인별 CRUD 캡슐화 (예: user_repository.py는 User 모델 CRUD만)
+- `{도메인}_repository.py`: 도메인별 CRUD 캡슐화
 
 ### models/
 - `{도메인}_model.py`: ORM 모델 (예: user_model.py, emotion_model.py)
@@ -95,8 +95,8 @@ utils
 
 ### LangGraph 워크플로우
 - **복잡한 다단계 처리**: LangGraph 적극 활용
-- **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트를 두어 부분 재시도 가능하게 구현 (권장)
-- **실험/경량 플로우**: stateless LangGraph도 허용하되, 추후 stateful 전환 여부를 문서나 주석으로 명시
+- **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트 구현 (권장)
+- **실험/경량 플로우**: stateless LangGraph 허용
 
 ### router 계층
 ```python
@@ -152,7 +152,6 @@ async def save_emotion(data: dict):
 from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
 
 async def get_session() -> AsyncSession:
-    # 의존성 주입으로 세션 제공
     pass
 
 # state/database.py: 직접 연결 (간단한 경우)
@@ -164,11 +163,11 @@ async def get_connection():
 - ❌ 프로덕션 router/services에서 직접 asyncpg.connect()
 - ❌ 하드코딩된 DB URL
 - ❌ JSONB 저장 시 dict 직접 전달 (json.dumps() 필수)
-  - 마이그레이션/원샷 스크립트 등 서비스 외부 유틸에서는 직접 연결 허용하되, 프로덕션 요청 경로에서 재사용 금지
+- ❌ 프로덕션 요청 경로에서 직접 DB 연결 재사용
 
 ## 7. 파일 크기 제한
 
-- **한 파일 최대 300줄 권장** (핵심 모듈은 가급적 유지)
+- **한 파일 최대 300줄 권장**
 - 초과 시 기능별 분리
 - 예: `services/email_integration.py` (500줄) → `email_send.py` + `email_fetch.py`
 
@@ -204,8 +203,8 @@ from app.services import coldmail_filter             # ✅ 모듈 import
 
 ### 예외 처리 시
 ```python
-# TODO: 계층 위반 - 리팩토링 필요 (issue #123)
-# 긴급 수정: 2025-10-02, 사유: DB 장애 복구
+# TODO: 계층 위반 - 리팩토링 필요
+# 긴급 수정: 사유 명시
 ```
 
 ## 11. 로깅 원칙