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,205 @@
+<?php
+
+namespace App\Http\Controllers\Care;
+
+use App\Http\Controllers\Care\Concerns\ScopesToAccount;
+use App\Http\Controllers\Controller;
+use App\Models\FinancialObligation;
+use App\Models\Payment;
+use App\Models\WorkflowStage;
+use App\Services\Care\AuditLogger;
+use App\Services\Care\BillService;
+use App\Services\Care\CareFeatures;
+use App\Services\Care\CarePermissions;
+use App\Services\Care\CareQueueContexts;
+use App\Services\Care\OrganizationResolver;
+use App\Services\Care\Workflow\FinancialGateService;
+use App\Services\Care\Workflow\WorkflowEngine;
+use App\Services\Care\Workflow\WorkflowQueueReleaseService;
+use App\Services\Care\Workflow\WorkflowStageCompletionService;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\Rule;
+use Illuminate\Validation\ValidationException;
+use Illuminate\View\View;
+
+class FinancialObligationController extends Controller
+{
+    use ScopesToAccount;
+
+    public function __construct(
+        protected CareFeatures $features,
+        protected FinancialGateService $gates,
+        protected WorkflowEngine $workflows,
+        protected WorkflowQueueReleaseService $queueRelease,
+        protected WorkflowStageCompletionService $workflowCompletion,
+        protected BillService $bills,
+    ) {}
+
+    public function index(Request $request): View
+    {
+        $this->authorizeAbility($request, 'bills.view');
+        $organization = $this->organization($request);
+        abort_unless($this->features->enabled($organization, CareFeatures::WORKFLOW_ENGINE), 404);
+
+        $branchScope = app(OrganizationResolver::class)->branchScope($this->member($request));
+        $status = (string) $request->query('status', FinancialObligation::STATUS_PENDING);
+
+        $obligations = FinancialObligation::owned($this->ownerRef($request))
+            ->where('organization_id', $organization->id)
+            ->when($branchScope, fn ($query) => $query->where('branch_id', $branchScope))
+            ->when($status !== '', fn ($query) => $query->where('status', $status))
+            ->with(['patient', 'branch', 'stage', 'visit', 'bill'])
+            ->latest('created_at')
+            ->paginate(20)
+            ->withQueryString();
+
+        return view('care.financial-obligations.index', [
+            'obligations' => $obligations,
+            'statuses' => config('care_workflows.obligation_statuses', []),
+            'clearanceMethods' => config('care_workflows.clearance_methods', []),
+            'paymentModes' => config('care_workflows.payment_modes', []),
+            'paymentMethods' => collect(config('care.payment_methods', []))->except(['gateway'])->all(),
+            'canClear' => app(CarePermissions::class)
+                ->can($this->member($request), 'payments.manage'),
+        ]);
+    }
+
+    public function clear(Request $request, FinancialObligation $financialObligation): RedirectResponse
+    {
+        $this->authorizeAbility($request, 'payments.manage');
+        $this->authorizeObligation($request, $financialObligation);
+
+        if ($financialObligation->status !== FinancialObligation::STATUS_PENDING) {
+            return back()->with('info', 'This financial obligation is no longer pending.');
+        }
+
+        $manualPaymentMethods = array_keys(
+            collect(config('care.payment_methods', []))->except(['gateway'])->all()
+        );
+        $validated = $request->validate([
+            'method' => ['required', Rule::in(array_keys(config('care_workflows.clearance_methods', [])))],
+            'payment_mode' => ['nullable', Rule::in(array_keys(config('care_workflows.payment_modes', [])))],
+            'payment_method' => ['nullable', Rule::in($manualPaymentMethods)],
+            'reference' => ['nullable', 'string', 'max:100'],
+        ]);
+
+        $stage = $financialObligation->stage;
+        $method = (string) $validated['method'];
+        $paymentMode = $validated['payment_mode'] ?? null;
+        $reference = trim((string) ($validated['reference'] ?? '')) ?: null;
+
+        $this->validateClearanceRules($stage, $method, $paymentMode, $reference);
+        if ($method === 'bank_receipt') {
+            $paymentMode = 'external_bank';
+        }
+
+        $settled = DB::transaction(function () use ($financialObligation, $validated, $method, $paymentMode, $reference, $request) {
+            $locked = FinancialObligation::query()->lockForUpdate()->findOrFail($financialObligation->id);
+            if ($locked->status !== FinancialObligation::STATUS_PENDING) {
+                return $locked;
+            }
+
+            if (in_array($method, ['payment', 'bank_receipt'], true) && $locked->amount_minor > 0) {
+                $bill = $this->bills->billForObligation(
+                    $locked,
+                    $this->ownerRef($request),
+                    $this->ownerRef($request),
+                );
+
+                $this->bills->recordPayment($bill, $this->ownerRef($request), [
+                    'amount_minor' => $locked->amount_minor,
+                    'method' => $method === 'bank_receipt'
+                        ? Payment::METHOD_OTHER
+                        : ($validated['payment_method'] ?? Payment::METHOD_CASH),
+                    'reference' => $reference,
+                    'notes' => 'Workflow financial obligation '.$locked->uuid,
+                ], $this->ownerRef($request));
+            }
+
+            $this->gates->clear(
+                $locked,
+                $method,
+                $this->ownerRef($request),
+                $paymentMode,
+                $reference,
+            );
+
+            AuditLogger::record(
+                $this->ownerRef($request),
+                'financial_obligation.cleared',
+                $locked->organization_id,
+                $this->ownerRef($request),
+                FinancialObligation::class,
+                $locked->id,
+                ['method' => $method, 'amount_minor' => $locked->amount_minor],
+            );
+
+            return $locked->fresh();
+        });
+
+        $visit = $settled->visit;
+        if ($visit) {
+            $advance = $this->workflows->refreshGate($visit);
+            if ($advance?->stage?->type === 'payment') {
+                $this->workflowCompletion->complete(
+                    $this->organization($request),
+                    $visit,
+                    CareQueueContexts::BILLING,
+                    $this->ownerRef($request),
+                    $this->ownerRef($request),
+                );
+            } else {
+                $this->queueRelease->releaseCurrent($this->organization($request), $visit);
+            }
+        }
+
+        return back()->with('success', 'Financial obligation cleared. The patient may now continue.');
+    }
+
+    protected function validateClearanceRules(?WorkflowStage $stage, string $method, ?string $paymentMode, ?string $reference): void
+    {
+        if ($method === 'insurance' && ! $stage?->insurance_eligible) {
+            throw ValidationException::withMessages(['method' => 'Insurance is not allowed for this stage.']);
+        }
+
+        if ($method === 'credit' && ! $stage?->credit_allowed) {
+            throw ValidationException::withMessages(['method' => 'Credit is not allowed for this stage.']);
+        }
+
+        if (in_array($method, ['waiver', 'override'], true) && ! $stage?->allow_override) {
+            throw ValidationException::withMessages(['method' => 'Waivers and overrides are not allowed for this stage.']);
+        }
+
+        if ($method === 'bank_receipt' && $reference === null) {
+            throw ValidationException::withMessages(['reference' => 'Enter the external bank receipt or slip number.']);
+        }
+
+        if ($method === 'bank_receipt' && $stage && ! in_array('external_bank', (array) $stage->payment_modes, true)) {
+            throw ValidationException::withMessages(['method' => 'External bank receipts are not allowed for this stage.']);
+        }
+
+        if ($method === 'payment') {
+            $allowedModes = (array) ($stage?->payment_modes ?? []);
+            if ($paymentMode === null || ($allowedModes !== [] && ! in_array($paymentMode, $allowedModes, true))) {
+                throw ValidationException::withMessages(['payment_mode' => 'Select a payment mode allowed for this stage.']);
+            }
+
+            if ($paymentMode === 'external_bank') {
+                throw ValidationException::withMessages(['method' => 'Use external bank receipt verification for bank payments.']);
+            }
+        }
+    }
+
+    protected function authorizeObligation(Request $request, FinancialObligation $obligation): void
+    {
+        $this->authorizeOwner($request, $obligation);
+        abort_unless($obligation->organization_id === $this->organization($request)->id, 404);
+
+        $branchId = app(OrganizationResolver::class)->branchScope($this->member($request));
+        if ($branchId !== null && $obligation->branch_id !== $branchId) {
+            abort(404);
+        }
+    }
+}