feat(appointment): log cancellation events and show them in a Timeline

Introduce the first per-appointment event system. On cancel (via the status
or general update endpoints) an AppointmentEvent (type=cancelled, «نوبت لغو
شد») is recorded with the actor, cancel time, and an optional cancel_reason,
plus a warning-level app_log entry. New GET /appointment/{uuid}/events
returns the ordered event list. The admin appointment detail page renders a
Timeline section and the cancel dialog now collects an optional reason.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/Appointment/Controller/AppointmentController.php

@@ -36,8 +36,34 @@ class AppointmentController extends BaseController
         private readonly \App\ClinicService\Repository\ServiceSectionRepository $sectionRepo,
         private readonly \App\ClinicService\Repository\ServiceItemRepository $itemRepo,
         private readonly \App\Staff\Repository\ClinicStaffRepository $staffRepo,
+        private readonly \App\Appointment\Repository\AppointmentEventRepository $eventRepo,
+        private readonly \Psr\Log\LoggerInterface $logger,
     ) {}
 
+    private const CANCEL_STATUSES = [
+        Appointment::STATUS_CANCELLED_BY_DOCTOR,
+        Appointment::STATUS_CANCELLED_BY_USER,
+    ];
+
+    /**
+     * ثبت رویداد لغو در Timeline نوبت + لاگ سطح warning (تا در app_log هم persist شود).
+     * بعد از ذخیره‌ی موفق نوبت صدا زده می‌شود.
+     */
+    private function recordCancellation(Appointment $appointment, string $status, ?string $reason, User $user): void
+    {
+        $actorName = $user->getRealName() ?: $user->getMobileNumber();
+
+        $event = new \App\Appointment\Entity\AppointmentEvent($appointment, \App\Appointment\Entity\AppointmentEvent::TYPE_CANCELLED, 'نوبت لغو شد');
+        $event->setActor($user->getId(), $actorName);
+        $event->setReason($reason);
+        $this->eventRepo->save($event);
+
+        $this->logger->warning(sprintf(
+            'Appointment cancelled: uuid=%s status=%s by user=%d(%s) reason=%s',
+            $appointment->getUuid(), $status, (int) $user->getId(), $actorName, $reason ?? '-'
+        ));
+    }
+
     // ── Public: available slots ───────────────────────────────────────────────
 
     #[OA\Get(
@@ -665,6 +691,11 @@ class AppointmentController extends BaseController
             $this->patientService->autoCreateOnAppointmentConfirm($appointment);
         }
 
+        if (in_array($newStatus, self::CANCEL_STATUSES, true)) {
+            $reason = isset($data['cancel_reason']) ? trim((string) $data['cancel_reason']) : '';
+            $this->recordCancellation($appointment, $newStatus, $reason !== '' ? $reason : null, $user);
+        }
+
         return $this->success(['data' => $appointment->toArray()]);
     }
 
@@ -750,7 +781,8 @@ class AppointmentController extends BaseController
         }
 
         // Optional status transition, same rules as the dedicated endpoint.
-        $newStatus = trim((string) ($data['status'] ?? ''));
+        $newStatus     = trim((string) ($data['status'] ?? ''));
+        $cancelledTo   = null;
         if ($newStatus !== '' && $newStatus !== $appointment->getStatus()) {
             if (!$appointment->canTransitionTo($newStatus)) {
                 return $this->error(ErrorCodes::ERR_VALIDATION_001, sprintf(
@@ -761,6 +793,9 @@ class AppointmentController extends BaseController
             if ($newStatus === Appointment::STATUS_CONFIRMED) {
                 $this->patientService->autoCreateOnAppointmentConfirm($appointment);
             }
+            if (in_array($newStatus, self::CANCEL_STATUSES, true)) {
+                $cancelledTo = $newStatus;
+            }
         }
 
         try {
@@ -772,6 +807,28 @@ class AppointmentController extends BaseController
             return $this->error(ErrorCodes::ERR_CONFLICT_001, 'این بازه زمانی قبلاً رزرو شده است', 409, 'slot_start');
         }
 
+        if ($cancelledTo !== null) {
+            $reason = isset($data['cancel_reason']) ? trim((string) $data['cancel_reason']) : '';
+            $this->recordCancellation($appointment, $cancelledTo, $reason !== '' ? $reason : null, $user);
+        }
+
         return $this->success(['data' => $appointment->toArray()]);
     }
+
+    // ── Timeline: رویدادهای یک نوبت ───────────────────────────────────────────
+
+    #[Route('/api/v1/appointment/{uuid}/events', methods: ['GET'])]
+    #[IsGranted('IS_AUTHENTICATED_FULLY')]
+    public function events(string $uuid, #[CurrentUser] User $user): JsonResponse
+    {
+        $appointment = $this->appointmentRepo->findByUuid($uuid);
+        if ($appointment === null) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_002, 'نوبت یافت نشد', 404);
+        }
+        if (!$this->canManage($appointment, $user)) {
+            return $this->error(ErrorCodes::ERR_AUTH_006, 'دسترسی ممنوع', 403);
+        }
+
+        return $this->success($this->eventRepo->findByAppointmentUuid($uuid));
+    }
 }