learn-flutter/llm.txt

# Tabling User Flutter 프로젝트 LLM 가이드

## 1. 프로젝트 개요

이 문서는 `tabling_user` Flutter 애플리케이션 프로젝트를 이해하고 개발하는 데 도움을 주기 위한 LLM 가이드입니다. Tabling 사용자 앱은 고객이 레스토랑을 검색하고, 예약하고, 웨이팅 목록에 참여하는 등의 기능을 제공하는 앱입니다.

## 2. 프로젝트 구조

### 2.1. 모노레포(Monorepo) 구조

Tabling Flutter 프로젝트는 모노레포 구조로 조직되어 있으며, 여러 앱과 패키지를 포함하고 있습니다.

tabling_c_flutter/
├── apps/
│ ├── tabling_user/ # 유저 타입 앱 (이 문서의 주제)
│ ├── tabling_web_app/ # 웹 앱
│ ├── server_board/
│ ├── tabling_web/
│ ├── reservation/
│ ├── ceoboard/
│ ├── storybook/
│ └── tabling_pager/
└── packages/ # 공유 패키지
├── tabling_ui/ # UI 컴포넌트 패키지
├── tabling_models/ # 데이터 모델 패키지
├── tabling_rest_client/ # API 클라이언트 패키지
├── tabling_shared_data/ # 공유 데이터 패키지
├── tabling_restaurant_card/ # 레스토랑 카드 UI 컴포넌트
├── tabling_format/ # 포맷팅 유틸리티
├── tabling_analytics/ # 분석 도구
├── tabling_image/ # 이미지 관련 유틸리티
└── tabling_video_player/ # 비디오 플레이어 컴포넌트

### 2.2. tabling_user 앱 구조

tabling_user 앱은 다음과 같은 디렉토리 구조를 가지고 있습니다:

tabling_user/
├── lib/
│ ├── analytics/ # 분석 관련 코드
│ ├── animations/ # 애니메이션 관련 코드
│ ├── constants/ # 상수 정의
│ ├── extensions/ # 확장 메소드
│ ├── locales/ # 다국어 지원
│ ├── mixins/ # 믹스인
│ ├── models/ # 앱 특화 모델 (패키지 모델 외)
│ ├── pages/ # 페이지 정의 (라우팅 진입점)
│ ├── providers/ # Riverpod 프로바이더
│ ├── repositories/ # 데이터 리포지토리
│ ├── router/ # 라우팅 설정
│ ├── services/ # 비즈니스 로직 서비스
│ ├── utils/ # 유틸리티 함수
│ ├── view_models/ # 뷰 모델
│ ├── app.dart # 앱 진입점
│ ├── flavors.dart # 환경 설정
│ ├── main.dart # 메인 진입점
│ ├── main_develop.dart # 개발 환경 진입점
│ ├── main_production.dart # 프로덕션 환경 진입점
│ └── main_staging.dart # 스테이징 환경 진입점

## 3. 아키텍처 패턴

### 3.1. Page -> Screen -> Widget 패턴

tabling_user 앱은 Page -> Screen -> Widget 패턴을 사용하여 UI를 구성합니다:

1. **Page**:
   - 라우팅 시스템의 진입점
   - 앱의 `/pages` 디렉토리에 정의됨
   - 해당 화면의 라우팅, 상태 관리 및 초기화 로직을 담당
   - 일반적으로 Provider나 View Model과 연결되어 데이터 상태를 관리
   - 화면 내용을 구성하는 Screen 컴포넌트를 포함

2. **Screen**:
   - `tabling_ui` 패키지의 `/screens` 디렉토리에 정의됨
   - 특정 페이지의 주요 레이아웃과 UI 로직을 담당
   - 재사용 가능한 단위로 설계됨
   - 상위 Page로부터 데이터와 이벤트 핸들러를 전달받음
   - 여러 작은 Widget들을 조합하여 화면을 구성

3. **Widget**:
   - `tabling_ui` 패키지의 `/widgets` 디렉토리에 정의됨
   - 작고 재사용 가능한 UI 컴포넌트
   - 버튼, 텍스트 필드, 카드 등 기본 UI 요소
   - 디자인 시스템에 따라 일관된 스타일과 동작을 제공

### 3.2. 상태 관리

tabling_user 앱은 Riverpod를 사용하여 상태를 관리합니다:

- `/providers` 디렉토리: 글로벌 상태 및 서비스 프로바이더
- 각 Page 디렉토리 내 `provider.dart`: 해당 페이지 특화 프로바이더
- 각 기능 디렉토리 내 `viewmodel.dart`: 상태와 비즈니스 로직 캡슐화

## 4. 주요 패키지 및 종속성

### 4.1. 내부 패키지

앱은 다음과 같은 내부 패키지를 활용합니다:

- **tabling_ui**: 디자인 시스템 구현, UI 컴포넌트 제공
- **tabling_models**: 앱에서 사용되는 데이터 모델 정의
- **tabling_rest_client**: API 통신 클라이언트
- **tabling_shared_data**: 앱 간 공유 데이터
- **tabling_restaurant_card**: 레스토랑 카드 UI 컴포넌트
- **tabling_format**: 날짜, 시간, 금액 등 포맷팅 유틸리티
- **tabling_analytics**: 분석 및 이벤트 추적
- **tabling_image**: 이미지 관련 유틸리티

### 4.2. 외부 종속성

주요 외부 라이브러리:

- **flutter_riverpod**: 상태 관리
- **go_router**: 라우팅
- **firebase_core, firebase_analytics, firebase_messaging 등**: Firebase 서비스
- **cached_network_image**: 네트워크 이미지 캐싱
- **flutter_facebook_auth, kakao_flutter_sdk_user, sign_in_with_apple**: 소셜 로그인
- **infinite_scroll_pagination**: 무한 스크롤
- **easy_debounce**: 입력 디바운싱
- **permission_handler**: 권한 관리
- **sentry_flutter**: 에러 모니터링
- **geolocator**: 위치 정보
- **flutter_local_notifications**: 로컬 알림
- **animations, flutter_animate, lottie**: 애니메이션 효과

## 5. 코드 규칙 및 패턴

### 5.1. 파일 명명 규칙

- **페이지**: `page.dart` (예: `/pages/my/reviews/page.dart`)
- **화면**: `*_screen.dart` (예: `search_screen.dart`)
- **위젯**: 기능/유형에 따른 이름 (예: `tabling_search_field.dart`)
- **프로바이더**: `provider.dart`
- **뷰모델**: `viewmodel.dart` 또는 `view_model.dart`
- **모델**: `*_model.dart` 또는 `entity.dart`

### 5.2. 코드 구조화 패턴

1. **기능별 디렉토리 구조**:
   - 각 주요 기능은 자체 디렉토리에 캡슐화됨
   - 예: `/pages/my/reviews/` - 리뷰 관련 페이지 및 로직

2. **Provider-ViewModel 패턴**:
   - Provider: 상태 관리 및 의존성 주입
   - ViewModel: UI 로직과 상태를 캡슐화
   - 예: `provider.dart` + `viewmodel.dart`

3. **이벤트 기반 통신**:
   - 화면 간 통신은 이벤트 기반 패턴 사용
   - `ScreenEvent` 클래스를 통한 일관된 이벤트 처리
   - 상위 컴포넌트에 이벤트 위임 (콜백 함수)

## 6. 개발 워크플로우

### 6.1. 새로운 기능 개발

1. **모델 정의**:
   - 필요한 데이터 모델이 `tabling_models`에 있는지 확인
   - 없다면 추가 요청 또는 로컬 모델 정의

2. **API 통합**:
   - `tabling_rest_client`를 통해 API 호출
   - 리포지토리 패턴으로 데이터 접근 추상화

3. **상태 관리 설정**:
   - Riverpod Provider 및 ViewModel 구현
   - 상태 및 비즈니스 로직 구현

4. **UI 구현**:
   - Page 컴포넌트 구현 (라우팅 진입점)
   - 필요한 Screen 컴포넌트 구현 또는 재사용
   - `tabling_ui` 위젯 활용

### 6.2. 환경 설정

- **Flavors**: 개발, 스테이징, 프로덕션 환경 구분
- **환경별 진입점**: `main_develop.dart`, `main_staging.dart`, `main_production.dart`
- **firebase_app_check**: 인증된 앱 요청 보장

## 7. UI/UX 가이드라인

### 7.1. 디자인 시스템

tabling_ui 패키지는 다음과 같은 디자인 시스템 요소를 제공합니다:

- **토큰 시스템**:
  - `/tokens/core`: 색상, 간격, 타이포그래피 등 기본 디자인 토큰
  - 일관된 디자인 적용을 위해 하드코딩된 값 대신 토큰 사용 권장

- **위젯 컴포넌트**:
  - `/widgets`: 버튼, 텍스트 필드, 카드 등 재사용 가능한 UI 컴포넌트
  - 커스텀 UI보다 기존 컴포넌트 재사용 권장

- **테마**:
  - `/theme`: 앱 전체 테마 및 스타일링
  - 앱 테마를 일관되게 유지하기 위해 테마 설정 준수

### 7.2. 반응형 디자인

- **LayoutBuilder 및 MediaQuery** 활용
- 다양한 화면 크기에 적응하는 UI 설계
- 기기 방향 변경 대응

## 8. 테스팅 및 품질 보증

### 8.1. 테스트 유형

- **단위 테스트**: `/test` 디렉토리
- **통합 테스트**: `/integration_test` 디렉토리
- **위젯 테스트**: UI 컴포넌트 테스트

### 8.2. 코드 품질 도구

- **analysis_options.yaml**: 린트 규칙 정의
- **custom_lint**: 추가 린트 규칙
- **lefthook.yml**: 커밋 전 검사

## 9. 배포 및 릴리스

### 9.1. CI/CD

- **codemagic.yaml**: CI/CD 파이프라인 구성
- **GitHub Actions**: 추가 자동화 작업

### 9.2. 버전 관리

- **pubspec.yaml**: 앱 버전 및 빌드 번호 관리
- **melos.yaml**: 모노레포 패키지 버전 관리

## 10. 문제 해결 및 디버깅

### 10.1. 로깅

- **talker_flutter**: 고급 로깅 및 디버깅 도구
- **sentry_flutter**: 에러 모니터링 및 보고

### 10.2. 성능 모니터링

- **firebase_performance**: 앱 성능 모니터링
- **firebase_crashlytics**: 크래시 보고 및 분석

## 11. 공통 개발 작업

### 11.1. 새 페이지 추가

1. `/pages/[feature]/` 디렉토리 생성
2. `page.dart` 파일 구현 (Page 컴포넌트)
3. Provider 및 ViewModel 구현
4. `/router/` 디렉토리에 라우트 등록

### 11.2. 기존 페이지 수정

1. 관련 Page 컴포넌트 식별
2. 필요한 상태 및 이벤트 핸들러 수정
3. 필요에 따라 Screen 또는 Widget 컴포넌트 수정

### 11.3. 새 API 통합

1. `tabling_rest_client`에서 API 엔드포인트 확인/추가
2. 필요한 모델 업데이트/추가
3. Repository 구현/수정
4. Provider 및 ViewModel 업데이트

## 12. 결론

tabling_user 프로젝트는 Page -> Screen -> Widget 패턴과 Riverpod를 사용한 상태 관리를 통해 구조화된 Flutter 앱입니다. 다양한 내부 패키지를 활용하여 일관된 UI/UX 및 기능을 제공합니다. 이 가이드를 참고하여 프로젝트의 구조를 이해하고 효율적으로 개발에 기여할 수 있습니다.