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/Artikelnummern in folgender Reihenfolge:
1. Produkt-Barcode (`llx_product.barcode`)
2. Lieferanten-Barcode (`llx_product_fournisseur_price.barcode`)
3. **Lieferanten-Artikelnummer** (`llx_product_fournisseur_price.ref_fourn`) ← **NEU ab v9.0**
4. Produkt-Referenz (`llx_product.ref`)

### Barcode-Formate (ZXing-JS, ab v8.3)

**Unterstützte Formate - wählbar per Dropdown:**
- **Code 128** - alphanumerisch (1D-Barcode)
- **QR-Code** - 2D-Matrix-Code
- **DataMatrix** - 2D-Matrix-Code

**Typ-Umschaltung ohne Kamera-Neustart:**
Der Barcode-Typ kann während des Scannens gewechselt werden. Die Kamera bleibt aktiv, nur der Decoder wird neu initialisiert. Die Auswahl wird persistent in localStorage gespeichert.

### OCR-Modus für Artikelnummern (ab v8.5, optimiert in v9.1)

**Für Etiketten OHNE Barcode:**
- Foto-basierte Texterkennung mit Tesseract.js
- Variable Ziffern-Anzahl (5-12 stellig) per Dropdown wählbar
- Erkennt **zusammenhängende** N-stellige Zahlen (z.B. 7-stellige Artikelnummer)
- Mehrere Treffer → Auswahl-Dialog
- Keine Treffer → Fallback auf manuelle Produktsuche

**Wichtig:** OCR erkennt nur **isolierte** Zahlenblöcke mit exakt N Ziffern. Keine Subsequenzen oder Zusammensetzungen aus längeren Zahlen!

## 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
- [ZXing-JS](https://github.com/zxing-js/library) v0.21.3 - Browser-basierte Barcode-Erkennung (1D + 2D)
- [Tesseract.js](https://github.com/naptha/tesseract.js) v5.1.0 - OCR (Optical Character Recognition) für Artikelnummern
- [JsBarcode](https://github.com/lindell/JsBarcode) v3.11.6 - 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 IMMER synchron erhöhen:
- `CACHE_NAME` in `sw.js` (z.B. `scanner-v9.1`)
- `?v=` Parameter in `pwa.php` für CSS und JS (z.B. `?v=91`)
- `$this->version` in `modHandyBarcodeScanner.class.php` (z.B. `9.1`)

**Aktuelle Version: 9.1**
- v9.1: OCR-Feature Bug-Fix (extractDigitSequences: nur zusammenhängende Zahlenblöcke)
- v9.0: OCR-Feature für Artikelnummern-Erkennung
- v8.3: ZXing-JS Integration (Code 128, QR, DataMatrix)

### 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