docs: FastAPI 구조 원칙에 모범 사례 반영

- models/schemas 분리 명시
- Repository 패턴 CRUD 캡슐화 설명 추가
- DB 세션 중앙화 예시 추가
- API 버전 관리 v1/v2 구조 추가
- 모범 사례 참고 섹션 추가

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

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

@@ -1,7 +1,7 @@
 # FastAPI 프로젝트 구조 원칙
 
 **작성일**: 2025-09-17
-**수정일**: 2025-10-02
+**수정일**: 2025-10-02 (모범 사례 반영)
 
 ## 1. 계층 분리 원칙
 
@@ -30,9 +30,13 @@
 ├── main.py              # 앱 실행, 라우터 등록만
 ├── app/
 │   ├── router/         # HTTP 엔드포인트
+│   │   └── v1/         # API 버전 관리 (선택)
 │   ├── services/       # 비즈니스 로직
-│   ├── state/          # DB 접근
+│   ├── state/          # DB 접근 (Repository 패턴)
+│   ├── models/         # ORM 모델 (DB 테이블 정의)
+│   ├── schemas/        # Pydantic 모델 (API 요청/응답)
 │   ├── core/           # 설정, 공통 기능
+│   ├── db/             # DB 세션 관리 (선택)
 │   └── utils/          # 유틸리티
 └── tests/
 ```
@@ -40,7 +44,10 @@
 ### 폴더 명명 규칙
 - `router/` 또는 `api/`: HTTP 처리
 - `services/`: 도메인 로직
-- `state/` 또는 `repositories/`: 데이터 접근
+- `state/` 또는 `repositories/`: Repository 패턴으로 CRUD 캡슐화
+- `models/`: SQLAlchemy 등 ORM 모델
+- `schemas/`: Pydantic 요청/응답 스키마 (models와 분리)
+- `db/`: DB 엔진/세션 중앙 관리 (선택)
 - 복수형 사용 권장
 
 ## 3. 파일 명명 규칙
@@ -53,19 +60,32 @@
 - `{도메인}_{기능}.py`: coldmail_filter.py, ir_analyzer.py
 - 한 파일 최대 500줄
 
-### state/
+### state/ (Repository 패턴)
 - `database.py`: 통합 DB 접근
-- `{도메인}_repository.py`: 도메인별 분리 시
+- `{도메인}_repository.py`: 도메인별 CRUD 캡슐화 (예: user_repository.py는 User 모델 CRUD만)
+
+### models/
+- `{도메인}_model.py`: ORM 모델 (예: user_model.py, emotion_model.py)
+
+### schemas/
+- `{도메인}_schema.py`: API 입출력 스키마 (예: user_schema.py, emotion_schema.py)
 
 ## 4. 의존성 방향 규칙
 
 ### 단방향 흐름
 ```
-router → services → state
+router → services → state/repositories
   ↓         ↓         ↓
-utils     core     models
+schemas   core     models
+  ↓
+utils
 ```
 
+### 계층 간 데이터 흐름
+- **router**: schemas로 요청/응답 검증
+- **services**: schemas + models 사용 가능
+- **state/repositories**: models만 사용 (DB 접근)
+
 ### 금지 사항
 - ❌ 순환 참조: A imports B, B imports A
 - ❌ 하위가 상위 호출: state가 services 호출
@@ -123,7 +143,14 @@ async def save_emotion(data: dict):
 
 ### 연결 방식
 ```python
-# state/database.py만 DB 연결 가능
+# db/database.py: DB 세션 중앙 관리 (권장)
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+
+async def get_session() -> AsyncSession:
+    # 의존성 주입으로 세션 제공
+    pass
+
+# state/database.py: 직접 연결 (간단한 경우)
 async def get_connection():
     return await asyncpg.connect(os.getenv("DATABASE_URL"))
 ```
@@ -174,3 +201,13 @@ from app.services import coldmail_filter             # ✅ 모듈 import
 # TODO: 계층 위반 - 리팩토링 필요 (issue #123)
 # 긴급 수정: 2025-10-02, 사유: DB 장애 복구
 ```
+
+## 11. 모범 사례 참고
+
+본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다:
+
+1. **models/schemas 분리**: DB 스키마와 API 스펙 독립 관리
+2. **Repository 패턴**: state/repositories에서 CRUD 캡슐화
+3. **DB 세션 중앙화**: db/database.py에서 의존성 주입
+4. **API 버전 관리**: router/v1/, router/v2/ 구조
+5. **관심사 분리**: 요청/비즈니스/데이터 계층 명확한 역할 분담