feat: insurance & medical billing system (6 phases)

Multi-tenant insurance contracts, service coverage, versioned tariffs,
invoice calculation, and insurance claims with debt reporting.

- TenantInsurance: per-tenant insurance contracts (coverage/franchise/ceiling,
  versioning, soft-deactivate) + active guard
- ServiceItem.insuranceCovered + TenantServiceCoverage per-service overrides
- Tariff: versioned yearly tariffs with fallback to ServiceItem price
- Billing domain: Money/ShareBreakdown VOs, BillingCalculator (unit-tested),
  Invoice/InvoiceItem aggregate, InvoiceService.createFromSession
- Claim/ClaimItem with state machine (pending->submitted->approved/rejected->paid),
  ClaimService, insurance-debt report
- ClaimSubmitterInterface + ManualClaimSubmitter (future insurance API ready)
- Admin UI: insurance-pricing page, claims page, service tariff modal,
  service insurance toggle; routes + sidebar entries
- Architecture doc + billing/insurance/clinic-services API docs

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/ClinicService/Controller/ClinicServiceController.php

@@ -7,6 +7,8 @@ use App\ClinicService\Entity\ServiceItem;
 use App\ClinicService\Entity\ServiceSection;
 use App\ClinicService\Repository\ServiceItemRepository;
 use App\ClinicService\Repository\ServiceSectionRepository;
+use App\ClinicService\Repository\TariffRepository;
+use App\ClinicService\Service\TariffService;
 use App\Clinic\Repository\ClinicRepository;
 use App\Doctor\Repository\DoctorRepository;
 use App\Shared\Constant\ErrorCodes;
@@ -32,6 +34,8 @@ class ClinicServiceController extends BaseController
         private readonly SubscriptionService      $subscriptionService,
         private readonly DoctorRepository         $doctorRepo,
         private readonly ClinicRepository         $clinicRepo,
+        private readonly TariffRepository         $tariffRepo,
+        private readonly TariffService            $tariffService,
     ) {}
 
     // ── Service Sections ─────────────────────────────────────────────────────
@@ -157,6 +161,13 @@ class ClinicServiceController extends BaseController
             }
         }
 
+        if (isset($data['insurance_covered'])) {
+            $item->setInsuranceCovered((bool) $data['insurance_covered']);
+        }
+        if (array_key_exists('insurance_price_rials', $data)) {
+            $item->setInsurancePriceRials($data['insurance_price_rials'] !== null ? (int) $data['insurance_price_rials'] : null);
+        }
+
         $this->itemRepo->save($item);
 
         return $this->success($item->toArray(), 201);
@@ -181,6 +192,12 @@ class ClinicServiceController extends BaseController
             $staff = $data['staff_uuid'] ? $this->staffRepo->findByUuid($data['staff_uuid']) : null;
             $item->setStaff($staff);
         }
+        if (isset($data['insurance_covered'])) {
+            $item->setInsuranceCovered((bool) $data['insurance_covered']);
+        }
+        if (array_key_exists('insurance_price_rials', $data)) {
+            $item->setInsurancePriceRials($data['insurance_price_rials'] !== null ? (int) $data['insurance_price_rials'] : null);
+        }
 
         $this->itemRepo->save($item);
 
@@ -206,6 +223,51 @@ class ClinicServiceController extends BaseController
         return $this->success(['message' => 'سرویس حذف شد']);
     }
 
+    // ── Tariffs (تعرفه‌ی نسخه‌دار سالانه) ──────────────────────────────────────
+
+    #[Route('/api/v1/service-items/{uuid}/tariffs', methods: ['GET'])]
+    #[IsGranted('IS_AUTHENTICATED_FULLY')]
+    public function listTariffs(string $uuid, #[CurrentUser] User $user): JsonResponse
+    {
+        [$entityType, $entityId] = $this->resolveEntity($user);
+
+        $item = $this->itemRepo->findByUuid($uuid);
+        if ($item === null || !$this->ownsSection($item->getSection(), $entityType, $entityId)) {
+            return $this->error(ErrorCodes::ERR_SERVICE_NOT_FOUND, ErrorCodes::message(ErrorCodes::ERR_SERVICE_NOT_FOUND), 404);
+        }
+
+        $tariffs = $this->tariffRepo->findByService($item->getId());
+
+        return $this->success([
+            'current_year'        => $this->tariffService->currentJalaliYear(),
+            'default_price_rials' => $item->getPriceRials(),
+            'data'                => array_map(fn($t) => $t->toArray(), $tariffs),
+        ]);
+    }
+
+    #[Route('/api/v1/service-items/{uuid}/tariffs/{year}', methods: ['PUT'], requirements: ['year' => '\d+'])]
+    #[IsGranted('IS_AUTHENTICATED_FULLY')]
+    public function setTariff(string $uuid, int $year, Request $request, #[CurrentUser] User $user): JsonResponse
+    {
+        [$entityType, $entityId] = $this->resolveEntity($user);
+
+        $item = $this->itemRepo->findByUuid($uuid);
+        if ($item === null || !$this->ownsSection($item->getSection(), $entityType, $entityId)) {
+            return $this->error(ErrorCodes::ERR_SERVICE_NOT_FOUND, ErrorCodes::message(ErrorCodes::ERR_SERVICE_NOT_FOUND), 404);
+        }
+
+        if ($year < 1390 || $year > 1500) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, 'سال نامعتبر است', 422);
+        }
+
+        $data  = json_decode($request->getContent(), true) ?? [];
+        $price = (int) ($data['price_rials'] ?? 0);
+
+        $tariff = $this->tariffService->upsert($item->getId(), $year, $price);
+
+        return $this->success(['data' => $tariff->toArray()]);
+    }
+
     // ── Helpers ──────────────────────────────────────────────────────────────
 
     private function resolveEntity(User $user): array

src/ClinicService/Entity/ServiceItem.php

@@ -36,6 +36,12 @@ class ServiceItem
     #[ORM\Column(type: 'boolean')]
     private bool $active = true;
 
+    #[ORM\Column(name: 'insurance_covered', type: 'boolean')]
+    private bool $insuranceCovered = false;
+
+    #[ORM\Column(name: 'insurance_price_rials', type: 'integer', nullable: true)]
+    private ?int $insurancePriceRials = null;
+
     #[ORM\Column(name: 'created_at', type: 'integer')]
     private int $createdAt;
 
@@ -59,6 +65,8 @@ class ServiceItem
     public function getName(): string          { return $this->name; }
     public function getPriceRials(): int       { return $this->priceRials; }
     public function isActive(): bool           { return $this->active; }
+    public function isInsuranceCovered(): bool  { return $this->insuranceCovered; }
+    public function getInsurancePriceRials(): ?int { return $this->insurancePriceRials; }
     public function getCreatedAt(): int        { return $this->createdAt; }
     public function getUpdatedAt(): int        { return $this->updatedAt; }
 
@@ -66,6 +74,8 @@ class ServiceItem
     public function setName(string $name): self           { $this->name = $name; $this->updatedAt = time(); return $this; }
     public function setPriceRials(int $price): self       { $this->priceRials = $price; $this->updatedAt = time(); return $this; }
     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 setInsurancePriceRials(?int $v): self { $this->insurancePriceRials = $v; $this->updatedAt = time(); return $this; }
 
     public function toArray(): array
     {
@@ -77,6 +87,8 @@ class ServiceItem
             'name'         => $this->name,
             'price_rials'  => $this->priceRials,
             'active'       => $this->active,
+            'insurance_covered'     => $this->insuranceCovered,
+            'insurance_price_rials' => $this->insurancePriceRials,
             'created_at'   => $this->createdAt,
             'updated_at'   => $this->updatedAt,
         ];

src/ClinicService/Entity/Tariff.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace App\ClinicService\Entity;
+
+use App\ClinicService\Repository\TariffRepository;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Uid\Uuid;
+
+#[ORM\Entity(repositoryClass: TariffRepository::class)]
+#[ORM\Table(name: 'service_tariffs')]
+#[ORM\UniqueConstraint(name: 'uniq_service_tariff_year', columns: ['service_item_id', 'year'])]
+#[ORM\Index(columns: ['service_item_id', 'is_active'], name: 'idx_tariff_service_active')]
+class Tariff
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    private ?int $id = null;
+
+    #[ORM\Column(type: 'string', length: 36, unique: true)]
+    private string $uuid;
+
+    #[ORM\Column(name: 'service_item_id', type: 'integer')]
+    private int $serviceItemId;
+
+    #[ORM\Column(type: 'smallint')]
+    private int $year;
+
+    #[ORM\Column(name: 'price_rials', type: 'integer')]
+    private int $priceRials = 0;
+
+    #[ORM\Column(name: 'is_active', type: 'boolean')]
+    private bool $isActive = true;
+
+    #[ORM\Column(name: 'created_at', type: 'integer')]
+    private int $createdAt;
+
+    #[ORM\Column(name: 'updated_at', type: 'integer')]
+    private int $updatedAt;
+
+    public function __construct(int $serviceItemId, int $year, int $priceRials = 0)
+    {
+        $this->uuid          = Uuid::v4()->toRfc4122();
+        $this->serviceItemId = $serviceItemId;
+        $this->year          = $year;
+        $this->priceRials    = $priceRials;
+        $this->createdAt     = time();
+        $this->updatedAt     = time();
+    }
+
+    public function getId(): ?int           { return $this->id; }
+    public function getUuid(): string       { return $this->uuid; }
+    public function getServiceItemId(): int { return $this->serviceItemId; }
+    public function getYear(): int          { return $this->year; }
+    public function getPriceRials(): int    { return $this->priceRials; }
+    public function isActive(): bool        { return $this->isActive; }
+
+    public function setPriceRials(int $v): self { $this->priceRials = $v; $this->updatedAt = time(); return $this; }
+    public function setActive(bool $v): self    { $this->isActive = $v; $this->updatedAt = time(); return $this; }
+
+    public function toArray(): array
+    {
+        return [
+            'uuid'            => $this->uuid,
+            'service_item_id' => $this->serviceItemId,
+            'year'            => $this->year,
+            'price_rials'     => $this->priceRials,
+            'is_active'       => $this->isActive,
+        ];
+    }
+}

src/ClinicService/Repository/TariffRepository.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\ClinicService\Repository;
+
+use App\ClinicService\Entity\Tariff;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+class TariffRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, Tariff::class);
+    }
+
+    public function findForServiceYear(int $serviceItemId, int $year): ?Tariff
+    {
+        return $this->findOneBy([
+            'serviceItemId' => $serviceItemId,
+            'year'          => $year,
+            'isActive'      => true,
+        ]);
+    }
+
+    /** @return Tariff[] */
+    public function findByService(int $serviceItemId): array
+    {
+        return $this->createQueryBuilder('t')
+            ->where('t.serviceItemId = :sid')
+            ->setParameter('sid', $serviceItemId)
+            ->orderBy('t.year', 'DESC')
+            ->getQuery()
+            ->getResult();
+    }
+
+    public function findByUuid(string $uuid): ?Tariff
+    {
+        return $this->findOneBy(['uuid' => $uuid]);
+    }
+
+    public function save(Tariff $entity, bool $flush = true): void
+    {
+        $this->getEntityManager()->persist($entity);
+        if ($flush) {
+            $this->getEntityManager()->flush();
+        }
+    }
+}

src/ClinicService/Service/TariffService.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\ClinicService\Service;
+
+use App\ClinicService\Entity\ServiceItem;
+use App\ClinicService\Entity\Tariff;
+use App\ClinicService\Repository\TariffRepository;
+
+class TariffService
+{
+    public function __construct(
+        private readonly TariffRepository $tariffRepo,
+    ) {}
+
+    /**
+     * تعرفه‌ی یک خدمت برای یک سال شمسی.
+     * اگر تعرفه‌ی آن سال ثبت نشده باشد، به priceRials خود خدمت fallback می‌شود.
+     */
+    public function resolvePrice(ServiceItem $service, ?int $year = null): int
+    {
+        $year ??= $this->currentJalaliYear();
+
+        $tariff = $service->getId() !== null
+            ? $this->tariffRepo->findForServiceYear($service->getId(), $year)
+            : null;
+
+        return $tariff?->getPriceRials() ?? $service->getPriceRials();
+    }
+
+    public function upsert(int $serviceItemId, int $year, int $priceRials): Tariff
+    {
+        $tariff = $this->tariffRepo->findForServiceYear($serviceItemId, $year);
+        if ($tariff === null) {
+            $tariff = new Tariff($serviceItemId, $year, $priceRials);
+        } else {
+            $tariff->setPriceRials($priceRials)->setActive(true);
+        }
+        $this->tariffRepo->save($tariff);
+        return $tariff;
+    }
+
+    public function currentJalaliYear(): int
+    {
+        $fmt = new \IntlDateFormatter(
+            'en_US@calendar=persian',
+            \IntlDateFormatter::FULL,
+            \IntlDateFormatter::NONE,
+            'Asia/Tehran',
+            \IntlDateFormatter::TRADITIONAL,
+            'yyyy'
+        );
+        return (int) $fmt->format(time());
+    }
+}