2.0.0 Production-RC

docs/BULK-API.md

@@ -0,0 +1,103 @@
+# Bulk API
+
+Der Bulk-Dienst ist für Publisher, CMS-Integrationen, Agenturen und andere Server-to-Server-Workflows gedacht.
+
+## Capability
+
+Die Runtime-Lizenz benötigt:
+
+```text
+bulk_api
+```
+
+Optional kann die Lizenzplattform ein Limit liefern:
+
+```text
+bulk_items=250
+```
+
+Der effektive Grenzwert ist der kleinere Wert aus Lizenzlimit und `BULK_MAX_ITEMS`.
+
+## Dedizierter Container
+
+`Dockerfile.bulk` verwendet dasselbe getestete Go-Binary, setzt aber sichere Betriebsdefaults:
+
+```text
+SERVICE_MODE=bulk
+REQUIRE_LICENSE=true
+BULK_REQUIRE_API_KEY=true
+API_ALLOWED_ORIGIN=
+```
+
+Damit enthält die Angriffsoberfläche keine Generator-, Produkt- oder Hintergrundseite.
+
+## Authentifizierung
+
+Bei aktivierter API-Key-Pflicht:
+
+```http
+Authorization: Bearer <key>
+```
+
+oder:
+
+```http
+X-API-Key: <key>
+```
+
+Der Schlüssel kann über `BULK_API_KEY_FILE` aus einem Container-/Kubernetes-Secret gelesen werden.
+
+## Anfrage
+
+```http
+POST /v1/bulk/declarations
+Content-Type: application/json
+Authorization: Bearer ...
+```
+
+```json
+{
+  "items": [
+    {
+      "id": "post-1001",
+      "parameters": {
+        "mode": "article",
+        "lang": "de",
+        "textExtent": "none",
+        "textReview": "none",
+        "coverImageExtent": "full",
+        "coverImageReview": "editorial",
+        "researchExtent": "assisted",
+        "researchReview": "expert",
+        "assurance": "technicallyRecorded"
+      }
+    }
+  ]
+}
+```
+
+Jedes Element wird unabhängig verarbeitet. Ein fachlich fehlerhaftes Element führt zu einem Item-Fehler, ohne die übrigen Elemente zu verwerfen.
+
+## Betriebsgrenzen
+
+- `BULK_MAX_ITEMS` begrenzt Items pro Request;
+- `BULK_MAX_BODY_BYTES` begrenzt die Requestgröße;
+- ein Lizenzlimit `bulk_items` kann die Itemzahl weiter reduzieren;
+- der Dedicated Container wird ohne gültige `bulk_api`-Capability nicht ready;
+- bei `REQUIRE_LICENSE=true` werden fachliche Requests ohne gültige Runtime-Lizenz mit 503 blockiert;
+- Prometheus exportiert Bulk-Request-, Item- und Failure-Counter.
+
+## Netzwerk
+
+Der Bulk-Service sollte standardmäßig intern betrieben werden. Die Kubernetes-Vorlage liefert nur einen `ClusterIP`-Service und bewusst keinen Ingress. Bei externer Veröffentlichung empfiehlt sich zusätzlich ein API-Gateway mit TLS, Rate-Limiting und organisationsspezifischer Authentifizierung.
+
+## Getrennte Runtime- und Ausgabe-URL
+
+Bei einer separaten Bulk-Instanz kann `BASE_URL` die interne bzw. lizenzgebundene Adresse des Bulk-Dienstes sein, während `OUTPUT_BASE_URL` auf die öffentliche Full-/API-Instanz zeigt:
+
+```env
+BASE_URL=http://ai-disclosure-bulk
+OUTPUT_BASE_URL=https://ai.example.org
+```
+
+Dadurch enthalten Bulk-Ergebnisse nutzbare öffentliche Deklarations-, Manifest- und Badge-URLs.