@fleetbase/fleetops-engine 0.6.48 → 0.6.49

package/server/src/Support/Analytics/TopDrivers.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Support\Carbon;
+
+/**
+ * Ranked driver leaderboard. Single GROUP BY join on orders → drivers so this
+ * scales without N+1 even on large fleets.
+ */
+class TopDrivers extends AbstractAnalytics
+{
+    protected int $limit = 10;
+    protected string $sortBy = 'orders_completed';
+
+    public function limit(int $limit): self
+    {
+        $this->limit = max(1, min(50, $limit));
+
+        return $this;
+    }
+
+    public function sortBy(string $key): self
+    {
+        $this->sortBy = in_array($key, ['orders_completed', 'distance', 'on_time'], true)
+            ? $key
+            : 'orders_completed';
+
+        return $this;
+    }
+
+    public function get(): array
+    {
+        $start = $this->start ?? Carbon::now()->subDays(30)->toDateTime();
+        $end   = $this->end ?? Carbon::now()->toDateTime();
+
+        $sortColumn = match ($this->sortBy) {
+            'distance' => 'distance_m',
+            'on_time'  => 'on_time_pct',
+            default    => 'orders_completed',
+        };
+
+        // `drivers.name` and `drivers.photo_uuid` aren't real columns — they're
+        // virtual attributes that resolve via the related users row. Join users
+        // explicitly so we can SELECT them at the SQL level.
+        $rows = Order::where('orders.company_uuid', $this->company->uuid)
+            ->where('orders.status', 'completed')
+            ->whereNotNull('orders.driver_assigned_uuid')
+            ->whereBetween('orders.updated_at', [$start, $end])
+            ->join('drivers', 'drivers.uuid', '=', 'orders.driver_assigned_uuid')
+            ->join('users', 'users.uuid', '=', 'drivers.user_uuid')
+            ->groupBy('drivers.uuid', 'users.name', 'users.avatar_uuid')
+            ->selectRaw('
+                drivers.uuid as driver_uuid,
+                users.name as name,
+                users.avatar_uuid as avatar_uuid,
+                COUNT(orders.uuid) as orders_completed,
+                COALESCE(SUM(orders.distance), 0) as distance_m,
+                SUM(CASE
+                    WHEN orders.scheduled_at IS NOT NULL
+                     AND TIMESTAMPDIFF(SECOND, orders.scheduled_at, orders.updated_at) <= 1800
+                    THEN 1 ELSE 0 END) as on_time_count,
+                SUM(CASE WHEN orders.scheduled_at IS NOT NULL THEN 1 ELSE 0 END) as scheduled_count
+            ')
+            ->orderByRaw("{$sortColumn} DESC")
+            ->limit($this->limit)
+            ->get();
+
+        $result = $rows->map(function ($r) {
+            $scheduled = (int) $r->scheduled_count;
+            $onTimePct = $scheduled > 0
+                ? round(((int) $r->on_time_count / $scheduled) * 100, 1)
+                : null;
+
+            return [
+                'driver_uuid'      => $r->driver_uuid,
+                'name'             => $r->name,
+                'avatar_uuid'      => $r->avatar_uuid,
+                'orders_completed' => (int) $r->orders_completed,
+                'distance_m'       => (float) $r->distance_m,
+                'on_time_pct'      => $onTimePct,
+            ];
+        })->all();
+
+        return [
+            'rows'    => $result,
+            'sort_by' => $this->sortBy,
+        ];
+    }
+}

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();
+    }
+}