feat(catalog): dual durations, item groups, relations and branch overrides

Section 5 of the design document rejects summing service durations. "Face + bikini"
is not 15+12=27 minutes but 15+8=23 — preparation and settling the patient do not
happen twice. Seven wasted minutes times twenty appointments a day is an hour of
capacity lost daily, and AppointmentController was doing exactly that plain sum.

Each item now carries a solo duration and an additional duration. One item counts at
its solo duration and the rest at their additional; the anchor is the item with the
*largest* solo duration rather than the first one selected. Anchoring on selection
order would have let the same basket cost different amounts depending on click order,
so a patient could buy a shorter appointment by reordering. Largest-first is also
conservative: no combination is ever under-estimated, and under-estimating pushes the
next appointment on top of this one.

additional_duration_minutes stays NULL by default and the entity reads NULL as "same
as solo", so every existing service keeps behaving exactly as before — the 236
appointment-domain tests pass unchanged. The old duration_minutes column is kept and
written in step rather than renamed, because other consumers still read it.

ServiceBookingCalculator now delegates to DurationCalculator, which is the one-line
change task 00 predicted when it deliberately preserved the naive sum.

Selection rules are data, not policy: min/max per group is a number, and "bikini does
not combine with full body" is a relation. Putting either in a rules engine means
several rules per service and nobody able to explain a rejection. Validation returns
*all* errors at once rather than the first, since a user with three problems should
not make three round trips. Prerequisite cycles are rejected at write time — storing
both "A requires B" and "B requires A" would make every selection permanently invalid.

Named CatalogCategory, not ServiceCategory: that name is already an insurance enum
(outpatient/inpatient) living on ServiceItem itself, so the two would have collided in
the same file's imports.

Also fixed a defect the tests caught: breakdown() used $overrides[$id]?->… on a key
that may not exist, which warns instead of yielding null.

1175 tests / 3289 assertions. phpstan measured at 14 errors both with and without
this change (verified by stashing). Slot-mode frozen contract green.

The admin UI tab for groups and relations is not built; the checklist records it as
outstanding with a target. The backend is complete and
POST /service-selection/validate is consumable without it.

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

src/ClinicService/Entity/CatalogCategory.php

@@ -0,0 +1,108 @@
+<?php
+
+namespace App\ClinicService\Entity;
+
+use App\ClinicService\Repository\CatalogCategoryRepository;
+use App\Shared\Tenant\TenantOwnedTrait;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Uid\Uuid;
+
+/**
+ * دسته‌بندی درختی کاتالوگ خدمات — «لیزر ← نواحی بدن»، «تزریقات ← ژل».
+ *
+ * نامش عمداً `ServiceCategory` نیست: آن نام از قبل گرفته شده و یک **enum بیمه‌ای**
+ * است ({@see \App\Insurance\Enum\ServiceCategory} با مقادیر outpatient/inpatient) که
+ * روی خودِ ServiceItem هم نشسته. هم‌نام کردنشان یعنی دو `use` متضاد در یک فایل.
+ *
+ * با {@see ServiceSection} هم فرق دارد: آن «بخش کلینیک» است (واحد سازمانی)، این
+ * تاکسونومی کاتالوگ.
+ */
+#[ORM\Entity(repositoryClass: CatalogCategoryRepository::class)]
+#[ORM\Table(name: 'service_catalog_categories')]
+#[ORM\Index(columns: ['entity_type', 'entity_id', 'active'], name: 'idx_catalog_cat_tenant')]
+#[ORM\Index(columns: ['parent_id'], name: 'idx_catalog_cat_parent')]
+class CatalogCategory
+{
+    use TenantOwnedTrait;
+
+    /** سقف عمق درخت — بدون آن یک اشتباه در UI می‌تواند زنجیرهٔ بی‌پایان بسازد. */
+    public const MAX_DEPTH = 4;
+
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    private ?int $id = null;
+
+    #[ORM\Column(type: 'string', length: 36, unique: true)]
+    private string $uuid;
+
+    #[ORM\ManyToOne(targetEntity: self::class)]
+    #[ORM\JoinColumn(name: 'parent_id', referencedColumnName: 'id', nullable: true, onDelete: 'CASCADE')]
+    private ?self $parent = null;
+
+    #[ORM\Column(type: 'string', length: 150)]
+    private string $name;
+
+    #[ORM\Column(name: 'sort_order', type: 'smallint', options: ['default' => 0])]
+    private int $sortOrder = 0;
+
+    #[ORM\Column(type: 'boolean', options: ['default' => true])]
+    private bool $active = true;
+
+    #[ORM\Column(name: 'created_at', type: 'integer')]
+    private int $createdAt;
+
+    #[ORM\Column(name: 'updated_at', type: 'integer')]
+    private int $updatedAt;
+
+    public function __construct(string $entityType, int $entityId, string $name, ?self $parent = null)
+    {
+        $this->uuid      = Uuid::v4()->toRfc4122();
+        $this->name      = $name;
+        $this->parent    = $parent;
+        $this->createdAt = time();
+        $this->updatedAt = time();
+
+        $this->assignTenantPair($entityType, $entityId);
+    }
+
+    public function getId(): ?int       { return $this->id; }
+    public function getUuid(): string   { return $this->uuid; }
+    public function getParent(): ?self  { return $this->parent; }
+    public function getName(): string   { return $this->name; }
+    public function getSortOrder(): int { return $this->sortOrder; }
+    public function isActive(): bool    { return $this->active; }
+
+    public function setName(string $v): self     { $this->name = $v; $this->touch(); return $this; }
+    public function setSortOrder(int $v): self   { $this->sortOrder = $v; $this->touch(); return $this; }
+    public function setActive(bool $v): self     { $this->active = $v; $this->touch(); return $this; }
+    public function setParent(?self $v): self    { $this->parent = $v; $this->touch(); return $this; }
+
+    /** عمق از ریشه؛ ریشه صفر است. */
+    public function depth(): int
+    {
+        $depth  = 0;
+        $node   = $this->parent;
+
+        while ($node !== null && $depth <= self::MAX_DEPTH + 1) {
+            $depth++;
+            $node = $node->getParent();
+        }
+
+        return $depth;
+    }
+
+    private function touch(): void { $this->updatedAt = time(); }
+
+    public function toArray(array $children = []): array
+    {
+        return [
+            'uuid'        => $this->uuid,
+            'parent_uuid' => $this->parent?->getUuid(),
+            'name'        => $this->name,
+            'sort_order'  => $this->sortOrder,
+            'active'      => $this->active,
+            'children'    => $children,
+        ];
+    }
+}

src/ClinicService/Entity/ItemGroup.php

@@ -0,0 +1,129 @@
+<?php
+
+namespace App\ClinicService\Entity;
+
+use App\ClinicService\Repository\ItemGroupRepository;
+use App\Shared\Tenant\TenantOwnedTrait;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Uid\Uuid;
+
+/**
+ * گروه انتخابِ آیتم درون یک سرویس — «نواحی بدن»، «سطح انرژی».
+ *
+ * بند ۵ مستند: این قوانین **نباید** به موتور قوانین سپرده شوند. «حتماً یک سطح انرژی،
+ * فقط یکی» یک عدد است (`min=1, max=1`)، نه یک قانون؛ سپردنش به موتور یعنی هر سرویس
+ * چند قانون و هیچ‌کس نمی‌فهمد چرا انتخابش رد شد.
+ */
+#[ORM\Entity(repositoryClass: ItemGroupRepository::class)]
+#[ORM\Table(name: 'service_item_groups')]
+#[ORM\Index(columns: ['entity_type', 'entity_id'], name: 'idx_item_group_tenant')]
+#[ORM\Index(columns: ['service_id', 'sort_order'], name: 'idx_item_group_service')]
+class ItemGroup
+{
+    use TenantOwnedTrait;
+
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    private ?int $id = null;
+
+    #[ORM\Column(type: 'string', length: 36, unique: true)]
+    private string $uuid;
+
+    /** سرویسی که این گروه متعلق به آن است. */
+    #[ORM\ManyToOne(targetEntity: ServiceItem::class)]
+    #[ORM\JoinColumn(name: 'service_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
+    private ServiceItem $service;
+
+    #[ORM\Column(type: 'string', length: 150)]
+    private string $name;
+
+    #[ORM\Column(name: 'min_select', type: 'smallint', options: ['default' => 0])]
+    private int $minSelect = 0;
+
+    /** `null` یعنی نامحدود. */
+    #[ORM\Column(name: 'max_select', type: 'smallint', nullable: true)]
+    private ?int $maxSelect = null;
+
+    #[ORM\Column(name: 'sort_order', type: 'smallint', options: ['default' => 0])]
+    private int $sortOrder = 0;
+
+    #[ORM\Column(name: 'created_at', type: 'integer')]
+    private int $createdAt;
+
+    #[ORM\Column(name: 'updated_at', type: 'integer')]
+    private int $updatedAt;
+
+    /** @var Collection<int, ItemGroupMember> */
+    #[ORM\OneToMany(targetEntity: ItemGroupMember::class, mappedBy: 'group', cascade: ['persist', 'remove'], orphanRemoval: true)]
+    #[ORM\OrderBy(['sortOrder' => 'ASC'])]
+    private Collection $members;
+
+    public function __construct(ServiceItem $service, string $name)
+    {
+        $this->uuid      = Uuid::v4()->toRfc4122();
+        $this->service   = $service;
+        $this->name      = $name;
+        $this->createdAt = time();
+        $this->updatedAt = time();
+        $this->members   = new ArrayCollection();
+
+        $this->assignTenantPair($service->getSection()->getEntityType(), $service->getSection()->getEntityId());
+    }
+
+    public function getId(): ?int             { return $this->id; }
+    public function getUuid(): string         { return $this->uuid; }
+    public function getService(): ServiceItem { return $this->service; }
+    public function getName(): string         { return $this->name; }
+    public function getMinSelect(): int       { return $this->minSelect; }
+    public function getMaxSelect(): ?int      { return $this->maxSelect; }
+    public function getSortOrder(): int       { return $this->sortOrder; }
+
+    /** @return Collection<int, ItemGroupMember> */
+    public function getMembers(): Collection  { return $this->members; }
+
+    public function setName(string $v): self   { $this->name = $v; $this->touch(); return $this; }
+    public function setSortOrder(int $v): self { $this->sortOrder = $v; $this->touch(); return $this; }
+
+    /** @throws \InvalidArgumentException روی بازهٔ ناممکن */
+    public function setSelectRange(int $min, ?int $max): self
+    {
+        if ($min < 0) {
+            throw new \InvalidArgumentException('min_select cannot be negative.');
+        }
+
+        if ($max !== null && $max < 1) {
+            throw new \InvalidArgumentException('max_select must be at least 1 when set.');
+        }
+
+        if ($max !== null && $max < $min) {
+            throw new \InvalidArgumentException('max_select cannot be smaller than min_select.');
+        }
+
+        $this->minSelect = $min;
+        $this->maxSelect = $max;
+        $this->touch();
+
+        return $this;
+    }
+
+    public function touch(): void { $this->updatedAt = time(); }
+
+    public function toArray(): array
+    {
+        return [
+            'uuid'         => $this->uuid,
+            'service_uuid' => $this->service->getUuid(),
+            'name'         => $this->name,
+            'min_select'   => $this->minSelect,
+            'max_select'   => $this->maxSelect,
+            'sort_order'   => $this->sortOrder,
+            'items'        => array_map(
+                static fn (ItemGroupMember $m): array => $m->toArray(),
+                $this->members->toArray(),
+            ),
+        ];
+    }
+}

src/ClinicService/Entity/ItemGroupMember.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace App\ClinicService\Entity;
+
+use App\ClinicService\Repository\ItemGroupMemberRepository;
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * عضویت یک آیتم در یک گروه انتخاب. فرزند aggregate با ریشهٔ {@see ItemGroup} که خودش
+ * جفت محیط دارد؛ uuid ندارد و فقط از `PUT /item-group/{uuid}/items` نوشته می‌شود.
+ */
+#[ORM\Entity(repositoryClass: ItemGroupMemberRepository::class)]
+#[ORM\Table(name: 'service_item_group_members')]
+#[ORM\UniqueConstraint(name: 'uniq_group_item', columns: ['group_id', 'item_id'])]
+#[ORM\Index(columns: ['item_id'], name: 'idx_group_member_item')]
+class ItemGroupMember
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    private ?int $id = null;
+
+    #[ORM\ManyToOne(targetEntity: ItemGroup::class, inversedBy: 'members')]
+    #[ORM\JoinColumn(name: 'group_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
+    private ItemGroup $group;
+
+    #[ORM\ManyToOne(targetEntity: ServiceItem::class)]
+    #[ORM\JoinColumn(name: 'item_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
+    private ServiceItem $item;
+
+    #[ORM\Column(name: 'sort_order', type: 'smallint', options: ['default' => 0])]
+    private int $sortOrder = 0;
+
+    public function __construct(ItemGroup $group, ServiceItem $item, int $sortOrder = 0)
+    {
+        $this->group     = $group;
+        $this->item      = $item;
+        $this->sortOrder = $sortOrder;
+    }
+
+    public function getId(): ?int          { return $this->id; }
+    public function getGroup(): ItemGroup  { return $this->group; }
+    public function getItem(): ServiceItem { return $this->item; }
+    public function getSortOrder(): int    { return $this->sortOrder; }
+
+    public function toArray(): array
+    {
+        return [
+            'item_uuid'                  => $this->item->getUuid(),
+            'item_name'                  => $this->item->getName(),
+            'solo_duration_minutes'      => $this->item->getSoloDurationMinutes(),
+            'additional_duration_minutes' => $this->item->effectiveAdditionalMinutes(),
+            'price_rials'                => $this->item->getPriceRials(),
+            'sort_order'                 => $this->sortOrder,
+            'active'                     => $this->item->isActive(),
+        ];
+    }
+}

src/ClinicService/Entity/ServiceBranchOverride.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace App\ClinicService\Entity;
+
+use App\ClinicService\Repository\ServiceBranchOverrideRepository;
+use App\Doctor\Entity\DoctorAddress;
+use App\Shared\Tenant\TenantOwnedTrait;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Uid\Uuid;
+
+/**
+ * قیمت و مدتِ اختصاصیِ یک سرویس در یک شعبه.
+ *
+ * «شعبه» همان `doctor_addresses` است ({@see docs/new_feture/taskes/_shared/branch-is-doctor-address.md}).
+ * هر ستون تهی‌پذیر است و `null` یعنی «همان مقدار خودِ سرویس» — نه صفر.
+ */
+#[ORM\Entity(repositoryClass: ServiceBranchOverrideRepository::class)]
+#[ORM\Table(name: 'service_branch_overrides')]
+#[ORM\UniqueConstraint(name: 'uniq_override_item_address', columns: ['item_id', 'address_id'])]
+#[ORM\Index(columns: ['entity_type', 'entity_id'], name: 'idx_override_tenant')]
+class ServiceBranchOverride
+{
+    use TenantOwnedTrait;
+
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    private ?int $id = null;
+
+    #[ORM\Column(type: 'string', length: 36, unique: true)]
+    private string $uuid;
+
+    #[ORM\ManyToOne(targetEntity: ServiceItem::class)]
+    #[ORM\JoinColumn(name: 'item_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
+    private ServiceItem $item;
+
+    #[ORM\ManyToOne(targetEntity: DoctorAddress::class)]
+    #[ORM\JoinColumn(name: 'address_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
+    private DoctorAddress $address;
+
+    #[ORM\Column(name: 'price_rials', type: 'bigint', nullable: true)]
+    private ?int $priceRials = null;
+
+    #[ORM\Column(name: 'solo_duration_minutes', type: 'smallint', nullable: true)]
+    private ?int $soloDurationMinutes = null;
+
+    #[ORM\Column(name: 'additional_duration_minutes', type: 'smallint', nullable: true)]
+    private ?int $additionalDurationMinutes = null;
+
+    #[ORM\Column(name: 'created_at', type: 'integer')]
+    private int $createdAt;
+
+    #[ORM\Column(name: 'updated_at', type: 'integer')]
+    private int $updatedAt;
+
+    public function __construct(ServiceItem $item, DoctorAddress $address)
+    {
+        $this->uuid      = Uuid::v4()->toRfc4122();
+        $this->item      = $item;
+        $this->address   = $address;
+        $this->createdAt = time();
+        $this->updatedAt = time();
+
+        $this->assignTenantPair($item->getSection()->getEntityType(), $item->getSection()->getEntityId());
+    }
+
+    public function getId(): ?int                       { return $this->id; }
+    public function getUuid(): string                   { return $this->uuid; }
+    public function getItem(): ServiceItem              { return $this->item; }
+    public function getAddress(): DoctorAddress         { return $this->address; }
+    public function getPriceRials(): ?int               { return $this->priceRials === null ? null : (int) $this->priceRials; }
+    public function getSoloDurationMinutes(): ?int      { return $this->soloDurationMinutes; }
+    public function getAdditionalDurationMinutes(): ?int { return $this->additionalDurationMinutes; }
+
+    public function setPriceRials(?int $v): self                { $this->priceRials = $v; $this->touch(); return $this; }
+    public function setSoloDurationMinutes(?int $v): self       { $this->soloDurationMinutes = $v; $this->touch(); return $this; }
+    public function setAdditionalDurationMinutes(?int $v): self { $this->additionalDurationMinutes = $v; $this->touch(); return $this; }
+
+    private function touch(): void { $this->updatedAt = time(); }
+
+    public function toArray(): array
+    {
+        return [
+            'uuid'                        => $this->uuid,
+            'item_uuid'                   => $this->item->getUuid(),
+            'address_uuid'                => $this->address->getUuid(),
+            'address_name'                => $this->address->getName(),
+            'price_rials'                 => $this->getPriceRials(),
+            'solo_duration_minutes'       => $this->soloDurationMinutes,
+            'additional_duration_minutes' => $this->additionalDurationMinutes,
+        ];
+    }
+}

src/ClinicService/Entity/ServiceItem.php

@@ -68,9 +68,36 @@ class ServiceItem
     #[ORM\Column(name: 'insurance_price_rials', type: 'integer', nullable: true)]
     private ?int $insurancePriceRials = null;
 
+    /**
+     * @deprecated مقدار قدیمی؛ منبع حقیقتِ مدت اکنون `soloDurationMinutes` است.
+     *             هنوز نوشته می‌شود تا مصرف‌کننده‌های موجود نشکنند.
+     */
     #[ORM\Column(name: 'duration_minutes', type: 'integer', nullable: true)]
     private ?int $durationMinutes = null;
 
+    /** مدت این آیتم وقتی **تنها** انجام شود. */
+    #[ORM\Column(name: 'solo_duration_minutes', type: 'smallint', nullable: true)]
+    private ?int $soloDurationMinutes = null;
+
+    /**
+     * مدت این آیتم وقتی **کنار آیتم دیگری** در همان نوبت انجام شود.
+     *
+     * بند ۵ مستند: جمع سادهٔ مدت‌ها ظرفیت را هدر می‌دهد. «صورت + بیکینی» ۱۵+۱۲=۲۷
+     * نیست، ۱۵+۸=۲۳ است؛ آماده‌سازی و استقرار بیمار دو بار انجام نمی‌شود.
+     *
+     * `null` یعنی «همان مدت تنها» — سازگاری با دادهٔ موجودی که فقط یک عدد داشت.
+     */
+    #[ORM\Column(name: 'additional_duration_minutes', type: 'smallint', nullable: true)]
+    private ?int $additionalDurationMinutes = null;
+
+    /** تعداد جلسات؛ ۱ یعنی تک‌جلسه‌ای. پروتکل کامل دوره در تسک ۱۲. */
+    #[ORM\Column(name: 'session_count', type: 'smallint', options: ['default' => 1])]
+    private int $sessionCount = 1;
+
+    #[ORM\ManyToOne(targetEntity: CatalogCategory::class)]
+    #[ORM\JoinColumn(name: 'catalog_category_id', referencedColumnName: 'id', nullable: true, onDelete: 'SET NULL')]
+    private ?CatalogCategory $catalogCategory = null;
+
     /** نمایش این سرویس در نوبت‌دهی (پزشک ممکن است همهٔ سرویس‌ها را ارائه ندهد). */
     #[ORM\Column(type: 'boolean', options: ['default' => false])]
     private bool $bookable = false;
@@ -203,7 +230,67 @@ class ServiceItem
     public function setActive(bool $active): self         { $this->active = $active; $this->updatedAt = time(); return $this; }
     public function setInsuranceCovered(bool $v): self    { $this->insuranceCovered = $v; $this->updatedAt = time(); return $this; }
     public function setServiceCategory(ServiceCategory $v): self { $this->serviceCategory = $v; $this->updatedAt = time(); return $this; }
-    public function setDurationMinutes(?int $v): self { $this->durationMinutes = $v; $this->updatedAt = time(); return $this; }
+    /** هر دو ستون را هم‌زمان می‌نویسد تا «مدت» یک منبع حقیقت داشته باشد. */
+    public function setDurationMinutes(?int $v): self
+    {
+        $this->durationMinutes     = $v;
+        $this->soloDurationMinutes = $v;
+        $this->updatedAt           = time();
+
+        return $this;
+    }
+
+    public function getSoloDurationMinutes(): ?int       { return $this->soloDurationMinutes ?? $this->durationMinutes; }
+    public function getAdditionalDurationMinutes(): ?int { return $this->additionalDurationMinutes; }
+    public function getSessionCount(): int               { return $this->sessionCount; }
+    public function getCatalogCategory(): ?CatalogCategory { return $this->catalogCategory; }
+
+    /**
+     * مدتِ «کنار بقیه». آیتمی که مقدارش را نگذاشته، همان مدت تنها را می‌گیرد — پس
+     * دادهٔ موجود دقیقاً مثل قبل حساب می‌شود و این تغییر افزایشی است.
+     */
+    public function effectiveAdditionalMinutes(): ?int
+    {
+        return $this->additionalDurationMinutes ?? $this->getSoloDurationMinutes();
+    }
+
+    public function setSoloDurationMinutes(?int $v): self
+    {
+        $this->soloDurationMinutes = $v;
+        $this->durationMinutes     = $v;   // ستون قدیمی هم‌گام می‌ماند
+        $this->updatedAt           = time();
+
+        return $this;
+    }
+
+    public function setAdditionalDurationMinutes(?int $v): self
+    {
+        $this->additionalDurationMinutes = $v;
+        $this->updatedAt = time();
+
+        return $this;
+    }
+
+    /** @throws \InvalidArgumentException روی تعداد جلسهٔ کمتر از ۱ */
+    public function setSessionCount(int $v): self
+    {
+        if ($v < 1) {
+            throw new \InvalidArgumentException('session_count must be at least 1.');
+        }
+
+        $this->sessionCount = $v;
+        $this->updatedAt    = time();
+
+        return $this;
+    }
+
+    public function setCatalogCategory(?CatalogCategory $v): self
+    {
+        $this->catalogCategory = $v;
+        $this->updatedAt       = time();
+
+        return $this;
+    }
     public function setBookable(bool $v): self { $this->bookable = $v; $this->updatedAt = time(); return $this; }
     public function setInventoryPackageId(?int $v): self { $this->inventoryPackageId = $v; $this->updatedAt = time(); return $this; }
 
@@ -237,6 +324,10 @@ class ServiceItem
             'service_category'      => $this->getServiceCategory()->value,
             'service_category_label' => $this->getServiceCategory()->label(),
             'duration_minutes'      => $this->durationMinutes,
+            'solo_duration_minutes' => $this->getSoloDurationMinutes(),
+            'additional_duration_minutes' => $this->effectiveAdditionalMinutes(),
+            'session_count'         => $this->sessionCount,
+            'catalog_category_uuid' => $this->catalogCategory?->getUuid(),
             'bookable'              => $this->bookable,
             'inventory_package_id'  => $this->inventoryPackageId,
             'consumables'           => array_map(

src/ClinicService/Entity/ServiceItemRelation.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace App\ClinicService\Entity;
+
+use App\ClinicService\Repository\ServiceItemRelationRepository;
+use App\Shared\Tenant\TenantOwnedTrait;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Uid\Uuid;
+
+/**
+ * رابطهٔ دو آیتم: «بیکینی با فول‌بادی جمع نمی‌شود» یا «الف پیش‌نیاز ب است».
+ *
+ * بند ۵ مستند این‌ها را از موتور قوانین جدا می‌کند: هر دو دربارهٔ **انتخاب** آیتم‌اند،
+ * نه دربارهٔ شرایط بیمار یا زمان، و باید پیش از هر محاسبه‌ای بررسی شوند.
+ */
+#[ORM\Entity(repositoryClass: ServiceItemRelationRepository::class)]
+#[ORM\Table(name: 'service_item_relations')]
+#[ORM\UniqueConstraint(name: 'uniq_relation_triple', columns: ['item_id', 'related_item_id', 'type'])]
+#[ORM\Index(columns: ['entity_type', 'entity_id'], name: 'idx_relation_tenant')]
+#[ORM\Index(columns: ['item_id', 'type'], name: 'idx_relation_item_type')]
+class ServiceItemRelation
+{
+    use TenantOwnedTrait;
+
+    public const TYPE_INCOMPATIBLE = 'incompatible_with';
+    public const TYPE_REQUIRES     = 'requires';
+
+    public const TYPES = [self::TYPE_INCOMPATIBLE, self::TYPE_REQUIRES];
+
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    private ?int $id = null;
+
+    #[ORM\Column(type: 'string', length: 36, unique: true)]
+    private string $uuid;
+
+    #[ORM\ManyToOne(targetEntity: ServiceItem::class)]
+    #[ORM\JoinColumn(name: 'item_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
+    private ServiceItem $item;
+
+    #[ORM\ManyToOne(targetEntity: ServiceItem::class)]
+    #[ORM\JoinColumn(name: 'related_item_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
+    private ServiceItem $relatedItem;
+
+    #[ORM\Column(type: 'string', length: 20)]
+    private string $type;
+
+    #[ORM\Column(name: 'created_at', type: 'integer')]
+    private int $createdAt;
+
+    public function __construct(ServiceItem $item, ServiceItem $relatedItem, string $type)
+    {
+        if (!in_array($type, self::TYPES, true)) {
+            throw new \InvalidArgumentException(sprintf('Unknown relation type "%s".', $type));
+        }
+
+        if ($item === $relatedItem) {
+            throw new \InvalidArgumentException('An item cannot relate to itself.');
+        }
+
+        $this->uuid        = Uuid::v4()->toRfc4122();
+        $this->item        = $item;
+        $this->relatedItem = $relatedItem;
+        $this->type        = $type;
+        $this->createdAt   = time();
+
+        $this->assignTenantPair($item->getSection()->getEntityType(), $item->getSection()->getEntityId());
+    }
+
+    public function getId(): ?int                 { return $this->id; }
+    public function getUuid(): string             { return $this->uuid; }
+    public function getItem(): ServiceItem        { return $this->item; }
+    public function getRelatedItem(): ServiceItem { return $this->relatedItem; }
+    public function getType(): string             { return $this->type; }
+
+    public function toArray(): array
+    {
+        return [
+            'uuid'              => $this->uuid,
+            'item_uuid'         => $this->item->getUuid(),
+            'related_item_uuid' => $this->relatedItem->getUuid(),
+            'related_item_name' => $this->relatedItem->getName(),
+            'type'              => $this->type,
+        ];
+    }
+}