skrift-programme/CLAUDE.md

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

---

# Projekt: Skrift

Handschriftliche Dokumente als Service. Kunden konfigurieren Briefe/Postkarten/Umschläge im Web; ein Backend rendert sie als SVG in echter Handschrift; ein Schreibroboter (Pen-Plotter) schreibt sie physisch. Alle Software in diesem Ordner gehört zu Skrift. Sprache im Projekt: Deutsch.

## Ebenen und Komponenten

Drei Ebenen, getrennt gehalten für einfachere Wartung:

### `Docker/` — serverseitig, hinter Nginx Proxy Manager (NPM)
- **skrift-backend** (Node/Express, `:4000`, Domain `backend.skrift.de`) — **Main-Backend**. Generiert Brief-/Umschlag-SVGs: Text → Scriptalizer-API (natürliche Handschrift-Variation) → eigene Font-Engine (`src/lib/svg-font-engine.js`). Preview-Cache + finaler Order-Output. Platzhalter-System (`[[Name]]` → CSV). Kein PayPal im Backend — die PayPal-Zahlung läuft **rein client-seitig** im configurator über das PayPal-JS-SDK (`actions.order.create/capture` direkt gegen PayPal). SVG-Fonts unter `fonts/` (`tilda`=PremiumUltra79, `alva`=PremiumUltra23, `ellie`=PremiumUltra39). Struktur: `src/api/{routes,controllers,middleware}`, `src/services` (scriptalizer, placeholder), `src/lib` (svg-generator, svg-font-engine, page-layout).
- **signature-service** (FastAPI, `:8000`, Domain `api-sign.skrift.de`) — **zustandslos**. Findet unsichtbare Marker-Token (`§§SIG1§§`) in einem gedruckten PDF, platziert die zugeordnete Unterschrift-SVG relativ dazu und liefert **eine A4-SVG pro Seite** (`/render`, ZIP) bzw. ein Vorschau-PDF (`/preview`). Keine Plotter-Kalibrierung/Offsets im Service — Mechanik wird in der Druckersoftware behandelt. Geometrie-Logik in `core.py`.

### `Webseite/` — WordPress-Plugins (öffentlich)
- **skrift-configurator** — **öffentlicher Haupt-Konfigurator**, Shortcode `[skrift_konfigurator]`. Spricht das Backend nur über einen **serverseitigen PHP-Proxy** an (`includes/api-proxy.php`, REST-Namespace `skrift/v1/proxy/*`), damit der API-Token nie ins Frontend gelangt. Liefert außerdem das Basis-CSS (`--sk-*`-Variablen, `.sk-*`-Klassen) sowie Admin-Settings (Backend-Verbindung, Preise, Produkte, Gutscheine).
- **skrift-job-manager** — Kunden-Auftragsportal, Shortcode `[skrift_kundenauftrag]`. **Hängt hart am configurator** (nutzt dessen CSS + Backend-Verbindungseinstellungen). Eigener Namespace `skrift/v1/job/*`; ruft Backend u.a. `/api/order/register`, `/api/order/files`. Signaturen: Kunde zeichnet auf einem `<canvas>` → Striche werden client-seitig via `pathsToSvg()` als Polyline-SVG (`M/L`-Pfade) erzeugt und als Platzhalter `[[signatur1..3]]` mitgeschickt.

### `Produktion/` — lokale Windows-Software
- **skrift-produktion** — **Main-Produktion**. FastAPI auf `127.0.0.1:8765` (öffnet Browser automatisch). Worker: `FTPPollWorker` pollt SFTP nach neuen Aufträgen, `MachinePollWorker` überwacht die Plotter-Maschine, `QueueWorker` arbeitet die Queue ab. Sendet SVGs an die Maschinen-API (Default `http://192.168.2.32:90`) mit Format-Templates (Maße/Position/Rotation) aus `config.json`. **Signaturen-Tab** ruft `signature-service /render` über den eigenen Endpunkt `POST /api/signature/print` und schickt die A4-Signaturen an den Plotter (Service-URL in `config.json` unter `app.signature_backend_url`, Default `http://localhost:8000`).
- **AutoRecover** — kleines win32-Skript (`auto_recover.py`). Erkennt das Java-„Error"-Fenster des Plotters (kein Papier) und klickt max. 3× „Recover".

## Datenfluss (End-to-End)
1. Kunde konfiguriert im **configurator** (oder **job-manager**) → WordPress-Proxy → **skrift-backend** generiert SVGs.
2. **skrift-backend** schreibt den fertigen Order-Ordner nach `/var/skrift-output` (docker-compose-Volume). **Dieses Verzeichnis ist gleichzeitig das SFTP-Ziel**, auf das per SFTP zugegriffen wird — kein Zwischenschritt.
3. **skrift-produktion** holt den Auftrag per SFTP und schickt die SVGs formatgerecht an den **Plotter**.
4. Bei Unterschriften: gedrucktes PDF mit Marker-Token → **signature-service** platziert Signaturen → produktion sendet die A4-Signatur-SVGs an den Plotter.
5. **AutoRecover** hält den Druck bei Papierende am Laufen.

## Befehle

**skrift-backend** (`Docker/skrift-backend`)
```bash
npm install
npm start            # node src/server.js → :4000
npm run dev          # nodemon
docker-compose up -d # Prod (Volume: /var/skrift-output, fonts/ read-only)
```

**signature-service** (`Docker/signature-service`)
```bash
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8000
pytest                    # ein Test: pytest tests/test_x.py::test_name
docker compose up -d --build
```

**signature-to-svg** (`Docker/signature-to-svg`) — `uvicorn app.main:app --host 0.0.0.0 --port 8765` bzw. `docker-compose up -d`.

**skrift-produktion** (`Produktion/skrift-produktion`) — `Einrichten.bat` (venv + deps einmalig), dann `Starten.bat` (bzw. `Starten (Debug).bat`). Läuft auf `127.0.0.1:8765`.

**AutoRecover** — `python auto_recover.py`; EXE-Build via `build_exe.bat`.

WordPress-Plugins haben keinen Build-Schritt (reines PHP/JS).

## Wichtige Hinweise / Fallstricke
- **NPM-Netz**: `signature-service` hängt im externen Docker-Netz `nginx-proxy-manager_default` und veröffentlicht keinen Host-Port — NPM proxyt intern per `container_name`.
- **`SCRIPTALIZER_ERR_FREQUENCY=0`** setzen: sonst erzeugt Scriptalizer absichtlich durchgestrichene „Fehler"-Wörter.
- **Secrets liegen im Repo**: `Docker/skrift-backend/.env` enthält reale Keys — nicht in Ausgaben/Commits streuen.
- Der job-manager ist **ohne den configurator nicht lauffähig** (CSS + Backend-Settings kommen von dort).
- `FRONTEND_BACKEND_ZUSAMMENFASSUNG.md` stammt aus der Zeit vor dieser Ordnerstruktur (spricht von „WordPress Plugin" / „Docker Backend") und ist teils veraltet — diese CLAUDE.md hat Vorrang.