submanager/doc/plan.md

SubManager UI 리디자인/리팩터링 계획 (flutter-shadcn-ui 기반)

개요

• 목적: 앱 전반 UI를 flutter-shadcn-ui로 표준화하고, 라이트/다크 테마와 의미 있는 컬러 체계를 구축. 사용하지 않는 코드/파일 정리, 복잡한 알고리즘을 동등 효과의 단순한 구현으로 교체.
• 원칙: 색채심리학/게슈탈트 심리학/피츠의 법칙/마이크로인터랙션을 반영. 화면 간 일관성 유지. 사이드 이펙트 최소화(동작/데이터 모델 변경 없이 UI 중심).
• 범위: lib/screens, lib/widgets, lib/theme 전반. 일부 services/* 단순화 대상 포함(동일 기능 유지).

사전 승인 필요(착수 전)

1. 의존성 추가: flutter_shadcn_ui (pubspec.yaml).
2. 테마 구조 재구성: 기존 app_theme.dart, app_colors.dart → shadcn 토큰/스케일 중심으로 정리.
3. 불용 파일 삭제: 기존 커스텀 위젯·스타일(예: 글라스모피즘 계열 등) 제거.
4. 점진적 마이그레이션 방식 선택(권장) 또는 일괄 치환(위험도 높음).

접근 전략(옵션)

• 옵션 A: 점진적 이행(권장)
  1단계 토대(테마/토큰/기본 컴포넌트) → 2단계 주요 화면 치환 → 3단계 잔여 위젯/정리. 리스크 낮고 롤백 용이.
• 옵션 B: 일괄 치환
  모든 화면/컴포넌트를 한 번에 교체. 속도는 빠르나 충돌/리스크 큼. 권장하지 않음.

이 계획서는 옵션 A를 기준으로 작성합니다.

테마·컬러 설계

• 토큰: primary, secondary, success, warning, danger, info, background, foreground, muted, accent, border, card, popover, ring, overlay.
• 라이트/다크 지원: 동일 의미 색상(semantics)을 양 테마에 매핑. 최소 WCAG 4.5:1 대비.
• 색채심리학 반영(과장 금지, 절제된 사용):
  • info: 블루(신뢰/안정),
  • success: 그린(완료/안도),
  • warning: 앰버(주의 환기),
  • danger: 레드(중단/삭제),
  • neutral: 슬레이트/징크 계열(콘텐츠 중심).
• 게슈탈트: 시각적 그룹화(카드/섹션/간격 체계), 시선 흐름(타이포·계층), 근접성·유사성 활용.
• 피츠의 법칙: 주요 액션 버튼 터치 타깃 ≥ 44dp, 간격 여유.
• 마이크로인터랙션: 진입/전환 120–200ms, 물리 기반 커브, Reduced Motion 설정 반영(utils/reduce_motion.dart 유지/연동).

구현 포인트(코드 단계에서 적용):

• ShadcnTheme 확장 혹은 테마 브리지 레이어 생성(예: lib/theme/shadcn_theme.dart) 후 기존 ThemeData와 연결.
• TextTheme/ColorScheme를 shadcn 토큰으로 역매핑해 타 3rd-party 위젯과도 일관성 유지.

컴포넌트 매핑(현행 → shadcn)

• 버튼: common/buttons/(primary|secondary)_button.dart → Button(variant: primary/secondary)
• 카드: 다수의 카드형 위젯 → Card + CardHeader/Content/Footer
• 다이얼로그: dialogs/* → Dialog/AlertDialog + 의미 색상(위험=red)
• 스낵바: app_snackbar.dart → Toast 또는 Inline Alert(상황별)
• 입력: base_text_field.dart, currency_input_field.dart, date_picker_field.dart, selector류 → Input, Select, Popover+Calendar(날짜)
• 네비게이션: floating_navigation_bar.dart → shadcn 스타일 버튼/탭/세그먼트 조합(기능은 Navigator 유지)
• 리스트/아이템: subscription_*_card(_widget).dart → Card+List 조합, 의미 색상 배지 사용
• 배지/상태: analysis_badge.dart → Badge(success/warning/info)

차트는 기존 라이브러리 유지, Card/토큰 색상만 적용.

화면별 리디자인 가이드

• 메인(main_screen.dart): 상단 요약(카드), 탭형 네비게이션, FAB 대신 우선작업 배치(피츠 법칙 반영).
• 구독 추가(add_subscription_screen.dart): 단계적 폼(섹션 카드), 필수/보조 액션 분리, 에러/힌트 색상 표준화.
• 상세(detail_screen.dart): 정보/행동 분리, 위험 액션은 danger 톤, url 영역은 info 톤.
• 분석(analysis_screen.dart): KPI 카드 3열(태블릿), 1열(폰), 차트 색상은 의미 기반 팔레트.
• 카테고리 관리(category_management_screen.dart): 리스트+인라인 편집, 확인/취소 분리, 경고 색상 남용 금지.
• 설정(settings_screen.dart): 토글/셀리스트 일관, 테마 전환 즉시 반영, 접근성 강조.
• SMS 권한(sms_permission_screen.dart): 단일 초점 화면, primary 호출-행동 버튼 + 보조 링크.
• 스플래시/잠금: 단순한 브랜드/배경, 과도한 애니메이션 제거.

정리/삭제 대상(마이그레이션 완료 후)

• 강한 시각효과 위젯: animated_wave_background.dart, glassmorphism_card.dart, glassmorphic_scaffold.dart 등
• 중복/대체 가능: 커스텀 버튼/카드/스낵바/다이얼로그 구현체(치환 완료 후)
• 사용되지 않는 유틸: 실사용 참조 0인 파일 전부
• 임시/백업: 오래된 백업/실험 파일

삭제는 단계별 PR에서 “치환 완료 확인 → 삭제” 순으로 안전하게 진행.

알고리즘 단순화(동일 효과 유지)

• SMS 스캔(services/sms_scanner.dart): 필터→파서→정규화 단일 파이프라인(순수 함수)로 재구성, 캐시/메모리 최적화 과잉 제거.
• URL 매처(services/url_matcher/*): 정규식 테이블 기반 단일 매칭기로 단순화(사전컴파일 RegExp), 서비스 데이터는 레포지토리 1곳에서 주입.
• 환율(exchange_rate_service.dart): CacheManager TTL 캐시 단일 책임, 만료 시 새로고침. 중복 포맷터/파서 제거.
• 알림(notification_service.dart): 스케줄/권한 체크를 단일 파사드로 노출, 내부 분기 축소.
• 성능 유틸(performance_optimizer.dart, memory_manager.dart): 체감·유지보수 이점 낮은 미세 최적화 제거, 프레임 드랍 유발 가능 애니메이션 단순화.

모든 변경은 퍼블릭 API/데이터 모델을 유지해 사이드 이펙트 방지.

테스트/검증

• 스크립트: scripts/check.sh 전 단계 실행(포맷/분석/테스트). 기존 deprecation 경고는 별 PR로 정리.
• 위젯/골든 테스트: 핵심 화면(메인/추가/상세/분석/설정) 라이트/다크 2종 캡처 비교.
• 유닛 테스트: URL 매처/환율 캐시/SMS 파이프라인.
• 접근성: 대비·포커스·터치 타깃 수동 점검 체크리스트.

작업 단위/PR 계획

1. 토대 구축: 의존성 추가 + 테마 브리지 + 핵심 컴포넌트(Button/Input/Card/Dialog) 도입.
2. 공용 UI 치환: 스낵바/다이얼로그/폼 필드/카드 템플릿 적용.
3. 화면별 리디자인: 메인→추가→상세→분석→설정 순.
4. 불용 코드 삭제: 치환 완료 파일 제거.
5. 알고리즘 단순화: sms/url/환율/알림 순으로 단일화 + 테스트.
6. 마감: 디테일 조정/접근성/성능 점검.

• 브랜치: codex/feat-shadcn-migration-* (단계별).
• 커밋: Conventional Commits + 한국어 본문.
• 롤백: 각 단계는 기능 플래그/치환 전후 비교가 쉬운 최소 단위로 유지.

위험 및 완화

• 리소스 색상/테마 충돌 → 토큰 브리지로 양방향 매핑, 미호환 위젯은 유지.
• 3rd-party 차트/네이티브 UI → 표면 색/텍스트만 토큰 적용.
• 분석 실패(deprecation) → 별 PR로 API 교체(activeColor 등), 마이그레이션과 분리 처리.

승인 체크리스트(Yes/No)

• flutter_shadcn_ui 의존성 추가 승인이 필요합니다.
• 테마 구조(shadcn 토큰 중심) 재구성 승인.
• 단계별 불용 파일 삭제 승인.
• 점진적 이행(옵션 A)로 진행 승인.

완료 기준(각 단계)

• scripts/check.sh 무사 통과(분석 경고 해결 내역은 별 PR 또는 병행).
• 라이트/다크 스냅샷 비교 이상 없음.
• 대상 화면/컴포넌트 치환 100% 및 구식 코드 제거.

---

작성자 메모: 본 계획은 코드 변경 없이 문서만 추가되었습니다. 승인 후 단계별 구현을 진행합니다.