@fleetbase/fleetops-engine 0.6.65 → 0.6.66

package/server/src/Support/InspectionFormSync.php

@@ -0,0 +1,231 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\InspectionForm;
+use Fleetbase\Models\Category;
+use Fleetbase\Models\CustomField;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+/**
+ * Writes a form's structure — groups of typed fields — from the shape the
+ * console builder holds it in, and converts the first cut's checklist into
+ * that structure.
+ *
+ * The console builder lets a form be laid out before the form record exists,
+ * so the whole draft arrives with the first save and has to be written in one
+ * go: groups become platform categories owned by the form, fields become
+ * platform custom fields whose subject is the form. Rows are matched on their
+ * uuid so a second post updates rather than duplicates; rows the post no
+ * longer mentions are pruned only when asked, because a partial post is the
+ * common case and losing fields is not.
+ */
+class InspectionFormSync
+{
+    /** The group columns the builder is allowed to write. */
+    public const GROUP_COLUMNS = ['name', 'description', 'meta', 'order', 'icon', 'icon_color', 'translations', 'tags'];
+
+    /** The field columns the builder is allowed to write. */
+    public const FIELD_COLUMNS = ['name', 'label', 'type', 'component', 'options', 'required', 'editable', 'default_value', 'validation_rules', 'meta', 'description', 'help_text', 'order', 'for'];
+
+    /**
+     * @param InspectionForm $form         the form the structure belongs to
+     * @param array          $draft        groups, each with its fields under `fields` or `customFields`
+     * @param bool           $pruneMissing drop groups and fields the draft no longer lists
+     * @param string         $primaryKey   the key rows are matched on, `uuid` or `id`
+     *
+     * @return array{groups: Category[], fields: CustomField[]}
+     */
+    public static function sync(InspectionForm $form, array $draft, bool $pruneMissing = false, string $primaryKey = 'uuid'): array
+    {
+        $existingGroups = Category::query()
+            ->where(['owner_uuid' => $form->uuid, 'for' => InspectionForm::GROUP_FOR])
+            ->get()
+            ->keyBy('uuid');
+        // Only the fields a driver answers. A custom field the console's
+        // generic panel added to the form *record* has the same subject and
+        // would otherwise be pruned as a field the builder no longer lists.
+        $existingFields = CustomField::query()
+            ->where(['subject_uuid' => $form->uuid, 'for' => InspectionForm::FIELD_FOR])
+            ->get()
+            ->keyBy('uuid');
+
+        $keptGroups = [];
+        $keptFields = [];
+        $now        = now();
+
+        foreach (array_values($draft) as $groupIndex => $groupData) {
+            $groupUuid  = Arr::get($groupData, $primaryKey);
+            $group      = $groupUuid ? $existingGroups->get($groupUuid) : null;
+            $groupUuid  = $group?->uuid ?? ($groupUuid ?: (string) Str::uuid());
+            $groupAttrs = static::normalizeRow(Arr::only($groupData, static::GROUP_COLUMNS), $groupIndex);
+
+            if ($group) {
+                DB::table('categories')->where('uuid', $groupUuid)->update(array_merge($groupAttrs, ['updated_at' => $now]));
+            } else {
+                DB::table('categories')->insert(array_merge($groupAttrs, [
+                    'uuid'         => $groupUuid,
+                    'public_id'    => 'category_' . Str::lower(Str::random(14)),
+                    'company_uuid' => $form->company_uuid,
+                    'owner_uuid'   => $form->uuid,
+                    'owner_type'   => $form->getMorphClass(),
+                    'for'          => InspectionForm::GROUP_FOR,
+                    'slug'         => Str::slug((string) ($groupAttrs['name'] ?? 'group')),
+                    'created_at'   => $now,
+                    'updated_at'   => $now,
+                ]));
+            }
+
+            $keptGroups[] = $groupUuid;
+
+            $fields = Arr::get($groupData, 'fields', Arr::get($groupData, 'customFields', []));
+            foreach (array_values(is_array($fields) ? $fields : []) as $fieldIndex => $fieldData) {
+                $fieldUuid  = Arr::get($fieldData, $primaryKey);
+                $field      = $fieldUuid ? $existingFields->get($fieldUuid) : null;
+                $fieldUuid  = $field?->uuid ?? ($fieldUuid ?: (string) Str::uuid());
+                $fieldAttrs = static::normalizeField(Arr::only($fieldData, static::FIELD_COLUMNS), $fieldIndex);
+
+                if ($field) {
+                    DB::table('custom_fields')->where('uuid', $fieldUuid)->update(array_merge($fieldAttrs, ['category_uuid' => $groupUuid, 'updated_at' => $now]));
+                } else {
+                    DB::table('custom_fields')->insert(array_merge($fieldAttrs, [
+                        'uuid'          => $fieldUuid,
+                        'company_uuid'  => $form->company_uuid,
+                        'category_uuid' => $groupUuid,
+                        'subject_uuid'  => $form->uuid,
+                        'subject_type'  => $form->getMorphClass(),
+                        'created_at'    => $now,
+                        'updated_at'    => $now,
+                    ]));
+                }
+
+                $keptFields[] = $fieldUuid;
+            }
+        }
+
+        if ($pruneMissing) {
+            static::prune($form, $existingGroups, $keptGroups, $existingFields, $keptFields);
+        }
+
+        $form->unsetRelation('fieldGroups');
+        $form->unsetRelation('fields');
+        $form->load(['fieldGroups', 'fields']);
+
+        return ['groups' => $form->fieldGroups->all(), 'fields' => $form->fields->all()];
+    }
+
+    /**
+     * Converts the first cut's `items` checklist into a "Checklist" group of
+     * pass-fail fields. Skips forms that have already been built with fields,
+     * and forms with nothing to convert, so it can be run any number of times.
+     *
+     * @return int the number of fields written
+     */
+    public static function convertLegacyItems(InspectionForm $form): int
+    {
+        $items = array_values(array_filter(is_array($form->items) ? $form->items : [], 'is_array'));
+        if (empty($items) || $form->fields()->count() > 0) {
+            return 0;
+        }
+
+        $fields = [];
+        foreach ($items as $index => $item) {
+            $label    = trim((string) ($item['label'] ?? $item['title'] ?? ''));
+            $label    = $label === '' ? 'Item ' . ($index + 1) : $label;
+            $fields[] = [
+                'label'       => $label,
+                'name'        => Str::slug((string) ($item['key'] ?? $label)),
+                'type'        => 'pass-fail',
+                'required'    => (bool) ($item['required'] ?? true),
+                'description' => $item['description'] ?? null,
+                'order'       => $index + 1,
+                'meta'        => [
+                    'severity'                => $item['severity'] ?? 'medium',
+                    'category'                => $item['category'] ?? null,
+                    'require_photo_on_fail'   => false,
+                    'require_comment_on_fail' => false,
+                    'unsafe_on_fail'          => ($item['severity'] ?? null) === 'critical',
+                ],
+            ];
+        }
+
+        $synced = static::sync($form, [[
+            'name'   => 'Checklist',
+            'order'  => 1,
+            'meta'   => ['grid_size' => 1, 'converted_from_items' => true],
+            'fields' => $fields,
+        ]]);
+
+        return count($synced['fields']);
+    }
+
+    /** Group attributes as the categories table stores them. */
+    protected static function normalizeRow(array $attributes, int $index): array
+    {
+        if (!array_key_exists('order', $attributes) || $attributes['order'] === null) {
+            $attributes['order'] = $index + 1;
+        }
+
+        foreach ($attributes as $key => $value) {
+            if (is_array($value) || is_object($value)) {
+                $attributes[$key] = json_encode($value, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+            }
+        }
+
+        return $attributes;
+    }
+
+    /** Field attributes as the custom_fields table stores them. */
+    protected static function normalizeField(array $attributes, int $index): array
+    {
+        $label = trim((string) ($attributes['label'] ?? ''));
+        if ($label === '') {
+            $label = 'Untitled field';
+        }
+
+        $attributes['label'] = $label;
+        $attributes['name']  = Str::slug((string) (($attributes['name'] ?? '') ?: $label));
+        $attributes['type']  = in_array($attributes['type'] ?? null, InspectionForm::FIELD_TYPES, true) ? $attributes['type'] : 'input';
+        $attributes['for']   = InspectionForm::FIELD_FOR;
+
+        if (empty($attributes['component'])) {
+            $attributes['component'] = static::componentFor($attributes['type']);
+        }
+
+        foreach (['required', 'editable'] as $flag) {
+            $attributes[$flag] = (int) filter_var($attributes[$flag] ?? ($flag === 'editable'), FILTER_VALIDATE_BOOLEAN);
+        }
+
+        return static::normalizeRow($attributes, $index);
+    }
+
+    /**
+     * The console component that edits a field type. The platform's own
+     * types keep the platform's components; the inspection-only types are
+     * rendered by FleetOps and named after themselves.
+     */
+    public static function componentFor(string $type): string
+    {
+        return $type === 'radio-button' ? 'radio-button-select' : $type;
+    }
+
+    protected static function prune(InspectionForm $form, Collection $existingGroups, array $keptGroups, Collection $existingFields, array $keptFields): void
+    {
+        $groupsToDelete = $existingGroups->keys()->diff($keptGroups)->values();
+        if ($groupsToDelete->isNotEmpty()) {
+            CustomField::query()
+                ->where(['subject_uuid' => $form->uuid, 'for' => InspectionForm::FIELD_FOR])
+                ->whereIn('category_uuid', $groupsToDelete)
+                ->delete();
+            Category::query()->whereIn('uuid', $groupsToDelete)->delete();
+        }
+
+        $fieldsToDelete = $existingFields->keys()->diff($keptFields)->values();
+        if ($fieldsToDelete->isNotEmpty()) {
+            CustomField::query()->whereIn('uuid', $fieldsToDelete)->delete();
+        }
+    }
+}

package/server/src/Support/InspectionLinkPin.php

@@ -0,0 +1,150 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Mail\InspectionLinkPinMail;
+use Fleetbase\FleetOps\Models\InspectionLink;
+use Fleetbase\Models\Company;
+use Fleetbase\Models\User;
+use Fleetbase\Services\SmsService;
+use Fleetbase\Support\Utils;
+use Illuminate\Support\Facades\Mail;
+
+/**
+ * Sends an inspection link and its PIN to whoever the link is for.
+ *
+ * The message carries both, so the recipient can open the inspection straight
+ * from it. The PIN still stops anyone who has only the link, such as a link
+ * copied or forwarded on its own, and it locks the link after a few wrong
+ * guesses.
+ */
+class InspectionLinkPin
+{
+    public const VIA = ['email', 'sms'];
+
+    /** Who a link's PIN goes to: the assignee, or failing that the driver's account. */
+    public static function recipientFor(InspectionLink $link): ?User
+    {
+        return $link->assignee ?? $link->driver?->user;
+    }
+
+    /** Why a PIN cannot go to this person this way, or null when it can. */
+    public static function unavailableReason(?User $recipient, string $via): ?string
+    {
+        if (!$recipient) {
+            return 'Assign the link to someone, or pick a driver, to send the PIN to.';
+        }
+
+        if ($via === 'sms' && !filled($recipient->phone)) {
+            return ($recipient->name ?: 'This person') . ' has no phone number to text the PIN to.';
+        }
+
+        if ($via === 'email' && !filled($recipient->email)) {
+            return ($recipient->name ?: 'This person') . ' has no email address to send the PIN to.';
+        }
+
+        return null;
+    }
+
+    /**
+     * Send the link's PIN. Never throws: a failed delivery is reported in the
+     * result, so minting a link does not fail because a mailer is misconfigured.
+     *
+     * @return array{sent: bool, via: string, to: ?string, error: ?string}
+     */
+    public static function send(InspectionLink $link, string $via): array
+    {
+        $recipient = static::recipientFor($link);
+        $reason    = static::unavailableReason($recipient, $via);
+
+        if (!$link->pin) {
+            $reason = 'This link has no PIN to send.';
+        }
+
+        if ($reason) {
+            return ['sent' => false, 'via' => $via, 'to' => null, 'error' => $reason];
+        }
+
+        try {
+            if ($via === 'sms') {
+                // Resolved from the container rather than built here, so the
+                // provider can be swapped out without touching this class.
+                $result = app(SmsService::class)->send($recipient->phone, static::smsText($link, $link->pin, static::urlFor($link)), static::smsOptions($link));
+
+                if (is_array($result) && array_key_exists('success', $result) && !$result['success']) {
+                    return ['sent' => false, 'via' => $via, 'to' => null, 'error' => 'The PIN could not be texted: ' . ($result['error'] ?? $result['message'] ?? 'the SMS provider refused it.')];
+                }
+
+                $to = static::maskPhone($recipient->phone);
+            } else {
+                Mail::to($recipient)->send(new InspectionLinkPinMail($link, $link->pin, $recipient, static::urlFor($link)));
+                $to = static::maskEmail($recipient->email);
+            }
+        } catch (\Throwable $e) {
+            report($e);
+
+            return ['sent' => false, 'via' => $via, 'to' => null, 'error' => 'The PIN could not be sent: ' . $e->getMessage()];
+        }
+
+        $link->forceFill(['pin_sent_via' => $via, 'pin_sent_at' => now()])->save();
+
+        return ['sent' => true, 'via' => $via, 'to' => $to, 'error' => null];
+    }
+
+    /**
+     * The link as the recipient opens it, on the console's own host. Null for a
+     * link minted before tokens were kept, whose URL cannot be rebuilt.
+     */
+    public static function urlFor(InspectionLink $link): ?string
+    {
+        $path = $link->path;
+
+        return $path ? Utils::consoleUrl($path) : null;
+    }
+
+    /** Naming the organisation so it is recognised, and short enough to read at a glance. */
+    public static function smsText(InspectionLink $link, string $pin, ?string $url = null): string
+    {
+        $company = Company::select(['uuid', 'name'])->find($link->company_uuid)?->name ?? config('app.name');
+        $form    = $link->form?->name ?? 'inspection';
+
+        if ($url) {
+            return "{$company}: complete the {$form} inspection at {$url} using PIN {$pin}. Do not share this PIN.";
+        }
+
+        return "{$company}: your PIN for the {$form} inspection is {$pin}. Do not share this PIN.";
+    }
+
+    /**
+     * The organisation's alphanumeric sender ID, when it has one, the same way
+     * the platform's own verification texts use it: as a Twilio-only option,
+     * so other providers are not handed a sender they would reject.
+     */
+    protected static function smsOptions(InspectionLink $link): array
+    {
+        $company = Company::select(['uuid', 'options'])->find($link->company_uuid);
+
+        if (!$company) {
+            return [];
+        }
+
+        $enabled  = Utils::castBoolean($company->getOption('alpha_numeric_sender_id_enabled'));
+        $senderId = $company->getOption('alpha_numeric_sender_id');
+
+        return $enabled && $senderId ? ['twilioParams' => ['from' => $senderId]] : [];
+    }
+
+    /** "r•••@fleetbase.io": enough to recognise, not enough to copy. */
+    public static function maskEmail(string $email): string
+    {
+        [$local, $domain] = array_pad(explode('@', $email, 2), 2, '');
+
+        return mb_substr($local, 0, 1) . '•••@' . $domain;
+    }
+
+    /** "•••1969": the last four digits. */
+    public static function maskPhone(string $phone): string
+    {
+        return '•••' . substr(preg_replace('/\D/', '', $phone), -4);
+    }
+}

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,
+        ];
+    }
+}