feat(transport) : export XLSX répertoire + prix transporteur (ERP-162)

GET /api/carriers/export.xlsx (mêmes filtres que la liste : includeArchived, search, certificationType) et GET /api/carriers/{id}/prices/export.xlsx (tableau Prix regroupé Benne / Fond Mouvant). Controllers Symfony custom avec #[Route(priority: 1)] pour éviter le conflit API Platform {id}, génération déléguée au service Shared SpreadsheetExporterInterface.
2026-06-16 11:07:46 +02:00
parent 7d2812cea6
commit e688fe7e0b
4 changed files with 646 additions and 0 deletions
@@ -0,0 +1,158 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Transport\Infrastructure\Controller;
+
+use App\Module\Transport\Domain\Entity\Carrier;
+use App\Module\Transport\Domain\Repository\CarrierRepositoryInterface;
+use App\Shared\Domain\Contract\SpreadsheetExporterInterface;
+use DateTimeImmutable;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Attribute\AsController;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Security\Http\Attribute\IsGranted;
+
+/**
+ * Export XLSX du repertoire transporteurs (M4, spec-back § 4.6). Jumeau des
+ * controllers d'export SupplierExportController (M2) / ProviderExportController
+ * (M3) — references en prose volontairement (pas de {@see} : un import
+ * inter-module violerait la regle ABSOLUE n°1). Simplifie : pas de cloisonnement
+ * par site (§ 2.3) ni de colonne gatee par une permission comptable.
+ *
+ * Controller Symfony custom (et non operation API Platform) car il produit un
+ * binaire de fichier, pas une representation Hydra. `priority: 1` est OBLIGATOIRE
+ * sur la route : sans cela API Platform capterait `/api/carriers/export.xlsx`
+ * comme l'item `GET /api/carriers/{id}.{_format}` (id="export", _format="xlsx")
+ * — cf. CLAUDE.md « controller custom sous /api ».
+ *
+ * Separation des responsabilites :
+ *  - le COMMENT (generation du fichier) est delegue au service Shared
+ *    {@see SpreadsheetExporterInterface} — generique, reutilisable, sans metier ;
+ *  - le QUOI vit ICI : selection des transporteurs (MEMES filtres que
+ *    `GET /api/carriers`, via {@see CarrierRepositoryInterface::createListQueryBuilder()}
+ *    — l'export reflete exactement ce que l'utilisateur voit a l'ecran) et mapping
+ *    metier des colonnes.
+ */
+#[AsController]
+final class CarrierExportController
+{
+    public function __construct(
+        #[Autowire(service: 'App\Module\Transport\Infrastructure\Doctrine\DoctrineCarrierRepository')]
+        private readonly CarrierRepositoryInterface $repository,
+        private readonly SpreadsheetExporterInterface $exporter,
+    ) {}
+
+    #[Route('/api/carriers/export.xlsx', name: 'transport_carriers_export_xlsx', methods: ['GET'], priority: 1)]
+    #[IsGranted('transport.carriers.view')]
+    public function __invoke(Request $request): Response
+    {
+        // Memes filtres que la vue liste (CarrierProvider) pour que l'export
+        // reflete exactement ce que l'utilisateur voit a l'ecran :
+        //  - includeArchived : reintegre les archives en plus des actifs ;
+        //  - search          : recherche fuzzy sur le nom ;
+        //  - certificationType : filtre repetable (?certificationType[]=A&...).
+        $includeArchived    = $this->readBool($request->query->get('includeArchived'));
+        $search             = $request->query->getString('search') ?: null;
+        $certificationTypes = $this->readStringList($request->query->all()['certificationType'] ?? []);
+
+        /** @var list<Carrier> $carriers */
+        $carriers = $this->repository
+            ->createListQueryBuilder($includeArchived, $search, $certificationTypes)
+            ->getQuery()
+            ->getResult()
+        ;
+
+        $binary = $this->exporter->export(
+            'Répertoire transporteurs',
+            $this->buildHeaders(),
+            $this->buildRows($carriers),
+        );
+
+        return $this->buildResponse($binary);
+    }
+
+    /**
+     * Colonnes de l'export (spec § 4.6).
+     *
+     * @return list<string>
+     */
+    private function buildHeaders(): array
+    {
+        return [
+            'Nom',
+            'Certification',
+            'Statut QUALIMAT',
+            'Date de validité',
+            'Affrété',
+            'Volume m³',
+            'Date de création',
+        ];
+    }
+
+    /**
+     * @param list<Carrier> $carriers
+     *
+     * @return iterable<list<null|scalar>>
+     */
+    private function buildRows(array $carriers): iterable
+    {
+        foreach ($carriers as $carrier) {
+            // Statut / date de validite proviennent du referentiel QUALIMAT lie
+            // (RG-4.04), deja fetch-joine par le repository (anti N+1, § 2.11).
+            $qualimat = $carrier->getQualimatCarrier();
+
+            yield [
+                $carrier->getName(),
+                $carrier->getCertificationType() ?? '',
+                $qualimat?->getStatus() ?? '',
+                $qualimat?->getValidityDate()?->format('d/m/Y') ?? '',
+                $carrier->isChartered() ? 'Oui' : 'Non',
+                $carrier->getVolumeM3() ?? '',
+                $carrier->getCreatedAt()?->format('d/m/Y'),
+            ];
+        }
+    }
+
+    private function buildResponse(string $binary): Response
+    {
+        $filename = sprintf('repertoire-transporteurs-%s.xlsx', new DateTimeImmutable()->format('Ymd'));
+
+        $response = new Response($binary);
+        $response->headers->set('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+        $response->headers->set('Content-Disposition', sprintf('attachment; filename="%s"', $filename));
+
+        return $response;
+    }
+
+    /**
+     * Lit un flag booleen issu des query params. Accepte true / "true" / "1".
+     * Aligne sur CarrierProvider pour un comportement identique a la liste.
+     */
+    private function readBool(mixed $raw): bool
+    {
+        return is_string($raw) && in_array(strtolower($raw), ['true', '1'], true);
+    }
+
+    /**
+     * Normalise un filtre en liste de chaines (valeur unique ou liste).
+     * Aligne sur CarrierProvider pour un comportement identique a la liste.
+     *
+     * @return list<string>
+     */
+    private function readStringList(mixed $raw): array
+    {
+        $values = is_array($raw) ? $raw : [$raw];
+
+        $out = [];
+        foreach ($values as $value) {
+            if (is_string($value) && '' !== trim($value)) {
+                $out[] = trim($value);
+            }
+        }
+
+        return $out;
+    }
+}
@@ -0,0 +1,170 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Transport\Infrastructure\Controller;
+
+use App\Module\Transport\Domain\Entity\Carrier;
+use App\Module\Transport\Domain\Entity\CarrierPrice;
+use App\Module\Transport\Domain\Repository\CarrierRepositoryInterface;
+use App\Shared\Domain\Contract\SpreadsheetExporterInterface;
+use DateTimeImmutable;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Attribute\AsController;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Security\Http\Attribute\IsGranted;
+
+/**
+ * Export XLSX du tableau Prix d'un transporteur (M4, spec-back § 4.6 / spec-front
+ * § « Onglet Prix »). Reproduit le tableau de consultation regroupe par type de
+ * contenant (Fond Mouvant / Benne — colonnes du docx p.10).
+ *
+ * Controller Symfony custom (binaire de fichier, pas une representation Hydra).
+ * `priority: 1` est OBLIGATOIRE : sans cela API Platform capterait
+ * `/api/carriers/{id}/prices/export.xlsx` via ses routes generiques.
+ *
+ * Separation des responsabilites : le COMMENT (generation) est delegue au service
+ * Shared {@see SpreadsheetExporterInterface} ; le QUOI (chargement du transporteur,
+ * regroupement par contenant, mapping metier des colonnes) vit ICI.
+ *
+ * Adresses cross-module : les contrats Shared (ClientInterface / SupplierInterface
+ * / SiteInterface) exposent volontairement le minimum (regle ABSOLUE n°1). Faute
+ * d'acceder au detail postal d'une adresse Client/Fournisseur sans coupler au
+ * module Commercial, les colonnes d'adresse identifient le point par le libelle
+ * disponible : nom du site pour un Site, raison sociale du client/fournisseur pour
+ * une adresse de livraison/approvisionnement.
+ */
+#[AsController]
+final class CarrierPriceExportController
+{
+    /** Libelles d'affichage des enums (spec-front « Onglet Prix »). */
+    private const array CONTAINER_LABELS = ['BENNE' => 'Benne', 'FOND_MOUVANT' => 'Fond Mouvant'];
+
+    private const array PRICE_STATE_LABELS = [
+        'EN_COURS'   => 'En cours',
+        'VALIDE'     => 'Validé',
+        'NON_VALIDE' => 'Non validé',
+    ];
+
+    public function __construct(
+        #[Autowire(service: 'App\Module\Transport\Infrastructure\Doctrine\DoctrineCarrierRepository')]
+        private readonly CarrierRepositoryInterface $repository,
+        private readonly SpreadsheetExporterInterface $exporter,
+    ) {}
+
+    #[Route('/api/carriers/{id}/prices/export.xlsx', name: 'transport_carrier_prices_export_xlsx', requirements: ['id' => '\d+'], methods: ['GET'], priority: 1)]
+    #[IsGranted('transport.carriers.view')]
+    public function __invoke(int $id): Response
+    {
+        $carrier = $this->repository->findById($id);
+        // Soft-delete jamais expose (comme CarrierProvider::provideItem) : 404.
+        if (null === $carrier || null !== $carrier->getDeletedAt()) {
+            throw new NotFoundHttpException('Transporteur introuvable.');
+        }
+
+        $binary = $this->exporter->export(
+            'Prix transporteur',
+            $this->buildHeaders(),
+            $this->buildRows($carrier),
+        );
+
+        return $this->buildResponse($carrier, $binary);
+    }
+
+    /**
+     * Colonnes du tableau Prix regroupe (spec-front « Onglet Prix » / docx p.10).
+     *
+     * @return list<string>
+     */
+    private function buildHeaders(): array
+    {
+        return [
+            'Type de contenant',
+            'Transporteurs',
+            'Adresse APRO ou Adresse Sites',
+            'Adresse livraisons',
+            'Forfait €',
+            'Tonne €',
+            'Indexation',
+            'État du prix',
+        ];
+    }
+
+    /**
+     * Lignes regroupees par type de contenant (Fond Mouvant / Benne). On trie les
+     * prix par contenant puis position pour materialiser le regroupement.
+     *
+     * @return iterable<list<null|scalar>>
+     */
+    private function buildRows(Carrier $carrier): iterable
+    {
+        $prices = $carrier->getPrices()->toArray();
+        usort(
+            $prices,
+            static fn (CarrierPrice $a, CarrierPrice $b): int => [$a->getContainerType(), $a->getPosition()]
+                <=> [$b->getContainerType(), $b->getPosition()],
+        );
+
+        // Indexation : portee par le transporteur (RG-4.03), identique pour toutes
+        // ses lignes de prix. Vide si non renseigne (spec-front).
+        $indexation = $carrier->getIndexationRate() ?? '';
+
+        foreach ($prices as $price) {
+            $isForfait = 'FORFAIT' === $price->getPricingUnit();
+
+            yield [
+                self::CONTAINER_LABELS[$price->getContainerType()] ?? $price->getContainerType(),
+                $carrier->getName(),
+                $this->formatDeparture($price),
+                $this->formatDelivery($price),
+                $isForfait ? $price->getPrice() : '',
+                $isForfait ? '' : $price->getPrice(),
+                $indexation,
+                self::PRICE_STATE_LABELS[$price->getPriceState()] ?? $price->getPriceState(),
+            ];
+        }
+    }
+
+    /**
+     * Point de depart du prix (colonne « Adresse APRO ou Adresse Sites ») :
+     *  - branche CLIENT  : le site de depart (un des 3 sites 86/17/82) ;
+     *  - branche FOURNISSEUR : l'adresse d'approvisionnement, identifiee par la
+     *    raison sociale du fournisseur (cf. note de classe sur les contrats Shared).
+     */
+    private function formatDeparture(CarrierPrice $price): string
+    {
+        if ('CLIENT' === $price->getDirection()) {
+            return $price->getDepartureSite()?->getName() ?? '';
+        }
+
+        return $price->getSupplierSupplyAddress()?->getSupplier()?->getCompanyName() ?? '';
+    }
+
+    /**
+     * Point de livraison du prix (colonne « Adresse livraisons ») :
+     *  - branche CLIENT  : l'adresse de livraison, identifiee par la raison sociale
+     *    du client ;
+     *  - branche FOURNISSEUR : le site de livraison (un des 3 sites 86/17/82).
+     */
+    private function formatDelivery(CarrierPrice $price): string
+    {
+        if ('CLIENT' === $price->getDirection()) {
+            return $price->getClientDeliveryAddress()?->getClient()?->getCompanyName() ?? '';
+        }
+
+        return $price->getDeliverySite()?->getName() ?? '';
+    }
+
+    private function buildResponse(Carrier $carrier, string $binary): Response
+    {
+        $filename = sprintf('prix-transporteur-%d-%s.xlsx', (int) $carrier->getId(), new DateTimeImmutable()->format('Ymd'));
+
+        $response = new Response($binary);
+        $response->headers->set('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+        $response->headers->set('Content-Disposition', sprintf('attachment; filename="%s"', $filename));
+
+        return $response;
+    }
+}