submanager/doc/payment_card_plan.md

결제수단 구분 확장 계획

배경

• 현재 홈 화면은 카테고리별 구독 목록만 제공하며, 결제 카드 기준으로 필터링하거나 시각적으로 구분할 수 없음.
• 사용자 요청: 카드 회사명과 마지막 4자리로 구독을 분류해 데이터/UX 양쪽 모두에서 카드별 인사이트를 제공.

목표

• 구독 데이터를 카드 단위로 매핑할 수 있는 스키마 확장.
• 카드 정보를 한 번만 등록하도록 관리 화면을 제공해 재사용성 확보.
• 홈 화면에서 카테고리/카드 뷰를 토글하며, 헤더·리스트·분석 카드가 카드 정보를 시각적으로 노출.
• 모든 변경은 기존 카테고리 UX를 유지하면서 점진적 도입이 가능해야 함.

작업 체크리스트

1. SubscriptionModel에 paymentCardId 추가, PaymentCardModel/PaymentCardProvider 구현, Hive 등록 및 마이그레이션 수행.
2. 결제수단 관리 화면과 구독 추가/편집/SMS 시트에서 사용할 PaymentCardSelector + “새 카드 추가” 플로우 구현.
3. 홈·리스트 UI에 카테고리/카드 토글, 그룹 헤더, 카드 Chip 표시, SubscriptionGroupingHelper 도입.
4. 구독 상세 화면(헤더, 결제 정보 섹션, 편집 폼)에서 카드 정보 노출 및 수정 기능 연결.
5. SMS 스캔 컨트롤러/리뷰 UI에 카드 추정·선택·저장 로직 추가, 기본값/자동 생성 전략 반영.
6. 분석 화면(파이 차트, 합계 카드, 월별 차트 등)이 카드 필터/데이터에 대응하도록 확장.
7. 설정/내비게이션/로컬라이제이션/접근성 업데이트 및 새 문자열 번역 반영.
8. QA 플로우: flutter pub run build_runner build, scripts/check.sh, 다국어·다크모드·태블릿·알림/백업 테스트 완료.

데이터 모델 및 저장소

• SubscriptionModel에 paymentCardId(필요 시 displayName/닉네임) 필드 추가, Hive 어댑터 재생성. 기존 데이터는 null 기본값으로 역호환.
• 새 PaymentCardModel 작성: id, issuerName(회사명 자유 입력), last4, colorHex, iconName 등을 저장. Hive typeId는 미사용 값을 배정.
• PaymentCardProvider에서 Hive box(payment_cards)를 관리하고 CRUD, 정렬, 기본값 선택 기능 제공.
• main.dart 초기화 시 카드 어댑터 등록 → Provider 주입.
• 구독 저장 로직(SubscriptionProvider.add/update)과 SMS/수동 추가 컨트롤러에서 paymentCardId를 인자로 전달.

카드 정보 입력 UX

• 전용 관리 화면: 설정 > “결제수단 관리” 또는 독립 PaymentCardManagementScreen.
  • 필수 입력: 회사명(자유 텍스트), 마지막 4자리(숫자 4자리), 선택형 색상/아이콘.
  • 리스트 정렬, 편집, 삭제, 기본 카드 지정, 구독 수 연동 배지 표시.
• 컨텍스트 내 빠른 등록: 구독 추가/수정 폼, SMS 스캔 리뷰 화면 등에서 “+ 새 카드” 버튼을 눌렀을 때 시트/모달로 간단 등록 가능.
• 구독 추가/수정 폼에 PaymentCardSelector를 추가:
  • 드롭다운/검색형 목록에 등록된 카드를 노출하고, 최근 사용 카드가 상단에 정렬되도록 UX 최적화.
  • 카드 ID가 비어 있으면 “미지정” 상태로 저장해 기존 UX 유지.
• UX 권장안: 설정 화면에서 카드 풀을 미리 관리하되, 컨텍스트 모달로도 등록할 수 있게 하여 흐름을 끊지 않음. 단순한 “옵션” 스위치에 카드 정보를 묻는 것보다 입력 목적이 명확하고 재사용성이 높음.

홈 화면 및 리스트 UI

• HomeContent를 상태형으로 전환하고 enum SubscriptionGrouping { category, paymentCard }를 유지. 선택 상태는 SharedPreferences 등으로 로컬 저장.
• “내 구독” 헤더 오른쪽에 SegmentedButton/ChoiceChip으로 카테고리↔카드 토글을 제공.
• SubscriptionListWidget을 범용 그룹 리스트로 확장:
  • 그룹 메타데이터(타이틀, 통화 합계, 색상, 서브텍스트)를 받아 헤더 구성.
  • 카드 모드에서는 회사명 + ****1234, 카드 색상 배지, 카드별 통화 합계를 노출.
• 개별 구독 카드(SubscriptionCard) 상단에 결제수단 Chip을 추가해 어떤 카드에 속했는지 즉시 파악 가능.

구독 상세 화면 반영

• DetailScreen 상단 요약 카드에 결제수단 Chip/배지와 카드 색상을 노출.
• “결제 정보” 섹션에 “결제수단” 행을 추가해 회사명 + ****1234, 카드별 메모 등을 보여줌.
• 상세 화면의 편집 아이콘 → 편집 시트로 진입 시 현재 paymentCardId를 기본 선택하여 사용자가 쉽게 변경할 수 있게 함.
• 카드 Chip을 탭하면 카드 관리 화면으로 이동하거나 빠른 편집 시트를 띄워 카드 명칭/색상 수정이 가능하도록 연동.

SMS 스캔 흐름 적용

• SmsScanController가 생성한 임시 구독 모델에도 paymentCardId 필드를 포함.
• 스캔 결과 리뷰 리스트에서 각 구독 옆에 카드 선택 드롭다운을 노출:
  • 기본값은 (1) 동일 발급사를 과거에 사용한 기록이 있으면 해당 카드, (2) 지정된 기본 카드, (3) “미지정” 순으로 결정.
  • 다중 선택을 빠르게 하기 위해 스와이프/컨텍스트 메뉴 대신 인라인 세그먼트나 바텀 시트를 사용.
• “모두 저장” 시 선택된 카드 ID를 SubscriptionProvider.addSubscription 호출에 전달.
• SMS 패턴으로 카드사를 추정할 수 있는 경우(문구에 “KB국민카드 ****1234” 등)라면 자동으로 새 카드 템플릿을 제안하고, 사용자 확인 후 생성하도록 선택지를 제공.

화면/플로우별 변경 영향 (릴리스 전 점검)

홈/목록/위젯

• HomeContent, SubscriptionListWidget, CategoryHeaderWidget, SubscriptionCard, NativeAdWidget 인접 간격 등 모든 위젯이 새로운 그룹 메타데이터를 받아도 레이아웃이 깨지지 않는지 확인.
• 카드 모드에서 스켈레톤/EmptyState/애니메이션이 그대로 작동하는지, 그리고 RefreshIndicator·무한 스크롤이 정상인지 검증.
• 다국어(en/ko/ja/zh)에서 카드명/****1234 조합이 줄바꿈되지 않도록 최소/최대 길이 처리.

구독 추가/편집/상세

• AddSubscriptionController, DetailScreenController의 상태/검증 로직에 paymentCardId가 포함되었는지 확인.
• 저장/취소/변경 이벤트에서 카드 ID가 누락될 경우 기본값 처리.
• 이벤트/할인 섹션, URL 섹션 등 기존 위젯과 상호작용 시 포커스 이동·폼 검증이 동일하게 작동하는지 QA.
• 상세 화면 헤더/폼/아코디언 등 모든 서브 위젯(detail_*)이 카드 배지를 수용하도록 패딩 보정.

SMS 스캔 및 자동 감지

• SmsScanController, SmsScanner, SubscriptionConverter 등 데이터 파이프라인에 카드 메타 추가.
• 스캔 결과 UI(선택 리스트, 확정 다이얼로그, Snackbar)에서 카드가 선택되지 않았을 때 경고/기본값 표시를 명확히 함.
• 자동 감지 카드 생성 로직은 사용자 최종 확인 후만 저장되도록 하고, 잘못된 카드 추론 시 수정 경로를 안내.

분석/대시보드

• AnalysisScreen, SubscriptionPieChartCard, TotalExpenseSummaryCard, MonthlyExpenseChartCard, EventAnalysisCard가 카드 모드 전환에 따른 필터/데이터세트 변경을 감지하는지 확인.
• 향후 카드별 하이라이트를 추가할 경우를 대비해 SubscriptionGroupingHelper 출력 구조가 확장 가능한지 검토.

설정/관리/내비게이션

• SettingsScreen 내 새 “결제수단 관리” 항목 및 PaymentCardManagementScreen이 탐색 스택/앱 잠금 흐름에 맞게 라우팅되는지 확인.
• NavigationProvider 및 FloatingNavigationBar 상태와 충돌하지 않는지 QA.

데이터/싱크/백업

• Hive 박스 버전이 증가한 뒤에도 기존 사용자 데이터(베타/QA) 로딩에 문제가 없는지 실제 마이그레이션 테스트.
• SubscriptionProvider.refreshSubscriptions, notificationProvider, ExchangeRateService 등 구독 컬렉션을 사용하는 모든 클래스에서 paymentCardId를 읽고 무시해도 예외가 발생하지 않는지 확인.
• 테스트 데이터(lib/temp/test_sms_data.dart, demo seed)에도 카드 필드가 포함되었는지 점검.

로컬라이제이션/접근성

• AppLocalizations, intl 메시지에 결제수단 관련 텍스트(“결제수단”, “카드 관리”, 오류 메시지 등)를 추가하고 4개 언어 번역을 준비.
• 스크린리더(VoiceOver/TalkBack)에서 카드 정보가 올바른 순서로 읽히는지, Chip 탭 시 라벨이 명확한지 확인.
• 컬러 배지 대비가 Material 3 접근성 가이드라인(대비 3:1 이상)을 만족하도록 색상 선택 UI/프리셋을 검토.

QA 체크리스트

1. 새 카드 생성 → 구독 추가/편집/상세/SMS 스캔 → 삭제까지 전 과정에서 데이터 일관성 확인.
2. 카드 토글이 유지되는지(앱 재시작 포함) 확인.
3. scripts/check.sh + flutter pub run build_runner build --delete-conflicting-outputs 실행 후 경고 없는지 확인.
4. 다국어·다크모드·태블릿 해상도에서 UI 붕괴 여부 점검.
5. 알림/위젯/백그라운드 서비스(예: 결제 알림)에서 카드 필드 추가로 인한 크래시가 없는지 Crashlytics/디버그 로그 확인.

QA 실행 현황 (2025-11-14)

• ✅ flutter pub run build_runner build --delete-conflicting-outputs
• ✅ scripts/check.sh
• ✅ flutter analyze
• ✅ flutter test

분석 및 향후 확장

• 공통 SubscriptionGroupingHelper를 만들어 카드/카테고리 그룹 데이터를 모두 생성하게 설계하면 MonthlyExpenseChartCard, 파이 차트, 이벤트 카드 등도 카드 필터를 쉽게 지원.
• 초기에는 홈 리스트에만 카드 모드를 적용하고, 이후 분석 탭에 “카드별 지출” 섹션을 추가해 순차 배포.

검증/운영

• 모든 변경 후 scripts/check.sh로 포맷(dart format), 정적 분석(flutter analyze), 테스트(flutter test)를 실행.
• Hive 스키마가 증가하므로 flutter pub run build_runner build --delete-conflicting-outputs를 통해 어댑터 재생성.
• UI 변경 시 기본/카드 모드 스크린샷을 확보해 QA 공유.

리스크 및 완화

• Hive 마이그레이션: 새 필드는 optional로 두고 기본값을 유지해 앱 크래시를 방지. 배포 전 베타 빌드로 데이터 검증.
• 사용자 혼란: 토글 기본값을 기존 “카테고리”로 유지하고, 첫 진입 시 간단한 스낵바/tooltip으로 카드 뷰를 안내.
• 데이터 입력 번거로움: 관리 화면에서 최소 필드만 요구하고, 구독 폼에서 바로 생성할 수 있게 동선 축소.