buchhaltungswidget/README.md

# BUCHHALTUNGS-WIDGET / ACCOUNTING WIDGETS FOR [DOLIBARR ERP & CRM](https://www.dolibarr.org)

**Version:** 1.3
**Compatibility:** Dolibarr 19.0+
**Author:** Eduard Wisch - Data IT Solution
**License:** GPL v3+

---

## Deutsch

### Beschreibung

Das Buchhaltungs-Widget Modul erweitert Dolibarr um drei leistungsstarke Dashboard-Widgets fuer die Finanzuebersicht sowie eine Zahlungsstatistik auf der Kundenkarte.

### Widgets

#### 1. Umsatzsteuer-Uebersicht (USt)
- Quartalsweise Darstellung der USt-Zahllast
- Vergleich mit Vorjahr (gestrichelte Linie)
- Aktuelles Quartal hervorgehoben
- Farbcodierung: Rot = Zahllast, Gruen = Erstattung
- Detailseite mit monatlicher/quartalsweiser Ansicht
- Hilfe-Icon mit Erklaerung der Berechnung

#### 2. Gewinn/Verlust (Rohertrag)
- Kumulierter Gewinn/Verlust im Jahresverlauf
- Berechnung ueber Buchungskonten (wenn vorhanden):
  - Einnahmen: Kontenklasse 8xxx (Erloese)
  - Materialkosten: Kontenklasse 3xxx (Wareneinsatz)
- Keine Betriebskosten (4xxx) - nur Rohertrag
- Fallback auf Rechnungsdaten wenn keine Buchungen vorhanden
- Schaetzung der Einkommensteuer
- Farbige Linie: Gruen = Gewinn, Rot = Verlust
- Hilfe-Icon mit Erklaerung der Berechnung

#### 3. Rentabilitaet (Echte Rentabilitaet)
- Zeigt echte Rentabilitaet inkl. ALLER Kosten
- Berechnung ueber Buchungskonten (wenn vorhanden):
  - Einnahmen: Kontenklasse 8xxx (Erloese)
  - Alle Ausgaben: Kontenklasse 3xxx + 4xxx (Wareneinsatz + Betriebskosten)
- Fallback auf Rechnungsdaten wenn keine Buchungen vorhanden
- Gewinnmarge in Prozent
- Produktivitaetsbewertung mit 5 Stufen:
  - Ausgezeichnet (>100%)
  - Gut (50-100%)
  - Durchschnittlich (20-50%)
  - Niedrig (0-20%)
  - Kritisch (<0%)
- Hilfe-Icon mit Erklaerung der Berechnung

### Zahlungsstatistik (Kundenkarte)

Zeigt auf der Kundenkarte das Zahlungsverhalten des Kunden:
- Durchschnittliche Zahlungsdauer
- Vergleich zur Faelligkeit
- Farbcodierte Bewertung:
  - Gruen: Vorbildlich (>5 Tage frueh)
  - Blau: Puenktlich
  - Gelb: Spaetzahler (bis 7 Tage)
  - Orange: Verspaetet (7-14 Tage)
  - Rot: Problematisch (>14 Tage)

### Rechnungsstatistik nach Kategorie

Neue Statistikseite unter Kundenrechnungen:
- Filter nach Rechnungskategorie (Schlagwort/Tag)
- Zusaetzliche Filter: Kunde, Benutzer, Status, Jahr
- Diagramme: Anzahl, Betrag, Durchschnitt pro Monat
- Jahrestabelle mit prozentualen Veraenderungen

### Einstellungen

Im Admin-Bereich koennen folgende Optionen konfiguriert werden:
- Zahlungsstatistik auf Kundenkarte ein/ausschalten
- Menueeintrag im Hauptmenue ein/ausschalten

### Installation

1. Ordner `buchaltungswidget` nach `htdocs/custom/` kopieren
2. In Dolibarr: Startseite > Einstellungen > Module
3. Modul "Buchhaltungs-Widget" aktivieren
4. Widgets auf dem Dashboard hinzufuegen

### Voraussetzungen

- Dolibarr 19.0 oder hoeher
- PHP 7.1 oder hoeher
- Modul "Rechnungen" aktiviert
- Modul "Lieferantenrechnungen" aktiviert (fuer vollstaendige Funktion)

---

## English

### Description

The Accounting Widgets module extends Dolibarr with three powerful dashboard widgets for financial overview and payment statistics on the customer card.

### Widgets

#### 1. VAT Overview
- Quarterly VAT balance display
- Year-over-year comparison (dashed line)
- Current quarter highlighted
- Color coding: Red = to pay, Green = refund
- Detail page with monthly/quarterly view
- Help icon explaining calculation

#### 2. Profit/Loss (Gross Margin)
- Cumulative profit/loss throughout the year
- Calculation via accounting accounts (if available):
  - Income: Account class 8xxx (Revenue)
  - Material costs: Account class 3xxx (Cost of goods)
- No operating costs (4xxx) - gross margin only
- Fallback to invoice data if no bookings exist
- Income tax estimation
- Colored line: Green = profit, Red = loss
- Help icon explaining calculation

#### 3. Profitability (Real Profitability)
- Shows real profitability including ALL costs
- Calculation via accounting accounts (if available):
  - Income: Account class 8xxx (Revenue)
  - All expenses: Account class 3xxx + 4xxx (Cost of goods + Operating costs)
- Fallback to invoice data if no bookings exist
- Profit margin percentage
- Productivity rating with 5 levels:
  - Excellent (>100%)
  - Good (50-100%)
  - Average (20-50%)
  - Low (0-20%)
  - Critical (<0%)
- Help icon explaining calculation

### Payment Statistics (Customer Card)

Displays payment behavior on the customer card:
- Average payment duration
- Comparison to due date
- Color-coded rating:
  - Green: Excellent (>5 days early)
  - Blue: On time
  - Yellow: Slow payer (up to 7 days)
  - Orange: Late (7-14 days)
  - Red: Critical (>14 days)

### Invoice Category Statistics

New statistics page under Customer Invoices:
- Filter by invoice category (tag)
- Additional filters: Customer, User, Status, Year
- Charts: Count, Amount, Average per month
- Year table with percentage changes

### Settings

The following options can be configured in the admin area:
- Enable/disable payment statistics on customer card
- Enable/disable menu entry in main menu

### Installation

1. Copy `buchaltungswidget` folder to `htdocs/custom/`
2. In Dolibarr: Home > Setup > Modules
3. Enable "Accounting Widgets" module
4. Add widgets to your dashboard

### Requirements

- Dolibarr 19.0 or higher
- PHP 7.1 or higher
- "Invoices" module enabled
- "Supplier Invoices" module enabled (for full functionality)

---

## Changelog

### Version 1.3
- Neu: Praezise Berechnung ueber Buchungskonten (SKR03/SKR04)
  - Gewinn/Verlust: Kontenklasse 8xxx (Erloese) minus 3xxx (Wareneinsatz)
  - Rentabilitaet: Kontenklasse 8xxx minus 3xxx + 4xxx (alle Kosten)
- Neu: Automatischer Fallback auf Rechnungsdaten wenn keine Buchungen vorhanden
- Neu: Hilfe-Icons mit Tooltips bei allen Widgets
- Neu: Dynamisches Chart.js-Laden (Charts funktionieren jetzt auch auf Dashboard ohne vorheriges Laden)
- Fix: Charts wurden nicht angezeigt wenn Chart.js nicht geladen war

### Version 1.2
- Fix: VAT widget showed paid VAT (input tax) always as 0 (wrong column name in supplier invoice detail table)
- Fix: Cancelled invoices (status 3) were included in all financial calculations
- Fix: Year comparison percentages in category statistics were calculated in wrong direction
- Fix: Robust path detection for invoice_category_stats.php
- Added missing English translations for category statistics

### Version 1.1
- New: Invoice Category Statistics page
  - Filter invoices by category/tag
  - Charts for count, amount, average
  - Year comparison with percentage changes
- Menu entry under Customer Invoices

### Version 1.0
- Initial release
- VAT Overview Widget with quarterly/monthly view
- Profit/Loss Widget with cumulative chart
- Profitability Widget with productivity rating
- Payment statistics on customer card
- Full German and English translations
- Theme-compatible styling (Dark/Light mode)
- Admin settings for feature toggling

---

## License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

## Support

For issues and feature requests, please contact:
- Email: data@data-it-solution.de