buchwerk/API.md

# buchwerk – Schnittstelle Backend ↔ Frontend

Backend: FastAPI auf Port 8020, liefert `frontend/dist/` aus. Alle Pfade unter `/api`.

## Adressen

Ein Thema hat einen Slug („Godot 4“ → `godot-4`) und Versionen `v1`, `v2`, … mit eigenem Lauf, Buch, Quellen und Leseposition.
Die Version ist in der API immer Teil des Pfads; „neueste“ löst die Oberfläche selbst auf.

Seite: `/<slug>`, `/<slug>/v2/lauf`, `/<slug>/v2/buch`, `/<slug>/v2/buch/3.4` (Abschnitt; `3` = Kapitel, `vorwort`), `/<slug>/v2/lesen`.
Ohne `v2` gilt die neueste Version.

## Themen und Versionen

- `GET /api/themen` → `[{slug, name, thema, spezialisierung, titel, hinweise, angelegt, status, laeuft, stufe, versionen: [{v, status, laeuft, stufe, angelegt, kosten_usd}]}]`
  – `status/laeuft/stufe` gelten für die neueste Version; `status`: `neu | laeuft | pausiert | fertig | fehler`
- `POST /api/themen` `{name, hinweise, spezialisierung}` → Thema wie oben (legt `v1` an)
  – `name`: Hauptthema; `spezialisierung`: grenzt es ein, nur was dafür gebraucht wird; die Bezeichnung (`name` in der Antwort, Ordner) wird „Thema – Spezialisierung“
  – `hinweise`: wie das Thema zu verstehen ist; gelten je Version und sind bei einer neuen Version änderbar
  – `stopp_gliederung` (bool, optional): der Lauf hält nach der Gliederung an (`pausiert`); „Fortsetzen“ schreibt die Kapitel
- `GET /api/themen/{slug}` → Thema wie oben
- `DELETE /api/themen/{slug}` – ganzes Thema
- `POST /api/themen/{slug}/versionen` `{hinweise?, stopp_gliederung?}` → `{"v": N}` – nächste Version ohne Start; ohne Angabe übernimmt sie die Hinweise der neuesten Version
- `DELETE /api/themen/{slug}/v{N}` – nur diese Version
- `POST /api/themen/{slug}/v{N}/start` – startet oder setzt fort (resümiert an der offenen Stufe)
- `POST /api/themen/{slug}/v{N}/pause` – bricht laufende Agenten ab; Neustart mit `start`
- `POST /api/themen/{slug}/v{N}/reset` – löscht alles in der Version außer dem Zustand „neu“
- `GET|PUT /api/themen/{slug}/v{N}/position` – Leseposition `{abschnitt, lesemodus}`

## Stufen

`recherche → gliederung → schreiben → pruefung → lektorat → konsistenz → montage`. Das Lektorat glättet jedes geprüfte Kapitel
Abschnitt für Abschnitt sprachlich (ohne Werkzeuge, `prompts/lektorat.md`); ein Abschnitt wird nur übernommen, wenn Bezeichner,
Zahlen, Überschriften, Codeblöcke und Diagramme erhalten sind und der Umfang nicht über 20 % wächst. Marker: `berichte/lektorat-NN.md`.
Alte Zustände ohne diese Stufe bekommen sie beim Laden nachgetragen.

## Zustand eines Laufs

`GET /api/themen/{slug}/v{N}` →

```json
{
  "slug": "godot-4", "name": "Godot 4", "version": 1, "thema": "Godot 4", "spezialisierung": "", "titel": "Godot 4", "hinweise": "…",  // hinweise: die dieser Version
  "status": "laeuft", "grund": "", "stufe": "schreiben", "angelegt": "2026-09-28T10:00:00Z",
  "deutung": {"titel": "Godot 4", "untertitel": "…", "deutung": "…", "buchtyp": "werkzeug|wissen", "zielgruppe": "…"},
  "stufen": [
    {"id": "recherche", "titel": "Thema deuten und Quellen beschaffen", "status": "fertig", "fertig": 1, "gesamt": 1,
     "kosten_usd": 1.2, "tokens": 250000, "gestartet": "2026-09-28T10:00:00Z", "beendet": "…"},
    {"id": "gliederung", "titel": "Gliederung", …},
    {"id": "schreiben", "titel": "Kapitel schreiben", "status": "laeuft", "fertig": 3, "gesamt": 18, …},
    {"id": "pruefung", "titel": "Kapitel prüfen", …},
    {"id": "konsistenz", "titel": "Doppelungen und Vorwort", …},
    {"id": "montage", "titel": "Buch zusammensetzen", …}
  ],
  "kosten_usd": 12.3, "tokens": 4100000,
  "agenten": [
    {"id": "kapitel-03", "stufe": "schreiben", "name": "Kapitel 3 schreiben", "status": "laeuft|fertig|fehler|abgebrochen",
     "kosten_usd": 0.9, "tokens": 180000, "werkzeuge": 41, "gestartet": "…", "beendet": "…", "bericht": "<Abschlussbericht, Markdown>"}
  ],
  "ereignisse": [{"zeit": "…", "agent": "kapitel-03", "art": "tool|text|start|ende|fehler", "text": "Write buch/03-dal.md"}]
}
```

`stufen[].status`: `offen | laeuft | fertig | fehler`. `ereignisse` sind die letzten 100.

## Buch

`GET /api/themen/{slug}/v{N}/buch` →

```json
{
  "titel": "Godot 4", "untertitel": "Architektur, Konzepte und Praxis der Engine", "status": "fertig",
  "vorwort": "<Markdown ohne H1>",
  "kapitel": [
    {"id": "03", "ord": 3, "titel": "GDScript", "teil": "Teil I – Grundlagen", "datei": "buch/03-gdscript.md",
     "status": "fehlt|geschrieben|geprueft|konsistent", "intro": "<Markdown vor dem ersten Abschnitt>",
     "abschnitte": [{"id": "03-1", "nr": "3.1", "titel": "Sprache und Syntax", "text": "<Markdown ohne die ##-Überschrift>", "woerter": 1400, "minuten": 8}],
     "woerter": 7000, "minuten": 39,
     "berichte": {"autor": "<Markdown>", "pruefer": "<Markdown>"}}
  ],
  "woerter": 130000, "minuten": 720,
  "gliederung": "<GLIEDERUNG.md>", "quellen": "<QUELLEN.md, Markdown>",
  "pdf": true
}
```

- `GET /api/themen/{slug}/v{N}/buch.md` – ganzes Buch als Markdown
- `GET /api/themen/{slug}/v{N}/kern.md` – alle `## Kern`-Blöcke der Kapitel (Frage-Antwort-Paare) in einer Datei, zum Auffrischen
- `GET /api/themen/{slug}/v{N}/buch.pdf` – PDF (404, solange nicht gebaut)

Solange ein Lauf läuft, enthält `buch` die bereits geschriebenen Kapitel (Status `geschrieben`, bis der Prüfer fertig ist).

## Dateien im Speicher

```
storage/<Thema>/
  thema.json          {name, thema, spezialisierung, slug, titel, hinweise, angelegt}  – name = „Thema – Spezialisierung“
  v1/, v2/, …         je Version:
    state.json        Zustand wie oben (ohne Buch), mit hinweise und stopp_gliederung der Version
    deutung.json      vom Recherche-Agenten
    position.json     Leseposition
    quellen/          QUELLEN.md + geklonte/geladene Quellen
    buch/             STIL.md, GLIEDERUNG.md, 00-vorwort.md, NN-*.md, README.md, buch.md, buch.pdf
    berichte/         <agent-id>.md (Abschlussberichte)
    arbeit/           Arbeitsdateien der Agenten
    log.jsonl         Ereignisse
```

Alte Ablagen (alles direkt unter `storage/<Thema>/`) werden beim Start nach `v1/` verschoben, fehlende Slugs nachgetragen.