Reorganize repo structure and standards references
This commit is contained in:
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)
|
||||
Reference in new issue
Block a user