aza/APP/backup 24.2.26/handover.md

AZA – Master Handover / Operational Runbook

Arbeitsmodus / Regeln

User bastelt nicht; nur Composer-Patches (meist Opus) oder 1 exakter Command mit Pfad.

• Alle Aenderungen kommen als fertige, vollstaendige Dateien (ready-to-paste).
• User fuehrt nur vorgegebene Commands aus, keine manuellen Edits.
• Jede Aenderung in 1 Patch, kein schrittweises Anleiten.
• Keine risky Refactors – immer minimal und sicher.

Lokaler Start

cd "C:\Users\surov\Documents\AZA\backup 24.2.26"
powershell -ExecutionPolicy Bypass -File .\deploy\local_reset_and_start.ps1

Tests (Lokal)

powershell -ExecutionPolicy Bypass -File .\deploy\authorized_test.ps1
powershell -ExecutionPolicy Bypass -File .\deploy\smoke_suite.ps1

Step 14 – Docker/Compose Smoke-Test

Ziel: Container bauen, starten, smoke_suite PASS gegen Docker.

1 Command:

cd "C:\Users\surov\Documents\AZA\backup 24.2.26"
powershell -ExecutionPolicy Bypass -File .\deploy\docker_smoke.ps1

Was das Script macht:

• docker compose up -d --build (baut und startet Container)
• Wartet bis /health HTTP 200 liefert (max 60s)
• Fuehrt smoke_suite.ps1 gegen den Container aus
• Gibt [RESULT] PASS oder [RESULT] FAIL aus
• Bei FAIL bleiben Container laufen (Logs inspizierbar)

Erwartete Checks (smoke_suite):

• GET /health -> 200
• GET /version -> 200 mit {name, build}
• GET /license/status ohne Token -> 401/403
• GET /license/status mit Token -> 200 mit {valid, valid_until}
• GET /stripe/health -> 200 oder 404 (WARN)
• GET /openapi.json -> 200

Bei Fehler:

docker compose -f .\deploy\docker-compose.yml logs --follow
docker compose -f .\deploy\docker-compose.yml down

Step 15 – Caddy/HTTPS Reverse Proxy

Ziel: HTTPS live mit ACME-Zertifikat, Reverse Proxy auf :8000.

• Caddyfile finalisieren (Domain, TLS)
• ACME-Challenge testen
• Reverse Proxy pruefen (curl https://DOMAIN/health)

Step 16 – Go-Live Runbook

Ziel: Production-Deployment auf VPS oder Buero-PC.

• Webhook erreichbar (Stripe)
• Stripe Signatur ok (STRIPE_WEBHOOK_SECRET)
• Billing Portal Return URL korrekt
• Log-Hygiene: keine Secrets in Logs

Do-Not-Break Regeln

1. Keine bestehenden API-Response-Formate aendern (besonders /license/status)
2. Auth/Security nicht modifizieren (Token-Rotation, _check_token)
3. Keine Secrets loggen/printen (Tokens, Keys, Passwoerter)
4. backend_token.txt nie committen (steht in .gitignore)
5. deploy/.env nie committen (enthaelt Produktions-Secrets)
6. Immer try/except um History-Logging (darf Response nie blockieren)
7. Windows PowerShell 5.1 kompatibel bleiben