feat(course): treatment courses with protocol-driven session planning

Laser is six to eight sessions; the previous design only knew single
appointments, which is the exception rather than the rule.

- CourseProtocol per service: session count and three distinct spacings —
  min is the earliest that is clinically allowed, ideal is best, max is where
  the course starts losing its effect
- Starting a course creates every session up front as `planned` and copies the
  protocol's numbers and per-session params, so changing the protocol tomorrow
  leaves a running course alone
- Suggestions anchor on the last *completed* session, not the course start:
  when session 2 slips, session 3 moves with it
- Slots are ranked by distance from ideal, not by earliest available — day 21
  is worse than day 27 when 28 is the target
- book-all is all-or-nothing inside one transaction, with a moving anchor and a
  90-day horizon; sessions past the horizon stay planned and are reported, not
  treated as failures
- The effective minimum is the stricter of the protocol and the task-09 spacing
  policy, so a clinic rule never fights the protocol
- Cancelling one session returns only that session to planned; abandoning a
  course does not cancel its appointments, which stays an explicit decision

One active course per (patient, service) via active_course_key, the same
partial-uniqueness trick as Appointment::activeSlotKey.

Admin: CourseProtocolsPage, TreatmentCoursePage and a courses tab on the
patient record.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/Course/Service/CourseSessionLinker.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace App\Course\Service;
+
+use App\Appointment\Entity\Appointment;
+use App\Course\Entity\CourseSession;
+use App\Course\Entity\TreatmentCourse;
+use App\Course\Repository\CourseSessionRepository;
+use Doctrine\ORM\EntityManagerInterface;
+
+/**
+ * تنها جایی که پیوند «نوبت ↔ جلسهٔ دوره» نوشته می‌شود.
+ *
+ * پیوند دوطرفه است (`course_sessions.appointment_id` و `appointments.course_session_id`)
+ * تا لیست نوبت‌های پنل بدون JOIN بفهمد نوبت جزو دوره است و صفحهٔ دوره بدون JOIN نوبت را
+ * پیدا کند. دو ستون یعنی دو فرصت برای واگرایی، پس **فقط این کلاس** می‌نویسدشان.
+ */
+final class CourseSessionLinker
+{
+    public function __construct(
+        private readonly CourseSessionRepository $sessions,
+        private readonly EntityManagerInterface  $em,
+    ) {}
+
+    public function link(CourseSession $session, Appointment $appointment): void
+    {
+        $session->markBooked($appointment);
+        $appointment->setCourseSession($session);
+
+        $this->em->flush();
+    }
+
+    /**
+     * لغو نوبت: همان جلسه به `planned` برمی‌گردد و بقیهٔ دوره دست‌نخورده می‌ماند.
+     *
+     * @return bool `false` یعنی این نوبت اصلاً جزو دوره‌ای نبود
+     */
+    public function unlink(Appointment $appointment): bool
+    {
+        $session = $this->sessions->findForAppointment($appointment);
+
+        if ($session === null) {
+            return false;
+        }
+
+        $session->unbook();
+        $appointment->setCourseSession(null);
+
+        $this->em->flush();
+
+        return true;
+    }
+
+    /**
+     * جلسه انجام شد. دوره وقتی کامل می‌شود که **همهٔ** جلساتش تمام شده باشند —
+     * نه وقتی آخرین جلسه رزرو شد.
+     */
+    public function complete(Appointment $appointment, ?int $at = null): bool
+    {
+        $session = $this->sessions->findForAppointment($appointment);
+
+        if ($session === null) {
+            return false;
+        }
+
+        $session->markCompleted($at);
+
+        $course = $session->getCourse();
+
+        if ($course->completedCount() >= $course->getSessionCount()) {
+            $course->complete($at);
+        }
+
+        $this->em->flush();
+
+        return true;
+    }
+
+    public function courseOf(Appointment $appointment): ?TreatmentCourse
+    {
+        return $this->sessions->findForAppointment($appointment)?->getCourse();
+    }
+}