Add clinical device registry, browser wedge scan, and local agent API.

Branch-scoped Care devices with hashed agent tokens, patient barcode lookup/labels, and provenance-aware vitals from a minimal device agent (Pro for agent hardware; wedge free).

Co-authored-by: Cursor <cursoragent@cursor.com>

app/Services/Care/CarePermissions.php

@@ -51,6 +51,7 @@ class CarePermissions
         'admin.practitioners.view', 'admin.practitioners.manage',
         'admin.members.view', 'admin.members.manage',
         'settings.view', 'settings.manage',
+        'devices.view', 'devices.manage',
         'audit.view', 'audit.export',
     ];
 

app/Services/Care/ConsultationService.php

@@ -97,14 +97,25 @@ class ConsultationService
 
     /**
      * @param  array<string, mixed>  $vitals
+     * @param  array{source?: string, device_id?: int|null, raw_payload?: array<string, mixed>|null}  $provenance
      */
-    protected function saveVitals(Consultation $consultation, string $ownerRef, array $vitals, ?string $actorRef): void
-    {
-        if (empty(array_filter($vitals))) {
-            return;
+    public function saveVitals(
+        Consultation $consultation,
+        string $ownerRef,
+        array $vitals,
+        ?string $actorRef = null,
+        array $provenance = [],
+    ): ?VitalSign {
+        $numeric = collect($vitals)->only([
+            'bp_systolic', 'bp_diastolic', 'pulse', 'temperature',
+            'weight_kg', 'height_cm', 'spo2', 'respiratory_rate',
+        ])->filter(fn ($v) => $v !== null && $v !== '')->all();
+
+        if ($numeric === []) {
+            return null;
         }
 
-        VitalSign::create([
+        return VitalSign::create([
             'owner_ref' => $ownerRef,
             'consultation_id' => $consultation->id,
             'bp_systolic' => $vitals['bp_systolic'] ?? null,
@@ -117,6 +128,9 @@ class ConsultationService
             'respiratory_rate' => $vitals['respiratory_rate'] ?? null,
             'recorded_by' => $actorRef,
             'recorded_at' => now(),
+            'source' => $provenance['source'] ?? VitalSign::SOURCE_MANUAL,
+            'device_id' => $provenance['device_id'] ?? null,
+            'raw_payload' => $provenance['raw_payload'] ?? null,
         ]);
     }
 

app/Services/Care/DemoTenantSeeder.php

@@ -13,6 +13,7 @@ use App\Models\BillLineItem;
 use App\Models\Branch;
 use App\Models\Consultation;
 use App\Models\Department;
+use App\Models\Device;
 use App\Models\Drug;
 use App\Models\DrugBatch;
 use App\Models\InvestigationRequest;
@@ -122,6 +123,7 @@ class DemoTenantSeeder
                     $ownerRef,
                     $volumes,
                 );
+                $this->seedDevices($organization, $branches, $ownerRef);
             }
 
             if ($volumes['assessments'] > 0) {
@@ -196,6 +198,8 @@ class DemoTenantSeeder
         DB::table('care_vital_signs')->where('owner_ref', $ownerRef)->delete();
         DB::table('care_consultations')->where('owner_ref', $ownerRef)->delete();
 
+        DB::table('care_devices')->where('owner_ref', $ownerRef)->delete();
+
         DB::table('care_appointments')->where('owner_ref', $ownerRef)->delete();
         DB::table('care_visits')->where('owner_ref', $ownerRef)->delete();
 
@@ -678,6 +682,57 @@ class DemoTenantSeeder
      * @param  list<Patient>  $patients
      * @param  array<string, mixed>  $volumes
      */
+    /**
+     * Demo hardware inventory: browser wedge scanner + agent thermometer per branch (Pro+).
+     *
+     * @param  list<Branch>  $branches
+     */
+    private function seedDevices(Organization $organization, array $branches, string $ownerRef): void
+    {
+        $deviceService = app(DeviceService::class);
+
+        foreach ($branches as $i => $branch) {
+            Device::withTrashed()->updateOrCreate(
+                [
+                    'organization_id' => $organization->id,
+                    'branch_id' => $branch->id,
+                    'name' => 'Demo barcode scanner',
+                ],
+                [
+                    'owner_ref' => $ownerRef,
+                    'type' => 'barcode_scanner',
+                    'connection_mode' => Device::MODE_BROWSER_WEDGE,
+                    'status' => Device::STATUS_OFFLINE,
+                    'device_token_hash' => null,
+                    'metadata' => ['demo' => true],
+                    'deleted_at' => null,
+                ],
+            );
+
+            $thermo = Device::withTrashed()->updateOrCreate(
+                [
+                    'organization_id' => $organization->id,
+                    'branch_id' => $branch->id,
+                    'name' => 'Demo thermometer',
+                ],
+                [
+                    'owner_ref' => $ownerRef,
+                    'type' => 'thermometer',
+                    'connection_mode' => Device::MODE_AGENT,
+                    'status' => Device::STATUS_OFFLINE,
+                    'metadata' => ['demo' => true, 'note' => 'Token issued on first seed only if missing'],
+                    'deleted_at' => null,
+                ],
+            );
+
+            if (! $thermo->device_token_hash) {
+                // Deterministic demo token so sales can reuse docs examples after reseed.
+                $plain = 'demo-care-device-'.$organization->id.'-'.$branch->id.'-thermo';
+                $thermo->update(['device_token_hash' => $deviceService->hashToken($plain)]);
+            }
+        }
+    }
+
     private function seedPaidModules(
         Organization $organization,
         array $branches,

app/Services/Care/DeviceService.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Services\Care;
+
+use App\Models\Device;
+use App\Models\Organization;
+use Illuminate\Support\Str;
+
+class DeviceService
+{
+    public function generateToken(): string
+    {
+        return Str::random(48);
+    }
+
+    public function hashToken(string $token): string
+    {
+        return hash('sha256', $token);
+    }
+
+    public function findByToken(string $token): ?Device
+    {
+        if ($token === '') {
+            return null;
+        }
+
+        return Device::query()
+            ->where('device_token_hash', $this->hashToken($token))
+            ->where('status', '!=', Device::STATUS_DISABLED)
+            ->first();
+    }
+
+    public function issueToken(Device $device): string
+    {
+        $plain = $this->generateToken();
+        $device->update(['device_token_hash' => $this->hashToken($plain)]);
+
+        return $plain;
+    }
+
+    public function revokeToken(Device $device): Device
+    {
+        $device->update(['device_token_hash' => null]);
+
+        return $device->fresh();
+    }
+
+    public function recordHeartbeat(Device $device, ?array $metadata = null): Device
+    {
+        $payload = [
+            'status' => Device::STATUS_ACTIVE,
+            'last_seen_at' => now(),
+        ];
+
+        if ($metadata !== null) {
+            $payload['metadata'] = array_merge($device->metadata ?? [], [
+                'agent' => $metadata,
+            ]);
+        }
+
+        $device->update($payload);
+
+        return $device->fresh();
+    }
+
+    public function defaultConnectionMode(string $type): string
+    {
+        return match ($type) {
+            'barcode_scanner', 'qr_scanner' => Device::MODE_BROWSER_WEDGE,
+            'badge_printer' => Device::MODE_MANUAL,
+            'thermometer', 'bp_monitor', 'pulse_ox', 'weight_scale', 'lab_analyzer', 'agent' => Device::MODE_AGENT,
+            default => Device::MODE_MANUAL,
+        };
+    }
+
+    public function typeRequiresPro(string $type): bool
+    {
+        return in_array($type, config('care.device_agent_types', []), true);
+    }
+
+    public function canRegisterType(Organization $organization, string $type, PlanService $plans): bool
+    {
+        if (! $this->typeRequiresPro($type)) {
+            return true;
+        }
+
+        return $plans->hasPaidPlan($organization);
+    }
+
+    public function connectionHint(string $type, string $mode): string
+    {
+        return match ($mode) {
+            Device::MODE_BROWSER_WEDGE => 'Works in the browser today as a USB keyboard wedge (scan into the focused field). No local agent required.',
+            Device::MODE_AGENT => 'Needs the Care Device Agent on a local machine (serial / BLE / vendor SDK). Browser alone cannot talk to this hardware.',
+            Device::MODE_WEB_BLUETOOTH => 'Experimental Web Bluetooth path — not broadly supported; prefer the local agent for clinical devices.',
+            default => 'Manual / inventory only — no automated capture path configured.',
+        };
+    }
+}

app/Services/Care/PatientService.php

@@ -72,6 +72,40 @@ class PatientService
         return $query->paginate((int) ($filters['per_page'] ?? 20))->withQueryString();
     }
 
+    /**
+     * Exact patient_number match first, then fall back to broad search (first hit).
+     */
+    public function findByScanCode(string $ownerRef, int $organizationId, string $code, ?int $branchId = null): ?Patient
+    {
+        $code = trim($code);
+        if ($code === '') {
+            return null;
+        }
+
+        $base = $this->queryForOrganization($ownerRef, $organizationId)
+            ->when($branchId !== null, fn ($q) => $q->where('branch_id', $branchId));
+
+        $exact = (clone $base)->where('patient_number', $code)->first();
+        if ($exact) {
+            return $exact;
+        }
+
+        // Case-insensitive exact patient number.
+        $ci = (clone $base)->whereRaw('lower(patient_number) = ?', [strtolower($code)])->first();
+        if ($ci) {
+            return $ci;
+        }
+
+        return (clone $base)
+            ->where(function (Builder $inner) use ($code) {
+                $inner->where('patient_number', 'like', "%{$code}%")
+                    ->orWhere('national_id', $code)
+                    ->orWhere('phone', 'like', "%{$code}%");
+            })
+            ->orderByDesc('created_at')
+            ->first();
+    }
+
     /**
      * @param  array<string, mixed>  $data
      */