# 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