# SFT Sign – Implementierungsdokumentation

Technische Referenz zum Portieren des **SFT Sign**-Moduls aus dem FTC-Projekt in ein anderes Symfony-Projekt.
FTC-Referenz unter /user/svenkrause/Web/ftc_io/ftc

---

## Verbindliche Konventionen (Ziel-App)

Diese Regeln gelten durchgängig – Abweichungen nur in Abschnitt [FTC-Referenz vs. Ziel-App](#ftc-referenz-vs-ziel-app).


| Thema | Ziel-App |
|-------|----------|
| **1. Unterzeichner** | Immer `User` (Ersteller), `sort_order = 0`, `is_self = true` |
| **2.+ Unterzeichner** | `User` **oder** `Contact` – mixed | Contact only if contact.contact_email has email or contact.contact_company_email has email |
| **Contact** | Kein App-Login → `access_token` (UUID v4) + `SignGuestController` + Public Route `/sign/{locale}/{token}` |
| **User (2.+)** | App-Login → `SignController`, **kein** `access_token` |
| **Frontend** | **Ein** Webpack-Entry: `sign` (`assets/sign.ts`) für alle Modi |
| **Nicht portieren** | `assets/sign_guest.ts`, Webpack-Entry `sign_guest`, `encore_entry_*('sign_guest')` |

---

## 1. Überblick

1. PDF hochladen und Signaturauftrag anlegen  
2. Unterzeichner festlegen (Signer 1 = User; weitere = User oder Contact)  
3. Felder (Unterschrift, Datum, Text) auf dem PDF platzieren  
4. Unterschrift: User in der App, Contact über Public Link  
5. Abschluss: Unterschriften ins PDF einbrennen + Signaturnachweis  

**Keine QES** – internes Workflow-Tool mit Audit-Trail.

---

## 2. Unterzeichner-Modell

| Position | Entity | App-Zugriff | Unterschrift |
|----------|--------|-------------|--------------|
| **1** | `User` (Ersteller) | ja | `SignController` |
| **2+** | `User` | ja | `SignController` |
| **2+** | `Contact` | nein | `SignGuestController` + Token-Link |

### Regeln

1. Beim Erstellen des Auftrags wird Signer 1 automatisch aus dem eingeloggten `User` angelegt.  
2. Weitere Signer wählt der Ersteller explizit als `User` oder `Contact`.  
3. Nur Contact-Signer erhalten `access_token` und Einladungs-E-Mail mit Public Link.  
4. User-Signer erhalten E-Mail/In-App-Link auf authentifizierte Routen unter `/app/{locale}/signatur/...`.

### `sign_signer` – Felder (Ziel-App)

| Feld | Signer 1 (User) | User 2+ | Contact |
|------|-----------------|---------|---------|
| `user_id` | Ersteller | User-FK | `NULL` |
| `contact_id` | `NULL` | `NULL` | Contact-FK |
| `is_self` | `true` | `false` | `false` |
| `sort_order` | `0` | ≥ `1` | ≥ `1` |
| `access_token` | `NULL` | `NULL` | UUID v4, unique |
| `auth_code` / `auth_code_expires_at` | — | — | nur bei OTP |
| `email`, Name | aus `User` | aus `User` | aus `Contact` |

**Invariante:** `(user_id IS NOT NULL) XOR (contact_id IS NOT NULL)` – bei Signer 1 zusätzlich `is_self = true`.

```
SignDocument
  └── SignSigner [0]  User (is_self)     → App
  └── SignSigner [1]  Contact + token    → /sign/{locale}/{token}
  └── SignSigner [2]  User                 → App
```

---

## 3. Architektur

```
┌─────────────────────────────────────────────────────────────────┐
│ SignController (auth)           SignGuestController (public)     │
│ /app/{locale}/signatur          /sign/{locale}/{access_token}  │
│ User-Signer (alle)              nur Contact-Signer               │
└────────────┬────────────────────────────┬───────────────────────┘
             └─────────────┬──────────────┘
                           ▼
                  SignService
                  (completeSigner, PDF-Stamp, Audit)
                           │
             Doctrine (User, Contact) · Mailer · Dateisystem
```

---

## 4. Abhängigkeiten

**Composer:** `setasign/fpdi` ^2.6, `tecnickcom/tcpdf` ^6.7  

**Frontend:** Webpack-Entry **`sign`** only, Bootstrap 5, PDF.js 3.11.174 (CDN), `assets/styles/sign.scss`  

**Symfony:** 6.4+, Doctrine, MySQL, Mailer, `%upload_directory%`, Übersetzungen `sign.*`  

**Entities:** `User` (`globalId`), `Contact` (extern, kein Login)

---

## 5. Datenmodell

Referenz: `sql/sign_schema.sql`, Migration `Version20260804000000.php` (+ `file_size` in `Version20260817100000.php`)

### `sign_document`

| Spalte | Bedeutung |
|--------|-----------|
| `global_id`, `public_id` | Mandant, Zertifikat-ID |
| `created_by_id` | Ersteller (`User`) |
| `title`, `message`, `email_subject` | Metadaten / Mail |
| `status` | `draft` → `waiting` / `action_required` → `completed` |
| `require_email_code` | OTP für Contact-Links |
| `sequential_signing` | Reihenfolge erzwingen |
| `expires_at`, `signed_filename`, `file_hash`, `file_size` | Lifecycle / Datei |

### `sign_field`

Typen: `signature`, `date`, `text`. Position in **Prozent** (0–100): `page`, `pos_x`, `pos_y`, `width`, `height`, `value`, `completed`.

### `sign_event`

Audit: `event_type`, `details`, `ip_address`, `created_at`.

---

## 6. SignService

| Methode | Wann |
|---------|------|
| `createFromUpload()` | PDF → Draft |
| `addSigner()` | Signer 1 auto-User; Contact → `access_token`; User → kein Token |
| `addField()` | Feld platzieren |
| `validateForSend()` | Vor Versand |
| `markSent()` | Status + `invited_at` |
| `completeSigner()` | User **und** Contact (gleiche Payload) |
| `issueAuthCode()` / `verifyAuthCode()` | Nur Contact |
| `isSignerTurn()` | Bei `sequential_signing` |
| `burnSignaturesIntoPdf()` / `ensureSignedPdf()` | Fertig-PDF |
| `buildCertificatePdf()` | Signaturnachweis |
| `log()` | Audit |

```php
// addSigner() – Kernlogik Ziel-App
if ($document->getSigners()->isEmpty()) {
    $signer->setUser($creator)->setIsSelf(true)->setSortOrder(0);
    return; // kein access_token
}
if ($contact !== null) {
    $signer->setContact($contact)->setAccessToken((string) Uuid::v4());
}
if ($user !== null) {
    $signer->setUser($user); // access_token bleibt null
}
```

---

## 7. Controller & Routen

### SignController (auth)

Prefix: `de` → `/app/{_locale}/signatur` · `en` → `/app/{_locale}/sign`

| Route | Zweck |
|-------|-------|
| `app_sign_index` | Liste |
| `app_sign_upload` | PDF-Upload |
| `app_sign_prepare` | Signer 1 auto; Signer 2+ wählen; Felder (AJAX) |
| `app_sign_review` | Metadaten + Versand |
| `app_sign_sent` | Bestätigung nach Versand |
| `app_sign_show` | Detail + **User-Unterschrift** |
| `app_sign_pdf`, `app_sign_download` | PDF |
| `app_sign_certificate`, `app_sign_certificate_pdf` | Nachweis |
| `app_sign_remind` | Erinnerung (**nur Contact**, Public Link) |
| `app_sign_delete` | Löschen |
| `app_sign_find_contacts` | Autocomplete **Contact** (User-Auswahl: eigene Route/UI) |

**Versand (`sendSignerInvites`):**

| Signer-Typ | Link | Route |
|------------|------|-------|
| Contact | Public | `app_sign_guest` + `access_token` |
| User | Auth | `app_sign_show` (oder dedizierte Sign-Route) |
| Signer 1 (self) | — | kein Mail; Status `action_required` |

### SignGuestController (public, nur Contact)

Prefix: `/sign/{_locale}/{token}` · Security: `{ path: ^/sign/, role: PUBLIC_ACCESS }`

| Route | Zweck |
|-------|-------|
| `app_sign_guest` | Einstieg |
| `app_sign_guest_auth` | OTP |
| `app_sign_guest_sign` | Unterschrift |
| `app_sign_guest_done` | Fertig |
| `app_sign_guest_pdf`, `app_sign_guest_download` | PDF |
| `app_sign_guest_certificate` (+ `_pdf`) | Nachweis |

**Pflicht-Check in `getSigner()`:** `contact_id IS NOT NULL` – sonst 404 oder Redirect zur App.

### Payload `completeSigner()`

```json
{
  "signatureData": "data:image/png;base64,...",
  "signatureType": "typed|draw",
  "fields": [{ "id": 1, "value": "..." }]
}
```

---

## 8. Frontend – ein Bundle `sign`

### Webpack

```javascript
.addEntry('sign', ['./assets/sign.ts'])
// Kein .addEntry('sign_guest', …)
```

### Modi in `assets/sign.ts`

Erkennung z. B. über Root-Element (`#signPrepare`, `#signGuestApp`) oder `data-sign-mode`:

| Modus | Template | Aufgabe |
|-------|----------|---------|
| `prepare` | `prepare.html.twig` | Upload, Signer, Feldplatzierung |
| `user-sign` | `show.html.twig` | User-Unterschrift in App |
| `contact-sign` | `guest_sign.html.twig` | Contact via Public Link |

Gemeinsame Module (empfohlen): PDF-Render, Feld-Overlay, Signatur-Modal → z. B. `assets/sign/pdf-viewer.ts`, `assets/sign/signature-modal.ts`.

### Templates – Asset-Einbindung

| Template | `encore_entry_script_tags` |
|----------|----------------------------|
| `index`, `prepare`, `review`, `show`, `sent`, `remind`, `certificate` | `'sign'` |
| `guest_sign`, `guest_auth`, `guest_done`, `guest_wait` | **`'sign'`** (in FTC fälschlich `'sign_guest'`) |

---

## 9. E-Mail

| Template | Empfänger |
|----------|-----------|
| `sign/email/invite.*` | Contact (Token-Link) · User (App-Link) |
| `sign/email/auth_code.*` | Contact (OTP) |
| `sign/email/completed.*` | Ersteller |

---

## 10. Konfiguration

```yaml
App\Service\SignService:
    arguments:
        $uploadDirectory: '%upload_directory%'
        $projectDir: '%kernel.project_dir%'

# security.yaml
access_control:
    - { path: ^/sign/, role: PUBLIC_ACCESS }
```

---

## 11. Workflow

```mermaid
sequenceDiagram
    participant U1 as User 1 Ersteller
    participant S as SignService
    participant C as Contact
    participant U2 as User 2
    participant M as Mailer

    U1->>S: upload, Signer 1 = self
    U1->>S: addSigner Contact, addSigner User
    U1->>S: fields, validate, markSent
    S->>M: Contact Public Link
    S->>M: User App-Link
    U1->>S: completeSigner App
    C->>S: token link, optional OTP, completeSigner
    U2->>S: completeSigner App
    S->>S: burnSignaturesIntoPdf
```

---

## 12. Portier-Checkliste

### Übernehmen (anpassen)

```
src/Entity/SignDocument.php
src/Entity/SignSigner.php      ← user_id FK ergänzen
src/Entity/SignField.php
src/Entity/SignEvent.php
src/Repository/Sign*.php       (4×)
src/Service/SignService.php    ← addSigner: Token nur Contact
src/Controller/SignController.php
src/Controller/SignGuestController.php   ← nur Contact
assets/sign.ts                 ← alle Modi + ggf. Untermodule
assets/styles/sign.scss
templates/sign/index.html.twig
templates/sign/prepare.html.twig
templates/sign/review.html.twig
templates/sign/show.html.twig
templates/sign/sent.html.twig
templates/sign/remind.html.twig
templates/sign/certificate.html.twig
templates/sign/certificate_pdf.html.twig
templates/sign/guest_auth.html.twig
templates/sign/guest_sign.html.twig
templates/sign/guest_done.html.twig
templates/sign/guest_wait.html.twig
templates/sign/email/
sql/sign_schema.sql
webpack.config.js              ← nur Entry sign
```

### Explizit nicht übernehmen

```
assets/sign_guest.ts
webpack Entry sign_guest
encore_entry_script_tags('sign_guest')   → überall durch 'sign' ersetzen
encore_entry_link_tags('sign_guest')     → überall durch 'sign' ersetzen
```

### Nach dem Kopieren prüfen

- [ ] Signer 1 wird automatisch als `User` / `is_self` angelegt  
- [ ] `access_token` nur wenn `contact_id` gesetzt  
- [ ] `SignGuestController` lehnt User-Signer ab  
- [ ] Alle `guest_*.html.twig` laden Entry **`sign`**  
- [ ] Kein Verweis auf `sign_guest` in Webpack/Templates  
- [ ] User-Auswahl für Signer 2+ implementiert (FTC hat nur Contact-Autocomplete)  
- [ ] `sendSignerInvites()` unterscheidet Contact vs. User Links  

---

## 13. Sicherheit

| Thema | Massnahme |
|-------|-----------|
| Contact-Link | UUID v4, unique, `expires_at` |
| Contact-Auth | Token + optional OTP; Session-Key `sign_guest_auth_{token}` |
| User-Signer | App-Session, kein Public Link |
| Mandant | `globalId` bei Dokument-Zugriff |
| CSRF | Owner-POST-Actions |
| PDF | Schreibschutz nach Stamp |

---

## 14. FTC-Referenz vs. Ziel-App

| | Ziel-App | FTC (Referenz) |
|---|----------|----------------|
| Signer 1 | `User` + `user_id` + `is_self` | nur `is_self`, kein `user_id` FK |
| Signer 2+ Contact | `contact_id` + Token | oft nur E-Mail-Freitext |
| Signer 2+ User | `user_id`, App-Route | nicht modelliert |
| Public Controller | nur Contact | alle externen E-Mails |
| Frontend | 1× `sign.ts` | 2× `sign.ts` + **`sign_guest.ts`** |
| Guest-Templates | Entry `sign` | Entry `sign_guest` |
| User-Autocomplete | neu bauen | nur `app_sign_find_contacts` |

---

## 15. Installation

```bash
composer require setasign/fpdi tecnickcom/tcpdf
php bin/console doctrine:schema:update --force
npm run dev
```

---

## 16. Verwandte Dokumentation

- `src/HelpContent/ArticlesSftSign.php` (beschreibt FTC-Produkt, inkl. Legacy-Gast-UI)
- `docs/SFT_COLLECT.md`
