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