--- module: 7 title: Angebot + Signatur phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-7, LP-9, LP-10, LP-11] spec_style: requirements-pur --- # Modul 7 — Angebot + Signatur > **Detail-Spec gemäß LP-9.** Phase 1 nur Integration mit PandaDoc/DocuSign — keine eigene eIDAS-Engine. Acceptance-Signatur läuft separat über M4/M5. ## Themenblöcke ``` A. Datenmodell B. Provider-Integration (PandaDoc, DocuSign) C. PDF-Upload und Send-Flow D. Status-Tracking (Webhook-basiert) E. Multi-Signer-Workflow F. Verweis auf Acceptance-Signatur (M4/M5) G. Integration mit anderen Modulen H. Permissions I. Phase 2 (Versionierung, eigene eIDAS-Engine) ``` --- ## Block A — Datenmodell ``` SignatureProviderConnection — pro Tenant pro Provider (über M33a) DealSignatureDocument — ein Dokument im Signatur-Prozess DealSignatureSigner — pro Document mehrere Signers DealSignatureStatusTransition — Status-Historie (Audit) SignatureWebhookEvent — Inbound-Webhook-Log ``` ### SignatureProviderConnection - `id`, `tenant_id`, `data_connection_id` (M33a) - `provider` (`pandadoc | docusign`) - `is_default` ### DealSignatureDocument - `id`, `tenant_id`, `deal_id` - `provider_connection_id`, `provider_document_id` - `title`, `description` - `source_pdf_file_id` (M23) - `status` (`draft | sent | viewed | signed | declined | expired | revoked`) - `sent_at`, `signed_at`, `expires_at` - `signed_pdf_file_id` - `archived_at` ### DealSignatureSigner - `id`, `document_id`, `position` (Sequential-Reihenfolge) - `signer_email`, `signer_name`, `signer_role` - `linked_contact_id` (M1) - `status` (`pending | viewed | signed | declined`) - `signed_at`, `ip_at_signing`, `user_agent_at_signing` ### DealSignatureStatusTransition - `id`, `document_id`, `from_status`, `to_status`, `transitioned_at` - `triggered_by` (`user | provider_webhook | system_timeout`) - `metadata` ### SignatureWebhookEvent - `id`, `provider_connection_id`, `received_at`, `event_type` - `payload`, `signature_validation_status`, `processed_at` --- ## Block B — Provider-Integration ### PandaDoc - OAuth2-Connect über M33a - Webhook: `/api/v1/webhooks/pandadoc/{tenant_id}/{connection_id}` - Capabilities: PDF-Upload, Field-Placement (P1 manuell in PandaDoc-UI), Multi-Signer, Reminder-Emails ### DocuSign - OAuth2-Connect (analog) - Webhook: `/api/v1/webhooks/docusign/{tenant_id}/{connection_id}` - Capabilities: analog ### Adapter-Pattern (M33a) Beide implementieren `SignatureProvider`-Interface: - `createDocument(pdf, signers)` → external_id - `sendDocument(external_id)` - `getDocumentStatus(external_id)` - `revokeDocument(external_id)` - `handleWebhook(payload)` --- ## Block C — PDF-Upload und Send-Flow ### Im Deal-Detail (`/{tenant}/deals/:id`) **Trigger:** *„Angebot zur Signatur senden"*-Funktion. **Workflow:** 1. **PDF-Upload** — User wählt PDF aus Files oder lädt neu hoch (M23) 2. **Signers konfigurieren:** - Mind. 1 Signer (Kunde) erforderlich - Optional weitere (Zeuge, Vertriebsleiter) - Pro Signer: Name (vorausgefüllt aus Contact), Email, Rolle - Sequenz: sequential oder parallel 3. **Provider auswählen** (Default = `is_default=true`) 4. **Optional: Field-Placement** (P1: in PandaDoc/DocuSign-UI; P2: Inline in HiveGrid) 5. **Send** — Document an Provider gepusht, Email an Signers 6. **Status `sent`** + Activity-Stream-Eintrag im Deal ### Klartext-Hinweise - PDF-Größe-Limit: *„Datei ist größer als 25 MB. Bitte komprimieren."* - Signer ohne Email: *„Signer ‚Max Mustermann' hat keine Email-Adresse. Bitte ergänzen."* - Provider-Down: *„Verbindung zu PandaDoc gerade nicht erreichbar. Versuche es in 5 Min erneut."* --- ## Block D — Status-Tracking ### Webhook-Verarbeitung Provider-Events: - `document.viewed` (Signer hat geöffnet) - `document.signed` - `document.declined` - `document.completed` (alle Signers fertig) - `document.expired` ### Status-Updates - HiveGrid verarbeitet Webhook → Update `DealSignatureDocument.status` + `DealSignatureSigner.status` - `DealSignatureStatusTransition`-Eintrag - Activity-Stream-Eintrag im Deal - Bei `completed`: signed PDF herunterladen, in M23 File-Storage speichern - Trigger-Event `signature.signed` für M17 ### Auto-Stage-Wechsel - `document.completed`: optional Auto-Stage-Wechsel zu Won-Stage (Tenant-konfigurierbar) - `document.declined`: Klartext-Notification + optional Auto-Stage-Wechsel zu Lost ### Detail-View im Deal **Zu zeigende Daten:** - Liste aller Documents pro Deal - Pro Document: Status, Signers mit Status, Sent-Datum, Signed-Datum - Original-PDF + Signed-PDF als Download **Operationen:** - Reminder an Signer schicken (über Provider) - Document widerrufen - Document neu senden (mit angepasstem PDF) - Manueller Status-Refresh --- ## Block E — Multi-Signer-Workflow - **Sequential:** Signer 1 unterschreibt, dann Signer 2, etc. - **Parallel:** alle gleichzeitig - Tenant-Admin-konfigurierbar pro Document - Status-Aggregat: `partially_signed` (P2) --- ## Block F — Verweis auf Acceptance-Signatur **Acceptance-Protokoll-Signatur (M4 + M5)** ist **separat**: - Touch-Signatur direkt im Form-Builder (M5 `signature`-Feldtyp) - IP + Timestamp automatisch - Rechtlich: einfache elektronische Signatur (für interne Abnahme ausreichend) - **Keine** eIDAS-konforme qualifizierte Signatur — Phase 2 --- ## Block G — Integration | Modul | Integration | |---|---| | **M3 Sales** | Document am Deal verknüpft; Auto-Stage-Wechsel bei Completed | | **M17 Automation** | Trigger `signature.sent/signed/declined/expired`; Action `signature.send` | | **M22 Notifications** | Push an Vertriebler bei Status-Änderungen | | **M23 Files** | Source-PDF + Signed-PDF | | **M33a Apps-Engine** | PandaDoc + DocuSign als Apps | --- ## Block H — Permissions | Permission | Erlaubt | |---|---| | `signature.read` | Documents sehen | | `signature.send` | Document zur Signatur senden | | `signature.revoke` | Document widerrufen | | `signature.admin` | Provider-Connection verwalten | ### Default-Rollen-Zuweisung | Rolle | Permission | |---|---| | GF | `signature.admin` | | Vertriebsleiter / Vertriebler | `signature.read` + `signature.send` + `signature.revoke` | | Andere | (keine — Documents nur im Deal-Kontext) | --- ## Block I — Phase 2 - Versionierung von Angeboten (V1, V2, V3) - Inline-Field-Placement in HiveGrid - eIDAS-konforme qualifizierte elektronische Signatur (D-Trust, Signaturit) - Bulk-Send --- ## Architektur-Vorschriften (Querschnitt) - **LP-7:** PandaDoc bleibt USP-Tool (keine eigene Engine) - **LP-11, AV #2:** Adapter-Pattern - **LP-10, AV #1:** Klartext-Diagnostik - **AV #6:** Audit-Trail über `DealSignatureStatusTransition` --- ## Detail-Spec-Status: DRAFT Modul 7 komplett spec'd. **Offene Detail-Punkte:** - Konkrete Webhook-Signature-Validation pro Provider - Field-Placement-UX (Phase 2) - eIDAS-Anforderungen klären (Phase 2)