Merge branch 'main' of https://git.ro-being.com/ivada_Ro-being/DOCS

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 스키마 변경 시 동기화 필수
 

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나 문서에 추가 규칙 명시