# 네이버 단축 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 원칙을 따르며, 기존 시스템과의 원활한 통합을 보장합니다.

주요 이점:
- ✅ 명확한 책임 분리
- ✅ 높은 테스트 가능성
- ✅ 유연한 확장성
- ✅ 안정적인 에러 처리

이 설계를 통해 사용자는 더 쉽고 빠르게 네이버 지도의 식당 정보를 앱에 추가할 수 있으며, 개발팀은 안정적이고 유지보수가 용이한 코드베이스를 유지할 수 있습니다.