Add service-point routing so call-next cannot steal assigned tickets.

Counters gain destination/staff metadata; tickets can be pre-assigned to a
service point with assigned_only queues for healthcare while shared_pool
preserves generic bank/government behavior. Display and announcements expose
ticket, staff, and destination clearly for Care and public boards.

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

app/Services/Qms/QueueEngine.php

@@ -56,11 +56,14 @@ class QueueEngine
                 ->count();
             $estimatedWait = $waitingCount * (int) $queue->avg_service_seconds;
 
+            $assignedCounterId = $this->resolveAssignedCounterId($queue, $attributes);
+
             $ticket = Ticket::create([
                 'owner_ref' => $ownerRef,
                 'organization_id' => $queue->organization_id,
                 'branch_id' => $queue->branch_id,
                 'service_queue_id' => $queue->id,
+                'assigned_counter_id' => $assignedCounterId,
                 'ticket_number' => $number,
                 'status' => 'waiting',
                 'priority' => $attributes['priority'] ?? 'walk_in',
@@ -75,7 +78,9 @@ class QueueEngine
                 'metadata' => $attributes['metadata'] ?? null,
             ]);
 
-            $this->recordEvent($ticket, 'issued', $attributes['actor_ref'] ?? null);
+            $this->recordEvent($ticket, 'issued', $attributes['actor_ref'] ?? null, null, [
+                'assigned_counter_id' => $assignedCounterId,
+            ]);
 
             AuditLogger::record(
                 $ownerRef,
@@ -87,7 +92,7 @@ class QueueEngine
                 ['ticket_number' => $number, 'queue' => $queue->name],
             );
 
-            $ticket = $ticket->fresh(['serviceQueue', 'branch']);
+            $ticket = $ticket->fresh(['serviceQueue', 'branch', 'assignedCounter']);
             app(QueueNotificationService::class)->ticketIssued($ticket);
 
             return $ticket;
@@ -96,7 +101,7 @@ class QueueEngine
 
     public function callNext(ServiceQueue $queue, Counter $counter, ?string $actorRef = null): ?Ticket
     {
-        $ticket = $this->nextWaitingTicket($queue);
+        $ticket = $this->nextWaitingTicket($queue, $counter);
         if (! $ticket) {
             return null;
         }
@@ -106,9 +111,14 @@ class QueueEngine
 
     public function callTicket(Ticket $ticket, Counter $counter, ?string $actorRef = null): Ticket
     {
+        if ($ticket->assigned_counter_id && (int) $ticket->assigned_counter_id !== (int) $counter->id) {
+            throw new \RuntimeException('Ticket is assigned to another service point.');
+        }
+
         $ticket->update([
             'status' => 'called',
             'counter_id' => $counter->id,
+            'assigned_counter_id' => $ticket->assigned_counter_id ?: $counter->id,
             'called_at' => now(),
         ]);
 
@@ -229,8 +239,9 @@ class QueueEngine
         ?Counter $counter = null,
         ?string $reason = null,
         ?string $actorRef = null,
+        ?Counter $assignToCounter = null,
     ): Ticket {
-        return DB::transaction(function () use ($ticket, $toQueue, $counter, $reason, $actorRef) {
+        return DB::transaction(function () use ($ticket, $toQueue, $counter, $reason, $actorRef, $assignToCounter) {
             $ticket = Ticket::query()->lockForUpdate()->findOrFail($ticket->id);
             $toQueue = ServiceQueue::query()->lockForUpdate()->findOrFail($toQueue->id);
 
@@ -256,6 +267,16 @@ class QueueEngine
                 }
             }
 
+            $assignedCounterId = null;
+            if ($assignToCounter) {
+                if ((int) $assignToCounter->organization_id !== (int) $toQueue->organization_id) {
+                    throw new \RuntimeException('Assigned service point is outside this organization.');
+                }
+                $assignedCounterId = $assignToCounter->id;
+            } elseif ($toQueue->usesAssignedOnlyRouting()) {
+                throw new \RuntimeException('Target queue requires an assigned service point.');
+            }
+
             $fromQueueId = $ticket->service_queue_id;
             $fromCounterId = $counter?->id ?? $ticket->counter_id;
             $ticketNumber = $ticket->ticket_number;
@@ -274,6 +295,7 @@ class QueueEngine
                 'position' => $waitingCount + 1,
                 'estimated_wait_seconds' => $estimatedWait,
                 'counter_id' => null,
+                'assigned_counter_id' => $assignedCounterId,
                 'called_at' => null,
                 'serving_started_at' => null,
                 'completed_at' => null,
@@ -355,26 +377,77 @@ class QueueEngine
     /**
      * @return list<Ticket>
      */
-    public function waitingTickets(ServiceQueue $queue, int $limit = 50): array
+    public function waitingTickets(ServiceQueue $queue, int $limit = 50, ?Counter $forCounter = null): array
     {
-        return Ticket::query()
-            ->where('service_queue_id', $queue->id)
-            ->where('status', 'waiting')
-            ->orderByRaw($this->priorityOrderSql())
-            ->orderBy('issued_at')
+        return $this->waitingTicketQuery($queue, $forCounter)
             ->limit($limit)
             ->get()
             ->all();
     }
 
-    protected function nextWaitingTicket(ServiceQueue $queue): ?Ticket
+    protected function nextWaitingTicket(ServiceQueue $queue, ?Counter $counter = null): ?Ticket
     {
-        return Ticket::query()
+        return $this->waitingTicketQuery($queue, $counter)->first();
+    }
+
+    /**
+     * Tickets visible/callable for a service point:
+     * - assigned_only: only tickets assigned to this counter
+     * - shared_pool: unassigned tickets, or tickets assigned to this counter
+     * - no counter: all waiting (admin/list views)
+     */
+    protected function waitingTicketQuery(ServiceQueue $queue, ?Counter $counter = null)
+    {
+        $query = Ticket::query()
             ->where('service_queue_id', $queue->id)
             ->where('status', 'waiting')
             ->orderByRaw($this->priorityOrderSql())
-            ->orderBy('issued_at')
-            ->first();
+            ->orderBy('issued_at');
+
+        if (! $counter) {
+            return $query;
+        }
+
+        if ($queue->usesAssignedOnlyRouting()) {
+            return $query->where('assigned_counter_id', $counter->id);
+        }
+
+        return $query->where(function ($q) use ($counter) {
+            $q->whereNull('assigned_counter_id')
+                ->orWhere('assigned_counter_id', $counter->id);
+        });
+    }
+
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    protected function resolveAssignedCounterId(ServiceQueue $queue, array $attributes): ?int
+    {
+        $counter = null;
+
+        if (! empty($attributes['assigned_counter_id'])) {
+            $value = $attributes['assigned_counter_id'];
+            $counter = is_numeric($value)
+                ? Counter::query()->find((int) $value)
+                : Counter::query()->where('uuid', (string) $value)->first();
+        } elseif (! empty($attributes['assigned_counter_uuid'])) {
+            $counter = Counter::query()->where('uuid', (string) $attributes['assigned_counter_uuid'])->first();
+        }
+
+        if (! $counter) {
+            if ($queue->usesAssignedOnlyRouting()) {
+                throw new \RuntimeException('This queue requires an assigned service point.');
+            }
+
+            return null;
+        }
+
+        if ((int) $counter->organization_id !== (int) $queue->organization_id
+            || (string) $counter->owner_ref !== (string) $queue->owner_ref) {
+            throw new \RuntimeException('Assigned service point is outside this organization.');
+        }
+
+        return (int) $counter->id;
     }
 
     protected function priorityOrderSql(): string