Sascha WolfandClaude Opus 5
6fd713497d
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>
5.2 KiB
5.2 KiB
10 Glossar
Begriffe, die in der Oberflaeche, im Code und in den Tabellen vorkommen. Die englischen Fachbegriffe sind bewusst nicht eingedeutscht - sie stehen so auch im Quelltext.
| Begriff | Bedeutung |
|---|---|
| Agent / Suchagent | Ein Beraterprofil im Scanner: Name, Lebenslauf als PDF, Suchbegriffe, Ausschluss-Begriffe. Tabelle agents. Nicht zu verwechseln mit einem Benutzerkonto. |
| Ausschluss-Begriff | Wort, das ein Projekt fuer diesen Agenten sofort aussortiert - noch vor der KI-Bewertung, spart also Kosten. Typisch: „Arbeitnehmerueberlassung". |
| Benutzer | Konto fuer die Anmeldung, Rolle admin oder user. Tabelle crm_users. |
| Boerse / Portal | Projektplattform, die der Scanner durchsucht. Oeffentlich (Hays, Etengo) oder geschuetzt (Freelance.de, Freelancermap.de). Tabelle portals. |
| App-only | Zugriff auf Microsoft 365 im Namen der Anwendung, nicht eines Benutzers (OAuth-Ablauf Client Credentials). Braucht Anwendungsberechtigungen und Administratorzustimmung, aber keinen Login. |
| Cookie-Import | Uebertragen einer angemeldeten Browsersitzung auf den Scraper, per JSON-Export der Erweiterung Cookie-Editor. Landet als session_state am Portal. |
| Delta Query | Graph-Abfrage, die beim naechsten Aufruf nur noch die Aenderungen liefert. Der Fortschritt steckt in einem Verweis (delta_link), der in crm_mail_sync_state liegt. |
| Kontakt / Lead | Person im Netzwerk: Firma, Position, Status, Verbindungen. Tabelle crm_leads. Im Code durchgaengig lead. |
| Kontakt-Vorschlag | Aus einer Mail gelesene Person, die noch kein Kontakt ist. Tabelle crm_mail_contact_candidates. Wird uebernommen, ergaenzt oder verworfen. |
| Match / Treffer | Die Bewertung eines Projekts fuer einen Agenten: Prozentwert, Pro-Liste, Contra-Liste, Status. Tabelle matches. Ein Projekt erzeugt so viele Treffer, wie es aktive Agenten gibt. |
| Opportunity | Geschaeft in Arbeit: Phase, Tagessatz, Laufzeit, Wahrscheinlichkeit, Ansprechpartner. Tabelle crm_opportunities. |
| Phase / Stage | Fortschritt einer Opportunity: Neu, Qualifizierung, Angebot, Verhandlung, Gewonnen, Verloren. |
| Pipeline | Zwei Bedeutungen, je nach Zusammenhang: die Kanban-Ansicht der Opportunities oder der Suchlauf des Scanners (services/pipeline.js). |
| Projekt | Ein von einer Boerse gescrapter Auftrag. Tabelle projects, Aufbewahrung 7 Tage. |
| Scraper | Der Teil, der mit einem echten Browser (Playwright/Chromium) die Suchseiten der Boersen abruft. |
| Session (Portal) | Gespeicherte Cookies einer angemeldeten Boersen-Sitzung, im Playwright-Format storageState. |
| Sitzung (CRM) | Die eigene Anmeldung, als JWT im localStorage, 12 Stunden gueltig. |
| Suchintervall | Abstand zwischen zwei automatischen Suchlaeufen, in Minuten. Einstellung search_interval. |
| Schwellenwert Anzeige | display_threshold - Treffer darunter bleiben im Dashboard ausgeblendet. |
| Schwellenwert Benachrichtigung | match_threshold - ab hier gibt es Signalton und E-Mail. |
| Verbindung | Kante zwischen zwei Kontakten im Netzwerkdiagramm, mit Art und Staerke. Tabelle crm_lead_connections. |
| Volumen | Tagessatz x Personentage. Gewichtet heisst zusaetzlich mit der Abschlusswahrscheinlichkeit multipliziert. |
| Whisper | Das Spracherkennungsmodell fuer das Diktat. Laeuft im Browser, nicht auf dem Server. |
| Zugriffsrichtlinie | ApplicationAccessPolicy in Exchange Online. Begrenzt eine App-only-Berechtigung auf einzelne Postfaecher - ohne sie gilt sie tenant-weit. |
| Zustaendiger / Owner | Benutzer, dem ein Kontakt oder eine Opportunity zugeordnet ist. Darf sie aendern, auch wenn er sie nicht angelegt hat. |
| Zuversicht / Confidence | Wert von 0 bis 100 an einem Kontakt-Vorschlag. Ab 70 und mit echter Mailadresse wird automatisch uebernommen. |
Herkunft eines Kontakt-Vorschlags
| Wert in der DB | in der Oberflaeche | Zuversicht |
|---|---|---|
absender |
Absender | 90, mit bestaetigender Signatur 95 |
empfaenger |
Empfaenger | 78 |
signatur |
Signatur | 55 - weitere Adresse in der Signatur, etwa eine Assistenz |
text |
Im Text genannt | 35 - nur mit Anrede und Rufnummer, nie automatisch uebernommen |
Status eines Kontakt-Vorschlags
| Wert | in der Oberflaeche | Bedeutung |
|---|---|---|
offen |
Offen | wartet auf eine Entscheidung |
uebernommen |
Uebernommen | es wurde ein Kontakt angelegt |
dublette |
Ergaenzt | Adresse war vorhanden, der Kontakt wurde erweitert |
verworfen |
Verworfen | von Hand abgelehnt |
Statuswerte im Scanner
| Wert in der DB | in der Oberflaeche | Bedeutung |
|---|---|---|
new |
Neu | noch nicht angesehen |
reviewed |
Gesehen | geprueft, noch keine Bewerbung |
applied |
Beworben | Bewerbung ist raus |
rejected |
Abgelehnt | passt nicht; erscheint nur unter Unpassend |
Portal-Status
| Wert | Bedeutung |
|---|---|
connected |
Verbindung steht, letzte Pruefung erfolgreich |
expired |
Session abgelaufen oder CAPTCHA - neuer Cookie-Import faellig |
error |
Portal nicht erreichbar oder Seitenaufbau geaendert |
disconnected |
nie verbunden; bei oeffentlichen Portalen heisst das nur „bereit" |