Include checked-in clinic visits on outpatient nursing boards.

OPD/service units list open department appointments without manual place; nursing actions soft-place the visit onto the unit. Inpatient wards stay placement-only. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-20 17:05:13 +00:00
parent 5fd402c043
commit f1bb432324
13 changed files with 522 additions and 60 deletions
@@ -0,0 +1,144 @@
+<?php
+
+namespace App\Services\Care;
+
+use App\Models\CareUnit;
+use App\Models\Visit;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Collection;
+
+/**
+ * Who appears on a care unit’s nursing boards.
+ *
+ * Inpatient: visits placed on the unit.
+ * Outpatient / service: placed visits plus open clinic visits for the same
+ * department (checked-in appointments) so OPD nurses do not need manual place.
+ */
+class CareUnitCensusService
+{
+    /** @var list<string> */
+    public const CLINIC_KINDS = ['outpatient', 'service'];
+
+    public function isClinicUnit(CareUnit $unit): bool
+    {
+        return in_array($unit->kind, self::CLINIC_KINDS, true);
+    }
+
+    /**
+     * Active visits nurses should see for this unit.
+     *
+     * @return Collection<int, Visit>
+     */
+    public function visitsForUnit(CareUnit $unit, string $ownerRef): Collection
+    {
+        $unit->loadMissing('department');
+
+        return $this->queryForUnit($unit, $ownerRef)
+            ->with(['patient', 'bed', 'appointment'])
+            ->orderByRaw('care_unit_id is null') // placed first
+            ->orderBy('placed_at')
+            ->orderBy('checked_in_at')
+            ->get();
+    }
+
+    public function visitBelongsToUnit(Visit $visit, CareUnit $unit): bool
+    {
+        if ((int) $visit->organization_id !== (int) $unit->organization_id) {
+            return false;
+        }
+
+        if (! in_array($visit->status, [Visit::STATUS_OPEN, Visit::STATUS_IN_PROGRESS], true)) {
+            return false;
+        }
+
+        if ((int) $visit->care_unit_id === (int) $unit->id) {
+            return true;
+        }
+
+        if (! $this->isClinicUnit($unit) || $visit->care_unit_id !== null) {
+            return false;
+        }
+
+        $unit->loadMissing('department');
+        $branchId = $unit->department?->branch_id;
+        if (! $branchId || (int) $visit->branch_id !== (int) $branchId) {
+            return false;
+        }
+
+        $departmentId = $unit->department_id;
+        if (! $departmentId) {
+            return false;
+        }
+
+        $appointment = $visit->relationLoaded('appointment')
+            ? $visit->appointment
+            : $visit->appointment()->first();
+
+        return $appointment !== null && (int) $appointment->department_id === (int) $departmentId;
+    }
+
+    /**
+     * Soft-place an eligible clinic visit onto the unit when a nurse acts on it.
+     */
+    public function ensurePlaced(
+        Visit $visit,
+        CareUnit $unit,
+        string $ownerRef,
+        ?string $actorRef = null,
+    ): Visit {
+        $visit->refresh();
+
+        if ((int) $visit->care_unit_id === (int) $unit->id) {
+            return $visit;
+        }
+
+        if (! $this->visitBelongsToUnit($visit, $unit)) {
+            abort(404);
+        }
+
+        if ($visit->care_unit_id !== null) {
+            abort(404);
+        }
+
+        app(VisitPlacementService::class)->place(
+            $visit,
+            $unit,
+            null,
+            $ownerRef,
+            $actorRef,
+            'Auto-placed from outpatient nursing board',
+        );
+
+        return $visit->fresh(['patient', 'bed', 'careUnit', 'appointment']);
+    }
+
+    /**
+     * @return Builder<Visit>
+     */
+    protected function queryForUnit(CareUnit $unit, string $ownerRef): Builder
+    {
+        $query = Visit::owned($ownerRef)
+            ->where('organization_id', $unit->organization_id)
+            ->whereIn('status', [Visit::STATUS_OPEN, Visit::STATUS_IN_PROGRESS]);
+
+        if (! $this->isClinicUnit($unit)) {
+            return $query->where('care_unit_id', $unit->id);
+        }
+
+        $unit->loadMissing('department');
+        $branchId = $unit->department?->branch_id;
+        $departmentId = $unit->department_id;
+
+        return $query->where(function (Builder $q) use ($unit, $branchId, $departmentId) {
+            $q->where('care_unit_id', $unit->id);
+
+            if ($branchId && $departmentId) {
+                $q->orWhere(function (Builder $clinic) use ($branchId, $departmentId) {
+                    $clinic->whereNull('care_unit_id')
+                        ->where('branch_id', $branchId)
+                        ->whereHas('appointment', fn (Builder $a) => $a->where('department_id', $departmentId));
+                });
+            }
+        });
+    }
+}