Sascha WolfandClaude Opus 5
6f57483f33
Erster Menuepunkt und Startansicht; das Logo oben links fuehrt dorthin zurueck. Vier Kennzahlen (Bewerbungen, daraus Opportunities samt Quote, gewonnene Projekte, aktuell beim Kunden), ein Saeulendiagramm mit denselben drei Reihen ueber der Zeit, die Bewerbungen je Berater, die naechsten Termine und alle Opportunities in Kundenvorstellung bzw. Interview Kunde. Zeitraum ueber vier Vorgaben oder frei, Einteilung nach Tag, Monat, Quartal oder Jahr. Bewerbung heisst dabei: ein Eintrag in der Akquise - jeder Eintrag bedeutet, dass ein Profil raus ist (so vom Nutzer festgelegt). Zwei Dinge dafuer am Datenmodell: - crm_opportunities.won_at haelt den Zeitpunkt des Wechsels nach "Beauftragt". Die Phase allein sagt nur, wie es jetzt steht, nicht wann es passiert ist. Beim Wechsel heraus wird das Datum geleert, sonst zaehlt das Dashboard einen Gewinn, den es nicht gibt. - Die Akquise loescht nach 90 Tagen - damit waere jede Jahresauswertung falsch. Der Aufraeumlauf sichert deshalb vorher Tag, Berater und Anzahl in crm_acquisition_history, in derselben Transaktion wie das Loeschen. Gesichert wird nur, was verschwindet; die Auswertung addiert beide Quellen und kann sich damit nicht ueberschneiden. Projektdaten sind nach dem Loeschen weiterhin weg. Termine und die Phasenlisten kommen nicht aus einem eigenen Endpunkt: Termine und Opportunities laedt die App ohnehin komplett, das Dashboard filtert sie selbst. Diagramme von Hand (SVG-freie Balken plus Tailwind-Uebergaenge) statt einer Bibliothek - drei Darstellungen rechtfertigen keine weitere Abhaengigkeit, und so kommen die Farben aus denselben Tokens wie der Rest. Die Zahlen laufen hoch, die Saeulen wachsen; wer Bewegung im System abgeschaltet hat, bekommt sofort den Endwert. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
# 01 Architektur
|
|
|
|
## Bausteine
|
|
|
|
Drei Teile, keiner davon spricht direkt mit einem anderen ausser über 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 überhaupt ein Backend.
|
|
Das Backend bindet ausschließlich auf `127.0.0.1` und ist von außen nur über
|
|
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 hängt unter `/api/scanner` und braucht damit **keine eigene
|
|
Apache-Regel**: alles läuft über den bestehenden `/api`-Proxy. Dasselbe gilt für
|
|
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, läuft die Anwendung ohne den jeweiligen
|
|
Teil weiter.
|
|
|
|
| Ziel | Wofür | Ausgelöst von |
|
|
| --- | --- | --- |
|
|
| Projektbörsen | 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` löscht das Frontend das Token und springt zurück auf den
|
|
Anmeldeschirm (`setUnauthorizedHandler` in `src/lib/api.ts`). Das Token wird bei
|
|
jeder Anfrage neu gegen die Datenbank geprüft - ein deaktivierter Benutzer ist
|
|
sofort draußen, ohne auf den Ablauf des Tokens zu warten.
|
|
|
|
## Rollen
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
L["Anmeldung"] --> R{"Rolle"}
|
|
R -->|admin| A["Dashboard, Akquise, Opportunities, Interviews, Kontakte, Mails, Scanner<br/>Einstellungen: Nutzerverwaltung, Mein Konto, Akquise, Postfach, Scanner, Whisper"]
|
|
R -->|user| U["Dashboard, Akquise, Opportunities, Interviews, Kontakte, Mails, Scanner<br/>Einstellungen: Mein Konto, Akquise, 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 Rollenprüfung sitzt **doppelt**: das Menü blendet aus, was nicht erlaubt
|
|
ist, und das Backend weist Zugriffe zusätzlich mit `403` ab (`requireAdmin`).
|
|
Ausnahme ist `GET /api/users/directory` - die Benutzerliste brauchen alle Rollen
|
|
für Netzwerkdiagramm, Zuständigkeiten, @-Mentions, Teilnehmerauswahl und
|
|
Terminfarben. Passwort-Hashes liefert der Endpunkt nie.
|
|
|
|
Ein Sicherheitsnetz im Backend verhindert, dass der letzte aktive Administrator
|
|
degradiert, deaktiviert oder gelöscht wird.
|
|
|
|
## Belegte Ports auf dem Server
|
|
|
|
Der Rechner hostet weitere Dienste (n8n, Docker, ~15 Apache-Vhosts). Vor jeder
|
|
Portbelegung `ss -tlnp` prüfen. 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 |
|