From 79f9aa3eb074ce4176149f30458c984a47497db5 Mon Sep 17 00:00:00 2001 From: JiWoong Sul Date: Wed, 10 Sep 2025 06:16:09 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20flutter-shadcn-ui=20=EB=A7=88=EC=9D=B4?= =?UTF-8?q?=EA=B7=B8=EB=A0=88=EC=9D=B4=EC=85=98=20=EC=83=81=EC=84=B8=20?= =?UTF-8?q?=EA=B3=84=ED=9A=8D=20=EC=B6=94=EA=B0=80(doc/plan.md)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/plan.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 doc/plan.md diff --git a/doc/plan.md b/doc/plan.md new file mode 100644 index 0000000..64a90ba --- /dev/null +++ b/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% 및 구식 코드 제거. + +--- +작성자 메모: 본 계획은 코드 변경 없이 문서만 추가되었습니다. 승인 후 단계별 구현을 진행합니다.