Initial commit: SubManager Flutter App

주요 구현 완료 기능: - 구독 관리 (추가/편집/삭제/카테고리 분류) - 이벤트 할인 시스템 (기본값 자동 설정) - SMS 자동 스캔 및 구독 정보 추출 - 알림 시스템 (타임존 처리 안정화) - 환율 변환 지원 (KRW/USD) - 반응형 UI 및 애니메이션 - 다국어 지원 (한국어/영어) 버그 수정: - NotificationService tz.local 초기화 오류 해결 - MainScreenSummaryCard 레이아웃 오버플로우 수정 - 구독 추가 시 LateInitializationError 완전 해결 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-09 14:29:53 +09:00
commit 8619e96739
177 changed files with 23085 additions and 0 deletions
--- a/doc/project_analysis.md
+++ b/doc/project_analysis.md
@@ -0,0 +1,411 @@
+# SubManager 프로젝트 분석
+
+## 1. 개요
+
+### 프로젝트 소개
+SubManager는 포괄적인 구독 서비스 관리를 위해 설계된 정교한 Flutter 기반 모바일 애플리케이션입니다. 이 앱은 사용자가 반복 구독을 추적하고, 지출 패턴을 분석하며, 결제 알림을 받을 수 있도록 하면서, 서버리스 아키텍처를 통해 완전한 프라이버시를 유지합니다.
+
+### 주요 발견사항
+- **아키텍처**: Provider 상태 관리를 사용한 잘 구조화된 MVVM 패턴
+- **기술 스택**: 로컬 저장소로 Hive를 사용하는 현대적인 Flutter 구현
+- **핵심 혁신**: SMS 기반 자동 구독 감지
+- **프라이버시 중심**: 서버 종속성 없이 모든 데이터를 로컬에 저장
+- **플랫폼 지원**: iOS, Android 및 부분적 웹 지원
+- **현지화**: 한국어 및 영어 지원
+
+### 기술적 하이라이트
+- **클린 아키텍처**: 데이터, 비즈니스 로직, 프레젠테이션 계층 간의 명확한 분리
+- **고급 기능**: 생체 인증, 실시간 환율, 자동화된 알림
+- **성능**: Hive를 사용한 효율적인 로컬 저장소, 최적화된 애니메이션
+- **디자인 시스템**: 커스텀 테마와 그라데이션이 적용된 Material 3 구현
+
+## 2. 아키텍처 개요
+
+### 상위 수준 아키텍처 다이어그램
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Presentation Layer                    │
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │
+│  │   Screens   │  │   Widgets    │  │    Theme     │  │
+│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘  │
+└─────────┼─────────────────┼─────────────────┼──────────┘
+          │                 │                 │
+┌─────────┼─────────────────┼─────────────────┼──────────┐
+│         │      State Management Layer       │          │
+│  ┌──────▼──────────────────▼────────────────▼──────┐  │
+│  │              Provider Pattern                    │  │
+│  │  (Subscription, Category, Notification, etc.)   │  │
+│  └──────────────────────┬──────────────────────────┘  │
+└─────────────────────────┼──────────────────────────────┘
+                          │
+┌─────────────────────────┼──────────────────────────────┐
+│                 Business Logic Layer                    │
+│  ┌──────────────┐  ┌───▼────────┐  ┌──────────────┐  │
+│  │   Services   │  │    Utils    │  │    Models    │  │
+│  │ (SMS, Notif) │  │  (Format)   │  │(Subscription)│  │
+│  └──────┬───────┘  └──────┬──────┘  └──────┬───────┘  │
+└─────────┼──────────────────┼────────────────┼──────────┘
+          │                  │                 │
+┌─────────┼──────────────────┼────────────────┼──────────┐
+│         │          Data Layer               │          │
+│  ┌──────▼───────┐  ┌──────▼──────┐  ┌─────▼───────┐  │
+│  │ Local Storage│  │External APIs│  │Platform Chls│  │
+│  │    (Hive)    │  │(Exchange RT)│  │(SMS, Notif) │  │
+│  └──────────────┘  └─────────────┘  └─────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 계층 설명
+
+#### 프레젠테이션 계층
+- **화면**: 앱의 다양한 측면을 관리하는 9개의 개별 화면
+- **위젯**: 일관된 스타일링을 가진 10개 이상의 재사용 가능한 컴포넌트
+- **테마**: 색상, 타이포그래피, 간격이 포함된 중앙화된 디자인 시스템
+
+#### 상태 관리 계층
+- **Provider 패턴**: 다양한 도메인을 관리하는 5개의 전문화된 Provider
+- **반응형 업데이트**: UI 동기화를 위한 ChangeNotifier 패턴
+- **의존성 주입**: 클린 아키텍처를 위한 MultiProvider 설정
+
+#### 비즈니스 로직 계층
+- **서비스**: SMS 스캔, 알림 등을 위한 6개의 전문화된 서비스
+- **유틸**: 포맷팅, 애니메이션, 계산을 위한 헬퍼 함수
+- **모델**: Hive 영속성 지원이 포함된 데이터 구조
+
+#### 데이터 계층
+- **로컬 저장소**: 오프라인 우선 아키텍처를 위한 Hive NoSQL 데이터베이스
+- **외부 API**: 환율 API 통합
+- **플랫폼 채널**: 네이티브 SMS 및 알림 접근
+
+### 데이터 흐름 패턴
+
+1. **사용자 인터랙션 흐름**:
+   ```
+   사용자 액션 → 화면 → Provider → 서비스 → 데이터 계층
+                    ↑                              ↓
+                    └──────── 상태 업데이트 ←───────┘
+   ```
+
+2. **SMS 감지 흐름**:
+   ```
+   SMS 권한 → 플랫폼 채널 → SMS 스캐너 → 패턴 분석
+                                                  ↓
+   UI 업데이트 ← Provider 업데이트 ← 구독 생성 ←─┘
+   ```
+
+3. **알림 흐름**:
+   ```
+   구독 데이터 → 알림 서비스 → 플랫폼 채널
+                        ↓
+              알림 스케줄링 → 시스템 전달
+   ```
+
+## 3. 기능 분석
+
+### 핵심 기능 분해
+
+#### 1. 구독 관리
+- **구현**: Hive 영속성을 사용한 CRUD 작업
+- **주요 컴포넌트**: 
+  - 코드 생성이 포함된 `SubscriptionModel`
+  - 상태 관리를 위한 `SubscriptionProvider`
+  - 표시를 위한 `SubscriptionCard` 위젯
+- **기능**:
+  - 폼 검증을 통한 수동 추가
+  - 편집/삭제 기능
+  - 카테고리 구성
+  - 다중 통화 지원 (KRW/USD)
+
+#### 2. SMS 자동 감지
+- **구현**: 패턴 인식과 함께 플랫폼 채널 통합
+- **주요 컴포넌트**:
+  - 정규식 패턴을 사용하는 `SmsScanner` 서비스
+  - 서비스 식별을 위한 `SubscriptionUrlMatcher`
+  - MethodChannel을 통한 네이티브 Android 구현
+- **알고리즘**:
+  - 서비스명별로 SMS 그룹화
+  - 반복 패턴 식별 (2회 이상 결제)
+  - 금액, 날짜, 서비스 정보 추출
+  - 웹사이트 URL 자동 제안
+
+#### 3. 재무 분석
+- **구현**: 차트 시각화와 함께 실시간 계산
+- **주요 컴포넌트**:
+  - 데이터 시각화를 위한 `fl_chart`
+  - 다중 통화 계산을 위한 `CurrencyUtil`
+  - 실시간 환율을 위한 `ExchangeRateService`
+- **기능**:
+  - 월별 지출 추세 (6개월 기록)
+  - 카테고리별 분포
+  - 총 비용 추적
+  - 통화 변환 표시
+
+#### 4. 알림 시스템
+- **구현**: 시간대 지원이 포함된 로컬 알림
+- **주요 컴포넌트**:
+  - `flutter_local_notifications` 통합
+  - 스케줄링 로직이 포함된 `NotificationService`
+  - 플랫폼별 구성
+- **기능**:
+  - 구성 가능한 알림 시간 (1-3일 전)
+  - 매일 알림 옵션
+  - 사용자 정의 알림 시간
+  - 자동 재스케줄링
+
+#### 5. 보안 기능
+- **구현**: 생체 인증 (현재 비활성화)
+- **주요 컴포넌트**:
+  - `local_auth` 패키지 통합
+  - 민감한 데이터를 위한 `flutter_secure_storage`
+  - 상태 관리를 위한 `AppLockProvider`
+- **상태**: 인프라는 구축되었지만 기능은 비활성화
+
+### 통합 지점
+
+1. **플랫폼 통합**:
+   - MethodChannel을 통한 Android SMS API
+   - iOS/Android 알림 시스템
+   - 생체 인증 API
+   - 파비콘 캐싱을 위한 파일 시스템
+
+2. **외부 서비스**:
+   - USD/KRW 환율을 위한 ExchangeRate-API
+   - 파비콘 서비스 (여러 제공자)
+   - Google Mobile Ads (Android/iOS만)
+
+3. **데이터 동기화**:
+   - Provider 패턴이 UI 일관성 보장
+   - 화면 간 반응형 업데이트
+   - Hive를 통한 영구 저장소
+
+## 4. 기술 세부사항
+
+### 의존성 분석
+
+#### 핵심 의존성
+- **상태 관리**: `provider: ^6.1.1`
+- **로컬 저장소**: `hive: ^2.2.3`, `hive_flutter: ^1.1.0`
+- **UI/UX**: `fl_chart: ^0.66.2`, `font_awesome_flutter: ^10.7.0`
+- **플랫폼 기능**: `local_auth: ^2.1.6`, `telephony: ^0.2.0`
+- **유틸리티**: `intl: ^0.19.0`, `uuid: ^4.2.1`, `timezone: ^0.9.2`
+
+#### 개발 의존성
+- **코드 생성**: `build_runner: ^2.4.6`, `hive_generator: ^2.0.1`
+- **린팅**: `flutter_lints: ^2.0.0`
+
+### 플랫폼 고려사항
+
+#### Android
+- 최소 SDK: Flutter 기본값에 의해 결정
+- 자동 감지를 위한 SMS 권한 필요
+- 네이티브 광고 통합
+- SMS 접근을 위한 MethodChannel
+
+#### iOS
+- iOS 11.0+ (의존성 기반)
+- 알림 권한 필요
+- 생체 인증 지원
+- 네이티브 광고 통합
+
+#### Web (부분 지원)
+- SMS 기능 비활성화
+- 알림 기능 비활성화
+- 대체 파비콘 로딩 전략
+- 네이티브 광고 대신 플레이스홀더 광고
+
+### 성능 고려사항
+
+1. **메모리 관리**:
+   - 파비콘을 위한 효율적인 이미지 캐싱
+   - 구독 목록의 지연 로딩
+   - 애니메이션 컨트롤러의 적절한 해제
+
+2. **저장소 최적화**:
+   - 빠른 로컬 쿼리를 위한 Hive 박스
+   - 선택적 데이터 로딩
+   - 생성된 어댑터를 사용한 효율적인 데이터 모델
+
+3. **UI 성능**:
+   - 적절한 커브를 사용한 부드러운 애니메이션
+   - 스켈레톤 로딩 상태
+   - Provider를 통한 최적화된 재빌드
+
+## 5. 코드 구성
+
+### 디렉터리 구조 분석
+```
+lib/
+├── l10n/               # 현지화 파일
+├── main.dart           # 애플리케이션 진입점
+├── models/             # Hive 어댑터가 포함된 데이터 모델
+├── navigator_key.dart  # 전역 네비게이션
+├── providers/          # 상태 관리 프로바이더
+├── screens/            # UI 화면 (9개 화면)
+├── services/           # 비즈니스 로직 서비스
+├── temp/              # 개발용 테스트 데이터
+├── theme/             # 디자인 시스템 구현
+├── utils/             # 헬퍼 함수
+└── widgets/           # 재사용 가능한 UI 컴포넌트
+```
+
+### 명명 규칙
+- **파일**: snake_case (예: `subscription_card.dart`)
+- **클래스**: PascalCase (예: `SubscriptionProvider`)
+- **변수**: camelCase (예: `monthlyCost`)
+- **상수**: UPPER_SNAKE_CASE 또는 camelCase
+- **비공개 멤버**: 선행 언더스코어 (예: `_isLoading`)
+
+### 사용된 디자인 패턴
+
+1. **MVVM 아키텍처**:
+   - Models: 데이터 구조
+   - View-Models: Provider
+   - Views: 화면 및 위젯
+
+2. **Provider 패턴**:
+   - 상태 관리
+   - 의존성 주입
+   - 반응형 프로그래밍
+
+3. **싱글톤 패턴**:
+   - `ExchangeRateService`
+   - 전역 네비게이션 키
+
+4. **팩토리 패턴**:
+   - 맵에서 모델 생성
+   - 위젯 빌더
+
+5. **옵저버 패턴**:
+   - ChangeNotifier 구현
+   - 스트림 구독
+
+## 6. 권장사항
+
+### 잠재적 개선사항
+
+1. **코드 품질**:
+   - 포괄적인 단위 테스트 추가
+   - 통합 테스트 구현
+   - 코드 문서화 추가
+   - 개발자 README 작성
+
+2. **아키텍처**:
+   - 데이터 접근을 위한 Repository 패턴 고려
+   - 적절한 오류 처리 전략 구현
+   - 로깅/분석 프레임워크 추가
+   - 추상 서비스 인터페이스 생성
+
+3. **기능**:
+   - 앱 잠금 기능 활성화 및 테스트
+   - 데이터 내보내기/가져오기 기능 추가
+   - 구독 공유 기능 구현
+   - 예산 알림 추가
+
+4. **성능**:
+   - 큰 목록을 위한 지연 로딩 구현
+   - SMS 스캔을 위한 페이지네이션 추가
+   - 이미지 로딩 최적화
+   - 상태 영속성 고려
+
+### 보안 고려사항
+
+1. **데이터 보호**:
+   - 앱 잠금 기능 활성화
+   - 민감한 정보에 대한 데이터 암호화 구현
+   - 안전한 백업 기능 추가
+   - 생체 인증을 위한 PIN 폴백 추가 고려
+
+2. **프라이버시**:
+   - SMS 권한 사용 검토
+   - 개인정보 처리방침 화면 추가
+   - 데이터 삭제 옵션 구현
+   - GDPR 준수 기능 추가
+
+3. **API 보안**:
+   - API 키 로테이션 구현
+   - 요청 서명 추가
+   - 인증서 고정 사용
+   - 속도 제한 구현
+
+### 확장성 제안
+
+1. **데이터 관리**:
+   - 오래된 구독에 대한 데이터 아카이빙 구현
+   - 검색 기능 추가
+   - 데이터 마이그레이션 전략 수립
+   - 클라우드 동기화 옵션 고려
+
+2. **기능 확장**:
+   - 가족 공유 추가
+   - 구독 추천 기능 구현
+   - 지출 목표 생성
+   - 영수증 스캔 추가
+
+3. **플랫폼 확장**:
+   - 웹 지원 완성
+   - 데스크톱 애플리케이션 고려
+   - 태블릿 최적화 레이아웃 추가
+   - 워치 앱 컴패니언 구현
+
+## 7. 부록
+
+### 파일 목록 요약
+- **총 Dart 파일**: 50개 이상
+- **화면**: 9개의 주요 화면
+- **위젯**: 10개 이상의 재사용 가능한 컴포넌트
+- **서비스**: 6개의 비즈니스 로직 서비스
+- **프로바이더**: 5개의 상태 관리 프로바이더
+- **모델**: Hive 지원이 포함된 3개의 데이터 모델
+
+### 주요 코드 패턴
+
+#### Provider 설정 예시
+```dart
+final provider = Provider.of<SubscriptionProvider>(context);
+await provider.loadSubscriptions();
+```
+
+#### 서비스 패턴 예시
+```dart
+class ExchangeRateService {
+  static final instance = ExchangeRateService._();
+  Future<double> getExchangeRate() async {...}
+}
+```
+
+#### 모델 패턴 예시
+```dart
+@HiveType(typeId: 0)
+class SubscriptionModel extends HiveObject {
+  @HiveField(0)
+  final String id;
+  // ... 다른 필드
+}
+```
+
+### API/서비스 매핑
+
+1. **외부 API**:
+   - 환율: `https://api.exchangerate-api.com/v4/latest/USD`
+   - 파비콘 서비스: 중복성을 위한 여러 제공자
+
+2. **플랫폼 채널**:
+   - SMS 채널: `com.submanager/sms`
+   - 메서드: `getSmsMessages`, `checkSmsPermission`, `requestSmsPermission`
+
+3. **로컬 저장소 키**:
+   - 구독: `subscriptions` 박스
+   - 카테고리: `categories` 박스
+   - 앱 잠금: `app_lock` 박스
+   - 설정: 보안 저장소의 다양한 키
+
+### 개발 노트
+
+1. **테스트 데이터**: `/lib/temp/test_sms_data.dart`에서 사용 가능
+2. **디버그 모드**: 실제 메시지 대신 테스트 SMS 데이터 사용
+3. **플랫폼 감지**: 웹용 자동 기능 비활성화
+4. **현지화**: 한국어와 영어를 지원하며 쉽게 확장 가능
+
+---
+
+이 분석은 SubManager 프로젝트의 포괄적인 개요를 제공하며, 잘 설계된 아키텍처, 강력한 기능 세트 및 미래 개선 가능성을 강조합니다. 코드베이스는 사용자 경험과 유지보수성에 초점을 맞춘 전문적인 Flutter 개발 관행을 보여줍니다.