diff --git a/README.md b/README.md index 41da1ac..89958aa 100644 --- a/README.md +++ b/README.md @@ -1 +1,358 @@ -# spring-sunshine-precourse \ No newline at end of file +# Spring Sunshine Precourse + +Spring Boot 기반 날씨 정보 조회 및 LLM을 활용한 날씨 요약 및 의상 추천 서비스입니다. + +## 목차 + +- [기능 목록](#기능-목록) +- [구현 전략](#구현-전략) +- [Git 커밋 컨벤션](#git-커밋-컨벤션) +- [AI 도구 활용](#ai-도구-활용) +- [프로젝트 구조](#프로젝트-구조) +- [실행 방법](#실행-방법) +- [API 엔드포인트](#api-엔드포인트) + +## 기능 목록 + +### 1. 기본 날씨 정보 조회 기능 +- **기능**: Open-Meteo API를 활용한 날씨 정보 조회 +- **구현 파일**: `WeatherService.java`, `WeatherController.java` +- **엔드포인트**: `GET /weather?city={cityName}` + +### 2. LLM 기반 날씨 요약 및 의상 추천 기능 +- **기능**: Google Gemini AI를 활용한 날씨 요약 및 의상 추천 +- **구현 파일**: `WeatherLLMService.java`, `LLMService.java`, `LLMServiceImpl.java` +- **엔드포인트**: `GET /weather/llm?location={location}&useCache={true|false}` + +### 3. LLM 호출 분리 (2단계 프로세스) +- **기능 3-1**: 날씨 정보 조회 (첫 번째 LLM 호출) + - `getWeather` 함수를 사용하여 날씨 데이터 조회 + - 캐시 키: `weatherInfo` +- **기능 3-2**: 요약 및 추천 생성 (두 번째 LLM 호출) + - 조회된 날씨 정보를 기반으로 요약 및 의상 추천 생성 + - 캐시 키: `weatherSummaries` + +### 4. 캐싱 기능 +- **기능**: Spring Cache를 활용한 LLM 응답 캐싱 +- **구현 파일**: `CacheConfig.java` +- **캐시 전략**: + - `ConcurrentMapCacheManager` 사용 + - 조건부 캐싱 (`useCache` 파라미터 기반) + - 두 개의 독립적인 캐시: `weatherInfo`, `weatherSummaries` + +### 5. 사용량 추적 및 비용 계산 +- **기능**: LLM 호출 시 토큰 사용량 추적 및 예상 비용 계산 +- **구현 파일**: `WeatherLLMService.java` +- **추적 정보**: Input Tokens, Output Tokens, Total Tokens, Estimated Cost + +### 6. 로깅 기능 +- **기능**: 각 LLM 호출 단계별 상세 로깅 +- **구현 파일**: `LLMServiceImpl.java` +- **로깅 내용**: + - 함수 시작/종료 로그 + - 응답 내용 로그 + - 토큰 사용량 로그 + +## 구현 전략 + +### 아키텍처 설계 + +#### 1. 계층 구조 +``` +Controller Layer (WeatherController) + ↓ +Service Layer (WeatherLLMService) + ↓ +LLM Service Interface (LLMService) + ↓ +LLM Service Implementation (LLMServiceImpl) + ↓ +Spring AI ChatClient +``` + +#### 2. 관심사 분리 (Separation of Concerns) +- **LLMService 인터페이스**: LLM 호출 계약 정의 +- **LLMServiceImpl**: 실제 LLM 호출 로직 구현 및 캐싱 +- **WeatherLLMService**: 비즈니스 로직 (파싱, 사용량 집계, DTO 변환) + +#### 3. 캐싱 전략 +- **2단계 캐싱**: + 1. 날씨 정보 조회 결과 캐싱 (`weatherInfo`) + 2. 요약 생성 결과 캐싱 (`weatherSummaries`) +- **조건부 캐싱**: `@Cacheable`의 `condition` 속성을 활용하여 `useCache` 파라미터로 제어 +- **캐시 키 전략**: + - `weatherInfo`: `#location` + - `weatherSummaries`: `#location + '_' + #weatherInfo.hashCode()` + +#### 4. LLM 호출 분리 전략 +- **1단계**: 날씨 정보 조회 (`fetchWeatherInfo`) + - `getWeather` 함수 호출 + - 원시 날씨 데이터 반환 +- **2단계**: 요약 생성 (`generateSummary`) + - 1단계 결과를 입력으로 받아 요약 및 추천 생성 + - 각 단계별 독립적인 캐싱 + +### 기술 스택 +- **Spring Boot 3.5.8** +- **Spring AI 1.1.2** (Google Gemini AI) +- **Java 21** +- **Spring Cache** (ConcurrentMapCacheManager) + +## Git 커밋 컨벤션 + +본 프로젝트는 [AngularJS Git Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-message-convention)을 따릅니다. + +### 커밋 메시지 형식 + +``` +(): + + + +