PickPl (픽플)

pickpl/ (Root Directory)
├── frontend/           # Next.js 프론트엔드 웹 앱
├── backend/            # Spring Boot 백엔드 API 서버
├── data-pipeline/      # Playwright & Gemini 데이터 수집 파이프라인
├── docker-compose.yml  # MySQL & Redis 개발 환경 컨테이너 스펙
└── Makefile            # 로컬 통합 개발 실행 단축 스크립트

// backend/src/main/java/com/pickpl/app/curation/service/CurationService.java
@Transactional(readOnly = true)
public CurationResponse getCuration(Long userId, Double latitude, Double longitude) {
    // 1. 기상 Open API 호출 및 현재 시간 수립
    String weatherState = weatherClient.getWeatherState(latitude, longitude);
    java.time.LocalDateTime now = java.time.LocalDateTime.now();
    java.time.DayOfWeek day = now.getDayOfWeek();
    int hour = now.getHour();
    int currentMonth = now.getMonthValue();
    String curationThemeKey;
 
    // 2. 날씨/시간대/계절 판정 매트릭스 트리 작동
    if ("RAINY".equals(weatherState)) {
        curationThemeKey = "rainy_indoor"; // 비 오는 날 큐레이션 배너 고정
    } else if ("SNOWY".equals(weatherState)) {
        curationThemeKey = "winter";
    } else {
        if ((day == java.time.DayOfWeek.FRIDAY || day == java.time.DayOfWeek.SATURDAY) && (hour >= 17 || hour <= 2)) {
            curationThemeKey = "night_market"; // 주말 저녁 야장 노포 테마
        } else if ((day == java.time.DayOfWeek.SATURDAY || day == java.time.DayOfWeek.SUNDAY) && (hour >= 9 && hour < 17)) {
            curationThemeKey = "pet_friendly"; // 주말 낮 애견동반 게릴라 테마
        } else if ((day == java.time.DayOfWeek.MONDAY || day == java.time.DayOfWeek.TUESDAY || day == java.time.DayOfWeek.WEDNESDAY || day == java.time.DayOfWeek.THURSDAY) && (hour >= 13 && hour < 17)) {
            curationThemeKey = "wellness"; // 평일 낮 다도/웰니스 차분한 테마
        } else {
            // 그 외 기본 달(Month)에 기반한 계절 배너 노출
            if (currentMonth >= 3 && currentMonth <= 5) curationThemeKey = "spring";
            else if (currentMonth >= 6 && currentMonth <= 8) curationThemeKey = "summer";
            else if (currentMonth >= 9 && currentMonth <= 11) curationThemeKey = "autumn";
            else curationThemeKey = "winter";
        }
    }
    
    List<PlaceSummaryResponse> places = java.util.Collections.emptyList();
    if (curationThemeKey != null) {
        places = placeService.findPlacesByCurationTheme(curationThemeKey, userId, latitude, longitude);
    }
    return CurationResponse.of(activeThemeTitle, activeThemeName, places);
}

// backend/src/main/java/com/pickpl/app/place/service/RecommendationService.java
@Transactional(readOnly = true)
public RecommendationResponse getPersonalizedRecommendations(Long userId) {
    if (userId == null) return getPopularFallback();
    
    // 1. Redis 캐시 또는 DB를 조회하여 사용자의 취향 가중치 벡터 맵을 획득
    Map<String, Double> userPreferences = getUserPreferenceVector(userId);
    if (userPreferences.isEmpty()) return getPopularFallback();
 
    // 2. 가장 선호도가 높은 주요 무드 및 상위 태그 추출
    String primaryMood = userPreferences.entrySet().stream()
            .max(Map.Entry.comparingByValue())
            .map(Map.Entry::getKey).orElse(null);
 
    List<String> topTags = userPreferences.entrySet().stream()
            .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
            .limit(3).map(Map.Entry::getKey).toList();
 
    // 3. 후보군 수집 (선호 태그 매칭 장소 100건 + 최근 등록 장소 50건)
    Set<Place> candidates = new HashSet<>();
    if (!topTags.isEmpty()) {
        candidates.addAll(placeRepository.findTop100ByTagNames(topTags, PageRequest.of(0, 100)));
    }
    candidates.addAll(placeRepository.findAllByIsPublishedTrue(PageRequest.of(0, 50, Sort.by(Sort.Direction.DESC, "id"))).getContent());
 
    List<ScoredPlace> scoredPlaces = new ArrayList<>();
    LocalDateTime now = LocalDateTime.now();
 
    // 4. 각 후보지별 개인화 매칭 스코어링 및 시간 감쇠(Time Decay) 연산
    for (Place place : candidates) {
        double matchScore = place.getPlaceTagMaps().stream()
                .map(m -> m.getTag().getName())
                .mapToDouble(tag -> userPreferences.getOrDefault(tag, 0.0)).sum();
 
        if (matchScore <= 0) matchScore = 0.1;
 
        // 지수 시간 감쇠 공식: exp(-0.05 * 경과일수) 적용 (최신 등록 핫플레이스 가산점)
        long days = place.getCreatedAt() != null ? Duration.between(place.getCreatedAt(), now).toDays() : 0;
        double timeDecay = Math.exp(-0.05 * Math.max(0, days));
        double finalScore = matchScore * timeDecay;
 
        scoredPlaces.add(new ScoredPlace(place, finalScore, matchScore));
    }
 
    // 5. 최종 고득점 순으로 12개 장소를 추려 개인화 하이브리드 결과 반환
    List<PlaceSummaryResponse> recommended = scoredPlaces.stream()
            .sorted(Comparator.comparingDouble(ScoredPlace::finalScore).reversed())
            .limit(12)
            .map(sp -> PlaceSummaryResponse.from(sp.place(), false, null))
            .toList();
 
    return new RecommendationResponse("PERSONALIZED_HYBRID", primaryMood, recommended);
}

// backend/src/main/java/com/pickpl/app/place/service/RecommendationService.java
private String calculateDistanceStr(Place place, Double userLat, Double userLon) {
    if (userLat == null || userLon == null || place.getLatitude() == null || place.getLongitude() == null) {
        return null;
    }
    double theta = userLon - place.getLongitude();
    double dist = Math.sin(Math.toRadians(userLat)) * Math.sin(Math.toRadians(place.getLatitude()))
            + Math.cos(Math.toRadians(userLat)) * Math.cos(Math.toRadians(place.getLatitude())) * Math.cos(Math.toRadians(theta));
    dist = Math.acos(dist);
    dist = Math.toDegrees(dist);
    dist = dist * 60 * 1.1515 * 1.609344; // 킬로미터 단위 정교화
    
    if (dist < 1.0) {
        return String.format("내 위치에서 %d" + "m", (int)(dist * 1000));
    } else {
        return String.format("내 위치에서 %.1f" + "km", dist);
    }
}

  [users (마스터 계정)] 1 ------- * [social_connection (소셜 정보 맵핑)]
    - id (PK)                         - social_connection_id (PK)
    - email (동일 이메일 확인)        - user_id (FK)
    - provider (최초 가입 정보)       - provider (GOOGLE, KAKAO, NAVER)
                                      - provider_id

// backend/src/main/java/com/pickpl/app/security/oauth2/CustomOAuth2UserService.java
// ...
if (linkUserId != null) {
    // 1. 세션 기반 수동 계정 연동 프로세스
    Long userId = Long.valueOf(linkUserId);
    user = userRepository.findById(userId).orElseThrow(() -> new OAuth2AuthenticationException("존재하지 않는 유저입니다."));
    
    if (socialConnectionRepository.existsByProviderAndProviderId(providerStr, providerId)) {
        throw new OAuth2AuthenticationException("이미 다른 계정에 연결되어 있는 소셜 계정입니다.");
    }
    
    SocialConnection newConn = SocialConnection.builder().user(user).provider(providerStr).providerId(providerId).build();
    socialConnectionRepository.save(newConn);
} else {
    // 2. 로그인 시점 소셜 연동 여부 조회
    Optional<SocialConnection> socialConnOpt = socialConnectionRepository.findByProviderAndProviderId(providerStr, providerId);
    if (socialConnOpt.isPresent()) {
        user = socialConnOpt.get().getUser(); // 연동된 계정으로 로그인 허용
    } else {
        // 3. 동일 이메일의 로컬(LOCAL) 회원이 존재하는 경우 자동 연동(Auto-Link) 처리
        String email = oAuth2UserInfo.getEmail();
        Optional<User> localUserOpt = userRepository.findByEmail(email);
        if (localUserOpt.isPresent() && localUserOpt.get().getProvider() == AuthProvider.LOCAL) {
            User localUser = localUserOpt.get();
            SocialConnection newConn = SocialConnection.builder().user(localUser).provider(providerStr).providerId(providerId).build();
            socialConnectionRepository.save(newConn);
            user = localUser;
        } else {
            user = registerNewUser(provider, oAuth2UserInfo); // 신규 가입
        }
    }
}

// backend/src/main/java/com/pickpl/app/place/controller/InternalPlaceController.java
@RestController
@RequestMapping("/api/v1/internal/places")
@RequiredArgsConstructor
public class InternalPlaceController {
 
    private final PlaceService placeService;
    private final com.pickpl.app.security.admin.AdminKeyService adminKeyService;
 
    @Operation(summary = "장소 대량 등록", description = "Python 크롤러가 수집한 데이터를 대량 등록합니다. (Admin Secret Key 필요)")
    @PostMapping("/batch")
    public ResponseEntity<String> batchInsertPlaces(
            @RequestHeader("X-Admin-Secret-Key") String requestSecretKey,
            @RequestBody PlaceBatchRequest request) {
 
        if (!adminKeyService.getAdminKey().equals(requestSecretKey)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("유효하지 않은 어드민 키입니다.");
        }
 
        int savedCount = placeService.saveBatch(request);
        return ResponseEntity.ok("성공적으로 " + savedCount + "개의 장소가 저장되었습니다.");
    }
}

# data-pipeline/analyzer/gemini_client.py
from pydantic import BaseModel, Field
from google import genai
from google.genai import types
 
# Pydantic을 활용한 Gemini Structured Output 스키마 정의
class PlaceAnalysis(BaseModel):
    externalId: str = Field(description="장소의 고유 식별자(externalId)")
    category: str = Field(description="1차 카테고리 대분류. '음식점', '카페/디저트', '술집', '자연명소', '문화/체험' 중 하나")
    subCategory: str = Field(description="2차 카테고리 소분류")
    aiMoodSummary: str = Field(description="장소의 분위기를 반영한 큐레이터 한 줄 추천 문구")
    moodTags: list[str] = Field(description="감성 분위기 태그")
    facilityTags: list[str] = Field(description="시설/편의 태그")
    weatherTags: list[str] = Field(description="날씨/상황 태그")
 
class BatchAnalysisResponse(BaseModel):
    places: list[PlaceAnalysis] = Field(description="분석된 장소 결과 목록")
 
# Gemini 일괄 분석 호출부
def analyze_places_batch(self, places: list[dict], batch_size: int = 3):
    # Pydantic schema를 response_schema에 주입하여 구조화 JSON 수신 강제화
    response = self.client.models.generate_content(
        model=self.model_name,
        contents=contents,
        config=types.GenerateContentConfig(
            system_instruction=SYSTEM_PROMPT,
            response_mime_type="application/json",
            response_schema=BatchAnalysisResponse,
            temperature=0.2,
        ),
    )
    return response.text