Issue cashier booth tickets when financial gates block service.

Pay-before-service holds now create a billing queue ticket (via an open bill) so cashiers can Call next / Serve; clearance completes the ticket and releases the clinical line as before.

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

app/Services/Care/Workflow/WorkflowQueueReleaseService.php

@@ -4,16 +4,21 @@ namespace App\Services\Care\Workflow;
 
 use App\Models\Appointment;
 use App\Models\Bill;
+use App\Models\FinancialObligation;
 use App\Models\InvestigationRequest;
 use App\Models\Organization;
 use App\Models\Prescription;
 use App\Models\Visit;
+use App\Models\WorkflowStage;
+use App\Services\Care\BillService;
 use App\Services\Care\CareQueueBridge;
 use App\Services\Care\CareQueueContexts;
+use Illuminate\Support\Facades\Log;
 
 /**
  * Releases the entity represented by the visit's current workflow stage to
- * Ladill Queue after stage entry or financial clearance.
+ * Ladill Queue after stage entry or financial clearance. Also owns the cashier
+ * booth queue for pay-before-service financial gates.
  */
 class WorkflowQueueReleaseService
 {
@@ -24,8 +29,24 @@ class WorkflowQueueReleaseService
 
     public function releaseCurrent(Organization $organization, Visit $visit): void
     {
-        $stage = $this->engine->currentStage($visit);
-        if ($stage === null || $stage->queue_context === null) {
+        $advance = $this->engine->currentAdvance($visit);
+        $stage = $advance?->stage;
+        if ($stage === null) {
+            return;
+        }
+
+        // Hold at the cashier booth while a before-service gate is unpaid.
+        if ($advance->isBlocked() && $advance->blocked_reason === 'awaiting_payment') {
+            $this->enqueueCashier($organization, $visit, $stage);
+
+            return;
+        }
+
+        if ($stage->queue_context === null) {
+            if ($stage->type === 'payment') {
+                $this->enqueueCashier($organization, $visit, $stage);
+            }
+
             return;
         }
 
@@ -93,11 +114,112 @@ class WorkflowQueueReleaseService
         }
 
         if ($context === CareQueueContexts::BILLING) {
-            Bill::query()
-                ->where('visit_id', $visit->id)
-                ->whereNotIn('status', [Bill::STATUS_PAID, Bill::STATUS_VOID])
-                ->get()
-                ->each(fn (Bill $bill) => $this->queue->issueForBill($organization, $bill));
+            $this->enqueueCashier($organization, $visit, $stage);
+        }
+    }
+
+    /**
+     * Ensure a visit blocked on payment has an open bill and an active cashier
+     * booth ticket. No-ops when Care Queue Engine is disabled.
+     */
+    public function enqueueCashier(
+        Organization $organization,
+        Visit $visit,
+        ?WorkflowStage $stage = null,
+    ): ?Bill {
+        if (! $this->queue->isEnabled($organization)) {
+            return null;
+        }
+
+        $stage ??= $this->engine->currentStage($visit);
+        if ($stage === null) {
+            return null;
+        }
+
+        $obligation = FinancialObligation::query()
+            ->where('visit_id', $visit->id)
+            ->where('workflow_stage_id', $stage->id)
+            ->whereNull('deleted_at')
+            ->first();
+
+        if ($obligation === null
+            || $obligation->isCleared()
+            || (int) $obligation->amount_minor <= 0) {
+            return null;
+        }
+
+        try {
+            $bill = app(BillService::class)->billForObligation(
+                $obligation,
+                (string) $visit->owner_ref,
+                (string) $visit->owner_ref,
+            );
+
+            return $this->queue->issueForBill($organization, $bill->fresh(['patient', 'visit']));
+        } catch (\Throwable $e) {
+            Log::warning('care.cashier_queue_enqueue_failed', [
+                'visit_id' => $visit->id,
+                'stage_code' => $stage->code,
+                'message' => $e->getMessage(),
+            ]);
+
+            return null;
+        }
+    }
+
+    /**
+     * Complete (or retire) the cashier booth ticket after a financial gate clears.
+     * Non-payment clearances void unpaid obligation-only placeholder bills.
+     */
+    public function completeCashier(
+        Organization $organization,
+        FinancialObligation $obligation,
+        string $clearanceMethod,
+    ): void {
+        if (! $this->queue->isEnabled($organization)) {
+            return;
+        }
+
+        $obligation->loadMissing('bill');
+        $bill = $obligation->bill;
+        if ($bill === null) {
+            return;
+        }
+
+        if (filled($bill->queue_ticket_uuid)
+            && ! in_array($bill->queue_ticket_status, ['completed', 'cancelled'], true)) {
+            $this->queue->complete($organization, $bill);
+            $bill = $bill->fresh();
+        }
+
+        if (in_array($clearanceMethod, ['payment', 'bank_receipt'], true)) {
+            return;
+        }
+
+        $bill = $bill->fresh(['lineItems']) ?? $bill;
+        if ((int) $bill->amount_paid_minor > 0
+            || in_array($bill->status, [Bill::STATUS_PAID, Bill::STATUS_VOID], true)) {
+            return;
+        }
+
+        $hasForeignLines = $bill->lineItems
+            ->contains(function ($item) use ($obligation) {
+                return $item->source_type !== FinancialObligation::class
+                    || (int) $item->source_id !== (int) $obligation->id;
+            });
+
+        if ($hasForeignLines) {
+            return;
+        }
+
+        try {
+            app(BillService::class)->void($bill, (string) $obligation->owner_ref, $obligation->cleared_by);
+        } catch (\Throwable $e) {
+            Log::warning('care.cashier_placeholder_bill_void_failed', [
+                'bill_id' => $bill->id,
+                'obligation_id' => $obligation->id,
+                'message' => $e->getMessage(),
+            ]);
         }
     }
 }