docs: flutter-shadcn-ui 마이그레이션 상세 계획 추가(doc/plan.md)

doc/plan.md

@@ -0,0 +1,113 @@
+# 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% 및 구식 코드 제거.
+
+---
+작성자 메모: 본 계획은 코드 변경 없이 문서만 추가되었습니다. 승인 후 단계별 구현을 진행합니다.