6.9 KiB
6.9 KiB
module, title, phase, status, last_updated, session_source, related_lps, spec_style
| module | title | phase | status | last_updated | session_source | related_lps | spec_style | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 7 | Angebot + Signatur | 1 | detail-spec-draft | 2026-05-08 | brainstorming-session-2026-05-07-2206.md |
|
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_idprovider_connection_id,provider_document_idtitle,descriptionsource_pdf_file_id(M23)status(draft | sent | viewed | signed | declined | expired | revoked)sent_at,signed_at,expires_atsigned_pdf_file_idarchived_at
DealSignatureSigner
id,document_id,position(Sequential-Reihenfolge)signer_email,signer_name,signer_rolelinked_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_attriggered_by(user | provider_webhook | system_timeout)metadata
SignatureWebhookEvent
id,provider_connection_id,received_at,event_typepayload,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_idsendDocument(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:
- PDF-Upload — User wählt PDF aus Files oder lädt neu hoch (M23)
- Signers konfigurieren:
- Mind. 1 Signer (Kunde) erforderlich
- Optional weitere (Zeuge, Vertriebsleiter)
- Pro Signer: Name (vorausgefüllt aus Contact), Email, Rolle
- Sequenz: sequential oder parallel
- Provider auswählen (Default =
is_default=true) - Optional: Field-Placement (P1: in PandaDoc/DocuSign-UI; P2: Inline in HiveGrid)
- Send — Document an Provider gepusht, Email an Signers
- 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.signeddocument.declineddocument.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.signedfü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)