feat: additional receipts as attachments to teamer invoices

addresses #869dv97u9

config/packages/oneup_uploader.yaml

@@ -36,6 +36,15 @@ oneup_uploader:
             namer: app.upload_namer
             storage:
                 directory: '%kernel.project_dir%/uploads/driver_license'
+        # Belege backing a Honorarnote. The directory has to be named exactly after
+        # Upload::TYPE_RECEIPT: UploadHandler::getUploadFilepath() interpolates the type into
+        # uploads/<type>/<shard>/<filename> rather than looking the mapping up.
+        receipt:
+            frontend: dropzone
+            use_orphanage: true
+            namer: app.upload_namer
+            storage:
+                directory: '%kernel.project_dir%/uploads/receipt'
     chunks:
         maxage: 86400
         storage:

src/Controller/Admin/System/Contact/CreateController.php

@@ -37,13 +37,13 @@ class CreateController extends AbstractController
             /** @var User $user */
             $user = $this->getUser();
 
-            $photo = Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_PHOTO);
+            $photo = Upload::fromUploadDto($uploadSession->getUploadsByType(Upload::TYPE_PHOTO)->first(), $user, Upload::TYPE_PHOTO);
             $contact->setPhoto($photo);
 
             $this->entityManager->flush();
 
             $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_PHOTO, $uploadSession);
-            $this->uploadHandler->destroyUploadSession();
+            $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_PHOTO);
         }
 
         $form = $this->createForm(ContactType::class, $contact, ['upload_session' => $uploadSession]);

src/Controller/Admin/System/Contact/EditController.php

@@ -34,14 +34,14 @@ class EditController extends AbstractController
         if (true === $request->isMethod('POST') && 0 < $uploadSession->getCount()) {
             /** @var User $user */
             $user = $this->getUser();
-            $photo = Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_PHOTO);
+            $photo = Upload::fromUploadDto($uploadSession->getUploadsByType(Upload::TYPE_PHOTO)->first(), $user, Upload::TYPE_PHOTO);
             if (null !== $existingPhoto = $contact->getPhoto()) {
                 $this->entityManager->remove($existingPhoto);
             }
             $contact->setPhoto($photo);
             $this->entityManager->flush();
             $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_PHOTO, $uploadSession);
-            $this->uploadHandler->destroyUploadSession();
+            $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_PHOTO);
         }
 
         $form = $this->createForm(ContactType::class, $contact, ['upload_session' => $uploadSession]);

src/Controller/Administrative/Disposition/DocumentUploadController.php

@@ -89,7 +89,7 @@ class DocumentUploadController extends AbstractController
         $uploadSession = $this->uploadHandler->getUploadSession();
 
         $upload = Upload::fromUploadDto(
-            $uploadSession->getUploads()->first(),
+            $uploadSession->getUploadsByType($type)->first(),
             $teamer->getUser(),
             $type
         );
@@ -113,7 +113,7 @@ class DocumentUploadController extends AbstractController
         $this->entityManager->flush();
 
         $this->uploadHandler->moveUploadSessionFilesFromOrphanage($type, $uploadSession);
-        $this->uploadHandler->destroyUploadSession();
+        $this->uploadHandler->removeUploadSessionUploadsByType($type);
 
         if (true === $this->featureManager->isActive('sanitize_uploads')) {
             $this->uploadHandler->ensurePdf($upload);

src/Controller/Administrative/Document/CheckController.php

@@ -94,6 +94,9 @@ class CheckController extends AbstractController
         return $this->render('administrative/document/modal_check.html.twig', [
             'document' => $document,
             'form' => $form->createView(),
+            'receipts' => Upload::TYPE_INVOICE === $document->getType()
+                ? $document->getDisposition()?->getDocumentsByType(Upload::TYPE_RECEIPT)
+                : null,
         ]);
     }
 
@@ -117,6 +120,25 @@ class CheckController extends AbstractController
         $this->entityManager->flush();
     }
 
+    private function removeReceipts(Upload $document): void
+    {
+        $receipts = $document->getDisposition()?->getDocumentsByType(Upload::TYPE_RECEIPT);
+
+        if (null === $receipts || 0 === $receipts->count()) {
+            return;
+        }
+
+        foreach ($receipts as $receipt) {
+            $this->entityManager->remove($receipt);
+        }
+
+        $this->logger->info('Delete receipts of accepted invoice', [
+            'document_id' => $document->getId(),
+            'disposition_id' => $document->getDisposition()->getId(),
+            'count' => $receipts->count(),
+        ]);
+    }
+
     private function confirmDocument(Upload $document, string $transition, string $status, DocumentCheckDto $formData): void
     {
         /** @var User $user */
@@ -147,6 +169,14 @@ class CheckController extends AbstractController
 
         if (true === $this->workflow->can($document->getDisposition(), $transition)) {
             $this->workflow->apply($document->getDisposition(), $transition);
+
+            // Belege only have to survive until the Honorarnote is accepted. Removing them here
+            // and not before the guard means a blocked confirmation - which still persists the
+            // new document status below - cannot destroy the evidence for an invoice that was in
+            // fact not approved. DeleteUploadListener removes the files from disk on preRemove.
+            if (Upload::TYPE_INVOICE === $document->getType() && Upload::STATUS_PAID === $status) {
+                $this->removeReceipts($document);
+            }
         } else {
             $blockers = $this->workflow->buildTransitionBlockerList($document->getDisposition(), $transition);
             foreach ($blockers as $blocker) {

src/Controller/Administrative/System/Document/ReplaceController.php

@@ -32,10 +32,10 @@ class ReplaceController extends AbstractController
         if (true === $request->isMethod('POST') && 0 < $uploadSession->getCount()) {
             /** @var User $user */
             $user = $this->getUser();
-            Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_DOCUMENT, $upload);
+            Upload::fromUploadDto($uploadSession->getUploadsByType(Upload::TYPE_DOCUMENT)->first(), $user, Upload::TYPE_DOCUMENT, $upload);
             $this->entityManager->flush();
             $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_DOCUMENT, $uploadSession);
-            $this->uploadHandler->destroyUploadSession();
+            $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_DOCUMENT);
         }
 
         $filenameBefore = $upload->getOriginalFilename();

src/Controller/Administrative/System/Document/UploadController.php

@@ -39,14 +39,14 @@ class UploadController extends AbstractController
         if (true === $request->isMethod('POST') && 0 < $uploadSession->getCount()) {
             /** @var User $user */
             $user = $this->getUser();
-            foreach ($uploadSession->getUploads() as $upload) {
+            foreach ($uploadSession->getUploadsByType(Upload::TYPE_DOCUMENT) as $upload) {
                 $document = Upload::fromUploadDto($upload, $user, Upload::TYPE_DOCUMENT);
                 $uploadedDocuments[] = $document;
                 $this->entityManager->persist($document);
             }
             $this->entityManager->flush();
             $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_DOCUMENT, $uploadSession);
-            $this->uploadHandler->destroyUploadSession();
+            $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_DOCUMENT);
         }
 
         if ($form->isSubmitted() && $form->isValid()) {

src/Controller/Teamer/Check/DriverLicenseController.php

@@ -133,13 +133,13 @@ class DriverLicenseController extends AbstractController
             $this->entityManager->remove($existingUpload);
         }
 
-        $upload = Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_DRIVER_LICENSE);
+        $upload = Upload::fromUploadDto($uploadSession->getUploadsByType(Upload::TYPE_DRIVER_LICENSE)->first(), $user, Upload::TYPE_DRIVER_LICENSE);
         $upload->setStatus(Upload::STATUS_NEW);
 
         $teamer->setDriverLicenseUpload($upload);
         $this->entityManager->flush();
 
         $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_DRIVER_LICENSE, $uploadSession);
-        $this->uploadHandler->destroyUploadSession();
+        $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_DRIVER_LICENSE);
     }
 }

src/Controller/Teamer/Disposition/DetailController.php

@@ -86,14 +86,18 @@ class DetailController extends AbstractController
         /** @var User $user */
         $user = $this->getUser();
 
-        $upload = Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_CONTRACT);
+        $upload = Upload::fromUploadDto(
+            $uploadSession->getUploadsByType(Upload::TYPE_CONTRACT)->first(),
+            $user,
+            Upload::TYPE_CONTRACT
+        );
         $upload->setStatus(Upload::STATUS_NEW);
 
         $disposition->addDocument($upload);
         $this->workflow->apply($disposition, 'upload_contract');
 
         $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_CONTRACT, $uploadSession);
-        $this->uploadHandler->destroyUploadSession();
+        $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_CONTRACT);
 
         if (true === $this->featureManager->isActive('sanitize_uploads')) {
             $this->uploadHandler->ensurePdf($upload);
@@ -119,14 +123,18 @@ class DetailController extends AbstractController
         /** @var User $user */
         $user = $this->getUser();
 
-        $upload = Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_INVOICE);
+        $upload = Upload::fromUploadDto(
+            $uploadSession->getUploadsByType(Upload::TYPE_INVOICE)->first(),
+            $user,
+            Upload::TYPE_INVOICE
+        );
         $upload->setStatus(Upload::STATUS_NEW);
 
         $disposition->addDocument($upload);
         $this->workflow->apply($disposition, 'upload_invoice');
 
         $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_INVOICE, $uploadSession);
-        $this->uploadHandler->destroyUploadSession();
+        $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_INVOICE);
 
         if (true === $this->featureManager->isActive('sanitize_uploads')) {
             $this->uploadHandler->ensurePdf($upload);

src/Controller/Teamer/Disposition/ReceiptController.php

@@ -0,0 +1,156 @@
+<?php
+
+namespace App\Controller\Teamer\Disposition;
+
+use App\Entity\Disposition;
+use App\Entity\Upload;
+use App\Entity\User;
+use App\Htmx\HxRedirectResponse;
+use App\Model\UploadDto;
+use App\Service\Upload\UploadHandler;
+use Doctrine\ORM\EntityManagerInterface;
+use Flagception\Manager\FeatureManagerInterface;
+use Psr\Log\LoggerInterface;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Security\Http\Attribute\IsGranted;
+
+/**
+ * Belege backing a Honorarnote.
+ *
+ * Deliberately separate from DetailController and from the disposition workflow: a receipt is
+ * evidence for the invoice, never a document in its own right. It is not approved or rejected, it
+ * carries no status, and it applies no transition - which is what lets a teamer keep managing
+ * receipts while the invoice is being checked, a phase in which the state machine offers no
+ * transition at all. The window is guarded by the MANAGE_RECEIPTS attribute on the disposition.
+ */
+class ReceiptController extends AbstractController
+{
+    public function __construct(
+        private readonly UploadHandler $uploadHandler,
+        private readonly EntityManagerInterface $entityManager,
+        private readonly LoggerInterface $logger,
+        private readonly FeatureManagerInterface $featureManager,
+    ) {
+    }
+
+    #[Route('/teamer/disposition/receipt/{uuid}', name: 'app_teamer_disposition_receipt_upload')]
+    #[IsGranted('ROLE_TEAMER')]
+    #[IsGranted('MANAGE_RECEIPTS', subject: 'disposition')]
+    public function upload(Disposition $disposition, Request $request): Response
+    {
+        // Dummy form without fields, as elsewhere: the files travel in the upload session, not in
+        // the form itself.
+        $form = $this->createFormBuilder()->getForm();
+        $form->handleRequest($request);
+
+        if ($form->isSubmitted() && $form->isValid()) {
+            $count = $this->processUpload($disposition);
+
+            $this->addFlash(
+                'success',
+                1 === $count ? 'Der Beleg wurde hochgeladen' : 'Die Belege wurden hochgeladen'
+            );
+
+            return new HxRedirectResponse($this->generateUrl('app_teamer_disposition_detail', [
+                'uuid' => $disposition->getUuid(),
+                'r' => $request->query->get('r'),
+            ]));
+        }
+
+        return $this->render('teamer/disposition/modal_receipt_upload.html.twig', [
+            'disposition' => $disposition,
+            'form' => $form->createView(),
+        ]);
+    }
+
+    #[Route('/teamer/disposition/receipt/delete/{uuid}', name: 'app_teamer_disposition_receipt_delete')]
+    #[IsGranted('ROLE_TEAMER')]
+    #[IsGranted('DELETE', subject: 'receipt')]
+    public function delete(Upload $receipt, Request $request): Response
+    {
+        if (Upload::TYPE_RECEIPT !== $receipt->getType()) {
+            throw $this->createNotFoundException('Not a receipt');
+        }
+
+        // UploadVoter::DELETE only asserts ownership, which would still hold once the invoice has
+        // been accepted. The window itself is the disposition's to answer.
+        $this->denyAccessUnlessGranted('MANAGE_RECEIPTS', $receipt->getDisposition());
+
+        if (true === $request->isMethod('POST')) {
+            $disposition = $receipt->getDisposition();
+
+            // Doctrine's DeleteUploadListener removes the file from disk on preRemove.
+            $this->entityManager->remove($receipt);
+            $this->entityManager->flush();
+
+            $this->addFlash('success', 'Der Beleg wurde gelöscht');
+            $this->logger->info('Delete receipt', [
+                'disposition_id' => $disposition->getId(),
+                'receipt_filename' => $receipt->getOriginalFilename(),
+                'owner' => $receipt->getOwner()->getFullName(),
+            ]);
+
+            return new HxRedirectResponse($this->generateUrl('app_teamer_disposition_detail', [
+                'uuid' => $disposition->getUuid(),
+                'r' => $request->query->get('r'),
+            ]));
+        }
+
+        return $this->render('teamer/disposition/modal_receipt_delete.html.twig', [
+            'receipt' => $receipt,
+        ]);
+    }
+
+    private function processUpload(Disposition $disposition): int
+    {
+        /** @var User $user */
+        $user = $this->getUser();
+
+        $uploadSession = $this->uploadHandler->getUploadSession();
+
+        // Only this dropzone's files: on the detail page in place "ended" the invoice dropzone is
+        // live at the same time and shares the one session.
+        $uploadDtos = $uploadSession->getUploadsByType(Upload::TYPE_RECEIPT);
+
+        $uploads = [];
+
+        /** @var UploadDto $uploadDto */
+        foreach ($uploadDtos as $uploadDto) {
+            $upload = Upload::fromUploadDto($uploadDto, $user, Upload::TYPE_RECEIPT);
+
+            // No status on purpose. UploadVoter grants CHECK only for "new" and "pending", so a
+            // null status is what keeps a receipt out of the checking process by construction.
+            $upload->setStatus(null);
+
+            $disposition->addDocument($upload);
+            $this->entityManager->persist($upload);
+
+            $uploads[] = $upload;
+        }
+
+        $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_RECEIPT, $uploadSession);
+        $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_RECEIPT);
+
+        if (true === $this->featureManager->isActive('sanitize_uploads')) {
+            foreach ($uploads as $upload) {
+                $this->uploadHandler->ensurePdf($upload);
+            }
+        }
+
+        $this->entityManager->flush();
+
+        $this->logger->info('Upload receipts', [
+            'user' => $user->getUserIdentifier(),
+            'disposition_id' => $disposition->getId(),
+            'count' => count($uploads),
+        ]);
+
+        // No DocumentUploadedEvent: its listener mails the managers about a document waiting to be
+        // checked, which is exactly what a receipt is not.
+
+        return count($uploads);
+    }
+}

src/Controller/Teamer/Profile/IndexController.php

@@ -96,11 +96,11 @@ class IndexController extends AbstractController
             $this->entityManager->remove($existingUpload);
         }
 
-        $upload = Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_PHOTO);
+        $upload = Upload::fromUploadDto($uploadSession->getUploadsByType(Upload::TYPE_PHOTO)->first(), $user, Upload::TYPE_PHOTO);
         $teamer->setPhoto($upload);
         $this->entityManager->flush();
         $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_PHOTO, $uploadSession);
-        $this->uploadHandler->destroyUploadSession();
+        $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_PHOTO);
 
         $this->addFlash('success', 'Dein Profilbild wurde aktualisiert');
         $this->logger->info('Update teamer photo', [

src/Controller/Teamer/Profile/License/AddController.php

@@ -73,11 +73,11 @@ class AddController extends AbstractController
 
     private function updateCertificate(User $user, License $license, UploadSessionDto $uploadSession): void
     {
-        $upload = Upload::fromUploadDto($uploadSession->getUploads()->first(), $user, Upload::TYPE_CERTIFICATE);
+        $upload = Upload::fromUploadDto($uploadSession->getUploadsByType(Upload::TYPE_CERTIFICATE)->first(), $user, Upload::TYPE_CERTIFICATE);
         $license->setCertificate($upload);
         $this->entityManager->flush();
         $this->uploadHandler->moveUploadSessionFilesFromOrphanage(Upload::TYPE_CERTIFICATE, $uploadSession);
-        $this->uploadHandler->destroyUploadSession();
+        $this->uploadHandler->removeUploadSessionUploadsByType(Upload::TYPE_CERTIFICATE);
 
         $this->addFlash('success', 'Der Nachweis wurde hochgeladen');
     }

src/Entity/Disposition.php

@@ -188,6 +188,20 @@ class Disposition implements BlameableEntityInterface, TimestampableEntityInterf
         return null;
     }
 
+    /**
+     * Unlike getDocumentByType() this returns every match, for the types a disposition can hold
+     * more than one of. Belege are the only such type today: there is exactly one Honorarvertrag
+     * and one Honorarnote, but any number of receipts backing the latter.
+     *
+     * @return Collection<int, Upload>
+     */
+    public function getDocumentsByType(string $type): Collection
+    {
+        return $this->documents->filter(function (Upload $upload) use ($type) {
+            return $type === $upload->getType();
+        });
+    }
+
     public function addDocument(Upload $document): static
     {
         if (!$this->documents->contains($document)) {

src/Entity/Upload.php

@@ -22,6 +22,7 @@ class Upload implements BlameableEntityInterface, TimestampableEntityInterface
     public const TYPE_INVOICE = 'invoice';
     public const TYPE_DOCUMENT = 'document';
     public const TYPE_DRIVER_LICENSE = 'driver_license';
+    public const TYPE_RECEIPT = 'receipt';
 
     public const STATUS_NEW = 'new';
     public const STATUS_PENDING = 'pending';
@@ -135,6 +136,7 @@ class Upload implements BlameableEntityInterface, TimestampableEntityInterface
             self::TYPE_INVOICE => 'Honorarnote',
             self::TYPE_DOCUMENT => 'Info',
             self::TYPE_DRIVER_LICENSE => 'Führerschein',
+            self::TYPE_RECEIPT => 'Beleg',
             default => 'Dokument',
         };
     }

src/EventListener/UploadSessionListener.php

@@ -25,12 +25,15 @@ class UploadSessionListener
         // Get original filename from Dropzone request
         $originalFileName = $request->request->get('originalFilename');
 
+        // The mapping name, which is 1:1 with the Upload::TYPE_* values. Without it the session
+        // is a flat list and a page with two dropzones cannot tell its own files apart.
         $upload = new UploadDto(
             $uuid,
             $uploadedFile->getFilename(),
             $originalFileName,
             $uploadedFile->getMimeType(),
-            $uploadedFile->getSize()
+            $uploadedFile->getSize(),
+            $event->getType()
         );
 
         $uploadSession = $this->uploadHandler->addUploadToSession($upload);

src/Model/UploadDto.php

@@ -4,13 +4,25 @@ namespace App\Model;
 
 class UploadDto
 {
+    /**
+     * The oneup_uploader mapping the file was uploaded through, which is 1:1 with the
+     * Upload::TYPE_* values. Deliberately not a promoted constructor property: the enclosing
+     * UploadSessionDto is serialized into the PHP session, and a promoted property carries no
+     * class-level default, so entries written before this field existed would deserialize
+     * uninitialized and throw on access. Nullable with a real default lets them come back as
+     * "unknown type", which matches no type and is therefore ignored.
+     */
+    private ?string $type = null;
+
     public function __construct(
         private readonly string $uuid,
         private readonly string $filename,
         private readonly string $originalFilename,
         private readonly string $mimeType,
         private readonly int $size,
+        ?string $type = null,
     ) {
+        $this->type = $type;
     }
 
     public function getUuid(): string
@@ -37,4 +49,9 @@ class UploadDto
     {
         return $this->size;
     }
+
+    public function getType(): ?string
+    {
+        return $this->type;
+    }
 }

src/Model/UploadSessionDto.php

@@ -52,6 +52,29 @@ class UploadSessionDto
         return $this->uploads;
     }
 
+    /**
+     * The uploads that came in through one oneup_uploader mapping. Two dropzones can be live on
+     * the same page (the Honorarnote and its Belege), and the session is one flat list, so a
+     * consumer must never take getUploads()->first() and hope.
+     *
+     * @return Collection<int, UploadDto>
+     */
+    public function getUploadsByType(string $type): Collection
+    {
+        return $this->uploads->filter(function (UploadDto $upload) use ($type) {
+            return $type === $upload->getType();
+        });
+    }
+
+    public function removeUploadsByType(string $type): static
+    {
+        foreach ($this->getUploadsByType($type) as $upload) {
+            $this->uploads->removeElement($upload);
+        }
+
+        return $this;
+    }
+
     public function flushUploads(): static
     {
         $this->uploads->clear();

src/Repository/UploadRepository.php

@@ -143,6 +143,15 @@ class UploadRepository extends ServiceEntityRepository
                 ->andWhere($qb->expr()->eq('upload.type', ':type'))
                 ->setParameter('type', $type)
             ;
+        } else {
+            // Belege are evidence for a Honorarnote, never checked in their own right - they have
+            // no status and are reachable from the check modal of their invoice. This is the only
+            // upload query that is not already scoped to a type, so it is the only one that would
+            // otherwise pad the list with them.
+            $qb
+                ->andWhere($qb->expr()->neq('upload.type', ':excludedType'))
+                ->setParameter('excludedType', Upload::TYPE_RECEIPT)
+            ;
         }
 
         if (null !== $dateFrom = $filterDto->getDateFrom()) {

src/Security/Voter/DispositionVoter.php

@@ -21,6 +21,7 @@ class DispositionVoter extends Voter
     public const INVOICE = 'INVOICE';
     public const FEEDBACK = 'FEEDBACK';
     public const CALL_OFF = 'CALL_OFF';
+    public const MANAGE_RECEIPTS = 'MANAGE_RECEIPTS';
 
     public function __construct(private readonly Security $security)
     {
@@ -42,6 +43,7 @@ class DispositionVoter extends Voter
             static::INVOICE,
             static::FEEDBACK,
             static::CALL_OFF,
+            static::MANAGE_RECEIPTS,
         ]);
     }
 
@@ -66,10 +68,42 @@ class DispositionVoter extends Voter
             static::ADMIN_DOCUMENT_UPLOAD => $this->assertAdminDocumentUploadAllowed($disposition),
             static::CALL_OFF => $this->security->isGranted('ROLE_ADMINISTRATIVE')
                 && Disposition::STATUS_CALLED_OFF !== $disposition->getStatus(),
+            static::MANAGE_RECEIPTS => $this->assertManageReceiptsAllowed($token, $disposition),
             default => false,
         };
     }
 
+    /**
+     * Whether Belege backing the Honorarnote may be added, listed or deleted.
+     *
+     * This is deliberately a permission and not a workflow transition. The disposition state
+     * machine offers upload_invoice only from "ended", so a teamer whose invoice is being checked
+     * has no transition available at all - which is precisely the phase in which receipts must
+     * stay manageable. Receipts also have to survive the ended -> checking_invoice -> ended
+     * bouncing that upload_invoice and reject_invoice cause, so the window is expressed as the two
+     * places themselves rather than as anything workflow_can() could answer. Do not "tidy" this
+     * into a workflow check.
+     *
+     * Once the invoice is accepted the disposition leaves for "completed" and the receipts are
+     * deleted (see Administrative\Document\CheckController), so the window closes on its own.
+     */
+    private function assertManageReceiptsAllowed(TokenInterface $token, Disposition $disposition): bool
+    {
+        if (true === $disposition->isSkipFormalities()) {
+            return false;
+        }
+
+        if (false === $this->security->isGranted('ROLE_ADMINISTRATIVE')
+            && false === $this->assertTeamerAccess($token, $disposition)) {
+            return false;
+        }
+
+        return in_array($disposition->getStatus(), [
+            Disposition::STATUS_ENDED,
+            Disposition::STATUS_CHECKING_INVOICE,
+        ], true);
+    }
+
     private function assertHouseManagerAccess(TokenInterface $token, Disposition $disposition): bool
     {
         if (false === $this->security->isGranted('ROLE_HOUSE_MANAGER')) {

src/Service/Upload/UploadHandler.php

@@ -23,7 +23,10 @@ class UploadHandler
         private readonly LoggerInterface $logger,
         private readonly string $projectDir,
         private readonly string $environment,
-        private readonly string $uploadReplacementFile,
+        // Bound from %env(default::UPLOAD_REPLACEMENT_FILE)%, whose empty fallback parameter
+        // resolves to null when the variable is not set at all - so "unset", "set to empty" and
+        // "absent" all have to mean the same thing here.
+        private readonly ?string $uploadReplacementFile,
     ) {
     }
 
@@ -65,6 +68,23 @@ class UploadHandler
         return $uploadSession;
     }
 
+    /**
+     * Drops the uploads of one mapping from the session and writes the trimmed DTO back, so a
+     * consumer clears only what it has just persisted. destroyUploadSession() below still exists
+     * for a full reset, but a page with two dropzones must not use it: it would throw away the
+     * files belonging to the other one.
+     */
+    public function removeUploadSessionUploadsByType(string $type): UploadSessionDto
+    {
+        $uploadSession = $this->getUploadSession();
+        $uploadSession->removeUploadsByType($type);
+
+        $session = $this->requestStack->getSession();
+        $session->set(self::SESSION_KEY, $uploadSession);
+
+        return $uploadSession;
+    }
+
     public function removeUploadFromSession(string $filename): UploadSessionDto
     {
         $uploadSession = $this->getUploadSession();
@@ -153,7 +173,9 @@ class UploadHandler
     {
         $originalPath = $this->getUploadFilepath($upload);
 
-        if ('' === $this->uploadReplacementFile || 'prod' === $this->environment) {
+        if (null === $this->uploadReplacementFile
+            || '' === $this->uploadReplacementFile
+            || 'prod' === $this->environment) {
             return $originalPath;
         }
 

templates/_partials/_receipts.html.twig

@@ -0,0 +1,47 @@
+{# Belege backing the Honorarnote. Rendered both while the invoice can still be uploaded and while
+   it is being checked - the window is MANAGE_RECEIPTS, not a workflow transition. Must not be
+   placed inside the invoice form: the triggers below are their own forms. #}
+{% set receipts = disposition.documentsByType('receipt') %}
+<div class="pt-8">
+    <h3 class="text-lg font-bold pb-2">
+        Belege
+    </h3>
+    <div class="text-sm pb-4">
+        Hast du Auslagen in deiner Honorarnote aufgeführt? Dann lade die zugehörigen Belege hier
+        hoch. Sie werden nach der Prüfung deiner Honorarnote automatisch gelöscht.
+    </div>
+    <ul class="list-disc pl-4 pb-4">
+        {% for receipt in receipts %}
+            <li>
+                <div class="flex items-center space-x-4">
+                    <span>{{ receipt }}</span>
+                    <a href="{{ path('app_common_download', { 'uuid': receipt.uuid, 'inline': true }) }}"
+                       target="_blank"
+                       title="Beleg öffnen">
+                        {{ icon('download', 'w-4 h-4') }}
+                    </a>
+                    <button type="button"
+                            class="text-red-500"
+                            title="Beleg löschen"
+                            hx-get="{{ path('app_teamer_disposition_receipt_delete', { 'uuid': receipt.uuid }) }}"
+                            hx-target="body"
+                            hx-swap="beforeend">
+                        {{ icon('delete', 'w-4 h-4') }}
+                    </button>
+                </div>
+            </li>
+        {% else %}
+            <li class="text-sm">
+                Du hast bisher keine Belege hochgeladen
+            </li>
+        {% endfor %}
+    </ul>
+    <button type="button"
+            class="btn"
+            title="Beleg hinzufügen"
+            hx-get="{{ path('app_teamer_disposition_receipt_upload', { 'uuid': disposition.uuid }) }}"
+            hx-target="body"
+            hx-swap="beforeend">
+        Belege hinzufügen
+    </button>
+</div>

templates/administrative/document/modal_check.html.twig

@@ -13,6 +13,26 @@
         </h2>
         {{ icon('eye') }}
     </a>
+    {# Belege backing this Honorarnote. Opened inline so the download route does not mark them
+       as downloaded - that marking is meant for the invoice itself. They are deleted as soon as
+       the invoice is accepted. #}
+    {% if receipts is not empty %}
+        <div class="pb-4">
+            <div class="font-bold pb-1">Belege</div>
+            <ul class="list-disc pl-4">
+                {% for receipt in receipts %}
+                    <li>
+                        <a href="{{ path('app_common_download', { 'uuid': receipt.uuid, 'inline': true }) }}"
+                           target="_blank"
+                           class="underline"
+                           title="Beleg öffnen">
+                            {{ receipt }}
+                        </a>
+                    </li>
+                {% endfor %}
+            </ul>
+        </div>
+    {% endif %}
     <div class="flex flex-col space-y-4 pb-4">
         {{ form_row(form.status) }}
         {% if form.specialAgreements is defined %}

templates/teamer/disposition/detail.html.twig

@@ -122,6 +122,11 @@
                         <twig:MessageBox message="{{ blocker.message }}"/>
                     {% endfor %}
                 {% endif %}
+
+                {# Outside the invoice form above - the receipt triggers are their own forms. #}
+                {% if is_granted('MANAGE_RECEIPTS', disposition) %}
+                    {% include '_partials/_receipts.html.twig' %}
+                {% endif %}
             {% endif %}
 
             {# Contract uploaded #}
@@ -189,6 +194,10 @@
                         </div>
                     {% endif %}
                 {% endif %}
+
+                {% if is_granted('MANAGE_RECEIPTS', disposition) %}
+                    {% include '_partials/_receipts.html.twig' %}
+                {% endif %}
             {% endif %}
 
             {# Invoice paid #}

templates/teamer/disposition/modal_receipt_delete.html.twig

@@ -0,0 +1,7 @@
+{% extends 'htmx_confirmation_modal.html.twig' %}
+
+{% block content %}
+    <div>
+        Möchtest du den Beleg <em>{{ receipt }}</em> wirklich löschen?
+    </div>
+{% endblock %}

templates/teamer/disposition/modal_receipt_upload.html.twig

@@ -0,0 +1,24 @@
+{% extends 'htmx_modal.html.twig' %}
+
+{% block title %}Belege hochladen{% endblock %}
+
+{% block content %}
+    {% set formAttr = stimulus_controller('form-upload-guard')|stimulus_action('form-upload-guard', 'guard', 'submit') %}
+    {{ form_start(form, { 'attr': { 'hx-post': app.request.uri, 'hx-target': '#htmx-modal', 'hx-swap': 'outerHTML' }|merge(formAttr.toArray()) }) }}
+    <div class="pb-4">
+        Lade hier die Belege zu den Auslagen hoch, die du in deiner Honorarnote aufführst.
+    </div>
+    <div class="pb-4">
+        {% include '_partials/_upload_collection_form.html.twig' with {
+            'endpoint_upload': path('_uploader_upload_receipt'),
+            'max_filesize': 5,
+            'max_files': 10,
+            'accepted_files': 'image/jpg,image/jpeg,application/pdf',
+        } %}
+    </div>
+    <button type="submit" class="btn" {{ stimulus_target('form-upload-guard', 'submit') }}>
+        Belege speichern
+    </button>
+    {{ form_rest(form) }}
+    {{ form_end(form) }}
+{% endblock %}

tests/Entity/DispositionTest.php

@@ -146,6 +146,45 @@ class DispositionTest extends TestCase
         $this->assertFalse($disposition->isContractRejected());
     }
 
+    /**
+     * getDocumentByType() answers with the first match and is right for the Honorarvertrag and the
+     * Honorarnote, of which there is one each. Belege are the first type a disposition can hold
+     * several of, so they need the collection-returning sibling.
+     */
+    public function testTheReceiptsOfADispositionAreReturnedAsACollection(): void
+    {
+        $disposition = $this->createDisposition(createdAt: 'today', assignmentEndsIn: '-1 day');
+
+        $disposition
+            ->addDocument((new Upload())->setType(Upload::TYPE_INVOICE))
+            ->addDocument((new Upload())->setType(Upload::TYPE_RECEIPT)->setOriginalFilename('bahn.pdf'))
+            ->addDocument((new Upload())->setType(Upload::TYPE_CONTRACT))
+            ->addDocument((new Upload())->setType(Upload::TYPE_RECEIPT)->setOriginalFilename('taxi.jpg'))
+        ;
+
+        $receipts = $disposition->getDocumentsByType(Upload::TYPE_RECEIPT);
+
+        $this->assertCount(2, $receipts);
+        $this->assertSame(
+            ['bahn.pdf', 'taxi.jpg'],
+            array_values(array_map(
+                fn (Upload $upload): string => $upload->getOriginalFilename(),
+                $receipts->toArray()
+            ))
+        );
+
+        // The single-result sibling keeps working for the types that only ever have one.
+        $this->assertSame(Upload::TYPE_INVOICE, $disposition->getDocumentByType(Upload::TYPE_INVOICE)?->getType());
+    }
+
+    public function testADispositionWithoutReceiptsReturnsAnEmptyCollection(): void
+    {
+        $disposition = $this->createDisposition(createdAt: 'today', assignmentEndsIn: '-1 day');
+        $disposition->addDocument((new Upload())->setType(Upload::TYPE_INVOICE));
+
+        $this->assertCount(0, $disposition->getDocumentsByType(Upload::TYPE_RECEIPT));
+    }
+
     private function createDisposition(
         string $createdAt,
         string $assignmentEndsIn,

tests/Model/UploadSessionDtoTest.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Model;
+
+use App\Entity\Upload;
+use App\Model\UploadDto;
+use App\Model\UploadSessionDto;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * The upload session is one flat list shared by every dropzone on a page, and the teamer's
+ * disposition detail page has two of them at once: the Honorarnote and its Belege. Before the
+ * uploads carried their mapping, a consumer could only take getUploads()->first() - so submitting
+ * the invoice form could persist a receipt as the Honorarnote. That is what these pin down.
+ */
+class UploadSessionDtoTest extends TestCase
+{
+    public function testUploadsAreSelectedByTheMappingTheyCameFrom(): void
+    {
+        $session = $this->createSession();
+
+        $this->assertSame(
+            ['honorarnote.pdf'],
+            $this->filenames($session->getUploadsByType(Upload::TYPE_INVOICE))
+        );
+        $this->assertSame(
+            ['bahn.pdf', 'taxi.jpg'],
+            $this->filenames($session->getUploadsByType(Upload::TYPE_RECEIPT))
+        );
+    }
+
+    public function testRemovingOneMappingLeavesTheOtherAlone(): void
+    {
+        $session = $this->createSession();
+
+        $session->removeUploadsByType(Upload::TYPE_RECEIPT);
+
+        $this->assertCount(0, $session->getUploadsByType(Upload::TYPE_RECEIPT));
+        $this->assertSame(['honorarnote.pdf'], $this->filenames($session->getUploadsByType(Upload::TYPE_INVOICE)));
+    }
+
+    /**
+     * A session written before UploadDto carried a type deserializes with a null one. Such an
+     * entry must match no mapping at all rather than being claimed by the first consumer to ask -
+     * that would be the very ambiguity the type removes.
+     */
+    public function testAnUploadWithoutAMappingMatchesNothing(): void
+    {
+        $session = new UploadSessionDto();
+        $session->addUpload(new UploadDto('uuid-legacy', 'legacy.pdf', 'legacy.pdf', 'application/pdf', 1));
+
+        $this->assertCount(0, $session->getUploadsByType(Upload::TYPE_INVOICE));
+        $this->assertCount(0, $session->getUploadsByType(Upload::TYPE_RECEIPT));
+        $this->assertCount(1, $session->getUploads());
+    }
+
+    private function createSession(): UploadSessionDto
+    {
+        $session = new UploadSessionDto();
+
+        $session
+            ->addUpload($this->createUpload('uuid-1', 'honorarnote.pdf', Upload::TYPE_INVOICE))
+            ->addUpload($this->createUpload('uuid-2', 'bahn.pdf', Upload::TYPE_RECEIPT))
+            ->addUpload($this->createUpload('uuid-3', 'taxi.jpg', Upload::TYPE_RECEIPT))
+        ;
+
+        return $session;
+    }
+
+    private function createUpload(string $uuid, string $filename, string $type): UploadDto
+    {
+        return new UploadDto($uuid, $filename, $filename, 'application/pdf', 1024, $type);
+    }
+
+    /**
+     * @param \Doctrine\Common\Collections\Collection<int, UploadDto> $uploads
+     *
+     * @return array<int, string>
+     */
+    private function filenames(iterable $uploads): array
+    {
+        $filenames = [];
+
+        foreach ($uploads as $upload) {
+            $filenames[] = $upload->getFilename();
+        }
+
+        return $filenames;
+    }
+}

tests/Security/Voter/DispositionVoterTest.php

@@ -8,6 +8,7 @@ use App\Entity\Application;
 use App\Entity\Assignment;
 use App\Entity\Disposition;
 use App\Entity\Teamer;
+use App\Entity\User;
 use App\Security\Voter\DispositionVoter;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
@@ -85,6 +86,98 @@ class DispositionVoterTest extends TestCase
         $this->assertSame(VoterInterface::ACCESS_GRANTED, $this->vote(DispositionVoter::CALL_OFF, $disposition));
     }
 
+    /**
+     * The receipt window is the one permission in this voter that is not derived from a workflow
+     * transition, because there is none to derive it from: while the Honorarnote is being checked
+     * the state machine offers nothing at all, and that is exactly when receipts must stay
+     * manageable.
+     *
+     * @dataProvider receiptWindowStatuses
+     */
+    public function testTheReceiptWindowIsTheTwoInvoiceStates(string $status, bool $expected): void
+    {
+        $this->security->method('isGranted')->willReturn(true);
+
+        $disposition = $this->createDisposition(skipFormalities: false)->setStatus($status);
+
+        $this->assertSame(
+            $expected ? VoterInterface::ACCESS_GRANTED : VoterInterface::ACCESS_DENIED,
+            $this->vote(DispositionVoter::MANAGE_RECEIPTS, $disposition),
+        );
+    }
+
+    /**
+     * @return array<string, array{string, bool}>
+     */
+    public static function receiptWindowStatuses(): array
+    {
+        return [
+            'invoice may still be uploaded' => [Disposition::STATUS_ENDED, true],
+            'invoice is being checked' => [Disposition::STATUS_CHECKING_INVOICE, true],
+            'nothing has happened yet' => [Disposition::STATUS_NEW, false],
+            'contract is being checked' => [Disposition::STATUS_CHECKING_CONTRACT, false],
+            'assignment is still ahead' => [Disposition::STATUS_CONFIRMED, false],
+            'invoice was accepted' => [Disposition::STATUS_COMPLETED, false],
+            'placement was cancelled' => [Disposition::STATUS_CALLED_OFF, false],
+        ];
+    }
+
+    public function testReceiptsAreDeniedOnASkipFormalitiesAssignment(): void
+    {
+        $this->security->method('isGranted')->willReturn(true);
+
+        $disposition = $this
+            ->createDisposition(skipFormalities: true)
+            ->setStatus(Disposition::STATUS_CHECKING_INVOICE)
+        ;
+
+        $this->assertSame(
+            VoterInterface::ACCESS_DENIED,
+            $this->vote(DispositionVoter::MANAGE_RECEIPTS, $disposition),
+        );
+    }
+
+    /**
+     * The owning teamer gets in without being administrative; anyone else's teamer does not.
+     *
+     * @dataProvider receiptOwnership
+     */
+    public function testOnlyTheOwningTeamerMayManageTheirReceipts(bool $owning, bool $expected): void
+    {
+        $this->security
+            ->method('isGranted')
+            ->willReturnCallback(fn (string $role): bool => 'ROLE_TEAMER' === $role)
+        ;
+
+        $teamer = new Teamer();
+        $assignment = (new Assignment())->setSkipFormalities(false);
+
+        $disposition = (new Disposition(new Application($assignment, $teamer)))
+            ->setStatus(Disposition::STATUS_CHECKING_INVOICE)
+        ;
+
+        $user = (new User())->setTeamer($owning ? $teamer : new Teamer());
+
+        $token = $this->createMock(TokenInterface::class);
+        $token->method('getUser')->willReturn($user);
+
+        $this->assertSame(
+            $expected ? VoterInterface::ACCESS_GRANTED : VoterInterface::ACCESS_DENIED,
+            (new DispositionVoter($this->security))->vote($token, $disposition, [DispositionVoter::MANAGE_RECEIPTS]),
+        );
+    }
+
+    /**
+     * @return array<string, array{bool, bool}>
+     */
+    public static function receiptOwnership(): array
+    {
+        return [
+            'their own placement' => [true, true],
+            'somebody else\'s placement' => [false, false],
+        ];
+    }
+
     private function vote(string $attribute, Disposition $disposition): int
     {
         return (new DispositionVoter($this->security))->vote(

translations/messages.de.yaml

@@ -20,6 +20,7 @@ label:
       certificate: Lizenznachweis
       photo: Foto
       driver_license: Führerschein
+      receipt: Beleg
     status:
       new: neu
       pending: in Bearbeitung