chore: migrate project documentation into repo (18 files)

docs/01-requirements.md

@@ -0,0 +1,392 @@
+# CRM System – Requirements (v1.0 MVP)
+
+> Phase: INTAKE → REQUIREMENTS | Single-Tenant CRM | Status: Draft for User Approval
+> Stack: FastAPI + SQLAlchemy (async) + Alembic + Pydantic + SQLite/PostgreSQL + Alpine.js + Tailwind + Docker + Coolify
+> Auth: JWT im localStorage | Deployment: Coolify `localhost` standalone (uuid `lw80w8scs4044gwcw084s00s4`)
+
+## 1. Vision & Scope
+
+**Was ist v1?**
+v1 ist ein leichtgewichtiges, self-hosted CRM für kleine bis mittelgroße Sales-Teams (5–25 Vertriebler), die ihre Pipeline, Accounts, Contacts und Verkaufsaktivitäten an einem Ort bündeln wollen – ohne Salesforce-Lock-in, ohne Cloud-Zwang, ohne monatliche Lizenzkosten. Kern ist die tägliche Arbeit eines Sales-Reps: Account anlegen, Contact verknüpfen, Deal durch die Pipeline ziehen, Aktivitäten (Calls/Meetings/Notes) tracken, im Dashboard den Überblick behalten. Single-Tenant bedeutet: Eine Org, ein Server, ein Datenbestand – dafür aber voller Datenschutz, DSGVO-Konformität out-of-the-box und Coolify-Deployment per Knopfdruck.
+
+**Was ist v1 NICHT?**
+v1 ist **kein** Enterprise-CRM mit Multi-Tenancy, komplexem Permission-Granular-RBAC oder AI-Features. v1 hat **kein** integriertes Email-Marketing, keine Marketing-Automation, keine Lead-Scoring-Maschine. v1 ist **kein** Mobile-First-System (responsive Web ja, native App nein), **kein** Realtime-Collaboration-Tool (kein Websocket-Editing wie in Notion), und **kein** vollumfängliches Reporting-Suite (KPIs ja, Custom-Reports/Exports nein). v1 verzichtet bewusst auf komplexe Workflow-Engines, Sales-Territory-Management und Product-Catalog-Features.
+
+**Annahmen:**
+- Eine Org, ein Deployment, ein Datenbank-Container – kein Mandanten-Trennungs-Layer
+- Erster Admin wird per Bootstrap-Registrierung angelegt (kein Invite-Only-Flow)
+- Maximale User-Anzahl: 50 (Soft-Cap, Hard-Limit erst in v2 via DB-Constraint)
+- Sales-Reps arbeiten im 1:1 mit Accounts/Contacts, kein Shared-Inbox-Pattern
+- Browser: aktuelle Evergreen-Chrome/Firefox/Safari/Edge, kein IE11
+- Internet-Anbindung an Coolify-Server ist stabil, kein Offline-Modus
+
+**Non-Goals (explizit out):**
+- Multi-Tenancy / Mandantenfähigkeit (auch wenn `org_id` bereits in DB vorbereitet wird)
+- Email-Marketing-Automation (Newsletter, Drip-Campaigns)
+- Mobile-App (iOS/Android)
+- Lead-Scoring / AI-gestützte Next-Best-Action
+- Custom-Report-Builder / BI-Integration
+- Rechnungsstellung / Quote-to-Cash (kein CPQ)
+- Marketing-Attribution / UTM-Tracking
+- Telefonie-Integration (CTI, Twilio, etc.)
+- Slack/Teams-Integration
+- Custom-Fields-Builder (DB-Schema ist fix für v1)
+
+## 2. Personas & Haupt-Use-Cases
+
+**Persona 1: Sales-Rep (Primärnutzer)**
+- Use-Case: „Ich logge mich morgens ein, sehe im Dashboard meine offenen Deals und überfälligen Activities, arbeite die Calls ab, verschiebe gewonnene Deals in die Won-Stage, lege neue Accounts für Inbound-Leads an."
+- Use-Case: „Ich durchsuche meine Accounts nach Branche/Größe, öffne einen Account, sehe alle Contacts und letzten Activities, plane für nächste Woche ein Follow-up-Meeting und vergebe Tags zur Segmentierung."
+- Use-Case: „Ich öffne die Pipeline-View, sehe alle meine Deals als Kanban, ziehe einen Deal von ‚Qualified' nach ‚Proposal' und ergänze einen Note mit dem Verhandlungsstand."
+
+**Persona 2: Sales-Manager**
+- Use-Case: „Ich logge mich ein, prüfe die Team-Pipeline im Dashboard, sehe Won-this-Month, Conversion-Rate, und filtere die Pipeline auf den Rep, der Backlog hat."
+- Use-Case: „Ich lege einen neuen Sales-Rep-User an, vergebe die Rolle, und der Rep kann sofort loslegen."
+- Use-Case: „Ich passe Org-Info an (Name, Logo-URL, Default-Currency) und sehe im Audit-Log (falls aktiviert), wer wann welche Einstellung geändert hat."
+
+**Persona 3: Admin (technisch/organisatorisch)**
+- Use-Case: „Ich führe das initiale Bootstrap-Setup durch, lege den ersten Admin an, konfiguriere Org-Settings, und überwache Health/Backups in Coolify."
+
+## 3. Funktionale Anforderungen (FR)
+
+### FR-1: Authentication & User Management
+- **FR-1.1** Registrierung des ersten Admin-Users (Bootstrap, nur einmalig möglich wenn `users`-Tabelle leer)
+- **FR-1.2** Login (email + password) → JWT (24h expiry, HS256, im Response-Body)
+- **FR-1.3** Logout (JWT clientseitig verworfen, optional Server-seitige Token-Blacklist in v2)
+- **FR-1.4** Passwort-Reset (token-basiert, per Email, Token 1h gültig, v1: Token-Endpoint-Output für Tests, SMTP-Integration out-of-scope)
+- **FR-1.5** User-CRUD (nur Admin): Anlegen, Bearbeiten, Soft-Delete, Rolle zuweisen (Admin / Sales-Manager / Sales-Rep)
+- **FR-1.6** `/api/users/me` Endpunkt für aktuellen User (für Auth-Validierung & UI-Profil)
+
+**Akzeptanzkriterien (testbar):**
+- [ ] POST /api/auth/register mit gültigem Payload (email, password ≥ 8 Zeichen, name) → 201 + User-Objekt + JWT
+- [ ] POST /api/auth/register mit existierender Email → 409 + generische Fehlermeldung
+- [ ] POST /api/auth/login mit korrekten Credentials → 200 + JWT + User-Objekt
+- [ ] POST /api/auth/login mit falschen Credentials → 401 + generische Fehlermeldung (kein Email-Leak)
+- [ ] GET /api/users/me mit gültigem JWT → 200 + User-Daten (ohne password_hash)
+- [ ] GET /api/users/me ohne JWT → 401
+- [ ] GET /api/users/me mit expired JWT → 401 + Hinweis "token_expired"
+- [ ] DB-User wird in `users` Tabelle angelegt mit gehashtem `password_hash` (bcrypt oder argon2)
+- [ ] Zweiter POST /api/auth/register nach erfolgreichem ersten → 403 (Bootstrap bereits erfolgt)
+
+### FR-2: Accounts (Firmen/Kunden)
+- **FR-2.1** Account anlegen (Pflicht: name; Optional: website, address (street/city/zip/country), industry, size [1-10/11-50/51-200/201-1000/1000+], owner_id default = current_user)
+- **FR-2.2** Account anzeigen, bearbeiten (PATCH), soft-löschen (DELETE → `deleted_at` timestamp)
+- **FR-2.3** Account-Liste mit Paginierung (page, page_size ≤ 100), Volltext-Suche (name), Filter (industry, size, owner_id)
+- **FR-2.4** Account-Detail-Page mit allen zugehörigen Contacts, Deals, Activities, Notes (via Eager-Loading)
+- **FR-2.5** Ownership-Transfer (PATCH owner_id, mit Audit-Logging in v2)
+
+**Akzeptanzkriterien:**
+- [ ] POST /api/accounts mit gültigem Payload → 201 + Account-Objekt
+- [ ] POST /api/accounts mit fehlendem Pflichtfeld `name` → 422 (Pydantic validation error)
+- [ ] GET /api/accounts?page=1&page_size=20 → 200 + Paginierte Liste (items, total, page, page_size)
+- [ ] GET /api/accounts?industry=SaaS&size=51-200 → 200 + gefilterte Liste
+- [ ] GET /api/accounts/{id} → 200 + Account-Details mit relationen (contacts[], deals[], activities[])
+- [ ] PATCH /api/accounts/{id} mit Teil-Update → 200 + aktualisiertes Objekt
+- [ ] DELETE /api/accounts/{id} → 204 (soft-delete: `deleted_at` gesetzt, Datensatz bleibt in DB)
+- [ ] DB-Account in `accounts` Tabelle angelegt, FK zu `users` (owner_id) ON DELETE RESTRICT
+
+### FR-3: Contacts (Personen)
+- **FR-3.1** Contact anlegen (Pflicht: first_name, last_name; Optional: email, phone, title, account_id)
+- **FR-3.2** Contact bearbeiten (PATCH), soft-löschen, duplizieren (POST /api/contacts/{id}/duplicate)
+- **FR-3.3** Contact-Liste mit Suche (first_name, last_name, email – ILIKE), Filter (account_id, owner_id)
+- **FR-3.4** Email-Uniqueness nur innerhalb einer Org (nicht global), damit mehrere Reps denselben Contact anlegen können
+
+**Akzeptanzkriterien:**
+- [ ] POST /api/contacts mit gültiger account_id → 201, FK-Constraint geprüft (Account existiert)
+- [ ] POST /api/contacts mit ungültiger account_id → 404 (Account not found)
+- [ ] GET /api/contacts?q=muster&account_id=5 → 200 + gefilterte Liste
+- [ ] POST /api/contacts/{id}/duplicate → 201 + neuer Contact (Suffix "(Kopie)" im first_name, ohne Notes/Activities)
+
+### FR-4: Deals (Verkaufschancen/Pipeline)
+- **FR-4.1** Deal anlegen (Pflicht: title, account_id; Optional: value, currency [default EUR], stage [default "Lead"], close_date, owner_id)
+- **FR-4.2** Pipeline-View (Kanban-Endpoint: GET /api/deals/pipeline → Deals gruppiert nach stage, sortiert nach close_date ASC)
+- **FR-4.3** Stage-Transition (PATCH /api/deals/{id}/stage) mit History-Tracking in `deal_stage_history`
+- **FR-4.4** Won/Lost-Tracking: Stage "Won" oder "Lost" erfordert `won_reason` bzw. `lost_reason` (text, pflicht im Request-Body)
+- **FR-4.5** Drag-and-Drop im Frontend: Optimistic Update + PATCH, bei Fehler Rollback + Toast
+
+**Akzeptanzkriterien:**
+- [ ] POST /api/deals mit gültigem Payload → 201
+- [ ] PATCH /api/deals/{id}/stage mit neuer stage → 200, History-Eintrag in `deal_stage_history` (from_stage, to_stage, changed_by, changed_at)
+- [ ] PATCH /api/deals/{id}/stage mit stage="Won" ohne `won_reason` → 422
+- [ ] GET /api/deals/pipeline → 200 + JSON mit Stages als Keys, Deal-Listen als Values
+- [ ] DELETE /api/deals/{id} → 204 (soft-delete, keine Cascade-Löschung der History)
+
+### FR-5: Activities (Calls, Meetings, Emails, Notes-Lite)
+- **FR-5.1** Activity anlegen (Pflicht: type [call/meeting/email/task], subject; Optional: body, due_date, account_id?, contact_id?, deal_id?)
+- **FR-5.2** Activity-Liste mit Filter (type, status [open/completed/overdue], owner_id, due_date_from/to)
+- **FR-5.3** Activity-Complete (PATCH /api/activities/{id}/complete) mit Outcome-Text und `completed_at = now()`
+- **FR-5.4** Overdue-View: GET /api/activities?overdue=true → nur Activities mit `due_date < now AND completed_at IS NULL`
+
+**Akzeptanzkriterien:**
+- [ ] POST /api/activities mit Polymorphic-FK (z.B. nur account_id) → 201
+- [ ] POST /api/activities mit unbekanntem type → 422
+- [ ] GET /api/activities?overdue=true → 200 + nur überfällige Activities
+- [ ] PATCH /api/activities/{id}/complete mit outcome → 200 + completed_at gesetzt
+
+### FR-6: Tags & Notes
+- **FR-6.1** Tag-System (color [hex], name) auf Accounts/Contacts/Deals verknüpfbar
+- **FR-6.2** Notes (Polymorphic, freier Text + author_id + created_at, parent_type ∈ {account, contact, deal})
+- **FR-6.3** Tag-CRUD (POST /api/tags, GET /api/tags, DELETE /api/tags/{id}) und Tag-Linking (POST /api/tags/link)
+
+**Akzeptanzkriterien:**
+- [ ] POST /api/tags mit gültigem Payload → 201
+- [ ] POST /api/tags/link mit (tag_id, parent_type, parent_id) → 201, Link in `tag_links`
+- [ ] GET /api/accounts/{id} liefert Tags inklusive der via `tag_links` verknüpften
+- [ ] POST /api/notes mit parent_type="deal" und parent_id=42 → 201, Note polymorph verknüpft
+
+### FR-7: Dashboard
+- **FR-7.1** KPIs (GET /api/dashboard/kpis):
+  - `open_deals_count` (Deals nicht in Won/Lost)
+  - `open_deals_value` (Summe value aller offenen Deals)
+  - `won_this_month_count` (Deals mit stage=Won und close_date im aktuellen Monat)
+  - `won_this_month_value` (Summe value dieser Deals)
+  - `conversion_rate` (Won / (Won + Lost) in den letzten 90 Tagen, 0–1)
+- **FR-7.2** Activity-Feed (GET /api/dashboard/feed?limit=20): Letzte 20 Activities gruppiert nach `date(created_at) = today` und `older`
+
+**Akzeptanzkriterien:**
+- [ ] GET /api/dashboard/kpis → 200 + JSON mit allen 5 KPIs, korrekt berechnet
+- [ ] GET /api/dashboard/feed?limit=20 → 200 + max 20 Activities, neueste zuerst
+- [ ] KPIs sind org-isoliert (kein Cross-Tenant-Leak)
+
+### FR-8: Settings (User-Profile, Org-Info)
+- **FR-8.1** User-Profile bearbeiten (PATCH /api/users/me): name, avatar_url, email_notification_prefs (JSON: {deal_won, activity_due})
+- **FR-8.2** Org-Info bearbeiten (PATCH /api/org) – nur Admin: name, logo_url, default_currency, timezone
+- **FR-8.3** Email-Change erfordert Re-Authentifizierung (Password-Bestätigung) in v1.1; v1 erlaubt direkten PATCH
+
+**Akzeptanzkriterien:**
+- [ ] PATCH /api/users/me mit gültigem Payload → 200 + aktualisierter User
+- [ ] PATCH /api/org als Non-Admin → 403
+- [ ] PATCH /api/org als Admin mit gültigem Payload → 200 + aktualisierte Org
+
+## 4. Nicht-funktionale Anforderungen (NFR)
+
+- **NFR-1 Performance**: p95 Response-Time < 300 ms für Standard-CRUD-Endpoints (unter Last 50 concurrent Users, SQLite/PostgreSQL lokal); Pipeline-Endpoint < 500 ms p95
+- **NFR-2 Security**:
+  - Passwort-Hashing: argon2id (Primary) oder bcrypt (Fallback), kein MD5/SHA1
+  - JWT: HS256 mit `AUTH_SECRET` ≥ 32 Zeichen aus Coolify Env-Vars
+  - Input-Validation: Pydantic v2 für alle Request-Bodies und Query-Params
+  - CORS-Whitelist: explizite Origins, kein `*`
+  - Rate-Limiting: 60 req/min/IP für Auth-Endpoints (SlowAPI oder ähnliches)
+  - SQL-Injection-Schutz: ausschließlich SQLAlchemy ORM/parameterisierte Queries
+- **NFR-3 Skalierbarkeit**: Horizontale Skalierung über mehrere FastAPI-Container via Coolify (stateless App), PostgreSQL als shared DB; SQLite-Limit (single-writer) in Dev-Setup dokumentiert
+- **NFR-4 Maintainability**:
+  - Type-Hints überall (mypy strict)
+  - Ruff/Black-Formatierung, pre-commit-Hook
+  - pytest-Coverage ≥ 70 % (Lines + Branches)
+  - OpenAPI-Spec wird automatisch generiert unter `/docs` und `/redoc`
+- **NFR-5 Observability**:
+  - Strukturiertes Logging: JSON (python-json-logger), Felder `timestamp`, `level`, `request_id`, `user_id`, `path`, `method`, `status`, `latency_ms`
+  - `/health` Endpoint: 200 wenn DB-Connection OK, sonst 503
+  - `/metrics` Prometheus-compatible (optional v1.1, vorbereitet via `prometheus-fastapi-instrumentator`)
+  - Request-ID-Middleware für Tracing
+- **NFR-6 Backup & Recovery**:
+  - Tägliches DB-Backup via Coolify-Side (PostgreSQL-Dump, 7 Tage Retention)
+  - Restore-Runbook in `docs/runbook-backup-restore.md`
+  - Recovery-Time-Objective (RTO) ≤ 4h, Recovery-Point-Objective (RPO) ≤ 24h
+- **NFR-7 Internationalization (i18n)**:
+  - v1: Deutsch + Englisch, Strings in separater `locales/` JSON-Datei
+  - Frontend: einfaches i18n-Objekt, Sprache umschaltbar via LocalStorage
+  - vorbereitet für v2 (3+ Sprachen, Crowdin-Integration)
+- **NFR-8 Accessibility (a11y)**:
+  - WCAG 2.1 AA: Kontraste, Keyboard-Navigation, ARIA-Labels
+  - Alpine.js + Tailwind ermöglichen semantisches HTML
+
+## 5. Datenmodell-Skizze
+
+```
+users (1) ──< (N) accounts (1) ──< (N) contacts
+                                     │
+                                     └──< (N) deals ──< (N) activities
+                                                  │           │
+                                                  │           └──< (N) notes (polymorphic)
+                                                  │
+                                                  └──< (N) deal_stage_history
+accounts, contacts, deals ──< (N) tags (polymorphic via tag_links)
+```
+
+**Wichtige Entities** (Felder-Übersicht, vollständige DDL in Phase 2):
+
+| Entity | Schlüsselfelder | Indizes |
+|---|---|---|
+| `users` | id (UUID), email (unique, citext), password_hash, name, role (enum), org_id, created_at, deleted_at | UNIQUE (org_id, email) WHERE deleted_at IS NULL |
+| `orgs` | id (UUID), name, logo_url, default_currency, timezone, created_at | – |
+| `accounts` | id (UUID), name, website, industry, size (enum), street, city, zip, country, owner_id, org_id, created_at, deleted_at | INDEX (org_id, deleted_at), INDEX (owner_id) |
+| `contacts` | id (UUID), first_name, last_name, email, phone, title, account_id, owner_id, org_id, created_at, deleted_at | INDEX (account_id), INDEX (org_id, last_name) |
+| `deals` | id (UUID), title, value (Decimal), currency, stage (enum), close_date, won_reason, lost_reason, account_id, owner_id, org_id, created_at, deleted_at | INDEX (org_id, stage), INDEX (owner_id, close_date) |
+| `activities` | id (UUID), type (enum), subject, body, due_date, completed_at, outcome, account_id?, contact_id?, deal_id?, owner_id, org_id, created_at | INDEX (owner_id, completed_at), INDEX (due_date) WHERE completed_at IS NULL |
+| `notes` | id (UUID), body (text), author_id, parent_type, parent_id, org_id, created_at | INDEX (parent_type, parent_id) |
+| `tags` | id (UUID), name, color, org_id, created_at | UNIQUE (org_id, name) |
+| `tag_links` | tag_id, parent_type, parent_id, org_id, created_at | UNIQUE (tag_id, parent_type, parent_id), INDEX (parent_type, parent_id) |
+| `deal_stage_history` | id, deal_id, from_stage, to_stage, changed_by, changed_at | INDEX (deal_id, changed_at DESC) |
+
+**Multi-Tenancy-Hinweis**: Single-Tenant v1, aber `org_id` Spalte ist in **allen** Tabellen mit dabei und alle Queries filtern automatisch nach `org_id = current_user.org_id`. Dies ermöglicht eine saubere Migration zu Multi-Tenant in v2 ohne Schema-Bruch (nur Middleware-Erweiterung).
+
+## 6. API-Surface-Skizze (OpenAPI-Lite)
+
+| Method | Path | Auth | Beschreibung |
+|---|---|---|---|
+| POST | /api/auth/register | – | Erster Admin registrieren (Bootstrap) |
+| POST | /api/auth/login | – | Login → JWT |
+| POST | /api/auth/refresh | JWT | JWT refreshen |
+| POST | /api/auth/logout | JWT | Logout (clientseitig) |
+| POST | /api/auth/password-reset/request | – | Reset-Token anfordern |
+| POST | /api/auth/password-reset/confirm | – | Reset-Token + neues Passwort |
+| GET | /api/users/me | JWT | Aktueller User |
+| PATCH | /api/users/me | JWT | Eigene Profil-Daten bearbeiten |
+| GET | /api/users | JWT+Admin | Alle User (paginiert) |
+| POST | /api/users | JWT+Admin | User anlegen |
+| PATCH | /api/users/{id} | JWT+Admin | User bearbeiten |
+| DELETE | /api/users/{id} | JWT+Admin | User löschen (soft) |
+| GET | /api/accounts | JWT | Accounts-Liste (paginiert, suchbar) |
+| POST | /api/accounts | JWT | Account anlegen |
+| GET | /api/accounts/{id} | JWT | Account-Detail inkl. Relationen |
+| PATCH | /api/accounts/{id} | JWT | Account bearbeiten |
+| DELETE | /api/accounts/{id} | JWT | Account löschen (soft) |
+| GET | /api/contacts | JWT | Contacts-Liste |
+| POST | /api/contacts | JWT | Contact anlegen |
+| GET | /api/contacts/{id} | JWT | Contact-Detail |
+| PATCH | /api/contacts/{id} | JWT | Contact bearbeiten |
+| DELETE | /api/contacts/{id} | JWT | Contact löschen (soft) |
+| POST | /api/contacts/{id}/duplicate | JWT | Contact duplizieren |
+| GET | /api/deals | JWT | Deals-Liste (filterbar) |
+| POST | /api/deals | JWT | Deal anlegen |
+| GET | /api/deals/pipeline | JWT | Kanban-View (gruppiert) |
+| GET | /api/deals/{id} | JWT | Deal-Detail |
+| PATCH | /api/deals/{id} | JWT | Deal bearbeiten |
+| PATCH | /api/deals/{id}/stage | JWT | Stage-Transition + History |
+| DELETE | /api/deals/{id} | JWT | Deal löschen (soft) |
+| GET | /api/activities | JWT | Activities-Liste (filterbar) |
+| POST | /api/activities | JWT | Activity anlegen |
+| GET | /api/activities/{id} | JWT | Activity-Detail |
+| PATCH | /api/activities/{id} | JWT | Activity bearbeiten |
+| PATCH | /api/activities/{id}/complete | JWT | Activity abschließen |
+| DELETE | /api/activities/{id} | JWT | Activity löschen (soft) |
+| GET | /api/notes | JWT | Notes (parent_type+parent_id) |
+| POST | /api/notes | JWT | Note anlegen (polymorph) |
+| DELETE | /api/notes/{id} | JWT | Note löschen |
+| GET | /api/tags | JWT | Tags-Liste |
+| POST | /api/tags | JWT | Tag anlegen |
+| PATCH | /api/tags/{id} | JWT | Tag bearbeiten (name/color) |
+| DELETE | /api/tags/{id} | JWT | Tag löschen (cascade zu tag_links) |
+| POST | /api/tags/link | JWT | Tag mit Entity verknüpfen |
+| DELETE | /api/tags/link | JWT | Tag-Verknüpfung löschen |
+| GET | /api/dashboard/kpis | JWT | KPIs (5 Werte) |
+| GET | /api/dashboard/feed | JWT | Activity-Feed (latest 20) |
+| GET | /api/org | JWT | Org-Info lesen |
+| PATCH | /api/org | JWT+Admin | Org-Info bearbeiten |
+| GET | /health | – | Healthcheck (200/503) |
+| GET | /docs | – | Swagger-UI |
+| GET | /redoc | – | ReDoc-UI |
+| GET | /openapi.json | – | OpenAPI-Spec (JSON) |
+
+## 7. UI-Skizze (Pages)
+
+- **/login** – Login-Form (Email + Passwort), Redirect auf /
+- **/register** – Erster-Admin-Registrierung (Bootstrap), nur erreichbar solange `users`-Tabelle leer
+- **/** – Dashboard (KPI-Karten oben: Open Deals, Pipeline Value, Won This Month, Conversion Rate; Activity-Feed unten)
+- **/accounts** – Account-Liste (Tabelle mit Suche, Filter-Sidebar für Industry/Size, Pagination)
+- **/accounts/{id}** – Account-Detail (Tabs: Info | Contacts | Deals | Activities | Notes)
+- **/contacts** – Contact-Liste (Tabelle mit Suche nach Name/Email, Filter nach Account)
+- **/contacts/{id}** – Contact-Detail (Tabs: Info | Activities | Notes)
+- **/pipeline** – Kanban-Board (Deals gruppiert nach Stage als Spalten, Drag-and-Drop)
+- **/activities** – Activity-Liste (Tabelle mit Overdue-Highlight, Filter nach Type/Status)
+- **/settings/profile** – User-Profile (Name, Avatar-URL, Notification-Prefs)
+- **/settings/users** – User-Verwaltung (nur Admin, Tabelle + Invite-Form)
+- **/settings/org** – Org-Info (nur Admin, Name, Logo-URL, Default-Currency, Timezone)
+- **/404** – Not-Found-Page
+- **/403** – Forbidden-Page (z.B. Non-Admin auf /settings/users)
+
+## 8. Test-Strategie (Kurzfassung, Details in Phase 5)
+
+- **Unit-Tests**: pytest, isolierte Tests für `models/`, `schemas/`, `services/`
+- **Integration-Tests**: pytest + `httpx.AsyncClient` gegen eine live FastAPI-Test-Instance mit **echter SQLite-DB in tmp-Dir + Alembic `upgrade head`** pro Test-Session
+- **DB-Write-Tests**: jedes SQLAlchemy-Model bekommt einen CRUD-Test gegen die echte Test-DB
+- **Auth-Tests**: positiver Login, negativer Login, expired JWT, fehlender JWT, fehlende Rollen (403)
+- **API-Contract-Tests**: Smoke-Tests für alle 51 Endpoints (200/201/204/400/401/403/404/422)
+- **E2E-Tests (optional v1)**: Playwright gegen den Docker-Stack (login → account anlegen → deal erstellen → pipeline-view → drag-and-drop)
+- **Smoke-Tests (Runtime)**: nach Docker-up werden via `curl` getestet: `/health`, Auth-Flow, 3+ zufällige Endpoints
+- **Coverage-Target**: ≥ 70 % Lines + Branches, gemessen mit `pytest-cov`, Threshold enforced in CI
+- **Test-DB-Isolation**: jede Test-Function bekommt eigene Transaktion (rollback nach Test), parallele Test-Runs via `pytest-xdist`
+
+## 9. Deployment-Plan (Kurzfassung, Details in Phase 5)
+
+- **Dev** (lokal):
+  - SQLite, `uvicorn main:app --reload --port 8000`
+  - `alembic upgrade head` vor Start
+  - `.env`-Datei mit Dev-Secrets (nicht in Git)
+  - Frontend: `python -m http.server 8080` (statische Files) oder direkt in FastAPI als StaticFiles gemounted
+
+- **Prod** (Coolify):
+  - PostgreSQL via Coolify DB-Service (Image: `postgres:16-alpine`)
+  - FastAPI-Container (Image: `python:3.12-slim`, Build via Dockerfile mit multi-stage)
+  - Caddy/Nginx-Proxy in Coolify für TLS + Domain-Routing
+  - Frontend: gleicher Container, statische Files via FastAPI StaticFiles
+
+- **Coolify-Server**:
+  - Server: `localhost` (uuid `lw80w8scs4044gwcw084s00s4`)
+  - Limits: 2 concurrent_builds, 25 queue_limit, 3600s build_timeout
+  - Coolify-Build-Command: `docker build -t crm-backend .`
+  - Coolify-Start-Command: `alembic upgrade head && uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2`
+
+- **Healthcheck**: `/health` Endpoint, Coolify-side `curl -f http://localhost:8000/health || exit 1`
+
+- **Secrets** (über Coolify Env-Vars, nie im Repo):
+  - `AUTH_SECRET` (≥ 32 Zeichen, JWT-Signing-Key)
+  - `DATABASE_URL` (PostgreSQL-Connection-String, von Coolify automatisch injected)
+  - `CORS_ORIGINS` (komma-separierte Liste erlaubter Origins)
+  - `LOG_LEVEL` (default INFO, in Prod WARNING)
+
+- **Migration-Run**: `alembic upgrade head` als Pre-Start-Schritt in Coolify (idempotent)
+
+- **Rollback-Strategie**: Coolify-Deployment-History, manuelle Rollback via Coolify-UI auf vorherigen Container-Tag
+
+## 10. Risiken & offene Punkte
+
+**Risiken:**
+- **R-1: Single-Tenant jetzt, aber Migrations-Pfad zu Multi-Tenant**: Trotz `org_id`-Spalte in allen Tabellen muss die Middleware/Query-Logik strikt nach `org_id` filtern. Risiko: ein vergessenes `.where(org_id=...)` in einem Query leakt Daten. Mitigation: zentraler `OrgScopedQuery`-Helper, der in allen Repositories genutzt wird.
+- **R-2: Polymorphic-FKs (Notes, Tags) komplexer als relational-FKs**: Kein DB-Constraint, der sicherstellt, dass `parent_id` in der richtigen Tabelle existiert. Risiko: orphaned Notes/Tags. Mitigation: Validierung in Service-Layer + Cleanup-Job in Phase 5.
+- **R-3: Coolify `localhost` = lokaler Container**: Coolify läuft auf `localhost`, der CRM-Container ist nur intern erreichbar. Eine echte Public-Domain mit TLS ist für v1.1 geplant. Risiko: Dev-Stack ≠ Prod-Stack. Mitigation: Docker-Compose-File, das identisch lokal wie in Coolify läuft.
+- **R-4: Single-Writer SQLite in Dev-Parallelbetrieb**: Wenn mehrere Developer/Tests parallel laufen, blockt SQLite. Mitigation: Tests nutzen separate in-memory-SQLites pro Worker; Prod-Plan ist explizit PostgreSQL.
+- **R-5: JWT im localStorage = XSS-Risiko**: Wenn ein Angreifer XSS schafft, kann er das JWT stehlen. Mitigation: strikte CSP-Header, kein `innerHTML` mit User-Input, Alpine.js mit `x-text` statt `x-html` als Default.
+
+**Offene Punkte (Entscheidungen ausstehend):**
+- **OP-1: Avatar-Upload ja/nein?** Empfehlung: **Nein in v1**, nur `avatar_url` (User gibt externe URL an). Begründung: File-Upload-Endpoint + Storage-Lösung (S3-kompatibel oder Coolify-Volume) wäre eigener Scope.
+- **OP-2: Email-Integration (SMTP) ja/nein?** Empfehlung: **Nein in v1**. Begründung: SMTP-Provider-Konfiguration, Email-Templates, Bounce-Handling, SPF/DKIM-Setup = signifikante Komplexität. Passwort-Reset-Token werden in v1 als Response-Output zurückgegeben (für Tests/Dev), SMTP-Integration in v1.1.
+- **OP-3: Audit-Log ja/nein?** Empfehlung: **Minimal in v1** (`deal_stage_history` deckt das Wichtigste ab), **vollständig in v2** (alle PATCH/DELETE-Aktionen mit Before/After-Snapshot). Begründung: Volles Audit-Log braucht Trigger oder Middleware, die Performance kostet.
+- **OP-4: i18n: Deutsch + Englisch oder nur Deutsch v1?** Empfehlung: **Beide** (Aufwand gering bei JSON-Locale-File, großer UX-Wert).
+- **OP-5: Soft-Delete vs. Hard-Delete für DSGVO „Recht auf Vergessenwerden"?** Empfehlung: **Soft-Delete** + Admin-Tool für Hard-Delete in v1.1. Begründung: Audit-Trail bleibt erhalten, Revoke möglich.
+
+## 11. User-Story-Mapping (Traceability)
+
+| # | Story | FR-Refs | API-Endpoint | UI-Page |
+|---|---|---|---|---|
+| 1 | Als Sales-Rep logge ich mich ein | FR-1.2 | POST /api/auth/login | /login |
+| 2 | Als Sales-Rep sehe ich beim ersten Besuch die Registrierung | FR-1.1 | POST /api/auth/register | /register |
+| 3 | Als Sales-Rep lege ich einen neuen Account an | FR-2.1 | POST /api/accounts | /accounts (Modal) |
+| 4 | Als Sales-Rep durchsuche Accounts nach Branche | FR-2.3 | GET /api/accounts?industry=... | /accounts |
+| 5 | Als Sales-Rep öffne einen Account und sehe alle Contacts | FR-2.4 | GET /api/accounts/{id} | /accounts/{id} (Tab Contacts) |
+| 6 | Als Sales-Rep füge ich einen Contact zu einem Account hinzu | FR-3.1 | POST /api/contacts | /accounts/{id} (Modal) |
+| 7 | Als Sales-Rep lege ich einen Deal auf einem Account an | FR-4.1 | POST /api/deals | /accounts/{id} (Modal) |
+| 8 | Als Sales-Rep öffne die Pipeline und sehe alle meine Deals als Kanban | FR-4.2 | GET /api/deals/pipeline | /pipeline |
+| 9 | Als Sales-Rep ziehe einen Deal per Drag-and-Drop in die nächste Stage | FR-4.3, FR-4.5 | PATCH /api/deals/{id}/stage | /pipeline (Kanban) |
+| 10 | Als Sales-Rep schließe einen Deal als Won ab mit Grund | FR-4.4 | PATCH /api/deals/{id}/stage | /pipeline / /deals/{id} (Modal) |
+| 11 | Als Sales-Rep plane eine Follow-up-Aktivität | FR-5.1 | POST /api/activities | /accounts/{id} / /contacts/{id} (Modal) |
+| 12 | Als Sales-Rep sehe ich alle meine überfälligen Aktivitäten | FR-5.4 | GET /api/activities?overdue=true | /activities |
+| 13 | Als Sales-Rep schließe eine Aktivität mit Outcome ab | FR-5.3 | PATCH /api/activities/{id}/complete | /activities (Row) |
+| 14 | Als Sales-Rep füge einem Account einen Tag hinzu | FR-6.1, FR-6.3 | POST /api/tags/link | /accounts/{id} (Tag-Picker) |
+| 15 | Als Sales-Rep füge eine Note zu einem Deal hinzu | FR-6.2 | POST /api/notes | /deals (Tab Notes) |
+| 16 | Als Sales-Rep öffne das Dashboard und sehe meine KPIs | FR-7.1 | GET /api/dashboard/kpis | / |
+| 17 | Als Sales-Rep sehe im Dashboard den Activity-Feed | FR-7.2 | GET /api/dashboard/feed | / |
+| 18 | Als Sales-Rep bearbeite mein Profil (Avatar, Notification-Prefs) | FR-8.1 | PATCH /api/users/me | /settings/profile |
+| 19 | Als Sales-Manager lege einen neuen Sales-Rep an | FR-1.5 | POST /api/users | /settings/users |
+| 20 | Als Sales-Manager sehe alle Deals meines Teams in der Pipeline | FR-4.2 | GET /api/deals/pipeline?owner_id=... | /pipeline (Filter) |
+| 21 | Als Admin bearbeite Org-Info (Name, Logo, Default-Currency) | FR-8.2 | PATCH /api/org | /settings/org |
+| 22 | Als User fordere ich einen Passwort-Reset an | FR-1.4 | POST /api/auth/password-reset/request | /login ("Passwort vergessen") |
+| 23 | Als User setze ich mein Passwort mit Token zurück | FR-1.4 | POST /api/auth/password-reset/confirm | /reset-password?token=... |
+| 24 | Als User logge mich aus | FR-1.3 | POST /api/auth/logout | (Header-Logout-Button) |
+
+---
+
+**Phase-Status**: REQUIREMENTS — Draft for User Approval
+
+**Nächste Phase nach User-Approval:** solution_architect → `02-architecture.md` + `03-task-graph.json`