# LeoCRM — Extracted Architecture Details

**Zweck:** Implementierungs-Details, die aus der bereinigten `requirements.md` entfernt wurden. Für den Solution Architect als Referenz.
**Quelle:** Original `requirements.md` (git HEAD, 1956 Zeilen) vs. bereinigte Version (2105 Zeilen)
**Datum:** 2026-06-28

---

## 1. Tech-Stack (vollständige Spezifikation)

### Original Tech-Stack-Tabelle (entfernt)

| Komponente | Entscheidung | Bemerkung |
|------------|-------------|----------|
| Backend | FastAPI + SQLAlchemy 2.0 | Python 3.12 |
| Datenbank | PostgreSQL (empfohlen) | Siehe DB-Empfehlung unten |
| Frontend | React SPA | Client-side rendering, i18n (bestätigt durch Prototyp) |
| Deployment | Coolify (Docker) | Bestätigt |
| Linting | ruff + black | Python-Standard |
| Testing | pytest + Vitest/Jest | Backend + Frontend |

### DB-Empfehlung: PostgreSQL statt SQLite

Ursprünglich war SQLite spezifiziert. Bei 200.000 Kontakten + mehreren Usern + Concurrent Writes ist SQLite limitiert:

- **SQLite:** File-Level Locking, nur 1 Writer gleichzeitig, ~15 Updates/Sekunde bei Concurrent Writes (StackOverflow Benchmark)
- **PostgreSQL:** True Concurrent Writers, ~1.500 Updates/Sekunde, MVCC-Architektur (tableone.dev Benchmark)
- **Fazit:** Bei 200k Datensätzen + Multi-User + gleichzeitige Schreibzugriffe → PostgreSQL

### v0.1 Historischer Tech-Stack (archiviert)
- ~~Backend: FastAPI (Python 3.11+)~~ → Python 3.12
- ~~DB: SQLite (Datei `leocrm.db`)~~ → PostgreSQL 16
- ~~Templates: Jinja2 (HTML)~~ → React 18 SPA
- ~~Server: Uvicorn / Gunicorn~~ → Uvicorn (async)
- ~~Deployment: 1 Container Docker Compose~~ → Multi-Container (Backend + Frontend + PostgreSQL + OnlyOffice + Worker)

---

## 2. Domain Knowledge (entfernte Referenzen)

**Domain:** Customer Relationship Management (CRM)

Standard-Entitäten in CRMs (Referenz: Zoho CRM, HubSpot, Salesforce):
- **Accounts (Firmen):** Name, Adresse, Industrie, Employees, Revenue, Owner, Phone, Website, Billing/Shipping Address
- **Contacts (Kontaktpersonen):** Name, Email, Phone, Mobile, Title, Department, Mailing Address, Reports To, Description
- **Beziehungen:** N:M (ein Kontakt kann mehreren Firmen zugeordnet sein)

Quellen:
- Zoho CRM Standard Fields Accounts: https://help.zoho.com/portal/en/kb/crm/sales-force-automation/accounts/articles/standard-fields-accounts
- Zoho CRM Standard Fields Contacts: https://help.zoho.com/portal/en/kb/crm/sales-force-automation/contacts/articles/standard-fields-contacts
- Encore Business Solutions — 30 CRM Custom Account Fields
- Bitrix24 Standard fields in CRM

---

## 3. HTTP-Endpunkt-Spezifikationen

### F-AUTH-01: Login
- **Endpoint:** POST `/api/auth/login`
- **Akzeptiert:** E-Mail + Passwort
- **Response:** Session-Cookie (HttpOnly+Secure+SameSite=Strict) oder 401

### F-AUTH-02: Logout
- **Clientseitig:** Token wird entfernt
- **Server:** Token-Blacklist optional für v1

### F-AUTH-03: User-Verwaltung
- **Endpoint:** POST `/api/users`
- **Auth:** Admin-Token erforderlich
- **Response:** 201 (erstellt) oder 403 (ohne Admin-Token)

### F-AUTH-04: RBAC
- **Jeder API-Endpoint prüft Rolle:** falsche Rolle → 403; korrekte Rolle → 200/201
- **Beispiele:** POST `/api/users` → 403 (editor); POST `/api/companies` → 403 (viewer), GET `/api/companies` → 200 (viewer)

### F-AUTH-05: Passwort-Reset
- **Request:** POST `/api/auth/password-reset/request` → sendet E-Mail
- **Confirm:** POST `/api/auth/password-reset/confirm` mit Token + neuem Passwort → aktualisiert Passwort

### F-COMP-01: Firma anlegen
- **Endpoint:** POST `/api/companies`
- **Response:** 201 Created (valide Daten); 422 Validation Error (ohne Name)

### F-COMP-02: Firma anzeigen
- **Endpoint:** GET `/api/companies/{id}`
- **Response:** 200 mit Firmendaten + Kontakte-Array; 404 (nicht-existent)

### F-COMP-03: Firma bearbeiten
- **Endpoint:** PUT/PATCH `/api/companies/{id}`
- **Response:** 200 mit aktualisierten Daten; 422 (Validierungsfehler)

### F-COMP-04: Firma löschen (Soft-Delete)
- **Endpoint:** DELETE `/api/companies/{id}?cascade=true|false`
- **Response:** 200; Firma wird als `deleted_at = NOW()` markiert
- **Cascade:** bei cascade=true auch Kontakte soft-deleted

### F-COMP-05: Firmen-Liste mit Pagination
- **Endpoint:** GET `/api/companies?page=2&page_size=25&sort_by=name&sort_order=desc`
- **Response:** 200 mit `{items, total, page, page_size}`

### F-COMP-06: Firmen-Suche & Filter
- **Endpoint:** GET `/api/companies?search=Tech&industry=IT&country=Germany`
- **Response:** 200 mit gefilterten Ergebnissen

### F-COMP-07: Audit-Log
- **Tabelle:** `audit_log`
- **Mechanismus:** Middleware/Decorator loggt schreibende Aktionen
- **Endpoint:** GET `/api/audit-log` (Admin, paginiert)

### F-COMP-08: DSGVO / Right to be Forgotten
- **Endpoint:** DELETE `/api/contacts/{id}?gdpr=true` → harte Löschung
- **Tabelle:** separate `deletion_log` Tabelle (unveränderlich)

### F-CONT-01: Kontaktperson anlegen
- **Endpoint:** POST `/api/contacts`
- **Response:** 201 (valide Daten); 422 (ohne last_name)
- **N:M:** mit company_ids → N:M-Verknüpfungen erstellt

### F-CONT-02: Kontaktperson anzeigen
- **Endpoint:** GET `/api/contacts/{id}`
- **Response:** 200 mit Kontaktdaten + Firmen-Array; 404

### F-CONT-03: Kontaktperson bearbeiten
- **Endpoint:** PUT/PATCH `/api/contacts/{id}`
- **Response:** 200; Änderung an company_ids → N:M-Tabelle aktualisiert

### F-CONT-04: Kontaktperson löschen (Soft-Delete)
- **Endpoint:** DELETE `/api/contacts/{id}`
- **Response:** 200; `deleted_at` gesetzt; N:M-Einträge gelöscht; Firmen unberührt

### F-CONT-05: Kontakt-Liste mit Pagination
- **Endpoint:** GET `/api/contacts?page=1&page_size=25&sort_by=last_name&sort_order=asc`
- **Response:** 200 mit paginierten Ergebnissen
- **Performance:** Response-Zeit <500ms bei 200k Datensätzen (mit DB-Index)

### F-CONT-06: Kontakt-Suche & Filter
- **Endpoint:** GET `/api/contacts?search=Müller&company_id=5`
- **Response:** 200 mit gefilterten Ergebnissen

### F-CONT-07: N:M Firmen-Kontakt-Zuordnung
- **Tabelle:** `company_contacts` (N:M-Verknüpfungstabelle)
- **Zuordnung:** POST `/api/companies/{id}/contacts/{contact_id}`
- **Entfernung:** DELETE `/api/companies/{id}/contacts/{contact_id}`

### F-DATA-01: CSV-Export
- **Endpoint:** GET `/api/companies/export?format=csv&filters=...`
- **Response:** 200 mit `Content-Type: text/csv`, Datei-Download

### F-DATA-02: Excel-Export
- **Endpoint:** GET `/api/companies/export?format=xlsx&filters=...`
- **Response:** 200 mit `Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`

### F-DATA-03: Daten-Validierung
- **Technologie:** Pydantic-Schemas für alle Entities
- **Response:** ungültige Eingaben → 422 mit detailiertem Fehler-Objekt

### F-DATA-06: ARIA-Rollen auf DataTable
- **ARIA-Rollen:** `role="table"`, `role="row"`, `role="columnheader"`, `role="cell"`
- **Sortierung:** `aria-sort="ascending|descending|none"`
- **Label:** beschreibendes `aria-label`
- **Testing:** NVDA und axe DevTools

### F-UI-01: Responsive Design
- **Breakpoints:** Mobile-First; Touch-Targets min 44px
- **Testing:** Chrome DevTools (375px, 768px, 1920px)

### F-UI-02: Internationalisierung
- **Library:** react-i18next
- **Locale-Files:** JSON-Locale-Files für DE/EN
- **Persistenz:** Sprachwahl persistiert in User-Settings

### F-UI-03: Error-Handling & Toast-Notifications
- **Komponente:** Toast-Komponente (success/error/warning/info)
- **Routen:** dedizierte 404/500-Routen im Frontend

### F-UI-04: Loading-States
- **Komponenten:** Loading-State-Komponenten; Skeleton-Loader
- **State:** API-Loading-State im Frontend-Store; Button-Disabled-State während Pending

### F-UI-05: Empty-States
- **Komponente:** Empty-State-Komponenten mit Icon + Text + CTA

### F-UI-06: Confirmation-Dialogs
- **Komponente:** Modal-Dialog-Komponente
- **Regel:** alle DELETE-Operationen erfordern Bestätigung

### F-SEC-01: CSRF-Schutz
- **Implementierung:** SameSite=Strict Cookies + Origin-Header-Validierung
- **Kein Double-Submit-Token**
- **Middleware:** Origin-Header-Validierung-Middleware
- **Exempt:** nur GET/HEAD/OPTIONS

### F-SEC-02: XSS-Schutz & Input-Sanitization
- **Frontend:** Output-Encoding
- **Backend:** Pydantic-Validierung strippt gefährliche Eingaben
- **Header:** CSP-Header gesetzt

### F-SEC-03: Session-Timeout
- **Timeout:** 8h
- **Interceptor:** 401-Interceptor im Frontend → Redirect zur Login-Seite
- **Refresh:** Refresh-Token optional für v1

### F-INFRA-01: Health-Check Endpoint
- **Endpoint:** GET `/api/health`
- **Response:** 200 `{status: "healthy", db: "connected"}` oder 503 `{status: "unhealthy", db: "disconnected"}`
- **Auth:** kein Auth erforderlich
- **Coolify:** nutzt Endpoint für Health-Check

### F-INFRA-02: Backup & Restore
- **Backup:** Docker-Volume-Backup konfiguriert
- **Doku:** Restore-Dokumentation in README

### F-INFRA-03: Logging
- **Format:** Python `logging` mit JSON-Formatter
- **Konfiguration:** Log-Level konfigurierbar via Env-Var
- **Inhalt:** Method, Path, Status, Duration; Error-Logs mit Stacktrace

### F-INFRA-04: Monitoring & Alerting
- **Monitoring:** Coolify-Built-in-Monitoring nutzt `/api/health`
- **Optional:** externes Monitoring-Tool

### F-MIG-01: CSV-Import
- **Endpoint:** POST `/api/import` mit CSV-Datei + Entity-Type
- **Response:** Import-Job mit success/skipped/failed counts

### F-INT-01: E-Mail-Integration (Passwort-Reset)
- **Config:** SMTP via Env-Vars (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS)
- **Templates:** E-Mail-Templates für Reset

### F-INT-02: API-Keys / Token-Auth
- **Auth:** Session-Auth-Middleware auf allen Endpoints außer `/api/health` und `/api/auth/*`
- **Optional:** API-Key für externe Integrationen (post-MVP)

### F-TEST-01: Testing-Strategie
- **Backend:** pytest + httpx für API-Tests; Coverage >80%
- **Frontend:** Vitest für Component-Tests
- **E2E:** Playwright für Critical Paths
- **CI:** Coverage-Report in CI; bei Fehlschlag wird Build blockiert

### F-ENV-01: Environments & Secrets
- **Env-Vars:** `LEOCRM_SECRET_KEY` (Session-Secret, min 32 Zeichen)
- **Datei:** `.env.example` dokumentiert alle Vars
- **Secrets:** keine Secrets im Git-Repo
- **Coolify:** Env-Vars konfiguriert

### F-DOC-01: Dokumentation
- **README:** `README.md` mit Setup-Anleitung
- **API-Doku:** `/docs` (Swagger/OpenAPI) auto-gen via FastAPI
- **Admin-Doku:** `docs/admin-guide.md` für Deploy/Backup/Restore

### F-PERF-01: Performance
- **Response-Zeit:** <500ms für List-Endpunkte bei 200k Datensätzen
- **DB-Indizes:** last_name, first_name, email, company.name, company.industry, company.country
- **Pagination:** verhindert Full-Table-Scan
- **Export:** >50k Datensätze als Background-Job oder Streaming-Response

### F-A11Y-01: Accessibility (WCAG 2.1 AA)
- **CSS-Utility:** `.sr-only` CSS-Klasse (visual-hidden pattern)
- **Kontrast:** >4.5:1
- **Testing:** axe DevTools

### F-A11Y-02: prefers-reduced-motion
- **CSS:** `@media (prefers-reduced-motion: reduce)` Block in globalen Styles
- **Properties:** alle `transition` und `animation` auf `none` oder `0.01ms`
- **Testing:** Chrome DevTools (Rendering → Emulate CSS prefers-reduced-motion: reduce)

### F-A11Y-03: 44px Touch-Targets
- **CSS-Regel:** `min-height: 44px; min-width: 44px;` für alle interaktiven Elemente
- **Alternative:** `::after` Pseudo-Element mit 44px Touch-Bereich
- **Testing:** Chrome DevTools (375px Breite, Touch-Emulation)

### F-SCHED-01: Background-Jobs
- **Queue:** Background-Task-Queue (Celery, ARQ, oder FastAPI BackgroundTasks für v1)
- **Status:** Job-Status-Endpoint
- **Export-Limit:** >50k Datensätze als Background-Job, <50k als direkter Download

---

## 4. DB-Schema-Definitionen (Feld-Tabellen)

### F-COMP-01: Company-Felder

| Feld | Typ | Pflicht | Bemerkung |
|------|-----|---------|-----------|
| name | String(100) | ✅ | Firmenname |
| account_number | String(40) | ❌ | Interne Referenznummer |
| industry | Picklist | ❌ | IT, Finance, Manufacturing, etc. |
| account_type | Picklist | ❌ | Customer, Partner, Prospect, etc. |
| ownership | Picklist | ❌ | Public, Private, Government, etc. |
| employees | Integer | ❌ | Anzahl Mitarbeiter |
| annual_revenue | Decimal | ❌ | Jahresumsatz |
| phone | String(30) | ❌ | Haupttelefon |
| fax | String(30) | ❌ | Fax |
| email | Email | ❌ | Allgemeine E-Mail |
| website | URL | ❌ | Website |
| rating | Picklist | ❌ | Hot, Warm, Cold |
| parent_account_id | FK→Company | ❌ | Muttergesellschaft |
| billing_street | String(250) | ❌ | Rechnungsadresse Strasse |
| billing_city | String(100) | ❌ | Rechnungsadresse Stadt |
| billing_state | String(100) | ❌ | Rechnungsadresse Bundesland |
| billing_postal_code | String(20) | ❌ | Rechnungsadresse PLZ |
| billing_country | String(100) | ❌ | Rechnungsadresse Land |
| shipping_street | String(250) | ❌ | Besuchsadresse Strasse |
| shipping_city | String(100) | ❌ | Besuchsadresse Stadt |
| shipping_state | String(100) | ❌ | Besuchsadresse Bundesland |
| shipping_postal_code | String(20) | ❌ | Besuchsadresse PLZ |
| shipping_country | String(100) | ❌ | Besuchsadresse Land |
| description | Text(32000) | ❌ | Notizfeld |
| sic_code | String(10) | ❌ | Standard Industrial Classification |
| ticker_symbol | String(30) | ❌ | Börsenkürzel |
| account_site | String(80) | ❌ | Standort-Name (z.B. Headquarters) |

### F-CONT-01: Contact-Felder

| Feld | Typ | Pflicht | Bemerkung |
|------|-----|---------|-----------|
| first_name | String(50) | ❌ | Vorname |
| last_name | String(50) | ✅ | Nachname |
| salutation | Picklist | ❌ | Herr, Frau, Dr., etc. |
| email | Email | ❌ | Haupt-E-Mail |
| secondary_email | Email | ❌ | Zweit-E-Mail |
| phone | String(30) | ❌ | Bürotelefon |
| mobile | String(30) | ❌ | Mobiltelefon |
| home_phone | String(30) | ❌ | Privattelefon |
| fax | String(30) | ❌ | Fax |
| title | String(100) | ❌ | Jobtitel (CEO, Manager, etc.) |
| department | String(100) | ❌ | Abteilung |
| reports_to | FK→Contact | ❌ | Vorgesetzter |
| date_of_birth | Date | ❌ | Geburtsdatum |
| assistant | String(50) | ❌ | Assistent-Name |
| assistant_phone | String(30) | ❌ | Assistent-Telefon |
| mailing_street | String(250) | ❌ | Postadresse Strasse |
| mailing_city | String(100) | ❌ | Postadresse Stadt |
| mailing_state | String(100) | ❌ | Postadresse Bundesland |
| mailing_postal_code | String(20) | ❌ | Postadresse PLZ |
| mailing_country | String(100) | ❌ | Postadresse Land |
| other_street | String(250) | ❌ | Andere Adresse Strasse |
| other_city | String(100) | ❌ | Andere Adresse Stadt |
| other_state | String(100) | ❌ | Andere Adresse Bundesland |
| other_postal_code | String(20) | ❌ | Andere Adresse PLZ |
| other_country | String(100) | ❌ | Andere Adresse Land |
| skype_id | String(50) | ❌ | Skype |
| linkedin | URL | ❌ | LinkedIn-Profil |
| twitter | String(50) | ❌ | Twitter-Handle |
| description | Text(32000) | ❌ | Notizfeld |
| company_ids | [FK→Company] | ❌ | N:M-Zuordnung (0..n Firmen) |

### Implizite DB-Tabellen (aus Akzeptanzkriterien extrahiert)

- `company_contacts` — N:M-Verknüpfungstabelle (company_id ↔ contact_id)
- `audit_log` — Tabelle für Audit-Log-Einträge (user, action, entity, entity_id, timestamp)
- `deletion_log` — Unveränderliche Tabelle für DSGVO-Löschungen
- `users` — User-Tabelle (email, name, role, password_hash)
- `companies` — Firmen-Tabelle (siehe Feld-Tabelle oben, + `deleted_at` TIMESTAMP für Soft-Delete)
- `contacts` — Kontakt-Tabelle (siehe Feld-Tabelle oben, + `deleted_at` TIMESTAMP für Soft-Delete)

---

## 5. Nicht-funktionale Anforderungen (vollständige Tabelle)

| ID | Kategorie | Anforderung | Metrik |
|----|-----------|-------------|--------|
| NF-01 | Performance | API-Response <500ms bei 200k Datensätzen | 95th Percentile <500ms |
| NF-02 | Skalierung | DB-Connection-Pooling (SQLAlchemy Pool size=10) | Keine Connection-Erschöpfung bei 10 concurrent Users |
| NF-03 | Sicherheit | Alle Passwörter bcrypt-gehashed (cost=12) | Keine Plain-Text-Passwörter in DB |
| NF-04 | Sicherheit | Session-Secret via Env-Var, min 32 Zeichen | App startet nicht ohne Secret |
| NF-05 | Verfügbarkeit | Health-Check für Coolify Auto-Restart | Auto-Restart bei 503 |
| NF-06 | Wartbarkeit | Code-Struktur: `api/`, `models/`, `schemas/`, `services/`, `tests/` | Klare Trennung |
| NF-07 | Wartbarkeit | Linting: ruff + black, pre-commit-hook | CI blockt bei Lint-Fehlern |
| NF-08 | Testbarkeit | pytest Coverage >80% Backend | Coverage-Report in CI |
| NF-09 | i18n | DE + EN, Sprachwahl persistiert | Alle UI-Texte übersetzt |
| NF-10 | Accessibility | WCAG 2.1 AA | axe-Check: 0 Violations |
| NF-11 | Logging | Strukturierte JSON-Logs | `docker logs` zeigt JSON-Einträge |
| NF-12 | Deployment | Docker-Container auf Coolify | `docker-compose.yml` + `Dockerfile` |

---

## 6. Annahmen (entfernte Details)

1. **Multi-Tenant (Multi-Company):** v1 ist Multi-Tenant (Multi-Company) — mehrere Organisationen, mehrere User.
2. **PostgreSQL statt SQLite:** Bei 200k Kontakten + Multi-User + Concurrent Writes wird PostgreSQL empfohlen. SQLite limitiert auf ~15 concurrent updates/sec vs PostgreSQL ~1500/sec.
3. **SPA-Frontend:** Client-side rendering mit React SPA (bestätigt durch genehmigten Prototyp leocrm-prototype-x7k2p9, v7).
4. **Max 10 concurrent Users:** v1 ist für kleine Teams, nicht für Enterprise.
5. **E-Mail-Versand:** SMTP via externem Provider (Mailtrap für Dev, Production-SMTP für Prod).
6. **Soft-Delete als Default:** Firmen und Kontakte werden soft-deleted (recoverable), außer DSGVO-Löschung (hard delete).
7. **Rollensystem v1:** 3 Rollen: admin, editor, viewer.
8. **Export-Limit:** Export von >50k Datensätzen als Background-Job, <50k als direkter Download.
9. **i18n-Default:** Deutsch ist Default-Sprache, Englisch ist zweites Locale.
10. **Python 3.12:** Aktuelle stabile Python-Version.

---

## 7. Technologie-Wahlen (Alle Module)

### Core-Stack
| Technologie | Verwendung |
|-------------|-----------|
| FastAPI | Backend-Framework |
| SQLAlchemy 2.0 | ORM |
| PostgreSQL 16 | Datenbank |
| React 18 SPA | Frontend |
| Uvicorn (async) | ASGI-Server |
| ruff + black | Linting |
| pytest + httpx | Backend-Tests |
| Vitest | Frontend-Tests |
| Playwright | E2E-Tests |
| Pydantic | Input-Validierung |
| bcrypt (cost=12) | Passwort-Hashing |
| Celery / ARQ / FastAPI BackgroundTasks | Background-Jobs |
| react-i18next | i18n-Frontend |
| Docker Compose | Multi-Container-Deployment |
| Coolify | Deployment-Plattform |

### DMS-Modul
| Technologie | Verwendung |
|-------------|-----------|
| PDF.js | PDF-Preview im Browser |
| OnlyOffice Document Server | Online-Bearbeitung (separater Container) |

### Mail-Modul
| Technologie | Verwendung |
|-------------|-----------|
| IMAP4rev1 (RFC 3501) | Mail-Empfang |
| IMAP IDLE (RFC 2177) | Real-time Push für neue Mails |
| SMTP Submission (RFC 6409) | Mail-Versand |
| DOMPurify | HTML-Sanitization (XSS-Schutz) |
| python-gnupg | PGP-Verschlüsselung (OpenPGP, RFC 4880) |
| PostgreSQL Full-Text Search (tsvector) | Volltext-Suche über Mails |
| AES-256 | Passwort-Verschlüsselung für IMAP/SMTP-Credentials |

---

## 8. Farbcodes (Hex-Werte)

### Kalender-Modul (F-CAL-06)

| Eintrags-Typ | Subtyp | Farbe (Hex) |
|-------------|-------|-------------|
| appointment | normal | `#3B82F6` (blau) |
| task | normal | `#F59E0B` (gelb) |
| * | follow_up | `#F97316` (orange) |
| * | private | `#9CA3AF` (grau) |

### Tag-System (F-TAG-02)
- Tags können mit Farbe versehen werden, z.B. `#FF0000` für „VIP"

---

## 9. Protokoll-Details (Mail-Modul)

### IMAP
- **Protokoll:** IMAP4rev1 (RFC 3501)
- **IDLE:** RFC 2177 für Push, Fallback: Polling alle 5 Min
- **Port:** 993 (SSL/TLS)
- **Auth:** PLAIN/LOGIN
- **MOVE:** RFC 6851 (Fallback: COPY + STORE \\Deleted + EXPUNGE)
- **Flags:** `\\Seen`, `\\Flagged`, `\\Answered`, `\\Draft`, `$Spam`
- **Kompatibilität:** Getestet mit Dovecot, Courier IMAP

### SMTP
- **Protokoll:** SMTP Submission (RFC 6409)
- **Port 587:** mit STARTTLS
- **Port 465:** mit SSL
- **Auth:** PLAIN/LOGIN mit Benutzername+Passwort

### PGP
- **Standard:** OpenPGP (RFC 4880)
- **Library:** python-gnupg
- **Private Key:** verschlüsselt gespeichert (AES-256 + Passphrase)
- **Passphrase:** nicht gespeichert, nur im Session-Cache
- **Public Key:** pro Kontakt speicherbar
- **S/MIME:** post-MVP

### Attachment-Storage
- Anhänge werden lokal gespeichert (Dateisystem oder S3)
- Nicht im IMAP-Server belassen (Caching)
- Mail-Body wird in PostgreSQL gespeichert
- Anhänge bei Bedarf vom IMAP-Server nachgeladen
- Max: 25 MB pro Anhang, 50 MB pro Mail

### Passwort-Speicherung
- IMAP/SMTP-Passwörter AES-256 verschlüsselt
- Key via Env-Var `MAIL_ENCRYPTION_KEY`

### Ordner-Mapping
- INBOX → Posteingang
- Sent → Postausgang
- Drafts → Entwürfe
- Spam/Junk → Spam

### Threading
- Basierend auf `References`- und `In-Reply-To`-Headern (RFC 5322)

### HTML-Rendering
- Sanitization mit DOMPurify (XSS-Schutz)
- Inline-Styles erlaubt, Scripts/IFrames entfernt
- Plain-Text-Fallback

---

## 10. RFC-Referenzen (alle)

| RFC | Titel | Verwendung |
|-----|-------|-----------|
| RFC 3501 | IMAP4rev1 | Mail-Empfang |
| RFC 2177 | IMAP IDLE | Real-time Push |
| RFC 6851 | IMAP MOVE | Mail verschieben |
| RFC 6409 | SMTP Submission | Mail-Versand |
| RFC 4880 | OpenPGP | PGP-Verschlüsselung |
| RFC 5322 | Internet Message Format | Threading (References/In-Reply-To) |
| RFC 5545 | iCalendar | Recurrence Rules (RRULE) für wiederkehrende Termine |
| RFC 6047 | iMIP | (Non-Goal: nicht in v2-mail) |
| RFC 8620 | JMAP | (Non-Goal: nicht unterstützt) |

---

## 11. DMS-Modul: HTTP-Endpunkte & Architektur-Details

### F-DMS-01: Ordner-Struktur
- **Create:** POST `/api/dms/folders` → 201
- **Rename/Move:** PATCH `/api/dms/folders/{id}` → 200
- **Delete:** DELETE `/api/dms/folders/{id}` → 200 (Soft-Delete)
- **Zirkuläre Verschiebung:** serverseitig verhindert → 422

### F-DMS-02: Datei-Upload
- **Endpoint:** POST `/api/dms/files/upload` (multipart) → 201 mit Datei-Metadaten
- **Max-Size:** 413 bei Überschreitung (Default 100 MB)
- **Status:** WebSocket oder Polling

### F-DMS-03: Datei-Operationen
- **Rename:** PATCH `/api/dms/files/{id}` → 200
- **Move:** PATCH `/api/dms/files/{id}` mit `folder_id` → 200
- **Delete:** DELETE `/api/dms/files/{id}` → 200 (Soft-Delete)
- **Restore:** POST `/api/dms/files/{id}/restore` → 200

### F-DMS-04: PDF-Preview
- **Endpoint:** GET `/api/dms/files/{id}/preview` → 200 mit `Content-Type: application/pdf`
- **Frontend:** PDF.js
- **Non-PDF:** 415 Unsupported Media Type

### F-DMS-05: OnlyOffice Integration
- **Server:** OnlyOffice Document Server als separater Container (Coolify)
- **Endpoint:** POST `/api/dms/files/{id}/edit-session` → 200 mit OnlyOffice-URL
- **Formate:** DOCX, XLSX, PPTX

### F-DMS-06: Datei-Metadaten
- **Endpoint:** GET `/api/dms/files/{id}` → 200 mit `{name, size, mime_type, uploaded_at, modified_at, uploaded_by}`
- **Größe:** serverseitig in Bytes, clientseitig formatiert

### F-DMS-07: Datei-Suche
- **Endpoint:** GET `/api/dms/search?q=vertrag&folder_id={id}` → 200 mit `{items: [{type, name, path, ...}]}`
- **Global:** ohne `folder_id` → gesamte DMS

### F-LINK-01: Dateien mit Firmen verknüpfen
- **Endpoint:** POST `/api/dms/files/{id}/link` mit `{entity_type: "company", entity_id: N}` → 201
- **Delete:** DELETE `/api/dms/files/{id}/link?entity_type=company&entity_id=N` → 204
- **Unique Constraint:** Duplikate serverseitig verhindert

### F-LINK-02: Dateien mit Kontakten verknüpfen
- **Endpoint:** POST `/api/dms/files/{id}/link` mit `{entity_type: "contact", entity_id: N}` → 201

### F-LINK-03: Verknüpfte Dateien in Firmen-Detail
- **Response:** GET `/api/companies/{id}` enthält `linked_files: [{id, name, size, mime_type, modified_at}]`

### F-LINK-04: Verknüpfte Dateien in Kontakt-Detail
- **Response:** GET `/api/contacts/{id}` enthält `linked_files: [{id, name, size, mime_type, modified_at}]`

### F-LINK-05: Reverse-Verknüpfung
- **Response:** GET `/api/dms/files/{id}` enthält `linked_entities: [{entity_type, entity_id, entity_name}]`
- **Delete:** DELETE `/api/dms/files/{id}/link?entity_type=company&entity_id=N` → 204

### F-LINK-06: Mehrfach-Verknüpfung
- **Bulk:** POST `/api/dms/files/bulk-link` mit `{file_ids: [...], entity_type: "company", entity_id: N}` → 201
- **Ordner:** POST `/api/dms/folders/{id}/link`

### F-TAG-01: Tags anwenden
- **Assign:** POST `/api/tags/assign` mit `{entity_type, entity_id, tag_id}` → 201
- **Remove:** DELETE `/api/tags/assign?entity_type=...&entity_id=...&tag_id=...` → 204
- **Unique Constraint:** (entity_type, entity_id, tag_id)

### F-TAG-02: Tag-Verwaltung
- **Create:** POST `/api/tags` (Admin) → 201
- **Update:** PATCH `/api/tags/{id}` → 200
- **Delete:** DELETE `/api/tags/{id}` → 204 mit Cascade Delete auf `tag_assignments`
- **Non-Admin:** → 403

### F-TAG-03: Tag-Filterung
- **Endpoint:** GET `/api/companies?tag_ids=1,2&tag_mode=and` → 200
- **Modi:** `tag_mode=or` → OR-Verknüpfung
- **Gleiche Parameter** für `/api/contacts`, `/api/dms/files`

### F-TAG-04: Tag-Cloud
- **Endpoint:** GET `/api/tags?with_counts=true` → 200 mit `[{id, name, color, count}]`

### F-PERM-01: Persönlicher Root-Ordner
- **User-Creation:** automatisch `personal_folder_id` gesetzt
- **Ownership-Check:** GET `/api/dms/folders/{id}` prüft Ownership → 403 bei fremdem Ordner (außer Admin)

### F-PERM-02: Gemeinsame Root-Ordner
- **Create:** POST `/api/dms/folders` mit `shared_with_group_id` → 201
- **Permissions:** `folder_permissions` Tabelle (folder_id, group_id, permission: read|write)

### F-PERM-03: Datei/Ordner mit Usern teilen
- **Share:** POST `/api/dms/files/{id}/share` mit `{user_id, permission: "read|write"}` → 201
- **Remove:** DELETE `/api/dms/files/{id}/share?user_id=N` → 204
- **Shared-with-me:** GET `/api/dms/shared-with-me` → 200

### F-PERM-04: Datei/Ordner mit Gruppen teilen
- **Share:** POST `/api/dms/files/{id}/share` mit `{group_id, permission: "read|write"}` → 201
- **Resolution:** Individual > Group > Default (Deny vor Allow)
- **Remove:** DELETE `/api/dms/files/{id}/share?group_id=N` → 204

### F-PERM-05: Share-Links
- **Create:** POST `/api/dms/files/{id}/share-link` mit `{password?, expires_at?, download_only?}` → 201 mit `{url}`
- **Public:** GET `/api/public/share/{token}` → 200 (oder 401 bei Passwort, 410 bei abgelaufen)
- **Public-Endpoint:** braucht keine Auth

### F-PERM-06: Berechtigungs-Anzeige
- **Endpoint:** GET `/api/dms/files/{id}/permissions` → 200 mit `{owner: {id, name}, shares: [{user_id?, group_id?, name, permission}], share_links: [{id, url, has_password, expires_at, is_active}]}`

### F-FILEUI-01: Datei-Browser
- **Komponenten:** `FileBrowser` mit `SidebarTree` + `MainView` (Grid/List Toggle)
- **State-Management:** für aktiven Ordner

### F-FILEUI-02: Breadcrumb-Navigation
- **Komponente:** `Breadcrumb` mit klickbaren Segmenten
- **Pfad:** aus `folder.path` (Materialized Path oder rekursive Abfrage) generiert

### F-FILEUI-03: Kontext-Menü
- **Komponente:** `ContextMenu` mit dynamischen Items basierend auf `entity_type` (file/folder) und `permission` (read/write)
- **Mobile:** Long-Press statt Rechtsklick

### F-FILEUI-04: Bulk-Aktionen
- **Move:** POST `/api/dms/files/bulk-move` mit `{file_ids: [...], target_folder_id}` → 200
- **Delete:** POST `/api/dms/files/bulk-delete` → 200
- **Tag:** POST `/api/tags/bulk-assign` → 201

### F-FILEUI-05: Upload-Progress
- **Komponente:** `UploadProgress` mit pro-Datei Progress
- **Upload:** via `XMLHttpRequest` (für Progress-Events) oder WebSocket

### F-FILEUI-06: Drag & Drop
- **Frontend:** HTML5 Drag & Drop API
- **Drop-Target:** validiert Permission clientseitig (grün = erlaubt, rot = verboten)
- **Server:** PATCH `/api/dms/files/{id}` mit `folder_id` → Permission-Check → 200 oder 403

---

## 12. Kalender-Modul: HTTP-Endpunkte & Architektur-Details

### Architektur-Hinweis

Ein Kalender-Eintrag (`CalendarEntry`) hat einen `entry_type`:
- **`appointment`** — Termin mit Start/Ende (Datum+Zeit), optional Ganztägig, Ort, Teilnehmer
- **`task`** — Aufgabe mit Fälligkeitsdatum (due_date), Priorität, Status, Sub-Tasks, Zuständiger — keine feste Uhrzeit

Beide Typen teilen sich die gleichen Verknüpfungs-, Erinnerungs-, Wiederholungs- und Anzeige-Mechanismen.

### F-CAL-01: Kalender-Ansichten
- **Frontend:** `CalendarView` Komponente mit `mode: month|week|day`
- **Endpoint:** GET `/api/calendar/entries?from=2026-06-01&to=2026-06-30` → 200 mit Entry-Array

### F-CAL-02: Kanban-Zeitraum-Ansicht
- **Frontend:** `KanbanCalendar` Komponente mit `period: this_week|next_2_weeks|this_month|custom`
- **Endpoint:** GET `/api/calendar/kanban?period=this_week` → 200 mit `{columns: [{date, appointments: [...], tasks: [...]}]}`

### F-CAL-03: Kalender-Eintrag erstellen
- **Endpoint:** POST `/api/calendar/entries` → 201
- **Fields appointment:** `entry_type`, `title`, `description?`, `start_at`, `end_at`, `all_day?`, `location?`, `attendees?`
- **Fields task:** `entry_type`, `title`, `description?`, `due_date?`, `priority: "high|medium|low"`, `status?: "open"`
- **Validierung:** end_at > start_at (außer all_day=true); title nicht leer

### F-CAL-04: Einträge mit Entitäten verknüpfen
- **Link:** POST `/api/calendar/entries/{id}/link` mit `{entity_type: "company|contact|deal", entity_id: N}` → 201
- **Response companies:** GET `/api/companies/{id}` enthält `upcoming_events: [...]` und `open_tasks: [...]`

### F-CAL-05: Drag & Drop im Kalender
- **Frontend:** HTML5 Drag & Drop auf Kalender-Zellen (appointments) und Kanban-Spalten (tasks)
- **Update:** PATCH `/api/calendar/entries/{id}` mit neuem `start_at`/`end_at` (appointment) oder `status` (task) → 200
- **Optimistic Update** mit Rollback bei Fehler

### F-CAL-06: Farbcodierung
- **Fields:** `entry_type: appointment|task` und `subtype: normal|follow_up|private`
- **Color Map:** `{appointment+normal: "#3B82F6", task+normal: "#F59E0B", *+follow_up: "#F97316", *+private: "#9CA3AF"}`
- **Update:** PATCH `/api/calendar/entries/{id}` mit `subtype` → 200

### F-CAL-07: Erinnerungen/Alerts
- **Field:** `reminder: {value: N, unit: "minutes|hours|days", channel: "in_app|email"}`
- **Background-Job:** prüft fällige Erinnerungen (Cron, minütlich)
- **Notification:** POST `/api/notifications` bei Fälligkeit
- **Überfällig-Check:** täglicher Cron-Job

### F-CAL-08: Wiederkehrende Einträge
- **Field:** `recurrence: {pattern: "daily|weekly|monthly|yearly|custom", custom_rule?, end_date?, exceptions?: [dates]}`
- **Appointments:** Server generiert Instanzen via RRULE (RFC 5545)
- **Tasks:** bei Status-Wechsel auf `done` → POST `/api/calendar/entries` mit neuem `due_date`
- **Status `cancelled`:** keine Generierung

### F-CAL-09: Kalender-Feeds (ICS)
- **Export:** GET `/api/calendar/{calendar_id}/ics-feed?token={user_token}` → 200 mit `Content-Type: text/calendar` (RFC 5545 konform)
- **Import:** POST `/api/calendar/import` (multipart ICS, optional calendar_id) → 201 mit `{imported: N, skipped: M}`
- **Auth:** Token-basierte Auth für Feed-URL

### F-CAL-10: Ressourcen-Booking
- **Create Resource:** POST `/api/resources` (Admin) → 201
- **Book:** POST `/api/calendar/entries/{id}/book-resource` mit `{resource_id}` → 201 oder 409 bei Konflikt
- **Bookings:** GET `/api/resources/{id}/bookings?from=...&to=...` → 200

### F-CAL-11: Mehrere Kalender
- **Create:** POST `/api/calendars` mit `{name, color, type: "personal|team|project|company"}` → 201
- **Auto-Create:** bei User-Anlage automatisch POST `/api/calendars` mit `{name: "Mein Kalender", type: "personal"}`
- **List:** GET `/api/calendars` → 200 mit sichtbaren Kalendern
- **Delete:** DELETE `/api/calendars/{id}` → 204 (Cascade auf Einträge)

### F-CAL-12: Kalender abonnieren
- **Frontend:** `CalendarSidebar` mit Toggle-Switches pro Kalender
- **Endpoint:** GET `/api/calendar/entries?calendar_ids=1,3,5` → 200
- **State:** persistiert pro User (`user_calendar_visibility` Tabelle)

### F-CAL-13: Kalender teilen
- **Share:** POST `/api/calendars/{id}/share` mit `{user_id?, group_id?, permission: "read|write"}` → 201
- **Remove:** DELETE `/api/calendars/{id}/share?user_id=N` → 204
- **Permissions:** GET `/api/calendars/{id}/permissions` → 200 mit `{owner, shares}`

### F-CAL-14: Default-Kalender
- **Setting:** `default_calendar_id` (User-Setting)
- **Update:** PATCH `/api/users/me/settings` mit `{default_calendar_id: N}` → 200
- **Fallback:** persönlicher Kalender bei keinem Setting

### F-CAL-15: Aufgaben-Zuweisung
- **Field:** `assigned_to: user_id` (nur für entry_type=task)
- **Update:** PATCH `/api/calendar/entries/{id}` mit `assigned_to` → 200, sendet Notification
- **Query:** GET `/api/calendar/entries?entry_type=task&assigned_to={user_id}` → 200

### F-CAL-16: Sub-Tasks
- **Create:** POST `/api/calendar/entries/{id}/subtasks` mit `{title}` → 201 (nur für entry_type=task)
- **Update:** PATCH `/api/calendar/entries/{id}/subtasks/{sub_id}` mit `{completed: true}` → 200
- **Response:** GET `/api/calendar/entries/{id}` enthält `subtasks: [{id, title, completed}]` und `progress: {completed, total}`

### F-CAL-17: Aufgaben-Filter & Liste
- **Query:** GET `/api/calendar/entries?entry_type=task&assigned_to={id}&priority=high&status=open&due_filter=overdue&page=1&page_size=25&sort_by=due_date&sort_order=asc` → 200 mit `{items, total, page, page_size}`
- **Export:** GET `/api/calendar/entries/export?format=csv&entry_type=task&status=open` → 200 mit CSV-Download
- **Frontend:** `TaskKanban` (4 Spalten) und `TaskList` (DataTable) Komponenten

### F-CAL-18: Bulk-Aktionen
- **Endpoint:** POST `/api/calendar/entries/bulk` mit `{entry_ids: [...], action: "status|assign|due_date|delete", value: ...}` → 200 mit `{updated: N}`

---

## 13. Mail-Modul: HTTP-Endpunkte & Architektur-Details

### F-MAIL-01: Standard-Ordner
- **Endpoint:** GET `/api/mail/folders` → 200 mit `{folders: [{id, name, type: "inbox|sent|drafts|spam|custom", unread_count, total_count}]}`
- **IMAP IDLE-Listener:** läuft als Background-Task, neue Mails innerhalb von 5 Sekunden
- **Bidirektionale Flag-Sync:** \\Seen, \\Flagged, \\Answered, \\Draft, $Spam

### F-MAIL-02: E-Mail schreiben
- **Send:** POST `/api/mail/send` mit `{to: [...], cc: [...], bcc: [...], subject, body_html, in_reply_to?, attachments: [...]}` → 201
- **Draft:** POST `/api/mail/drafts` → speichert Entwurf
- **Reply:** POST `/api/mail/{id}/reply` → erstellt Reply mit vorausgefüllten Feldern
- **Forward:** POST `/api/mail/{id}/forward` → erstellt Forward
- **HTML-Sanitization:** DOMPurify

### F-MAIL-03: Volltext-Suche
- **Endpoint:** GET `/api/mail/search?q=angebot&folder=inbox&date_from=...&date_to=...` → 200 mit `{items: [{id, subject, from, date, snippet, folder}], total}`
- **Index:** PostgreSQL tsvector-Index über `mail_body_tsv` und `mail_subject_tsv`
- **Performance:** <500ms bei 10.000 Mails

### F-MAIL-04: Anhänge
- **Send:** POST `/api/mail/send` mit multipart-Form-Data für Anhänge
- **Download:** GET `/api/mail/{id}/attachments/{att_id}` → 200
- **Content-Disposition:** `attachment` für Downloads, `inline` für inline-Bilder
- **Max:** 25 MB pro Anhang, 50 MB pro Mail

### F-MAIL-05: Threading
- **Endpoint:** GET `/api/mail/threads?folder=inbox` → 200 mit `{items: [{thread_id, subject, participants, message_count, last_date, messages: [{id, from, date, snippet}]}]}`
- **Basis:** `In-Reply-To`/`References`-Header (RFC 5322)
- **Frontend:** `ThreadView` Komponente

### F-MAIL-06: Vorlagen/Templates
- **Create:** POST `/api/mail/templates` mit `{name, subject, body_html, shared: false}` → 201
- **List:** GET `/api/mail/templates?scope=me|shared` → 200
- **Compose:** POST `/api/mail/compose?template_id=N&contact_id=M&company_id=K` → 200 mit aufgelösten Platzhaltern
- **Syntax:** `{{entity.field}}`

### F-MAIL-07: Filter/Regeln
- **Create:** POST `/api/mail/rules` mit `{name, conditions: [{field, operator, value}], actions: [{type, value}]}` → 201
- **Evaluation:** Background-Worker nach IMAP-IDLE-Trigger
- **List:** GET `/api/mail/rules` → 200
- **Delete:** DELETE `/api/mail/rules/{id}` → 204

### F-MAIL-08: Abwesenheitsnotiz
- **Endpoint:** POST `/api/mail/vacation` mit `{active: true, subject, body, start_date, end_date}` → 201
- **Background-Worker:** prüft eingehende Mails, `vacation_sent_log` Tabelle (einmal pro Absender)
- **No-Reply-Erkennung:** Absender enthält „noreply", „no-reply", „donotreply"

### F-MAIL-09: Labels/Flags
- **Flag:** PATCH `/api/mail/{id}/flags` mit `{starred: true}` → 200, setzt IMAP \\Flagged
- **Label:** POST `/api/mail/{id}/labels` mit `{label_id: N}` → 201
- **Filter:** GET `/api/mail?label=vertrieb` → 200
- **Label-Verwaltung:** POST `/api/mail/labels` mit `{name, color}`

### F-MAIL-10: Kontakt-Verknüpfung
- **Contact-Mails:** GET `/api/contacts/{id}/emails` → 200 mit `{items: [{id, subject, from, date, direction: "in|out", thread_id}]}`
- **Company-Mails:** GET `/api/companies/{id}/emails` → 200
- **Auto-Verknüpfung:** Background-Job matcht Absender/Empfänger gegen `contacts.email`-Feld
- **Manual:** POST `/api/mail/{id}/link` mit `{contact_id, company_id}`

### F-MAIL-11: Kalender-Integration
- **Endpoint:** POST `/api/mail/{id}/create-event` mit `{date, time, duration, calendar_id?, title?}` → 201
- **Defaults:** Titel = Mail-Betreff, Beschreibung = Mail-Body (plain text), Teilnehmer = Mail-Absender
- **Link:** `calendar_entry.source_mail_id = mail.id`

### F-MAIL-12: PGP-Verschlüsselung
- **Import Private Key:** POST `/api/mail/pgp/keys` mit `{private_key, passphrase}` → 201 (verschlüsselt gespeichert)
- **Import Public Key:** POST `/api/contacts/{id}/pgp-key` mit `{public_key}` → 201
- **Encrypt Send:** POST `/api/mail/send` mit `{encrypt: true}` → python-gnupg Verschlüsselung
- **Decrypt:** GET `/api/mail/{id}` → erkennt PGP-Block, entschlüsselt bei vorhandener Passphrase (Session-Cache)

### F-MAIL-13: Signaturen
- **Create:** POST `/api/mail/signatures` mit `{name, body_html}` → 201
- **Assign Default:** PATCH `/api/mail/accounts/{id}` mit `{default_signature_id: N}` → 200
- **Compose:** POST `/api/mail/compose?account_id=N` → Response enthält `signature`-Feld

### F-MAIL-14: Mehrere Postfächer
- **Create:** POST `/api/mail/accounts` mit `{name, imap_host, imap_port, imap_ssl, smtp_host, smtp_port, smtp_ssl, username, password}` → 201 (Passwort verschlüsselt)
- **List:** GET `/api/mail/accounts` → 200
- **Default:** PATCH `/api/users/me/settings` mit `{default_mail_account_id: N}`

### F-MAIL-15: Geteilte Postfächer
- **Create:** POST `/api/mail/accounts` mit `{type: "shared", name: "info@firma.de", ...}` → 201
- **Assign Users:** POST `/api/mail/accounts/{id}/users` mit `{user_ids: [1, 2, 3]}` → 200
- **List:** GET `/api/mail/accounts/shared` → 200
- **Seen-By:** `mail_seen_by` Tabelle (mail_id, user_id, seen_at)

### F-MAIL-16: Stellvertretung
- **Delegate:** POST `/api/mail/accounts/{id}/delegates` mit `{delegate_user_id, permission: "read|full"}` → 201
- **Remove:** DELETE `/api/mail/accounts/{id}/delegates?user_id=N` → 204
- **List:** GET `/api/mail/accounts?include_delegated=true` → 200 mit `delegated: true` Markierung

### F-MAIL-17: Sende-Berechtigungen
- **Grant:** POST `/api/mail/accounts/{id}/send-permissions` mit `{user_ids: [...]}` → 200
- **List:** GET `/api/mail/accounts/{id}/send-permissions` → 200
- **Send-Check:** POST `/api/mail/send` mit `{from_account_id: N}` → prüft, 403 wenn nicht

### F-MAIL-18: Postfach-Konfiguration
- **Create:** POST `/api/mail/accounts` mit `{imap_host, imap_port, imap_ssl: true, smtp_host, smtp_port, smtp_starttls: true, username, password}`
- **Validierung:** IMAP-Login + SMTP-Login, 422 bei Fehler
- **Verschlüsselung:** AES-256, Key via Env-Var `MAIL_ENCRYPTION_KEY`
- **Maskierung:** GET `/api/mail/accounts/{id}` → Passwort-Feld ist `***`

### F-MAIL-19: Mail-Ordner verwalten
- **Create:** POST `/api/mail/folders` mit `{name, parent_id?}` → 201, führt IMAP CREATE aus
- **Rename:** PATCH `/api/mail/folders/{id}` mit `{name}` → 200, führt IMAP RENAME aus
- **Delete:** DELETE `/api/mail/folders/{id}` → 204, führt IMAP DELETE aus

---

## 14. Mail-Modul: Technische Constraints (vollständige Tabelle)

| Constraint | Beschreibung |
|-----------|-------------|
| IMAP-Protokoll | IMAP4rev1 (RFC 3501) — Server muss IMAP IDLE (RFC 2177) für Push unterstützen |
| SMTP-Protokoll | SMTP Submission (RFC 6409) — Port 587 mit STARTTLS oder Port 465 mit SSL |
| Auth | SMTP: PLAIN/LOGIN mit Benutzername+Passwort; IMAP: PLAIN/LOGIN |
| Attachment-Storage | Anhänge lokal gespeichert (DMS-Integration), nicht im IMAP-Server belassen (Caching) |
| IMAP IDLE | Real-time Push; Fallback: Polling alle 5 Min |
| Volltext-Suche | PostgreSQL Full-Text Search (tsvector) über Mail-Body + Anhang-Namen (OCR optional post-MVP) |
| HTML-Rendering | Sanitization mit DOMPurify (XSS-Schutz); Plain-Text-Fallback |
| Verschlüsselung | PGP (OpenPGP, RFC 4880) via python-gnupg; S/MIME post-MVP |
| Mail-Sync | Bidirektionale Sync: IMAP-Flags (Seen/Flagged) synchronisiert |
| Ordner-Mapping | INBOX→Posteingang, Sent→Postausgang, Drafts→Entwürfe, Spam/Junk→Spam |
| Passwort-Speicherung | IMAP/SMTP-Passwörter AES-256 verschlüsselt, Key via Env-Var MAIL_ENCRYPTION_KEY |
| Max Anhang-Größe | 25 MB pro Anhang, 50 MB pro Mail |

---

## 15. Mail-Modul: Annahmen

1. **IMAP-Server-Kompatibilität:** IMAP4rev1 (RFC 3501), getestet mit Dovecot, Courier IMAP.
2. **SMTP-Auth:** SMTP-Server muss Authentifizierung unterstützen (PLAIN/LOGIN). Kein Open-Relay.
3. **IMAP IDLE:** Server muss RFC 2177 unterstützen. Fallback: Polling alle 5 Minuten.
4. **IMAP MOVE:** Server muss RFC 6851 unterstützen. Fallback: COPY + STORE \\Deleted + EXPUNGE.
5. **Attachment-Storage:** Lokal (Dateisystem oder S3), Caching in PostgreSQL.
6. **Maximale Anhang-Größe:** 25 MB pro Anhang, 50 MB pro Mail.
7. **Passwort-Speicherung:** AES-256 verschlüsselt, Key via `MAIL_ENCRYPTION_KEY`.
8. **HTML-Sanitization:** DOMPurify, Inline-Styles erlaubt, Scripts/IFrames entfernt.
9. **Multi-Tenant (Multi-Company):** Mail-Modul ist Multi-Tenant (Multi-Company).
10. **PGP-Key-Verwaltung:** Private Keys verschlüsselt (AES-256 + Passphrase). Passphrase nicht gespeichert, nur Session-Cache.

---

## 16. Implizite DB-Tabellen (aus allen Akzeptanzkriterien extrahiert)

| Tabelle | Modul | Zweck |
|---------|-------|-------|
| `users` | Core | User (email, name, role, password_hash, default_calendar_id, default_mail_account_id) |
| `companies` | Core | Firmen (siehe Feld-Tabelle + deleted_at, created_at) |
| `contacts` | Core | Kontakte (siehe Feld-Tabelle + deleted_at, created_at) |
| `company_contacts` | Core | N:M-Verknüpfung (company_id, contact_id) |
| `audit_log` | Core | Audit (user, action, entity, entity_id, timestamp) |
| `deletion_log` | Core | Unveränderliche DSGVO-Lösch-Logs |
| `dms_folders` | DMS | Ordner (id, name, parent_id, owner_id, deleted_at) |
| `dms_files` | DMS | Dateien (id, name, folder_id, size, mime_type, uploaded_at, modified_at, uploaded_by, deleted_at) |
| `file_links` | DMS | Verknüpfung (file_id, entity_type, entity_id) — Unique Constraint |
| `tags` | DMS | Tags (id, name, color) |
| `tag_assignments` | DMS | Zuordnung (entity_type, entity_id, tag_id) — Unique Constraint |
| `folder_permissions` | DMS | (folder_id, group_id, permission: read|write) |
| `file_shares` | DMS | (file_id, user_id?, group_id?, permission) |
| `share_links` | DMS | (file_id, token, password?, expires_at?, download_only?) |
| `calendar_entries` | Kalender | (id, entry_type, title, description, start_at?, end_at?, due_date?, all_day?, location?, priority?, status?, assigned_to?, calendar_id, subtype, reminder, recurrence) |
| `calendars` | Kalender | (id, name, color, type, owner_id) |
| `calendar_entry_links` | Kalender | (entry_id, entity_type, entity_id) |
| `calendar_shares` | Kalender | (calendar_id, user_id?, group_id?, permission) |
| `user_calendar_visibility` | Kalender | (user_id, calendar_id, visible) |
| `subtasks` | Kalender | (entry_id, title, completed) |
| `resources` | Kalender | (id, name, type) — später |
| `resource_bookings` | Kalender | (resource_id, entry_id, from, to) — später |
| `mail_accounts` | Mail | (id, user_id, name, imap_host, imap_port, imap_ssl, smtp_host, smtp_port, smtp_ssl/starttls, username, password_encrypted, type) |
| `mails` | Mail | (id, account_id, folder_id, subject, body_html, body_text, from, to, cc, bcc, date, in_reply_to, references, thread_id, seen, flagged, has_attachments) |
| `mail_attachments` | Mail | (mail_id, filename, mime_type, size, dms_file_id) |
| `mail_folders` | Mail | (id, account_id, name, type, parent_id, unread_count, total_count) |
| `mail_labels` | Mail | (id, name, color) |
| `mail_label_assignments` | Mail | (mail_id, label_id) |
| `mail_rules` | Mail | (id, account_id, name, conditions, actions, priority) |
| `mail_templates` | Mail | (id, user_id, name, subject, body_html, shared) |
| `mail_signatures` | Mail | (id, user_id, name, body_html) |
| `vacation_sent_log` | Mail | (account_id, sender_address, sent_at) |
| `mail_seen_by` | Mail | (mail_id, user_id, seen_at) |
| `mail_account_delegates` | Mail | (account_id, delegate_user_id, permission) |
| `mail_account_send_permissions` | Mail | (account_id, user_id) |
| `pgp_keys` | Mail | (user_id, private_key_encrypted, public_key) |
| `contact_pgp_keys` | Mail | (contact_id, public_key) |
| `notifications` | Core | (id, user_id, type, title, body, created_at, read_at) |

---

## 17. Historische v0.1 Endpoints (archiviert)

| Endpoint | Historisch | Aktuell |
|----------|-----------|--------|
| POST `/login` | F-1 | POST `/api/auth/login` |
| POST `/logout` | F-2 | POST `/api/auth/logout` |
| GET `/companies` | F-5 | GET `/api/companies` |
| POST `/companies` | F-5 | POST `/api/companies` |
| DELETE `/companies/{id}` | F-8 | DELETE `/api/companies/{id}` |
| POST `/contacts` | F-10 | POST `/api/contacts` |
| GET `/api/health` | F-15 | GET `/api/health` |

### v0.1 Demo-Seed
- Beim ersten Start: 1 Admin (`admin`/`admin`), 2 Firmen, 3 Kontakte
- Frische DB → Seed-Daten vorhanden
- DB bereits befüllt → Seed überspringt

---

## 18. Non-Goals (alle Module, vollständig)

### v1 Non-Goals
1. Self-Registration (nur Admin legt User an)
2. ~~Multi-Tenant (Single-Tenant in v1)~~ — Multi-Tenant (Multi-Company) ist v1-Feature
3. Sales Pipeline / Deals
4. Kampagnen-Management
5. Mobile App (Native) — nur Responsive Web-UI
6. Offline-Support
7. AI-Features (Lead-Scoring, Auto-Enrichment)
8. Real-time Collaboration (Google Docs-style)
9. Webhooks für externe Systeme
10. Multi-Currency
11. Advanced Analytics/Dashboards (BI)
12. SSO/OAuth (nur E-Mail/Passwort)
13. Custom Fields (Standard-Felder fest definiert)
14. Two-Factor Auth (post-MVP)
15. PWA

### v2 DMS Non-Goals
1. Versionierung (History, Diff)
2. Volltext-Suche in Dokumenten (kein OCR, kein Volltext-Index)
3. Eigene Office-Suite (nur OnlyOffice)
4. E-Mail-Attachment aus DMS
5. Externes Sync (WebDAV/Nextcloud)
6. Watermarking

### v2 Kalender Non-Goals
1. Ressourcen-Booking (nur optional markiert)
2. Time-Tracking
3. Task-Templates
4. Automatisierte Task-Erstellung aus Triggern
5. Gantt-Diagramm
6. Öffentliche Kalender-Sync (außer ICS)

### v2 Mail Non-Goals
1. Google/Microsoft API (nur direkte IMAP/SMTP)
2. S/MIME (nur PGP in v2-mail)
3. Mail-Server-Hosting (nur Client)
4. Mailinglisten-Management
5. Newsletter-Tool
6. Mail-to-Ticket
7. OCR für Anhänge
8. Kalender-Einladungen per Mail (iMIP, RFC 6047)
9. JMAP (RFC 8620)
10. Push-Benachrichtigungen (Web Push) — nur In-App

---

**Ende der extrahierten Architektur-Details.**