Fix queue handoff so tickets keep their number across services.

Handoff now frees the counter, ends the service session, and requeues
the same ticket for the next department — critical for hospital flows
like doctor → lab.

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

app/Http/Controllers/Api/ConsoleApiController.php

@@ -87,7 +87,7 @@ class ConsoleApiController extends Controller
             'call_next' => $this->handleCallNext($counter, $validated['queue_uuid'] ?? '', $actor),
             'available' => tap($counter)->update(['status' => 'available']),
             'offline' => tap($counter)->update(['status' => 'offline']),
-            default => $this->handleTicketAction($validated, $actor),
+            default => $this->handleTicketAction($validated, $counter, $actor),
         };
 
         if ($result instanceof Ticket) {
@@ -105,7 +105,7 @@ class ConsoleApiController extends Controller
         return $this->engine->callNext($queue, $counter, $actor);
     }
 
-    protected function handleTicketAction(array $validated, string $actor): Ticket|Counter|null
+    protected function handleTicketAction(array $validated, Counter $counter, string $actor): Ticket|Counter|null
     {
         $ticketUuid = $validated['ticket_uuid'] ?? '';
         abort_if($ticketUuid === '', 422, 'ticket_uuid is required for this action.');
@@ -119,14 +119,28 @@ class ConsoleApiController extends Controller
             'skip' => $this->engine->skip($ticket, $actor),
             'complete' => $this->engine->completeTicket($ticket, $actor),
             'no_show' => $this->engine->markNoShow($ticket, $actor),
-            'transfer' => $this->engine->transfer(
+            'transfer' => $this->handleTransfer(
                 $ticket,
-                ServiceQueue::where('uuid', $validated['to_queue_uuid'] ?? '')->firstOrFail(),
-                null,
+                $counter,
+                $validated['to_queue_uuid'] ?? '',
                 $validated['reason'] ?? null,
                 $actor,
             ),
             default => abort(422, 'Unknown action.'),
         };
     }
+
+    protected function handleTransfer(
+        Ticket $ticket,
+        Counter $counter,
+        string $toQueueUuid,
+        ?string $reason,
+        string $actor,
+    ): Ticket {
+        abort_if($toQueueUuid === '', 422, 'to_queue_uuid is required for transfer.');
+
+        $toQueue = ServiceQueue::where('uuid', $toQueueUuid)->firstOrFail();
+
+        return $this->engine->transfer($ticket, $toQueue, $counter, $reason, $actor);
+    }
 }

app/Http/Controllers/Api/TicketController.php

@@ -101,12 +101,20 @@ class TicketController extends Controller
         $actor = $this->ownerRef($request);
 
         $validated = $request->validate([
-            'action' => ['required', 'string', 'in:recall,start,hold,skip,complete,no_show,cancel,delay'],
+            'action' => ['required', 'string', 'in:recall,start,hold,skip,complete,no_show,cancel,delay,transfer'],
             'minutes' => ['nullable', 'integer', 'min:5', 'max:120'],
-            'to_queue_id' => ['nullable', 'uuid'],
+            'to_queue_id' => ['required_if:action,transfer', 'nullable', 'uuid'],
             'reason' => ['nullable', 'string', 'max:500'],
         ]);
 
+        if ($validated['action'] === 'transfer') {
+            $toQueue = ServiceQueue::where('uuid', $validated['to_queue_id'])->firstOrFail();
+            $this->authorizeOwner($request, $toQueue);
+            $result = $this->engine->transfer($ticket, $toQueue, null, $validated['reason'] ?? null, $actor);
+
+            return response()->json(['data' => TicketPresenter::toArray($result->load(['serviceQueue', 'counter']))]);
+        }
+
         $result = match ($validated['action']) {
             'recall' => $this->engine->recall($ticket, $actor),
             'start' => $this->engine->startServing($ticket, $actor),
@@ -119,11 +127,6 @@ class TicketController extends Controller
             default => $ticket,
         };
 
-        if ($validated['action'] === 'transfer' && ! empty($validated['to_queue_id'])) {
-            $toQueue = ServiceQueue::where('uuid', $validated['to_queue_id'])->firstOrFail();
-            $result = $this->engine->transfer($ticket, $toQueue, null, $validated['reason'] ?? null, $actor);
-        }
-
         return response()->json(['data' => TicketPresenter::toArray($result->load(['serviceQueue', 'counter']))]);
     }
 }

app/Http/Controllers/Qms/ConsoleController.php

@@ -61,37 +61,45 @@ class ConsoleController extends Controller
             'action' => ['required', 'string'],
             'queue_id' => ['nullable', 'integer'],
             'ticket_id' => ['nullable', 'integer'],
-            'to_queue_id' => ['nullable', 'integer'],
+            'to_queue_id' => ['required_if:action,transfer', 'nullable', 'integer'],
             'reason' => ['nullable', 'string', 'max:500'],
         ]);
 
-        match ($validated['action']) {
-            'call_next' => $this->handleCallNext($counter, (int) $validated['queue_id'], $actor),
-            'recall' => $this->handleTicketAction($validated['ticket_id'], 'recall', $actor),
-            'start' => $this->handleTicketAction($validated['ticket_id'], 'start', $actor),
-            'hold' => $this->handleTicketAction($validated['ticket_id'], 'hold', $actor),
-            'skip' => $this->handleTicketAction($validated['ticket_id'], 'skip', $actor),
-            'complete' => $this->handleTicketAction($validated['ticket_id'], 'complete', $actor),
-            'no_show' => $this->handleTicketAction($validated['ticket_id'], 'no_show', $actor),
-            'transfer' => $this->handleTransfer($validated['ticket_id'], (int) $validated['to_queue_id'], $counter, $validated['reason'] ?? null, $actor),
-            'available' => $counter->update(['status' => 'available']),
-            'offline' => $counter->update(['status' => 'offline']),
-            default => null,
-        };
+        try {
+            $message = match ($validated['action']) {
+                'call_next' => $this->handleCallNext($counter, (int) $validated['queue_id'], $actor),
+                'recall' => $this->handleTicketAction($validated['ticket_id'], 'recall', $actor),
+                'start' => $this->handleTicketAction($validated['ticket_id'], 'start', $actor),
+                'hold' => $this->handleTicketAction($validated['ticket_id'], 'hold', $actor),
+                'skip' => $this->handleTicketAction($validated['ticket_id'], 'skip', $actor),
+                'complete' => $this->handleTicketAction($validated['ticket_id'], 'complete', $actor),
+                'no_show' => $this->handleTicketAction($validated['ticket_id'], 'no_show', $actor),
+                'transfer' => $this->handleTransfer($validated['ticket_id'], (int) $validated['to_queue_id'], $counter, $validated['reason'] ?? null, $actor),
+                'available' => tap(null, fn () => $counter->update(['status' => 'available'])),
+                'offline' => tap(null, fn () => $counter->update(['status' => 'offline'])),
+                default => null,
+            };
+        } catch (\RuntimeException $e) {
+            return back()->with('error', $e->getMessage());
+        }
 
-        return back();
+        return $message
+            ? back()->with('success', $message)
+            : back();
     }
 
-    protected function handleCallNext(Counter $counter, int $queueId, string $actor): void
+    protected function handleCallNext(Counter $counter, int $queueId, string $actor): ?string
     {
         $queue = ServiceQueue::findOrFail($queueId);
-        $this->engine->callNext($queue, $counter, $actor);
+        $ticket = $this->engine->callNext($queue, $counter, $actor);
+
+        return $ticket ? "Called {$ticket->ticket_number}." : 'No tickets waiting in that queue.';
     }
 
-    protected function handleTicketAction(?int $ticketId, string $action, string $actor): void
+    protected function handleTicketAction(?int $ticketId, string $action, string $actor): ?string
     {
         if (! $ticketId) {
-            return;
+            return null;
         }
         $ticket = Ticket::findOrFail($ticketId);
         match ($action) {
@@ -103,15 +111,28 @@ class ConsoleController extends Controller
             'no_show' => $this->engine->markNoShow($ticket, $actor),
             default => null,
         };
+
+        return null;
     }
 
-    protected function handleTransfer(?int $ticketId, int $toQueueId, Counter $counter, ?string $reason, string $actor): void
+    protected function handleTransfer(?int $ticketId, int $toQueueId, Counter $counter, ?string $reason, string $actor): ?string
     {
         if (! $ticketId || ! $toQueueId) {
-            return;
+            return null;
         }
         $ticket = Ticket::findOrFail($ticketId);
         $toQueue = ServiceQueue::findOrFail($toQueueId);
+
+        if (
+            $toQueue->organization_id !== $counter->organization_id
+            || $toQueue->branch_id !== $counter->branch_id
+            || $toQueue->owner_ref !== $counter->owner_ref
+        ) {
+            throw new \RuntimeException('You can only hand off to queues at this branch.');
+        }
+
         $this->engine->transfer($ticket, $toQueue, $counter, $reason, $actor);
+
+        return "Handed off {$ticket->ticket_number} to {$toQueue->name}. Ticket number unchanged.";
     }
 }

app/Http/Controllers/Qms/TicketController.php

@@ -92,7 +92,13 @@ class TicketController extends Controller
         $this->authorizeAbility($request, 'tickets.view');
         $this->authorizeOwner($request, $ticket);
 
-        $ticket->load(['serviceQueue', 'counter', 'events']);
+        $ticket->load([
+            'serviceQueue',
+            'counter',
+            'events',
+            'transfers.fromQueue',
+            'transfers.toQueue',
+        ]);
 
         return view('qms.tickets.show', [
             'ticket' => $ticket,