# Feature: Dokumenten-Upload über die API

Als API-Client möchte ich Dokumente (PDF, JPG, PNG, HEIC) hochladen,
damit sie automatisch verarbeitet, durchsuchbar gemacht und abgelegt werden.

```gherkin
Funktionalität: Dokumenten-Upload über die API

  Szenario: Erfolgreicher PDF-Upload
    Angenommen ein gültiger API-Token
    Wenn ein PDF per POST /v1/documents (multipart, Feld "file") hochgeladen wird
    Dann antwortet das System mit 202 und einer neuen Dokument-UUID
    Und das Dokument hat den Status "received"
    Und die Datei liegt unter data/staging/{uuid}.pdf
    Und ein Event "DocumentReceived" mit origin "api" wurde aufgezeichnet

  Szenario: Upload eines Bildes
    Angenommen ein gültiger API-Token
    Wenn eine JPG-, PNG- oder HEIC-Datei hochgeladen wird
    Dann antwortet das System mit 202
    Und der media_type des Dokuments entspricht dem Dateityp

  Szenario: Duplikat-Upload wird abgelehnt
    Angenommen ein bereits importiertes Dokument mit bekanntem SHA-256-Hash
    Wenn eine byte-identische Datei erneut hochgeladen wird
    Dann antwortet das System mit 409
    Und die Antwort enthält error.code "duplicate_document" und die existing_document_id
    Und es wurde kein neues Aggregat angelegt

  Szenario: Upload ohne Token wird abgelehnt
    Angenommen kein oder ein falscher API-Token
    Wenn ein Dokument hochgeladen wird
    Dann antwortet das System mit 401

  Szenario: Nicht unterstützter Dateityp wird abgelehnt
    Angenommen ein gültiger API-Token
    Wenn eine Datei mit nicht unterstützter Endung (z.B. .docx) hochgeladen wird
    Dann antwortet das System mit 422 und error.code "unsupported_media_type"

  Szenario: Upload über dem Größenlimit wird abgelehnt
    Angenommen ein konfiguriertes Upload-Limit von 100 MB
    Wenn eine größere Datei hochgeladen wird
    Dann antwortet das System mit 413
    Und es verbleibt keine .part-Datei im Staging
```

## Traceability

| Szenario | Go-Test (Paket `internal/api`, `internal/ingest`) |
|---|---|
| Erfolgreicher PDF-Upload | `TestUpload_PDFReturns202AndReceived` |
| Upload eines Bildes | `TestUpload_ImageSetsMediaType` |
| Duplikat-Upload wird abgelehnt | `TestUpload_DuplicateReturns409` |
| Upload ohne Token wird abgelehnt | `TestUpload_MissingTokenReturns401` |
| Nicht unterstützter Dateityp wird abgelehnt | `TestUpload_UnsupportedTypeReturns422` |
| Upload über dem Größenlimit wird abgelehnt | `TestUpload_TooLargeReturns413AndCleansUp` |