submanager/doc/project_analysis.md

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 설정 예시

final provider = Provider.of<SubscriptionProvider>(context);
await provider.loadSubscriptions();

서비스 패턴 예시

class ExchangeRateService {
  static final instance = ExchangeRateService._();
  Future<double> getExchangeRate() async {...}
}

모델 패턴 예시

@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 개발 관행을 보여줍니다.