<?php

namespace Modules\LandedCost\Entities\Drivers;

use Illuminate\Support\Collection;
use Modules\LandedCost\Entities\LcExpense;

/**
 * A driver adapts a concrete "parent" (a PurchaseRequisition share, a core Purchase,
 * or a core Purchase Order) to the generic landed-cost engine. It knows how to
 * resolve the parent's purchase lines, how to read each line's base price + currency,
 * where to persist the resulting landed cost, and which currency options to offer.
 */
interface LandedCostDriverInterface
{
    /** Abort (403/404) if the current user may not manage landed cost on this parent. */
    public function authorize(): void;

    /** Polymorphic type stored on lc_expenses.parent_type. */
    public function parentType(): string;

    /** Numeric parent id stored on lc_expenses.parent_id. */
    public function parentId(): int;

    /** Owning business id (nullable). */
    public function businessId(): ?int;

    /** The underlying purchase transaction, used as the activity-log subject (nullable). */
    public function subjectModel(): ?\Illuminate\Database\Eloquent\Model;

    /** The purchase lines (App\PurchaseLine) the expense is distributed across. */
    public function getLines(): Collection;

    /** Symbol of the base currency the expense base_amount is expressed in. */
    public function baseSymbol(): string;

    /** Currency options for the modal: [['id','name','symbol','rate'], ...]. */
    public function currencyOptions(): array;

    /**
     * Enrich one engine distribution row (for a line) into a preview row with
     * base price, per-unit expense, and resulting landed cost.
     *
     * @param  array  $row   one row from LandedCostDistributionService::buildDistributions()
     * @param  mixed  $line  the matching App\PurchaseLine
     */
    public function buildPreviewRow(array $row, $line): array;

    /** Recompute and persist landed cost for every line, across all current expenses. */
    public function recalculateLandedCosts(): void;

    /** Landed cost per line for the frontend, keyed by purchase_line_id. */
    public function getLandedCostData(): array;
}
