lunchpick/doc/03_architecture/project_structure_diagram.md

프로젝트 구조도

1. 전체 구조 개요

lunchpick/
├── lib/
│   ├── core/                      # 핵심 공통 모듈
│   │   ├── constants/             # 상수 정의
│   │   ├── errors/                # 에러 및 예외 처리
│   │   ├── services/              # 공통 서비스
│   │   ├── utils/                 # 유틸리티 함수
│   │   └── widgets/               # 공통 위젯
│   │
│   ├── data/                      # 데이터 계층
│   │   ├── datasources/           # 데이터 소스
│   │   │   ├── local/             # 로컬 데이터 소스
│   │   │   └── remote/            # 원격 데이터 소스
│   │   ├── models/                # 데이터 모델 (DTO)
│   │   └── repositories/          # 레포지토리 구현체
│   │
│   ├── domain/                    # 도메인 계층
│   │   ├── entities/              # 도메인 엔티티
│   │   ├── repositories/          # 레포지토리 인터페이스
│   │   └── usecases/              # 유스케이스 (비즈니스 로직)
│   │
│   ├── presentation/              # 프레젠테이션 계층
│   │   ├── pages/                 # 화면 단위 구성
│   │   ├── providers/             # 상태 관리 (Riverpod)
│   │   └── widgets/               # 프레젠테이션 공통 위젯
│   │
│   └── main.dart                  # 앱 진입점
│
├── test/                          # 테스트 코드
├── doc/                           # 문서
└── pubspec.yaml                   # 의존성 관리

2. 계층별 상세 구조

2.1 Core Layer (핵심 모듈)

core/
├── constants/
│   ├── api_keys.dart              # API 키 관리
│   ├── app_colors.dart            # 색상 테마
│   ├── app_constants.dart         # 앱 전역 상수
│   ├── app_typography.dart        # 텍스트 스타일
│   └── categories.dart            # 카테고리 정의
│
├── errors/
│   ├── exceptions.dart            # 커스텀 예외
│   └── failures.dart              # 실패 타입 정의
│
├── services/
│   └── notification_service.dart  # 알림 서비스
│
├── utils/
│   ├── distance_calculator.dart   # 거리 계산 유틸
│   └── validators.dart            # 입력 검증 유틸
│
└── widgets/
    ├── empty_state_widget.dart    # 빈 상태 위젯
    ├── error_widget.dart          # 에러 표시 위젯
    └── loading_indicator.dart     # 로딩 인디케이터

2.2 Data Layer (데이터 계층)

data/
├── datasources/
│   ├── local/
│   │   └── (Hive 데이터소스)
│   │
│   └── remote/
│       ├── naver_map_parser.dart        # 네이버 지도 파서 (기존)
│       ├── naver_local_api_client.dart  # 네이버 로컬 API (신규)
│       └── naver_url_processor.dart     # URL 처리기 (신규)
│
├── models/
│   ├── naver_local_search_result.dart  # API 검색 결과 모델 (신규)
│   └── naver_place_detail.dart         # 장소 상세 모델 (신규)
│
└── repositories/
    ├── recommendation_repository_impl.dart
    ├── restaurant_repository_impl.dart
    ├── settings_repository_impl.dart
    ├── visit_repository_impl.dart
    └── weather_repository_impl.dart

2.3 Domain Layer (도메인 계층)

domain/
├── entities/
│   ├── recommendation_record.dart  # 추천 기록
│   ├── restaurant.dart            # 식당 엔티티
│   ├── share_device.dart          # 공유 디바이스
│   ├── user_settings.dart         # 사용자 설정
│   ├── visit_record.dart          # 방문 기록
│   └── weather_info.dart          # 날씨 정보
│
├── repositories/
│   ├── recommendation_repository.dart
│   ├── restaurant_repository.dart
│   ├── settings_repository.dart
│   ├── visit_repository.dart
│   └── weather_repository.dart
│
└── usecases/
    └── recommendation_engine.dart  # 추천 엔진

2.4 Presentation Layer (프레젠테이션 계층)

presentation/
├── pages/
│   ├── calendar/                  # 캘린더 화면
│   │   ├── calendar_screen.dart
│   │   └── widgets/
│   │       ├── visit_confirmation_dialog.dart
│   │       ├── visit_record_card.dart
│   │       └── visit_statistics.dart
│   │
│   ├── main/                      # 메인 화면
│   │   └── main_screen.dart
│   │
│   ├── random_selection/          # 랜덤 선택 화면
│   │   ├── random_selection_screen.dart
│   │   └── widgets/
│   │       └── recommendation_result_dialog.dart
│   │
│   ├── restaurant_list/           # 식당 목록 화면
│   │   ├── restaurant_list_screen.dart
│   │   └── widgets/
│   │       ├── add_restaurant_dialog.dart
│   │       └── restaurant_card.dart
│   │
│   ├── settings/                  # 설정 화면
│   │   ├── settings_screen.dart
│   │   └── widgets/
│   │
│   ├── share/                     # 공유 화면
│   │   ├── share_screen.dart
│   │   └── widgets/
│   │
│   └── splash/                    # 스플래시 화면
│       └── splash_screen.dart
│
├── providers/
│   ├── di_providers.dart          # 의존성 주입
│   ├── location_provider.dart     # 위치 상태 관리
│   ├── notification_handler_provider.dart
│   ├── notification_provider.dart
│   ├── recommendation_provider.dart
│   ├── restaurant_provider.dart
│   ├── settings_provider.dart
│   ├── visit_provider.dart
│   └── weather_provider.dart
│
└── widgets/
    └── category_selector.dart     # 카테고리 선택기

3. 데이터 흐름도

graph TD
    A[사용자 인터페이스] -->|사용자 액션| B[Presentation Layer]
    B -->|Provider/State| C[Domain Layer]
    C -->|Use Case 실행| D[Data Layer]
    D -->|Repository 구현| E[Data Sources]
    
    E --> F[Local Data Source<br/>Hive]
    E --> G[Remote Data Source<br/>APIs]
    
    G --> H[네이버 지도 파서]
    G --> I[네이버 로컬 API]
    G --> J[날씨 API]
    
    F -->|데이터 반환| D
    G -->|데이터 반환| D
    D -->|엔티티 반환| C
    C -->|결과 반환| B
    B -->|UI 업데이트| A

4. 네이버 URL 처리 플로우

graph LR
    A[네이버 단축 URL] --> B[NaverUrlProcessor]
    B --> C{URL 유효성<br/>검증}
    
    C -->|유효| D[NaverMapParser]
    C -->|무효| E[에러 반환]
    
    D --> F[단축 URL<br/>리다이렉션]
    F --> G[HTML<br/>스크래핑]
    
    G --> H[기본 정보<br/>추출]
    H --> I[NaverLocalApiClient]
    
    I --> J[로컬 API<br/>검색]
    J --> K[결과 매칭]
    
    K --> L[정보 병합]
    L --> M[Restaurant<br/>엔티티 생성]
    
    M --> N[Repository]
    N --> O[Hive 저장]

5. 의존성 관계도

graph BT
    A[main.dart] --> B[Presentation Layer]
    B --> C[Domain Layer]
    C --> D[Data Layer]
    D --> E[Core Layer]
    
    B --> E
    D --> F[External Packages]
    
    F --> G[flutter_riverpod]
    F --> H[hive]
    F --> I[dio]
    F --> J[http]
    F --> K[html]
    
    E --> L[Flutter SDK]

6. 모듈별 책임

6.1 Core 모듈

• 역할: 앱 전체에서 공통으로 사용되는 기능 제공
• 책임:
  • 상수 및 설정 관리
  • 공통 유틸리티 제공
  • 전역 위젯 제공
  • 에러 처리 표준화

6.2 Data 모듈

• 역할: 데이터 접근 및 변환
• 책임:
  • 외부 API 통신
  • 로컬 데이터베이스 관리
  • DTO ↔ Entity 변환
  • 캐싱 처리

6.3 Domain 모듈

• 역할: 비즈니스 로직 정의
• 책임:
  • 엔티티 정의
  • 비즈니스 규칙 구현
  • 유스케이스 정의
  • 레포지토리 인터페이스 정의

6.4 Presentation 모듈

• 역할: 사용자 인터페이스 및 상태 관리
• 책임:
  • UI 렌더링
  • 사용자 입력 처리
  • 상태 관리 (Riverpod)
  • 네비게이션 처리

7. 확장 포인트

7.1 새로운 데이터 소스 추가

data/datasources/remote/
├── kakao_map_parser.dart      # 카카오맵 지원
├── google_maps_parser.dart    # 구글맵 지원
└── delivery_app_parser.dart   # 배달앱 지원

7.2 새로운 기능 모듈 추가

presentation/pages/
├── reviews/                   # 리뷰 기능
├── social/                    # 소셜 기능
└── analytics/                 # 통계 기능

7.3 새로운 저장소 추가

domain/repositories/
├── review_repository.dart     # 리뷰 저장소
├── user_repository.dart       # 사용자 저장소
└── analytics_repository.dart  # 분석 저장소