dolibarr.stundenzettel/README.md

# Stundenzettel Modul für Dolibarr

**Version:** 1.7.0
**Autor:** Data IT Solution
**Kompatibilität:** Dolibarr 16.0+
**Lizenz:** GPL v3

## Beschreibung

Das Stundenzettel-Modul ermöglicht die Verwaltung von Stundenzetteln für Kundenaufträge in Dolibarr. Es bietet eine umfassende Dokumentation von Arbeitszeiten, verbrauchten Materialien, Mehraufwand und Notizen.

## Funktionen

### Kernfunktionen

- **Stundenzettel-Verwaltung**: Erstellen, Bearbeiten und Löschen von Stundenzetteln pro Auftrag und Datum
- **Leistungserfassung**: Zeiterfassung mit Start-/Endzeit und automatischer Dauerberechnung
- **Zeitüberlappungsprüfung**: Verhindert doppelte Zeitbuchungen auf demselben Stundenzettel
- **Produktverfolgung**: Dokumentation von verbrauchten Materialien aus dem Auftrag
- **Mehraufwand**: Erfassung zusätzlicher Produkte/Dienstleistungen, die nicht im Auftrag waren
- **Entfällt-Markierung**: Kennzeichnung von Produkten, die nicht verbaut werden müssen
- **Notizen**: Merkzettel und Notizen für den nächsten Termin

### Freigabe & Rechnungsstellung

- **Stundenzettel-Freigabe**: Sperren von Stundenzetteln nach Fertigstellung
- **Rechnungsübernahme**: Automatische Übernahme aller Produkte und Leistungen in eine Rechnung
- **Stunden-Modus**: Wahlweise Übernahme gruppiert oder pro Stundenzettel (einstellbar pro Auftrag)
- **Rücknahme**: Bereits verbaute Produkte als zurückgenommen markieren
- **Leistungsbeschreibungen**: Arbeitsbeschreibungen werden automatisch in die Rechnung übernommen

### Integration

- **SubtotalTitle-Integration**: Unterstützung für Produktgruppen aus dem SubtotalTitle-Modul
- **Auftragsintegration**: Direkter Zugriff auf Stundenzettel über Aufträge
- **Kundenintegration**: Standard-Leistung pro Kunde konfigurierbar

## Installation

1. Modul-Ordner nach `/custom/stundenzettel/` kopieren
2. In Dolibarr einloggen
3. Unter **Einstellungen > Module/Anwendungen** das Modul "Stundenzettel" aktivieren
4. Das Modul erstellt automatisch:
   - Erforderliche Datenbanktabellen
   - Extrafeld "Auftragsbeschreibung" für Aufträge
   - Extrafeld "Standard-Leistung" für Kunden
   - Datenbank-View für Dienstleistungen

## Konfiguration

Die Moduleinstellungen finden Sie unter **Einstellungen > Module > Stundenzettel > Zahnrad-Symbol**:

| Einstellung | Beschreibung |
|-------------|--------------|
| **Zeiteingabe-Modus** | Dropdown (15-Minuten-Takt) oder Freitext (exakte Uhrzeit) |
| **Standard-Filter** | Welcher Filter in der Produktliste standardmäßig angezeigt wird |
| **Standard-Datum** | Aktuelles Datum oder Datum des letzten offenen Stundenzettels |
| **Stunden-Übernahme** | Gesamtstunden auf einer Zeile oder pro Tag eine Zeile |

### Stundenübernahme-Modus (pro Auftrag)

Im Auftrag kann unter den Extrafeldern der Modus der Stundenübernahme eingestellt werden:

| Modus | Beschreibung |
|-------|--------------|
| **Gruppiert (Standard)** | Alle gleichen Leistungspositionen über alle Stundenzettel zusammenrechnen |
| **Pro Stundenzettel** | Jeder Stundenzettel bekommt eigene Rechnungszeile(n) mit STZ-Referenz und Datum |

In beiden Modi werden die Leistungsbeschreibungen automatisch in die Rechnungszeile übernommen.

### Standard-Leistung beim Kunden

Sie können beim Kunden (unter **Kunden > Kundenkarte**) eine Standard-Leistung (Dienstleistung) hinterlegen. Diese wird dann bei allen Stundenzetteln für diesen Kunden angezeigt und kann für die Rechnungsstellung verwendet werden.

## Datenbanktabellen

| Tabelle | Beschreibung |
|---------|--------------|
| `llx_stundenzettel` | Haupttabelle für Stundenzettel |
| `llx_stundenzettel_leistung` | Leistungen/Arbeitszeiten (inkl. fk_product für Leistungsposition) |
| `llx_stundenzettel_product` | Verbrauchte Produkte |
| `llx_stundenzettel_tracking` | Gesamtübersicht Mengen pro Auftrag |
| `llx_stundenzettel_note` | Notizen und Merkzettel |
| `llx_product_services` | View für Dienstleistungen (Extrafeld-Filter) |

## Extrafelder

| Feld | Element | Beschreibung |
|------|---------|--------------|
| `auftragsbeschreibung` | Auftrag | Zusätzliche Beschreibung für den Auftrag |
| `stundenzettel_status` | Auftrag | Status der Stundenzettel (0=Offen, 1=Freigegeben, 2=Abgerechnet) |
| `stundenzettel_netto` | Auftrag | Berechneter Netto-Wert aller freigegebenen Stundenzettel |
| `stundenzettel_hours_mode` | Auftrag | Stundenübernahme-Modus: Gruppiert oder Pro Stundenzettel |
| `stundenzettel_default_service` | Kunde | Standard-Dienstleistung für Stundenzettel |

## Berechtigungen

| Berechtigung | Beschreibung |
|--------------|--------------|
| Eigene Stundenzettel lesen | Eigene Stundenzettel anzeigen |
| Alle Stundenzettel lesen | Alle Stundenzettel anzeigen |
| Stundenzettel erstellen | Stundenzettel erstellen |
| Alle Stundenzettel bearbeiten | Alle Stundenzettel bearbeiten (Admin) |
| Freigeben | Stundenzettel freigeben/sperren |
| Eigene Stundenzettel löschen | Eigene Stundenzettel löschen |
| Alle Stundenzettel löschen | Alle Stundenzettel löschen (Admin) |

## Workflow

1. **Stundenzettel erstellen**: Über Auftrag > Stundenzettel-Tab
2. **Leistungen erfassen**: Arbeitszeiten mit Start-/Endzeit dokumentieren
3. **Produkte dokumentieren**: Verbrauchte Materialien aus dem Auftrag erfassen
4. **Mehraufwand hinzufügen**: Zusätzliche Produkte bei Bedarf
5. **Notizen erstellen**: Merkzettel für nächsten Termin
6. **Stundenzettel freigeben**: Nach Fertigstellung sperren
7. **In Rechnung übernehmen**: Automatische Rechnungserstellung

## Changelog

### Version 1.7.0
- **Rücknahme-Anzeige verbessert**: Rücknahmen werden mit rotem Badge (-X) angezeigt
- **Rücknahme beeinflusst Beauftragt**: Zurückgenommene Mengen werden von der Zielmenge abgezogen (soll nicht wieder verbaut werden)
- **Status korrekt bei Rücknahme**: Wenn alles zurückgenommen wurde, zeigt der Status "Erledigt" statt "Offen"
- **Mehraufwand-Filter**: Der Mehraufwand-Bereich wird jetzt auch nach dem aktiven Filter (offen/erledigt/alle) gefiltert
- **Tracking-Tab Rücknahmen**: Rücknahmen werden auch im Tracking-Tab (Lieferauflistung) korrekt berücksichtigt
- **Freitext-Rücknahmen**: Rücknahmen von Freitext-Produkten werden über description gematcht und korrekt zugeordnet
- **Bugfix Freitext-Label**: Bei Rücknahme von Freitext-Produkten wird jetzt auch product_label korrekt gesetzt

### Version 1.6.0
- **Stundenübernahme-Modus pro Auftrag**: Neues Extrafeld am Auftrag zur Wahl zwischen gruppierten Leistungen (Standard) und pro-Stundenzettel-Übernahme
- **Leistungsbeschreibungen in Rechnung**: Arbeitsbeschreibungen aus den Stundenzetteln werden automatisch in die Rechnungszeilen übernommen
- **Bugfix Rücknahme-Dropdown**: Manuell hinzugefügte Produkte (ohne Auftragszeile) werden jetzt korrekt angezeigt
- **Bugfix Entfällt**: Freitext-Produkte und Produkte ohne Auftragszeile werden korrekt berücksichtigt
- **Bugfix NULL-Handling**: Korrektes SQL-Handling für `fk_product IS NULL` bei Freitext-Produkten (5 Stellen)
- **Bugfix Rechnungsübernahme**: Produkte mit `origin='added'` ohne Auftragszeile werden jetzt in der Rechnung berücksichtigt
- **Bugfix Tracking-Tab**: Mehraufwand/zusätzlich verbaute Produkte werden vollständig in der Lieferauflistung angezeigt

### Version 1.5.0
- **Rücknahme-Bereich**: Bereits verbaute Produkte können als zurückgenommen markiert werden
- **Checkbox-Sichtbarkeit**: Verbesserte Darstellung der Produktauswahl
- **Berechtigungen**: Erweiterte Berechtigungssteuerung

### Version 1.4.0
- **Stundenzettel öffnen ohne Produktauswahl**: Button "Stundenzettel öffnen" funktioniert jetzt auch ohne Checkbox-Auswahl - öffnet oder erstellt direkt einen Stundenzettel
- **Dezimalmengen**: Alle Mengenfelder (Produkte, Mehraufwand, Entfällt) unterstützen jetzt Kommazahlen (z.B. 0,3m Kabel)
- **Aktionsspalte in Liste**: Jeder Listeneintrag hat einen direkten Link zum Stundenzettel-Tab des Auftrags
- **Aufgeräumtes Menü**: Nur noch die Übersicht hat ein Icon, restliche Menüpunkte ohne Icons

### Version 1.3.0
- **Netto STZ Spalte in Auftragsliste**: Neue Spalte zeigt den Netto-Wert aller freigegebenen Stundenzettel eines Auftrags
  - Automatische Berechnung bei Freigabe/Wiedereröffnung von Stundenzetteln
  - Berücksichtigt Produkte (mit Auftrags- oder Katalogpreisen)
  - Berücksichtigt Arbeitsstunden (mit der gewählten Leistungsposition pro Zeile)
  - Unterstützt kundenspezifische Preise
- **Verbesserte Preisberechnung**: Jede Arbeitszeit-Zeile verwendet den Preis ihrer eigenen Leistungsposition (nicht mehr Standard-Leistung des Kunden)
- **Extrafeld `stundenzettel_netto`**: Wird automatisch bei Modulaktivierung erstellt
- **Debug-Script**: `debug_netto.php` für Fehleranalyse der Netto-Berechnung

### Version 1.2.0
- **Leistungsposition pro Arbeitszeit**: Jede Arbeitszeit kann einer eigenen Leistungsposition (Dienstleistung) zugeordnet werden
- **Mobile-optimierte Ansicht**: Responsive CSS für Touch-Geräte (Smartphones/Tablets)
  - Kompakte Tabellen mit horizontalem Scrollen bei Bedarf
  - Größere Touch-Targets für Buttons und Icons
  - Optimierte Eingabefelder (Font 16px, kein iOS-Zoom)
  - Beschreibungsfelder auf separater Zeile für bessere Bedienbarkeit
  - Grund/Beschreibung wird klein unter dem Produktnamen angezeigt
  - Action-Buttons sticky am unteren Bildschirmrand
  - Dark Mode Support (kompatibel mit Dolibarr Themes)
- **Erweiterte Lieferauflistung**: Tracking-Tab zeigt jetzt auch Leistungen gruppiert nach Leistungsposition
- **Verbesserte Tab-Navigation**: Einheitliche Tabs auf Auftrags- und Stundenzettel-Ebene
- **Layout-Verbesserungen**: Konsistente Spaltenbreiten und Ausrichtung in allen Tabellen

### Version 1.1.0
- Standard-Leistung beim Kunden hinterlegen (nur Dienstleistungen auswählbar)
- Stunden-Übernahme Modus (Gesamt oder pro Tag)
- Zeitüberlappungsprüfung für Leistungen
- Verbessertes Setup-Seitenlayout
- Datenbank-View für Dienstleistungs-Filter

### Version 1.0.0
- Initiale Version
- Grundlegende Stundenzettel-Verwaltung
- Leistungs- und Produkterfassung
- Mehraufwand und Entfällt-Funktionen
- Notizen-System
- Freigabe und Rechnungsübernahme
- SubtotalTitle-Integration

## Support

Bei Fragen oder Problemen wenden Sie sich an:
**Data IT Solution**
E-Mail: data@data-it-solution.de
Web: https://data-it-solution.de

## Lizenz

Dieses Modul steht unter der GNU General Public License v3. Siehe LICENSE-Datei für Details.