From 29e2357e6427285422e6510541490a89dbeadb83 Mon Sep 17 00:00:00 2001
From: happybell80 <goeun2dcc@gmail.com>
Date: Thu, 2 Oct 2025 15:21:00 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20FastAPI=20=EA=B5=AC=EC=A1=B0=20?=
 =?UTF-8?q?=EC=9B=90=EC=B9=99=EC=97=90=20=EB=AA=A8=EB=B2=94=20=EC=82=AC?=
 =?UTF-8?q?=EB=A1=80=20=EB=B0=98=EC=98=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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 | 53 ++++++++++++++++---
 1 file changed, 45 insertions(+), 8 deletions(-)

diff --git a/300_architecture/311_FastAPI_구조_원칙.md b/300_architecture/311_FastAPI_구조_원칙.md
index b8fa2a1..f651372 100644
--- a/300_architecture/311_FastAPI_구조_원칙.md
+++ b/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. **관심사 분리**: 요청/비즈니스/데이터 계층 명확한 역할 분담