lunchpick/doc/03_architecture/architecture_overview.md

네이버 단축 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 (신규)

class NaverUrlProcessor {
  // 책임: URL 처리 파이프라인 관리
  // 의존성: NaverMapParser, NaverLocalApiClient
  // 출력: Restaurant 엔티티
}

주요 기능:

• URL 유효성 검증
• 단축 URL 리다이렉션
• 정보 추출 조정
• 데이터 병합

3.2 NaverLocalApiClient (신규)

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 계층별 예외

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 구조화된 로깅

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

주요 이점:

• ✅ 명확한 책임 분리
• ✅ 높은 테스트 가능성
• ✅ 유연한 확장성
• ✅ 안정적인 에러 처리

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