package com.flightticket.service;

import com.flightticket.dto.billing.UsageLogRequest;
import org.springframework.scheduling.annotation.Async;

/**
 * Service for asynchronously logging API usage data.
 * 
 * This service is responsible for persisting usage records to the Usage_Ledger
 * without blocking the main API call flow. All logging operations are executed
 * asynchronously to maintain performance.
 * 
 * Requirements: 1.5, 1.6, 1.7, 7.1, 7.2, 7.5
 */
public interface UsageLoggerService {
    
    /**
     * Asynchronously logs API usage data to the database.
     * 
     * This method executes in a separate thread pool to avoid blocking the
     * calling API operation. If logging fails, errors are logged but not
     * propagated to the caller.
     * 
     * The method implements retry logic with exponential backoff:
     * - Attempt 1: Immediate (0ms delay)
     * - Attempt 2: 100ms delay
     * - Attempt 3: 400ms delay
     * 
     * After 3 failed attempts, the error is logged and the operation is abandoned.
     * 
     * @param request The usage log request containing all required fields
     * 
     * Requirements:
     * - 1.5: Store usage data to Usage_Ledger
     * - 1.6: Execute logging asynchronously
     * - 1.7: Log errors without throwing exceptions
     * - 7.1: Log errors to application error log
     * - 7.2: Don't throw exceptions to calling code
     * - 7.5: Retry up to 3 times with exponential backoff
     */
    @Async
    void logUsage(UsageLogRequest request);
}