Migrate from Supabase to Appwrite with core functionality and UI components

This commit is contained in:
hansoo
2025-05-05 08:58:27 +09:00
parent fdfdf15166
commit f83bb384af
79 changed files with 2373 additions and 199 deletions

View File

@@ -0,0 +1,276 @@
# Appwrite 전환 가이드
## 개요
Zellyy Finance는 백엔드 서비스를 Supabase에서 Appwrite로 전환합니다. 이 문서는 전환 과정과 새로운 코드 구조에 대한 가이드를 제공합니다.
## 전환 이유
1. **더 나은 성능**: Appwrite는 경량화된 서비스로 더 빠른 응답 시간 제공
2. **확장성**: 사용자 증가에 따른 확장성 개선
3. **기능 세트**: Appwrite의 실시간 데이터베이스와 인증 시스템 활용
4. **유지보수 용이성**: 단일 백엔드 서비스로 통합하여 유지보수 간소화
## 코드 구조
```
src/
├── lib/
│ ├── appwrite/ (Appwrite 서비스)
│ │ ├── index.ts (단일 진입점)
│ │ ├── client.ts (클라이언트 설정)
│ │ ├── config.ts (환경 설정)
│ │ └── setup.ts (데이터베이스 설정)
│ └── capacitor/ (네이티브 기능)
│ ├── index.ts (단일 진입점)
│ ├── buildInfo.ts (빌드 정보 관련)
│ ├── notification.ts (알림 관련)
│ └── permissions.ts (권한 관련)
├── hooks/
│ ├── auth/
│ │ └── useAppwriteAuth.ts (인증 관련 훅)
│ └── transactions/
│ └── useAppwriteTransactions.ts (트랜잭션 관련 훅)
├── components/
│ ├── auth/
│ │ └── AppwriteConnectionStatus.tsx (연결 상태 표시)
│ ├── migration/
│ │ └── SupabaseToAppwriteMigration.tsx (마이그레이션 도구)
│ └── native/
│ ├── PermissionRequest.tsx (권한 요청 UI)
│ └── NotificationSettings.tsx (알림 설정 UI)
└── utils/
└── appwriteTransactionUtils.ts (트랜잭션 유틸리티)
```
## 환경 설정
`.env` 파일에 다음 환경 변수를 설정합니다:
```
# Appwrite 설정
VITE_APPWRITE_ENDPOINT=https://a11.ism.kr/v1
VITE_APPWRITE_PROJECT_ID=zellyy-finance
VITE_APPWRITE_DATABASE_ID=zellyy-finance
VITE_APPWRITE_TRANSACTIONS_COLLECTION_ID=transactions
# 네이티브 설정
VITE_ANDROID_MIN_API_LEVEL=21
VITE_ANDROID_TARGET_API_LEVEL=33
VITE_ANDROID_NOTIFICATION_CHANNEL_ID=zellyy_finance_notifications
```
## 마이그레이션 단계
1. **데이터베이스 설정**
- Appwrite 데이터베이스 및 컬렉션 생성
- 필요한 인덱스 및 권한 설정
2. **인증 시스템 전환**
- Appwrite 인증 시스템 설정
- 사용자 계정 마이그레이션
3. **데이터 마이그레이션**
- 트랜잭션 데이터 마이그레이션
- 데이터 무결성 검증
4. **Supabase 코드 제거**
- 마이그레이션 완료 후 Supabase 관련 코드 제거
- 환경 변수 정리
## 주요 컴포넌트 및 훅
### 1. Appwrite 클라이언트 설정
```typescript
// src/lib/appwrite/client.ts
import { Client, Account, Databases, Storage } from 'appwrite';
import { config } from './config';
// 클라이언트 초기화
export const client = new Client()
.setEndpoint(config.endpoint)
.setProject(config.projectId);
// 서비스 초기화
export const account = new Account(client);
export const databases = new Databases(client);
export const storage = new Storage(client);
```
### 2. 인증 훅
```typescript
// src/hooks/auth/useAppwriteAuth.ts
import { useState, useEffect } from 'react';
import { account } from '../../lib/appwrite';
export const useAppwriteAuth = () => {
const [user, setUser] = useState(null);
const [loading, setLoading] = useState(true);
// 사용자 세션 확인
useEffect(() => {
const checkSession = async () => {
try {
const session = await account.getSession('current');
if (session) {
const currentUser = await account.get();
setUser(currentUser);
}
} catch (error) {
console.error('세션 확인 오류:', error);
} finally {
setLoading(false);
}
};
checkSession();
}, []);
// 로그인 함수
const login = async (email, password) => {
try {
await account.createEmailSession(email, password);
const currentUser = await account.get();
setUser(currentUser);
return { success: true };
} catch (error) {
console.error('로그인 오류:', error);
return { success: false, error };
}
};
// 로그아웃 함수
const logout = async () => {
try {
await account.deleteSession('current');
setUser(null);
return { success: true };
} catch (error) {
console.error('로그아웃 오류:', error);
return { success: false, error };
}
};
return { user, loading, login, logout };
};
```
### 3. 트랜잭션 훅
```typescript
// src/hooks/transactions/useAppwriteTransactions.ts
import { useState, useEffect, useCallback } from 'react';
import { databases } from '../../lib/appwrite';
import { config } from '../../lib/appwrite/config';
import { Query } from 'appwrite';
export const useAppwriteTransactions = (userId) => {
const [transactions, setTransactions] = useState([]);
const [loading, setLoading] = useState(true);
// 트랜잭션 불러오기
const fetchTransactions = useCallback(async () => {
if (!userId) return;
try {
setLoading(true);
const response = await databases.listDocuments(
config.databaseId,
config.transactionsCollectionId,
[Query.equal('userId', userId)]
);
setTransactions(response.documents);
} catch (error) {
console.error('트랜잭션 불러오기 오류:', error);
} finally {
setLoading(false);
}
}, [userId]);
// 초기 데이터 로드
useEffect(() => {
fetchTransactions();
}, [fetchTransactions]);
// 트랜잭션 추가
const addTransaction = async (transaction) => {
try {
const newTransaction = await databases.createDocument(
config.databaseId,
config.transactionsCollectionId,
'unique()',
{
...transaction,
userId,
createdAt: new Date().toISOString(),
}
);
setTransactions((prev) => [...prev, newTransaction]);
return { success: true, transaction: newTransaction };
} catch (error) {
console.error('트랜잭션 추가 오류:', error);
return { success: false, error };
}
};
// 트랜잭션 업데이트
const updateTransaction = async (id, data) => {
try {
const updatedTransaction = await databases.updateDocument(
config.databaseId,
config.transactionsCollectionId,
id,
data
);
setTransactions((prev) =>
prev.map((t) => (t.$id === id ? updatedTransaction : t))
);
return { success: true, transaction: updatedTransaction };
} catch (error) {
console.error('트랜잭션 업데이트 오류:', error);
return { success: false, error };
}
};
// 트랜잭션 삭제
const deleteTransaction = async (id) => {
try {
await databases.deleteDocument(
config.databaseId,
config.transactionsCollectionId,
id
);
setTransactions((prev) => prev.filter((t) => t.$id !== id));
return { success: true };
} catch (error) {
console.error('트랜잭션 삭제 오류:', error);
return { success: false, error };
}
};
return {
transactions,
loading,
fetchTransactions,
addTransaction,
updateTransaction,
deleteTransaction,
};
};
```
## 마이그레이션 도구 사용법
1. 설정 페이지에서 "Appwrite 설정" 메뉴 선택
2. "Supabase에서 Appwrite로 마이그레이션" 섹션에서 "마이그레이션 시작" 버튼 클릭
3. 마이그레이션 진행 상황 확인
4. 완료 후 데이터 검증
## 주의사항
1. 마이그레이션 중에는 데이터 변경을 최소화하세요.
2. 마이그레이션 전에 데이터 백업을 수행하세요.
3. 마이그레이션 후 모든 기능이 정상 작동하는지 테스트하세요.
4. 문제 발생 시 개발팀에 즉시 보고하세요.

View File

@@ -0,0 +1,59 @@
# Zellyy Finance 개발 가이드라인
## 1. 코드 작성 원칙
- 모든 컴포넌트는 함수형 컴포넌트로 작성할 것
- Hook 명명 규칙은 'use'로 시작하는 camelCase 사용할 것
- 비즈니스 로직은 훅으로 분리하여 재사용성 높일 것
- 주석은 한국어로 작성하여 가독성 높일 것
- prop 타입은 모두 TypeScript 인터페이스로 정의할 것
## 2. 트랜잭션 삭제 안전성
- 트랜잭션 삭제 작업은 UI 스레드를 차단하지 않도록 비동기로 처리할 것
- 상태 업데이트 전/후에 try-catch 블록으로 오류 처리할 것
- 가능한 requestAnimationFrame 또는 queueMicrotask를 사용하여 UI 업데이트 최적화할 것
- 컴포넌트 언마운트 상태를 추적하여 메모리 누수 방지할 것
- 이벤트 핸들러는 성능 병목 지점이 될 수 있으므로 디바운스/스로틀링 적용할 것
## 3. Appwrite 통합 원칙
- Appwrite 클라이언트는 앱 시작 시 한 번만 초기화
- 인증 및 데이터 동기화는 전용 훅 사용
- 오류 처리 및 사용자 피드백 제공
- 트랜잭션 작업은 비동기로 처리
- 네트워크 오류 시 적절한 재시도 메커니즘 구현
## 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만 증가할 것
- 버전 정보는 항상 설정 페이지에 표시하여 사용자와 개발자가 확인 가능하게 할 것

View File

@@ -1,141 +1,59 @@
# 적자 탈출 가계부 프로젝트 문서
# Zellyy Finance 프로젝트 문서
이 디렉토리는 적자 탈출 가계부 프로젝트의 모든 문서를 체계적으로 정리한 곳입니다. 사용자들이 개인 재정을 효과적으로 관리하고 적자 상태에서 벗어날 수 있도록 도와주는 모바일 앱 개발 프로젝트입니다.
이 디렉토리는 Zellyy Finance 프로젝트의 모든 문서를 체계적으로 정리한 곳입니다. 사용자들이 개인 재정을 효과적으로 관리하고 적자 상태에서 벗어날 수 있도록 도와주는 모바일 앱입니다.
## 프로젝트 개요
'적자 탈출 가계부'는 단순한 수입/지출 기록을 넘어, 사용자의 소비 패턴을 분석하고 맞춤형 절약 전략을 제안하여 재정 건전성을 개선하는 데 중점을 둔 모바일 앱입니다. AI 기술을 활용한 개인화된 재정 관리 경험을 제공하고, 궁극적으로는 사용자들의 재정적 웰빙을 향상시키는 것을 목표로 합니다.
'Zellyy Finance'는 단순한 수입/지출 기록을 넘어, 사용자의 소비 패턴을 분석하고 맞춤형 절약 전략을 제안하여 재정 건전성을 개선하는 데 중점을 둔 모바일 앱입니다. Appwrite 백엔드를 활용하여 안정적인 데이터 관리와 인증 시스템을 제공합니다.
## 폴더 구조
### 00_프로젝트_개요
프로젝트의 기본 개요와 목표, 사용자 정의에 관한 문서가 포함되어 있습니다.
- `01_프로젝트_소개.md` - 프로젝트 개요 및 주요 기능 설명
- `02_핵심_문제_정의.md` - 해결하고자 하는 문제 정의 (예정)
- `03_사용자_페르소나.md` - 타겟 사용자 프로필 (예정)
- `04_사용자_스토리.md` - 사용자 관점의 요구사항 (예정)
- `05_비즈니스_모델.md` - 수익 모델 및 사업화 전략 (예정)
- `06_법률_규제_검토.md` - 금융 앱 관련 법규 및 규제 검토 (예정)
- `프로젝트_소개.md` - 프로젝트 개요 및 주요 기능 설명
- `핵심_문제_정의.md` - 해결하고자 하는 문제 정의
- `사용자_페르소나.md` - 타겟 사용자 프로필
### 01_기획_및_설계
프로젝트의 기획 및 UI/UX 설계에 관한 문서가 포함되어 있습니다.
- `01_요구사항_분석.md` - 사용자 요구사항 및 기능적/비기능적 요구사항 분석
- `02_MVP_기능_목록.md` - 최소 기능 제품(MVP)의 기능 목록 (예정)
- `03_주요_사용_시나리오.md` - 주요 사용 사례 시나리오 (예정)
- `04_UI_와이어프레임.md` - 핵심 화면 와이어프레임 (예정)
- `05_사용자_여정_맵.md` - 사용자 경험 흐름도 (예정)
- `06_정보_아키텍처.md` - 앱 구조 및 화면 흐름도 (예정)
- `요구사항_분석.md` - 사용자 요구사항 및 기능적/비기능적 요구사항 분석
- `UI_와이어프레임.md` - 핵심 화면 와이어프레임
- `사용자_경험_전략.md` - 사용자 경험 설계 전략
### 02_기술_문서
프로젝트의 기술적 구현에 관한 문서가 포함되어 있습니다.
- `01_시스템_아키텍처.md` - 시스템 아키텍처 설계 문서
- `02_데이터_모델_설계.md` - 데이터 모델 설계 문서 (예정)
- `03_API_명세서.md` - API 엔드포인트 명세 (예정)
- `04_보안_설계.md` - 보안 및 개인정보 보호 설계 (예정)
- `05_성능_최적화_전략.md` - 앱 성능 최적화 전략 (예정)
- `06_CI_CD_파이프라인.md` - 지속적 통합/배포 전략 (예정)
- `07_AI_ML_구현_전략.md` - AI 기반 소비 패턴 분석 구현 방법 (예정)
- `시스템_아키텍처.md` - 시스템 아키텍처 설계 문서
- `데이터_모델_설계.md` - 데이터베이스 스키마 및 모델 설계
- `Appwrite_전환_가이드.md` - Supabase에서 Appwrite로의 전환 가이드
### 03_개발_단계
프로젝트 개발 단계별 문서가 포함되어 있습니다.
- `01_개발_로드맵.md` - 전체 개발 로드맵 및 일정
- `02_1단계_개발_계획.md` - 1단계(MVP) 개발 상세 계획 (예정)
- `03_테스트_전략.md` - 테스트 방법론 및 계획 (예정)
- `04_배포_전략.md` - 배포 및 운영 계획 (예정)
- `05_품질_보증_계획.md` - QA 전략 및 테스트 케이스 (예정)
- `06_유지보수_전략.md` - 출시 후 유지보수 및 업데이트 계획 (예정)
개발 과정과 관련된 문서가 포함되어 있습니다.
- `개발_가이드라인.md` - 코드 작성 원칙, iOS/Android 지원, Appwrite 통합 등에 관한 가이드라인
### 04_디자인_가이드
UI/UX 디자인 관련 문서가 포함되어 있습니다.
- `01_디자인_시스템.md` - 디자인 언어 및 컴포넌트 정의 (예정)
- `02_색상_팔레트.md` - 앱 색상 가이드라인 (예정)
- `03_타이포그래피.md` - 폰트 및 텍스트 스타일 가이드 (예정)
- `04_아이콘_및_이미지.md` - 아이콘 디자인 및 사용 가이드 (예정)
- `05_애니메이션_가이드.md` - UI 애니메이션 및 트랜지션 (예정)
- `06_접근성_지침.md` - 접근성 디자인 원칙 (예정)
### archive
더 이상 활발하게 사용되지 않는 레거시 문서들이 보관되어 있습니다.
- `Supabase 관련 문서` - 이전에 사용하던 Supabase 관련 설정 및 가이드
- `개발 단계별 문서` - 이전 개발 단계의 계획 및 산출물 요약
### 05_프로젝트_관리
프로젝트 관리 및 협업 관련 문서가 포함되어 있습니다.
- `01_팀_구성.md` - 팀 구성원 및 역할 정의 (예정)
- `02_의사결정_프로세스.md` - 프로젝트 의사결정 체계 (예정)
- `03_커뮤니케이션_계획.md` - 팀 내 소통 방식 및 도구 (예정)
- `04_일정_및_마일스톤.md` - 주요 마일스톤 및 납기일 (예정)
- `05_위험_관리.md` - 잠재적 위험 요소 및 대응 계획 (예정)
## 주요 기술 스택
### 06_참고자료
프로젝트 진행에 참고할 수 있는 자료들이 포함되어 있습니다.
- `01_시장_조사_보고서.md` - 가계부 앱 시장 조사 보고서
- `02_경쟁사_분석.md` - 주요 경쟁 앱 상세 분석 (예정)
- `03_사용자_인터뷰.md` - 잠재 사용자 인터뷰 결과 (예정)
- `04_참고_리소스.md` - 유용한 참고 자료 및 링크 (예정)
- `05_금융_데이터_소스.md` - 재정 관리 데이터 참고 자료 (예정)
- `06_관련_연구_자료.md` - 소비 행동 및 금융 심리학 연구 (예정)
- **프론트엔드**: React Native, TypeScript
- **백엔드**: Appwrite
- **상태 관리**: Context API
- **UI 컴포넌트**: Lovable UI
- **네이티브 통합**: Capacitor
### 07_마케팅_및_성장
마케팅 및 사용자 확보 전략 관련 문서가 포함되어 있습니다.
- `01_마케팅_전략.md` - 출시 및 사용자 확보 전략 (예정)
- `02_ASO_전략.md` - 앱 스토어 최적화 전략 (예정)
- `03_콘텐츠_전략.md` - 콘텐츠 마케팅 계획 (예정)
- `04_사용자_유지_전략.md` - 사용자 참여 및 유지 방안 (예정)
- `05_파트너십_계획.md` - 잠재적 파트너십 및 협업 기회 (예정)
## 개발 가이드라인
## 주요 기능
개발 가이드라인은 [03_개발_단계/개발_가이드라인.md](./03_개발_단계/개발_가이드라인.md) 문서를 참조하세요. 이 문서에는 다음 내용이 포함되어 있습니다:
1. **수입/지출 기록**: 간편한 UI로 일상 재정 활동 기록
2. **카테고리 관리**: 사용자 정의 카테고리로 지출 분류
3. **예산 설정**: 카테고리별 월간/주간 예산 설정 및 알림
4. **지출 분석**: 차트와 그래프로 소비 패턴 시각
5. **AI 기반 분석**: 소비 패턴 분석 및 맞춤형 절약 제안
6. **절약 챌린지**: 사용자 맞춤형 절약 목표 설정 및 달성 보상
7. **재정 건강 점수**: 사용자의 재정 상태를 점수화하여 개선 동기 부여
8. **구독 관리**: 정기 구독 서비스 추적 및 최적화 제안
9. **재정 목표 설정**: 단기/중기/장기 저축 목표 설정 및 진행 상황 추적
10. **알림 시스템**: 예산 초과, 주요 지출, 절약 기회에 대한 스마트 알림
11. **가계부 보고서**: 정기적인 재정 상태 요약 보고서 제공
12. **공유 기능**: 가족 또는 파트너와 특정 재정 정보 공유
1. 코드 작성 원칙
2. 트랜잭션 삭제 안전성
3. Appwrite 통합 원칙
4. 상태 관리 최적
5. iOS/Android 지원
6. 디버깅 및 로깅
## 기술 스택
## Appwrite 전환
- **프론트엔드**: React, Vite, Tailwind CSS, Capacitor
- **백엔드**: Node.js, Express, Supabase(PostgreSQL)
- **AI/ML**: TensorFlow, Python
- **클라우드**: Supabase On-Premise
- **데이터 시각화**: D3.js, Chart.js
- **인증/보안**: JWT, OAuth 2.0, 데이터 암호화
- **테스트**: Jest, Cypress
- **CI/CD**: GitHub Actions
- **분석**: Supabase Analytics
## 문서 작성 가이드라인
- 모든 문서는 마크다운(.md) 형식으로 작성합니다.
- 파일명은 내용을 명확히 나타내는 한글 또는 영문으로 작성합니다.
- 이미지나 다이어그램은 가능한 마크다운 내에 포함시킵니다.
- 문서 간 연결이 필요한 경우 상대 경로를 사용하여 링크합니다.
- 코드 예시는 적절한 구문 강조와 함께 코드 블록으로 포함합니다.
- 변경 사항은 문서 하단의 업데이트 이력에 기록합니다.
- 중요 결정사항은 의사결정 배경과 함께 기록합니다.
## 개발 워크플로우
1. **기능 기획**: 사용자 스토리 및 요구사항 정의
2. **설계**: UI/UX 디자인 및 기술 아키텍처 설계
3. **개발**: 기능 구현 및 단위 테스트
4. **코드 리뷰**: 팀원 간 코드 품질 검토
5. **테스트**: QA 및 사용성 테스트
6. **배포**: 스테이징 및 프로덕션 환경 배포
7. **모니터링**: 성능 및 사용자 피드백 모니터링
8. **반복**: 피드백을 바탕으로 기능 개선
## 출시 계획
- **알파 버전**: 내부 테스트 (2024년 4월 초)
- **베타 버전**: 제한적 사용자 테스트 (2024년 4월 중순)
- **MVP 출시**: 앱스토어 및 플레이스토어 공개 (2024년 4월 말)
- **기능 업데이트**: 사용자 피드백 기반 주요 기능 추가 (2024년 5월 초)
- **확장 계획**: 웹 버전 및 추가 기능 확장 (2024년 5월 중순부터)
## 업데이트 이력
- 2024-03-15: 프로젝트 문서 초기 구성 완료
- 2024-03-15: 프로젝트 소개, 요구사항 분석, 시스템 아키텍처, 개발 로드맵, 시장 조사 보고서 추가
- 2024-04-01: 폴더 구조 개선 및 추가 섹션(디자인 가이드, 프로젝트 관리, 마케팅) 추가
- 2024-04-05: 일정 조정 - 모든 개발 계획을 4월 말까지 완료하도록 수정
- 2025-03-09: 개발 방법 변경 - Flutter에서 React, Tailwind CSS, Capacitor 기반 웹 앱으로 전환, Lovable UI 컴포넌트 스타일 적용
- 2025-03-09: 데이터베이스 변경 - MongoDB에서 Supabase(PostgreSQL) On-Premise로 전환
Supabase에서 Appwrite로의 전환에 관한 상세 정보는 [02_기술_문서/Appwrite_전환_가이드.md](./02_기술_문서/Appwrite_전환_가이드.md) 문서를 참조하세요.