Stand vor Einführung des Nacht-Agenten

docs/lizenzsystem-erweiterung/README.md

@@ -0,0 +1,50 @@
+# Lizenzsystem-Erweiterung: Edition (Schlüssel-Präfix) und festes Ablaufdatum
+
+**Zweck:** Das Kundencenter soll Familytool-Stufen verkaufen (Premium, Unlimited, Lifetime, Trial). Das Familytool erkennt die Stufe am **Präfix des Lizenzschlüssels** (`PREMIUM-…`, `TRIAL-…`, `LIFETIME…`, sonst Unlimited). Das Lizenzsystem konnte bisher nur Schlüssel ohne Präfix erzeugen, jede Lizenz wäre also automatisch Unlimited gewesen.
+
+**Wo einspielen:** auf der Instanz, gegen die das Kundencenter und das Familytool laufen, also **licensing.flessinglabs.com** (nicht auf dem lokalen Dienst dieses Servers). Ohne den Patch verweigert das Kundencenter Bestellungen mit Edition (das Produkt bleibt Entwurf, eine Bestellung würde nie eine falsche Lizenz anlegen).
+
+Getestet an einer Kopie des Codes mit eigener Testdatenbank auf einem separaten Port: Präfix für alle drei Editionen, ungültiges Präfix → 422, festes Ablaufdatum, unveränderte Anlage ohne Präfix, `validate` mit Präfix-Schlüssel, Erkennung über `GET /`.
+
+## Ablauf (ca. 10 Minuten, kurze Unterbrechung nur beim Neustart)
+
+1. **Sichern** (DB und Code des Lizenzsystems auf dem Zielserver):
+   ```bash
+   mysqldump --single-transaction <DBNAME> > licensing-vor-erweiterung.sql
+   cp -a <pfad>/backend/app app-vor-erweiterung
+   ```
+2. **Vorab prüfen: startet der Dienst nach einem Neustart korrekt?** (Wir hatten am 26.09. auf dem lokalen Dienst einen Ausfall, weil das venv neuer war als der laufende Prozess. Siehe LICENSING-11.)
+   ```bash
+   <pfad>/backend/venv/bin/pip list | grep -iE "bcrypt|passlib|slowapi|starlette"   # bcrypt muss < 5 sein (z. B. 4.0.1)
+   grep -n "def validate_license" -A3 <pfad>/backend/app/routers/licenses.py           # Parameter muss "request: Request" heißen
+   ```
+   Wenn `bcrypt` ≥ 5 ist oder die Schema-Parameter noch `request` heißen: **erst das beheben**, sonst fallen Login und `validate` beim Neustart aus.
+3. **Datenbank erweitern** (Schlüssel werden mit Präfix länger als 36 Zeichen):
+   ```sql
+   ALTER TABLE licenses MODIFY license_key VARCHAR(64) NOT NULL;
+   ```
+4. **Code anpassen** (erst Trockenlauf, dann anwenden):
+   ```bash
+   python3 apply_erweiterung.py <pfad>/backend             # zeigt nur, was geändert würde
+   python3 apply_erweiterung.py <pfad>/backend --apply     # legt Sicherungen *.bak-<zeit> an
+   ```
+   Weicht der Code ab, bricht das Skript ohne Änderung ab und nennt die Stelle.
+5. **Dienst neu starten** (z. B. `systemctl restart licensing-backend`) und prüfen:
+   ```bash
+   curl -s https://licensing.flessinglabs.com/api/        # muss "features":["key_prefix","explicit_expiry"] enthalten
+   ```
+   Danach kurz testen: Login im Admin-Panel, eine Lizenz prüfen (`validate`) und im Familytool die Lizenzprüfung.
+6. **Im Kundencenter**: Verbindungen → „Jetzt abgleichen“. Unter „Fähigkeiten“ erscheinen `license.key_prefix` und `license.expiry`. Danach lassen sich die Familytool-Produkte aktivieren.
+
+## Zurückrollen
+Dienst stoppen, `*.bak-<zeit>` zurückkopieren, Dienst starten. Die Spalte darf auf 64 Zeichen bleiben. Bereits mit Präfix angelegte Lizenzen bleiben gültig.
+
+## API-Änderungen im Detail
+- `POST /licenses/` Body: neues optionales Feld `key_prefix` (`PREMIUM` | `TRIAL` | `LIFETIME`). Antwort enthält den Schlüssel `<PRAEFIX>-<uuid>`.
+- `POST /licenses/`: ein angegebenes `expires_at` (Ortszeit wie bisher) wird verwendet; ohne Angabe gilt die bisherige Berechnung aus `duration_type`.
+- `GET /`: Feld `features` (Liste).
+- Nicht geändert: `validate`, `register`, Shop, Login, alle bestehenden Felder.
+
+## Bekannte Grenzen
+- Ein Upgrade von Premium auf Unlimited bedeutet einen **neuen Schlüssel** (das Präfix steckt im Schlüssel). Das Kundencenter legt dann eine neue Lizenz an; die alte wird gesperrt. Eine spätere Lösung mit einem Feld `edition` im Lizenzsystem (statt Präfix) ist möglich.
+- Das Ablaufdatum wird (wie im Lizenzsystem üblich) als Ortszeit gespeichert.