<?php
/**
 * PRD 9.7 / 17.3 quantity normalization: string → integer units.
 *
 * Fractional quantities outside adapter support are downgraded to Unknown.
 *
 * @package Kayvandra\MarginBeacon
 */

declare(strict_types=1);

namespace Kayvandra\MarginBeacon\Application\OrderRisk;

/**
 * Normalizes WC decimal quantity to integer units for evaluator arithmetic.
 */
final class QuantityNormalizer {

	/**
	 * Parse a raw WC quantity string into integer units.
	 *
	 * Canonical format matches DECIMAL(12,4): optional sign, up to 8 integer
	 * digits, optional scale of at most 4. Fractional (non-zero) quantities
	 * are invalid. Negative integers stay valid so the evaluator can route
	 * them to credit/MB015.
	 *
	 * @param string $raw Raw quantity from WC_Order_Item::get_quantity().
	 * @return array{valid:bool,units:int,reason:?string}
	 */
	public static function parse( $raw ) {
		$raw = trim( (string) $raw );
		if ( '' === $raw ) {
			return array(
				'valid'  => false,
				'units'  => 0,
				'reason' => 'MB_MONEY_PRECISION_INVALID',
			);
		}

		if ( ! preg_match( '/^-?(?:\d{1,8})(?:\.\d{1,4})?$/', $raw ) ) {
			return array(
				'valid'  => false,
				'units'  => 0,
				'reason' => 'MB_MONEY_PRECISION_INVALID',
			);
		}

		$neg      = '-' === $raw[0];
		$unsigned = $neg ? substr( $raw, 1 ) : $raw;
		$dot_pos  = strpos( $unsigned, '.' );
		if ( false === $dot_pos ) {
			$int_part  = $unsigned;
			$frac_part = '';
		} else {
			$int_part  = substr( $unsigned, 0, $dot_pos );
			$frac_part = rtrim( substr( $unsigned, $dot_pos + 1 ), '0' );
		}

		if ( '' !== $frac_part ) {
			return array(
				'valid'  => false,
				'units'  => 0,
				'reason' => 'MB_MONEY_PRECISION_INVALID',
			);
		}

		$units = (int) $int_part;
		if ( $neg ) {
			$units = -$units;
		}

		return array(
			'valid'  => true,
			'units'  => $units,
			'reason' => null,
		);
	}
}