Files

T

Sascha WolfandClaude Opus 5 6fd713497d feat(postfach): crm@perinco.de lesend anbinden, Kontakte aus Mails

Spiegelt das Vertriebspostfach ueber Microsoft Graph ins CRM. Aus jeder Mail
entstehen Kontakt-Vorschlaege, und jede Mail laesst sich an Opportunities und
Kontakte haengen.

Uebernommen ist die Idee aus dem Altsystem KeepTrack, nicht die Umsetzung:

- Delta Query statt "$filter=isRead eq false" mit anschliessendem PATCH. Damit
  genuegt die Anwendungsberechtigung Mail.Read, es braucht keinen Schreibzugriff
  auf das Postfach, und eine vorher in Outlook geoeffnete Mail geht nicht
  verloren. Der Fortschritt liegt als delta_link in der Datenbank und ueberlebt
  Neustarts; ein Lauf ist gedeckelt und fortsetzbar.
- Tenant- und Client-ID kommen aus der .env, nicht aus dem Browser. Im
  Altsystem konnte jeder Angemeldete das Server-Secret gegen einen fremden
  Tenant verwenden.
- Kontaktdaten werden aus den Graph-Feldern und der Signatur gelesen, ohne
  Sprachmodell. Mailinhalte verlassen den Server nicht.
- Ein Vorschlag ohne E-Mail-Adresse wird nicht mit einer erfundenen Adresse
  angelegt, sondern bleibt zur Durchsicht liegen. Ist die Adresse schon als
  Kontakt vorhanden, werden nur leere Felder ergaenzt.
- Mails haengen als eigene Verknuepfung an Opportunity und Kontakt, nicht als
  Text im Notizfeld - loesbar und mehrfach moeglich.
- Fremdes Mail-HTML wird serverseitig entschaerft und in einem iframe mit
  sandbox="" gezeigt. Externe Bilder sind per CSP gesperrt, damit das Oeffnen
  dem Absender nichts meldet.
- Der Verbindungstest prueft Anmeldung und tatsaechlichen Postfachzugriff und
  benennt den wahrscheinlichen Grund. Der alte Test holte nur ein Token.

Fehlen die MS_*-Werte, startet das CRM normal; die Einstellungen nennen die
fehlende Variable. Neue Tabellen: crm_mail_messages, crm_mail_links,
crm_mail_contact_candidates, crm_mail_sync_state, crm_settings.

Uebernommene Kontakte tragen source = 'Mail'; die Kontaktliste hat dafuer einen
Herkunftsfilter.

Nicht enthalten: Senden, Antworten, Weiterleiten, Anhaenge und die automatische
Zuordnung zu Opportunities.

npm test im Verzeichnis server prueft Kontaktextraktion und Graph-Client
(47 Pruefungen, ohne Framework und ohne Datenbank).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-11 00:06:01 +02:00

16 KiB

Raw Blame History

07 Anleitung fuer Benutzer

Diese Anleitung setzt keine Vorkenntnisse voraus. Sie beschreibt, was die Anwendung tut und wie man sie bedient.

Was die Anwendung ist

Ein CRM fuer die Projektvermittlung. Es beantwortet vier Fragen:

Frage	Bereich
Welche Geschaefte sind in Arbeit und was sind sie wert?	Opportunities
Wer ist wann wo, und wer ist beteiligt?	Kalender
Wen kennen wir, und wer kennt wen?	Kontakte
Welche Projekte auf den Boersen passen zu unseren Beratern?	Scanner

Anmelden

https://pcrm.perinco.de. Anmelden geht mit Benutzername oder E-Mail plus Passwort. Die Sitzung haelt 12 Stunden, danach fragt die Anwendung erneut.

Sagt die Meldung „Benutzername oder Passwort ist falsch", bleibt bewusst offen, welches von beidem nicht stimmte - so kann ueber die Anmeldemaske niemand Benutzernamen durchprobieren.

Es gibt zwei Rollen: Administrator sieht zusaetzlich die Nutzerverwaltung und die Scanner-Einstellungen. Alles andere ist fuer beide Rollen gleich.

Sich zurechtfinden

┌──────────────┬───────────────────────────────────────────┐
│ Kategorien   │  Titel der Ansicht        [Hell/Dunkel]   │
│  Opportunities├──────────────────────────────────────────┤
│  Kalender    │                                           │
│  Kontakte    │   Inhalt                                  │
│  Mails       │                                           │
│  Scanner   ▾ │                                           │
│   Dashboard  │                                           │
│   Unpassend  │                                           │
│   Suchagenten│                                           │
│   Boersen-…  │                                           │
├──────────────┤                                           │
│ Einstellungen│                                           │
├──────────────┤                                           │
│ [Foto] Name  │                                           │
└──────────────┴───────────────────────────────────────────┘

Der Knopf mit den drei Strichen oben links klappt das Menue auf Symbolbreite zusammen - hilfreich auf kleinen Bildschirmen.
Rechts oben schaltet zwischen hellem und dunklem Design. Ein Doppelklick auf den Schalter folgt wieder der Systemeinstellung.
Der Menuepunkt Scanner klappt beim Anklicken seine Unterpunkte auf.

Opportunities

Der Startbereich: eine Opportunity ist ein Geschaeft in Arbeit. Oben rechts wechselt man die Darstellung:

Ansicht	wofuer
Kachel	Ueberblick mit Volumen, Tagessatz, Laufzeit, letzter Interaktion
Liste	viele Eintraege vergleichen, Spaltenkoepfe sortieren
Pipeline	Fortschritt durch die Phasen, Karten per Maus verschieben

Volumen rechnet die Anwendung selbst: Tagessatz x Personentage. Das gewichtete Volumen multipliziert das noch mit der Abschlusswahrscheinlichkeit. Beide Zahlen stehen live im Formular, auf jeder Karte, als Summe ueber der Liste, je Pipeline-Spalte und in der Kopfzeile.

Zu jeder Opportunity gehoeren beliebig viele Ansprechpartner aus den Kontakten, jeder mit eigener Rolle („Entscheider", „Fachbereich", …).

Aendern und loeschen darf der Ersteller, der Zustaendige und jeder Administrator. Wer keines davon ist, bekommt eine Fehlermeldung - das prueft der Server, nicht nur die Oberflaeche.

Auf dem Tablet oder ohne Lust auf Ziehen: die Phase laesst sich auch ueber das Auswahlfeld direkt auf der Karte aendern.

Kalender

Ein gemeinsamer Teamkalender - alle sehen dieselben Termine, jeder darf eintragen.

Monat, Woche, Tag oben umschalten, Heute und die Pfeile blaettern.
Klick auf einen Monatstag oder eine Stundenzelle legt sofort einen Termin an.
Klick auf einen Wochentagskopf springt in die Tagesansicht.
Verschieben per Ziehen: Termin anfassen und auf einen anderen Tag oder eine andere Uhrzeit ziehen. Im Monatsraster wechselt nur der Tag, die Uhrzeit bleibt stehen; in Woche und Tag rastet der Termin auf 15 Minuten ein, und eine gestrichelte Linie zeigt vorab die neue Startzeit. Die Dauer bleibt immer gleich, und der Punkt, an dem man den Termin angefasst hat, wandert mit. Ziehen darf nur, wer den Termin auch aendern darf.
Farben gehoeren zum Ersteller. Die eigene Farbe aendert man unter Einstellungen → Mein Konto; die Legende unter dem Kalender zeigt, welche Farbe zu wem gehoert.
Teilnehmer erscheinen mit Foto oder Initiale und sind anklickbar.
@-Erwaehnungen: In der Beschreibung @ tippen, dann Kontakte und Benutzer aus der Vorschlagsliste waehlen (Pfeiltasten, Enter). In der Leseansicht sind sie klickbar - Kontakte oeffnen die Kontaktkarte, Benutzer ein Detailfenster mit naechsten Terminen.
Rechts stehen die naechsten Termine, nach Tagen gruppiert. Vergangenes fliegt aus der Liste, bleibt im Kalender aber erhalten.

Aendern und loeschen darf nur der Ersteller oder ein Administrator. Anlegen darf jeder.

Kontakte

Drei Ansichten, davon eine besondere:

Ansicht	wofuer
Kachel	Ueberblick mit Foto, Firma, Status
Liste	sortierbar, viele Eintraege
Netzwerk	wer steht mit wem in Kontakt

Im Netzwerk sind Kreise Kontakte (Farbe = Status, Groesse = Anzahl Verbindungen) und Quadrate Benutzer, die Kontakte angelegt haben. Gruene Linien verbinden Kontakte untereinander, graue gestrichelte den Ersteller mit seinem Kontakt.

Bedienung: Hintergrund ziehen verschiebt, Mausrad zoomt, einen Knoten ziehen setzt ihn fest (gruener Punkt), Doppelklick loest ihn wieder. Ueber Verbindung erstellen zwei Kontakte anklicken, um eine Verbindung anzulegen; Esc bricht ab. Suche und Statusfilter wirken auch hier.

Sobald Kontakte aus dem Postfach uebernommen wurden, erscheint neben dem Statusfilter ein Herkunftsfilter: Aus Mails zeigt nur die automatisch entstandenen, Selbst angelegt nur die von Hand erfassten.

Mails

Das gemeinsame Postfach crm@perinco.de liegt hier im CRM. Der Zugriff ist nur lesend - im Postfach selbst wird nichts veraendert, keine Mail als gelesen markiert, nichts geloescht. Antworten geht weiter in Outlook; der Link In Outlook oeffnen springt direkt zur Mail.

Zwei Reiter oben:

Postfach

Links die Mailliste, rechts die gewaehlte Mail. Die Kennzeichen an einem Listeneintrag sagen, was noch zu tun ist:

Kennzeichen	Bedeutung
1x zugeordnet	haengt an einer Opportunity oder einem Kontakt
2 Kontakte	so viele Kontakt-Vorschlaege warten noch auf eine Entscheidung
📎	Anhaenge vorhanden (im Postfach, nicht im CRM)

Das Auswahlfeld filtert die Liste. Nicht zugeordnet ist die eigentliche Arbeitsliste: alles, was noch nirgends haengt. Die Suche geht ueber Betreff, Absender und den kompletten Mailtext; mehrere Woerter wirken als ein Suchbegriff.

Zuordnen haengt die Mail an eine Opportunity und/oder einen Kontakt. Der Dialog schlaegt oben vor, was zu den Mailadressen passt - ein Klick auf den Vorschlag genuegt. Beides gleichzeitig ist moeglich, jede Zuordnung laesst sich einzeln wieder mit dem x loesen.

Beim Mailinhalt sind externe Bilder zunaechst gesperrt. Das ist Absicht: geladene Bilder melden dem Absender, dass die Mail geoeffnet wurde. Ueber Externe Bilder laden geht es pro Mail. Groesser klappt den Inhalt auf, Nur Text anzeigen zeigt die Rohfassung ohne Formatierung.

Steht an einer Mail Im Postfach geloescht, wurde sie in Outlook entfernt. Im CRM bleibt sie erhalten, damit Zuordnungen nicht verloren gehen.

Kontakt-Vorschlaege

Aus Absender, Empfaengerliste und Signatur jeder Mail liest die Anwendung Kontaktdaten. Wer eine echte Mailadresse hat und aus Absender oder Empfaengerliste stammt, wird automatisch Kontakt. Alles Unsichere landet hier - typischerweise Personen, die nur mit Telefonnummer im Text genannt werden.

Der Balken rechts ist die Zuversicht: je voller und gruener, je verlaesslicher die Angaben. Das Kennzeichen darunter sagt, woher sie stammen (Absender, Empfaenger, Signatur, Im Text genannt).

Zwei Knoepfe:

Als Kontakt anlegen - es entsteht ein neuer Kontakt mit Herkunft „Mail".
Ergaenzen (statt „anlegen", wenn Bereits vorhanden dransteht) - der vorhandene Kontakt wird um die fehlenden Angaben erweitert. Was schon gepflegt ist, bleibt unangetastet.
Verwerfen - der Vorschlag verschwindet aus der Liste.

Eigene Kollegen (@perinco.de) und Funktionsadressen wie info@ oder no-reply@ werden nie vorgeschlagen.

Ist die Liste leer und die automatische Uebernahme an, ist das der Normalzustand: es gab nichts zu entscheiden.

Scanner

Durchsucht Projektboersen und bewertet jeden Fund mit KI gegen die Lebenslaeufe der Berater.

Dashboard

Oben vier Kennzahlen, darunter die Trefferliste. Der Knopf Jetzt scannen startet sofort einen Suchlauf; laeuft schon einer, sagt die Anwendung das.

Die Filterzeile:

Feld	Bedeutung
Zeitraum	wie alt darf das Projekt sein (Standard: letzte 24 Stunden)
Agent	nur Treffer eines Beraters
Anzeige ab %	schwaechere Treffer ausblenden
Hinweis ab %	ab wann Signalton und E-Mail

Die letzten zwei Werte werden gespeichert und gelten auch beim naechsten Mal und in den Einstellungen. Rechts daneben steht sichtbar / gesamt.

Ein Klick auf eine Zeile oeffnet die Details: Projektbeschreibung, die KI-Auswertung mit Pro und Contra, dazu die Knoepfe Gesehen, Beworben, Zurueck auf Neu, Boerse oeffnen, Passt nicht und Treffer loeschen.

Ueber der Liste steht der Betriebszustand: automatische Suche aktiv, nur manuelle Suche, pausiert oder Suchlauf laeuft.

Ton bei neuen Treffern

Findet der Scanner einen Treffer ueber dem Wert Hinweis ab %, spielt das Dashboard einen Signalton und zeigt ein Hinweisbanner. Drei Dinge muss man dazu wissen:

Nur im Dashboard. Wer auf Opportunities oder Kontakte wechselt, hoert nichts - und bekommt es auch spaeter nicht nachgemeldet.
In einem anderen Browsertab klingelt es weiter, aber verzoegert: der Browser bremst versteckte Tabs auf etwa eine Pruefung pro Minute. Ausserdem muss man vorher einmal irgendwo auf der Seite geklickt haben, sonst laesst der Browser keinen Ton zu.
Ist der Tab geschlossen, passiert nichts. Wer unabhaengig vom Browser benachrichtigt werden will, schaltet die E-Mail in den Einstellungen ein.

Unpassend

Alles, was ueber Passt nicht aussortiert wurde. Von hier bringt Zurueck ins Dashboard einen Treffer wieder zurueck, oder er wird endgueltig geloescht.

Suchagenten

Ein Suchagent ist ein Berater:

Feld	wofuer
Name	erscheint an jedem Treffer
E-Mail	Ziel der Benachrichtigung fuer diesen Berater
Suchbegriffe	kommagetrennt, damit wird auf den Boersen gesucht
Ausschluss-Begriffe	kommagetrennt; Projekte mit diesen Woertern werden uebersprungen
Lebenslauf (PDF)	wird als Text ausgelesen und gegen jedes Projekt bewertet
aktiv	nur aktive Agenten suchen im Hintergrund

Ohne Lebenslauf kann ein Agent nichts bewerten. Die Ausschluss-Begriffe sind nicht nur Bequemlichkeit: sie greifen vor der KI-Bewertung und sparen damit echte Kosten. „Arbeitnehmerueberlassung" oder „Festanstellung" sind typische Kandidaten.

Loeschen nimmt die Treffer mit. Wird ein Suchagent geloescht, verschwinden alle seine bisherigen Treffer und sein Lebenslauf mit ihm - die Datenbank raeumt das automatisch auf. Die gefundenen Projekte bleiben erhalten, sie gehoeren nicht zu einem einzelnen Agenten. Wer einen Berater nur vorübergehend aus der Suche nehmen will, setzt ihn besser auf inaktiv statt ihn zu loeschen: dann sucht er nicht mehr, die Treffer bleiben aber sichtbar.

Boersen-Konten

Zeigt fuer jede Boerse, ob die Verbindung steht. Zwei Arten:

Oeffentliche Portale (Hays, Etengo, …) brauchen keinen Login.
Geschuetzte Portale (Freelance.de, Freelancermap.de) brauchen eine angemeldete Sitzung. Dafuer exportiert man die Cookies mit der Browser-Erweiterung Cookie-Editor als JSON und fuegt sie unter Cookie-Import ein.

Jetzt pruefen testet eine Verbindung sofort. Steht dort Abgelaufen / CAPTCHA, hilft nur ein neuer Cookie-Import.

Die Zugangsdaten (Benutzername, Passwort) sind optional - der Scraper versucht damit im Notfall eine eigene Anmeldung. Passwoerter liegen verschluesselt in der Datenbank.

Einstellungen

Reiter	Wer	Inhalt
Nutzerverwaltung	Admin	Benutzer anlegen, bearbeiten, deaktivieren, loeschen
Mein Konto	alle	Foto, Kalenderfarbe, Passwort aendern
Postfach	Admin	Verbindung zu Microsoft 365, Abgleich, Kontaktuebernahme
Scanner	Admin	Suchintervall, Schwellenwerte, KI-Schluessel, Ton, E-Mail
Whisper	alle	Spracherkennung fuer das Diktat einrichten

Im Reiter Scanner steht das Suchintervall (Minuten) - also wie oft der Hintergrund-Scanner die Boersen durchsucht.

Darueber der Hauptschalter Scanner aktiviert. Ist er aus, sucht die Anwendung nicht mehr: kein Lauf im Hintergrund, und Jetzt scannen antwortet mit einem Hinweis statt zu starten. Der Zustand steht auch oben im Scanner-Dashboard, damit man nicht raetselt, warum keine neuen Treffer kommen.

Im Reiter Postfach steht oben, ob die Verbindung zu Microsoft 365 steht. Verbindung testen prueft beides: die Anmeldung und den tatsaechlichen Zugriff auf crm@perinco.de. Schlaegt etwas fehl, nennt die Meldung den wahrscheinlichen Grund. Darunter lassen sich Intervall, Zeitraum des ersten Durchlaufs und die automatische Kontaktuebernahme einstellen.

Die Zugangsdaten selbst stehen nicht in der Oberflaeche, sondern in der Serverkonfiguration - sie werden beim Start gelesen. Fehlt einer, sagt die Seite welcher.

Foto und Kalenderfarbe werden sofort gespeichert, ohne Speichern-Knopf. Der letzte aktive Administrator kann sich nicht selbst degradieren oder loeschen - das verhindert der Server.

Diktat

Ueberall, wo laengerer Text entsteht, sitzt ein Mikrofon-Knopf. Beim ersten Mal steht dort Diktat einrichten und fuehrt in die Einstellungen: dort einmal Sprachmodell laden klicken, rund 759 MB, danach ist es dauerhaft in diesem Browser.

Die Erkennung laeuft komplett auf dem eigenen Rechner. Aufnahmen verlassen das Geraet nicht und werden nirgends gespeichert. Auf einem anderen Rechner oder in einem anderen Browser faellt der Download erneut an - er gehoert zum Browser, nicht zum Benutzerkonto.

Wenn etwas nicht klappt

Beobachtung	Ursache und Abhilfe
„Sitzung abgelaufen"	12 Stunden vorbei, neu anmelden
Trefferliste ist leer	Anzeige ab % zu hoch oder Zeitraum zu kurz
Kein Ton bei Treffern	Dashboard offen? Einmal auf der Seite geklickt? Wert Hinweis ab % erreicht?
Mikrofon-Knopf fehlt	kein Mikrofon oder keine HTTPS-Verbindung
Boerse zeigt „Abgelaufen"	Cookies neu importieren
„Ein Suchlauf laeuft bereits"	kurz warten, es laeuft nur einer zur Zeit
Aendern nicht erlaubt	bei Opportunities darf nur Ersteller, Zustaendiger oder Admin
Keine Mails sichtbar	steht oben ein Hinweisbalken? Sonst Admin bitten, in Einstellungen → Postfach die Verbindung zu testen
„Erstabgleich laeuft noch"	aeltere Mails werden in mehreren Durchlaeufen nachgeholt, die Liste waechst noch
Bilder in einer Mail fehlen	Externe Bilder laden klicken - sie sind absichtlich gesperrt
Kontakt-Vorschlaege bleiben leer	Normalfall: sichere Vorschlaege werden automatisch uebernommen und tauchen hier nicht auf

16 KiB Raw Blame History