# 03 Frontend

React 19 mit TypeScript, gebaut von Vite 6, gestaltet mit Tailwind 4. Eine
einzige Seite; Apache liefert sie über `FallbackResource` für jeden Pfad aus.

## Menü

```
Dashboard
Leads                 Pipeline als Kanban
  └ Archiviert        alles, was per Aktenschrank weggelegt wurde
Kontakte
Unternehmen
Ausschreibungen       Tabelle; nur der laufende Bestand
  ├ Live!             Kanban über die Phasen
  └ Archiv            archivierte Ausschreibungen, von dort zurückholbar
Laufende Projekte
Historie
Einstellungen
```

Die Unterpunkte klappen auf, sobald ein Punkt des Zweigs benutzt wird. Dauerhaft
ausgeklappt wäre die Leiste doppelt so lang, und Archive schaut man selten an.

Die **Netzwerkansicht ist kein Menüpunkt**, sondern eine Ansicht innerhalb von
Kontakten und Unternehmen – genau wie im perinco CRM.

## Komponentenkarte

```mermaid
flowchart TD
    M["main.tsx<br/>AuthProvider, ThemeProvider, ToastProvider,<br/>OptionsProvider, WhisperProvider"] --> A["App.tsx<br/>Ansichtswechsel, gemeinsame Daten"]
    A --> SB["Sidebar"]
    A --> HD["Header<br/>Suche, Design, hell/dunkel, Konto"]
    A --> V{"Ansicht"}
    V --> DSH["dashboard/"]
    V --> LDS["leads/<br/>Kanban, Karte, ToDos, Erinnerungen"]
    V --> KON["contacts/<br/>Liste, Kacheln, Netzwerk, CV-Import"]
    V --> UNT["companies/<br/>Liste, Kacheln, Group, Netzwerk"]
    V --> AUS["tenders/<br/>Tabelle, Live!, Archiv"]
    V --> PRJ["projects/<br/>Kacheln, Karte, Marge"]
    V --> HIS["history/"]
    V --> SET["settings/<br/>Nutzer, Stammdaten, Konto, Diktat"]
    KON --> NW["network/Network.tsx<br/>d3-force + SVG"]
    UNT --> NW
    NW --> CT["network/CompanyTree.tsx"]
```

`projects/margin.ts` rechnet die Marge: Tagessatz des Projekts minus
Stundensatz des Beraters mal acht. Die Rechnung liegt neben der Ansicht und
nicht im Backend, weil sie in der Projektkarte **live** mitlaufen muss – dort
lassen sich Tagessatz und Berater ändern, bevor gespeichert wird. Siehe
`docs/02-datenmodell.md`, Abschnitt `icon_projects`.

Zwei Dinge liegen bewusst in `App.tsx`:

* Die Listen der Unternehmen und Benutzer werden **einmal** geladen und
  weitergereicht – fast jedes Formular braucht sie als Auswahl.
* `open(type, id)` wechselt die Ansicht und reicht die Kennung durch. Damit kann
  jede @-Erwähnung und jeder Suchtreffer die passende Karte öffnen, ohne dass
  die Ebenen dazwischen davon wissen (`src/lib/navigation.tsx`). Dort hängt auch
  `goToSettings(tab)` – der Weg, den der Diktat-Knopf nimmt, wenn das Modell
  noch fehlt.

## Zustand

| Was | Wo |
| --- | --- |
| Angemeldeter Benutzer, JWT | `lib/auth.tsx`, Token im `localStorage` |
| Design und hell/dunkel | `lib/theme.tsx` – am Benutzer **und** im `localStorage` |
| Auswahllisten (Branchen, Arten) | `lib/options.tsx` |
| Spracherkennung | `lib/whisper.tsx` |
| Meldungen | `components/Toast.tsx` |

Es gibt keinen globalen Datenspeicher. Jede Ansicht lädt, was sie braucht, und
meldet über `onChanged` zurück, wenn die gemeinsamen Listen neu gelesen werden
müssen. Bei der Größe des Bestands ist das die einfachere Wahl.

## Designs

Rechts oben zwei Umschalter: Farbwelt und hell/dunkel. Beides gilt für den
angemeldeten Benutzer, nicht nur für den Browser.

| Design | Beschreibung |
| --- | --- |
| **ICON** | Gold `#C1862F` auf neutralem Grau, Montserrat – bewusst ohne Grafik |
| **Half-Life** | Black Mesa: HEV-Orange auf Sichtbeton, harte Schatten, Oswald in den Überschriften |
| **Pixel Art** | 8-bit: keine Radien, versetzte Schatten, Arcade-Grün, Silkscreen in den Überschriften |

Half-Life und Pixel Art bringen Grafiken hinter Kopfleiste und Menü mit (SVG
unter `public/themes/`). Die CSS-Variable enthält dabei **zwei** Ebenen: einen
Schleier aus der Flächenfarbe und darunter die Zeichnung – nur so funktioniert
dieselbe Grafik in hell und dunkel, ohne dass die Schrift verliert.

Ein Design tauscht ausschließlich Variablenwerte; im Markup steht nirgends eine
feste Farbe. Auch der Dunkelmodus arbeitet **ohne `dark:`-Varianten**: die
Klasse `dark` auf `<html>` tauscht in `src/index.css` die Werte von `canvas`,
`surface`, `ink-*`, `brand-*` und den getönten Statusfarben. Ein Inline-Skript
in `index.html` setzt die Klasse vor dem ersten Frame, sonst blitzt die helle
Variante auf.

Die Liste der Designs steht an zwei Stellen und muss übereinstimmen:
`THEME_PALETTES` in `src/types.ts` und `THEMES` in `server/src/userFields.js`.
Ein unbekannter Wert wird vom Backend mit 400 abgewiesen und beim Lesen auf
`null` normalisiert – sonst reicht ein entfernter Palettenname, um die Oberfläche
beim Anmelden abstürzen zu lassen.

## Texte: drei Feldarten

| Art | Komponente | Wo |
| --- | --- | --- |
| WYSIWYG (HTML) | `ui/RichTextEditor.tsx` | Ausschreibungstext, Projektnotizen |
| Text mit @-Erwähnungen | `lib/mentions.tsx` (`MentionField`) | Notizen an Kontakt, Unternehmen, Lead |
| einfacher Text | `ui/form.tsx` | alles Übrige |

Der WYSIWYG-Editor kommt **ohne Fremdpaket** aus: `contentEditable` plus
`document.execCommand` für sechs Formate. Quill & Co. bringen ihr eigenes
Farbschema mit, das im Dunkelmodus gegen die Variablen arbeitet, und kosten über
200 kB.

Aus dem Altbestand kommt HTML mit Inline-Farben, geschützten Leerzeichen und
verschachtelten Listen. `src/lib/richText.ts` räumt es beim Laden zurückhaltend
auf (`sanitize()`): Farbe, Hintergrund, Schriftart und -größe fliegen aus den
Stilangaben, Fett und Kursiv bleiben. Zusätzlich hebt `src/index.css` alle
Inline-Farben im Editor aus – sonst stünde im Dunkelmodus schwarze Schrift auf
weißen Kästen.

**@-Erwähnungen** stehen als Token im Text: `@[Anzeigename](contact:12)`, ebenso
für `company` und `user`. Das Feld hat zwei Zustände: *lesen* (Erwähnungen sind
Knöpfe und führen auf das Profil) und *bearbeiten* (der rohe Token – anders
ließe sich eine Erwähnung nicht setzen oder löschen).

## Netzwerkansicht

Kraftgerichtetes Layout (`d3-force`), gerendert als SVG.

* **Rechtecke** = Unternehmen, Größe nach Anzahl Verbindungen, dunkler Rahmen bei Kunden
* **Kreise** = Kontakte
* **Goldene Linie** = arbeitet dort · **graue gestrichelte** = hat dort gearbeitet
* **Feine Linie** = Kontakt kennt Kontakt
* **Grün umrandete Kreise** = Kontakte aus dem perinco CRM (siehe [06 Schnittstellen](06-schnittstellen.md))

Hintergrund ziehen verschiebt, Mausrad zoomt auf den Zeiger, Knoten ziehen
fixiert ihn, Doppelklick löst die Fixierung. Eine Geste gilt erst ab 4 px Weg
als Ziehen, damit Verschieben nicht die Auswahl verwirft.

> **Falle:** Die Liste der externen Knoten muss **stabil** sein. Ein
> `externals = []` als Vorgabewert erzeugt bei jedem Rendern ein neues Array;
> die Simulation startet dann endlos neu und alle Knoten liegen auf einem Punkt.
> Deshalb steht in `Network.tsx` ein `NO_EXTERNALS` auf Modulebene, und die
> aufrufende Ansicht memoisiert ihre Liste.

### Stammbaum eines Unternehmens

Ein Klick auf ein Unternehmen mit Kontakten öffnet dessen Stammbaum: das
Unternehmen oben, die Kontakte darunter.

| Ast | Bedeutung |
| --- | --- |
| **golden** | Berater – Kontaktart „Experte" |
| **hell** | normale Verbindung – Ansprechpartner und übrige |
| **grau, gestrichelt** | Ehemalige – beendete Anstellung; darunter steht, wo die Person heute ist |

Die Art des Astes ergibt sich aus der **Beziehung**, nicht aus der Person: wer
das Unternehmen verlassen hat, hängt am grauen Ast, auch wenn er Berater ist.

## Fotos

Fotos und Logos liegen als Data-URL in der Datenbank. Der Browser verkleinert
jedes Bild **vor** dem Upload (`src/lib/imageCompress.ts`): mittiger Ausschnitt
auf 400 px im Quadrat, WebP mit Qualität 0,82, Rückfall JPEG, dann PNG.

Der Knopf *Von LinkedIn* holt das öffentliche Profilfoto – über das Backend
(`server/src/linkedinPhoto.js`), weil aus dem Browser die Same-Origin-Policy
davorstünde. Gelesen wird ausschließlich die Open-Graph-Vorschau der
öffentlichen Profilseite.