Dokumentation: README.md

2026-09-14 15:34:06 +02:00
commit ea5f7eb33d
1 changed files with 685 additions and 0 deletions
@@ -0,0 +1,685 @@
 # ICON CRM
 CRM im ICON Corporate Design. Vite/React-Frontend, Express-Backend, MariaDB.
 Läuft auf <https://icrm.icon-experts.de>.
 Der Aufbau folgt bewusst dem perinco CRM: gleiche Architektur, gleiche
 Deploy-Wege, gleiche Muster für Theme, Dialoge, Erwähnungen und Netzwerkansicht.
 Wer das eine kennt, findet sich im anderen zurecht.
 ## Corporate Identity
 Das Favicon ist die kleine Wortmarke des Hauses, erzeugt aus
 `Draw/Logo klein.png`: `public/favicon.ico` (16/32/48/64 px) und
 `public/favicon.png` (180 px) für den Startbildschirm. Bewusst **keine** SVG:
 die `favicon.svg` der Website ist der violette Blitz des Gerüsts und gehört
 nicht zu ICON.
 | Rolle | Wert |
 | --- | --- |
 | Primärfarbe (Gold) | `#C1862F`, Akzent `#DFA85A` |
 | Gefüllte Knöpfe | `#A06C22` (`brand-600`) – weiße Schrift braucht den dunkleren Ton |
 | Flächen | `#F6F6F7` hell, `#0A0A0A` dunkel |
 | Schrift | Montserrat |
 Die Farbskalen liegen als Tailwind-Theme in `src/index.css` (`brand-*`, `ink-*`)
 sowie die Flächen `canvas` (Seite) und `surface` (Karten, Leisten, Dialoge).
 ## Designs
 Rechts oben im Kopf stehen zwei Umschalter: ein Auswahlfeld für die Farbwelt und
 ein Knopf für hell/dunkel. Beides gilt für den angemeldeten Benutzer – es steht
 an seinem Konto, nicht nur im Browser.
 | Design | Beschreibung |
 | --- | --- |
 | **ICON** | Das Design des Hauses – Gold `#C1862F` auf neutralem Grau, Montserrat. Bewusst ohne Grafik: das Corporate Design bleibt sachlich |
 | **Half-Life** | Black Mesa: HEV-Orange auf Sichtbeton, fast rechtwinklige Ecken, harte versetzte Schatten, Überschriften in Oswald |
 | **Pixel Art** | 8-bit: keine Radien, versetzte Schatten ohne Weichzeichnung, Arcade-Grün, Überschriften in Silkscreen |
 Half-Life und Pixel Art bringen zusätzlich **Grafiken** hinter der Kopfleiste
 (`.app-header`) und dem Menü (`.app-sidebar`) mit – als SVG unter
 `public/themes/`. Die Variable enthält dabei **zwei** Ebenen: einen Schleier aus
 der Flächenfarbe und darunter die Zeichnung. Das ist kein Umweg, sondern der
 Grund, dass dieselbe Grafik in hell und dunkel funktioniert – und die Bedingung
 dafür, dass die Schrift lesbar bleibt: in der Kopfleiste liegt der Schleier an
 den Rändern dicht und lässt die Grafik nur in der Mitte durch, im Menü liegt er
 oben über den Einträgen und gibt nach unten frei.
 Ein Design tauscht ausschließlich Variablenwerte – im Markup steht nirgends eine
 feste Farbe. Deshalb kommen Half-Life und ICON mit derselben Oberfläche aus.
 Zwei Entscheidungen zu Half-Life, weil sie sonst als Versehen aussähen:
 * Der Akzent bleibt **Orange und wird nicht zu Warngelb**. Auf `brand-500` und
  `brand-600` steht überall weiße Schrift; auf Gelb wäre sie nicht mehr lesbar.
  Das Gelb-Schwarz der Gefahrenstreifen kommt deshalb nicht als Fläche vor.
 * **Oswald trägt nur die Überschriften und Feldbeschriftungen**, gesperrt in
  Versalien. Der Fließtext bleibt Montserrat: die Tabellen haben bis zu acht
  Spalten bei 12 px, und eine Schmalschrift wäre darin nicht mehr zu lesen.
  Dasselbe gilt für Silkscreen in Pixel Art.
 Die Liste der Designs steht an zwei Stellen und muss übereinstimmen:
 `THEME_PALETTES` in `src/types.ts` und `THEMES` in `server/src/userFields.js`.
 Das Backend weist einen unbekannten Wert mit 400 ab, damit ein Tippfehler nicht
 still zum Standarddesign führt.
 ## Dunkelmodus
 Umschalter rechts oben im Kopf; die Wahl liegt im `localStorage`
 (`icon_crm_theme_mode`) **und** am Benutzer in der Datenbank, gilt also auf jedem
 Gerät. Ohne Wahl folgt die Anwendung der Systemeinstellung, ein Doppelklick auf
 den Umschalter stellt das wieder her.
 Umgesetzt ist der Modus **ohne `dark:`-Varianten im Markup**: die Klasse `dark`
 auf `<html>` tauscht in `src/index.css` nur die Werte von `canvas`, `surface`,
 `ink-*`, `brand-*` und der getönten Statusfarben. Ein Inline-Skript in
 `index.html` setzt die Klasse vor dem ersten Frame, sonst blitzt beim Laden die
 helle Variante auf.
 ## 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         nur für Administratoren
 ```
 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.
 ## Stammdaten
 *Einstellungen → Stammdaten* (nur Administratoren) pflegt die Auswahllisten, die
 die Formulare speisen: **Branchen** und **Arten der Kontakte**. Beides war vorher
 Freitext bzw. fest im Quelltext; beides wächst im Betrieb.
 Zwei Eigenschaften, die in der Oberfläche stehen, weil man sie beim Pflegen
 kennen muss:
 * **Umbenennen zieht den Bestand mit.** Sonst trüge ein Unternehmen eine
  Branche, die seine Auswahlliste nicht mehr kennt, und das Feld stünde beim
  nächsten Öffnen leer.
 * **Entfernen geht nur, solange ein Wert nirgends benutzt wird.** Hinter jedem
  Eintrag steht deshalb, wie oft er vorkommt.
 Ein Altwert, der nicht mehr in der Liste steht, bleibt im Formular trotzdem
 wählbar – sonst würde er beim nächsten Speichern still verschwinden.
 ## Architektur
 ```
 Browser ──► Apache (:443/:80, icrm.icon-experts.de)
              ├── /            → /var/www/icon_CRM/dist   (SPA, FallbackResource)
              └── /api         → 127.0.0.1:5007           (Express)
                                      └──► MariaDB icon_CRM
 ```
 Der Browser spricht **nie** direkt mit der Datenbank – deshalb das
 Express-Backend. Es bindet ausschließlich auf `127.0.0.1` und ist von außen nur
 über den Apache-Proxy erreichbar. Das ersetzt den früheren Aufbau, bei dem der
 Supabase-Anon-Key im Browser lag und vollen Zugriff auf `icon_users` samt
 Passwort-Hashes hatte.
 ### Datenmodell
 | Tabelle | Inhalt |
 | --- | --- |
 | `icon_users` | Benutzer, Rolle `admin` oder `user`, bcrypt-Hash, Farbe, Foto, Design |
 | `icon_companies` | Unternehmen: Gruppe, Branche, Mitarbeiterzahl, 5-Sterne-Bewertung, `is_customer` + `customer_state` (aktiv/alumni), Freelancer-Einsatz |
 | `icon_contacts` | Kontakte – Experten **und** Ansprechpartner, unterschieden über `kind`; inkl. Lead-Quelle und Kontaktstand |
 | `icon_employments` | Werdegang: wer war wann bei welchem Unternehmen – speist den Zweig „Verlassen" |
 | `icon_interviews` | Wann wurde mit wem gesprochen |
 | `icon_history` | Alle Tätigkeiten: Zeitstempel, Benutzer, Text, Feldänderungen |
 | `icon_mentions` | Index der `@`-Erwähnungen (Quelle → Ziel) |
 | `icon_connections` | Wer kennt wen; Paar aufsteigend gespeichert, Unique-Key verhindert Duplikate |
 | `icon_tenders`, `icon_tender_contacts` | Ausschreibungen und die zugeordneten Kontakte |
 | `icon_projects` | Laufende Projekte |
 | `icon_leads`, `icon_lead_todos` | Lead-Pipeline mit Checkliste und Erinnerungen |
 | `icon_cv_imports` | CV-Import: Eingang, Screening, Auswahl |
 | `icon_options` | Gepflegte Auswahllisten (Branchen, Arten der Kontakte) |
 | `icon_settings` | Schlüssel/Wert, auch für Migrationsmerker |
 Zwei Entscheidungen stecken im Modell:
 * **Ein Kunde ist kein eigener Datentyp**, sondern ein Unternehmen mit
  `is_customer = 1`. Der Umschalter in der Oberfläche filtert nur darauf – es
  gibt keine zweite Liste, die auseinanderlaufen könnte.
 * **Experten und Ansprechpartner liegen in einer Tabelle.** Ein Ansprechpartner,
  der die Firma wechselt und plötzlich als Experte interessant wird, ist
  derselbe Mensch und behält seine Historie.
 ### Rollen
 * `admin` – sieht den Menüpunkt Einstellungen inkl. Nutzerverwaltung
 * `user` – sieht Einstellungen nicht; die API weist Zugriffe zusätzlich mit 403 ab
 Ein Sicherheitsnetz im Backend verhindert, dass der letzte aktive Administrator
 degradiert, deaktiviert oder gelöscht wird. Ausnahme von der Admin-Regel ist
 `GET /api/users/directory`: die Benutzerliste brauchen alle Rollen für
 Erwähnungen, Zuständigkeiten und die Historie. Passwort-Hashes liefert der
 Endpunkt nie.
 ## Struktur
 ```
 src/
  App.tsx                     Layout, gemeinsame Daten, Ansichtswechsel
  types.ts                    Gemeinsame Typen und Konstanten
  lib/api.ts                  Fetch-Wrapper + typisierte Endpunkte
  lib/auth.tsx                Auth-Context (JWT im localStorage)
  lib/theme.tsx               Modus und Design
  lib/navigation.tsx          Karte öffnen aus beliebiger Tiefe
  lib/mentions.tsx            @-Token: Parser, Renderer, Autocomplete
  lib/imageCompress.ts        Bilder im Browser auf 400 px verkleinern
  components/
    Sidebar.tsx, Header.tsx, GlobalSearch.tsx, Toast.tsx, LoginScreen.tsx
    ui/Modal.tsx              Dialog + Bestätigung; Hintergrundklick schließt
    ui/Avatar.tsx             Foto, sonst Initialen; quadratisch für Logos
    ui/AvatarPicker.tsx       Upload, LinkedIn-Abruf, Entfernen
    ui/StarRating.tsx         5-Sterne-Bewertung der Unternehmen
    ui/form.tsx               Eingabestile, Knöpfe, Pillen, Umschalter
    settings/MasterData.tsx   Stammdaten: die gepflegten Auswahllisten
    contacts/                 Liste, Kacheln, Netzwerk, Karte mit Werdegang
    companies/                Liste, Kacheln, Group, Netzwerk
    network/Network.tsx       Die Netzwerkansicht beider Listen (d3-force + SVG)
    leads/                    Pipeline als Kanban, Archiv, Erinnerungen
    tenders/Tenders.tsx       Tabelle mit aufklappbarer Zeile (wie im Original)
    tenders/TenderText.tsx    Ausschreibungstext (WYSIWYG + KI) auf `notes`
    tenders/LiveBoard.tsx     Ansicht „Live!" – Kanban über die Phasen
    projects/                 Laufende Projekte
    history/                  Reiter Historie und der Verlauf je Karte
    dashboard/, settings/
 server/
  src/server.js               Express-App
  src/db.js                   Pool, Schema-Init, Admin-Seed
  src/schema.sql              Idempotentes Schema
  src/history.js              Historie schreiben, Erwähnungen indizieren
  src/migrate.js              Einmalige Übernahme aus Supabase
  src/linkedinPhoto.js        Profilfoto aus der Open-Graph-Vorschau
  src/middleware/auth.js      JWT-Prüfung, Admin-Wächter
  src/routes/                 auth, users, companies, contacts, tenders,
                              projects, history, search, network, connections,
                              dashboard
 deploy/
  icon-crm-backend.service    systemd-Unit
  icrm.icon-experts.de.conf   Apache-Vhost
  deploy.ps1                  Build lokal, Upload, Neustart
 legacy/                       Der alte Supabase-Stand, nur zum Nachschlagen
 ```
 ## Kleinigkeiten mit Absicht
 * **„Zuständig" ist beim Anlegen mit dem angemeldeten Benutzer vorbelegt** – in
  aller Regel kümmert sich der, der den Datensatz erfasst. Ändern geht weiter.
 * **Erwähnungen sind anklickbar.** Im Eingabefeld steht der rohe Token
  `@[Name](contact:12)` – anders ließe sich der Text nicht bearbeiten. Darunter
  steht deshalb die Lesefassung, und dort führt jede Erwähnung auf das Profil.
 ## Historie und Erwähnungen
 Jede schreibende Route ruft `logHistory()` auf, statt selbst in `icon_history` zu
 schreiben. Dadurch gilt an einer Stelle, was überall gelten soll: **in jeder
 Historie steht, welcher Benutzer was geändert hat.** Bei einer Änderung werden
 zusätzlich die betroffenen Felder mit Vorher/Nachher abgelegt.
 Erwähnungen stehen als Token im Text: `@[Anzeigename](contact:12)`, ebenso für
 `company` und `user`. Der Name steht mit im Token, damit ein Text auch ohne
 geladene Listen lesbar bleibt; beim Rendern gewinnt der aktuelle Name. Jede
 Erwähnung wird zusätzlich in `icon_mentions` indiziert – deshalb kann eine Karte
 zeigen, wo sie überall genannt wurde, ohne jeden Freitext der Datenbank zu
 durchsuchen.
 Ein Arbeitgeberwechsel erzeugt drei Einträge von selbst: beim alten Unternehmen
 „hat das Unternehmen verlassen", beim neuen „ist jetzt hier tätig", beim Kontakt
 den Wechsel. Daraus speist sich der Zweig **Verlassen** im Stammbaum.
 ## Globale Suche
 Ein Feld, zwei Modi – umgeschaltet über die beiden Symbole rechts im Feld:
 **Lupe – die normale Suche** (`Strg+K`). Über Kontakte, Unternehmen,
 Ausschreibungen, Projekte, Leads und die Historie; läuft beim Tippen mit, ein
 Treffer öffnet direkt die Karte. Bewusst `LIKE` statt Volltextindex: die
 Datenmengen sind klein, und ein `FULLTEXT`-Index würde bei Teilwortsuche –
 „informat" soll „Finanz Informatik" finden – nicht helfen.
 **Funke – die erweiterte Suche.** Eine Frage in Worten, beantwortet von
 `gpt-5.6-luna`: *„Wer arbeitet alles bei der KfW?"* → „Bei der KfW ist Gunther
 Stammwitz als Ansprechpartner hinterlegt." Die genannten Datensätze kommen als
 anklickbare Chips zurück und öffnen ihre Karte.
 Sie läuft **nicht** beim Tippen mit, sondern erst auf Enter – jede Anfrage
 kostet. Und sie erzeugt **kein SQL**: der Bestand wird zusammengefasst und
 mitgegeben (`server/src/routes/search.js`). Ein Modell, das Abfragen auf die
 Datenbank schreiben darf, wäre eine Angriffsfläche; der Bestand ist klein genug,
 um ihn vollständig mitzuliefern. Ab 400 Zeilen je Liste wird gekürzt, und die
 Antwort sagt das dazu.
 ## KI
 Modell: **`gpt-5.6-luna`** (OpenAI), angesprochen über `chat/completions`.
 Schlüssel und Modell stehen ausschließlich in `server/.env` (chmod 600) – der
 Browser spricht nie direkt mit OpenAI, jede Anfrage läuft über das Backend
 (`server/src/ai.js`). Fehlt der Schlüssel, läuft das CRM normal weiter und
 blendet die KI-Knöpfe aus.
 > **Fallstrick:** `gpt-5.6-luna` akzeptiert kein eigenes `temperature` und weist
 > jeden Wert außer dem Standard mit HTTP 400 ab. `ai.js` schickt deshalb keines.
 ### CV-Import
 *Kontakte → CV-Import.* Lebensläufe als PDF, DOCX oder Text, per Dateiauswahl
 oder Ziehen, auch mehrere auf einmal (bis 20, je 15 MB). Der Ablauf folgt der
 Featureliste als drei Ordner:
 | Ordner | Bedeutung |
 | --- | --- |
 | Eingang | hochgeladen; ein Mensch entscheidet je Datei „Ja, auslesen“ oder „Nein“ |
 | Screening | ausgelesen; der Vorschlag steht im Formular und wird bestätigt |
 | Auswahl | übernommen – Kontakt angelegt, Lebenslauf hängt daran |
 Es wird bewusst **nichts automatisch angelegt**: ein falsch gelesener Name oder
 Stundensatz wäre in der Datenbank schwerer zu finden als im Formular. Was dort
 korrigiert wird, gewinnt gegen die KI.
 Übernommen werden Name, Position, Kontaktdaten, LinkedIn, aktueller Arbeitgeber,
 Schlagworte, eine Zusammenfassung und – nur wenn sie ausdrücklich im Text stehen
 – die Stundensätze. Frühere Stationen werden als **beendete** Anstellungen
 angelegt; dadurch erscheint der Kontakt beim jeweiligen Unternehmen sofort im
 Zweig „Verlassen“. Unbekannte Unternehmen legt der Import mit an.
 Die Datei bleibt am Kontakt (`icon_contacts.cv_file`) und lässt sich aus dessen
 Karte herunterladen. Der Download läuft über `fetch` mit Bearer-Kopf – ein
 normaler Link schickt ihn nicht mit.
 ### Schreibhilfe für Ausschreibungen
 Das Feld *Ausschreibungstext* (also `icon_tenders.notes`, siehe unten) ist ein
 WYSIWYG-Editor (`components/ui/RichTextEditor.tsx`) mit fünf Knöpfen: *Text erzeugen*,
 *Verbessern*, *Kürzen*, *Stichpunkte*, *Anforderungsprofil*. Darunter ein Feld
 für die Vorgabe („Interim PL SAP S/4HANA, Bank, 12 Monate, 80 % remote“). Der
 vorherige Stand lässt sich mit *Zurück* zurückholen – die KI überschreibt nichts
 unwiderruflich.
 Der Editor kommt ohne Fremdpaket aus: Quill & Co. bringen ihr eigenes
 Farbschema mit, das im Dunkelmodus gegen die Variablen dieser Anwendung
 arbeitet, und kosten über 200 kB. Gebraucht werden sechs Formate – das leistet
 `contentEditable`. Eingefügter Text wird bewusst entformatiert: aus Word oder
 einem Portal kämen sonst fremde Schriftgrößen und `<span style>`-Wolken mit.
 ### Erweiterte Suche und die Sätze
 Die Frage „wer hat den höchsten Satz?" ging lange ins Leere: der Bestand, den
 die erweiterte Suche mitbekommt, enthielt die Felder `rate_onsite` und
 `rate_remote` gar nicht. Sie sind jetzt dabei, zusammen mit Kontaktstand und
 LinkedIn.
 Zwei Dinge stehen dafür ausdrücklich im Systemprompt, weil das Modell sie sonst
 falsch beantwortet:
 * Ein fehlender Satz ist **nicht** null Euro. Verglichen wird nur, wo ein Wert
  steht, und die Antwort sagt dazu, bei wie vielen keiner hinterlegt ist.
 * Es sind **Stundensätze**. Fragt jemand nach einem Tagessatz, antwortet die
  Suche mit dem Stundensatz und sagt das dazu.
 > **Zur Benennung:** Die Felder heißen `rate_onsite`/`rate_remote` und stammen
 > aus `hourlyRateOnsite`/`hourlyRateRemote` des alten CRM, das sie als
 > „Stundensatz Onsite (€)" beschriftet und als `€/h` angezeigt hat. Das neue
 > CRM hatte sie zwischenzeitlich „Tagessatz" genannt – bei Werten bis 165 €
 > wäre das ein sehr günstiger Tag gewesen. Beschriftung und Anzeige tragen die
 > Einheit jetzt überall mit.
 ## Diktat (Whisper im Browser)
 Überall dort, wo längerer Text entsteht – Notiz am Kontakt, Notizen an Lead,
 Unternehmen und Projekt, Ausschreibungstext – sitzt ein Mikrofon-Knopf. Die
 Erkennung läuft **vollständig im Browser**: das Backend sieht keine Audiodaten,
 es gibt keinen Schlüssel und keine Kosten pro Minute. Aufnahmen werden nirgends
 gespeichert.
 Übernommen aus dem perinco CRM, 1:1 in der Technik:
 | Teil | Datei |
 | --- | --- |
 | Modellverwaltung, Zustand, Cache | `src/lib/whisper.tsx` |
 | Erkennung im Web Worker | `src/lib/whisper.worker.ts` |
 | Aufnahme (MediaRecorder) | `src/lib/dictation.tsx` |
 | Umrechnung auf 16 kHz Mono | `src/lib/audio.ts` |
 | Downloadgröße bei Hugging Face | `src/lib/whisperModels.ts` |
 | Knopf und Textfeld | `src/components/ui/Dictate.tsx` |
 | Reiter *Einstellungen → Diktat* | `src/components/settings/WhisperSettings.tsx` |
 Festgelegt und nicht einstellbar: `onnx-community/whisper-large-v3-turbo`, `q4`,
 Sprache Deutsch, Grafikkarte wenn vorhanden (WebGPU), sonst CPU (WASM). Die
 Begründung dazu steht im Kopf von `src/lib/whisper.tsx` – kurz: kleinere Modelle
 verlieren genau bei den Fachbegriffen, andere Genauigkeiten scheitern am
 Speicher oder liefern auf der Grafikkarte Unsinn.
 Das Modell wird **einmal je Browser** geladen (rund 300 MB) und liegt danach im
 Cache-Speicher der Seite; die ONNX-Laufzeit liefert das Build selbst aus
 (`dist/assets/ort-wasm-simd-threaded.jsep-*.wasm`, 21 MB). Ist es im Cache,
 stellt sich das Diktat beim Anmelden von selbst bereit – ein Download von 300 MB
 startet nie unaufgefordert. *Einstellungen → Diktat* zeigt den Zustand, eine
 Probeaufnahme und den Weg, das Modell wieder loszuwerden.
 Erkannter Text wird **angehängt**, nie ersetzt: in den WYSIWYG-Feldern als
 eigener Absatz am Ende, in den Textfeldern hinter dem vorhandenen Text. Ohne
 Mikrofon oder ohne HTTPS bleibt der Knopf unsichtbar, ohne geladenes Modell
 steht dort *Diktat einrichten* und führt direkt in den Reiter.
 ## Ausschreibungen und die ICON Website
 Die Ansicht ist bewusst so aufgebaut wie im ursprünglichen ICON CRM: eine
 Tabelle, deren Zeile sich aufklappt – links die zugewiesenen Experten und der
 Kundenkontakt, rechts der Ausschreibungstext.
 Zwei Dinge sind dabei keine Kosmetik, sondern hängen an der Website:
 * **Der Ausschreibungstext steht in `icon_tenders.notes`**, als HTML. Nicht in
  `details` – dieses Feld ist im gesamten Bestand leer und bleibt ungenutzt. Wer
  den Editor auf `details` legt, zeigt ein leeres Feld und schreibt am
  veröffentlichten Text vorbei.
 * **`online` entscheidet, ob eine Ausschreibung auf der Website erscheint.** Der
  Schalter sitzt deshalb direkt in der Liste, einen Klick entfernt.
 Gespeichert wird der Text automatisch, 800 ms nach dem letzten Tastendruck –
 wie zuvor auch, es gibt keinen Speichern-Knopf.
 Das Kanban über die Phasen ist nicht Teil dieser Ansicht, sondern steht als
 **Live!** im Menü. Anders als früher ist es bearbeitbar: eine Kachel lässt sich
 in eine andere Spalte ziehen, und der Wechsel landet in der Historie.
 ### Die ICON Website
 Seit dem 14.09.2026 liegt die Website **auf demselben Server** wie das CRM
 (`/var/www/icon_website/dist`, Vhost `icon-experts.de` + `www`). Vorher lief sie
 auf `212.227.135.41` – derselben Maschine wie perinco CRM, n8n, Docker, Supabase
 und ein halbes Dutzend weiterer Dienste, bei 5,5 von 7,9 GB belegtem RAM.
 Der Vhost reicht **`/api/public` an das CRM-Backend durch**. Das ist kein
 Schönheitsfehler, sondern der Grund, warum die Content-Security-Policy der Seite
 weiter mit `connect-src 'self'` auskommt: der Aufruf ist gleicher Herkunft.
 Zeigte die Seite direkt auf `icrm.icon-experts.de`, müsste dieser Host in der CSP
 stehen und der Browser bräuchte einen CORS-Vorabruf. Durchgereicht wird
 ausschließlich `/api/public` – Anmeldung, Kontakte und Leads bleiben von der
 Website aus unerreichbar.
 ### Öffentliche Schnittstelle für die Website
 `GET /api/public/tenders` – ohne Anmeldung, nur Lesen, nur Zeilen mit
 `online = 1`, neueste zuerst. Dazu `GET /api/public/tenders/:id` für einen
 direkten Link. Beide antworten mit `Access-Control-Allow-Origin: *` und
 `Cache-Control: public, max-age=60`.
 Ausgeliefert werden genau die Felder, die die Projektbörse anzeigt:
 ```json
 [{ "id": 8, "title": "…", "status": "Aktiv", "notes": "<h2>…</h2>",
   "created_at": "…", "updated_at": "…" }]
 ```
 **Nicht** ausgeliefert werden der zugeordnete Kunde, die zugewiesenen Experten,
 die Quelle, Fristen und die Phase. Das ist der eigentliche Gewinn gegenüber dem
 vorherigen Weg: die Website las mit dem Supabase-Anon-Key direkt in der Tabelle
 und durfte `select('*')` – der Schlüssel lag dafür im Browser-Bundle.
 Auf Seiten der Website (`D:\Vibe Coding\ICON Website`) hängt das an
 `src/lib/iconCrm.js`; `src/pages/Experts.jsx` ruft nur noch `fetchTenders()`
 auf. Die Adresse lässt sich über `VITE_ICON_CRM_URL` umbiegen, Vorgabe ist
 `https://icrm.icon-experts.de`. `@supabase/supabase-js` und `src/lib/supabase.js`
 werden dort seither nirgends mehr benutzt und könnten entfallen.
 > **Zwei Bedingungen, nicht eine:** `online = 1` **und** nicht archiviert. Im
 > Altbestand steht eine archivierte Ausschreibung, deren Schalter noch an ist –
 > über Supabase war sie unsichtbar, über diesen Endpunkt wäre sie mit der
 > Kategorie „Archiviert" auf der Website aufgetaucht.
 ## Kontakte aus dem perinco CRM
 *Kontakte → Schalter „perinco".* Die Kontakte des perinco CRM werden zusätzlich
 angezeigt – **grün umrandet**, rein lesend, und **nichts davon wird
 gespeichert**. Ein nächtlicher Abgleich in die eigene Datenbank wäre der falsche
 Weg: dann stünde derselbe Mensch in zwei Systemen, und irgendwann wäre zu
 klären, welcher Eintrag gilt.
 Das gilt **in beide Richtungen**, gleich gebaut:
 ```
 ICON  ──HTTPS + Token──► pcrm.perinco.de/api/integrations/contacts  ──► crm_leads
 perinco ──HTTPS + Token──► icrm.icon-experts.de/api/integrations/contacts ──► icon_contacts
 ```
 Im ICON CRM erscheinen die perinco-Kontakte **grün** umrandet (Häkchen
 „perinco" in den Kontakten), im perinco CRM die ICON-Kontakte **gold**
 (Häkchen „ICON"). Beide Seiten speichern nichts, beide kennen nur `GET`.
 Auf perinco-Seite (`server/src/routes/integrations.js`) hängt ein eigener
 Router mit festem Token statt JWT – der Aufrufer ist das ICON-Backend, kein
 angemeldeter Mensch. Nur `GET`, kein Schreibweg, auch später nicht. Der Token
 steht dort als `ICON_API_TOKEN`, hier als `PERINCO_API_TOKEN`.
 **Wer weitergegeben wird, entscheidet ein Häkchen im perinco CRM.** Dort trägt
 jeder Kontakt das Feld *„Im ICON CRM anzeigen“* (`crm_leads.icon`); nur wer es
 gesetzt hat, taucht hier auf. Die Weitergabe ist damit eine Entscheidung am
 einzelnen Datensatz und nicht die Folge davon, dass ein Kontakt existiert.
 Beim Anlegen der Spalte wurden alle vorhandenen Kontakte auf gesetzt gestellt –
 sie waren bis dahin hier sichtbar, und ein Feld einzuführen darf nichts
 verschwinden lassen. **Neue Kontakte starten ungesetzt.**
 Abgebildet wird auf die **vorhandenen** Felder eines ICON-Kontakts; neue Felder
 wurden ausdrücklich keine angelegt:
 | perinco `crm_leads` | ICON |
 | --- | --- |
 | `first_name`, `last_name`, `position` | gleichnamig |
 | `company` | wird als Unternehmensname angezeigt |
 | `email`, `phone` bzw. `mobile` | `email`, `phone` |
 | `linkedin`, `avatar`, `tags` | gleichnamig |
 | `kind` (Recruiter/Partner/Endkunde) | `kind` – **unverändert**, nicht auf die ICON-Arten umgebogen |
 | `source` | `lead_source` |
 | `notes` | `bio` |
 Bleiben drüben, weil ICON bei Kontakten kein Gegenstück hat: Anrede, Website,
 Anschrift. Ebenso Zuständiger und Ersteller – das sind Benutzer *jenes* Systems,
 deren Kennungen hier nichts bedeuten. Kontakte im Vorbereich „Aus Mails"
 (`mail_pool = 1`) bleiben ebenfalls außen vor: unvollständig und teils Dubletten.
 Die Kennung bekommt ein Präfix (`perinco-31`), damit sie nie mit einer
 ICON-Kennung verwechselt wird. Ohne eingerichtete Schnittstelle bleibt der
 Schalter unsichtbar – ein Knopf, der nur eine Fehlermeldung erzeugt, ist keiner.
 In der **Netzwerkansicht** erscheinen sie mit, solange der Schalter an ist:
 grün umrandete Kreise, über eine fein gestrichelte grüne Kante an ihr
 Unternehmen gehängt. Die Verbindung läuft über den **Firmennamen**, denn drüben
 steht dort nur Text und keine Kennung – groß/klein wird ignoriert, damit „KfW“
 und „KFW“ zusammenfinden. Passt kein Name, steht der Kontakt für sich; das ist
 ehrlicher als eine geratene Zuordnung. Verbinden lassen sie sich nicht, und ihre
 Seitenleiste bietet keine Karte an – gepflegt werden sie drüben.
 ## Lead-Pipeline
 Kanban über acht Phasen (*Backlog* bis *Absage*) mit Drag & Drop. Eine Kachel
 trägt die Daten des Unternehmens und des Ansprechpartners, den Kontaktstand, den
 Stand der Checkliste und die nächste Erinnerung. Auf jeder Kachel sitzen zwei kleine Knöpfe: ein
 **Aktenschrank** (archivieren) und ein roter **Mülleimer** (löschen, mit
 Rückfrage). Archiviertes steht im Menü unter *Leads → Archiviert* und lässt sich
 von dort zurückholen.
 Die Karte eines Leads hat drei Reiter: Stammdaten (inkl. Erinnerung), **ToDos**
 als Checkliste mit Fälligkeitsdatum und Fortschrittsbalken in Prozent, und die
 Historie.
 **Erinnerungen** gibt es in zwei Formen, beide als Pop-up, das sich unabhängig
 von der offenen Ansicht meldet (`components/leads/ReminderWatcher.tsx`, Abfrage
 beim Anmelden und danach stündlich):
 * **gesetzt** – „in 2 Tagen anrufen“. Eingegeben werden Tage, nicht ein Datum;
  gerechnet wird auf dem Server, sonst hinge das Ergebnis an der Zeitzone des
  Browsers. Quittieren heißt *Erledigt* oder *in n Tagen erneut*.
 * **automatisch** – wird ein Lead 30 Tage nicht angefasst, fragt das CRM, ob er
  archiviert werden soll. Wird er das nicht, läuft die Frist von vorn: das
  Quittieren setzt `last_contact_at` auf jetzt. Jede Bearbeitung des Leads gilt
  ebenfalls als Berührung – nur das Umsortieren innerhalb einer Spalte nicht.
 ## Netzwerkansicht
 Sie ist **kein eigener Menüpunkt**, sondern die Netzwerk-Ansicht der Kontakte
 und der Unternehmen – wie im perinco CRM. Beide Listen reichen ihre Filter
 durch, es sind also dieselben Daten, nur anders gezeichnet. In den Kontakten
 lassen sich zusätzlich Verbindungen anlegen: *Verbindung erstellen*, dann zwei
 Kontakte anklicken; Esc bricht ab.
 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 Linie** = hat dort gearbeitet
 * **Feine Linie** = Kontakt kennt Kontakt
 Hintergrund ziehen verschiebt, Mausrad zoomt auf den Zeiger, Knoten ziehen
 fixiert ihn (goldener Punkt), Doppelklick löst die Fixierung, Klick auf freie
 Fläche hebt die Auswahl auf. Damit das Verschieben nicht versehentlich die
 Auswahl verwirft, gilt eine Geste erst ab 4 px Weg als Ziehen.
 ### Stammbaum eines Unternehmens
 Ein Klick auf ein Unternehmen, an dem Kontakte hängen, öffnet dessen Stammbaum
 (`components/network/CompanyTree.tsx`): das Unternehmen oben, die Kontakte
 darunter, verbunden durch Äste. Die Farbe des Astes sagt, welcher Art die
 Verbindung ist:
 | Ast | Bedeutung |
 | --- | --- |
 | **golden** | Berater – Kontaktart „Experte" |
 | **hell** | normale Verbindung – Ansprechpartner und übrige Kontakte |
 | **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.
 Erst unter den heutigen wird zwischen Berater und übrigen unterschieden. Wer
 wieder hier arbeitet, steht nicht zusätzlich unter „Ehemalige".
 Der graue Ast ist zusätzlich **gestrichelt**, und die normale Verbindung nimmt
 `ink-700` statt reinem Weiß: im hellen Modus wäre ein weißer Ast auf weißem
 Grund unsichtbar, und ohne die Strichelung lägen Grau und Neutral dort zu nah
 beieinander. Im Dunkelmodus ist `ink-700` nahezu weiß – dort sieht es aus wie
 gedacht.
 Passen nicht alle Kontakte nebeneinander, bricht die Reihe um; jede Zeile wird
 für sich mittig ausgerichtet. Ein Klick auf einen Kontakt öffnet dessen Karte,
 *Zurück zum Netz* führt in die Kräfteansicht zurück.
 ## 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 ein Quadrat von 400 px, WebP mit Qualität 0,82, Rückfall JPEG, dann PNG. Das
 Backend akzeptiert nur Bild-Data-URLs und http(s)-Adressen und begrenzt die
 Länge.
 Trägt man beim Kontakt eine LinkedIn-Adresse ein, holt der Knopf *Von LinkedIn*
 das öffentliche Profilfoto. Den Abruf macht das Backend
 (`server/src/linkedinPhoto.js`) – aus dem Browser heraus stünde die
 Same-Origin-Policy davor. Gelesen wird **ausschließlich** die
 Open-Graph-Vorschau der öffentlichen Profilseite; der übrige Quelltext wird nicht
 durchsucht, weil dort auch Firmenlogos und fremde Profilbilder stehen.
 ## Migration aus dem alten CRM
 `server/src/migrate.js` übernimmt den Supabase-Bestand einmalig.
 ```bash
 cd /var/www/icon_CRM/server
 SUPABASE_URL=https://icondb.perinco.de SUPABASE_KEY=<anon-key> node src/migrate.js
 SUPABASE_URL=https://icondb.perinco.de SUPABASE_KEY=<anon-key> node src/migrate.js --write
 ```
 Ohne `--write` ist es ein Probelauf: er liest, rechnet die Zuordnung aus und
 zeigt, was passieren würde. Wiederholbar – Unternehmen und Kontakte werden über
 ihren Namen wiedererkannt.
 Abbildung der Altdaten:
 | alt | neu |
 | --- | --- |
 | `icon_customers` | `icon_companies` mit `is_customer = 1` |
 | `icon_contacts` | `icon_contacts`, `kind = 'Ansprechpartner'` |
 | `icon_experts` | `icon_contacts`, `kind = 'Experte'` |
 | Status `Verfügbar` | `Interessiert` – der Verfügbarkeitsstatus ist entfallen |
 | `kanbanStatus: Experten sichten` | Phase `Kontakte sichten` |
 **Passwörter:** im alten CRM lagen sie als ungesalzenes SHA-256 in Supabase. Die
 Hashes werden übernommen und sind an ihrer Form erkennbar (64 Hexziffern). Beim
 ersten erfolgreichen Login schreibt das Backend sie auf bcrypt um – danach gilt
 nur noch der starke Hash. Neu vergeben wird ausschließlich bcrypt.
 ## Lokale Entwicklung
 ```bash
 npm install
 cd server && npm install && cp .env.example .env   # Werte anpassen
 npm start                                          # Backend :5007
 cd .. && npm run dev                               # Frontend :3101, /api wird geproxied
 ```
 Lokal braucht es eine erreichbare MariaDB mit der Datenbank `icon_CRM`; das
 Schema legt das Backend beim Start selbst an.
 ## Deployment
 Gebaut wird **lokal**, auf den Server gehen nur `dist/` plus Backend-Quellen.
 ```powershell
 $env:ICON_CRM_SSH_PASSWORD = '…'
 powershell -File deploy/deploy.ps1
 powershell -File deploy/deploy.ps1 -Deps   # bei neuen Backend-Paketen
 ```
 ### Serverseitige Einrichtung (einmalig, bereits erledigt)
 ```bash
 apt-get install -y apache2 mariadb-server certbot python3-certbot-apache nodejs
 a2enmod proxy proxy_http rewrite headers expires
 mariadb -e "CREATE DATABASE icon_CRM CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
 mariadb -e "CREATE USER 'iconcrm'@'localhost' IDENTIFIED BY '…';
            GRANT ALL PRIVILEGES ON icon_CRM.* TO 'iconcrm'@'localhost';"
 cd /var/www/icon_CRM/server && npm install --omit=dev
 cp deploy/icon-crm-backend.service /etc/systemd/system/
 systemctl daemon-reload && systemctl enable --now icon-crm-backend
 cp deploy/icrm.icon-experts.de.conf /etc/apache2/sites-available/
 a2ensite icrm.icon-experts.de && systemctl reload apache2
 certbot --apache -d icrm.icon-experts.de
 ```
 Die Firewall (`ufw`) lässt 22, 80 und 443 durch. Das Zertifikat erneuert ein
 Zeitplan von certbot selbst; es ist ohne Kontaktadresse ausgestellt, es kommen
 also keine Ablaufwarnungen per Mail.
 ## Zugang
 Beim ersten Backend-Start wird ein Administrator aus den `ADMIN_*`-Variablen in
 `server/.env` angelegt – aber nur, solange `icon_users` leer ist. Danach ist das
 Passwort ausschließlich über die Nutzerverwaltung bzw. *Mein Konto* änderbar.
 ## Was noch offen ist
 Aus der Featureliste vom 14.09.2026 stehen noch aus – jeweils mit dem, was dafür
 gebraucht wird:
 | Offen | Was fehlt dafür |
 | --- | --- |
 | Scraper für Stellenausschreibungen | Quellen von Kai; Technik läge mit dem Projekt Scanner des perinco CRM bereits vor (Playwright + Bewertung) |
 | Morgenlage („Morning Post") aus den zuletzt genannten Unternehmen | Recherchequelle und Zustellweg; Datengrundlage und Modell stehen (`icon_mentions` + `icon_history`, `ai.js`) |
 | Foto aus dem Lebenslauf ziehen | In der Featureliste als „ggf." vermerkt. Aus DOCX wäre es machbar (eingebettete Medien), aus PDF nur mit zusätzlicher Bibliothek |
 | Design *Duke Nukem 3D* | Nur die Farbwerte – Umschalter, Speicherung am Benutzer und die CSS-Haken stehen. Bis dahin bewusst **nicht** in der Auswahl: ein Design, das nichts ändert, sieht nach Fehler aus |