docs: add desktop app user guide

README.md

@@ -1,3 +1,453 @@
-# bc-erp-desktop-releases
+# BC-ERP Desktop App
 
-BC-ERP Desktop Windows installer releases
+Öffentliches Release-Repository für die BC-ERP Windows-Desktop-App. Dieses Repository enthält fertige Windows-Installer als Releases und diese bebilderte Anwenderdokumentation.
+
+## Inhaltsverzeichnis
+
+- [Zweck der Desktop-App](#zweck-der-desktop-app)
+- [Installation unter Windows](#installation-unter-windows)
+- [Erster Start: Serveradresse und Login](#erster-start-serveradresse-und-login)
+- [Updates installieren](#updates-installieren)
+- [Dashboard](#dashboard)
+- [Kunden](#kunden)
+- [Projekte](#projekte)
+- [Angebote](#angebote)
+- [Rechnungen](#rechnungen)
+- [Materialbeschaffung](#materialbeschaffung)
+- [Katalog und Mitarbeiter](#katalog-und-mitarbeiter)
+- [Einstellungen](#einstellungen)
+- [Backup und Wiederherstellung](#backup-und-wiederherstellung)
+- [Rechnungsexport](#rechnungsexport)
+- [Benutzerverwaltung](#benutzerverwaltung)
+- [Fehlerbehebung](#fehlerbehebung)
+
+## Zweck der Desktop-App
+
+Die BC-ERP Desktop-App ist die Windows-Anwendung für Büro, Verwaltung und Projektsteuerung. Sie verbindet sich mit dem privaten BC-ERP Backend und bildet die zentrale Oberfläche für:
+
+- Kundenverwaltung
+- Projektverwaltung
+- Angebote
+- Rechnungen
+- Aufmaß- und Stundenübernahme in Rechnungen
+- Materialbedarf und Beschaffung
+- Katalogpositionen und Mitarbeiter
+- Einstellungen, Nummernkreise, PDF-Ausgabe
+- Backup, Restore und Rechnungsexport
+- Benutzer- und Rechteverwaltung
+- Desktop-Updates
+
+Die Desktop-App ist immer online gegen das Backend. Offline-Erfassung und Baustellen-Sync gehören zur Android-App.
+
+## Installation unter Windows
+
+Die Desktop-App wird als Windows-Installer über die Releases dieses Repositorys bereitgestellt.
+
+### Installer herunterladen
+
+1. Dieses Repository öffnen:
+   `https://git.bahmcloud.de/bahmcloud/bc-erp-desktop-releases`
+2. Den Bereich `Releases` öffnen.
+3. Das neueste Release wählen, zum Beispiel `BC-ERP Desktop 1.0.2`.
+4. Unter `Assets` die Datei `BC-ERP-Setup-<version>.exe` herunterladen.
+5. Die heruntergeladene `.exe` starten.
+
+### Windows-Sicherheitsabfrage
+
+Da der Installer nicht aus dem Microsoft Store kommt, kann Windows eine Warnung anzeigen.
+
+Mögliche Meldungen:
+
+- `Der Computer wurde durch Windows geschützt`
+- `Unbekannter Herausgeber`
+- `Diese App kann Änderungen an Ihrem Gerät vornehmen`
+
+Vorgehen bei SmartScreen:
+
+1. `Weitere Informationen` anklicken.
+2. `Trotzdem ausführen` wählen.
+3. Die Windows-Benutzerkontensteuerung bestätigen.
+
+### Setup ausführen
+
+1. Installer starten.
+2. Zielordner übernehmen oder anpassen.
+3. Installation abschließen.
+4. BC-ERP über Startmenü oder Desktop-Verknüpfung öffnen.
+
+Hinweise:
+
+- Für Updates muss die alte Version nicht manuell deinstalliert werden.
+- Der Installer überschreibt die vorhandene Installation.
+- Lokale Einstellungen wie die Serveradresse bleiben bei einem normalen Update erhalten.
+
+## Erster Start: Serveradresse und Login
+
+Beim ersten Start muss die Backend-Adresse gesetzt werden. Die Serveradresse wird lokal in der Desktop-App gespeichert.
+
+![Login und Serveradresse](docs/desktop-app/01-login-serveradresse.png)
+
+Vorgehen:
+
+1. Backend-URL eintragen, zum Beispiel `http://192.168.178.50:3000/api`.
+2. `Speichern` anklicken.
+3. E-Mail und Passwort eintragen.
+4. `Anmelden` anklicken.
+
+Hinweise:
+
+- Eingaben ohne `/api` werden automatisch zu einer API-Adresse normalisiert.
+- Wenn die Backend-Adresse falsch ist, schlägt der Login fehl.
+- Die Serveradresse kann später auf dem Login-Screen geändert werden.
+
+## Updates installieren
+
+Die Desktop-App prüft das öffentliche Desktop-Release-Repository auf neue Installer.
+
+Update über die App:
+
+1. `Einstellungen` öffnen.
+2. Tab `Desktop-Update` öffnen.
+3. `Updates prüfen` anklicken.
+4. Falls ein Update verfügbar ist, `Update installieren` anklicken.
+5. Der Installer wird heruntergeladen und gestartet.
+6. App schließen, Installer abschließen, App neu starten.
+
+![Desktop-Update](docs/desktop-app/17-einstellungen-desktop-update.png)
+
+Manuelles Update:
+
+1. Neuestes Release im Repository öffnen.
+2. `BC-ERP-Setup-<version>.exe` herunterladen.
+3. Installer ausführen.
+4. Vorhandene Installation überschreiben lassen.
+
+## Dashboard
+
+Das Dashboard zeigt den aktuellen Überblick über Angebote, Projekte, Rechnungen und Umsatz.
+
+![Dashboard](docs/desktop-app/02-dashboard.png)
+
+Angezeigt werden:
+
+- offene Angebote
+- aktive Projekte
+- offene Rechnungen
+- bezahlter Umsatz
+- Warnung bei überfälligen Rechnungen
+- letzte Projekte mit Zeiten und Materialbedarf
+
+## Kunden
+
+In `Kunden` werden private und gewerbliche Kunden verwaltet.
+
+![Kunden](docs/desktop-app/03-kunden.png)
+
+Funktionen:
+
+- Kunden suchen
+- neuen Kunden anlegen
+- Kundendaten anzeigen
+- Kundendaten bearbeiten
+- Kunden löschen
+- Anzahl verknüpfter Projekte sehen
+
+## Projekte
+
+Die Projektliste ist die zentrale Übersicht aller Projekte.
+
+![Projekte](docs/desktop-app/04-projekte.png)
+
+Filter:
+
+- Suche
+- Status
+- Kategorie
+- Kunde
+
+Aktionen:
+
+- neues Projekt anlegen
+- Projekt anzeigen
+- Projekt bearbeiten
+- Projekt löschen
+
+### Projektdetail
+
+![Projektdetail](docs/desktop-app/05-projekt-detail.png)
+
+Die Projektdetailansicht bündelt:
+
+- Projektdaten und Status
+- Kunde und Baustellenadresse
+- Angebote, Rechnungen, Zeiten, Aufmaß und Fotos
+- Kostenübersicht Soll/Ist
+- direkte Aktionen für Angebot, Aufmaß, Material und Rechnung
+- Baustellenfotos aus der Android-App
+
+## Angebote
+
+Die Angebotsliste zeigt alle Angebote mit Status, Projekt, Kunde und Betrag.
+
+![Angebote](docs/desktop-app/06-angebote.png)
+
+Funktionen:
+
+- Angebote filtern
+- neues Angebot erstellen
+- Angebot anzeigen
+- Angebot bearbeiten
+- PDF erstellen
+- Angebot löschen
+
+### Angebotsdetail
+
+![Angebotsdetail](docs/desktop-app/07-angebot-detail.png)
+
+Die Detailansicht zeigt:
+
+- Angebotsnummer
+- Projekt und Kunde
+- Status
+- Positionen mit Typ, Menge, Einheit, Einzelpreis und Netto
+- Summen netto, MwSt und brutto
+- PDF-Erzeugung
+- Projektbeauftragung bei angenommenem Angebot
+
+## Rechnungen
+
+Die Rechnungsliste zeigt Entwürfe und fix abgerechnete Rechnungen.
+
+![Rechnungen](docs/desktop-app/08-rechnungen.png)
+
+Wichtig für den Rechnungsworkflow:
+
+- Entwürfe erhalten noch keine Rechnungsnummer.
+- Entwürfe zeigen `in Vorbereitung`.
+- Die Rechnungsnummer wird erst beim fixen Abrechnen vergeben.
+- Dadurch entstehen keine Lücken durch gelöschte Entwürfe.
+
+Aktionen:
+
+- neue Rechnung erstellen
+- Rechnung anzeigen
+- Entwurf abrechnen
+- PDF erzeugen
+- Rechnung stornieren
+- Rechnung als bezahlt markieren
+- Entwurf löschen
+
+### Rechnung erstellen
+
+![Rechnung erstellen](docs/desktop-app/09-rechnung-erstellen.png)
+
+Rechnungen können erstellt werden:
+
+- manuell
+- aus einem Projekt
+- aus einem Angebot
+
+Wichtige Buttons:
+
+- `Angebotsmengen löschen`: setzt Positionsmengen zurück, damit die Rechnung über eigene Mengen oder Aufmaße gefüllt wird.
+- `Aufmaß übernehmen`: öffnet eine Tabelle mit erfassten Aufmaßen.
+- Stundensymbol an Lohnpositionen: übernimmt erfasste Stunden in die Position.
+
+### Aufmaß in Rechnung übernehmen
+
+![Aufmaß übernehmen](docs/desktop-app/10-rechnung-aufmass-dialog.png)
+
+Die Aufmaß-Tabelle erlaubt:
+
+- einzelne Aufmaße auswählen
+- alle Aufmaße auswählen
+- bereits abgerechnete Aufmaße erkennen
+- Material- und Maschinenpositionen übernehmen
+- ausgewählte Positionen in die Rechnung schreiben
+
+Wenn bereits abgerechnete Positionen erneut übernommen werden, warnt die App vor der Doppelabrechnung.
+
+## Materialbeschaffung
+
+Materialbedarf aus der Android-App landet in der Desktop-App unter `Material`.
+
+![Materialbeschaffung](docs/desktop-app/11-materialbedarf.png)
+
+Die Ansicht zeigt:
+
+- Projekt
+- Position
+- Menge
+- Preis
+- Status
+- Angebotszuordnung
+- Quelle Android oder Windows
+
+Status:
+
+- `Angefordert`
+- `Bestellt`
+- `Geliefert`
+- `Storniert`
+
+### Bedarfsmeldung bearbeiten
+
+![Bedarfsmeldung Detail](docs/desktop-app/12-materialbedarf-detail.png)
+
+In der Detailansicht kann der Materialbedarf:
+
+- mit Einzelpreis versehen werden
+- auf `Bestellt`, `Geliefert` oder `Storniert` gesetzt werden
+- einem Angebot zugeordnet werden
+- in Angebotspositionen übernommen werden
+
+## Katalog und Mitarbeiter
+
+Der Katalog enthält Arbeits-, Material- und Maschinenpositionen.
+
+![Katalog](docs/desktop-app/13-katalog.png)
+
+Funktionen:
+
+- Katalogpositionen anlegen
+- Material, Maschinen und Arbeit definieren
+- Einheit und Preis hinterlegen
+- Mitarbeiter anlegen
+- Mitarbeitergruppen verwalten
+- Stundenverrechnungssatz pro Mitarbeiter hinterlegen
+
+Mitarbeiter werden außerdem für App-Logins und Zeitbuchungen genutzt.
+
+## Einstellungen
+
+Die Einstellungen sind in Tabs aufgeteilt.
+
+![Firmeneinstellungen](docs/desktop-app/14-einstellungen-firma.png)
+
+Wichtige Bereiche:
+
+- Firma
+- Nummernkreise
+- MwSt-Sätze
+- PDFs
+- Backup
+- Rechnungsexport
+- Desktop-Update
+- Benutzer
+
+Der Menüpunkt `Einstellungen` ist nur sichtbar, wenn der Benutzer das Recht `Einstellungen` besitzt oder Admin ist.
+
+## Backup und Wiederherstellung
+
+![Backup](docs/desktop-app/15-einstellungen-backup.png)
+
+Funktionen:
+
+- manuelles Backup erstellen
+- Backup herunterladen
+- externes Backup hochladen
+- Backup wiederherstellen
+- manuelle Backups löschen
+- tägliches Auto-Backup aktivieren
+- Auto-Backup-Aufbewahrung einstellen
+
+Auto-Backup:
+
+- läuft einmal pro Tag
+- bewahrt Auto-Backups entsprechend der eingestellten Tage auf
+- löscht keine manuellen oder importierten Backups
+
+## Rechnungsexport
+
+![Rechnungsexport](docs/desktop-app/16-einstellungen-rechnungsexport.png)
+
+Der Rechnungsexport erstellt ein ZIP-Archiv für Buchhaltung und Steuerberater.
+
+Enthalten:
+
+- CSV-Datei mit finalisierten Rechnungen
+- alle zugehörigen Rechnungs-PDFs
+- nur Rechnungen mit echter Rechnungsnummer
+
+Nicht enthalten:
+
+- Entwürfe
+- Rechnungen mit `in Vorbereitung`
+
+Der Export ist immer auf ein Jahr beschränkt. Das Jahr wird vor dem Export ausgewählt.
+
+## Benutzerverwaltung
+
+![Benutzerverwaltung](docs/desktop-app/18-einstellungen-benutzer.png)
+
+Die Benutzerverwaltung steuert Logins und leichte Rechte.
+
+Funktionen:
+
+- Benutzer anlegen
+- Benutzer aktiv/inaktiv setzen
+- Passwort ändern
+- Benutzer löschen
+- Rolle setzen
+- Recht `Einstellungen` setzen
+- Recht `App-Login erlauben` setzen
+- Standardmonteur für Android-Zeitbuchungen setzen
+
+Regeln:
+
+- Admin erhält alle Rechte.
+- Admin-Einstellungen können nur von Admins bearbeitet werden.
+- Benutzer ohne Recht `Einstellungen` sehen den Menüpunkt `Einstellungen` nicht.
+- Android-Login ist nur mit aktivem App-Recht möglich.
+
+## Fehlerbehebung
+
+### App startet nicht
+
+Prüfen:
+
+- Wurde der Installer vollständig ausgeführt?
+- Blockiert Windows SmartScreen?
+- Wurde die App nach dem Update neu gestartet?
+
+### Login schlägt fehl
+
+Prüfen:
+
+- Serveradresse korrekt?
+- Backend erreichbar?
+- `/api` am Ende vorhanden oder automatisch ergänzt?
+- Benutzer aktiv?
+- Passwort korrekt?
+
+### Einstellungen fehlen im Seitenmenü
+
+Der Benutzer besitzt kein Recht `Einstellungen`. Ein Admin kann dieses Recht in der Benutzerverwaltung aktivieren.
+
+### Update wird nicht installiert
+
+Prüfen:
+
+- Internetverbindung vorhanden?
+- Windows erlaubt das Starten des heruntergeladenen Installers?
+- Installer wurde nicht durch Virenschutz oder SmartScreen blockiert?
+
+### PDF wird nicht geöffnet
+
+Prüfen:
+
+- PDF-Speicherordner in `Einstellungen > PDFs` gesetzt?
+- Ordner existiert und ist beschreibbar?
+- Standard-PDF-Programm in Windows eingerichtet?
+
+### Backup kann nicht wiederhergestellt werden
+
+Prüfen:
+
+- Datei ist ein gültiges JSON-Backup aus BC-ERP.
+- Backup wurde vollständig hochgeladen.
+- Backend hat Schreibrechte auf Datenbank und Upload-Verzeichnisse.
+
+## Release-Hinweis
+
+Dieses Repository enthält nur öffentliche Desktop-Release-Artefakte und Dokumentation. Der Quellcode des Hauptprojekts liegt nicht in diesem Repository.