Skip to content

A free open source IT asset/license management system

20.7 KB
Raw Blame
<?php

namespace App\Models\Traits;

use App\Models\Actionlog;
use App\Models\Order;
use App\Models\OrderItem;
use App\Models\Setting;
use App\Models\Supplier;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Relations\HasManyThrough;
use Illuminate\Database\Eloquent\Relations\MorphMany;

/**
 * Wires an inventory model up to the polymorphic Orders + OrderItems
 * data model. Consumed by Accessory / Consumable / Component (via the
 * AdjustsQuantity flow) and by Asset / License (for historical order
 * lookups even though they don't get replenished per-event).
 *
 * `orderItems()` is the direct polymorphic relation — one row per line
 * on an Order that referenced this model. `orders()` is a
 * HasManyThrough convenience that surfaces the underlying Order rows
 * so free-text search on
 * `$searchableRelations = ['orders' => ['order_number']]` lands on the
 * joined column without the caller having to walk through order_items
 * manually.
 */
trait HasOrders
{
    /**
     * Hook a model lifecycle listener so that force-deleting an
     * inventory row (Accessory / Consumable / Component / Asset /
     * License) soft-deletes every OrderItem pointing at it. Preserves
     * the acquisition ledger — the Order row and its (now-trashed)
     * OrderItem lines remain queryable via `withTrashed()` for
     * historical reports, while ordinary `->orderItems()` reads exclude
     * them. Soft-delete on the parent does not propagate. The Order
     * data model treats a soft-deleted inventory row as still-existing.
     */
    protected static function bootHasOrders(): void
    {
        static::deleting(function ($model) {
            if (! method_exists($model, 'isForceDeleting') || ! $model->isForceDeleting()) {
                return;
            }

            OrderItem::where('item_type', static::class)
                ->where('item_id', $model->id)
                ->delete();
        });
    }

    public function orderItems(): MorphMany
    {
        return $this->morphMany(OrderItem::class, 'item');
    }

    /**
     * HasManyThrough into Orders via the polymorphic order_items pivot.
     * The extra where on order_items.item_type filters the pivot to
     * lines that reference THIS model class, which HasManyThrough on
     * its own can't do because it doesn't understand morph maps.
     */
    public function orders(): HasManyThrough
    {
        return $this->hasManyThrough(
            Order::class,
            OrderItem::class,
            'item_id',   // FK on order_items pointing at model
            'id',        // FK on orders (its primary key)
            'id',        // local key on this model
            'order_id',  // FK on order_items pointing at orders
        )->where('order_items.item_type', static::class);
    }

    /**
     * Count of distinct Orders this item has been *purchased* on. Feeds
     * the info-panel's "Total Orders" row. Filters to lines with
     * positive qty so corrections / consumption events (0- or
     * negative-qty OrderItems) don't inflate the count. Those aren't
     * purchases, and treating them as such was misleading when a
     * lifecycle had more corrections than actual acquisitions.
     * DISTINCT because one Order can carry multiple positive lines for
     * the same item under staggered receipts.
     */
    public function ordersCount(): int
    {
        return (int) $this->orders()
            ->where('order_items.qty', '>', 0)
            ->distinct()
            ->count('orders.id');
    }

    /**
     * Row count that the Orders-tab API endpoint will return for this
     * item. Used by the tab badge so the number next to "Orders"
     * matches the row count of the table underneath. ordersCount
     * (distinct Orders) is wrong for this specific surface because
     * one Order can produce multiple table rows via multi-line
     * acquisitions, and HasManyThrough's inner join + Order's own
     * SoftDeletes scope can diverge from the API's leftJoin shape.
     *
     * Mirrors the filters applied by OrderItemsController::index,
     * which excludes OrderItems whose parent Order has no order
     * number. Those are the initial-inventory anchors written by
     * writeInitialOrderIfStocked and shouldn't surface as "orders"
     * in the admin UI alongside real acquisition records.
     */
    public function orderItemsCount(): int
    {
        return (int) $this->orderItems()
            ->where('qty', '>', 0)
            ->whereHas('order', fn ($q) => $q->whereNotNull('order_number'))
            ->count();
    }

    /**
     * Prefill context for the adjust-quantity modal and the info-panel's
     * "last" fields. Prefers the most recent Order/OrderItem when one
     * exists (companies drift — the last supplier they actually bought
     * from beats a stale parent "default" field), and falls back to the
     * parent's `default_*` template values on items that have never been
     * ordered yet.
     *
     * Returns null only when there is no last-order data AND no template
     * defaults on the parent — a brand-new item with no history to seed
     * from.
     *
     * One query per invocation. Cheap on the view page (1 model per
     * page); eager-load on index pages.
     *
     * @return array{unit_cost: ?string, currency: ?string, purchase_date: ?string, supplier_id: ?int}|null
     */
    public function lastOrderDefaults(): ?array
    {
        $line = $this->orderItems()
            ->with('order:id,currency,purchase_date,supplier_id')
            ->latest('id')
            ->first();

        if ($line) {
            return [
                'unit_cost' => $line->price !== null ? (string) $line->price : null,
                'currency' => $line->order?->currency ?: null,
                'purchase_date' => $line->order?->purchase_date?->toDateString(),
                'supplier_id' => $line->order?->supplier_id,
            ];
        }

        $defaultSupplier = $this->default_supplier_id;
        $defaultCost = $this->default_purchase_cost;

        if ($defaultSupplier === null && $defaultCost === null) {
            return null;
        }

        return [
            'unit_cost' => $defaultCost !== null ? (string) $defaultCost : null,
            'currency' => null,
            'purchase_date' => null,
            'supplier_id' => $defaultSupplier !== null ? (int) $defaultSupplier : null,
        ];
    }

    /**
     * Batch version of lastOrderDefaults()['unit_cost'] for a whole
     * collection of items of the same class. Falls back to each
     * item's default_purchase_cost when it has no order history.
     *
     * @param  iterable<int, self>  $items
     * @return array<int, string|null> Keyed by item id.
     */
    public static function lastUnitCostsFor(iterable $items): array
    {
        $ids = [];
        $defaults = [];
        foreach ($items as $item) {
            $id = (int) $item->getKey();
            if ($id <= 0) {
                continue;
            }
            $ids[$id] = true;
            if (! array_key_exists($id, $defaults) && $item->default_purchase_cost !== null) {
                $defaults[$id] = (string) $item->default_purchase_cost;
            }
        }
        $ids = array_keys($ids);
        if ($ids === []) {
            return [];
        }

        $latestOrderItemIds = OrderItem::query()
            ->where('item_type', static::class)
            ->whereIn('item_id', $ids)
            ->groupBy('item_id')
            ->select('item_id')
            ->selectRaw('MAX(id) as max_id')
            ->pluck('max_id')
            ->all();

        $prices = [];
        if ($latestOrderItemIds !== []) {
            $prices = OrderItem::query()
                ->whereIn('id', $latestOrderItemIds)
                ->pluck('price', 'item_id')
                ->all();
        }

        $out = [];
        foreach ($ids as $id) {
            if (array_key_exists($id, $prices) && $prices[$id] !== null) {
                $out[$id] = (string) $prices[$id];

                continue;
            }
            $out[$id] = $defaults[$id] ?? null;
        }

        return $out;
    }

    /**
     * Prefill values for the create / clone form's initial-acquisition
     * fields. Distinct from lastOrderDefaults() because this shape
     * includes `order_number` (per-shipment, not a "default" concept)
     * and matches the request keys the create form posts back.
     *
     * Used by getClone() on Accessories / Consumables / Components to
     * carry the source item's most recent acquisition context onto the
     * cloned entry's create form, restoring the pre-Orders workflow
     * where cloning a stock entry pre-filled supplier / order # / date
     * / price for a fast restock. Items with no order history return
     * an all-null array.
     *
     * Returns native types (Carbon for purchase_date, float for
     * purchase_cost) so getClone() can assign directly onto typed
     * model properties without a coercion step and without tripping
     * larastan's assign.propertyType on the cast-inferred property
     * signatures. The @var below is needed because MorphMany::first()
     * infers to Model|null; the annotation resolves $line to OrderItem
     * so `->order` and `->price` accesses type through cleanly rather
     * than falling into the Model::$order baseline ignore bucket.
     *
     * @return array{
     *     supplier_id: ?int,
     *     purchase_date: ?\Carbon\Carbon,
     *     purchase_cost: ?float,
     *     order_number: ?string,
     * }
     */
    public function lastOrderPrefill(): array
    {
        /** @var \App\Models\OrderItem|null $line */
        $line = $this->orderItems()
            ->with('order:id,order_number,supplier_id,purchase_date')
            ->latest('id')
            ->first();

        return [
            'supplier_id' => $line?->order?->supplier_id,
            'purchase_date' => $line?->order?->purchase_date,
            'purchase_cost' => $line?->price !== null ? (float) $line->price : null,
            'order_number' => $line?->order?->order_number,
        ];
    }

    /**
     * Resolve a Supplier for the "last acquisition" view (transformers,
     * info-panel, report callbacks). Same fallback ladder as
     * lastOrderDefaults(): last Order.supplier_id wins, falls back to
     * the parent's default_supplier_id template value on items with no
     * order history. Returns null when both are unset.
     *
     * Prefers walking eager-loaded relations (orderItems.order.supplier)
     * when the caller pre-loaded them; otherwise issues one query for
     * the latest OrderItem's Order.supplier_id and then hydrates the
     * Supplier. Callers rendering a list should always eager-load to
     * avoid N+1.
     */
    public function lastAcquisitionSupplier(): ?Supplier
    {
        $cachedSupplier = $this->cachedLastOrderSupplier();
        if ($cachedSupplier !== null) {
            return $cachedSupplier;
        }

        $supplierId = $this->lastOrderSupplierId() ?? $this->default_supplier_id;

        return $supplierId ? Supplier::find($supplierId) : null;
    }

    /**
     * Fast-path: return the eager-loaded Supplier from the
     * `orderItems.order.supplier` chain if the caller pre-loaded it.
     * Callers rendering a list should eager-load this chain to avoid
     * an N+1 through Supplier::find below.
     */
    private function cachedLastOrderSupplier(): ?Supplier
    {
        if (! $this->relationLoaded('orderItems')) {
            return null;
        }

        $order = $this->orderItems->sortByDesc('id')->first()?->order;

        if ($order?->relationLoaded('supplier') && $order->supplier) {
            return $order->supplier;
        }

        return null;
    }

    /**
     * Slow-path: read the latest OrderItem's Order.supplier_id via a
     * fresh query. Called only when the eager-loaded fast-path missed.
     */
    private function lastOrderSupplierId(): ?int
    {
        if ($this->relationLoaded('orderItems')) {
            return $this->orderItems->sortByDesc('id')->first()?->order?->supplier_id;
        }

        return $this->orderItems()->with('order:id,supplier_id')->latest('id')->first()?->order?->supplier_id;
    }

    /**
     * Sort scope that lets the bootstrap-table sortable header for an
     * order-number column keep working after the parent order_number
     * column moved to Orders. Attaches a correlated subquery selecting
     * the latest Order.order_number for each row (matched via the
     * polymorphic order_items pivot), then orders by that alias.
     *
     * "Latest" is defined as the Order with the most recent created_at
     * among all OrderItems that reference this row. Rows with no Order
     * history sort last on `asc` / first on `desc` (natural NULL sort
     * behavior on both MySQL and SQLite).
     *
     * Uses addSelect so preceding withCount subqueries survive — a
     * plain select() would wipe them and re-introduce N+1 downstream.
     */
    public function scopeOrderByOrderNumber(Builder $query, string $direction = 'asc'): Builder
    {
        $modelTable = (new static)->getTable();

        return $query->addSelect([
            'sort_order_number' => OrderItem::query()
                ->join('orders', 'orders.id', '=', 'order_items.order_id')
                ->whereColumn('order_items.item_id', $modelTable.'.id')
                ->where('order_items.item_type', static::class)
                ->orderByDesc('orders.created_at')
                ->limit(1)
                ->select('orders.order_number'),
        ])->orderBy('sort_order_number', $direction);
    }

    /**
     * Sort by the most recent OrderItem's price. Rows with no order
     * history sort last on `asc` / first on `desc` (natural NULL sort
     * behavior on both MySQL and SQLite). Uses addSelect for the same
     * reason as scopeOrderByOrderNumber above.
     */
    public function scopeOrderByLastPurchaseCost(Builder $query, string $direction = 'asc'): Builder
    {
        $modelTable = (new static)->getTable();

        return $query->addSelect([
            'sort_last_purchase_cost' => OrderItem::query()
                ->whereColumn('order_items.item_id', $modelTable.'.id')
                ->where('order_items.item_type', static::class)
                ->orderByDesc('order_items.id')
                ->limit(1)
                ->select('order_items.price'),
        ])->orderBy('sort_last_purchase_cost', $direction);
    }

    /**
     * Sort by the most recent Order.purchase_date across this row's
     * OrderItems. See scopeOrderByLastPurchaseCost for the null-sort
     * caveat.
     */
    public function scopeOrderByLastPurchaseDate(Builder $query, string $direction = 'asc'): Builder
    {
        $modelTable = (new static)->getTable();

        return $query->addSelect([
            'sort_last_purchase_date' => OrderItem::query()
                ->join('orders', 'orders.id', '=', 'order_items.order_id')
                ->whereColumn('order_items.item_id', $modelTable.'.id')
                ->where('order_items.item_type', static::class)
                ->orderByDesc('order_items.id')
                ->limit(1)
                ->select('orders.purchase_date'),
        ])->orderBy('sort_last_purchase_date', $direction);
    }

    /**
     * Sort by the sum of (qty * price) across every OrderItem attached
     * to this row. Matches the info-panel's total_cost display so a
     * click on the total-cost column header lands rows in the same
     * order the panel shows them.
     */
    public function scopeOrderByTotalOrderCost(Builder $query, string $direction = 'asc'): Builder
    {
        $modelTable = (new static)->getTable();

        return $query->addSelect([
            'sort_total_order_cost' => OrderItem::query()
                ->whereColumn('order_items.item_id', $modelTable.'.id')
                ->where('order_items.item_type', static::class)
                ->selectRaw('COALESCE(SUM(order_items.qty * order_items.price), 0)'),
        ])->orderBy('sort_total_order_cost', $direction);
    }

    /**
     * Sum every OrderItem's line total (qty × price) grouped by the
     * parent Order's currency, so mixed-currency acquisitions render
     * as a per-currency breakdown instead of a single misleading total.
     *
     * Returns [] when the item has no OrderItems yet or every line has
     * a null price. The info-panel skips the "Total cost" line entirely
     * in that case rather than showing 0. Orders / OrderItems is the
     * single source of truth for acquisition cost, no fallback to
     * legacy_* columns (those will be dropped in a later version).
     *
     * @return array<string, float> currency code => sum in that currency
     */
    public function totalCostSumByCurrency(): array
    {
        return $this->orderItems()
            ->with('order:id,currency')
            ->get()
            ->reduce(function (array $carry, OrderItem $line) {
                if ($line->price === null) {
                    return $carry;
                }
                $currency = $line->order?->currency
                    ?? Setting::getSettings()?->default_currency
                    ?? '';
                $carry[$currency] = ($carry[$currency] ?? 0) + ($line->qty * (float) $line->price);

                return $carry;
            }, []);
    }

    /**
     * Naive cross-currency sum, kept for backwards compatibility with
     * external callers. New code should prefer totalCostSumByCurrency()
     * so mixed-currency totals stay disambiguated.
     */
    public function totalCostSum()
    {
        return array_sum($this->totalCostSumByCurrency()) ?: null;
    }

    /**
     * True when every recorded acquisition for this item came from the
     * same supplier. Info-panel supplier row hides when false so a
     * single supplier name doesn't misrepresent multi-supplier history.
     */
    public function hasConsistentSupplier(): bool
    {
        return $this->orderItems()
            ->with('order:id,supplier_id')
            ->get()
            ->map(fn (OrderItem $line) => $line->order?->supplier_id)
            ->filter()
            ->unique()
            ->count() <= 1;
    }

    /**
     * Called from the inventory observer's `created` event. When the row
     * lands with qty > 0, write a placeholder Order + OrderItem to
     * represent the initial acquisition. Transaction metadata
     * (supplier_id, purchase_date, purchase_cost, currency, order_number)
     * only lives on Orders / OrderItems now, form-driven creates enrich
     * the placeholder via the controller's enrichInitialOrderFromRequest,
     * and factory / seeder paths fill it via an afterCreating hook.
     *
     * qty=0/null is container-only: a bare inventory row with no initial
     * acquisition. The Order + OrderItem write is skipped entirely,
     * later adjust-quantity events write their own when stock actually
     * arrives.
     *
     * The create action_log always writes, linked to the OrderItem when
     * one exists and unlinked (order_item_id = null) for container-only
     * creates. quantity captures the initial on-hand count so auditors
     * get a "started with N units" anchor, subsequent QuantityAdjust
     * logs record deltas rather than running totals.
     */
    public function writeInitialInventoryCreate(): void
    {
        $initialQty = (int) ($this->getAttributes()['qty'] ?? 0);
        $orderItem = $this->writeInitialOrderIfStocked($initialQty);

        $log = new Actionlog;
        $log->item_type = static::class;
        $log->item_id = $this->id;
        $log->created_at = date('Y-m-d H:i:s');
        // See AssetModelObserver::created for the seeder-friendly
        // auth fallback rationale.
        $log->created_by = auth()->id() ?? $this->created_by;
        $log->quantity = $initialQty;
        $log->order_item_id = $orderItem?->id;
        if ($this->imported) {
            $log->setActionSource('importer');
        }
        $log->logaction('create');
    }

    private function writeInitialOrderIfStocked(int $initialQty): ?OrderItem
    {
        if ($initialQty <= 0) {
            return null;
        }

        $locationCurrency = $this->location?->currency;
        $currency = ($locationCurrency !== '' && $locationCurrency !== null)
            ? $locationCurrency
            : Setting::getSettings()?->default_currency;

        $order = new Order([
            'order_number' => null,
            'supplier_id' => null,
            'company_id' => $this->company_id,
            'purchase_date' => null,
            'currency' => $currency,
        ]);
        $order->created_by = $this->created_by ?? auth()->id();
        $order->save();

        $orderItem = new OrderItem([
            'order_id' => $order->id,
            'item_type' => static::class,
            'item_id' => $this->id,
            'qty' => $initialQty,
            'price' => null,
        ]);
        $orderItem->created_by = $this->created_by ?? auth()->id();
        $orderItem->save();

        return $orderItem;
    }
}