<?php
/**
 * Coupon discount allocation contract (Free + Pro injectable fallback).
 *
 * @package Kayvandra\MarginBeacon
 */

declare(strict_types=1);

namespace Kayvandra\MarginBeacon\Application\Audit;

use Kayvandra\MarginBeacon\Domain\Money\MoneyAmount;

/**
 * Shared allocator surface for WooCalculationAdapter fallback injection.
 */
interface DiscountAllocatorInterface {

	/**
	 * Allocate discount for one eligible line.
	 *
	 * @param \WC_Coupon  $coupon        Coupon.
	 * @param MoneyAmount $line_subtotal quantity × effective_unit_price.
	 * @param int         $quantity      Integer quantity.
	 * @return array{discount:MoneyAmount,fidelity:string,note:?string}
	 */
	public function allocate_single_line( $coupon, MoneyAmount $line_subtotal, $quantity );

	/**
	 * Multi-line allocation.
	 *
	 * Each line: key, line_subtotal (MoneyAmount), quantity, product_id, variation_id.
	 *
	 * @param \WC_Coupon $coupon Coupon.
	 * @param array      $lines  Lines.
	 * @return array{discounts:array<string,MoneyAmount>,fidelity:string,note:?string}
	 */
	public function allocate_lines( $coupon, array $lines );
}