<?php
/**
 * AEAT Next Action
 *
 * Enum-like class defining possible next actions after processing an AEAT response.
 * Each action represents what the plugin (or user) should do next.
 *
 * @package Freefactu
 * @since 1.1.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Class Freefactu_Aeat_Next_Action
 *
 * Defines the possible next actions after receiving an AEAT response.
 * Used by Freefactu_Aeat_Next_Action_Decider to communicate what should happen next.
 */
class Freefactu_Aeat_Next_Action {

	/**
	 * No action needed - invoice was accepted.
	 * AEAT returned status Correct/Accepted.
	 */
	const NO_ACTION_NEEDED = 'no_action_needed';

	/**
	 * Retry as subsanation.
	 * The error is technical (census, XML, hash) and can be fixed.
	 * The same invoice should be corrected and resent with isCorrection = true.
	 *
	 * ONLY applicable to F1, F3, F4 invoices.
	 * NEVER applicable to F2 (cancellation) or already-accepted invoices.
	 */
	const RETRY_SUBSANATION = 'retry_subsanation';

	/**
	 * Create a rectificativa invoice (F3).
	 * The original invoice content is wrong (business error).
	 * A new corrective invoice must be created with type R1-R5.
	 *
	 * This is the ONLY valid solution when:
	 * - Original invoice was already accepted by AEAT
	 * - The error is in the economic content (amounts, VAT, customer)
	 */
	const CREATE_RECTIFICATIVA = 'create_rectificativa';

	/**
	 * Retry with a new F2 (cancellation).
	 * F2 messages CANNOT be subsanated. If a cancellation fails,
	 * you must send a NEW F2, not fix the old one.
	 */
	const RETRY_NEW_F2 = 'retry_new_f2';

	/**
	 * Manual intervention required.
	 * The system cannot automatically determine the correct action.
	 * User must review the error and decide what to do.
	 *
	 * Examples:
	 * - Max subsanation attempts reached
	 * - Unknown error category
	 * - Conflicting states
	 */
	const MANUAL_INTERVENTION = 'manual_intervention';

	/**
	 * Fatal error - stop processing.
	 * An unrecoverable error occurred. No automatic action is possible.
	 * The invoice is marked as failed and user is shown clear error.
	 */
	const SHOW_FATAL_ERROR = 'show_fatal_error';

	/**
	 * Retry client-side validation error.
	 * Errors from josemmo/verifactu-php library before AEAT API call.
	 * Unlimited retries, no snapshot save/load, no subsanation_count.
	 * User should fix the issue and click "Reintentar".
	 */
	const RETRY_CLIENT = 'retry_client';

	/**
	 * Get all action constants.
	 *
	 * @return array List of all action constants.
	 */
	public static function get_all() {
		return array(
			self::NO_ACTION_NEEDED,
			self::RETRY_SUBSANATION,
			self::CREATE_RECTIFICATIVA,
			self::RETRY_NEW_F2,
			self::MANUAL_INTERVENTION,
			self::SHOW_FATAL_ERROR,
			self::RETRY_CLIENT,
		);
	}

	/**
	 * Get human-readable label for an action (Spanish).
	 *
	 * @param string $action The action constant.
	 * @return string Human-readable label in Spanish.
	 */
	public static function get_label( $action ) {
		$labels = array(
			self::NO_ACTION_NEEDED     => __( 'Sin acción necesaria', 'freefactu' ),
			self::RETRY_SUBSANATION    => __( 'Subsanar y reenviar', 'freefactu' ),
			self::CREATE_RECTIFICATIVA => __( 'Crear factura rectificativa', 'freefactu' ),
			self::RETRY_NEW_F2         => __( 'Reintentar anulación', 'freefactu' ),
			self::MANUAL_INTERVENTION  => __( 'Intervención manual requerida', 'freefactu' ),
			self::SHOW_FATAL_ERROR     => __( 'Error irrecuperable', 'freefactu' ),
			self::RETRY_CLIENT         => __( 'Reintentar envío', 'freefactu' ),
		);

		return isset( $labels[ $action ] ) ? $labels[ $action ] : __( 'Acción desconocida', 'freefactu' );
	}

	/**
	 * Get user-facing instruction for an action (Spanish).
	 *
	 * @param string $action The action constant.
	 * @return string Instruction for the user in Spanish.
	 */
	public static function get_instruction( $action ) {
		$instructions = array(
			self::NO_ACTION_NEEDED     => __( 'La factura ha sido aceptada por la AEAT.', 'freefactu' ),
			self::RETRY_SUBSANATION    => __( 'Corrija los datos indicados y pulse "Subsanar" para reenviar a la AEAT.', 'freefactu' ),
			self::CREATE_RECTIFICATIVA => __( 'El contenido de la factura es incorrecto. Debe crear una factura rectificativa (F3) para corregir los importes.', 'freefactu' ),
			self::RETRY_NEW_F2         => __( 'La anulación falló. Revise los datos y envíe una nueva solicitud de anulación.', 'freefactu' ),
			self::MANUAL_INTERVENTION  => __( 'Se requiere intervención manual. Revise el error y decida cómo proceder.', 'freefactu' ),
			self::SHOW_FATAL_ERROR     => __( 'Ha ocurrido un error irrecuperable. Contacte con soporte técnico.', 'freefactu' ),
			self::RETRY_CLIENT         => __( 'Corrija el problema y pulse "Reintentar" para enviar de nuevo.', 'freefactu' ),
		);

		return isset( $instructions[ $action ] ) ? $instructions[ $action ] : '';
	}

	/**
	 * Check if an action requires user interaction.
	 *
	 * @param string $action The action constant.
	 * @return bool True if user must take action.
	 */
	public static function requires_user_action( $action ) {
		return in_array( $action, array(
			self::CREATE_RECTIFICATIVA,
			self::MANUAL_INTERVENTION,
			self::SHOW_FATAL_ERROR,
		), true );
	}

	/**
	 * Check if an action can be retried automatically.
	 *
	 * @param string $action The action constant.
	 * @return bool True if action can be retried.
	 */
	public static function is_retriable( $action ) {
		return in_array( $action, array(
			self::RETRY_SUBSANATION,
			self::RETRY_NEW_F2,
			self::RETRY_CLIENT,
		), true );
	}
}
