crm-system/docs/01-requirements.md

# 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`