package com.flightticket.service;

import com.flightticket.client.amadeus.AmadeusModificationRequest;
import com.flightticket.client.amadeus.AmadeusModificationResponse;
import com.flightticket.dto.modification.ModificationCost;
import com.flightticket.exception.AmadeusServiceException;
import com.flightticket.model.entity.Booking;
import com.flightticket.model.entity.ModificationRecord;

import java.util.UUID;

/**
 * Service for executing booking modifications.
 * Handles the submission of modifications to Amadeus API and synchronization of local state.
 * 
 * Requirements: 2.4, 7.3, 7.5
 */
public interface ModificationExecutionService {
    
    /**
     * Submit a modification request to the Amadeus API.
     * 
     * This method:
     * 1. Converts the modification request to Amadeus API format
     * 2. Calls the Amadeus Flight Order Modification endpoint
     * 3. Handles API errors and retries
     * 4. Returns the API response for further processing
     * 
     * @param booking The booking being modified
     * @param modificationRequest The modification details in Amadeus format
     * @return The Amadeus API response containing updated booking details
     * @throws AmadeusServiceException if the API call fails
     * 
     * Requirements: 2.4, 7.3
     */
    AmadeusModificationResponse submitToAmadeus(
        Booking booking,
        AmadeusModificationRequest modificationRequest
    ) throws AmadeusServiceException;
    
    /**
     * Update the local booking record with the modification results from Amadeus API.
     * 
     * This method synchronizes the local database state with the Amadeus API response:
     * 1. Updates booking PNR if changed
     * 2. Updates passenger details if modified
     * 3. Updates flight segments if changed
     * 4. Updates fare information
     * 5. Updates booking status
     * 
     * The update is performed within a transaction to ensure atomicity.
     * 
     * @param booking The booking to update
     * @param amadeusResponse The Amadeus API response containing updated details
     * 
     * Requirements: 7.3, 7.5
     * Property 20: Local State Synchronization
     */
    void updateBookingWithModification(
        Booking booking,
        AmadeusModificationResponse amadeusResponse
    );
    
    /**
     * Create and persist a modification record.
     * 
     * This method:
     * 1. Captures the before-state of the booking (as JSON)
     * 2. Captures the after-state of the booking (as JSON)
     * 3. Records the modification cost and wallet transaction
     * 4. Records the Amadeus confirmation code
     * 5. Sets the modification status
     * 6. Persists the record to the database
     * 
     * The modification record serves as an audit trail and enables
     * modification history queries.
     * 
     * @param booking The booking that was modified
     * @param beforeState The booking state before modification (as JSON map)
     * @param afterState The booking state after modification (as JSON map)
     * @param modificationCost The cost details of the modification
     * @param walletTransactionId The ID of the wallet transaction (if any)
     * @param amadeusConfirmationCode The Amadeus API confirmation code
     * @param agentId The ID of the agent who performed the modification
     * @return The created modification record
     * 
     * Requirements: 2.4, 7.5
     * Property 23: State Change Recording
     */
    ModificationRecord createModificationRecord(
        Booking booking,
        java.util.Map<String, Object> beforeState,
        java.util.Map<String, Object> afterState,
        ModificationCost modificationCost,
        UUID walletTransactionId,
        String amadeusConfirmationCode,
        UUID agentId
    );
}