apairon
1928922e07
- Audit: plans/doku-audit.md (Befunde, Phasen P1-P9, Ausführungsprotokoll) + plans/audit/ (8 Detailreports) + plans/offene-issues.md - Werkzeuge: scripts/audit-docs.mjs (Links/Anker/Bilder/Tabellen), scripts/gen-schema-matrix.mjs (npm run gen:schemas) - Neue Seiten: projekt/feld-rechte, reference/rest-system, reference/schema-properties, projekt/tests, 5 Anwender-Seiten - Fehler behoben: EMBEDDING_BGE_M3_*-Env, allowSnapshots, MCP-Scopes (.read/.create/.update), meta.views, loadAll-Signatur, OpenAPI-Endpunkt, MongoDB 8, Befehlspalette - Screenshots: 9 Admin + 10 Anwender aus Mock-Projekt corporate (t1 entfernt), 49 Bilder gesamt - AGENTS.md: Sync-Behauptung richtiggestellt, Belegpflicht/UI-Namen/Screenshot-Regeln, Werkzeug-Abschnitt - Build: 71 Seiten grün, 0 tote Links, 0 kaputte Tabellen
69 lines
12 KiB
Markdown
69 lines
12 KiB
Markdown
# Review: Einstieg + Server
|
||
|
||
- Umfang: `src/content/docs/einstieg/*.md` (4 Dateien), `src/content/docs/server/*.md` (5 Dateien). Alle vollständig gelesen.
|
||
- Datum: 2026-10-16.
|
||
- Geprüft gegen: `AGENTS.md` §1, `tibi-server/internal/**` (Code), `tibi-svelte-starter` (Compose, Makefile, `api/`, `scripts/`, `.env`), `tibi-admin-nova/.../de.json` (nur Stichworte), Server-HEAD `68b42785`, Starter-HEAD `e3f92ebf`.
|
||
- Regel: Nur belegte Fehler stehen als `FEHLER-INHALT`; alles andere als `PRUEFEN` am Ende.
|
||
|
||
## Befundtabelle
|
||
|
||
| # | Datei:Zeile | Kategorie | Befund (kurz) | Vorschlag |
|
||
|---|---|---|---|---|
|
||
| 1 | konfiguration.md:21 | FEHLER-INHALT | „`bge-m3` → `EMBEDDING_BGE-M3_*`" ist falsch. `normalizeEnvKeyName` ersetzt `-` durch `_` und uppercaset, Beleg `tibi-server/internal/config/server.go:245-251,437-439`. Korrekt wäre `EMBEDDING_BGE_M3_*`. | Beispiel korrigieren zu `EMBEDDING_BGE_M3_*`; Regel umformulieren („Bindestrich wird zu Unterstrich“). |
|
||
| 2 | konfiguration.md:99-105 | FEHLER-INHALT | Gleicher Fehler im Beispielblock: 7× `EMBEDDING_BGE-M3_*` (`TYPE`, `MODELPATH`, `DIMENSIONS`, `DOCUMENTPREFIX`, `QUERYPREFIX`). Keine dieser Variablen greift. Beleg wie #1. | Alle Prefixe zu `EMBEDDING_BGE_M3_*` ändern. |
|
||
| 3 | betrieb.md:21 | FEHLER-INHALT | „`mongo` (MongoDB 7)“ — der Starter pinnt `image: gitbase.de/server/mongo:8` (`docker-compose-local.yml`, Service `mongo`). | Auf „MongoDB 8“ ändern. |
|
||
| 4 | schnittstellen.md:62 | FEHLER-INHALT | „Alle Antworten sind gzip-komprimiert“ — falsch absolut. Ausgenommen sind `.pdf/.mp4/.jpg/.jpeg/.png` und `/metrics`. Beleg `internal/controller/setup.go:151-154`. | „Alle JSON-Antworten … (ausgenommen Mediendateien und `/metrics`)“. |
|
||
| 5 | neues-projekt.md:68,77 | MD-FEHLER | `$CODING_TIBISERVER_URL` ist nirgends definiert: nicht in Starter-`.env`, nicht in der URL-Liste in schnellstart.md:51, in keinem Script. Nur `-tibiserver`-Host, inline gebaut in `scripts/reload-local-tibi.sh:10`. Befehle so nicht kopierbar. | Variable definieren (`.env` + schnellstart.md:51) oder Befehle auf dokumentierten Host umschreiben. |
|
||
| 6 | uebersicht.md:36 | MD-FEHLER | „Verifiziert am 68b42785“ ohne Backticks; alle 4 anderen Server-Seiten nutzen `` `68b42785` ``. | Backticks ergänzen. |
|
||
| 7 | server/betrieb.md:6, konfiguration.md:6, schnittstellen.md:6, sicherheit.md:6 | MD-FEHLER | Identische 8er-Importzeile (`Aside, Tabs, TabItem, Steps, Card, CardGrid, Badge, FileTree`), davon pro Seite 3–6 ungenutzt (z. B. betrieb: `Tabs/TabItem/Card/CardGrid/FileTree` ohne Verwendung; schnittstellen: `Aside/Steps/Card/CardGrid/Badge/FileTree` ohne Verwendung). Copy-Paste-Rest. | Je Seite nur importieren, was verwendet wird. |
|
||
| 8 | server/*.md:1-4 vs einstieg/*.md:1-4 | MD-FEHLER | Frontmatter inkonsistent: Server-Seiten mit einfachen Quotes (`title: '...'`), Einstieg ohne. | Eine Form wählen (ohne Quotes, wie einstieg). |
|
||
| 9 | uebersicht.md:8-14 | MD-FEHLER | Zwei Hinweis-Stile auf einer Seite: Blockquote (`> **Handseite.** …`) plus `:::note`. | Einen Stil wählen (Repo-Konvention: `<Aside>`). |
|
||
| 10 | konfiguration.md:41-43 | STIL | „Das README-Beispiel ist unvollständig und nennt …“ + „README lügt an zwei Stellen“ + rohes `<del>/<ins>`-HTML. „Lügt“ ist unsachlich, HTML-Tags sind kein Doku-Stilmittel. | Sachlich: „Das README-Beispiel ist veraltet (noch Go 1.23 statt `go 1.25.0`/`go1.25.7` laut `go.mod`).“ Version als `Badge` oder Code, kein `<del>/<ins>`. |
|
||
| 11 | neues-projekt.md:10 | STIL | Agenten-Meta im Nutzertext: „Stand: am Code geprüft, nicht aus Alt-Doku.“ Für Leser wertlos. | Streichen; Prüfnachweis gehört in Commit/Plan, nicht auf die Seite. |
|
||
| 12 | neues-projekt.md:53 | STIL | Belehrung an den Leser: „Keine Pfad-B-Schritte im lokalen Starter-Stack erfinden.“ | Streichen oder in Ergebnis-Satz umwandeln („Im lokalen Stack entfällt Pfad B.“). |
|
||
| 13 | uebersicht.md:8 | STIL | Maintainer-Meta („Wird vom Sync nie überschrieben (`keep`) …“) steht als erster Satz im Nutzertext. | In HTML-Kommentar oder ans Seitenende verschieben. |
|
||
| 14 | uebersicht.md:10, begriffe.md:8-18 | STIL | Benennung uneinheitlich: „**Tibi-server**“, „**Tibi-Server**“, „**Tibi-Admin**“, „**Tibi-Projekt**“ — AGENTS.md §0 verlangt `tibi-server` / `tibi-admin` (klein). | Durchgehend Kleinschreibung wie in was-ist-tibi.md:10-11. |
|
||
| 15 | einstieg/*.md vs server/*.md | STIL | Codezaun-Sprache uneinheitlich: Einstieg `sh`, Server `bash` (bei identischem Inhalt Shell). | Einheitlich `bash` (oder `sh`) wählen. |
|
||
| 16 | schnittstellen.md:53-57 | STIL | Recht-Spalte uneinheitlich: `project.reload`, `project.regenerate-search`, dann bloß „Projekt-Admin“ (Embedding-Status), dann `project.backup` / `project.snapshot`. | Überall Scope schreiben (Embedding-Status: welches Recht genau, Beleg `setup.go:390` prüfen). |
|
||
| 17 | schnellstart.md:91 | STIL | „nur wenn Server-Token vorhanden“ — vage Bedingung ohne Handlung. | Konkret: „… oder `X-Admin-Token` mit Scope `project.create`“ (falls belegbar, sonst streichen). |
|
||
| 18 | konfiguration.md:123 | STIL | Tippfehler „`namespace….)`“ (vier Punkte + Klammer). | „`namespace.…`“ bzw. Beispiel wie sicherheit.md:21. |
|
||
| 19 | uebersicht.md:20 | STIL | Card verspricht „inkl. Go-Version und Legacy-Default“ — `Legacy-Default` kommt in konfiguration.md nirgends vor (gemeint sind wohl die 201/204-Legacy-Codes aus schnittstellen.md:62). | Begriff klären oder streichen. |
|
||
| 20 | was-ist-tibi.md:30-35 | STARLIGHT | `Card` mit Markdown-Link im Body („[Loslegen](…)“) ist kein klickbares Karten-Link. | `LinkCard` mit `href` nutzen, Text ohne Markdown-Link. |
|
||
| 21 | uebersicht.md:19-33 | STARLIGHT | 5× `Card` + `[Lesen](…)`-Link statt Karten-Link; doppelte Information (Titel + Link-Text identisch). | Auf `LinkCard` (`link.href`, `link.description`) umstellen. |
|
||
| 22 | neues-projekt.md:12-23 | STARLIGHT | Setup-Checkliste als statischer `text`-Codeblock mit `[ ]` — nicht abhakbar, kein Fortschritt. | `Steps` + echte Task-List (`- [ ]` im Fließtext) oder `Steps`-Komponente pro Meilenstein. |
|
||
| 23 | neues-projekt.md:81-83 | STARLIGHT | Wichtiger Token-Hinweis als `:::caution` (Syntax im Repo sonst nirgends, siehe PRUEFEN P1). | `<Aside type="caution" title="…">` wie sicherheit.md:30. |
|
||
| 24 | schnellstart.md:8-10 | STARLIGHT | `:::danger` für die Kern-Regel (Repo-Einzelfall). | `<Aside type="danger" title="Kern-Regel aus dem Starter">`. |
|
||
| 25 | konfiguration.md:46-77, schnittstellen.md:21-60 | STARLIGHT | `Tabs` ohne `syncKey` — gewählte Tabs (z. B. „Minimal-Beispiel“/„Lokaler Dial“) gehen beim Seitenwechsel verloren. | `syncKey` ergänzen (z. B. `syncKey="serverblick"`). |
|
||
| 26 | begriffe.md:6-19 | STARLIGHT | Reine Tabelle ohne einzige Heading: kein `tableOfContents`, keine Sprungmarken, kein Aside, keine Weiterführung. | Je Oberbegriff (`Namespace`, `Collection`, …) als `##`-Abschnitt oder Glossar-`CardGrid`; Tabelle als Kurzindex oben behalten. |
|
||
| 27 | schnittstellen.md:101 | STRUKTUR | „Wie frage ich Daten ab?“ verlinkt auf `/einstieg/begriffe/` statt auf die Abfrage-Seite. | Auf `/projekt/abfragen-lesen/` zeigen; begriffe-Zeile streichen oder umbenennen. |
|
||
| 28 | was-ist-tibi.md:27-36 | STRUKTUR | „Wo geht es weiter?“ nennt nur Schnellstart + Begriffe; „Neues Projekt“ (4. Sidebar-Eintrag) fehlt, obwohl schnellstart.md:94 darauf verweist. | Dritte Karte „Neues Projekt“ ergänzen. |
|
||
| 29 | schnellstart.md:85-92, neues-projekt.md:81-83 | STRUKTUR | Token-Kopf-Wissen steht doppelt (Tabelle vs. Caution) plus drittes Mal in `reference/token-koepfe.md`. Drei Wahrheiten zu einer Tatsache. | Kurzfassung + ein Verweis auf `reference/token-koepfe.md` als Single Source. |
|
||
| 30 | schnellstart.md:73, neues-projekt.md:105-115 | STRUKTUR | Nach „Abnahme“ endet der Pfad im Leeren: kein Verweis in Admin-/Anwender-Doku (erste Anmeldung, erste Inhalte). | „Nächster Schritt“-Box mit Links auf `admin/`- und `anwender/`-Seiten. |
|
||
| 31 | betrieb.md:62-70 | LUECKE | Backup/Snapshot nur als „Fortschritts-Stream“ erwähnt; kein Wort zu Wiederherstellung, Retention, `prune`, obwohl Endpunkte existieren (`setup.go:416-491`). | Abschnitt „Sichern und Wiederherstellen“ mit `backup`-, `snapshots`- und `prune`-Befehlen. |
|
||
| 32 | betrieb.md | LUECKE | `/api/v1/admin/shutdown` (`server.shutdown`) kommt nur als Tabellenzelle in schnittstellen.md:32 vor; Betreiber-Seite ohne Stop-/Neustart-Prozedur. | Störungs-/Wartungsabschnitt um Shutdown + Audit-Spur (`setup.go:772-798`) ergänzen. |
|
||
| 33 | konfiguration.md:24-43 | LUECKE | Beispielblöcke nur für DB/API/Mail + LLM/Embedding; `audit`, `ratelimit`, `hook`, `mcp` nur als Tabellenzeilen ohne YAML-Form. | Je ein Minimal-YAML pro Bereich (Defaults aus `server.go` sind belegt). |
|
||
| 34 | begriffe.md | LUECKE | Kein Eintrag zu Token-Arten (PAT/JWT/Admin-Token) und Scope-Syntax, obwohl Einstieg + Server ständig darauf verweisen. | 2 Zeilen + Verweis auf `reference/token-koepfe.md` und `server/sicherheit/`. |
|
||
| 35 | einstieg/*.md | LUECKE | Mock-Modus wird nur in begriffe.md:19 definiert; schnellstart.md erwähnt `MOCK` nirgends, obwohl Starter `start:mock` (`MOCK=1`) kennt. | Schnellstart-Schritt „Starten“ um Mock-Hinweis ergänzen oder bewusst ausklammern. |
|
||
|
||
## Starlight-Potenzial (pro Seite)
|
||
|
||
- was-ist-tibi.md: `Card` → `LinkCard` (#20); ASCII-Diagramm (Z. 15-23) als `Steps`- oder nummerierte Liste mit je einem Satz Wirkung pro Pfeil.
|
||
- schnellstart.md: `:::danger` → `<Aside type="danger">` (#24); Schritt 1-6 in `<Steps>` statt nummerierter Headings (konsistent zu betrieb.md:38).
|
||
- neues-projekt.md: Checkliste → `Steps`/Task-List (#22); `:::caution` → `<Aside>` (#23); `FileTree` um Stamm (`./`, `docker-compose-local.yml`, `.env`) erweitern.
|
||
- begriffe.md: Glossar-Struktur mit Headings + `CardGrid`-Kurzindex (#26); `tableOfContents` greift dann automatisch.
|
||
- uebersicht.md: `Card` → `LinkCard` (#21); Blockquote + `:::note` → ein `<Aside type="note">` (#9).
|
||
- konfiguration.md: `Tabs` mit `syncKey` (#25); `<del>/<ins>` → `Badge` für `go 1.25.0` (#10); Beispielblöcke (#33).
|
||
- betrieb.md: ungenutzte Imports entfernen (#7); Störungstabelle um Shutdown-Zeile erweitern (#32); `Badge`-Profilzeile (Z. 14) ans Seitenende in „Voraussetzungen“ wiederholen ist unnötig — streichen.
|
||
- sicherheit.md: ungenutzte Imports entfernen (#7); Token-Tabelle um PAT-Beispiel (`tibi_pat_…`) als `bash`-Block ergänzen; Checkliste (`Steps`) ist bereits Musterbeispiel — behalten.
|
||
- schnittstellen.md: `Tabs` mit `syncKey` (#25); API-Baum (Z. 10-17) als `FileTree` statt `text`-Block prüfen; Linkfix #27.
|
||
|
||
## Unsichere Punkte
|
||
|
||
- P1. `:::caution title="…"`, `:::danger title="…"`, `:::note title="…"` (neues-projekt.md:81, schnellstart.md:8, uebersicht.md:12): Titel-Attribut ohne Klammern ist keine Standard-Starlight-Syntax (`[Titel]` wäre sie); Repo-Konvention ist `<Aside>`. Build-Rendering nicht geprüft — bitte Rendern verifizieren oder auf `<Aside>` umstellen.
|
||
- P2. schnellstart.md:73 („Anmeldung im Admin lokal: `admin` / `admin`“): im geprüften Server-Code keine Seed-Stelle gefunden (nur massenhaft `GetLoginToken("admin","admin")` in Tests). Vermutlich Starter-/Admin-Seed — bitte belegen oder als Starter-Fakt kennzeichnen.
|
||
- P3. Doku-Domäne `*.code.testversion.online` vs. Compose-Label `online.testversion.code.subdomain=…`: Abbildungsregel steht nicht im geprüften Repo-Ausschnitt (nur ein auskommentierter `Host(...code.testversion.online)` in `docker-compose-local.yml`). Bitte Traefik-Regel belegen.
|
||
- P4. betrieb.md:72-74 („Jobs laufen unter der Projekt-UID“, „Quotas und Nutzung landen in der LLM-Nutzungsablage“): Cron-Registrierung belegt (`models/api.go:268`, `models/job.go:4`, `JOB_CONTEXT` in `models/function.go:276`), suexec-Pfad für Jobs und „Nutzungsablage“ nicht explizit nachgewiesen.
|
||
- P5. sicherheit.md:42 („Globales CORS ist auskommentiert“): keine Default-`config.yml` im geprüften Stand gefunden; unbelegt, ob das für alle Deployments gilt.
|
||
- P6. neues-projekt.md:57/71 (`project not found`, `GET /api/v1/project`): String existiert in `internal/filecleanup/cleanup.go:70`, System-Projekt-CRUD via `Project.Middleware` (`models/project.go:206`) ist belegt; ob genau dieser String bei fehlender Registrierung erscheint, nicht end-to-end nachgewiesen.
|
||
- P7. neues-projekt.md:61-64 (Login via `$CODING_TIBIADMIN_URL/api/login`): Admin-Frontend-Proxy-Pfad, nicht gegen `tibi-admin-nova`-Code geprüft (Server-Route ist `POST /api/v1/login`, `setup.go:728`).
|