239 lines
6.9 KiB
Markdown
239 lines
6.9 KiB
Markdown
---
|
||
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)
|