@fleetbase/fleetops-engine 0.6.64 → 0.6.66

package/server/src/Support/InspectionSubmitter.php

@@ -0,0 +1,297 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\InspectionForm;
+use Fleetbase\FleetOps\Models\InspectionItemResult;
+use Fleetbase\FleetOps\Models\InspectionSubmission;
+use Fleetbase\FleetOps\Rules\Base64OrUrl;
+use Fleetbase\Models\CustomField;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
+
+/**
+ * Records an inspection against a published form.
+ *
+ * Two doors lead here — the tokenised public link and the driver API — and
+ * they must agree on what a submission is: one row, the answers, the pass/fail
+ * counts, and whatever follow-up the form's settings ask for. The doors differ
+ * only in who they say submitted it, which is what the `$attributes` argument
+ * carries.
+ *
+ * A form built from fields is answered with `custom_field_values`: one value
+ * per field, stored through the platform's custom-field values, with every
+ * `pass-fail` answer mirrored into an item result. The first cut's
+ * `item_results` body is still accepted for the public link and older app
+ * builds; when both arrive the field values win and the duplicated results
+ * are ignored.
+ */
+class InspectionSubmitter
+{
+    /**
+     * The body of a submit, as both doors accept it.
+     */
+    public static function rules(): array
+    {
+        return [
+            'odometer'                            => 'nullable|integer|min:0',
+            'engine_hours'                        => 'nullable|integer|min:0',
+            // Every key of an answer needs a rule of its own. validate() returns
+            // only keys that have one, and with nested rules present an array's
+            // other keys are dropped: without these, `value` never reached the
+            // submitter, so every answer arrived empty and a failed check
+            // carrying its photo was refused for having none.
+            'answers'                                 => 'required_without_all:item_results,custom_field_values|array',
+            'answers.*.field'                         => 'required_without:answers.*.custom_field|string|max:191',
+            'answers.*.custom_field'                  => 'nullable|string|max:191',
+            'answers.*.value'                         => 'nullable',
+            'answers.*.value_type'                    => 'nullable|string|max:50',
+            'custom_field_values'                     => 'required_without_all:item_results,answers|array',
+            'custom_field_values.*.custom_field'      => 'required_without:custom_field_values.*.custom_field_uuid|string|max:191',
+            'custom_field_values.*.custom_field_uuid' => 'nullable|string|max:191',
+            'custom_field_values.*.value'             => 'nullable',
+            'custom_field_values.*.value_type'        => 'nullable|string|max:50',
+            'item_results'                            => 'required_without_all:custom_field_values,answers|array',
+            'item_results.*.item_key'                 => 'nullable|string|max:191',
+            'item_results.*.label'                    => 'required|string|max:255',
+            'item_results.*.category'                 => 'nullable|string|max:191',
+            'item_results.*.status'                   => 'nullable|string|max:50',
+            'item_results.*.severity'                 => 'nullable|string|max:50',
+            'item_results.*.passed'                   => 'required|boolean',
+            'item_results.*.comments'                 => 'nullable|string|max:2000',
+            'item_results.*.photos'                   => 'nullable|array',
+            'item_results.*.photos.*'                 => ['string', new Base64OrUrl()],
+            'location'                                => 'nullable|array',
+            'signature'                               => 'nullable|array',
+            'attachments'                             => 'nullable|array',
+        ];
+    }
+
+    /**
+     * @param array $validated  the request body, already validated against rules()
+     * @param array $attributes columns the door owns: vehicle_uuid, driver_uuid,
+     *                          submitted_by_uuid, source, started_at, meta
+     */
+    public static function submit(InspectionForm $form, array $validated, array $attributes = []): InspectionSubmission
+    {
+        $submission = InspectionSubmission::create(array_merge([
+            'company_uuid'         => $form->company_uuid,
+            'inspection_form_uuid' => $form->uuid,
+            'type'                 => $form->type ?? 'dvir',
+            'status'               => 'submitted',
+            'odometer'             => data_get($validated, 'odometer'),
+            'engine_hours'         => data_get($validated, 'engine_hours'),
+            'started_at'           => now(),
+            'submitted_at'         => now(),
+            'location'             => data_get($validated, 'location'),
+            'signature'            => data_get($validated, 'signature'),
+            'attachments'          => data_get($validated, 'attachments'),
+        ], $attributes));
+
+        // `answers` is what the API documents; `custom_field_values` is what
+        // the first cut shipped and the console still sends.
+        $values = data_get($validated, 'answers') ?: data_get($validated, 'custom_field_values');
+        $under  = data_get($validated, 'answers') ? 'answers' : 'custom_field_values';
+        if (is_array($values) && !empty($values)) {
+            static::applyCustomFieldValues($submission, $values, $submission->submitted_by_uuid, $under);
+        } else {
+            foreach ((array) data_get($validated, 'item_results', []) as $item) {
+                InspectionItemResult::create([
+                    'company_uuid'               => $form->company_uuid,
+                    'inspection_submission_uuid' => $submission->uuid,
+                    'item_key'                   => data_get($item, 'item_key'),
+                    'label'                      => data_get($item, 'label'),
+                    'category'                   => data_get($item, 'category'),
+                    'status'                     => data_get($item, 'status', data_get($item, 'passed') ? 'passed' : 'failed'),
+                    'severity'                   => data_get($item, 'severity'),
+                    'passed'                     => (bool) data_get($item, 'passed'),
+                    'comments'                   => data_get($item, 'comments'),
+                    'photos'                     => data_get($item, 'photos'),
+                ]);
+            }
+        }
+
+        $submission->syncResultCounts();
+
+        if (data_get($form->settings, 'create_issue_on_failure') && $submission->has_failures) {
+            $submission->createIssueFromFailures();
+        }
+
+        if (data_get($form->settings, 'create_work_order_on_failure') && $submission->has_failures) {
+            $submission->createWorkOrderFromFailures();
+        }
+
+        return $submission;
+    }
+
+    /**
+     * Stores a set of answers against the submission's form.
+     *
+     * Each row names a field of the form by uuid (or name), carries a value
+     * and, optionally, a value type. A field that does not belong to the form,
+     * or a failed pass-fail answer missing the comment or photo the field
+     * insists on, refuses the whole set with a 422 so nothing half-filled is
+     * written. Base64 photos and signatures become platform files on the way
+     * in; when the answers are in, the item results and the counts follow.
+     *
+     * @param array       $rows         [{custom_field|custom_field_uuid, value, value_type}]
+     * @param string|null $uploaderUuid the user a stored photo or signature is credited to
+     * @param string      $under        the body key the rows arrived under, which the
+     *                                  422 paths are reported against
+     *
+     * @throws ValidationException
+     */
+    public static function applyCustomFieldValues(InspectionSubmission $submission, array $rows, ?string $uploaderUuid = null, string $under = 'custom_field_values'): array
+    {
+        $fields  = CustomField::query()->where('subject_uuid', $submission->inspection_form_uuid)->where('for', InspectionForm::FIELD_FOR)->get();
+        $payload = [];
+        $errors  = [];
+
+        foreach (array_values($rows) as $index => $row) {
+            $key   = Arr::get($row, 'field', Arr::get($row, 'custom_field', Arr::get($row, 'custom_field_uuid')));
+            $field = static::findField($fields, $key);
+            if (!$field) {
+                $errors["{$under}.{$index}." . ($under === 'answers' ? 'field' : 'custom_field')] = ['The field "' . (is_scalar($key) ? $key : '?') . '" does not belong to this inspection form.'];
+                continue;
+            }
+
+            [$value, $valueType, $fieldErrors] = static::normalizeValue($field, Arr::get($row, 'value'), Arr::get($row, 'value_type'), $submission, $uploaderUuid);
+            foreach ($fieldErrors as $message) {
+                $errors["{$under}.{$index}.value"][] = $message;
+            }
+
+            $payload[] = [
+                'custom_field_uuid' => $field->uuid,
+                'value'             => $value,
+                'value_type'        => $valueType,
+            ];
+        }
+
+        if (!empty($errors)) {
+            throw ValidationException::withMessages($errors);
+        }
+
+        // `custom_field_values.value` is a NOT NULL column, so an answer that
+        // is nothing is not an answer: it clears whatever was there instead.
+        $summary = $submission->syncCustomFieldValues($payload, ['treat_null_as_delete' => true]);
+        $submission->syncItemResultsFromCustomFieldValues();
+        $submission->syncResultCounts();
+
+        return $summary;
+    }
+
+    /** Finds a field of the form by uuid or, failing that, by its name. */
+    protected static function findField(Collection $fields, mixed $key): ?CustomField
+    {
+        if (!is_string($key) || $key === '') {
+            return null;
+        }
+
+        return $fields->first(fn (CustomField $field) => $field->uuid === $key)
+            ?? $fields->first(fn (CustomField $field) => $field->public_id === $key)
+            ?? $fields->first(fn (CustomField $field) => $field->name === $key);
+    }
+
+    /**
+     * The value as it is stored, its type, and anything wrong with it.
+     *
+     * @return array{0: mixed, 1: string, 2: string[]}
+     */
+    protected static function normalizeValue(CustomField $field, mixed $value, mixed $valueType, InspectionSubmission $submission, ?string $uploaderUuid): array
+    {
+        $errors = [];
+
+        switch ($field->type) {
+            case 'pass-fail':
+                $answer = static::passFailAnswer($value);
+                $failed = !$answer['not_applicable'] && !filter_var($answer['passed'], FILTER_VALIDATE_BOOLEAN);
+                $meta   = is_array($field->meta) ? $field->meta : [];
+                $photos = array_values(array_filter($answer['photos'], 'is_string'));
+
+                // What the field insists on is checked before anything is
+                // stored, so a refused answer leaves no orphan photo behind.
+                if ($failed) {
+                    if (data_get($meta, 'require_comment_on_fail') && trim((string) $answer['comments']) === '') {
+                        $errors[] = 'A comment is required when "' . $field->label . '" fails.';
+                    }
+                    if (data_get($meta, 'require_photo_on_fail') && empty($photos)) {
+                        $errors[] = 'A photo is required when "' . $field->label . '" fails.';
+                    }
+                }
+
+                if (!empty($errors)) {
+                    return [$answer, 'object', $errors];
+                }
+
+                $answer['photos'] = array_values(array_map(
+                    fn ($photo) => InspectionFileStore::normalize($photo, $submission, InspectionFileStore::TYPE_PHOTO, $uploaderUuid),
+                    $photos
+                ));
+
+                if ($failed) {
+                    $answer['severity'] = $answer['severity'] ?? data_get($meta, 'severity');
+                    $answer['unsafe']   = filter_var($answer['unsafe'] ?? data_get($meta, 'unsafe_on_fail', false), FILTER_VALIDATE_BOOLEAN);
+                } else {
+                    $answer['severity'] = null;
+                    $answer['unsafe']   = false;
+                }
+
+                return [$answer, 'object', $errors];
+
+            case 'file-upload':
+            case 'signature':
+                $type = $field->type === 'signature' ? InspectionFileStore::TYPE_SIGNATURE : InspectionFileStore::TYPE_PHOTO;
+
+                return [InspectionFileStore::normalize($value, $submission, $type, $uploaderUuid), 'file', $errors];
+
+            case 'number':
+                return [$value === null || $value === '' ? null : (is_numeric($value) ? $value + 0 : $value), 'number', $errors];
+
+            case 'boolean':
+                return [filter_var($value, FILTER_VALIDATE_BOOLEAN), 'boolean', $errors];
+
+            default:
+                if (is_array($value)) {
+                    return [$value, 'array', $errors];
+                }
+
+                return [$value, is_string($valueType) && $valueType !== '' ? $valueType : 'text', $errors];
+        }
+    }
+
+    /**
+     * A pass-fail answer in one shape, whatever the client sent: an object,
+     * its JSON, a bare boolean, or the words "pass" / "fail".
+     *
+     * "Not applicable" is an answer of its own — the app sends it as
+     * `passed: true, not_applicable: true`, and it must not read as a pass
+     * once it is a result row, or a tail lift a rigid does not have would
+     * count towards the vehicle's clean record.
+     */
+    public static function passFailAnswer(mixed $value): array
+    {
+        if (is_string($value) && Str::startsWith(trim($value), '{')) {
+            $decoded = json_decode($value, true);
+            $value   = is_array($decoded) ? $decoded : $value;
+        }
+
+        if (!is_array($value)) {
+            $passed = is_string($value) ? !in_array(Str::lower(trim($value)), ['fail', 'failed', 'false', '0', 'no'], true) : (bool) $value;
+            $value  = ['passed' => $passed];
+        }
+
+        $notApplicable = filter_var($value['not_applicable'] ?? $value['na'] ?? false, FILTER_VALIDATE_BOOLEAN)
+            || (array_key_exists('passed', $value) && $value['passed'] === null);
+
+        return [
+            'passed'         => $notApplicable ? true : filter_var($value['passed'] ?? $value['pass'] ?? true, FILTER_VALIDATE_BOOLEAN),
+            'not_applicable' => $notApplicable,
+            'severity'       => isset($value['severity']) ? (Str::slug((string) $value['severity']) ?: null) : null,
+            'comments'       => isset($value['comments']) ? (string) $value['comments'] : null,
+            'photos'         => is_array($value['photos'] ?? null) ? $value['photos'] : [],
+            'unsafe'         => $value['unsafe'] ?? null,
+        ];
+    }
+}

package/server/src/Support/Radar/RadarAgenda.php

@@ -0,0 +1,375 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Radar;
+
+use Illuminate\Support\Carbon;
+
+/**
+ * The Agenda view: the same items laid out on a time scale. Four lanes
+ * across the next 24 hours or 7 days, an Overdue band left of now that is
+ * not part of the scale, a Later rail for dated work beyond the window, and
+ * an Anytime tray for everything with no date. Shifts ending with orders
+ * still assigned get a handover card with a suggested cover driver.
+ *
+ * Pure: items, shifts, drivers, orders and a clock in; a layout out.
+ */
+class RadarAgenda
+{
+    public const WINDOWS = ['24h' => 24, '7d' => 168];
+
+    public const LANES = [RadarRules::LANE_SHIFTS, RadarRules::LANE_MAINTENANCE, RadarRules::LANE_EXPIRIES, RadarRules::LANE_NOTICES];
+
+    /** Where an undated item goes once someone gives it a time. */
+    public const LANE_BY_CATEGORY = [
+        RadarRules::CATEGORY_STAFFING     => RadarRules::LANE_SHIFTS,
+        RadarRules::CATEGORY_MAINTENANCE  => RadarRules::LANE_MAINTENANCE,
+        RadarRules::CATEGORY_INSPECTIONS  => RadarRules::LANE_MAINTENANCE,
+        RadarRules::CATEGORY_ISSUES       => RadarRules::LANE_MAINTENANCE,
+        RadarRules::CATEGORY_PARTS        => RadarRules::LANE_MAINTENANCE,
+        RadarRules::CATEGORY_CONNECTIVITY => RadarRules::LANE_MAINTENANCE,
+        RadarRules::CATEGORY_COMPLIANCE   => RadarRules::LANE_EXPIRIES,
+        RadarRules::CATEGORY_FUEL         => RadarRules::LANE_EXPIRIES,
+        RadarRules::CATEGORY_NOTICES      => RadarRules::LANE_NOTICES,
+    ];
+
+    /** A cover driver must still be on shift this long after the handover. */
+    public const COVER_MARGIN_HOURS = 2;
+
+    /** Orders a driver can carry in a day when the driver record does not say. */
+    public const DEFAULT_CAPACITY = 6;
+
+    /**
+     * @param array $items   RadarRules items with state merged
+     * @param array $shifts  shift rows (see RadarController::loadShifts)
+     * @param array $drivers driver rows (uuid, public_id, name, online, location, active_orders, max_daily_orders)
+     * @param array $orders  active orders keyed by driver uuid: [{public_id, uuid, destination, ends_at}]
+     */
+    public static function build(array $items, array $shifts, string $window, Carbon $now, array $drivers = [], array $orders = []): array
+    {
+        $hours = self::WINDOWS[$window] ?? self::WINDOWS['24h'];
+        $start = $now->copy()->startOfHour();
+        $end   = $start->copy()->addHours($hours);
+        $open  = array_values(array_filter($items, fn ($item) => RadarRules::isOpen($item, $now)));
+
+        $lanes   = array_fill_keys(self::LANES, []);
+        $overdue = [];
+        $later   = [];
+        $anytime = [];
+
+        foreach ($open as $item) {
+            $placed = self::place($item, $start, $end, $now);
+
+            switch ($placed['zone']) {
+                case 'overdue':
+                    $overdue[] = $placed['entry'];
+                    break;
+                case 'lane':
+                    $lanes[$placed['entry']['lane']][] = $placed['entry'];
+                    break;
+                case 'later':
+                    $later[] = $placed['entry'];
+                    break;
+                default:
+                    $anytime[] = $placed['entry'];
+            }
+        }
+
+        // Every live shift is a bar on the shifts lane, gap or not, so the
+        // lane reads as the day's roster.
+        $byDriver = [];
+        foreach ($open as $item) {
+            if (($item['category'] ?? null) === RadarRules::CATEGORY_STAFFING && !empty($item['subject']['uuid'])) {
+                $byDriver[$item['subject']['uuid']][] = $item;
+            }
+        }
+        foreach ($shifts as $shift) {
+            $bar = self::shiftBar($shift, $byDriver, $start, $end, $now);
+            if ($bar) {
+                $lanes[RadarRules::LANE_SHIFTS][] = $bar;
+            }
+        }
+
+        usort($overdue, fn ($a, $b) => strcmp((string) $a['at'], (string) $b['at']));
+        usort($later, fn ($a, $b) => strcmp((string) $a['at'], (string) $b['at']));
+        foreach ($lanes as &$entries) {
+            usort($entries, fn ($a, $b) => strcmp((string) $a['at'], (string) $b['at']));
+        }
+        unset($entries);
+
+        return [
+            'now'       => $now->toIso8601String(),
+            'window'    => [
+                'key'      => isset(self::WINDOWS[$window]) ? $window : '24h',
+                'hours'    => $hours,
+                'start_at' => $start->toIso8601String(),
+                'end_at'   => $end->toIso8601String(),
+                'ticks'    => self::ticks($start, $hours),
+                'now_pct'  => self::pct($now, $start, $hours),
+            ],
+            'lanes'     => $lanes,
+            'overdue'   => $overdue,
+            'later'     => $later,
+            'anytime'   => $anytime,
+            'handovers' => self::handovers($open, $shifts, $drivers, $orders, $now),
+            'counts'    => [
+                'overdue' => count($overdue),
+                'later'   => count($later),
+                'anytime' => count($anytime),
+                'shifts'  => count($lanes[RadarRules::LANE_SHIFTS]),
+            ],
+        ];
+    }
+
+    /**
+     * Which zone an item lands in, and the entry the lane draws.
+     *
+     * @return array{zone: string, entry: array}
+     */
+    public static function place(array $item, Carbon $start, Carbon $end, Carbon $now): array
+    {
+        $planned = RadarRules::carbon($item['state']['planned_at'] ?? null);
+        $due     = RadarRules::carbon($item['due_at'] ?? null);
+        $at      = $planned ?? $due;
+
+        // A shift gap with no due date is happening now: it sits on the
+        // shifts lane from the moment the window opened.
+        if ($at === null && !empty($item['window']['start_at'])) {
+            $windowStart = RadarRules::carbon($item['window']['start_at']);
+            $at          = $windowStart ? $windowStart->max($now) : null;
+        }
+
+        $entry = self::entry($item, $at, $planned !== null, $start, $end);
+
+        if ($at === null) {
+            return ['zone' => 'anytime', 'entry' => $entry];
+        }
+        if ($at->lt($now) && !$planned) {
+            return ['zone' => 'overdue', 'entry' => $entry];
+        }
+        if ($at->gt($end)) {
+            return ['zone' => 'later', 'entry' => $entry];
+        }
+
+        return ['zone' => 'lane', 'entry' => $entry];
+    }
+
+    /**
+     * The handover cards: shifts ending soon with orders still assigned,
+     * each with the best cover driver we can find.
+     */
+    public static function handovers(array $open, array $shifts, array $drivers, array $orders, Carbon $now, array $rules = ['shift_handover']): array
+    {
+        $cards = [];
+
+        foreach ($open as $item) {
+            if (!in_array($item['rule'] ?? null, $rules, true)) {
+                continue;
+            }
+
+            $driverUuid   = $item['subject']['uuid'] ?? null;
+            $end          = RadarRules::carbon($item['window']['end_at'] ?? null);
+            $driverRows   = array_column($drivers, null, 'uuid');
+            $driver       = $driverRows[$driverUuid] ?? null;
+            $driverOrders = array_values($orders[$driverUuid] ?? []);
+            $suggested    = $end ? self::suggestCover($driverUuid, $driver, $end, $shifts, $driverRows, $now) : null;
+
+            $cards[] = [
+                'key'           => $item['key'],
+                'driver'        => $item['subject'],
+                'rule'          => $item['rule'],
+                'shift'         => ($item['window'] ?? []) + ['uuid' => $item['source']['uuid'] ?? null, 'public_id' => $item['source']['public_id'] ?? null, 'minutes_left' => $end ? max(0, $now->diffInMinutes($end, false)) : null],
+                'orders'        => array_map(fn ($order) => $order + ['finishes_after_shift' => self::finishesAfter($order, $end)], $driverOrders),
+                'active_orders' => (int) ($item['source']['active_orders'] ?? count($driverOrders)),
+                'suggested'     => $suggested,
+                'record'        => $item['record'] ?? null,
+            ];
+        }
+
+        return $cards;
+    }
+
+    /**
+     * The on-shift driver best placed to take the orders: still on shift
+     * past the handover, online, nearest, with capacity to spare.
+     */
+    public static function suggestCover(?string $driverUuid, ?array $driver, Carbon $shiftEnd, array $shifts, array $driverRows, Carbon $now): ?array
+    {
+        $needUntil  = $shiftEnd->copy()->addHours(self::COVER_MARGIN_HOURS);
+        $candidates = [];
+
+        foreach ($shifts as $shift) {
+            $uuid = $shift['driver']['uuid'] ?? null;
+            if (!$uuid || $uuid === $driverUuid || !in_array($shift['status'] ?? 'scheduled', RadarRules::SHIFT_LIVE_STATUSES, true)) {
+                continue;
+            }
+
+            $start = RadarRules::carbon($shift['start_at'] ?? null);
+            $end   = RadarRules::carbon($shift['end_at'] ?? null);
+            if (!$start || !$end || $start->gt($shiftEnd) || $end->lt($needUntil)) {
+                continue;
+            }
+
+            $row      = $driverRows[$uuid] ?? [];
+            $capacity = (int) ($row['max_daily_orders'] ?? self::DEFAULT_CAPACITY) ?: self::DEFAULT_CAPACITY;
+            $active   = (int) ($row['active_orders'] ?? $shift['active_orders'] ?? 0);
+            if ($active >= $capacity) {
+                continue;
+            }
+
+            $distance = self::distanceKm($driver['location'] ?? null, $row['location'] ?? null);
+
+            $candidates[] = [
+                'driver'         => $shift['driver'],
+                'on_shift_until' => $end->toIso8601String(),
+                'online'         => (bool) ($shift['driver_online'] ?? $row['online'] ?? false),
+                'distance_km'    => $distance,
+                'active_orders'  => $active,
+                'capacity'       => $capacity,
+                'capacity_label' => sprintf('%d of %d orders', $active, $capacity),
+            ];
+        }
+
+        if (!$candidates) {
+            return null;
+        }
+
+        usort($candidates, function ($a, $b) {
+            $online = ($b['online'] ? 1 : 0) <=> ($a['online'] ? 1 : 0);
+            if ($online !== 0) {
+                return $online;
+            }
+            $distance = ($a['distance_km'] ?? PHP_FLOAT_MAX) <=> ($b['distance_km'] ?? PHP_FLOAT_MAX);
+            if ($distance !== 0) {
+                return $distance;
+            }
+
+            return $a['active_orders'] <=> $b['active_orders'];
+        });
+
+        return $candidates[0];
+    }
+
+    /**
+     * Great-circle distance in km between two {lat, lng} points, or null.
+     */
+    public static function distanceKm(?array $from, ?array $to): ?float
+    {
+        if (!isset($from['lat'], $from['lng'], $to['lat'], $to['lng'])) {
+            return null;
+        }
+
+        $earth = 6371.0;
+        $dLat  = deg2rad((float) $to['lat'] - (float) $from['lat']);
+        $dLng  = deg2rad((float) $to['lng'] - (float) $from['lng']);
+        $a     = sin($dLat / 2) ** 2 + cos(deg2rad((float) $from['lat'])) * cos(deg2rad((float) $to['lat'])) * sin($dLng / 2) ** 2;
+
+        return round($earth * 2 * atan2(sqrt($a), sqrt(1 - $a)), 1);
+    }
+
+    // ------------------------------------------------------------------
+    // Helpers
+    // ------------------------------------------------------------------
+
+    protected static function entry(array $item, ?Carbon $at, bool $planned, Carbon $start, Carbon $end): array
+    {
+        $lane  = $item['lane'] ?? RadarRules::LANE_ANYTIME;
+        if ($lane === RadarRules::LANE_ANYTIME) {
+            $lane = self::LANE_BY_CATEGORY[$item['category'] ?? ''] ?? RadarRules::LANE_MAINTENANCE;
+        }
+        $hours = max(1, $start->diffInHours($end));
+
+        return [
+            'kind'      => 'item',
+            'key'       => $item['key'],
+            'rule'      => $item['rule'],
+            'chip'      => $item['chip'] ?? null,
+            'category'  => $item['category'] ?? null,
+            'severity'  => $item['severity'] ?? 'info',
+            'title'     => $item['title'],
+            'subject'   => $item['subject'] ?? null,
+            'meta_line' => $item['meta_line'] ?? null,
+            'lane'      => $lane,
+            'at'        => $at?->toIso8601String(),
+            'label'     => $at ? $at->format($start->diffInHours($end) > 24 ? 'D H:i' : 'H:i') : null,
+            'planned'   => $planned,
+            'pct'       => $at ? self::pct($at, $start, $hours) : null,
+            'state'     => $item['state'] ?? null,
+            'actions'   => $item['actions'] ?? [],
+            'record'    => $item['record'] ?? null,
+        ];
+    }
+
+    protected static function shiftBar(array $shift, array $byDriver, Carbon $start, Carbon $end, Carbon $now): ?array
+    {
+        $from   = RadarRules::carbon($shift['start_at'] ?? null);
+        $to     = RadarRules::carbon($shift['end_at'] ?? null);
+        $driver = $shift['driver'] ?? null;
+        if (!$from || !$to || !$driver || $to->lt($start) || $from->gt($end)) {
+            return null;
+        }
+
+        $hours    = max(1, $start->diffInHours($end));
+        $gaps     = $byDriver[$driver['uuid'] ?? ''] ?? [];
+        $handover = null;
+        $worst    = null;
+        foreach ($gaps as $gap) {
+            if ($gap['rule'] === 'shift_handover') {
+                $handover = $gap['key'];
+            }
+            if ($worst === null || self::severityRank($gap['severity']) > self::severityRank($worst)) {
+                $worst = $gap['severity'];
+            }
+        }
+
+        $status = $shift['status'] ?? 'scheduled';
+        $state  = $to->lte($now) ? 'ended' : ($from->gt($now) ? 'upcoming' : (!empty($shift['driver_online']) || $status === 'in_progress' ? 'on_shift' : 'not_online'));
+
+        return [
+            'kind'          => 'shift',
+            'key'           => 'shift:' . ($shift['public_id'] ?? $shift['uuid'] ?? ($driver['public_id'] ?? '')),
+            'driver'        => $driver,
+            'status'        => $status,
+            'state'         => $state,
+            'at'            => $from->toIso8601String(),
+            'end_at'        => $to->toIso8601String(),
+            'label'         => $from->format('H:i') . '–' . $to->format('H:i'),
+            'pct'           => self::pct($from->max($start), $start, $hours),
+            'width_pct'     => max(1.0, round(($from->max($start)->diffInMinutes($to->min($end)) / 60) / $hours * 100, 2)),
+            'lane'          => RadarRules::LANE_SHIFTS,
+            'severity'      => $worst,
+            'gap_keys'      => array_column($gaps, 'key'),
+            'handover_key'  => $handover,
+            'active_orders' => (int) ($shift['active_orders'] ?? 0),
+            'vehicle_uuid'  => $shift['driver_vehicle_uuid'] ?? null,
+        ];
+    }
+
+    protected static function finishesAfter(array $order, ?Carbon $shiftEnd): bool
+    {
+        $ends = RadarRules::carbon($order['ends_at'] ?? null);
+
+        return (bool) ($shiftEnd && $ends && $ends->gt($shiftEnd));
+    }
+
+    protected static function ticks(Carbon $start, int $hours): array
+    {
+        $ticks = [];
+        $step  = $hours > 24 ? 24 : 2;
+        for ($offset = 0; $offset <= $hours; $offset += $step) {
+            $at      = $start->copy()->addHours($offset);
+            $ticks[] = ['at' => $at->toIso8601String(), 'label' => $hours > 24 ? $at->format('D j') : $at->format('H'), 'pct' => round($offset / $hours * 100, 2)];
+        }
+
+        return $ticks;
+    }
+
+    protected static function pct(Carbon $at, Carbon $start, int $hours): float
+    {
+        return round(max(0, min(100, $start->diffInMinutes($at, false) / 60 / $hours * 100)), 2);
+    }
+
+    protected static function severityRank(?string $severity): int
+    {
+        return [RadarRules::SEVERITY_CRITICAL => 3, RadarRules::SEVERITY_WARNING => 2, RadarRules::SEVERITY_INFO => 1][$severity] ?? 0;
+    }
+}