09 – Rapport (Baustellenrapport)

Reifegrad: 🟢 produktiv · Schicht: rapports + rapport_entries + rapport_materials, @work7/domain (Rapport-Funktionen), src/lib/rapport-draft-guard.ts, src/app/rapport, src/app/api/rapports/*, src/templates/rapport-template.html

Zweck

Tägliche/auftragsbezogene Leistungsnachweise von der Baustelle: erbrachte Arbeitsstunden (je Mitarbeiter/Tätigkeit) und verbrauchtes Material – als Grundlage für die Abrechnung nach Aufwand (Regie).

Datenmodell

• rapports: rapport_number (UNIQUE), completed (BOOLEAN – Abschluss-Flag), customer_id, project_id, created_by_user_id, Signatur (signed_pdf, signed_at, signed_by_name/_email), billing_status ∈ {unbilled, partial, billed} (Migration 006).
• rapport_entries: Arbeitszeile – date, job_category, hours, employee_user_id.
• rapport_materials: Materialzeile – name, quantity, unit, notes.

Geschäftslogik (@work7/domain)

listRapports, getRapport, createRapport, addRapportEntry, addRapportMaterial, updateRapport, completeRapport, deleteRapport, sendRapportEmail.

• Draft-Guard: assertRapportDraft(completed) + src/lib/rapport-draft-guard.ts verhindern Änderungen an abgeschlossenen Rapporten (completed=true → gesperrt). completeRapport schließt ab.
• E-Mail-Versand: sendRapportEmail rendert das Rapport-PDF und versendet es (an Kunde).

API-Endpunkte

Endpoint	Funktion
GET/POST /api/rapports	Liste / anlegen
GET/PUT/DELETE /api/rapports/[id]	Detail / ändern / löschen
GET/POST /api/rapports/[id]/entries · /entries/[entryId]	Arbeitszeilen
GET/POST /api/rapports/[id]/materials · /materials/[materialId]	Materialzeilen
POST /api/rapports/[id]/send-email	Rapport per E-Mail senden
GET /api/pdf/rapport/[id]	Rapport-PDF
… /api/signing/rapport/[id]	digitale Signatur (DocuSign, siehe 14-docusign-signing)

Hinweis: Es existiert zusätzlich eine ältere Singular-Route /api/rapport/route.ts; der aktuelle Funktionsumfang liegt unter /api/rapports/* (Plural).

Verzahnung mit anderen Features

• Zeiterfassung → Rapport: Projektzeiten aus time_logs werden per importProjectTimesToRapport als rapport_entries übernommen; time_logs.rapport_entry_id hält die 1:1-Verknüpfung (siehe 08-zeiterfassung).
• Rapport → Rechnung: POST /api/invoices/from-rapports erzeugt eine Rechnung aus einem oder mehreren Rapporten; invoice_rapport_links dokumentiert die Zuordnung inkl. billing_percentage. Stunden werden über labor_rates(job_category) bepreist (siehe 10-rechnungen-e-rechnung). billing_status wird fortgeschrieben.
• WhatsApp-Agent: Rapport-Entwürfe können per Sprache/Text auf der Baustelle entstehen – Capability-Stub rapport-draft + Draft-Store (siehe 11-whatsapp-agent).

UI

/rapport (Liste), /rapport/[id] (Detail mit Zeilen, Material, Abschluss, Versand, Signatur). Komponenten: src/components/rapports/*.

Bekannte Befunde / offene Punkte

• Abschluss-Logik basiert auf einem einfachen completed-Flag (kein mehrstufiger Status).
• Doppelte Route-Welt rapport (Singular, legacy) vs. rapports (Plural, aktuell) – bei Aufräumarbeiten konsolidieren.

Verwandte Notes

• 04-projekte · 08-zeiterfassung · 10-rechnungen-e-rechnung · 14-docusign-signing · 18-pdf-print-templates