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/DisplayService.php

@@ -34,25 +34,35 @@ class DisplayService
             ->orderBy('name')
             ->get();
 
-        // One active ticket per destination (counter). Older called/serving
+        // One active ticket per destination (service point / counter). Older called/serving
         // tickets at the same window must not crowd the public board.
         $nowServing = Ticket::query()
             ->whereIn('service_queue_id', $queueIds)
             ->whereIn('status', ['called', 'serving'])
-            ->with(['counter', 'serviceQueue'])
+            ->with(['counter', 'assignedCounter', 'serviceQueue'])
             ->orderByDesc('called_at')
             ->limit(48)
             ->get()
             ->unique(fn (Ticket $t) => $t->counter_id
                 ? 'counter:'.$t->counter_id
-                : 'queue:'.$t->service_queue_id)
+                : ($t->assigned_counter_id
+                    ? 'assigned:'.$t->assigned_counter_id
+                    : 'queue:'.$t->service_queue_id))
             ->take(12)
             ->values()
-            ->map(fn (Ticket $t) => [
-                'ticket_number' => $t->ticket_number,
-                'queue_name' => $t->serviceQueue?->name,
-                'counter' => $t->counter?->name,
-            ])
+            ->map(function (Ticket $t) {
+                $point = $t->counter ?? $t->assignedCounter;
+
+                return [
+                    'ticket_number' => $t->ticket_number,
+                    'queue_name' => $t->serviceQueue?->name,
+                    'department' => $t->serviceQueue?->name,
+                    'counter' => $point?->displayDestination() ?? $point?->name,
+                    'destination' => $point?->displayDestination(),
+                    'staff_display_name' => $point?->staff_display_name,
+                    'announcement_text' => TicketPresenter::announcementText($t, $point),
+                ];
+            })
             ->all();
 
         $waiting = Ticket::query()

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

app/Services/Qms/TicketPresenter.php

@@ -11,6 +11,12 @@ class TicketPresenter
      */
     public static function toArray(Ticket $ticket, bool $includeQr = true): array
     {
+        $ticket->loadMissing(['serviceQueue', 'counter', 'assignedCounter']);
+
+        $serving = $ticket->counter;
+        $assigned = $ticket->assignedCounter;
+        $point = $serving ?? $assigned;
+
         return [
             'uuid' => $ticket->uuid,
             'ticket_number' => $ticket->ticket_number,
@@ -28,13 +34,46 @@ class TicketPresenter
                 'name' => $ticket->serviceQueue->name,
                 'prefix' => $ticket->serviceQueue->prefix,
                 'color' => $ticket->serviceQueue->color,
+                'routing_mode' => $ticket->serviceQueue->routingMode(),
             ] : null,
-            'counter' => $ticket->counter ? [
-                'uuid' => $ticket->counter->uuid,
-                'name' => $ticket->counter->name,
-            ] : null,
+            'counter' => $serving ? self::serializePoint($serving) : null,
+            'assigned_counter' => $assigned ? self::serializePoint($assigned) : null,
+            'destination' => $point?->displayDestination(),
+            'staff_display_name' => $point?->staff_display_name,
+            'announcement_text' => self::announcementText($ticket, $point),
             'track_url' => $includeQr ? route('qms.mobile.show', $ticket->qr_token) : null,
             'barcode' => $ticket->barcode,
         ];
     }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public static function serializePoint(\App\Models\Counter $counter): array
+    {
+        return [
+            'uuid' => $counter->uuid,
+            'name' => $counter->name,
+            'destination' => $counter->displayDestination(),
+            'staff_ref' => $counter->staff_ref,
+            'staff_display_name' => $counter->staff_display_name,
+            'code' => $counter->code,
+        ];
+    }
+
+    public static function announcementText(Ticket $ticket, ?\App\Models\Counter $point): ?string
+    {
+        if (! $point) {
+            return $ticket->ticket_number;
+        }
+
+        $parts = array_values(array_filter([
+            $ticket->ticket_number,
+            $point->staff_display_name ?: null,
+            $ticket->serviceQueue?->name,
+            $point->displayDestination(),
+        ]));
+
+        return implode(', ', $parts);
+    }
 }

app/Services/Qms/VoiceAnnouncementService.php

@@ -31,10 +31,25 @@ class VoiceAnnouncementService
     {
         $templates = config('qms.announcement_templates');
         $template = $templates[$locale] ?? $templates['en'];
+        $destination = $counter->displayDestination();
+        $staff = trim((string) ($counter->staff_display_name ?? ''));
+        $queueName = trim((string) ($ticket->serviceQueue?->name ?? ''));
+
+        // Prefer rich healthcare-style copy when staff is known:
+        // "A005, Dr. Mensah, Consultation Room 4."
+        if ($staff !== '') {
+            $parts = array_values(array_filter([
+                $ticket->ticket_number,
+                $staff,
+                $queueName !== '' ? $queueName.' '.$destination : $destination,
+            ]));
+
+            return implode(', ', $parts).'.';
+        }
 
         return str_replace(
             [':ticket', ':counter'],
-            [$ticket->ticket_number, $counter->name],
+            [$ticket->ticket_number, $destination],
             $template,
         );
     }