# Kontingent für Testsysteme

Testsysteme können ein monatliches Dokumentenlimit erhalten. Ist das Limit erreicht, nimmt SQUEEZE neue Dokumente zwar noch an, verarbeitet sie aber nicht weiter.

Die Funktion ist **opt-in**: Ohne den entsprechenden Konfigurationsschlüssel gilt kein Limit und die Verarbeitung läuft unbegrenzt. Ist der Schlüssel gesetzt, gilt das System als Testsystem.

## Einrichtung

Das Limit wird über den Konfigurationsschlüssel `quota.trialMode.monthlyDocumentLimit` gesetzt.

Der Schlüssel kann an zwei Stellen stehen:

- **Server-Konfiguration** (`server.json`) – gilt für alle Mandanten der Instanz.
- **Mandanten-Konfiguration** (`clients/<mandant>.json`) – gilt nur für diesen Mandanten und **überschreibt** den Serverwert.

### Beispiel

```json
{
  "quota": {
    "trialMode": {
      "monthlyDocumentLimit": 150
    }
  }
}
```

Die Vorgabe für Testsysteme liegt bei **150 Dokumenten pro Mandant und Monat**.

### Gültige Werte

<table id="bkmrk-wert-wirkung-schl%C3%BCss"><thead><tr><th>Wert</th><th>Wirkung</th></tr></thead><tbody><tr><td>Schlüssel fehlt</td><td>Kein Limit, unbegrenzte Verarbeitung</td></tr><tr><td>Ganzzahl ab 1</td><td>Monatslimit in Dokumenten</td></tr><tr><td>`0`</td><td>Jedes neue Dokument wird blockiert</td></tr><tr><td>Nicht-numerischer Wert, z. B. `"abc"`</td><td>Wird wie „kein Limit" behandelt, im Log erscheint eine Warnung</td></tr></tbody></table>

> **Hinweis:** Ein Tippfehler im Wert stoppt nie versehentlich die Verarbeitung – er führt still dazu, dass *kein* Limit greift. Nach dem Setzen der Konfiguration daher immer über den Endpunkt unter [Aktuellen Verbrauch abfragen](#bkmrk-aktuellen-verbrauch-) gegenprüfen, ob das Limit tatsächlich aktiv ist.

## Funktionsweise

### Was gezählt wird

Gezählt werden **Dokumente, nicht Seiten**. Es findet bewusst keine Umrechnung von Seiten in Belege statt – ein Dokument mit 60 Seiten zählt genauso wie ein Dokument mit einer Seite.

### Wann gezählt wird

Ein Dokument zählt, **sobald es im Init-Step angenommen wird** – nicht erst bei der Validierung oder beim Export. Dadurch greift das Limit auch dann zuverlässig, wenn auf einen Schlag sehr viele Dokumente hochgeladen werden.

### Wann ein Platz wieder frei wird

- Schlägt ein Dokument fehl – technischer Fehler oder Validierungsfehler, zum Beispiel ein leeres Pflichtfeld –, gibt es seinen Platz wieder frei und zählt nicht mehr.
- Wird ein Dokument per Barcode getrennt, gibt das Ausgangsdokument seinen Platz frei. Gezählt werden stattdessen die entstandenen Teildokumente.

### Erneute Verarbeitung

- Ein bereits gezähltes Dokument verbraucht bei erneuter Verarbeitung **keinen weiteren Platz** – auch nicht in einem späteren Monat.
- Ein zuvor fehlgeschlagenes Dokument benötigt beim erneuten Durchlauf wieder einen freien Platz im aktuellen Monat.

### Monatlicher Reset

Der Zähler läuft pro Kalendermonat und beginnt am 1. des Monats wieder bei 0.

### Verhalten beim System-Reset

Ein System-Reset über die Administration löscht zwar alle Dokumente, setzt den Verbrauchszähler aber **nicht** zurück. Ein Reset verschafft dem Testsystem also kein neues Kontingent.

## Verhalten bei erreichtem Limit

<table id="bkmrk-situation-verhalten-"><thead><tr><th>Situation</th><th>Verhalten</th></tr></thead><tbody><tr><td>Neues Dokument wird hochgeladen</td><td>Wird angenommen, bleibt aber im Step `Init` mit Status `Fehler` stehen</td></tr><tr><td>Bereits gezähltes Dokument erneut verarbeiten</td><td>Läuft normal weiter</td></tr><tr><td>Fehlgeschlagenes Dokument per Requeue erneut verarbeiten</td><td>Bleibt mit dem Limit-Fehler stehen</td></tr><tr><td>In der Validierungsmaske manuell validieren und exportieren</td><td>Das Dokument wird gespeichert, der Export wird mit HTTP 403 abgelehnt</td></tr></tbody></table>

In allen Fällen lautet der Fehlertext:

```
License limit (test system) reached | no further processing possible
```

Liegengebliebene Dokumente gehen nicht verloren. Nach dem Monatswechsel oder nach Erhöhen des Limits können sie erneut in die Verarbeitung geschickt werden.

## Aktuellen Verbrauch abfragen

Das eingestellte Kontingent und der aktuelle Verbrauch lassen sich über die API abfragen:

```
GET /api/v2/system/quota
```

Der Aufruf ist authentifiziert, Administrationsrechte sind nicht erforderlich.

**Antwort mit konfiguriertem Limit:**

```json
{
  "quota": { "trialMode": { "monthlyDocumentLimit": 150 } },
  "currentDocumentCount": 30,
  "percentageUsed": 20.0
}
```

**Antwort ohne konfiguriertes Limit:**

```json
{
  "quota": { "trialMode": null },
  "currentDocumentCount": null,
  "percentageUsed": null
}
```

Hinweise zu `percentageUsed`:

- Der Wert wird nicht bei 100 gedeckelt und kann über 100 liegen.
- Ist das Limit auf `0` gesetzt, beträgt der Wert immer `100.0`.

## Anzeige in der Oberfläche

> Stand Release 2.37 – die Darstellung in der Oberfläche wird mit der UI-Umsetzung der Funktion ausgeliefert.

- **Administration → System:** Fortschrittsbalken mit dem aktuellen Verbrauch im Verhältnis zum Kontingent.
- **Dashboard:** Ab 70 % Auslastung erscheint über der Validierungskachel eine Hinweiskachel mit Text und aktuellem Kontingent.
- **Eingebetteter Viewer:** Ab 70 % Auslastung erscheint eine nicht schließbare Warnung mit Text und aktuellem Kontingent.

Farbstufen der Hinweise:

<table id="bkmrk-auslastung-darstellu"><thead><tr><th>Auslastung</th><th>Darstellung</th></tr></thead><tbody><tr><td>ab 70 %</td><td>gelb</td></tr><tr><td>ab 90 %</td><td>rot</td></tr><tr><td>ab 100 %</td><td>dunkelrot, geänderter Text</td></tr></tbody></table>

Die Schwellenwerte betreffen ausschließlich die Anzeige. Die Verarbeitungssperre greift erst bei 100 %.

## Abgrenzung und Ausblick

- Die hier beschriebene Einstellung gilt nur für Testsysteme.
- Ein allgemeines Kontingent für Produktivsysteme – mit wählbarem Intervall (monatlich oder jährlich), Startdatum und eigenem Dokumentenlimit – ist geplant, aber nicht Bestandteil dieser Funktion.
- Die Konfiguration des Limits über das Portal ist ebenfalls als Erweiterung vorgesehen.