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
@@ -3,7 +3,13 @@
 namespace App\Appointment\Service;

 use App\Appointment\Entity\Appointment;
+use App\Appointment\Repository\AppointmentRepository;
+use App\Auth\Entity\User;
+use App\Patient\Entity\PatientSession;
 use App\Patient\Service\PatientService;
+use App\Shared\Constant\ErrorCodes;
+use App\Shared\Exception\AppException;
+use Doctrine\ORM\EntityManagerInterface;
 use Psr\Log\LoggerInterface;

 /**
@@ -16,8 +22,10 @@ use Psr\Log\LoggerInterface;
 class AppointmentConfirmationService
 {
    public function __construct(
-        private readonly PatientService  $patientService,
-        private readonly LoggerInterface $logger,
+        private readonly PatientService        $patientService,
+        private readonly AppointmentRepository $appointmentRepo,
+        private readonly EntityManagerInterface $em,
+        private readonly LoggerInterface       $logger,
    ) {}

    /**
@@ -27,20 +35,66 @@ class AppointmentConfirmationService
     * رزرو شده و پول پرداخت شده است؛ پرونده را می‌شود با
     * `app:appointment:backfill-sessions` ساخت، ولی رول‌بکِ پرداخت برگشت‌ناپذیر است.
     */
-    public function onConfirmed(Appointment $appointment): void
+    public function onConfirmed(Appointment $appointment): ?PatientSession
    {
        // نوبت رزروِ روز-محور اسلات و ساعت مشخص ندارد؛ مراجعهٔ زمان‌دار برایش معنا ندارد.
        if ($appointment->isReserve()) {
-            return;
+            return null;
        }

        try {
-            $this->patientService->autoCreateOnAppointmentConfirm($appointment);
+            return $this->patientService->autoCreateOnAppointmentConfirm($appointment);
        } catch (\Throwable $e) {
            $this->logger->error('Auto-creating the patient record on confirm failed', [
                'appointment_uuid' => $appointment->getUuid(),
                'exception'        => $e,
            ]);
+
+            return null;
        }
    }
+
+    /**
+     * قطعی‌کردنِ صریح از پنل: انتقال وضعیت، ثبت پرونده/مراجعه و ثبت پرداخت‌ها — همه
+     * در یک تراکنش. برخلاف onConfirmed اینجا شکست خاموش نمی‌ماند: کاربر روبه‌روی
+     * مودالی ایستاده که مبلغ نشان داده و منتظر تأیید است؛ «قطعی شد ولی پول ثبت نشد»
+     * بدترین خروجیِ ممکن است.
+     *
+     * @param  array<int, array{method: string, amount_rials: int}> $payments
+     * @return PatientSession|null null یعنی این tenant قابلیت پرونده را ندارد
+     *                             (فقط وقتی مجاز است که پرداختی هم ارسال نشده باشد)
+     */
+    public function confirmWithPayments(
+        Appointment $appointment,
+        int $expectedVersion,
+        array $payments,
+        User $actor,
+    ): ?PatientSession {
+        return $this->em->wrapInTransaction(function () use ($appointment, $expectedVersion, $payments, $actor) {
+            $appointment->transitionTo(Appointment::STATUS_CONFIRMED);
+            $this->appointmentRepo->saveWithLock($appointment, $expectedVersion);
+
+            $session = $this->patientService->autoCreateOnAppointmentConfirm($appointment);
+
+            if ($session === null) {
+                if ($payments !== []) {
+                    throw new AppException(ErrorCodes::ERR_SUBSCRIPTION_REQUIRED, null, 403);
+                }
+
+                return null;
+            }
+
+            foreach ($payments as $payment) {
+                $this->patientService->addSessionPayment(
+                    $session,
+                    $payment['method'],
+                    $payment['amount_rials'],
+                    null,
+                    $actor,
+                );
+            }
+
+            return $session;
+        });
+    }
 }