d15ec49714
Seite: /<slug>[/v<N>][/lauf|/buch|/lesen][/<Abschnitt>], Zurück-Taste je Abschnitt. API: /api/themen/<slug>/v<N>/… mit Version als Pflichtteil des Pfads; /api/topics entfällt. Slugs stehen in thema.json und werden beim Start nachgetragen. Unbekannte API-Pfade liefern 404 statt der Seite. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# 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, 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}` → Thema wie oben (legt `v1` an)
|
||
- `GET /api/themen/{slug}` → Thema wie oben
|
||
- `DELETE /api/themen/{slug}` – ganzes Thema
|
||
- `POST /api/themen/{slug}/versionen` → `{"v": N}` – nächste Version, gleiche Eingaben, ohne Start
|
||
- `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}`
|
||
|
||
## Zustand eines Laufs
|
||
|
||
`GET /api/themen/{slug}/v{N}` →
|
||
|
||
```json
|
||
{
|
||
"slug": "godot-4", "name": "Godot 4", "version": 1, "titel": "Godot 4", "hinweise": "…",
|
||
"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": "Querverweise 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}/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, slug, titel, hinweise, angelegt}
|
||
v1/, v2/, … je Version:
|
||
state.json Zustand wie oben (ohne Buch)
|
||
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.
|