Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M07-angebot-signatur.md
T

6.9 KiB
Raw Blame History

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
LP-7
LP-9
LP-10
LP-11
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)