zellyy-finance/docs/03_개발_단계/개발_가이드라인.md

Zellyy Finance 개발 가이드라인

1. 코드 작성 원칙

• 모든 컴포넌트는 함수형 컴포넌트로 작성할 것
• Hook 명명 규칙은 'use'로 시작하는 camelCase 사용할 것
• 비즈니스 로직은 훅으로 분리하여 재사용성 높일 것
• 주석은 한국어로 작성하여 가독성 높일 것
• prop 타입은 모두 TypeScript 인터페이스로 정의할 것

2. 트랜잭션 삭제 안전성

• 트랜잭션 삭제 작업은 UI 스레드를 차단하지 않도록 비동기로 처리할 것
• 상태 업데이트 전/후에 try-catch 블록으로 오류 처리할 것
• 가능한 requestAnimationFrame 또는 queueMicrotask를 사용하여 UI 업데이트 최적화할 것
• 컴포넌트 언마운트 상태를 추적하여 메모리 누수 방지할 것
• 이벤트 핸들러는 성능 병목 지점이 될 수 있으므로 디바운스/스로틀링 적용할 것

3. Supabase 통합 원칙

• Supabase 클라이언트는 앱 시작 시 한 번만 초기화하여 전역적으로 사용합니다.
• 데이터 조회 및 변경은 Supabase 클라이언트 라이브러리가 제공하는 메서드를 사용합니다.
• 실시간 데이터 동기화가 필요한 경우, Supabase의 실시간 구독(Realtime Subscriptions) 기능을 활용합니다.
• 복잡한 데이터베이스 로직은 Supabase의 RPC(Remote Procedure Call)를 통해 처리하는 것을 권장합니다.
• 모든 Supabase API 호출에는 적절한 오류 처리 및 사용자 피드백 로직을 포함해야 합니다.
• 네트워크 불안정성에 대비하여 Supabase 클라이언트 라이브러리의 내장된 재연결 로직을 신뢰하고, 필요한 경우 추가적인 재시도 로직을 구현합니다.

4. 상태 관리 최적화

• 컴포넌트 간 상태 공유는 Context API나 상태 관리 라이브러리 사용할 것
• 큰 상태 객체는 여러 작은 조각으로 분리하여 불필요한 리렌더링 방지할 것
• 불변성을 유지하여 React의 상태 업데이트 최적화 활용할 것
• useCallback, useMemo를 적극 활용하여 함수와 값 메모이제이션할 것
• 기본 데이터 로딩은 상위 컴포넌트에서 처리하고 하위 컴포넌트로 전달할 것

5. 디버깅 및 로깅

• 중요 작업(특히 트랜잭션 삭제와 같은 위험 작업)은 상세한 로그 남길 것
• 개발 모드에서는 상태 변화를 추적할 수 있는 로그 포함할 것
• 사용자에게 영향을 주는 오류는 UI 피드백(토스트 등)으로 표시할 것
• 백그라운드 작업 실패는 적절히 로깅하고 필요시 재시도 메커니즘 구현할 것

6. iOS 지원

• iOS 안전 영역(Safe Area) 고려한 UI 레이아웃 설계
• iOS 특유의 제스처와 상호작용 패턴 지원 (스와이프, 핀치 등)
• iOS 다크 모드 대응을 위한 동적 색상 시스템 활용
• iOS 기기별 화면 크기 및 노치(Notch) 대응
• iOS 앱 배포 시 필요한 인증서 및 프로비저닝 프로파일 관리

7. Android 지원

• BuildInfo와 같은 네이티브 플러그인은 반드시 MainActivity에 등록할 것
• 안드로이드 빌드 정보는 Capacitor 플러그인을 통해 JS로 전달할 것
• 플러그인 호출 시 항상 오류 처리 로직 포함할 것
• 네이티브 기능 실패 시 대체 방법(fallback) 제공할 것
• 안드로이드 버전별 호환성 고려 (API 레벨 차이)
• 다양한 화면 크기 및 해상도 대응 (태블릿 포함)
• 안드로이드 백 버튼 처리 및 생명주기 관리
• 권한 요청 및 처리 로직 구현
• 안드로이드 알림 채널 설정 및 관리

8. 버전 관리

• 모든 빌드는 자동으로 빌드 번호가 증가되도록 설정할 것
• 릴리즈 빌드는 versionCode와 buildNumber 모두 증가할 것
• 디버그 빌드는 buildNumber만 증가할 것
• 버전 정보는 항상 설정 페이지에 표시하여 사용자와 개발자가 확인 가능하게 할 것