Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M07-angebot-signatur.md

239 lines
6.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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)