[Feat] Api Limit — 외부 API 일일 호출 한도 가드 + 누적 비용 알림

linktrip-application/src/main/kotlin/com/linktrip/application/domain/notification/CostAlertEvent.kt

@@ -0,0 +1,13 @@
+package com.linktrip.application.domain.notification
+
+import com.linktrip.application.domain.quota.ApiCostBreakdown
+import java.time.LocalDate
+
+/**
+ * 외부 API 누적 비용이 임계값(1000원 단위)을 새로 넘었을 때 발송되는 알림 이벤트.
+ */
+data class CostAlertEvent(
+    val date: LocalDate,
+    val thresholdKrw: Long,
+    val breakdown: ApiCostBreakdown,
+)

linktrip-application/src/main/kotlin/com/linktrip/application/domain/quota/ApiCallCount.kt

@@ -0,0 +1,31 @@
+package com.linktrip.application.domain.quota
+
+import com.linktrip.application.domain.common.IdGenerator
+import java.time.LocalDate
+import java.time.LocalDateTime
+
+/**
+ * 특정 [apiType] 의 [callDate] 일자 호출 누적 카운트.
+ * UPSERT 의 UPDATE 경로에서는 SQL 측 `call_count + 1` 로 누적되며 [callCount] 값은 사용되지 않는다.
+ */
+data class ApiCallCount(
+    val id: String,
+    val apiType: ApiType,
+    val callDate: LocalDate,
+    val callCount: Long,
+    val createdAt: LocalDateTime = LocalDateTime.now(),
+    val updatedAt: LocalDateTime = LocalDateTime.now(),
+) {
+    companion object {
+        fun create(
+            apiType: ApiType,
+            callDate: LocalDate,
+        ): ApiCallCount =
+            ApiCallCount(
+                id = IdGenerator.generate(),
+                apiType = apiType,
+                callDate = callDate,
+                callCount = 1L,
+            )
+    }
+}

linktrip-application/src/main/kotlin/com/linktrip/application/domain/quota/ApiCallCounterService.kt

@@ -0,0 +1,78 @@
+package com.linktrip.application.domain.quota
+
+import com.linktrip.application.domain.notification.CostAlertEvent
+import com.linktrip.application.port.output.notification.NotificationPort
+import com.linktrip.application.port.output.quota.ApiCallCountPersistencePort
+import com.linktrip.application.port.output.quota.ApiCostPolicyPort
+import com.linktrip.application.port.output.quota.ApiDailyCostAlertPersistencePort
+import mu.KotlinLogging
+import org.springframework.stereotype.Service
+import java.time.LocalDate
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * 외부 API 호출 성공 시의 부수 처리 (카운트 적재 + 누적 비용 임계값 알림) 를 담당한다.
+ *
+ * 서비스 레이어에서 호출 직후 한 줄로 호출:
+ * ```
+ * val r = port.callApi(...)
+ * apiCallCounterService.recordSuccess(ApiType.X)
+ * ```
+ *
+ * 실패 처리 정책:
+ * - **카운트 실패는 그대로 throw**. 카운트가 실제 호출 수와 어긋나면 가드가 한도 초과를 감지 못 해 비용 폭주 위험.
+ *   본 PR 의 핵심 가치 (비용 보호) 를 지키려면 fail-loud 가 맞다.
+ * - **알림 실패는 로그만**. 알림이 늦어져도 가드는 정상 작동하므로 비용 보호에는 영향 없음.
+ */
+@Service
+class ApiCallCounterService(
+    private val countPort: ApiCallCountPersistencePort,
+    private val costPolicyPort: ApiCostPolicyPort,
+    private val alertPort: ApiDailyCostAlertPersistencePort,
+    private val notificationPort: NotificationPort,
+) {
+    fun recordSuccess(apiType: ApiType) {
+        countPort.increment(ApiCallCount.create(apiType, LocalDate.now()))
+
+        try {
+            notifyIfCostThresholdCrossed()
+        } catch (e: Exception) {
+            logger.warn(e) { "비용 알림 체크 실패: $apiType" }
+        }
+    }
+
+    private fun notifyIfCostThresholdCrossed() {
+        val today = LocalDate.now()
+        val breakdown = computeCostBreakdown(today)
+        val lastSent = alertPort.findLastSentThresholdKrw(today) ?: 0L
+
+        if (breakdown.totalKrw < lastSent + THRESHOLD_KRW) return
+
+        val newThreshold = (breakdown.totalKrw / THRESHOLD_KRW) * THRESHOLD_KRW
+        notificationPort.sendCostAlert(
+            CostAlertEvent(
+                date = today,
+                thresholdKrw = newThreshold,
+                breakdown = breakdown,
+            ),
+        )
+        alertPort.upsert(ApiDailyCostAlert.create(today, newThreshold))
+        logger.info { "비용 임계값 알림 발송: total=${breakdown.totalKrw}원, threshold=${newThreshold}원" }
+    }
+
+    private fun computeCostBreakdown(date: LocalDate): ApiCostBreakdown {
+        val countByApi = countPort.findAllByDate(date).associateBy { it.apiType }
+        val items =
+            ApiType.entries.map { apiType ->
+                val count = countByApi[apiType]?.callCount ?: 0L
+                ApiCostItem(apiType, count * costPolicyPort.perCallKrw(apiType))
+            }
+        return ApiCostBreakdown(items)
+    }
+
+    companion object {
+        /** 알림 임계값 단위 (KRW). 1000원마다 한 번 발송. */
+        private const val THRESHOLD_KRW = 1000L
+    }
+}

linktrip-application/src/main/kotlin/com/linktrip/application/domain/quota/ApiCostBreakdown.kt

@@ -0,0 +1,19 @@
+package com.linktrip.application.domain.quota
+
+/**
+ * 특정 일자의 API 별 누적 비용 (KRW) 분해.
+ * 합계 / 0원 제외 필터 등 표현/판정 로직을 도메인에 포함.
+ */
+data class ApiCostBreakdown(
+    val items: List<ApiCostItem>,
+) {
+    val totalKrw: Long = items.sumOf { it.costKrw }
+
+    /** 비용 0원인 API 는 제외 (Discord 메시지에 노출할 항목만). */
+    fun nonZero(): List<ApiCostItem> = items.filter { it.costKrw > 0L }
+}
+
+data class ApiCostItem(
+    val apiType: ApiType,
+    val costKrw: Long,
+)

linktrip-application/src/main/kotlin/com/linktrip/application/domain/quota/ApiDailyCostAlert.kt

@@ -0,0 +1,29 @@
+package com.linktrip.application.domain.quota
+
+import com.linktrip.application.domain.common.IdGenerator
+import java.time.LocalDate
+import java.time.LocalDateTime
+
+/**
+ * 일자별로 마지막으로 발송한 비용 알림 임계값 (KRW).
+ * 같은 임계값 구간에 대해 알림이 두 번 나가지 않게 추적하는 용도.
+ */
+data class ApiDailyCostAlert(
+    val id: String,
+    val alertDate: LocalDate,
+    val lastSentThresholdKrw: Long,
+    val createdAt: LocalDateTime = LocalDateTime.now(),
+    val updatedAt: LocalDateTime = LocalDateTime.now(),
+) {
+    companion object {
+        fun create(
+            alertDate: LocalDate,
+            lastSentThresholdKrw: Long,
+        ): ApiDailyCostAlert =
+            ApiDailyCostAlert(
+                id = IdGenerator.generate(),
+                alertDate = alertDate,
+                lastSentThresholdKrw = lastSentThresholdKrw,
+            )
+    }
+}

linktrip-application/src/main/kotlin/com/linktrip/application/domain/quota/ApiQuotaGuardService.kt

@@ -0,0 +1,36 @@
+package com.linktrip.application.domain.quota
+
+import com.linktrip.application.port.output.quota.ApiCallCountPersistencePort
+import com.linktrip.application.port.output.quota.ApiQuotaPolicyPort
+import com.linktrip.common.exception.ExceptionCode
+import com.linktrip.common.exception.LinktripException
+import mu.KotlinLogging
+import org.springframework.stereotype.Service
+import java.time.LocalDate
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * 외부 API 일일 호출 한도 가드.
+ * 서비스 레이어에서 호출 직전 [isExceeded] 로 체크, 큐 컨슈머는 [isAnyApiExceeded] 로 dequeue 차단.
+ * 자정 지나면 [LocalDate.now] 가 바뀌어 자동 해제.
+ */
+@Service
+class ApiQuotaGuardService(
+    private val countPort: ApiCallCountPersistencePort,
+    private val policyPort: ApiQuotaPolicyPort,
+) {
+    fun isAnyApiExceeded(): Boolean = ApiType.entries.any { isExceeded(it) }
+
+    fun isExceeded(apiType: ApiType): Boolean {
+        val limit =
+            policyPort.dailyLimit(apiType)
+                ?: throw LinktripException(ExceptionCode.INTERNAL_QUOTA_POLICY_NOT_CONFIGURED)
+        val current = countPort.findByApiTypeAndDate(apiType, LocalDate.now())?.callCount ?: 0L
+        val exceeded = current >= limit
+        if (exceeded) {
+            logger.warn { "$apiType 일일 한도 초과: 현재=$current / 한도=$limit" }
+        }
+        return exceeded
+    }
+}

linktrip-application/src/main/kotlin/com/linktrip/application/domain/quota/ApiType.kt

@@ -0,0 +1,16 @@
+package com.linktrip.application.domain.quota
+
+/**
+ * 비용 통제가 필요한 외부 API 종류.
+ * 새 외부 API 도입 시 enum 값 + properties 의 daily-quota / cost-per-call 항목 추가.
+ */
+enum class ApiType {
+    /** Google Vertex AI Gemini — 토큰 기반 종량제 */
+    GEMINI,
+
+    /** YouTube Data API v3 — 일일 quota */
+    YOUTUBE_DATA,
+
+    /** Google Places Text Search — 호출당 과금 */
+    GOOGLE_PLACES,
+}

linktrip-application/src/main/kotlin/com/linktrip/application/domain/trip/TripPlanService.kt

@@ -13,8 +13,10 @@ import com.linktrip.application.port.output.persistence.TripPlanPersistencePort
 import com.linktrip.application.port.output.persistence.TripPlanRequestPersistencePort
 import com.linktrip.common.exception.ExceptionCode
 import com.linktrip.common.exception.LinktripException
+import org.springframework.beans.factory.annotation.Value
 import org.springframework.stereotype.Service
 import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDate
 import java.time.LocalDateTime
 
 @Service
@@ -24,16 +26,30 @@ class TripPlanService(
     private val itineraryItemPort: TravelItineraryItemPersistencePort,
     private val requestPort: TripPlanRequestPersistencePort,
     private val hashtagPort: HashtagPersistencePort,
+    @Value("\${member.daily-video-analyze-limit:10}")
+    private val dailyVideoAnalyzeLimit: Long,
 ) : TripPlanUseCase {
     @Transactional
     override fun registerRequest(
         memberId: String,
         videoAnalysisTaskId: String,
     ) {
         if (requestPort.existsByMemberIdAndVideoAnalysisTaskId(memberId, videoAnalysisTaskId)) return
+        ensureDailyVideoAnalyzeLimitNotExceeded(memberId)
         requestPort.save(TripPlanRequest.create(memberId, videoAnalysisTaskId))
     }
 
+    private fun ensureDailyVideoAnalyzeLimitNotExceeded(memberId: String) {
+        val today = LocalDate.now()
+        val count = requestPort.countByMemberIdAndDate(memberId, today)
+        if (count >= dailyVideoAnalyzeLimit) {
+            throw LinktripException(
+                ExceptionCode.TOO_MANY_REQUESTS_VIDEO_ANALYZE_DAILY,
+                "오늘 영상 분석 요청 한도($count/$dailyVideoAnalyzeLimit) 초과",
+            )
+        }
+    }
+
     @Transactional
     override fun createFromAnalysisIfAbsent(
         memberId: String,

linktrip-application/src/main/kotlin/com/linktrip/application/domain/video/VideoAnalysisQueueConsumer.kt

@@ -1,5 +1,6 @@
 package com.linktrip.application.domain.video
 
+import com.linktrip.application.domain.quota.ApiQuotaGuardService
 import com.linktrip.application.domain.trip.TripPlanService
 import com.linktrip.application.port.output.external.VideoAnalysisNotificationPort
 import com.linktrip.application.port.output.external.VideoAnalyzePort
@@ -26,6 +27,7 @@ class VideoAnalysisQueueConsumer(
     private val tripPlanRequestPort: TripPlanRequestPersistencePort,
     private val tripPlanService: TripPlanService,
     private val rateLimitBucketStore: RateLimitBucketStore,
+    private val apiQuotaGuardService: ApiQuotaGuardService,
 ) {
     fun startConsuming() {
         Thread({ consumeLoop() }, "VideoAnalysisQueueConsumer").apply {
@@ -38,6 +40,11 @@ class VideoAnalysisQueueConsumer(
     private fun consumeLoop() {
         while (!Thread.currentThread().isInterrupted) {
             try {
+                if (apiQuotaGuardService.isAnyApiExceeded()) {
+                    logger.warn { "외부 API 일일 한도 초과 — ${QUOTA_BACKOFF_MS / 1000}초 대기" }
+                    Thread.sleep(QUOTA_BACKOFF_MS)
+                    continue
+                }
                 val event = videoAnalysisQueuePort.dequeue() ?: continue
                 processAnalysis(event)
             } catch (_: InterruptedException) {
@@ -209,5 +216,8 @@ class VideoAnalysisQueueConsumer(
 
     companion object {
         private const val RATE_LIMIT_KEY = "gemini-api"
+
+        /** API 한도 초과 시 다음 가드 체크까지 대기 시간. 자정 후 재개 지연 / 로그 노이즈 절충. */
+        private const val QUOTA_BACKOFF_MS = 60_000L
     }
 }

linktrip-application/src/main/kotlin/com/linktrip/application/port/output/notification/NotificationPort.kt

@@ -1,5 +1,6 @@
 package com.linktrip.application.port.output.notification
 
+import com.linktrip.application.domain.notification.CostAlertEvent
 import com.linktrip.application.domain.notification.ExceptionAlertEvent
 
 /**
@@ -8,4 +9,6 @@ import com.linktrip.application.domain.notification.ExceptionAlertEvent
  */
 interface NotificationPort {
     fun sendExceptionAlert(event: ExceptionAlertEvent)
+
+    fun sendCostAlert(event: CostAlertEvent)
 }

linktrip-application/src/main/kotlin/com/linktrip/application/port/output/persistence/TripPlanRequestPersistencePort.kt

@@ -1,6 +1,7 @@
 package com.linktrip.application.port.output.persistence
 
 import com.linktrip.application.domain.trip.TripPlanRequest
+import java.time.LocalDate
 
 interface TripPlanRequestPersistencePort {
     fun save(request: TripPlanRequest): TripPlanRequest
@@ -15,4 +16,9 @@ interface TripPlanRequestPersistencePort {
     fun findMemberIdsByVideoAnalysisTaskId(videoAnalysisTaskId: String): List<String>
 
     fun saveAll(requests: List<TripPlanRequest>)
+
+    fun countByMemberIdAndDate(
+        memberId: String,
+        date: LocalDate,
+    ): Long
 }

linktrip-application/src/main/kotlin/com/linktrip/application/port/output/quota/ApiCallCountPersistencePort.kt

@@ -0,0 +1,20 @@
+package com.linktrip.application.port.output.quota
+
+import com.linktrip.application.domain.quota.ApiCallCount
+import com.linktrip.application.domain.quota.ApiType
+import java.time.LocalDate
+
+/**
+ * 일별 API 호출 카운트 영속화 포트.
+ * 구현체는 (api_type, call_date) 단일 row 를 유지하며 호출 횟수를 atomic 하게 +1 한다.
+ */
+interface ApiCallCountPersistencePort {
+    fun increment(apiCallCount: ApiCallCount)
+
+    fun findByApiTypeAndDate(
+        apiType: ApiType,
+        date: LocalDate,
+    ): ApiCallCount?
+
+    fun findAllByDate(date: LocalDate): List<ApiCallCount>
+}

linktrip-application/src/main/kotlin/com/linktrip/application/port/output/quota/ApiCostPolicyPort.kt

@@ -0,0 +1,11 @@
+package com.linktrip.application.port.output.quota
+
+import com.linktrip.application.domain.quota.ApiType
+
+/**
+ * API 별 호출 1회당 추정 비용 (KRW). yml 등 외부 소스에서 제공.
+ * 0 = 비용 추적 비활성 (구현체는 항상 non-null Long 을 반환).
+ */
+interface ApiCostPolicyPort {
+    fun perCallKrw(apiType: ApiType): Long
+}

linktrip-application/src/main/kotlin/com/linktrip/application/port/output/quota/ApiDailyCostAlertPersistencePort.kt

@@ -0,0 +1,14 @@
+package com.linktrip.application.port.output.quota
+
+import com.linktrip.application.domain.quota.ApiDailyCostAlert
+import java.time.LocalDate
+
+/**
+ * 일자별로 마지막으로 알림 발송한 누적 비용 임계값을 추적한다.
+ * 같은 임계값(예: 5000원) 에 대해 알림이 한 번만 발송되도록 함.
+ */
+interface ApiDailyCostAlertPersistencePort {
+    fun findLastSentThresholdKrw(date: LocalDate): Long?
+
+    fun upsert(alert: ApiDailyCostAlert)
+}

linktrip-application/src/main/kotlin/com/linktrip/application/port/output/quota/ApiQuotaPolicyPort.kt

@@ -0,0 +1,11 @@
+package com.linktrip.application.port.output.quota
+
+import com.linktrip.application.domain.quota.ApiType
+
+/**
+ * API 별 일일 호출 한도 정책 (yml 등 외부 소스에서 제공).
+ * null = 한도 미설정 = 가드 비활성.
+ */
+interface ApiQuotaPolicyPort {
+    fun dailyLimit(apiType: ApiType): Long?
+}