bericht/README.md

# Bericht — Arbeitsberichte für Dolibarr

Erstellt aus den Anhängen einer Rechnung (oder eines Auftrags / Angebots) einen Arbeitsbericht als PDF.
Bilder und PDFs lassen sich im Browser annotieren (Pfeile, Kreise, Rechtecke, Text, Freihand) — der fertige Bericht wird unter *Verknüpfte Dokumente* der Rechnung abgelegt.

## Funktionen

- **Reiter „Bericht"** auf Rechnungen, Aufträgen und Angeboten (jeweils per Konstante deaktivierbar)
- **Anhänge-Browser** zeigt alle Dateien des aktuellen Dokuments **und** der direkt verknüpften Objekte (z. B. der Auftrag zur Rechnung)
- **Auswahl per Checkbox** — markierte Dateien werden als Seiten in den Bericht übernommen
- **Browser-Editor** mit PDF.js + Fabric.js: Pfeile, Kreise, Rechtecke, Freihand, Text, Farbe, Strichstärke, Undo/Redo
- **Seiten-Verwaltung** per Drag&Drop (SortableJS): umordnen, löschen, drehen, neue Seiten hochladen
- **Notizen pro Seite** — werden im finalen PDF unten auf der Seite gedruckt
- **Deckblatt aus ODT-Vorlage** mit Platzhaltern (`{auftragsnummer}`, `{kunde_name}`, `{datum}`, …)
- **ODT-Templates** im Admin-Bereich verwaltbar (mehrere Vorlagen, Standard wählbar)
- **Auftragsnummer** wird automatisch aus dem Extrafield `options_auftragsnummer` der Rechnung gezogen
- **Mehrere Berichte pro Dokument** möglich
- Berichte als **Entwurf** speichern (jederzeit wieder editierbar) oder **finalisieren** (PDF erzeugen)
- **PWA-API** für Mobile-Nutzung: Aufträge, Fotos, Sprachnotizen, Materiallisten, Signaturen
- **PDF-Viewer in PWA** mit PDF.js Canvas-Rendering (Zoom, Seitennummerierung, Download)

## Voraussetzungen

- Dolibarr ≥ 19.0
- PHP ≥ 7.4
- TCPDF (in Dolibarr enthalten)
- **FPDI** (für PDF-Anhänge in den Bericht zu mergen) — empfohlen, optional
- **LibreOffice headless** (für ODT→PDF Konvertierung der Deckblätter)
- Optional: `pdfinfo` oder `imagick` für PDF-Seitenanzahl-Erkennung

## Installation

1. Modul-Verzeichnis nach `dolibarr/htdocs/custom/bericht/` (oder per Symlink aus dem Module-Mount-Pfad) kopieren
2. In Dolibarr unter **Konfiguration → Module/Anwendungen** das Modul **Bericht** aktivieren
3. Beim Aktivieren werden die SQL-Tabellen `llx_bericht` und `llx_bericht_page` angelegt
4. Vorhandene Extrafields auf `llx_facture_extrafields` (`auftragsnummer`, `angebotsnummer`, …) werden erkannt und nicht überschrieben — fehlende werden angelegt
5. Im Admin-Bereich (`/bericht/admin/setup.php`) die ODT-Templates hochladen und Standard-Template setzen

## Verwendung

1. Eine Rechnung öffnen (`/compta/facture/card.php?id=…`)
2. Reiter **Bericht** auswählen
3. **+ Neuer Bericht** klicken — die Auftragsnummer wird automatisch übernommen
4. Im Editor links die gewünschten Anhänge ankreuzen → **Auswahl in Bericht übernehmen**
5. Im mittleren Editor mit den Werkzeugen Pfeile, Texte etc. zeichnen
6. Seiten rechts per Drag&Drop sortieren, einzelne Seiten löschen, neue Dateien hochladen
7. **Bericht finalisieren** — PDF wird erzeugt, Deckblatt aus der ODT-Vorlage gerendert und unter den verknüpften Dokumenten der Rechnung abgelegt

## ODT-Template Platzhalter

| Platzhalter | Inhalt |
|---|---|
| `{auftragsnummer}` | Aus extrafield `options_auftragsnummer` der Rechnung |
| `{angebotsnummer}` | Aus extrafield `options_angebotsnummer` |
| `{rechnungsnummer}` | `ref` der Rechnung |
| `{kunde_name}` | Name des Kunden (Société) |
| `{kunde_adresse}` | Adresse des Kunden, mehrzeilig |
| `{datum}` | Heutiges Datum |
| `{beschreibung}` | extrafield `options_beschreibung` |
| `{hinweis}` | extrafield `options_hinweis` |
| `{bericht_titel}` | Titel des Berichts |
| `{ersteller}` | Login-Name des erstellenden Users |

## PWA-Integration (Baustelle Mobile App)

Die **Baustelle-PWA** (`https://awl.data-it-solution.de/baustelle/`) nutzt die folgenden API-Endpoints des Bericht-Moduls:

### Authentifizierung
```
POST /custom/bericht/api/auth.php
Body: { login: string, password: string }
Response: { ok: true, token: JWT, user: {...} }
```

JWT-Token hat 7 Tage Gültigkeit und enthält: `sub` (user id), `login`, `name`, `perms` (read/write/delete/admin).

### Order-APIs
```
GET    /custom/bericht/api/orders.php
GET    /custom/bericht/api/orders.php?id=<id>
GET    /custom/bericht/api/orders.php?id=<id>&action=photos
POST   /custom/bericht/api/orders.php?action=create
```

### Dateien
```
GET    /custom/bericht/api/photo.php?relpath=<path>&jwt=<token>
       Liefert Dateien aus DOL_DATA_ROOT (Whitelist: facture/, commande/, propal/, bericht/)
       Optional: ?size=small|mini (Thumbnails), ?download=1 (Attachment-Header)
```

### PDF-Ansicht
```
GET    /custom/bericht/api/pdf.php?id=<bericht_id>&jwt=<token>
       Liefert finalisiertes Bericht-PDF als Blob
```

### Seiten-Verwaltung (PWA)
```
DELETE /custom/bericht/api/pages.php?id=<page_id>
POST   /custom/bericht/api/pages.php?id=<page_id>  Body: { note: string }
POST   /custom/bericht/api/pages.php?action=signature&bericht_id=<id>
       Body: FormData mit file=<PNG-Blob>, signer_name, gps_lat, gps_lon
```

## Architektur

```
bericht/
├── core/modules/modBericht.class.php   Modul-Descriptor, Tabs, Extrafields-Init
├── class/bericht.class.php             Bericht + BerichtPage CRUD
├── lib/bericht.lib.php                 Helper (Anhänge sammeln, Auftragsnr., Templates)
├── bericht_card.php                    Editor-Seite (Tab-Inhalt)
├── admin/setup.php                     Admin: ODT-Templates, Konstanten
├── ajax/                               Legacy Endpoints (Token-geschützt)
│   ├── _inc.php                        Gemeinsamer Header
│   ├── add_attachment.php              Anhang als Seite hinzufügen
│   ├── upload_extra.php                Direkter Upload
│   ├── save_annotations.php            Fabric-JSON speichern
│   ├── page_meta.php                   Annotationen + Notiz laden
│   ├── page_image.php                  Seitenbild/PDF ausliefern
│   ├── delete_page.php
│   ├── reorder_pages.php
│   └── generate_pdf.php                Finalisierung: TCPDF + FPDI + ODT-Deckblatt
├── api/                                REST-API (JWT-Auth)
│   ├── _inc.php                        JWT-Authentifizierung + Dolibarr-Init
│   ├── _jwt.php                        JWT encoding/decoding
│   ├── auth.php                        Login-Endpoint
│   ├── orders.php                      Order-Liste, Detail, Fotos, Create
│   ├── photo.php                       Datei-Serving mit Whitelist
│   ├── pdf.php                         Finalized Bericht-PDF
│   ├── pages.php                       Seiten-Verwaltung (Note, Rotation, Signature)
│   ├── reports.php                     Bericht-CRUD
│   ├── templates.php                   ODT-Templates
│   ├── materials.php                   Materiallisten
│   ├── voice.php                       Sprachnotizen (Upload + Transkription)
│   └── transcribe.php                  Whisper-Transkription
├── js/
│   ├── editor.js                       PDF.js + Fabric.js Integration
│   └── lib/                            PDF.js, Fabric.js, SortableJS (lokal)
├── css/bericht.css
├── sql/
│   ├── llx_bericht.sql
│   ├── llx_bericht.key.sql
│   ├── llx_bericht_page.sql
│   └── llx_bericht_page.key.sql
└── langs/{de_DE,en_US}/bericht.lang
```

## Lizenz

GPL v3+