feat: 초기 프로젝트 설정 및 LunchPick 앱 구현

LunchPick(오늘 뭐 먹Z?) Flutter 앱의 초기 구현입니다. 주요 기능: - 네이버 지도 연동 맛집 추가 - 랜덤 메뉴 추천 시스템 - 날씨 기반 거리 조정 - 방문 기록 관리 - Bluetooth 맛집 공유 - 다크모드 지원 기술 스택: - Flutter 3.8.1+ - Riverpod 상태 관리 - Hive 로컬 DB - Clean Architecture 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-30 19:03:28 +09:00
commit 85fde36157
237 changed files with 30953 additions and 0 deletions
--- a/doc/03_architecture/architecture_overview.md
+++ b/doc/03_architecture/architecture_overview.md
@@ -0,0 +1,247 @@
+# 네이버 단축 URL 처리 아키텍처 개요
+
+## 1. 프로젝트 요약
+
+### 1.1 목표
+네이버 단축 URL(naver.me)을 처리하여 식당 정보를 추출하고, 네이버 로컬 API를 통해 상세 정보를 보강하는 시스템 구축
+
+### 1.2 핵심 가치
+- **사이드이펙트 방지**: 명확한 책임 분리와 순수 함수 활용
+- **책임 분리**: 각 컴포넌트가 단일 책임 원칙 준수
+- **테스트 가능성**: 의존성 주입과 모킹을 통한 단위 테스트
+- **확장성**: 새로운 데이터 소스 추가 용이
+
+## 2. 아키텍처 선택
+
+### 2.1 Clean Architecture + MVVM
+- **이유**: 비즈니스 로직과 UI의 명확한 분리
+- **장점**: 테스트 용이성, 유지보수성, 확장성
+- **구현**: 3계층 구조 (Presentation → Domain → Data)
+
+### 2.2 상태 관리: Riverpod
+- **이유**: 
+  - 컴파일 타임 안전성
+  - 의존성 주입 내장
+  - 기존 프로젝트와 일관성
+- **장점**: 
+  - Provider 범위 제어
+  - 자동 리소스 관리
+  - 테스트 모킹 용이
+
+### 2.3 로컬 저장소: Hive
+- **이유**: 
+  - 빠른 성능
+  - 간단한 API
+  - 기존 인프라 활용
+- **장점**: 
+  - NoSQL 기반 유연성
+  - 타입 안전성
+  - 오프라인 우선 설계
+
+## 3. 주요 컴포넌트 설계
+
+### 3.1 NaverUrlProcessor (신규)
+```dart
+class NaverUrlProcessor {
+  // 책임: URL 처리 파이프라인 관리
+  // 의존성: NaverMapParser, NaverLocalApiClient
+  // 출력: Restaurant 엔티티
+}
+```
+
+**주요 기능:**
+- URL 유효성 검증
+- 단축 URL 리다이렉션
+- 정보 추출 조정
+- 데이터 병합
+
+### 3.2 NaverLocalApiClient (신규)
+```dart
+class NaverLocalApiClient {
+  // 책임: 네이버 로컬 API 통신
+  // 의존성: Dio, ApiKeys
+  // 출력: API 응답 모델
+}
+```
+
+**주요 기능:**
+- API 호출 및 에러 처리
+- Rate limiting
+- 응답 파싱
+
+### 3.3 NaverMapParser (확장)
+- 기존 HTML 스크래핑 기능 유지
+- 검색 키워드 추출 기능 추가
+- 메타데이터 추출 강화
+
+## 4. 데이터 플로우
+
+```
+1. 사용자 입력 (네이버 단축 URL)
+    ↓
+2. RestaurantRepository.addRestaurantFromUrl()
+    ↓
+3. NaverUrlProcessor.processNaverUrl()
+    ↓
+4. URL 검증 및 리다이렉션
+    ↓
+5. 병렬 처리:
+    - NaverMapParser: HTML 스크래핑
+    - NaverLocalApiClient: API 검색
+    ↓
+6. 데이터 매칭 및 병합
+    ↓
+7. Restaurant 엔티티 생성
+    ↓
+8. Hive 저장
+```
+
+## 5. 에러 처리 전략
+
+### 5.1 계층별 예외
+```dart
+DataLayer: NetworkException, ParseException
+DomainLayer: BusinessException, ValidationException  
+PresentationLayer: UIException
+```
+
+### 5.2 복구 전략
+- **네트워크 실패**: 3회 재시도 후 캐시 데이터 사용
+- **파싱 실패**: 기본값 사용 및 부분 데이터 반환
+- **API 제한**: Rate limiting 및 백오프
+
+## 6. 성능 최적화
+
+### 6.1 캐싱 전략
+- **메모리 캐시**: URL 리다이렉션, API 응답 (LRU)
+- **디스크 캐시**: Restaurant 데이터 (Hive)
+- **TTL**: URL 1시간, API 30분
+
+### 6.2 동시성 제어
+- 최대 동시 요청: 3개
+- API Rate limit: 초당 10회
+- 타임아웃: 10초
+
+## 7. 테스트 전략
+
+### 7.1 단위 테스트
+- **목표 커버리지**: 80% 이상
+- **핵심 테스트**: URL 파서, API 클라이언트, 매칭 알고리즘
+
+### 7.2 통합 테스트
+- E2E 시나리오 테스트
+- 실제 네이버 URL 테스트 (CI 제외)
+
+### 7.3 모킹
+- Mockito/Mocktail 사용
+- HTTP 응답 모킹
+- Provider 오버라이드
+
+## 8. 보안 고려사항
+
+### 8.1 API 키 관리
+- 환경 변수 사용
+- 컴파일 타임 주입
+- ProGuard 난독화
+
+### 8.2 입력 검증
+- URL 화이트리스트
+- XSS 방지
+- 인젝션 방지
+
+## 9. 모니터링 및 로깅
+
+### 9.1 구조화된 로깅
+```dart
+logger.info('URL 처리 시작', {
+  'url': url,
+  'timestamp': DateTime.now(),
+  'userId': userId,
+});
+```
+
+### 9.2 성능 모니터링
+- 응답 시간 측정
+- 성공률 추적
+- 에러율 모니터링
+
+## 10. 향후 확장 계획
+
+### 10.1 단기 (1-3개월)
+- 카카오맵 URL 지원
+- 메뉴 정보 수집
+- 오프라인 모드 강화
+
+### 10.2 중기 (3-6개월)
+- 자체 백엔드 구축
+- 리뷰 데이터 수집
+- ML 기반 매칭
+
+### 10.3 장기 (6개월+)
+- 다중 플랫폼 통합
+- 실시간 업데이트
+- 개인화 추천
+
+## 11. 개발 가이드라인
+
+### 11.1 코딩 원칙
+- DRY (Don't Repeat Yourself)
+- KISS (Keep It Simple)
+- SOLID 원칙 준수
+
+### 11.2 PR 체크리스트
+- [ ] 단위 테스트 작성
+- [ ] 문서 업데이트
+- [ ] 코드 리뷰 통과
+- [ ] CI/CD 통과
+
+### 11.3 배포 전략
+- Feature flag 사용
+- 점진적 롤아웃
+- 롤백 계획 수립
+
+## 12. 팀 협업
+
+### 12.1 개발 프로세스
+1. 이슈 생성 및 할당
+2. 기능 브랜치 생성
+3. 구현 및 테스트
+4. PR 생성 및 리뷰
+5. 머지 및 배포
+
+### 12.2 문서화
+- 코드 내 주석 (한국어)
+- API 문서 자동 생성
+- 아키텍처 결정 기록 (ADR)
+
+## 13. 리스크 관리
+
+| 리스크 | 가능성 | 영향도 | 대응 방안 |
+|--------|--------|--------|-----------|
+| 네이버 구조 변경 | 높음 | 높음 | 파서 모듈화, 빠른 업데이트 |
+| API 제한 강화 | 중간 | 중간 | 캐싱 강화, 대체 API |
+| CORS 프록시 장애 | 중간 | 높음 | 다중 프록시, 자체 구축 |
+
+## 14. 성공 지표
+
+### 14.1 기술적 지표
+- URL 처리 성공률 > 95%
+- 평균 응답 시간 < 3초
+- 크래시율 < 0.1%
+
+### 14.2 비즈니스 지표
+- 사용자 만족도 향상
+- 식당 등록 시간 단축
+- 데이터 정확도 향상
+
+## 15. 결론
+
+본 아키텍처는 네이버 단축 URL 처리를 위한 확장 가능하고 유지보수가 용이한 시스템을 제공합니다. Clean Architecture 원칙을 따르며, 기존 시스템과의 원활한 통합을 보장합니다.
+
+주요 이점:
+- ✅ 명확한 책임 분리
+- ✅ 높은 테스트 가능성
+- ✅ 유연한 확장성
+- ✅ 안정적인 에러 처리
+
+이 설계를 통해 사용자는 더 쉽고 빠르게 네이버 지도의 식당 정보를 앱에 추가할 수 있으며, 개발팀은 안정적이고 유지보수가 용이한 코드베이스를 유지할 수 있습니다.