Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,238 @@
---
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)