@fleetbase/fleetops-engine 0.6.48 → 0.6.50

package/server/src/Support/Metrics/AbstractMetric.php

@@ -0,0 +1,170 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\Models\Company;
+use Illuminate\Support\Carbon;
+
+/**
+ * Base class for FleetOps scalar metrics.
+ *
+ * Subclasses implement query() + aggregate() and declare slug() + format(). The base
+ * handles period selection, optional period-over-period delta, and optional sparkline.
+ */
+abstract class AbstractMetric
+{
+    protected Company $company;
+    protected ?\DateTimeInterface $start        = null;
+    protected ?\DateTimeInterface $end          = null;
+    protected ?\DateTimeInterface $compareStart = null;
+    protected ?\DateTimeInterface $compareEnd   = null;
+    protected int $sparklineBuckets             = 0;
+    protected string $sparklineUnit             = 'day';
+
+    /**
+     * Period boundaries for the currently-executing aggregate call.
+     * Set by value()/delta()/sparkline() before invoking aggregate(); subclasses
+     * that need to issue a second parallel query (e.g. AvgOrderValueMetric) read
+     * these instead of re-introspecting the query's where clauses.
+     */
+    protected ?\DateTimeInterface $currentStart = null;
+    protected ?\DateTimeInterface $currentEnd   = null;
+
+    abstract public static function slug(): string;
+
+    abstract public function format(): string;
+
+    /**
+     * Build the query for the given period. The base class invokes this with the
+     * current period, the comparison period (for delta), and one sub-range per
+     * sparkline bucket — so it must be cheap and idempotent.
+     */
+    abstract protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end);
+
+    /**
+     * Reduce a query to a single numeric value. Override for sums (`->sum('amount')`),
+     * counts (`->count()`), or computed expressions.
+     */
+    abstract protected function aggregate($query): float|int;
+
+    public function currency(): ?string
+    {
+        return null;
+    }
+
+    public static function forCompany(Company $company): static
+    {
+        return (new static())->setCompany($company);
+    }
+
+    public function between(?\DateTimeInterface $start, ?\DateTimeInterface $end): static
+    {
+        $this->start = $start;
+        $this->end   = $end;
+
+        return $this;
+    }
+
+    public function compareTo(\DateTimeInterface $start, \DateTimeInterface $end): static
+    {
+        $this->compareStart = $start;
+        $this->compareEnd   = $end;
+
+        return $this;
+    }
+
+    public function withSparkline(int $buckets = 14, string $unit = 'day'): static
+    {
+        $this->sparklineBuckets = max(0, $buckets);
+        $this->sparklineUnit    = $unit;
+
+        return $this;
+    }
+
+    public function value(): float|int
+    {
+        return $this->runAggregate($this->start, $this->end);
+    }
+
+    public function delta(): ?float
+    {
+        if (!$this->compareStart || !$this->compareEnd) {
+            return null;
+        }
+
+        $current  = $this->value();
+        $previous = $this->runAggregate($this->compareStart, $this->compareEnd);
+
+        if ((float) $previous === 0.0) {
+            return $current > 0 ? 100.0 : 0.0;
+        }
+
+        return round((($current - $previous) / $previous) * 100, 1);
+    }
+
+    public function sparkline(): ?array
+    {
+        if ($this->sparklineBuckets === 0 || $this->end === null) {
+            return null;
+        }
+
+        $end    = Carbon::instance($this->end);
+        $cursor = $end->copy()->sub($this->sparklineUnit, $this->sparklineBuckets);
+        $labels = [];
+        $data   = [];
+
+        for ($i = 0; $i < $this->sparklineBuckets; $i++) {
+            $next     = $cursor->copy()->add($this->sparklineUnit, 1);
+            $labels[] = $cursor->format('Y-m-d');
+            $data[]   = $this->runAggregate($cursor->toDateTime(), $next->toDateTime());
+            $cursor   = $next;
+        }
+
+        return ['labels' => $labels, 'data' => $data];
+    }
+
+    /**
+     * Run a single aggregation for a sub-period. Sets $currentStart/$currentEnd
+     * so subclasses that need to issue a parallel query can read the bucket range.
+     */
+    protected function runAggregate(?\DateTimeInterface $start, ?\DateTimeInterface $end): float|int
+    {
+        $this->currentStart = $start;
+        $this->currentEnd   = $end;
+
+        return $this->aggregate($this->query($start, $end));
+    }
+
+    public function get(): array
+    {
+        $payload = [
+            'slug'   => static::slug(),
+            'value'  => $this->value(),
+            'format' => $this->format(),
+        ];
+
+        $currency = $this->currency();
+        if ($currency !== null) {
+            $payload['currency'] = $currency;
+        }
+
+        $delta = $this->delta();
+        if ($delta !== null) {
+            $payload['delta_pct'] = $delta;
+        }
+
+        $sparkline = $this->sparkline();
+        if ($sparkline !== null) {
+            $payload['sparkline'] = $sparkline;
+        }
+
+        return $payload;
+    }
+
+    protected function setCompany(Company $company): static
+    {
+        $this->company = $company;
+
+        return $this;
+    }
+}

package/server/src/Support/Metrics/ActiveLiveOrdersMetric.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Support\LiveOrderQuery;
+
+class ActiveLiveOrdersMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'active_live_orders';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        return LiveOrderQuery::make($this->company->uuid, ['active' => true]);
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/AvgOrderValueMetric.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Models\Transaction;
+
+/**
+ * Average revenue per completed order in the period. Computed as
+ * sum(transactions.amount, primary_currency) / count(completed orders).
+ *
+ * Uses $this->currentStart/$currentEnd (set by the base class) so the metric
+ * cooperates with the sparkline machinery — each bucket recomputes both
+ * numerator and denominator over its own sub-range.
+ */
+class AvgOrderValueMetric extends MoneyMetric
+{
+    public static function slug(): string
+    {
+        return 'avg_order_value';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Order::where('company_uuid', $this->company->uuid)
+            ->where('status', 'completed');
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): float
+    {
+        $orderCount = (int) $query->count();
+        if ($orderCount === 0) {
+            return 0.0;
+        }
+
+        $revenueQuery = Transaction::where('company_uuid', $this->company->uuid)
+            ->where('currency', $this->currency());
+
+        if ($this->currentStart && $this->currentEnd) {
+            $revenueQuery->whereBetween('created_at', [$this->currentStart, $this->currentEnd]);
+        }
+
+        $totalRevenue = (float) $revenueQuery->sum('amount');
+
+        return round($totalRevenue / $orderCount, 2);
+    }
+}

package/server/src/Support/Metrics/DriversOnlineMetric.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Driver;
+
+class DriversOnlineMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'drivers_online';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        return Driver::where('company_uuid', $this->company->uuid)
+            ->where('online', true)
+            ->whereNotNull('current_job_uuid');
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/EarningsMetric.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\Models\Transaction;
+
+class EarningsMetric extends MoneyMetric
+{
+    public static function slug(): string
+    {
+        return 'earnings';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Transaction::where('company_uuid', $this->company->uuid)
+            ->where('currency', $this->currency());
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): float
+    {
+        return (float) $query->sum('amount');
+    }
+}

package/server/src/Support/Metrics/FuelCostsMetric.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\FuelReport;
+
+class FuelCostsMetric extends MoneyMetric
+{
+    public static function slug(): string
+    {
+        return 'fuel_costs';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = FuelReport::where('company_uuid', $this->company->uuid)
+            ->where('currency', $this->currency());
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): float
+    {
+        return (float) $query->sum('amount');
+    }
+}

package/server/src/Support/Metrics/MoneyMetric.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+/**
+ * Base for money-valued metrics. Enforces currency awareness so we never repeat
+ * the legacy bug of summing mixed-currency rows.
+ */
+abstract class MoneyMetric extends AbstractMetric
+{
+    protected ?string $currencyOverride = null;
+
+    public function inCurrency(?string $currency): static
+    {
+        $this->currencyOverride = $currency;
+
+        return $this;
+    }
+
+    public function format(): string
+    {
+        return 'money';
+    }
+
+    public function currency(): string
+    {
+        return $this->currencyOverride
+            ?? ($this->company->currency ?? 'USD');
+    }
+}

package/server/src/Support/Metrics/OpenIssuesMetric.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Issue;
+
+class OpenIssuesMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'open_issues';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Issue::where('company_uuid', $this->company->uuid)
+            ->where('status', 'pending');
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/OrdersCanceledMetric.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Order;
+
+class OrdersCanceledMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'orders_canceled';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Order::where('company_uuid', $this->company->uuid)
+            ->where('status', 'canceled');
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/OrdersCompletedMetric.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Order;
+
+class OrdersCompletedMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'orders_completed';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Order::where('company_uuid', $this->company->uuid)
+            ->where('status', 'completed');
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/OrdersInProgressMetric.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Order;
+
+/**
+ * Counts orders currently in flight. Uses an explicit allowlist of "active" statuses
+ * rather than the legacy exclusion list, which was brittle against new statuses.
+ */
+class OrdersInProgressMetric extends AbstractMetric
+{
+    public const IN_PROGRESS_STATUSES = [
+        'dispatched',
+        'assigned',
+        'started',
+        'enroute',
+        'in_progress',
+        'driver_enroute',
+        'picking_up',
+        'picked_up',
+        'dropping_off',
+    ];
+
+    public static function slug(): string
+    {
+        return 'orders_in_progress';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Order::where('company_uuid', $this->company->uuid)
+            ->whereIn('status', self::IN_PROGRESS_STATUSES);
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/OrdersScheduledMetric.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Support\Carbon;
+
+class OrdersScheduledMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'orders_scheduled';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Order::where('company_uuid', $this->company->uuid)
+            ->where('status', 'created')
+            ->whereDate('scheduled_at', '>', Carbon::now());
+
+        if ($start && $end) {
+            $query->whereBetween('created_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/Registry.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+/**
+ * Explicit slug → metric-class map. Replaces the legacy
+ * `array_slice(get_class_methods, 9)` reflection which broke whenever a
+ * private helper was added to the wrong position in Metrics.php.
+ */
+class Registry
+{
+    /** @var array<string, class-string<AbstractMetric>> */
+    public const METRICS = [
+        'earnings'                => EarningsMetric::class,
+        'fuel_costs'              => FuelCostsMetric::class,
+        'total_distance_traveled' => TotalDistanceTraveledMetric::class,
+        'total_time_traveled'     => TotalTimeTraveledMetric::class,
+        'orders_completed'        => OrdersCompletedMetric::class,
+        'orders_canceled'         => OrdersCanceledMetric::class,
+        'orders_in_progress'      => OrdersInProgressMetric::class,
+        'orders_scheduled'        => OrdersScheduledMetric::class,
+        'active_live_orders'      => ActiveLiveOrdersMetric::class,
+        'drivers_online'          => DriversOnlineMetric::class,
+        'total_drivers'           => TotalDriversMetric::class,
+        'total_customers'         => TotalCustomersMetric::class,
+        'open_issues'             => OpenIssuesMetric::class,
+        'resolved_issues'         => ResolvedIssuesMetric::class,
+        'avg_order_value'         => AvgOrderValueMetric::class,
+    ];
+
+    public static function resolve(string $slug): ?string
+    {
+        return self::METRICS[$slug] ?? null;
+    }
+
+    /** @return array<string, class-string<AbstractMetric>> */
+    public static function all(): array
+    {
+        return self::METRICS;
+    }
+
+    public static function slugs(): array
+    {
+        return array_keys(self::METRICS);
+    }
+}

package/server/src/Support/Metrics/ResolvedIssuesMetric.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Issue;
+
+class ResolvedIssuesMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'resolved_issues';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        $query = Issue::where('company_uuid', $this->company->uuid)
+            ->whereNotNull('resolved_at');
+
+        if ($start && $end) {
+            $query->whereBetween('resolved_at', [$start, $end]);
+        }
+
+        return $query;
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}

package/server/src/Support/Metrics/TotalCustomersMetric.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Metrics;
+
+use Fleetbase\FleetOps\Models\Contact;
+
+class TotalCustomersMetric extends AbstractMetric
+{
+    public static function slug(): string
+    {
+        return 'total_customers';
+    }
+
+    public function format(): string
+    {
+        return 'count';
+    }
+
+    protected function query(?\DateTimeInterface $start, ?\DateTimeInterface $end)
+    {
+        return Contact::where('company_uuid', $this->company->uuid)
+            ->where('type', 'customer');
+    }
+
+    protected function aggregate($query): int
+    {
+        return (int) $query->count();
+    }
+}