diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md index e3bdcad..5f4e2c5 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-02 (Nginx 타임아웃 설정 확인 필수 원칙 추가) +**수정일**: 2025-12-23 (Supabase 쿼리 컬럼명 충돌 처리 원칙 추가) ## 1. 계층 분리 원칙 @@ -131,11 +131,17 @@ utils - **권장**: `db/database.py`에서 DB 세션 중앙 관리 (의존성 주입) - **간단한 경우**: `state/database.py`에서 직접 연결 +### Supabase 쿼리 컬럼명 충돌 처리 +- **예약어/컬럼명 충돌**: `order` 같은 예약어가 컬럼명과 겹칠 경우 쿼리 체이닝에서 직접 `.order()` 사용 금지 +- **Python 로직 처리**: 컬럼명 충돌 시 Supabase 쿼리 체이닝 대신 Python 로직으로 정렬 처리 (모든 데이터 조회 후 Python에서 정렬) +- **별칭 사용**: 가능한 경우 컬럼명 별칭 사용하여 충돌 회피 + ### 금지 사항 - ❌ 프로덕션 router/services에서 직접 asyncpg.connect() - ❌ 하드코딩된 DB URL - ❌ JSONB 저장 시 dict 직접 전달 (json.dumps() 필수) - ❌ 프로덕션 요청 경로에서 직접 DB 연결 재사용 +- ❌ Supabase 쿼리 체이닝에서 컬럼명과 예약어 충돌 시 직접 사용 (Python 로직으로 처리) ## 6-1. DB 스키마 변경 시 동기화 필수 diff --git a/book/300_architecture/313_React_구조_원칙.md b/book/300_architecture/313_React_구조_원칙.md index e585135..2ef6ce3 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-02 (배열/객체 필드 검증 필수 원칙 추가) +**수정일**: 2025-12-23 (라우팅 원칙, useCallback 무한루프 방지 원칙 추가) **참고**: 311_FastAPI_구조_원칙.md, 312_문서_작성_원칙.md ## 1. 컴포넌트 설계 원칙 @@ -91,6 +91,7 @@ src/ - 의존성 배열 정확히 명시 - 중복 호출 및 무한 루프 방지 - cleanup 함수 적절히 사용 +- **Custom Hook 함수 반환**: custom hook에서 반환하는 함수는 `useCallback`으로 메모이제이션 필수 (의존성 배열에 포함 시 무한 루프 방지) ### 성능 최적화 - 불필요한 리렌더링 방지: `React.memo`, `useMemo`, `useCallback` 적절히 활용 @@ -182,7 +183,14 @@ src/ - [ ] useEffect 의존성이 정확한가? - [ ] JS/CSS 파일 로드 시 버전 파라미터(`?v=YYYYMMDD`) 추가 확인 (캐싱 문제 방지) -## 11. 프론트엔드 캐싱 전략 +## 11. 라우팅 원칙 + +### React Router basename 사용 +- **basename 설정 시**: `BrowserRouter`에 `basename` 설정 후, 모든 `Link` 컴포넌트는 상대 경로만 사용 +- **절대 경로 하드코딩 금지**: `/goosefarm/blog` 같은 절대 경로에 하위 경로를 하드코딩하지 않음 (basename과 중복되어 `/goosefarm/goosefarm/blog` 같은 잘못된 URL 생성) +- **권장**: `Link to="/blog"` (상대 경로), React Router가 basename과 자동 결합 + +## 12. 프론트엔드 캐싱 전략 ### 버전 파라미터 필수 - JS/CSS 파일: `?v=YYYYMMDD` 추가 (예: `app.js?v=20251204`) @@ -192,7 +200,7 @@ src/ - ETag 사용 시 Ctrl+F5로도 캐시 회피 어려움 - 버전 파라미터가 가장 확실한 방법 -## 12. 참고 +## 13. 참고 - 상위 원칙: 이 문서는 일반적인 React 프로젝트 원칙을 다룹니다. - 프로젝트별 특화 규칙: 각 프로젝트의 README나 문서에 추가 규칙 명시