feat(appointments,patients): make clinic context a first-class citizen

Three related fixes, all rooted in the same flaw: authorization and scoping decided by the caller's role instead of by the environment the data belongs to. 1. Single-appointment access (clinic operations were entirely broken) AppointmentController::canView/canManage only knew the patient, the owning doctor and admin -- appointment.clinic was never consulted. A clinic user could create an appointment through /my/appointment but got 403 on detail, edit, move, reserve transfer/replace and status change, so nearly every appointment operation failed in clinic mode. AppointmentAccessChecker now decides from appointment.clinic: clinic owner, member doctor (via ClinicDoctorPermissionChecker) and assigned secretary (via active context + DoctorSecretary) are recognised. Actions reuse the existing permission vocabulary, so active=false remains the single source of truth for "collaboration ended". Cancellation is gated separately and an inline status on PATCH /appointment/{uuid} cannot bypass that gate. The patient is narrowed to view + cancel. Also fixed alongside: listByDoctor now serves a clinic manager but scoped to that clinic; todayStats gained an admin branch and no longer passes an array of doctor ids as the clinic parameter; PatientController::appointments filters on appointment.clinic instead of current membership, so deactivating a doctor no longer erases clinic appointment history from the case file. The doctor-only active_slot_key was reviewed and deliberately left alone -- a doctor is one physical person, so adding clinic to the key would permit double-booking, not fix a bug. Reasoning recorded on the entity. 2. Appointment registration and confirmation Panel-created appointments are born pending ("ثبت شده") instead of confirmed. Confirming is now an explicit act: POST /appointment/{uuid}/confirm transitions the status, files the case file for the appointment's environment (reusing an existing record or creating one) and registers full or partial payments on the resulting visit -- all in one transaction. AppointmentExpiryService would have expired those pending appointments the moment their slot time passed; findExpiredPending is now limited to online gateway holds, which are the only pendings carrying a TTL. A pending appointment still occupies its slot, so the time stays reserved. The admin panel gets a "قطعی کردن نوبت" modal showing the visit fee, each selected service, the total, and paid/remaining/status. It is wired inside AppointmentStatusDropdown, so picking "confirmed" anywhere (timeline, detail, reserve list, info modal) goes through it and confirmation can never silently skip the case file and payment. 3. Clinic case-file access PatientRecordScopeResolver replaces the single-destination role mapping: the active context decides, so a doctor invited into a clinic finally sees their patients' records there. A clinic record is per-patient and shared by design, so "their own patients" is derived from appointments with that doctor in that clinic rather than from a new column. Clinic secretaries are limited to their assigned doctors. Read and write share one rule, and out-of-scope records report 404 so other environments are never disclosed. Tests: 29 new cases across the three areas (clinic appointment access, confirm flow, clinic record access). Full suite 466 tests, 2 pre-existing failures unchanged. API docs updated for all three. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-18 21:04:50 +03:30
parent e6422014d1
commit 7921407f33
26 changed files with 2409 additions and 188 deletions
@@ -0,0 +1,115 @@
+<?php
+
+namespace App\Patient\Security;
+
+use App\Auth\Entity\User;
+use App\Auth\Repository\UserActiveContextRepository;
+use App\Clinic\Repository\ClinicRepository;
+use App\Clinic\Security\ClinicDoctorPermissionChecker;
+use App\Doctor\Repository\DoctorRepository;
+use App\Secretary\Repository\DoctorSecretaryRepository;
+
+/**
+ * «پرونده‌های کدام محیط را این کاربر می‌بیند؟»
+ *
+ * پیش از این، نگاشت تک‌مقصدی بود: نقش پزشک همیشه به پروندهٔ مطب شخصی می‌رسید، پس
+ * پزشکِ دعوت‌شده به کلینیک پرونده‌های بیمارانش در آن کلینیک را اصلاً نمی‌دید. محیط
+ * فعال (UserActiveContext) تعیین‌کننده است، دقیقاً مثل EntityContextResolver.
+ *
+ * «پایان همکاری» منبع حقیقتِ جدا ندارد: ClinicDoctorPermission/DoctorSecretary با
+ * active=false خودشان رد می‌کنند.
+ */
+class PatientRecordScopeResolver
+{
+    private const RESOURCE = 'patients';
+
+    public function __construct(
+        private readonly DoctorRepository              $doctorRepo,
+        private readonly ClinicRepository              $clinicRepo,
+        private readonly UserActiveContextRepository   $contextRepo,
+        private readonly DoctorSecretaryRepository     $secretaryRepo,
+        private readonly ClinicDoctorPermissionChecker $clinicPermissions,
+    ) {}
+
+    public function resolve(User $user): PatientRecordScope
+    {
+        if ($user->hasRole('ROLE_DOCTOR')) {
+            return $this->forDoctorUser($user);
+        }
+
+        if ($user->hasRole('ROLE_CLINIC')) {
+            $clinic = $this->clinicRepo->findByUser($user);
+
+            return PatientRecordScope::forClinic($clinic?->getId());
+        }
+
+        if ($user->hasRole('ROLE_SECRETARY')) {
+            return $this->forSecretary($user);
+        }
+
+        return PatientRecordScope::unknown();
+    }
+
+    /**
+     * پزشک در محیط کلینیکِ فعالش پرونده‌های همان کلینیک را می‌بیند — محدود به
+     * بیمارانِ خودش. بیرون از آن محیط، فقط پروندهٔ مطب شخصی.
+     */
+    private function forDoctorUser(User $user): PatientRecordScope
+    {
+        $doctor = $this->doctorRepo->findByUser($user);
+        if ($doctor === null) {
+            return PatientRecordScope::forDoctor(null);
+        }
+
+        $dbUuid = $this->contextRepo->findByUser($user)?->getDbUuid();
+        $clinic = $dbUuid !== null ? $this->clinicRepo->findByUuid($dbUuid) : null;
+
+        if ($clinic === null || !$clinic->hasDoctor($doctor)) {
+            return PatientRecordScope::forDoctor($doctor->getId());
+        }
+
+        // مالک کلینیکی که خودش پزشک هم هست، محدود نمی‌شود.
+        if ($clinic->getUser()->getId() === $user->getId()) {
+            return PatientRecordScope::forClinic($clinic->getId());
+        }
+
+        if (!$this->clinicPermissions->can($user, $clinic, self::RESOURCE, 'view')) {
+            return PatientRecordScope::forDoctor($doctor->getId());
+        }
+
+        return PatientRecordScope::forClinicRestrictedToDoctors($clinic->getId(), [$doctor->getId()]);
+    }
+
+    /**
+     * منشی در محیط فعالش. در کلینیک، فقط بیمارانِ پزشکانِ تخصیص‌یافته به او —
+     * عضویت در کلینیک به‌تنهایی یعنی منشیِ یک پزشک پروندهٔ بیماران پزشک دیگر را ببیند.
+     */
+    private function forSecretary(User $user): PatientRecordScope
+    {
+        $dbUuid = $this->contextRepo->findByUser($user)?->getDbUuid();
+        if ($dbUuid === null) {
+            return PatientRecordScope::unknown();
+        }
+
+        $clinic = $this->clinicRepo->findByUuid($dbUuid);
+        if ($clinic !== null) {
+            if ($this->secretaryRepo->findActiveBySecretaryForClinic($user, $clinic) === null) {
+                return PatientRecordScope::unknown();
+            }
+
+            $doctorIds = array_map(
+                fn($d) => $d->getId(),
+                $this->secretaryRepo->findDoctorsBySecretaryInClinic($user, $clinic),
+            );
+
+            return PatientRecordScope::forClinicRestrictedToDoctors($clinic->getId(), $doctorIds);
+        }
+
+        $doctor = $this->doctorRepo->findByUuid($dbUuid);
+        if ($doctor !== null && $this->secretaryRepo->findActiveBySecretaryForDoctor($user, $doctor) !== null) {
+            return PatientRecordScope::forDoctor($doctor->getId());
+        }
+
+        return PatientRecordScope::unknown();
+    }
+}