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>
121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# 01 Architektur
|
|
|
|
## Bausteine
|
|
|
|
Drei Teile, keiner davon spricht direkt mit einem anderen ausser ueber HTTP bzw.
|
|
SQL:
|
|
|
|
| Teil | Technik | Wo |
|
|
| --- | --- | --- |
|
|
| Frontend | React 19, TypeScript, Tailwind 4, Vite | statisches Build in `/var/www/perinco_CRM/dist` |
|
|
| Backend | Express 4, mysql2 (CRM), Sequelize (Scanner) | `/var/www/perinco_CRM/server`, `127.0.0.1:5006` |
|
|
| Datenbank | MariaDB 10.11 | `perinco_CRM` und `perinco_scanner` |
|
|
|
|
Der Browser spricht **nie** direkt mit MariaDB - deshalb ueberhaupt ein Backend.
|
|
Das Backend bindet ausschliesslich auf `127.0.0.1` und ist von aussen nur ueber
|
|
den Apache-Reverse-Proxy erreichbar.
|
|
|
|
## Topologie
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
U(("Browser")) -->|"HTTPS"| A["Apache :443<br/>pcrm.perinco.de"]
|
|
A -->|"/"| D["dist/<br/>SPA, FallbackResource"]
|
|
A -->|"/api"| E["Express :5006"]
|
|
E --> C[("perinco_CRM")]
|
|
E --> S[("perinco_scanner")]
|
|
|
|
U2(("Browser")) -->|"HTTPS"| A2["Apache :443<br/>scanner.perinco.de"]
|
|
A2 -->|"/api, /uploads, /health"| E2["alte Scanner-App :5005"]
|
|
E2 --> S2[("project_scanner")]
|
|
|
|
classDef alt fill:#f7f7f7,stroke:#9a9a9a,stroke-dasharray: 4 3
|
|
class U2,A2,E2,S2 alt
|
|
```
|
|
|
|
Der Scanner im CRM haengt unter `/api/scanner` und braucht damit **keine eigene
|
|
Apache-Regel**: alles laeuft ueber den bestehenden `/api`-Proxy. Dasselbe gilt fuer
|
|
die Postfachanbindung unter `/api/mail` (siehe
|
|
[11 Postfachanbindung](11-postfach.md)).
|
|
|
|
## Ausgehende Verbindungen
|
|
|
|
Das Backend spricht von sich aus mit drei fremden Diensten. Alle drei sind
|
|
optional - fehlen die Zugangsdaten, laeuft die Anwendung ohne den jeweiligen
|
|
Teil weiter.
|
|
|
|
| Ziel | Wofuer | Ausgeloest von |
|
|
| --- | --- | --- |
|
|
| Projektboersen | Scraping der Projektangebote | Scanner-Scheduler |
|
|
| `api.openai.com` | Bewertung Lebenslauf gegen Projekt | Scanner-Pipeline |
|
|
| `login.microsoftonline.com`, `graph.microsoft.com` | Postfach `crm@perinco.de` lesen | Mail-Scheduler |
|
|
|
|
Die Postfachanbindung schickt **keine** Mailinhalte an Dritte: Kontaktdaten
|
|
werden auf dem Server aus Graph-Feldern und Signaturen gelesen, ohne
|
|
Sprachmodell.
|
|
|
|
## Anfrageweg mit Anmeldung
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
actor B as Browser
|
|
participant A as Apache
|
|
participant E as Express
|
|
participant M as MariaDB
|
|
|
|
B->>A: POST /api/auth/login
|
|
A->>E: weiterleiten
|
|
E->>M: SELECT crm_users WHERE username
|
|
M-->>E: Zeile mit bcrypt-Hash
|
|
E->>E: bcrypt.compare
|
|
E-->>B: { token (JWT, 12 h), user }
|
|
Note over B: Token im localStorage
|
|
|
|
B->>A: GET /api/scanner/matches<br/>Authorization: Bearer ...
|
|
A->>E: weiterleiten
|
|
E->>E: requireAuth: JWT pruefen
|
|
E->>M: SELECT crm_users WHERE id (ist der noch aktiv?)
|
|
E->>M: SELECT matches JOIN agents, projects
|
|
M-->>E: Treffer
|
|
E-->>B: JSON
|
|
```
|
|
|
|
Bei `401` loescht das Frontend das Token und springt zurueck auf den
|
|
Anmeldeschirm (`setUnauthorizedHandler` in `src/lib/api.ts`). Das Token wird bei
|
|
jeder Anfrage neu gegen die Datenbank geprueft - ein deaktivierter Benutzer ist
|
|
sofort draussen, ohne auf den Ablauf des Tokens zu warten.
|
|
|
|
## Rollen
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
L["Anmeldung"] --> R{"Rolle"}
|
|
R -->|admin| A["Opportunities, Kalender, Kontakte, Mails, Scanner<br/>Einstellungen: Nutzerverwaltung, Mein Konto, Postfach, Scanner, Whisper"]
|
|
R -->|user| U["Opportunities, Kalender, Kontakte, Mails, Scanner<br/>Einstellungen: Mein Konto, Whisper"]
|
|
```
|
|
|
|
Bei den Mails darf jede Rolle lesen und zuordnen - `crm@perinco.de` ist ein
|
|
gemeinsames Vertriebspostfach. Einrichten, Verbindungstest und manueller Abgleich
|
|
sind Administratoren vorbehalten.
|
|
|
|
Die Rollenpruefung sitzt **doppelt**: das Menue blendet aus, was nicht erlaubt
|
|
ist, und das Backend weist Zugriffe zusaetzlich mit `403` ab (`requireAdmin`).
|
|
Ausnahme ist `GET /api/users/directory` - die Benutzerliste brauchen alle Rollen
|
|
fuer Netzwerkdiagramm, Zustaendigkeiten, @-Mentions, Teilnehmerauswahl und
|
|
Kalenderfarben. Passwort-Hashes liefert der Endpunkt nie.
|
|
|
|
Ein Sicherheitsnetz im Backend verhindert, dass der letzte aktive Administrator
|
|
degradiert, deaktiviert oder geloescht wird.
|
|
|
|
## Belegte Ports auf dem Server
|
|
|
|
Der Rechner hostet weitere Dienste (n8n, Docker, ~15 Apache-Vhosts). Vor jeder
|
|
Portbelegung `ss -tlnp` pruefen. Relevant hier:
|
|
|
|
| Port | Dienst |
|
|
| --- | --- |
|
|
| 5006 | perinco CRM Backend (nur `127.0.0.1`) |
|
|
| 5005 | alte Scanner-App (`0.0.0.0`) |
|
|
| 3000 | weitere Vite-App |
|
|
| 5678 | n8n |
|