Merge pull request #97 from TU-NEBULA/feature/SCRUM-239

SCRUM-239: 추천 시스템 API 구현

Author: m3k0813

src/main/java/com/team_nebula/nebula/domain/recommendation/api/RecommendationController.java

@@ -0,0 +1,69 @@
+package com.team_nebula.nebula.domain.recommendation.api;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.team_nebula.nebula.domain.recommendation.dto.request.RecommendationFeedbackRequestDTO;
+import com.team_nebula.nebula.domain.recommendation.dto.request.SearchBasedRecommendationRequestDTO;
+import com.team_nebula.nebula.domain.recommendation.dto.response.ClusterTrendsResponseDTO;
+import com.team_nebula.nebula.domain.recommendation.dto.response.GeneralRecommendationResponseDTO;
+import com.team_nebula.nebula.domain.recommendation.dto.response.RecommendationFeedbackResponseDTO;
+import com.team_nebula.nebula.domain.recommendation.dto.response.SearchBasedRecommendationResponseDTO;
+import com.team_nebula.nebula.domain.recommendation.service.RecommendationService;
+import com.team_nebula.nebula.global.annotation.AuthUser;
+import com.team_nebula.nebula.global.apipayload.ApiResponse;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequestMapping("/api/v2/recommendations")
+@RequiredArgsConstructor
+@Tag(name = "[추천]")
+public class RecommendationController {
+
+	private final RecommendationService recommendationService;
+
+	@Operation(summary = "전체적인 콘텐츠 추천", description = "사용자 프로파일과 클러스터 분석을 기반으로 전체적인 콘텐츠를 추천하는 API")
+	@GetMapping("/general")
+	public ApiResponse<GeneralRecommendationResponseDTO> generalRecommendation(
+		@AuthUser Long userId,
+		@RequestParam(defaultValue = "10") int limit,
+		@RequestParam(required = false) String category,
+		@RequestParam(defaultValue = "true") boolean excludeViewed,
+		@RequestParam(defaultValue = "true") boolean diversify,
+		@RequestParam(defaultValue = "week") String timeRange) {
+		return ApiResponse.onSuccess(
+			recommendationService.generalRecommendation(userId, limit, category, excludeViewed, diversify, timeRange));
+	}
+
+	@Operation(summary = "검색 기반 실시간 추천", description = "사용자의 검색어를 분석하여 실시간으로 관련 콘텐츠를 추천하는 API")
+	@PostMapping("/search-based")
+	public ApiResponse<SearchBasedRecommendationResponseDTO> searchBasedRecommendation(
+		@AuthUser Long userId,
+		@RequestBody SearchBasedRecommendationRequestDTO request) {
+		return ApiResponse.onSuccess(recommendationService.searchBasedRecommendation(userId, request));
+	}
+
+	@Operation(summary = "클러스터 트렌드 분석", description = "사용자 클러스터별 트렌딩 키워드와 관심사를 분석하는 API")
+	@GetMapping("/cluster-trends")
+	public ApiResponse<ClusterTrendsResponseDTO> clusterTrends(
+		@RequestParam(required = false) Integer clusterId,
+		@RequestParam(defaultValue = "week") String timePeriod,
+		@RequestParam(defaultValue = "true") boolean includeGlobal) {
+		return ApiResponse.onSuccess(recommendationService.clusterTrends(clusterId, timePeriod, includeGlobal));
+	}
+
+	@Operation(summary = "추천 피드백 수집", description = "사용자의 추천 콘텐츠 상호작용을 수집하는 API")
+	@PostMapping("/feedback")
+	public ApiResponse<RecommendationFeedbackResponseDTO> feedback(
+		@AuthUser Long userId,
+		@RequestBody RecommendationFeedbackRequestDTO request) {
+		return ApiResponse.onSuccess(recommendationService.feedback(userId, request));
+	}
+}

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/request/RecommendationFeedbackRequestDTO.java

@@ -0,0 +1,25 @@
+package com.team_nebula.nebula.domain.recommendation.dto.request;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class RecommendationFeedbackRequestDTO {
+	private String recommendationId;
+	private String bookmarkId;
+	private String actionType;
+	private LocalDateTime shownAt;
+	private LocalDateTime actionAt;
+	private String sessionId;
+	private String pageContext;
+	private Integer recommendationPosition;
+	private Integer explicitRating;
+	private Integer engagementTime;
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/request/SearchBasedRecommendationRequestDTO.java

@@ -0,0 +1,29 @@
+package com.team_nebula.nebula.domain.recommendation.dto.request;
+
+import java.util.List;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class SearchBasedRecommendationRequestDTO {
+	private String query;
+
+	@Builder.Default
+	private Integer limit = 10;
+
+	@Builder.Default
+	private Boolean includeSimilarQueries = true;
+
+	@Builder.Default
+	private Boolean boostUserPreferences = true;
+
+	private String sessionId;
+	
+	private List<String> previousQueries;
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/response/ClusterTrendDTO.java

@@ -0,0 +1,30 @@
+package com.team_nebula.nebula.domain.recommendation.dto.response;
+
+import java.util.List;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class ClusterTrendDTO {
+	private Integer clusterId;
+
+	private String clusterName;
+
+	private Integer memberCount;
+
+	private List<TrendingKeywordDTO> trendingKeywords;
+
+	private List<String> popularDomains;
+
+	private List<String> activityPeakHours;
+
+	private List<String> primaryInterests;
+
+	private List<String> emergingTopics;
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/response/ClusterTrendsResponseDTO.java

@@ -0,0 +1,22 @@
+package com.team_nebula.nebula.domain.recommendation.dto.response;
+
+import java.util.List;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class ClusterTrendsResponseDTO {
+	private List<ClusterTrendDTO> clusterTrends;
+
+	private Object globalTrends;
+
+	private String generatedAt;
+
+	private String analysisPeriod;
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/response/GeneralRecommendationResponseDTO.java

@@ -0,0 +1,30 @@
+package com.team_nebula.nebula.domain.recommendation.dto.response;
+
+import java.util.List;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class GeneralRecommendationResponseDTO {
+	private List<RecommendationDTO> recommendations;
+
+	private Long userClusterId;
+
+	private String clusterDescription;
+
+	private Integer totalRecommendations;
+
+	private String generatedAt;
+
+	private String algorithmVersion;
+
+	private Double personalizationScore;
+
+	private Double diversityScore;
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/response/RecommendationDTO.java

@@ -0,0 +1,50 @@
+package com.team_nebula.nebula.domain.recommendation.dto.response;
+
+import java.util.List;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class RecommendationDTO {
+	private String bookmarkId;
+
+	private String title;
+
+	private String url;
+
+	private Double score;
+
+	private String reasonType;
+
+	private ReasonDetailsDTO reasonDetails;
+
+	private String domain;
+
+	private List<String> keywords;
+
+	private String category;
+
+	private String publishedAt;
+
+	private String summary;
+
+	@Getter
+	@Builder
+	@AllArgsConstructor
+	@NoArgsConstructor
+	public static class ReasonDetailsDTO {
+		private String algorithm;
+
+		private Double similarityScore;
+
+		private Double clusterScore;
+
+		private Double popularityScore;
+	}
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/response/RecommendationFeedbackResponseDTO.java

@@ -0,0 +1,18 @@
+package com.team_nebula.nebula.domain.recommendation.dto.response;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class RecommendationFeedbackResponseDTO {
+	private String feedbackId;
+	private Boolean processed;
+	private Double impactScore;
+	private Boolean modelUpdated;
+	private String message;
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/response/SearchBasedRecommendationDTO.java

@@ -0,0 +1,72 @@
+package com.team_nebula.nebula.domain.recommendation.dto.response;
+
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class SearchBasedRecommendationDTO {
+	@JsonProperty("bookmark_id")
+	private String bookmarkId;
+
+	private String title;
+
+	private String url;
+
+	private Double score;
+
+	@JsonProperty("reason_type")
+	private String reasonType;
+
+	@JsonProperty("reason_details")
+	private SearchBasedReasonDetailsDTO reasonDetails;
+
+	private String domain;
+
+	private List<String> keywords;
+
+	private String category;
+
+	@JsonProperty("published_at")
+	private String publishedAt;
+
+	private String summary;
+
+	@Getter
+	@Builder
+	@AllArgsConstructor
+	@NoArgsConstructor
+	public static class SearchBasedReasonDetailsDTO {
+		private String type;
+
+		@JsonProperty("search_query")
+		private String searchQuery;
+
+		@JsonProperty("expanded_keywords")
+		private List<String> expandedKeywords;
+
+		private List<RecommendationFactorDTO> factors;
+
+		private Double confidence;
+	}
+
+	@Getter
+	@Builder
+	@AllArgsConstructor
+	@NoArgsConstructor
+	public static class RecommendationFactorDTO {
+		private String factor;
+
+		private String description;
+
+		private Double weight;
+	}
+} 

src/main/java/com/team_nebula/nebula/domain/recommendation/dto/response/SearchBasedRecommendationResponseDTO.java

@@ -0,0 +1,28 @@
+package com.team_nebula.nebula.domain.recommendation.dto.response;
+
+import java.util.List;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class SearchBasedRecommendationResponseDTO {
+	private List<SearchBasedRecommendationDTO> recommendations;
+
+	private List<String> queryKeywords;
+
+	private List<String> expandedConcepts;
+
+	private String searchIntent;
+
+	private Integer totalRecommendations;
+
+	private Long processingTimeMs;
+
+	private Double similarityThresholdUsed;
+}