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/Appointment/Booking/Service/BookingService.php

@@ -7,6 +7,7 @@ use App\Appointment\Booking\Entity\AppointmentHold;
 use App\Appointment\Booking\Entity\AppointmentSegment;
 use App\Appointment\Entity\Appointment;
 use App\Package\Service\CreditLedgerService;
+use App\Course\Service\CourseSessionLinker;
 use App\Package\Service\PackageConsumptionService;
 use App\Shared\Constant\ErrorCodes;
 use App\Shared\Exception\AppException;
@@ -25,6 +26,7 @@ final class BookingService
         private readonly HoldService                $holds,
         private readonly PackageConsumptionService  $packages,
         private readonly CreditLedgerService        $credits,
+        private readonly CourseSessionLinker        $courseSessions,
         private readonly EntityManagerInterface     $em,
     ) {}
 
@@ -107,6 +109,9 @@ final class BookingService
         // ردیف `consume` **حذف نمی‌شود**؛ بازگشت یک ردیف تازه است تا تاریخچه بماند.
         $this->credits->refund($appointment);
 
+        // جلسهٔ دوره به `planned` برمی‌گردد؛ بقیهٔ جلسات دست‌نخورده می‌مانند.
+        $this->courseSessions->unlink($appointment);
+
         return count($occupancies);
     }
 

src/Appointment/Entity/Appointment.php

@@ -225,6 +225,14 @@ class Appointment
     #[ORM\Column(name: 'service_buffer_minutes', type: 'smallint', nullable: true)]
     private ?int $serviceBufferMinutes = null;
 
+    /**
+     * پیوند به جلسهٔ دوره — عمداً دوطرفه است تا لیست نوبت‌ها بدون JOIN بفهمد این نوبت
+     * جزو یک دوره است. فقط `CourseSessionLinker` می‌نویسدش.
+     */
+    #[ORM\ManyToOne(targetEntity: \App\Course\Entity\CourseSession::class)]
+    #[ORM\JoinColumn(name: 'course_session_id', nullable: true, onDelete: 'SET NULL')]
+    private ?\App\Course\Entity\CourseSession $courseSession = null;
+
     #[ORM\Column(name: 'created_at', type: 'integer')]
     private int $createdAt;
 
@@ -286,6 +294,9 @@ class Appointment
     public function setAddressId(?int $v): self { $this->addressId = $v; return $this; }
     public function setClinic(?\App\Clinic\Entity\Clinic $v): self { $this->clinic = $v; return $this; }
     public function setPatientName(?string $v): self { $this->patientName = $v; return $this; }
+
+    public function getCourseSession(): ?\App\Course\Entity\CourseSession { return $this->courseSession; }
+    public function setCourseSession(?\App\Course\Entity\CourseSession $v): self { $this->courseSession = $v; return $this; }
     public function setPatientMobile(?string $v): self { $this->patientMobile = $v; return $this; }
     public function setPatientNationalCode(?string $v): self { $this->patientNationalCode = $v; return $this; }
     public function setPatientGender(?string $v): self { $this->patientGender = $v; return $this; }