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>
226 lines
11 KiB
Markdown
226 lines
11 KiB
Markdown
# 08 Anleitung fuer Entwickler
|
|
|
|
Fuer jemanden, der das Projekt zum ersten Mal oeffnet. Was man braucht, wie man es
|
|
startet, wo man was aendert - und welche Fallen es gibt.
|
|
|
|
## In zwei Minuten zum Bild
|
|
|
|
* **Ein** Vite-Frontend (React 19, TypeScript, Tailwind 4), **ein** Express-Backend,
|
|
**zwei** MariaDB-Datenbanken.
|
|
* Kein Router im Frontend: `App.tsx` haelt die Ansicht in einem `useState`. Die
|
|
App liegt hinter einer Anmeldung, tiefe Links braucht sie nicht.
|
|
* Kein ORM im CRM-Teil - dort schreibt das Backend SQL mit `mysql2`. Der
|
|
Scanner-Teil benutzt Sequelize, weil er 1:1 aus einer anderen Anwendung
|
|
uebernommen wurde.
|
|
* Alles auf Deutsch: Bezeichner, Kommentare, Meldungen. Kommentare erklaeren das
|
|
**Warum**, nicht das Was.
|
|
|
|
## Voraussetzungen
|
|
|
|
| | Version |
|
|
| --- | --- |
|
|
| Node | 20 oder neuer (Server laeuft 20.20) |
|
|
| MariaDB | 10.11 oder neuer, erreichbar mit Benutzer und Passwort |
|
|
| Browser | Chrome/Edge fuer WebGPU beim Diktat (sonst laeuft es auf der CPU) |
|
|
|
|
## Lokal starten
|
|
|
|
```bash
|
|
git clone http://192.168.1.199:3000/sascha/perinco-CRM.git
|
|
cd perinco-CRM
|
|
|
|
npm install # Frontend
|
|
cd server && npm install # Backend
|
|
cp .env.example .env # Werte eintragen, mindestens DB_* und JWT_SECRET
|
|
npm start # Backend auf :5006
|
|
cd .. && npm run dev # Frontend auf :3100, /api wird geproxied
|
|
```
|
|
|
|
Was dabei von selbst passiert:
|
|
|
|
* `perinco_CRM` muss **existieren**; die Tabellen legt `server/src/schema.sql`
|
|
beim Start an (idempotent).
|
|
* `perinco_scanner` legt das Backend **komplett selbst** an - Datenbank, Tabellen,
|
|
Portale, Standardeinstellungen.
|
|
* Fehlt `ADMIN_PASSWORD`, wird beim ersten Start ein Zufallspasswort erzeugt und
|
|
**einmalig ins Log geschrieben**. Dort nachsehen, sonst kommt man nicht rein.
|
|
|
|
Ohne MariaDB startet das Backend nicht. Das Frontend laesst sich trotzdem
|
|
ansehen - siehe *Oberflaeche pruefen ohne Datenbank* weiter unten.
|
|
|
|
## Pruefen
|
|
|
|
```bash
|
|
npm run lint # = tsc --noEmit, das ist die Wahrheit
|
|
npm run build # muss ohne Fehler durchlaufen
|
|
cd server && npm test # Pruefungen der Postfachanbindung
|
|
```
|
|
|
|
Automatische Tests gibt es nur fuer **einen** Bereich: `server/test/mail.test.mjs`
|
|
prueft die Kontaktextraktion aus Mails und den Graph-Client. Beides laeuft
|
|
unbeaufsichtigt im Hintergrund und laesst sich von Hand kaum nachstellen - ein
|
|
falsch erkannter Name landet still in der Kontaktliste, und ein 429 vom echten
|
|
Dienst kommt genau dann, wenn niemand hinsieht. Kein Test-Framework, reines Node,
|
|
keine Datenbank.
|
|
|
|
Fuer alles andere gilt: `tsc`, ein Build und ein Blick in die Oberflaeche - notfalls
|
|
mit dem Stub aus [Oberflaeche pruefen ohne Datenbank](#oberflaeche-pruefen-ohne-datenbank).
|
|
|
|
## Aufbau
|
|
|
|
```
|
|
src/ Frontend
|
|
App.tsx Ansicht, zentrale Daten, Layout
|
|
types.ts Typen, Konstanten, Rechenhilfen (Volumen, Farben)
|
|
lib/ API-Zugriff und Kontexte
|
|
components/ je Bereich ein Ordner
|
|
server/src/ Backend
|
|
server.js Express-App, Reihenfolge der Routen
|
|
db.js Verbindungspool, Schema-Init, Admin-Seed
|
|
settings.js crm_settings lesen und schreiben (ohne Geheimnisse)
|
|
routes/ ein Router je Ressource
|
|
middleware/auth.js JWT pruefen, Adminrechte
|
|
mail/ Postfach crm@perinco.de ueber Microsoft Graph
|
|
scanner/ portierter Projekt Scanner (Sequelize, Playwright, OpenAI)
|
|
docs/ diese Dokumentation
|
|
deploy/ Apache-Vhosts, systemd-Unit, Deployskript
|
|
```
|
|
|
|
## Wie eine Anfrage laeuft
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant K as Komponente
|
|
participant A as lib/api.ts
|
|
participant E as Express
|
|
participant M as middleware/auth
|
|
participant R as routes/*.js
|
|
participant D as MariaDB
|
|
|
|
K->>A: leadsApi.update(7, { status: 'Gewonnen' })
|
|
A->>A: Token anhaengen, Content-Type setzen
|
|
A->>E: PATCH /api/leads/7
|
|
E->>M: requireAuth
|
|
M->>D: Benutzer laden, aktiv?
|
|
M->>R: req.user gesetzt
|
|
R->>R: Eingaben pruefen und normalisieren
|
|
R->>D: UPDATE ... ; SELECT (angereichert)
|
|
R-->>A: 200 JSON
|
|
A-->>K: typisiertes Objekt
|
|
```
|
|
|
|
Jede Route liefert den **vollstaendigen, angereicherten Datensatz** zurueck (mit
|
|
`created_by_name`, `owner_name`, Ansprechpartnern, Teilnehmern). Das Frontend muss
|
|
danach nichts nachladen.
|
|
|
|
## Etwas hinzufuegen
|
|
|
|
### Neues Feld an einem Kontakt
|
|
|
|
1. `server/src/schema.sql`: Spalte mit `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`
|
|
ergaenzen - das Statement muss beim naechsten Start wiederholbar sein.
|
|
2. `server/src/routes/leads.js`: Feld in die Listen `TEXT_FIELDS` bzw. in
|
|
`INSERT`/`UPDATE` und in den `SELECT` aufnehmen.
|
|
3. `src/types.ts`: Feld ins `Lead`-Interface.
|
|
4. `src/components/leads/LeadModal.tsx`: Eingabefeld, `inputClass` benutzen.
|
|
5. Wenn es in Kachel oder Liste sichtbar sein soll: `LeadGrid.tsx`, `LeadList.tsx`.
|
|
|
|
### Neuer Menuepunkt
|
|
|
|
1. `src/types.ts`: Wert in `ViewState` ergaenzen.
|
|
2. `src/components/Sidebar.tsx`: Eintrag in `CATEGORY_ITEMS` (Name + SVG-Pfad).
|
|
3. `src/App.tsx`: Komponente rendern und einen Untertitel setzen.
|
|
|
|
Der Name in `ViewState` ist gleichzeitig die Beschriftung und der Titel in der
|
|
Kopfzeile. Wer eine abweichende Beschriftung braucht, setzt `label` am `MenuItem`
|
|
(so macht es der Unterpunkt *Dashboard*, der auf die Ansicht `Scanner` zeigt).
|
|
|
|
### Neuer Reiter in den Einstellungen
|
|
|
|
1. `src/types.ts`: Wert in `SettingsTab`; nur fuer Admins zusaetzlich in
|
|
`ADMIN_SETTINGS_TABS`.
|
|
2. `src/components/settings/Settings.tsx`: Eintrag in `TABS` und Rendering.
|
|
|
|
Ein Sprung dorthin aus einer beliebigen Tiefe:
|
|
`goTo('Einstellungen', { tab: 'whisper' })`.
|
|
|
|
### Neuer Endpunkt
|
|
|
|
1. Router in `server/src/routes/` anlegen, `router.use(requireAuth)` nicht
|
|
vergessen, `requireAdmin` wo noetig.
|
|
2. In `server/src/server.js` einhaengen - **vor** dem `/api`-404-Fallback.
|
|
3. In `src/lib/api.ts` eine typisierte Funktion ergaenzen.
|
|
|
|
### Neue Einstellung im CRM
|
|
|
|
Nur fuer Werte, die im Betrieb verstellbar sein sollen. **Zugangsdaten gehoeren
|
|
nicht dazu** - die stehen in `server/.env` und werden beim Start gelesen, damit ein
|
|
Datenbank-Dump keine Geheimnisse enthaelt.
|
|
|
|
1. Schluessel samt Vorgabe in das Vorgabenobjekt des Bereichs eintragen (Muster:
|
|
`MAIL_SETTING_DEFAULTS` in `server/src/mail/config.js`). Es ist gleichzeitig die
|
|
Positivliste des Speicher-Endpunkts.
|
|
2. Lesen mit `getSettings(defaults)` aus `server/src/settings.js`, schreiben mit
|
|
`setSetting()`. Zahlen und Schalter mit `asInt`/`asBool` wandeln.
|
|
3. Feld im passenden Einstellungsreiter ergaenzen.
|
|
|
|
Die Tabelle `crm_settings` legt `schema.sql` an; ein neuer Schluessel braucht keine
|
|
Migration.
|
|
|
|
## Fallen
|
|
|
|
Diese Punkte haben real Zeit gekostet:
|
|
|
|
| Falle | Was passiert |
|
|
| --- | --- |
|
|
| **Reihenfolge in `server.js`** | Der 404-Fallback `app.use('/api', ...)` faengt alles, was danach registriert wird. Neue Router davor einhaengen. |
|
|
| **`Content-Type` bei FormData** | `apiRequest` setzt JSON nur, wenn der Body **keine** `FormData` ist - sonst fehlt die multipart-Grenze und der Upload scheitert. |
|
|
| **Dateien in neuen Tabs** | Ein `<a href>` schickt kein Bearer-Token. Deshalb holt `openAgentCv()` das PDF per `fetch` und oeffnet einen Blob. |
|
|
| **Leerzeichen in Pfaden** | Der alte Scanner liegt unter `/var/www/Projekt Scanner/…`. In der `.env` muss der Wert gequotet sein, sonst schneidet systemd ihn am Leerzeichen ab. |
|
|
| **`.env` ist gleichzeitig `EnvironmentFile`** | Also kein `export`, keine Shell-Ausdruecke, Werte mit Leerzeichen in Anfuehrungszeichen. |
|
|
| **Zeitstempel koennen nur vorziehen** | Ein „vorgealterter" `lastRunTime` verzoegert keinen Cronlauf. Wer verzoegern will, braucht eine eigene Frist. |
|
|
| **Sperrfristen bei jedem Start neu** | Frueher schob jedes Deployment den faelligen Scan um 30 Minuten - er fand nie statt. Deshalb liegt `last_scan_at` in der Datenbank. |
|
|
| **`sequelize.sync({ alter: true })`** | Legt bei jedem Start Unique-Indizes neu an und sprengt irgendwann MySQLs Grenze von 64 Keys. Nur `sync()` benutzen. |
|
|
| **Kaskaden beim Loeschen** | Einen Suchagenten loeschen loescht alle seine Treffer mit. Inaktiv setzen ist meist gemeint. |
|
|
| **Doppelte Scanner-Laeufe** | Scheduler und *Jetzt scannen* teilen eine Sperre. Ohne sie zahlt man jede KI-Bewertung zweimal. |
|
|
| **`allow-same-origin` bei `srcDoc`** | Ein so eingebettetes Dokument erbt die Origin der Anwendung und kann `localStorage` lesen - also das Anmeldetoken. Fremdes HTML gehoert in `sandbox=""` ohne jedes Flag. Der Preis: die Inhaltshoehe ist nicht auslesbar, deshalb hat der Mailrahmen eine feste Hoehe. |
|
|
| **`/me` unter App-only** | Es gibt keinen Benutzer im Token, also auch kein `/me` - jeder Graph-Aufruf muss `/users/{postfach}/…` lauten. Genau daran ist das Altsystem gescheitert, still, weil die Antwort nicht geprueft wurde. |
|
|
| **UTC neben Wandzeit** | `crm_mail_messages.received_at` steht in UTC (so liefert Graph es), `crm_events.starts_at` in lokaler Wandzeit. Beim Lesen im Frontend `parseMailDate()` benutzen, sonst ist die Anzeige um Stunden verschoben. |
|
|
| **Aufzaehlungen in der Datenbank sind deutsch** | `crm_mail_links.origin` (`manuell`/`automatisch`), Vorschlagsstatus (`offen`, `uebernommen`, `verworfen`, `dublette`). Wer englische Werte schickt, bekommt einen Datenbankfehler statt einer Validierungsmeldung. |
|
|
|
|
## Oberflaeche pruefen ohne Datenbank
|
|
|
|
Fuer Bildschirmfotos und Klickwege genuegt ein Stub: ein kleiner `node:http`-Server,
|
|
der `dist/` ausliefert und auf `/api/...` erfundene Daten zurueckgibt. Token vorab
|
|
setzen, dann ist die Anmeldung uebersprungen:
|
|
|
|
```js
|
|
await page.goto(BASE);
|
|
await page.evaluate(() => localStorage.setItem('perinco_crm_token', 'stub-token'));
|
|
await page.goto(BASE);
|
|
```
|
|
|
|
Playwright startet dabei am besten das **installierte Chrome**
|
|
(`chromium.launch({ channel: 'chrome' })`) - dann braucht es keinen
|
|
Browser-Download.
|
|
|
|
## Konventionen
|
|
|
|
* **Deutsch** in Bezeichnern, Kommentaren, Meldungen. Fachbegriffe bleiben
|
|
englisch (`Match`, `Opportunity`, `Lead`).
|
|
* **Kommentare erklaeren das Warum.** Was der Code tut, steht im Code.
|
|
* **Kein `dark:` im Markup.** Nur die Skalen `ink-*`, `brand-*`, `canvas`,
|
|
`surface` benutzen, den Rest macht `index.css`.
|
|
* **Gemeinsame Klassen** statt kopierter Utility-Ketten: `inputClass`,
|
|
`labelClass` aus `components/leads/leadUi.tsx`, dazu `cardClass`,
|
|
`primaryButtonClass` aus `components/scanner/scannerUi.tsx`.
|
|
* **Meldungen als Toast**, Loeschabfragen ueber `ConfirmDialog` - nie `alert()`
|
|
oder `confirm()`.
|
|
* **Rechte immer doppelt**: Oberflaeche blendet aus, Backend antwortet mit 403.
|
|
|
|
## Deployment
|
|
|
|
Siehe [06 Betrieb](06-betrieb.md). Kurzform: lokal bauen, `deploy/deploy.ps1`
|
|
laedt `dist/` und `server/src` hoch und startet den Dienst neu. Auf dem Server
|
|
wird **nicht** gebaut - dort sind RAM und Swap knapp.
|