# Nexus Core Wiki-Quelle

Hier liegen alle Markdown-Quellen fuer die App-Wiki.

## Ziel

Die Wiki wird nicht mehr als einmalig gepflegte HTML-Seite gedacht, sondern als dauerhafte Dokumentationsquelle.

Das bedeutet:

- Jede App-Funktion und jedes Tool bekommt ein eigenes Markdown-Dokument.
- Die API bekommt einen eigenen Bereich mit Route-Dokumentation.
- Screenshots, Beispiel-Eingaben und Schrittfolgen werden direkt an der Quelle dokumentiert.
- Aus diesen Dateien kann die statische App-Wiki jederzeit neu gebaut werden.
- Produktive Wiki-Dateien erhalten zusaetzlich eigene englische und franzoesische Sprachvarianten.

## Verbindliche Ordnerstruktur

```text
wiki/
  wiki-info.md
  app/
    app-index.md
    {Appbereich}/
      {datei}.md
  api/
    api-index.md
    {Bereich}/
      {datei}.md
```

Praktische Beispiele:

```text
wiki/app/dashboard/dashboard.md
wiki/app/filaments/globale-filamente.md
wiki/app/labels/labels-designer.md
wiki/api/filaments/filaments-api.md
wiki/api/system/system-api.md
```

## Pflichtinhalt pro Markdown-Datei

Jede Datei soll moeglichst diese Punkte abdecken:

1. Zweck des Bereichs oder Tools
2. Route oder Einstiegspunkt
3. Wichtige Buttons, Menues und Dialoge
4. Schritt-fuer-Schritt Ablauf
5. Beispiel-Eingaben oder Beispiel-Datensaetze
6. Typische Fehlerbilder oder Stolperstellen
7. Mindestens 3 Bilder
8. gepflegte Sprachvarianten fuer `en` und `fr`, sobald der Bereich im in-app Wiki erscheint

## Bildregeln

Jede groessere Doku-Datei bekommt mindestens 3 Bilder:

1. Gesamtansicht des Bereichs
2. Detailansicht eines relevanten Dialogs, Menues oder Buttons
3. Ergebnisansicht nach dem eigentlichen Arbeitsschritt

Wenn ein Workflow komplex ist, sollen es mehr als 3 Bilder sein.

### Was Bilder zeigen sollen

- Reihenfolge der Klicks
- sichtbare Buttons und Menues
- Beispiel-Eingaben
- den Zustand vor und nach einer Aktion

### Bild-Checkliste

- nur den relevanten Bereich zeigen
- 100 Prozent Browser-Zoom
- klare Beispiel-Daten verwenden
- Light-Theme als Standard, Dark-Theme nur bei Bedarf
- keine zufaelligen Testreste im Bild

## Beispiel-Eingaben

Jede Doku-Datei soll Beispiel-Eingaben enthalten, wenn es Felder oder Filter gibt.

Beispiele:

```text
Hersteller: Cailab
Material: PETG
Variante: Transparent Blue
SKU: CAI-PETG-TRBL-175
EAN: 4260000000002
```

oder:

```text
Lagername: Hauptregal Nord
Code: HN-01
Kapazitaet: 48
```

## App-Bereiche, die dokumentiert werden muessen

Mindestens diese Bereiche muessen eigene Markdown-Dateien bekommen:

- Lokale Installation / Erster Start
- Dashboard
- Globale Filamente
- Filament-Statistik
- Lagerverwaltung
- Spulenverwaltung
- Bewegungen
- Wiegen
- Label Tool
- Label Designer
- Einstellungen
- Statusleiste
- Paketmanager
- Roadmap / Changelog
- Community-Share
- Backup / Import / Export

## Pflicht fuer die Installationsdokumentation

Die Installationsdokumentation ist ein eigener Pflichtbereich und muss mindestens enthalten:

1. Python-Voraussetzung
2. Hinweis, dass die ZIP vollstaendig entpackt werden muss
3. lokalen Start ohne Docker
4. automatisches Erstellen der Datenbank beim ersten Start
5. manuellen Terminal-Start fuer Support-Faelle
6. typische Erststart-Fehler und deren Loesung
7. mindestens 3 Screenshots aus echter Browser- oder Explorer-Ansicht

## API-Bereich

Die API bekommt einen eigenen Wiki-Bereich unter `wiki/api/`.

### API-Dokumentation muss enthalten

Fuer jede Route:

- HTTP-Methode
- Pfad
- Zweck
- benoetigte Eingaben
- typische Rueckgabe
- wie die Route im Ablauf verwendet wird
- welche UI oder welches Tool sie benutzt

### API-Gruppierung

Die API-Doku wird mindestens nach diesen Bereichen getrennt:

- Filamente und Hersteller
- Labels
- Hardware / MQTT / Scale / Firmware
- System / Updates / Bugtracker / Tests / Datasheets
- Spools / Jobs / Reservations

## Pflegeworkflow fuer neue Features

Wenn eine neue Funktion in die App kommt:

1. passenden Doku-Bereich bestimmen
2. neue Markdown-Datei anlegen oder bestehende erweitern
3. Beispiel-Eingaben dokumentieren
4. mindestens 3 Screenshots erstellen
5. API-Route dokumentieren, falls die Funktion eine API nutzt
6. englische und franzoesische Markdown-Dateien nachziehen
7. erst danach statische Wiki neu bauen

## Pflegeworkflow bei UI-Aenderungen

Wenn sich Buttons, Dialoge oder Reihenfolgen aendern:

1. betroffene Markdown-Datei oeffnen
2. Schrittfolge aktualisieren
3. Screenshots erneuern
4. Beispiel-Eingaben pruefen
5. Sprachvarianten angleichen
6. API-Doku pruefen, falls Requests geaendert wurden

## Zielbild fuer den Static-Wiki-Builder

Langfristig wird die statische Wiki direkt aus diesen Markdown-Dateien gebaut.

Die Builder-Pipeline soll:

- `wiki/app/**/*.md` lesen
- `wiki/api/**/*.md` lesen
- daraus die statische App-Wiki erzeugen
- Screenshots aus der App-Wiki-Bildablage einbinden

## Aktueller Bestand

Diese Datei ist die verbindliche Pflegeanweisung. Die eigentlichen Inhalte fuer App und API liegen in den Unterordnern `wiki/app/` und `wiki/api/`.
