Add shared specialty module shell (Phase 2).

Overview/Visits/History/Billing/Workspace layout with stage maps, KPIs,
patient header/timeline, and service catalogs seeded into Billing on activate.
Emergency, Blood Bank, and Dentistry ship first-class shell configs.

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

app/Http/Controllers/Care/SpecialtyModuleController.php

@@ -2,13 +2,15 @@
 
 namespace App\Http\Controllers\Care;
 
-use App\Http\Controllers\Controller;
 use App\Http\Controllers\Care\Concerns\ScopesToAccount;
+use App\Http\Controllers\Controller;
 use App\Models\Appointment;
 use App\Models\Department;
+use App\Models\Visit;
 use App\Services\Care\CareQueueBridge;
 use App\Services\Care\OrganizationResolver;
 use App\Services\Care\SpecialtyModuleService;
+use App\Services\Care\SpecialtyShellService;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
@@ -21,68 +23,86 @@ class SpecialtyModuleController extends Controller
         Request $request,
         string $module,
         SpecialtyModuleService $modules,
+        SpecialtyShellService $shell,
         CareQueueBridge $queueBridge,
     ): View {
+        return $this->renderShell($request, $module, 'overview', $modules, $shell, $queueBridge);
+    }
+
+    public function visits(
+        Request $request,
+        string $module,
+        SpecialtyModuleService $modules,
+        SpecialtyShellService $shell,
+        CareQueueBridge $queueBridge,
+    ): View {
+        return $this->renderShell($request, $module, 'visits', $modules, $shell, $queueBridge);
+    }
+
+    public function history(
+        Request $request,
+        string $module,
+        SpecialtyModuleService $modules,
+        SpecialtyShellService $shell,
+        CareQueueBridge $queueBridge,
+    ): View {
+        return $this->renderShell($request, $module, 'history', $modules, $shell, $queueBridge);
+    }
+
+    public function billing(
+        Request $request,
+        string $module,
+        SpecialtyModuleService $modules,
+        SpecialtyShellService $shell,
+        CareQueueBridge $queueBridge,
+    ): View {
+        return $this->renderShell($request, $module, 'billing', $modules, $shell, $queueBridge);
+    }
+
+    public function workspace(
+        Request $request,
+        string $module,
+        SpecialtyModuleService $modules,
+        SpecialtyShellService $shell,
+        CareQueueBridge $queueBridge,
+        ?Visit $visit = null,
+    ): View {
+        return $this->renderShell($request, $module, 'workspace', $modules, $shell, $queueBridge, $visit);
+    }
+
+    public function addService(
+        Request $request,
+        string $module,
+        Visit $visit,
+        SpecialtyModuleService $modules,
+        SpecialtyShellService $shell,
+    ): RedirectResponse {
         $definition = $modules->definition($module);
         abort_unless($definition, 404);
 
         $organization = $this->organization($request);
         $member = $this->member($request);
         abort_unless($modules->memberCanAccess($organization, $member, $module), 403);
+        abort_unless($visit->organization_id === $organization->id, 404);
 
-        $owner = $this->ownerRef($request);
-        $resolver = app(OrganizationResolver::class);
-        $branchScope = $resolver->branchScope($member);
-        $practitionerScope = $resolver->practitionerScope($organization, $member);
+        $validated = $request->validate([
+            'service_code' => ['required', 'string', 'max:64'],
+        ]);
 
-        $departments = Department::owned($owner)
-            ->where('type', $definition['department_type'] ?? 'general')
-            ->where('is_active', true)
-            ->when($branchScope, fn ($q) => $q->where('branch_id', $branchScope))
-            ->with('branch')
-            ->orderBy('name')
-            ->get();
-
-        $departmentIds = $departments->pluck('id')->all();
-
-        $waiting = Appointment::owned($owner)
-            ->where('organization_id', $organization->id)
-            ->whereIn('status', [Appointment::STATUS_WAITING, Appointment::STATUS_CHECKED_IN])
-            ->when($departmentIds !== [], fn ($q) => $q->whereIn('department_id', $departmentIds))
-            ->when($departmentIds === [], fn ($q) => $q->whereRaw('1 = 0'))
-            ->when($branchScope, fn ($q) => $q->where('branch_id', $branchScope))
-            ->when(
-                $practitionerScope !== null,
-                fn ($q) => $q->whereIn('practitioner_id', $practitionerScope ?: [0]),
-            )
-            ->with(['patient', 'practitioner', 'department'])
-            ->orderBy('queue_position')
-            ->orderBy('checked_in_at')
-            ->limit(25)
-            ->get();
-
-        $branchId = (int) ($branchScope ?: $departments->first()?->branch_id);
-        if ($practitionerScope !== null && $practitionerScope !== []) {
-            $pracBranch = (int) \App\Models\Practitioner::owned($owner)
-                ->whereKey($practitionerScope[0])
-                ->value('branch_id');
-            if ($pracBranch > 0) {
-                $branchId = $pracBranch;
-            }
+        try {
+            $bill = $shell->addCatalogServiceToVisit(
+                $organization,
+                $visit,
+                $module,
+                $validated['service_code'],
+                $this->ownerRef($request),
+                $this->ownerRef($request),
+            );
+        } catch (\Throwable $e) {
+            return back()->with('error', $e->getMessage());
         }
 
-        return view('care.specialty.show', [
-            'organization' => $organization,
-            'moduleKey' => $module,
-            'definition' => $definition,
-            'departments' => $departments,
-            'waiting' => $waiting,
-            'queueStubs' => $modules->queueStubsFor($organization, $module),
-            'branchId' => $branchId,
-            'queueIntegration' => $branchId
-                ? $queueBridge->listMeta($organization, $module, $branchId)
-                : ['enabled' => false],
-        ]);
+        return back()->with('success', 'Added to invoice '.$bill->invoice_number.'.');
     }
 
     public function callNext(
@@ -126,4 +146,125 @@ class SpecialtyModuleController extends Controller
 
         return back()->with('success', 'Called '.$ticket['ticket_number'].'.');
     }
+
+    protected function renderShell(
+        Request $request,
+        string $module,
+        string $section,
+        SpecialtyModuleService $modules,
+        SpecialtyShellService $shell,
+        CareQueueBridge $queueBridge,
+        ?Visit $visit = null,
+    ): View {
+        $definition = $modules->definition($module);
+        abort_unless($definition, 404);
+
+        $organization = $this->organization($request);
+        $member = $this->member($request);
+        abort_unless($modules->memberCanAccess($organization, $member, $module), 403);
+
+        $owner = $this->ownerRef($request);
+        $resolver = app(OrganizationResolver::class);
+        $branchScope = $resolver->branchScope($member);
+        $practitionerScope = $resolver->practitionerScope($organization, $member);
+
+        $departments = Department::owned($owner)
+            ->where('type', $definition['department_type'] ?? 'general')
+            ->where('is_active', true)
+            ->when($branchScope, fn ($q) => $q->where('branch_id', $branchScope))
+            ->with('branch')
+            ->orderBy('name')
+            ->get();
+
+        $departmentIds = $departments->pluck('id')->all();
+
+        $waiting = Appointment::owned($owner)
+            ->where('organization_id', $organization->id)
+            ->whereIn('status', [Appointment::STATUS_WAITING, Appointment::STATUS_CHECKED_IN])
+            ->when($departmentIds !== [], fn ($q) => $q->whereIn('department_id', $departmentIds))
+            ->when($departmentIds === [], fn ($q) => $q->whereRaw('1 = 0'))
+            ->when($branchScope, fn ($q) => $q->where('branch_id', $branchScope))
+            ->when(
+                $practitionerScope !== null,
+                fn ($q) => $q->whereIn('practitioner_id', $practitionerScope ?: [0]),
+            )
+            ->with(['patient', 'practitioner', 'department', 'visit'])
+            ->orderBy('queue_position')
+            ->orderBy('checked_in_at')
+            ->limit(25)
+            ->get();
+
+        $branchId = (int) ($branchScope ?: $departments->first()?->branch_id);
+        if ($practitionerScope !== null && $practitionerScope !== []) {
+            $pracBranch = (int) \App\Models\Practitioner::owned($owner)
+                ->whereKey($practitionerScope[0])
+                ->value('branch_id');
+            if ($pracBranch > 0) {
+                $branchId = $pracBranch;
+            }
+        }
+
+        $shellDefinition = $shell->definition($module);
+        $kpis = $shell->kpis($organization, $module, $owner, $branchScope, $practitionerScope);
+        $openVisits = $shell->openVisits($organization, $module, $owner, $branchScope, $practitionerScope);
+        $visitHistory = $section === 'history'
+            ? $shell->visitHistory($organization, $module, $owner, $branchScope, $practitionerScope)
+            : collect();
+        $services = $shell->provisionedServices($organization, $module);
+
+        $workspaceVisit = null;
+        $patientHeader = null;
+        $timeline = [];
+        $activeTab = (string) $request->query('tab', array_key_first($shell->workspaceTabs($module)) ?: 'overview');
+
+        if ($visit) {
+            abort_unless($visit->organization_id === $organization->id, 404);
+            $visit->load(['patient.allergies', 'patient.emergencyContacts', 'appointment.practitioner', 'bill.lineItems']);
+            $workspaceVisit = $visit;
+            if ($visit->patient) {
+                $patientHeader = array_merge(
+                    ['patient' => $visit->patient, 'visit' => $visit, 'appointment' => $visit->appointment],
+                    $shell->patientHeaderMeta($visit->patient),
+                );
+                $timeline = $shell->patientTimeline($visit->patient);
+            }
+        } elseif ($section === 'workspace') {
+            $first = $openVisits->first();
+            if ($first?->patient) {
+                $workspaceVisit = $first;
+                $patientHeader = array_merge(
+                    ['patient' => $first->patient, 'visit' => $first, 'appointment' => $first->appointment],
+                    $shell->patientHeaderMeta($first->patient),
+                );
+                $timeline = $shell->patientTimeline($first->patient);
+            }
+        }
+
+        return view('care.specialty.shell', [
+            'organization' => $organization,
+            'moduleKey' => $module,
+            'definition' => $shellDefinition,
+            'section' => $section,
+            'navItems' => $shell->navItems($module),
+            'departments' => $departments,
+            'waiting' => $waiting,
+            'openVisits' => $openVisits,
+            'visitHistory' => $visitHistory,
+            'kpis' => $kpis,
+            'stages' => $shell->stages($module),
+            'services' => $services,
+            'workspaceTabs' => $shell->workspaceTabs($module),
+            'actions' => $shell->actions($module),
+            'activeTab' => $activeTab,
+            'workspaceVisit' => $workspaceVisit,
+            'patientHeader' => $patientHeader,
+            'timeline' => $timeline,
+            'queueStubs' => $modules->queueStubsFor($organization, $module),
+            'branchId' => $branchId,
+            'queueIntegration' => $branchId
+                ? $queueBridge->listMeta($organization, $module, $branchId)
+                : ['enabled' => false],
+            'currency' => strtoupper((string) config('care.billing.currency', config('care.currency', 'GHS'))),
+        ]);
+    }
 }