--- name: logbuch description: Use when writing project updates into Logbuch, the update archive of the NYO group. Covers the API at /api/v1, the editorial rules, images, dating and publishing. Trigger on "Logbuch", "Eintrag schreiben", "Projekt-Update", "Änderung festhalten", or when work is finished and someone should hear about it. --- # Logbuch Logbuch hält fest, was in den Produkten passiert ist. Alle zwei Wochen entsteht pro Projekt ein Eintrag über das, was fertig geworden ist. Es ist kein Änderungsprotokoll für Entwickler und keine Pressemitteilung, sondern für Kollegen und Kunden, die wissen wollen, was sich geändert hat, ohne Tickets oder Code zu lesen. ## Was du wissen musst, bevor du schreibst Ein Zugang kann **niemals veröffentlichen**. Alles, was du anlegst, ist ein Entwurf. Ein Mensch schaut drauf und gibt frei. Schreib entsprechend fertig, nicht halb. Jede Anfrage trägt das Token im Kopf: ``` Authorization: Bearer ``` Die Basis-Adresse steht in deiner Aufgabe, im Zweifel `https://logbuch.nyo.de`. Alles liegt unter `/api/v1`. Dein Zugang hat drei Eigenschaften, die bestimmen, was du darfst: | Eigenschaft | Bedeutung | |---|---| | Modus | `read` liest, `write` schreibt zusätzlich | | Zielgruppe | `internal`, `customer` oder `public`. Du siehst und setzt nie etwas Offeneres | | Projektbindung | Ist ein Projekt gesetzt, gilt der Zugang ausschließlich dort | ## Reihenfolge 1. `GET /api/v1/projects` - welche Projekte darfst du bespielen 2. `GET /api/v1/post-types` - die gültigen Schlüssel der Beitragsarten, nicht raten 3. `GET /api/v1/style-guide` - der Redaktionsleitfaden im Wortlaut 4. `POST /api/v1/media` - Bilder hochladen, wenn du welche hast 5. `POST /api/v1/posts` - Entwurf anlegen 6. `PUT /api/v1/posts/:id/blocks` - Inhalt setzen 7. `GET /api/v1/posts/:id` - zurücklesen und prüfen ## Einen Eintrag anlegen ```bash curl -s -X POST -H "Authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{ "project": "trakk", "title": "SLA-Uhr zählt Feiertage nicht mehr mit", "teaser": "Reaktionszeiten liefen über Wochenenden weiter und lösten falsche Eskalationen aus.", "type": "fix", "audience": "customer", "cover_media_id": "", "publish_at": "2026-06-04T09:00:00Z", "idempotency_key": "sla-2026-06-04" }' \ "$BASE/api/v1/posts" ``` Die Antwort trägt die Kennung. **Merk sie dir**, du brauchst sie für Blöcke, Änderungen und Löschen. Hast du sie verloren, findest du den Entwurf über `GET /api/v1/posts/`. `idempotency_key` setzen, wenn dein Lauf abbrechen könnte. Derselbe Schlüssel liefert denselben Eintrag zurück, statt einen zweiten anzulegen. `number` ist bei Entwürfen `null`. Die laufende Nummer vergibt Logbuch beim Veröffentlichen, damit im Archiv keine Lücken entstehen. ## Inhalt setzen ```bash curl -s -X PUT -H "Authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"blocks":[ {"type":"text","data":{"text":"Bisher lief die Uhr durch. Wer freitags meldete, hatte montags eine Eskalation im Postfach."}}, {"type":"image","data":{"mediaId":""}}, {"type":"text","data":{"text":"Jetzt zählt nur noch die vereinbarte **Servicezeit**."}} ]}' \ "$BASE/api/v1/posts//blocks" ``` Der Aufruf setzt die Blöcke vollständig, in der übergebenen Reihenfolge. Höchstens 100. | Typ | Felder in `data` | |---|---| | `text` | `text`, als Markdown: Absätze, **fett**, *kursiv*, Verweise, Listen, `###` als Zwischenüberschrift. Kein rohes HTML | | `image` | `mediaId` | | `gallery` | `mediaIds` | | `before_after` | `beforeMediaId`, `afterMediaId` | | `video` | `url`, `title` | | `quote` | `text`, `source` | | `code` | `code`, `language` | | `link` | `url`, `title`, `description` | | `callout` | `text`, `tone` | ## Bilder ```bash curl -s -X POST -H "Authorization: Bearer $TOKEN" \ -F "file=@screenshot.png" \ -F "project=trakk" \ -F "alt=Spaltenmenü mit den neuen Einträgen" \ "$BASE/api/v1/media" ``` `project` ist der Slug, bei projektgebundenem Token darf er wegbleiben. Nur Bildformate, höchstens 15 MB. Die Antwort trägt die Medien-Kennung für `cover_media_id` und für Bildblöcke. Ein Bild zeigt, was sich geändert hat. Kein Firmenlogo, kein Symbolbild. Findest du nichts, was den Punkt wirklich zeigt, lass es weg. Der Alt-Text beschreibt, was zu sehen ist, und ist bei öffentlichen Beiträgen Pflicht, sonst lässt sich der Beitrag nicht freigeben. Ein Bild wieder loswerden: `DELETE /api/v1/media/:id`. Hängt es noch an einem Beitrag, kommt 409. ## Datum `publish_at` nimmt eine ISO-Zeitangabe, beim Anlegen und beim Ändern. Du veröffentlichst damit nichts, du hinterlegst nur das Datum. Gibt ein Mensch frei, übernimmt Logbuch genau dieses statt der aktuellen Uhrzeit. So landen ältere Meldungen an der richtigen Stelle im Archiv. ## Wie es klingen soll **Aufbau.** Titel, Anreißer, dann der Text. Der Titel sagt, was sich geändert hat, nicht dass sich etwas geändert hat. Der Anreißer fasst in zwei bis drei Sätzen zusammen, was der Leser davon hat. Der Text erklärt, was vorher war, was jetzt ist, und was zu tun bleibt. Gute Titel: - "SLA-Uhr zählt Feiertage nicht mehr mit" - "Spalten per Rechtsklick verwalten" Schlechte Titel: - "Verbesserungen an der Tabelle" - sagt nichts - "Wir haben ein spannendes neues Feature gebaut" - Werbung statt Information **Ton.** Sachlich und direkt, aktive Verben. Keine Werbesprache, keine Superlative, keine Ausrufezeichen, keine Emojis. Keine Gedankenstriche, immer normales Minus. Echte Umlaute, niemals ae, oe, ue. **Länge.** So lang wie nötig, meist drei bis sechs Absätze. Eine Fehlerbehebung darf aus zwei Sätzen bestehen. **Zielgruppe.** `internal` für Umbauten, Zwischenstände und alles über Kunden. `customer` für das, was ein Kunde des Produkts wissen soll. `public` nur für das, was auch außerhalb stehen darf. Im Zweifel die engere wählen. ## Fehler Antworten kommen als Problem-JSON mit `type`, `title`, `status` und `detail`. | Status | Bedeutung | |---|---| | 400 | fehlerhafte Eingabe, `detail` sagt welches Feld | | 401 | Token fehlt oder ist widerrufen | | 403 | dem Zugang fehlt das Recht, etwa eine zu offene Zielgruppe | | 404 | nicht vorhanden oder für diesen Zugang nicht sichtbar | | 409 | bereits veröffentlicht, Änderung nicht mehr möglich | | 422 | unbekannte Beitragsart oder fehlende Projektbindung | ## Was du nicht tust - Veröffentlichen. Geht nicht und soll nicht. - Eine offenere Zielgruppe setzen, als dein Zugang hat. - Beitragsarten raten statt `GET /api/v1/post-types` zu fragen. - Symbolbilder anhängen, damit etwas bunt ist. - Bei einem Abbruch blind neu anlegen. Erst `GET /api/v1/posts/` fragen oder `idempotency_key` verwenden. ## Vollständige Beschreibung `GET /api/v1/openapi.json` liefert die maschinenlesbare Fassung mit allen Feldern und Antworten. `GET /api/v1/style-guide` liefert den Leitfaden. Beide verlangen dasselbe Token.