Activate Care workflows across check-in and financial clearance.

Enforce service-queue gates, cashier settlements, and clinical stage progression so patient journeys cannot bypass configured payment or authorization rules. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-17 21:13:06 +00:00
parent 86bfce1e17
commit 3ee59a0956
38 changed files with 1953 additions and 107 deletions
@@ -0,0 +1,67 @@
+<?php
+
+namespace App\Services\Care\Workflow;
+
+use App\Models\Organization;
+use App\Models\Visit;
+use App\Services\Care\CareFeatures;
+use App\Services\Care\CareQueueContexts;
+
+/**
+ * Single boundary for deciding whether a visit may be exposed to a Queue
+ * service line. Every direct issue and background backfill passes through it.
+ */
+class WorkflowQueueGate
+{
+    public function __construct(
+        protected CareFeatures $features,
+        protected WorkflowEngine $engine,
+    ) {}
+
+    public function enabled(Organization $organization): bool
+    {
+        return $this->features->enabled($organization, CareFeatures::WORKFLOW_ENGINE);
+    }
+
+    public function canRelease(
+        Organization $organization,
+        ?Visit $visit,
+        string $queueContext,
+    ): bool {
+        if (! $this->enabled($organization) || $visit === null) {
+            return true;
+        }
+
+        $advance = $this->engine->currentAdvance($visit)
+            ? $this->engine->refreshGate($visit)
+            : $this->engine->start($visit);
+        $stage = $advance?->stage;
+
+        // An enabled org without a materialized workflow keeps legacy behavior.
+        if ($stage === null) {
+            return true;
+        }
+
+        if (! $this->contextsMatch($stage->queue_context, $stage->type, $queueContext)) {
+            return false;
+        }
+
+        if (! $this->features->enabled($organization, CareFeatures::FINANCIAL_GATES)) {
+            return true;
+        }
+
+        return $this->engine->isQueueReleasable($visit);
+    }
+
+    protected function contextsMatch(?string $stageContext, string $stageType, string $queueContext): bool
+    {
+        if ($stageContext === $queueContext) {
+            return true;
+        }
+
+        // Specialty appointments still fulfill a consultation workflow stage.
+        return $stageType === 'consultation'
+            && CareQueueContexts::isSpecialty($queueContext)
+            && $stageContext === CareQueueContexts::CONSULTATION;
+    }
+}