feat: 채널 추천 결과 저장 API 구현

src/main/java/chaeso/zip/server/auth/infrastructure/security/SecurityConfig.java

@@ -11,6 +11,7 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.core.annotation.Order;
+import org.springframework.http.HttpMethod;
 import org.springframework.http.HttpStatus;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
@@ -48,10 +49,13 @@ public class SecurityConfig {
       "/api/v1/channels/*",
       "/api/v1/onboarding",
       "/api/v1/onboarding/ad-history/presigned-urls",
-      "/api/v1/recommendations",
       "/api/v1/simulations/estimate"
   };
 
+  private static final String[] PUBLIC_GET_PATHS = {
+      "/api/v1/recommendations"
+  };
+
   private final JwtTokenProvider jwtTokenProvider;
   private final ObjectMapper objectMapper;
   private final CorsProperties corsProperties;
@@ -80,6 +84,7 @@ SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
             session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
         .authorizeHttpRequests(authorize -> authorize
             .requestMatchers(PUBLIC_PATHS).permitAll()
+            .requestMatchers(HttpMethod.GET, PUBLIC_GET_PATHS).permitAll()
             .anyRequest().authenticated())
         .exceptionHandling(exception ->
             exception.authenticationEntryPoint(authenticationEntryPoint()))

src/main/java/chaeso/zip/server/common/config/ResponseWrapperSchemaCustomizer.java

@@ -0,0 +1,48 @@
+package chaeso.zip.server.common.config;
+
+import chaeso.zip.server.common.response.ApiResponse;
+import io.swagger.v3.oas.models.media.Schema;
+import java.util.Map;
+import org.springdoc.core.customizers.OpenApiCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class ResponseWrapperSchemaCustomizer {
+
+  private static final String WRAPPER = ApiResponse.class.getSimpleName();
+  private static final String VOID_WRAPPER = WRAPPER + "Void";
+  private static final String DATA = "data";
+  private static final String ERROR = "error";
+
+  @Bean
+  public OpenApiCustomizer responseWrapperRequiredFields() {
+    return openApi -> {
+      Map<String, Schema> schemas = openApi.getComponents().getSchemas();
+      if (schemas == null) {
+        return;
+      }
+      schemas.forEach((name, schema) -> {
+        if (carriesPayload(name)) {
+          require(schema, DATA);
+        } else if (name.equals(WRAPPER)) {
+          require(schema, ERROR);
+        }
+      });
+    };
+  }
+
+  private boolean carriesPayload(String schemaName) {
+    return schemaName.startsWith(WRAPPER)
+        && !schemaName.equals(WRAPPER)
+        && !schemaName.equals(VOID_WRAPPER);
+  }
+
+  private void require(Schema<?> schema, String field) {
+    boolean present = schema.getProperties() != null && schema.getProperties().containsKey(field);
+    boolean alreadyRequired = schema.getRequired() != null && schema.getRequired().contains(field);
+    if (present && !alreadyRequired) {
+      schema.addRequiredItem(field);
+    }
+  }
+}

src/main/java/chaeso/zip/server/onboarding/domain/repository/OnboardingRepository.java

@@ -1,14 +1,23 @@
 package chaeso.zip.server.onboarding.domain.repository;
 
 import chaeso.zip.server.onboarding.domain.entity.Onboarding;
+import jakarta.persistence.LockModeType;
 import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Lock;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 
 /**
  * 온보딩 응답 리포지토리 인터페이스.
  */
 public interface OnboardingRepository extends JpaRepository<Onboarding, UUID> {
 
   List<Onboarding> findByUserIdAndIsActiveTrue(UUID userId);
+
+  @Lock(LockModeType.PESSIMISTIC_WRITE)
+  @Query("select o from Onboarding o where o.id = :onboardingId")
+  Optional<Onboarding> findByIdForUpdate(@Param("onboardingId") UUID onboardingId);
 }

src/main/java/chaeso/zip/server/recommendation/application/RecommendationService.java

@@ -1,6 +1,7 @@
 package chaeso.zip.server.recommendation.application;
 
 import chaeso.zip.server.recommendation.application.dto.RecommendationItemResponse;
+import chaeso.zip.server.recommendation.application.dto.SavedRecommendationResponse;
 import java.util.List;
 import java.util.UUID;
 
@@ -10,4 +11,12 @@ public interface RecommendationService {
    * 온보딩 응답에 맞는 채널을 적합도 순으로 추천한다.
    */
   List<RecommendationItemResponse> recommend(UUID onboardingId);
+
+  /**
+   * 추천 결과를 추천 시점 값 그대로 저장한다. 같은 온보딩으로 다시 저장하면 이전 것을 덮어쓴다.
+   *
+   * @param userId       저장하는 사용자
+   * @param onboardingId 추천의 근거가 된 온보딩. 저장된 추천 1건을 가리키는 키가 된다
+   */
+  SavedRecommendationResponse save(UUID userId, UUID onboardingId);
 }

src/main/java/chaeso/zip/server/recommendation/application/RecommendationServiceImpl.java

@@ -6,6 +6,7 @@
 import chaeso.zip.server.channel.domain.repository.ChannelPricingRepository;
 import chaeso.zip.server.channel.domain.repository.ChannelProductRepository;
 import chaeso.zip.server.channel.domain.repository.ChannelRepository;
+import chaeso.zip.server.channel.domain.vo.PricingModel;
 import chaeso.zip.server.estimation.application.DefaultCtrProvider;
 import chaeso.zip.server.estimation.domain.EstimationService;
 import chaeso.zip.server.estimation.domain.RepresentativeProduct;
@@ -16,16 +17,22 @@
 import chaeso.zip.server.onboarding.domain.entity.Onboarding;
 import chaeso.zip.server.onboarding.domain.repository.OnboardingRepository;
 import chaeso.zip.server.recommendation.application.dto.RecommendationItemResponse;
+import chaeso.zip.server.recommendation.application.dto.SavedRecommendationResponse;
 import chaeso.zip.server.recommendation.domain.ChannelMatcher;
 import chaeso.zip.server.recommendation.domain.MatchScore;
+import chaeso.zip.server.recommendation.domain.RecommendationSnapshot;
+import chaeso.zip.server.recommendation.domain.entity.ChannelRecommendation;
+import chaeso.zip.server.recommendation.domain.repository.ChannelRecommendationRepository;
 import java.math.BigDecimal;
 import java.math.RoundingMode;
 import java.util.Comparator;
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 import java.util.stream.Collectors;
+import java.util.stream.IntStream;
 import lombok.RequiredArgsConstructor;
+import org.springframework.dao.DataIntegrityViolationException;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -36,28 +43,102 @@ public class RecommendationServiceImpl implements RecommendationService {
 
   static final int MAX_ITEMS = 8;
 
+  /** 추천 순위의 시작 번호 */
+  private static final int FIRST_RANK = 1;
+
   /**
    * 추천 순서
    */
-  private static final Comparator<Recommendation> BEST_FIRST = Comparator
-      .comparingInt((Recommendation recommendation) -> recommendation.score().score()).reversed()
-      .thenComparing(recommendation -> recommendation.item().isExecutable(),
-          Comparator.reverseOrder())
-      .thenComparing(recommendation -> recommendation.item().channelName());
+  private static final Comparator<Scored> BEST_FIRST = Comparator
+      .comparingInt((Scored scored) -> scored.score().score()).reversed()
+      .thenComparing(scored -> scored.snapshot().isExecutable(), Comparator.reverseOrder())
+      .thenComparing(scored -> scored.snapshot().channelName());
 
   private final OnboardingRepository onboardingRepository;
   private final ChannelRepository channelRepository;
   private final ChannelProductRepository channelProductRepository;
   private final ChannelPricingRepository channelPricingRepository;
+  private final ChannelRecommendationRepository channelRecommendationRepository;
   private final DefaultCtrProvider defaultCtrProvider;
 
   @Override
   public List<RecommendationItemResponse> recommend(UUID onboardingId) {
-    Onboarding onboarding = onboardingRepository.findById(onboardingId)
+    return calculate(findOnboarding(onboardingId)).stream()
+        .map(RecommendationItemResponse::from)
+        .toList();
+  }
+
+  /**
+   * 추천 결과를 스냅샷으로 저장한다.
+   */
+  @Override
+  @Transactional
+  public SavedRecommendationResponse save(UUID userId, UUID onboardingId) {
+    Onboarding onboarding = findOwnedOnboarding(userId, onboardingId);
+    List<RecommendationSnapshot> snapshots = calculate(onboarding);
+
+    onboardingRepository.findByIdForUpdate(onboardingId);
+
+    channelRecommendationRepository.deleteByOnboardingId(onboardingId);
+    try {
+      channelRecommendationRepository.saveAll(IntStream.range(0, snapshots.size())
+          .mapToObj(index -> toEntity(userId, onboardingId, FIRST_RANK + index,
+              snapshots.get(index)))
+          .toList());
+      channelRecommendationRepository.flush();
+    } catch (DataIntegrityViolationException e) {
+      throw new OnboardingBusinessException(OnboardingErrorCode.CONCURRENT_SUBMISSION);
+    }
+
+    return SavedRecommendationResponse.of(onboardingId, snapshots);
+  }
+
+  private Onboarding findOnboarding(UUID onboardingId) {
+    return onboardingRepository.findById(onboardingId)
         .orElseThrow(() -> new OnboardingBusinessException(
             OnboardingErrorCode.ONBOARDING_NOT_FOUND,
             "온보딩 정보가 없습니다. id=" + onboardingId));
+  }
+
+  private Onboarding findOwnedOnboarding(UUID userId, UUID onboardingId) {
+    Onboarding onboarding = findOnboarding(onboardingId);
+    if (!userId.equals(onboarding.getUserId())) {
+      throw new OnboardingBusinessException(OnboardingErrorCode.ONBOARDING_NOT_FOUND,
+          "온보딩 정보가 없습니다. id=" + onboardingId);
+    }
+    return onboarding;
+  }
 
+  private ChannelRecommendation toEntity(UUID userId, UUID onboardingId, int rank,
+      RecommendationSnapshot snapshot) {
+    return ChannelRecommendation.builder()
+        .userId(userId)
+        .onboardingId(onboardingId)
+        .channelId(snapshot.channelId())
+        .rank(rank)
+        .score(snapshot.matchRate())
+        .reason(snapshot.reason())
+        .reasonTags(snapshot.reasonTags())
+        .channelName(snapshot.channelName())
+        .estPricingModel(snapshot.pricingModel())
+        .estUnitPrice(snapshot.unitPrice())
+        .estImpressionsMin(snapshot.impressions() == null ? null : snapshot.impressions().min())
+        .estImpressionsMax(snapshot.impressions() == null ? null : snapshot.impressions().max())
+        .estClicksMin(snapshot.clicks() == null ? null : snapshot.clicks().min())
+        .estClicksMax(snapshot.clicks() == null ? null : snapshot.clicks().max())
+        .cpcWon(snapshot.cpcWon())
+        .pricingModelsAll(snapshot.pricingModelNames())
+        .minBudgetWonSnap(snapshot.minBudgetWon())
+        .audienceSummarySnap(snapshot.primaryTarget())
+        .executable(snapshot.isExecutable())
+        .shortfallWon(snapshot.shortfallWon())
+        .build();
+  }
+
+  /**
+   * 온보딩 하나에 대한 채널별 추천을 적합도 순으로 계산한다. 조회와 저장이 같은 결과를 쓴다.
+   */
+  private List<RecommendationSnapshot> calculate(Onboarding onboarding) {
     List<Channel> channels = channelRepository.findByActiveTrue();
     if (channels.isEmpty()) {
       return List.of();
@@ -85,7 +166,7 @@ public List<RecommendationItemResponse> recommend(UUID onboardingId) {
                 defaultCtrPercent))
         .sorted(BEST_FIRST)
         .limit(MAX_ITEMS)
-        .map(Recommendation::item)
+        .map(Scored::snapshot)
         .toList();
   }
 
@@ -97,18 +178,19 @@ private Candidate toCandidate(Onboarding onboarding, Channel channel,
   /**
    * 매칭된 채널 하나에 온보딩 예산·기간을 적용한다.
    */
-  private Recommendation evaluate(Candidate candidate, Onboarding onboarding,
+  private Scored evaluate(Candidate candidate, Onboarding onboarding,
       Map<UUID, List<ChannelPricing>> pricingsByProduct, long budgetWon, int periodDays,
       BigDecimal defaultCtrPercent) {
     Channel channel = candidate.channel();
     MatchScore score = candidate.score();
+    List<PricingModel> pricingModels = pricingModels(candidate, pricingsByProduct);
 
     RepresentativeProduct representative = RepresentativeProduct
         .select(candidate.products(), pricingsByProduct, defaultCtrPercent)
         .orElse(null);
     if (representative == null) {
-      return new Recommendation(score,
-          RecommendationItemResponse.quoteRequired(channel, score, onboarding.getIndustry()));
+      return new Scored(score, RecommendationSnapshot.quoteRequired(channel, score,
+          onboarding.getIndustry(), pricingModels));
     }
 
     long minBudgetWon = minBudgetWon(representative.pricing().value());
@@ -119,13 +201,29 @@ private Recommendation evaluate(Candidate candidate, Onboarding onboarding,
     EstimationResult result =
         EstimationService.estimate(representative.product(), estimationBudgetWon, periodDays);
     if (result == null) {
-      return new Recommendation(score,
-          RecommendationItemResponse.quoteRequired(channel, score, onboarding.getIndustry()));
+      return new Scored(score, RecommendationSnapshot.quoteRequired(channel, score,
+          onboarding.getIndustry(), pricingModels));
     }
 
-    return new Recommendation(score, RecommendationItemResponse.estimated(channel, score,
-        onboarding.getIndustry(), representative.pricing(), result, minBudgetWon, executable,
-        shortfallWon, estimationBudgetWon));
+    return new Scored(score, RecommendationSnapshot.estimated(channel, score,
+        onboarding.getIndustry(), representative.pricing(), pricingModels, result, minBudgetWon,
+        executable, shortfallWon, estimationBudgetWon));
+  }
+
+  /**
+   * 채널이 그 시점에 가지고 있던 과금 방식 전체. 저장 스냅샷에만 쓴다.
+   *
+   * <p>대표 단가로 고르지 못한 상품의 과금 방식도 포함한다. 열거 순서로 정렬해 같은 채널이면 같은
+   * 배열이 되게 한다.
+   */
+  private List<PricingModel> pricingModels(Candidate candidate,
+      Map<UUID, List<ChannelPricing>> pricingsByProduct) {
+    return candidate.products().stream()
+        .flatMap(product -> pricingsByProduct.getOrDefault(product.getId(), List.of()).stream())
+        .map(ChannelPricing::getPricingModel)
+        .distinct()
+        .sorted()
+        .toList();
   }
 
   private Map<UUID, List<ChannelProduct>> productsByChannel(List<Channel> channels) {
@@ -154,6 +252,6 @@ private static long minBudgetWon(BigDecimal price) {
   private record Candidate(Channel channel, List<ChannelProduct> products, MatchScore score) {
   }
 
-  private record Recommendation(MatchScore score, RecommendationItemResponse item) {
+  private record Scored(MatchScore score, RecommendationSnapshot snapshot) {
   }
 }