dolibarr.handybarcodescanner/README.md

# HANDYBARCODESCANNER FOR [DOLIBARR ERP & CRM](https://www.dolibarr.org)

Mobiler Barcode-Scanner für Dolibarr - optimiert für die Verwendung auf Smartphones.

## Features

Das Modul bietet drei Modi für die mobile Barcode-Erfassung:

### 1. Bestellmodus (Order)
- Produkt per Barcode scannen oder manuell suchen (Lupe-Button)
- Alle verfügbaren Lieferanten mit Einkaufspreisen werden angezeigt
- Günstigster Lieferant ist vorausgewählt
- Produkt wird zu einer lieferantenspezifischen Entwurfsbestellung hinzugefügt
- Bestellungen werden automatisch als "Direkt" erstellt (dauerhafte Direktbestellung pro Lieferant)
- Falls kein Lieferant zugewiesen: Manuelle Auswahl aller verfügbaren Lieferanten
- **Freitext-Positionen**: Plus-Button für Artikel ohne Produktstamm
- **Bestellübersicht**: Nach links swipen zeigt alle offenen Bestellungen
- **Zeilen bearbeiten**: Klick auf Bestellzeile öffnet Dialog zum Ändern/Löschen
- **Bestellungen löschen**: Entwürfe können direkt aus der Übersicht gelöscht werden

### 2. Shop-Modus
- Produkt per Barcode scannen
- Zeigt Links zu den Webshops der Lieferanten
- Schneller Zugriff auf Lieferanten-Onlineshops

### 3. Inventur-Modus
- Produkt per Barcode scannen
- Aktueller Lagerbestand wird angezeigt
- Neuen Bestand eingeben und mit Bestätigungsdialog speichern
- Lagerbewegungen werden korrekt protokolliert

### 4. Barcode-Druck
- **Druck-Button** auf Produktkarte oder via Produktsuche
- Barcode-Vorschau mit Produkt-Referenz, Barcode-Strichen und Barcode-Wert
- Code128-Format, optimiert für 24mm Etikettendrucker

**Zwei Druck-Optionen:**

#### Browser-Druck
- Standard Browser-Druckfunktion für Desktop-Drucker
- Unterstützt alle gängigen Drucker und PDF-Export

#### Brother PT-E560BT (Android App)
- **Native Android App** für direkten Bluetooth-Druck auf Brother P-touch E560BT
- Intent-basierte Integration: PWA startet App automatisch mit Barcode-Daten
- Druckt Barcode **längs auf 24mm TZe-Band** mit Produkt-Referenz (fett), Barcode und Wert
- Automatischer Halbschnitt zwischen Labels, Vollschnitt am Ende
- App verfügbar in `android-app/BrotherPrintHelper/`
- Installation: APK auf Android-Gerät installieren, PT-E560BT in Bluetooth-Settings paaren

## Barcode-Unterstützung

Das Modul sucht Barcodes in folgender Reihenfolge:
1. Produkt-Barcode (`llx_product.barcode`)
2. Lieferanten-Barcode (`llx_product_fournisseur_price.barcode`)
3. Produkt-Referenz (`llx_product.ref`)

Unterstützte Barcode-Formate (Quagga2):
- **Code 128** (empfohlen für alphanumerische Codes, höchste Priorität)
- **Code 39** (alphanumerisch, zweite Priorität)
- **EAN-13** (nur Ziffern, dritte Priorität)
- **EAN-8** (nur Ziffern, niedrigste Priorität)

**WICHTIG:** Reader-Reihenfolge optimiert für alphanumerische Codes! CODE128/CODE39 haben Vorrang vor EAN-Readern, um Fehlerkennungen bei Herstellercodes wie "P20260030" zu vermeiden.

## Installation

### Voraussetzungen
- Dolibarr ERP & CRM (Version 14.0 oder höher empfohlen)
- Aktiviertes Modul "Lieferanten" (Fournisseur/Supplier)
- Aktiviertes Modul "Lager" (Stock) für Inventur-Modus
- HTTPS-Verbindung (erforderlich für Kamerazugriff im Browser)

### Installation via Git

```bash
cd /path/to/dolibarr/htdocs/custom
git clone https://git.data-it-solution.de/data/dolibarr.handybarcodescanner.git handybarcodescanner
```

### Installation via ZIP

1. ZIP-Datei herunterladen
2. In Dolibarr: `Home > Setup > Modules > Deploy external module`
3. ZIP-Datei hochladen

### Aktivierung

1. Als Administrator in Dolibarr einloggen
2. Gehe zu `Setup > Modules`
3. Suche nach "HandyBarcodeScanner"
4. Modul aktivieren

## Konfiguration

Die Einstellungen sind unter `Setup > Modules > HandyBarcodeScanner > Settings` verfügbar:

### Allgemein
- **Bestellpräfix**: Präfix für automatisch erstellte Bestellungen (Standard: "Direktbestellung")
- **Standard-Lager**: Standard-Lager für Inventur-Bewegungen

### Aktivierte Modi
- **Bestellmodus aktivieren**: Ein/Aus
- **Shop-Modus aktivieren**: Ein/Aus
- **Inventur-Modus aktivieren**: Ein/Aus

### Feedback
- **Vibration aktivieren**: Vibriert bei erfolgreichem Scan (auf unterstützten Geräten)
- **Ton aktivieren**: Akustisches Signal bei erfolgreichem Scan

### QR-Code für mobilen Zugriff
Auf der Einstellungsseite wird ein QR-Code angezeigt, der mit dem Smartphone gescannt werden kann, um direkt zur Scanner-Seite zu gelangen.

## Berechtigungen

Das Modul definiert folgende Berechtigungen:

| Berechtigung | Beschreibung |
|-------------|--------------|
| `handybarcodescanner->use` | Scanner verwenden |
| `handybarcodescanner->order->create` | Bestellungen erstellen |
| `handybarcodescanner->inventory->write` | Lagerbestand ändern |

## Verwendung

Der Scanner ist im linken Menü unter **Produkte > Scanner** erreichbar.

### Moduswechsel ohne Unterbrechung
Die Modi (Bestellen/Shop/Inventur) können per Tab gewechselt werden, ohne dass die Kamera stoppt. Bereits gescannte Produkte werden im neuen Modus direkt angezeigt.

### Im mobilen Browser / PWA
1. QR-Code von der Admin-Seite scannen oder URL direkt eingeben
2. Kamerazugriff erlauben (HTTPS erforderlich!)
3. Gewünschten Modus wählen und "Scannen" tippen
4. Barcode vor die Kamera halten

### Gesten-Steuerung
- **Nach links swipen**: Bestellübersicht öffnen (Order-Mode)
- **Nach rechts swipen**: Barcode-Druck (Produktsuche öffnet sich)

## Technische Details

### Dateistruktur

```
handybarcodescanner/
├── admin/
│   ├── about.php
│   └── setup.php
├── ajax/
│   ├── addtoorder.php          # Produkt zu Bestellung hinzufügen
│   ├── addfreetextline.php     # Freitext-Position hinzufügen
│   ├── deleteorder.php         # Bestellung löschen
│   ├── findproduct.php         # Produkt per Barcode suchen
│   ├── getorders.php           # Bestellungen abrufen
│   ├── getorderlines.php       # Bestellzeilen abrufen
│   ├── getsuppliers.php        # Alle Lieferanten abrufen
│   ├── searchproduct.php       # Produktsuche
│   ├── updateorderline.php     # Bestellzeile bearbeiten
│   └── updatestock.php         # Lagerbestand aktualisieren
├── android-app/
│   └── BrotherPrintHelper/     # Native Android App für Brother PT-E560BT
│       ├── app/
│       │   ├── src/main/java/de/data_it_solution/brotherprinthelper/
│       │   │   └── MainActivity.kt
│       │   ├── libs/
│       │   │   └── brlmprinterkit-release.aar
│       │   └── build.gradle.kts
│       └── build.gradle.kts
├── core/modules/
│   └── modHandyBarcodeScanner.class.php
├── css/
│   └── scanner.css
├── js/
│   ├── barcodezoom.js.php      # Barcode-Zoom Feature
│   └── scanner.js              # Hauptlogik Scanner + PWA
├── langs/
│   ├── de_DE/handybarcodescanner.lang
│   └── en_US/handybarcodescanner.lang
├── lib/
│   └── handybarcodescanner.lib.php
├── pwa.php                     # PWA Hauptseite
├── sw.js                       # Service Worker für PWA
├── manifest.json               # PWA Manifest
└── handybarcodescannerindex.php
```

### Verwendete Bibliotheken
- [Quagga2](https://github.com/ericblade/quagga2) - Browser-basierte Barcode-Erkennung
- [JsBarcode](https://github.com/lindell/JsBarcode) - Barcode-Generierung für Druck
- [ZXing](https://github.com/zxing/zxing) - Barcode-Generierung in Android App

### PWA (Progressive Web App)

Das Modul ist als PWA konzipiert mit:
- **Service Worker** (`sw.js`) für Offline-Funktionalität und Performance
- **Web App Manifest** (`manifest.json`) für Installation auf Startbildschirm
- **localStorage** für persistente Einstellungen (letzte Lieferanten, letzte Bestellung)
- **Cache-Strategie**: Network-First für eigene Assets, Cache-First für CDN-Bibliotheken

**Browser-Kompatibilität:**
- Chrome/Edge auf Android: Vollständiger PWA-Standalone-Modus ✅
- Firefox auf Android: Nur Shortcuts, kein echter Standalone-Modus ⚠️
- Safari auf iOS: PWA-Unterstützung mit Einschränkungen

**Versionsverwaltung:** Bei Updates CACHE_NAME in `sw.js` + `?v=` in `pwa.php` synchron erhöhen!

### Brother PT-E560BT Android App

Native Kotlin-App für Bluetooth-Druck auf Brother P-touch E560BT:
- **SDK:** Brother Print SDK v4.x (brlmprinterkit-release.aar)
- **Intent-Schema:** `brotherprint://print?barcode=VALUE&ref=PRODUCTREF`
- **Features:**
  - Auto-Discovery von gepaartem Drucker
  - 90° Rotation für Längs-Druck auf 24mm TZe-Band
  - Produkt-Referenz (fett), Barcode-Strichen, Barcode-Wert
  - Erweiterte Error-Handling (SetLabelsizeError, NoCoverError, etc.)
- **Build:** Gradle 9.3.1, Kotlin 2.1.0, Android SDK 34

## Changelog

Siehe [ChangeLog.md](ChangeLog.md)

## Lizenz

### Hauptcode
GPLv3 oder (nach Wahl) jede spätere Version. Siehe Datei [COPYING](COPYING) für weitere Informationen.

### Dokumentation
Alle Texte und READMEs sind unter [GFDL](https://www.gnu.org/licenses/fdl-1.3.en.html) lizenziert.

## Autor

Eduard Wisch - [DATA IT-Solution](https://data-it-solution.de)

## Support

Bei Fragen oder Problemen:
- Issue erstellen: https://git.data-it-solution.de/data/dolibarr.handybarcodescanner/issues
- E-Mail: data@data-it-solution.de