@fleetbase/fleetops-engine 0.6.65 → 0.6.67

package/addon/utils/fleet-ops-options.js

@@ -216,6 +216,41 @@ export const fuelReportStatuses = [
     { label: 'Reimbursed', value: 'reimbursed', description: 'Driver expense reimbursed' },
 ];
 
+export const inspectionFormTypes = [
+    { label: 'DVIR', value: 'dvir', description: 'Driver vehicle inspection report — the daily walk-round a driver signs.' },
+    { label: 'Pre-Trip', value: 'pre_trip', description: 'Completed before the vehicle leaves.' },
+    { label: 'Post-Trip', value: 'post_trip', description: 'Completed when the vehicle returns.' },
+    { label: 'Pre-Operational', value: 'pre_operational', description: 'Checks performed before operation begins.' },
+    { label: 'Post-Operational', value: 'post_operational', description: 'Checks performed after operation ends.' },
+    { label: 'Safety Inspection', value: 'safety_inspection', description: 'Comprehensive safety and compliance inspection.' },
+    { label: 'Maintenance Inspection', value: 'maintenance_inspection', description: 'Scheduled maintenance check and service inspection.' },
+    { label: 'Damage Assessment', value: 'damage_assessment', description: 'Inspection to assess damage or condition issues.' },
+    { label: 'Annual Inspection', value: 'annual_inspection', description: 'Yearly comprehensive vehicle inspection.' },
+    { label: 'Safety', value: 'safety', description: 'General safety checklist.' },
+    { label: 'Compliance', value: 'compliance', description: 'Regulatory or audit checklist.' },
+    { label: 'Maintenance', value: 'maintenance', description: 'Workshop or technician checklist.' },
+];
+
+export const inspectionFormStatuses = [
+    { label: 'Draft', value: 'draft', description: 'Still being written. Drivers cannot see it.' },
+    { label: 'Published', value: 'published', description: 'Available to drivers and to the public link.' },
+    { label: 'Archived', value: 'archived', description: 'Retired. Kept for the records already filed against it.' },
+];
+
+export const inspectionSeverities = [
+    { label: 'Minor', value: 'low', description: 'Monitor it. Nothing stops.' },
+    { label: 'Medium', value: 'medium', description: 'Book it in.' },
+    { label: 'High', value: 'high', description: 'Unsafe. Needs attention before the next trip.' },
+    { label: 'Critical', value: 'critical', description: 'Immobilise the vehicle.' },
+];
+
+export const inspectionSubmissionStatuses = [
+    { label: 'Draft', value: 'draft', description: 'Started but not filed.' },
+    { label: 'Submitted', value: 'submitted', description: 'Filed by the driver or the console.' },
+    { label: 'Needs Review', value: 'needs_review', description: 'Flagged for a supervisor to look at.' },
+    { label: 'Resolved', value: 'resolved', description: 'Follow-up is complete.' },
+];
+
 export const workOrderStatuses = [
     { label: 'Open', value: 'open', description: 'Work order has been created and is awaiting planning or assignment' },
     { label: 'Scheduled', value: 'scheduled', description: 'Work has been planned for a specific service window' },
@@ -945,6 +980,11 @@ export default function fleetOpsOptions(key) {
         routingConstraintOptions,
         serviceTimePresets,
         importColumnMappings,
+        // Inspections
+        inspectionFormTypes,
+        inspectionFormStatuses,
+        inspectionSeverities,
+        inspectionSubmissionStatuses,
     };
 
     return allOptions[key] ?? [];

package/addon/utils/fuel-integration-format.js

@@ -0,0 +1,43 @@
+export function fuelDate(value, fallback = 'Not yet') {
+    if (!value) return fallback;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) return fallback;
+    const pad = (number) => String(number).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+export function fuelNumber(value) {
+    return Number(value ?? 0).toLocaleString('en-US', { maximumFractionDigits: 2 });
+}
+
+export function fuelMoney(amount, currency) {
+    return `${currency || 'SAR'} ${fuelNumber(Number(amount ?? 0) / 100)}`;
+}
+
+export function syncRunView(run) {
+    const received = run.summary?.received ?? Number(run.imported ?? 0) + Number(run.summary?.updated ?? 0);
+    const pending = ['queued', 'running'].includes(run.status);
+    const waiting = run.status === 'queued' && Date.now() - new Date(run.created_at).getTime() > 120000;
+    const labels = { queued: 'Queued', running: 'Importing', completed: 'Completed', error: 'Failed' };
+    return {
+        ...run,
+        pending,
+        label: labels[run.status] ?? run.status,
+        tone: run.status === 'error' ? 'danger' : pending ? 'warning' : 'success',
+        date: fuelDate(run.finished_at || run.started_at || run.created_at),
+        window: run.from && run.to ? `${String(run.from).slice(0, 10)} – ${String(run.to).slice(0, 10)}` : 'Date range unavailable for this earlier run',
+        result:
+            run.status === 'error'
+                ? run.error || 'The import failed. Retry this date range.'
+                : waiting
+                  ? 'Still queued. Check that the background worker is running.'
+                  : run.status === 'queued'
+                    ? 'Waiting for the background worker.'
+                    : run.status === 'running'
+                      ? 'Reading transactions from the provider.'
+                      : received === 0
+                        ? 'No transactions returned for this date range.'
+                        : `${fuelNumber(run.imported)} new · ${fuelNumber(run.summary?.updated)} updated · ${fuelNumber(run.unmatched)} need matching`,
+        received,
+    };
+}

package/addon/utils/fuel-transaction.js

@@ -0,0 +1,115 @@
+import { fuelDate, fuelMoney } from './fuel-integration-format';
+
+export const transactionStatuses = {
+    imported: { label: 'Imported', tone: 'info' },
+    matched: { label: 'Matched', tone: 'success' },
+    unmatched: { label: 'Unmatched', tone: 'warning' },
+    reviewed: { label: 'Reviewed', tone: 'success' },
+    ignored: { label: 'Ignored', tone: 'default' },
+    duplicate: { label: 'Duplicate', tone: 'warning' },
+    error: { label: 'Error', tone: 'error' },
+};
+
+export const transactionActions = {
+    vehicle: {
+        title: 'Match to Vehicle',
+        description: 'Choose the vehicle for this purchase. Confirming replaces the current vehicle match and may create a Fuel Report according to the integration settings.',
+    },
+    order: {
+        title: 'Match to Order',
+        description: 'Choose the order or trip for this purchase. Confirming replaces the current order link. The vehicle match and review status are unchanged.',
+    },
+    reprocess: {
+        title: 'Reprocess / Rematch',
+        description:
+            'Run the integration’s matching rules again for missing matches. Existing vehicle and order links are kept. Reviewed or ignored status will be replaced with Matched or Unmatched. A Fuel Report may be created if enabled in the integration settings.',
+    },
+    ignored: {
+        title: 'Ignore Transaction',
+        description:
+            'Exclude this purchase from automatic matching while keeping it in the ledger. Existing matches and Fuel Reports are kept. You can reprocess it later to resume matching.',
+    },
+    reviewed: { title: 'Mark Reviewed', description: 'Confirm that you have checked this purchase. This updates its review status without changing its vehicle, order, or Fuel Report.' },
+};
+
+export function openTransactionAction(modalsManager, mode, transactions, onSaved) {
+    const records = Array.isArray(transactions) ? transactions : [transactions];
+    if (!records.length || !transactionActions[mode]) return;
+    return modalsManager.show('modals/fuel-transaction-action', {
+        title: transactionActions[mode].title,
+        acceptButtonText: transactionActions[mode].title,
+        acceptButtonType: mode === 'ignored' ? 'danger' : 'primary',
+        declineButtonText: 'Cancel',
+        keepOpen: true,
+        mode,
+        transactions: records,
+        onSaved,
+    });
+}
+
+export async function loadTransactionOrder(store, transaction) {
+    const orderId = transaction?.order_uuid;
+
+    if (!orderId) {
+        return null;
+    }
+
+    // The transaction response carries the foreign key without an order relationship.
+    const order = await store.findRecord('order', orderId, { reload: true });
+
+    if (transaction.order_uuid !== orderId) {
+        return null;
+    }
+
+    transaction.set('order', order);
+    return order;
+}
+
+const present = (value) => ['string', 'number'].includes(typeof value) && String(value).trim() !== '';
+const text = (value) => (present(value) ? String(value).trim() : null);
+
+// Only named purchase fields are presented. Unknown payload objects, provider codes,
+// credentials and other integration internals never become operator-facing content.
+export function purchaseGroups(transaction) {
+    const normalized = transaction.normalized_payload ?? {};
+    const raw = transaction.raw_payload ?? {};
+    const value = (...keys) => keys.flatMap((key) => [normalized[key], raw[key]]).find(present);
+    const group = (title, rows) => ({ title, rows: rows.filter(([, value]) => present(value)).map(([label, value]) => ({ label, value: text(value) })) });
+    const petroapp = transaction.provider === 'petroapp';
+    const groups = [
+        group('Purchase', [
+            ['Bill number', transaction.provider_transaction_id],
+            ['Purchased at', transaction.transaction_at ? fuelDate(transaction.transaction_at, 'Unavailable') : null],
+            ['Amount', present(transaction.amount) ? fuelMoney(transaction.amount, transaction.currency) : null],
+            ['Quantity', present(transaction.volume) ? `${transaction.volume} ${transaction.metric_unit || 'L'}` : null],
+            ['Fuel type', value('fuel_type', 'product_name', 'fuel_grade')],
+            ['Payment method', value('payment_method_text', 'payment_method_name')],
+            ['Odometer', transaction.odometer],
+            ['Invoice number', value('invoice_number')],
+            [
+                'Amount before VAT',
+                petroapp && present(raw.cost_before_vat) ? `${transaction.currency || 'SAR'} ${Number(raw.cost_before_vat).toLocaleString('en-US', { maximumFractionDigits: 3 })}` : null,
+            ],
+            ['VAT rate', petroapp && present(raw.vat_percent) ? `${Number(raw.vat_percent) * 100}%` : null],
+        ]),
+        group('Station & account', [
+            ['Station', transaction.station_name],
+            ['City', value('city')],
+            ['District', value('district')],
+            ['Account branch', value('branch_name')],
+            ['Representative', value('delegate_name')],
+            ['Representative phone', petroapp ? value('delegate_mobile') : null],
+        ]),
+        group('Vehicle & trip references', [
+            ['Plate number', transaction.plate_number],
+            ['Fuel card', transaction.vehicle_card_id],
+            ['Internal number', transaction.internal_number],
+            ['Structure number', transaction.structure_number],
+            ['Trip number', transaction.trip_number],
+            ['VIN', value('vin', 'vin_number')],
+            ['Serial number', value('serial_number')],
+            ['Call sign', value('call_sign')],
+        ]),
+    ];
+    return groups.filter((group) => group.rows.length);
+}

package/addon/utils/identity-cell-resource.js

@@ -18,3 +18,59 @@ export function resolveIdentityCellResource(args) {
 
     return args.row;
 }
+
+const inflight = new WeakMap();
+
+/**
+ * A stand-in for a related record a row only knows by name: enough for an
+ * identity cell to render (`name`, `resourceType`) and a `loadResource()`
+ * the cell, pill or summary calls when the real record is needed. The
+ * stub never carries a UUID in an identifier field, so nothing renders one
+ * as a plate or an id, and concurrent loads of the same row share one
+ * request.
+ *
+ * `load` receives the row and returns the record (or a promise of it); with
+ * no `load`, `loadResource()` resolves to null and the stub stays static.
+ */
+export function buildIdentityStub(row, { type, nameKey = `${type}_name`, name, load, extra = {} } = {}) {
+    const label = name ?? (row ? get(row, nameKey) : null);
+
+    if (!label) {
+        return null;
+    }
+
+    const stub = {
+        ...extra,
+        name: label,
+        display_name: label,
+        displayName: label,
+        resourceType: type,
+        isIdentityStub: true,
+        loadResource: async () => {
+            if (typeof load !== 'function') {
+                return null;
+            }
+
+            let loads = inflight.get(row);
+
+            if (!loads) {
+                loads = new Map();
+                inflight.set(row, loads);
+            }
+
+            if (!loads.has(type)) {
+                loads.set(
+                    type,
+                    Promise.resolve()
+                        .then(() => load(row))
+                        .catch(() => null)
+                        .finally(() => loads.delete(type))
+                );
+            }
+
+            return loads.get(type);
+        },
+    };
+
+    return stub;
+}

package/addon/utils/inspection-answers.js

@@ -0,0 +1,283 @@
+/**
+ * Reading an inspection's answers.
+ *
+ * The sheet, its section headers and its running total all need the same
+ * questions answered — did this row pass, is a required row still blank, is
+ * anything on this form unsafe to operate — and they must agree, so they ask
+ * here rather than each working it out from the raw value.
+ *
+ * The rules mirror the driver app's `src/v3/data/useInspections.ts`, so a form
+ * filled in from a phone and the same form filled in from the console are
+ * counted the same way.
+ */
+
+import { flattenFields } from './inspection-form-structure';
+import { valueTypeForFieldType } from './inspection-field-types';
+
+/** A pass-fail answer, in one shape whatever was stored. */
+export function passFailAnswer(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+
+    // The first cut stored a bare boolean.
+    if (typeof value === 'boolean') {
+        return { passed: value, not_applicable: false };
+    }
+
+    return null;
+}
+
+/**
+ * What a pass-fail row currently says: `pass`, `fail`, `na`, or null when the
+ * field is not a pass-fail field at all.
+ */
+export function answerState(field, value) {
+    if (field?.type !== 'pass-fail') {
+        return null;
+    }
+
+    const answer = passFailAnswer(value);
+    if (!answer) {
+        return null;
+    }
+
+    if (answer.not_applicable === true) {
+        return 'na';
+    }
+
+    return answer.passed === false ? 'fail' : 'pass';
+}
+
+/** Whether a failed row was marked unsafe to operate. */
+export function isUnsafeAnswer(field, value) {
+    return answerState(field, value) === 'fail' && passFailAnswer(value)?.unsafe === true;
+}
+
+/**
+ * Whether a required field is still waiting for an answer.
+ *
+ * A pass-fail row is never blank — it opens on Pass, which is what the driver
+ * app does too — and a toggle is never blank, because off is an answer.
+ */
+export function isBlank(field, value) {
+    if (field?.type === 'pass-fail' || field?.type === 'boolean') {
+        return false;
+    }
+
+    if (value === null || value === undefined || value === '') {
+        return true;
+    }
+
+    return Array.isArray(value) && value.length === 0;
+}
+
+/** Whether a failed row is still missing the comment or photo its field demands. */
+export function defectIncomplete(field, value) {
+    if (answerState(field, value) !== 'fail') {
+        return false;
+    }
+
+    const meta = field?.meta && typeof field.meta === 'object' ? field.meta : {};
+    const answer = passFailAnswer(value) ?? {};
+
+    if (meta.require_comment_on_fail === true && !String(answer.comments ?? '').trim()) {
+        return true;
+    }
+
+    return meta.require_photo_on_fail === true && !(Array.isArray(answer.photos) && answer.photos.length > 0);
+}
+
+/** The types that always need the full width of a group, whatever the answer. */
+export const ROOMY_FIELD_TYPES = ['textarea', 'file-upload', 'signature'];
+
+/**
+ * Whether a field spans the full width of its group's grid.
+ *
+ * Only the types whose size the form itself decides: a note, an upload, a
+ * signature. It depends on the field and never on the answer, so answering a
+ * field can never change the layout. A failure's detail used to widen its
+ * field too, which re-flowed the group every time a check failed; it now
+ * opens in a flyout instead, and the field stays the size it was.
+ */
+// eslint-disable-next-line no-unused-vars
+export function isPromoted(field, value) {
+    return ROOMY_FIELD_TYPES.includes(field?.type);
+}
+
+/**
+ * What a failed check has recorded, in one shape: for the chip a closed
+ * failure leaves behind in its field, and for the defects tray.
+ */
+export function defectSummary(field, value) {
+    const answer = passFailAnswer(value) ?? {};
+    const photos = Array.isArray(answer.photos) ? answer.photos : [];
+    const meta = field?.meta && typeof field.meta === 'object' ? field.meta : {};
+    const hasComment = Boolean(String(answer.comments ?? '').trim());
+
+    return {
+        field,
+        severity: answer.severity ?? meta.severity ?? null,
+        unsafe: answer.unsafe === true,
+        photoCount: photos.length,
+        hasComment,
+        needsComment: meta.require_comment_on_fail === true && !hasComment,
+        needsPhoto: meta.require_photo_on_fail === true && photos.length === 0,
+        incomplete: defectIncomplete(field, value),
+    };
+}
+
+/** Every failed check on the sheet, in the order they are answered. */
+export function listDefects(fields = [], values = {}) {
+    return fields.filter((field) => answerState(field, values?.[field.uuid]) === 'fail').map((field) => defectSummary(field, values?.[field.uuid]));
+}
+
+/**
+ * The one-word state a group header's dot shows for a field: `pass`, `fail`,
+ * `na`, `outstanding` (required and unanswered, or a failure still owing its
+ * comment or photo), `done`, or `empty`.
+ */
+export function fieldMarker(field, value) {
+    const state = answerState(field, value);
+
+    if (state === 'fail') {
+        return defectIncomplete(field, value) ? 'outstanding' : 'fail';
+    }
+
+    if (state) {
+        return state;
+    }
+
+    if (field?.required && isBlank(field, value)) {
+        return 'outstanding';
+    }
+
+    return isBlank(field, value) ? 'empty' : 'done';
+}
+
+/**
+ * The totals a section header and the sheet's foot both read.
+ *
+ * `outstanding` is what still stops the sheet being finished: a required field
+ * left blank, or a failure that owes a comment or a photo.
+ */
+export function summarize(fields = [], values = {}) {
+    const summary = {
+        total: fields.length,
+        checks: 0,
+        passed: 0,
+        failed: 0,
+        notApplicable: 0,
+        missingRequired: 0,
+        incompleteDefects: 0,
+        unsafe: false,
+        unsafeField: null,
+        firstOutstanding: null,
+    };
+
+    for (const field of fields) {
+        const value = values?.[field.uuid];
+        const state = answerState(field, value);
+
+        if (state) {
+            summary.checks += 1;
+
+            if (state === 'pass') {
+                summary.passed += 1;
+            } else if (state === 'fail') {
+                summary.failed += 1;
+            } else {
+                summary.notApplicable += 1;
+            }
+        }
+
+        if (field.required && isBlank(field, value)) {
+            summary.missingRequired += 1;
+        }
+
+        if (defectIncomplete(field, value)) {
+            summary.incompleteDefects += 1;
+        }
+
+        // The banners name the field rather than counting it, so an inspector
+        // is told what to go and fix, not how many things are wrong.
+        if (!summary.firstOutstanding && fieldMarker(field, value) === 'outstanding') {
+            summary.firstOutstanding = field;
+        }
+
+        if (isUnsafeAnswer(field, value)) {
+            summary.unsafe = true;
+
+            if (!summary.unsafeField) {
+                summary.unsafeField = field;
+            }
+        }
+    }
+
+    summary.outstanding = summary.missingRequired + summary.incompleteDefects;
+
+    return summary;
+}
+
+/**
+ * The answer every field starts with.
+ *
+ * A pass-fail row opens on Pass, so a sheet saved untouched still files a
+ * complete set — which is what the driver app does, and what the first cut of
+ * the console did. Everything else starts empty.
+ */
+export function seedAnswers(groups = [], stored = {}) {
+    return flattenFields(groups).reduce((carry, field) => {
+        if (stored?.[field.uuid] !== undefined) {
+            carry[field.uuid] = stored[field.uuid];
+            return carry;
+        }
+
+        carry[field.uuid] = field.type === 'pass-fail' ? { passed: true, not_applicable: false, severity: null, comments: '', photos: [], unsafe: false } : null;
+
+        return carry;
+    }, {});
+}
+
+/**
+ * A file value is a reference on the way out, whichever way it came in: the
+ * `file:<uuid>` a fresh upload leaves, or the `{ id, url, … }` the submission
+ * resource resolved a stored reference to.
+ */
+function serializeFile(value) {
+    if (value && typeof value === 'object') {
+        return value.id ?? null;
+    }
+
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+
+function serializeValue(field, value) {
+    if (field.type === 'pass-fail') {
+        const answer = passFailAnswer(value) ?? { passed: true, not_applicable: false };
+
+        return {
+            ...answer,
+            photos: (Array.isArray(answer.photos) ? answer.photos : []).map(serializeFile).filter(Boolean),
+        };
+    }
+
+    if (field.type === 'file-upload' || field.type === 'signature') {
+        return serializeFile(value);
+    }
+
+    return value;
+}
+
+/**
+ * The answers as the server takes them — the same `custom_field_values` body
+ * the driver API accepts, so the console, a public link and the app all file
+ * the same rows and the item results are derived from the same place.
+ */
+export function answerRows(fields = [], values = {}) {
+    return fields.map((field) => ({
+        custom_field: field.uuid,
+        value_type: valueTypeForFieldType(field.type),
+        value: serializeValue(field, values?.[field.uuid]),
+    }));
+}

package/addon/utils/inspection-field-types.js

@@ -0,0 +1,74 @@
+/**
+ * The field types an inspection form may be built from.
+ *
+ * This list mirrors `Fleetbase\FleetOps\Models\InspectionForm::FIELD_TYPES`
+ * exactly — the server refuses anything else and falls back to `input`, so the
+ * builder must not offer a type the writer will silently rewrite.
+ */
+export const INSPECTION_FIELD_TYPES = ['pass-fail', 'input', 'textarea', 'number', 'select', 'radio-button', 'boolean', 'date-picker', 'date-time-input', 'file-upload', 'signature'];
+
+/** The severities a failed pass-fail answer can carry. */
+export const INSPECTION_SEVERITIES = ['low', 'medium', 'high', 'critical'];
+
+/** The types whose answer is chosen from a list the author writes. */
+export const OPTION_FIELD_TYPES = ['select', 'radio-button'];
+
+/**
+ * The types FleetOps renders itself. `pass-fail`, `signature` and the
+ * inspection flavour of `file-upload` are inspection-only; `textarea`,
+ * `number` and `boolean` are ordinary but absent from the platform's
+ * custom-field type map, so there is nothing to delegate them to.
+ */
+export const FLEETOPS_OWNED_FIELD_TYPES = ['pass-fail', 'signature', 'file-upload', 'textarea', 'number', 'boolean'];
+
+/** The types the platform's own `custom-field/input` already renders. */
+export const DELEGATED_FIELD_TYPES = ['input', 'select', 'radio-button', 'date-picker', 'date-time-input'];
+
+/**
+ * The console component that renders a field type. Mirrors
+ * `InspectionFormSync::componentFor()` so a field built here and a field
+ * converted from the first cut's checklist name the same component.
+ */
+export function componentForFieldType(type) {
+    return type === 'radio-button' ? 'radio-button-select' : type;
+}
+
+/**
+ * How the server stores an answer of this type — the `value_type` a submitted
+ * `custom_field_values` row carries. Mirrors `InspectionSubmitter::normalizeValue()`
+ * and the app's own `valueTypeFor` in `src/v3/data/useInspections.ts`, so the
+ * console and the driver app file the same rows.
+ */
+export function valueTypeForFieldType(type) {
+    switch (type) {
+        case 'pass-fail':
+            return 'object';
+        case 'file-upload':
+        case 'signature':
+            return 'file';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'date-picker':
+            return 'date';
+        case 'date-time-input':
+            return 'datetime';
+        default:
+            return 'text';
+    }
+}
+
+/** Whether a field of this type needs the author to write its options. */
+export function isOptionFieldType(type) {
+    return OPTION_FIELD_TYPES.includes(type);
+}
+
+/** Whether FleetOps renders this type itself rather than delegating it. */
+export function isFleetOpsOwnedFieldType(type) {
+    return FLEETOPS_OWNED_FIELD_TYPES.includes(type);
+}
+
+export default function inspectionFieldTypes() {
+    return INSPECTION_FIELD_TYPES;
+}