# HHA Lua Workflow Analyse

## Überblick

Die analysierten Lua-Skripte implementieren einen umfangreichen Logistik-Workflow für die Hamburger Hochbahn (HHA). Die App verwaltet den Transport und die Zustandsänderungen verschiedener Objekte zwischen verschiedenen Stationen.

## Architektur der Lua-App

### Dateistruktur
- `hha_mainscript.lua` - Initialisierung und Barcode-Handling
- `hha_main.lua` - Hauptlogik mit UI und State-Machine
- `hha_db_migration_V0_initial.lua` - Datenbank-Schema

### UI-Framework
Die App verwendet ein proprietäres UI-Framework (ASUI) mit folgenden Komponenten:
- ASUIStackLayout - Layout-Container
- ASUILabel - Textanzeige
- ASUIButton - Schaltflächen
- ASUIScrollView - Scrollbare Bereiche
- ASUIPerfListViewM - Performante Listen
- ASUIBoxView / ASUIRelativeLayout - Container

## Objekt-Typen

### 1. Geldkassetten (GK)
- **Typ-ID**: 3
- **Codes**: MEKxxx, BEKxxx
- **Subtypen**: meka, mekb, mekc, mekd, beka, bekb, bekc, bekd
- **Workflow**: Lager → Fahrzeug → Station → Fahrscheinautomat → Geldinstitut

### 2. HP Patronen (HP)
- **Typ-ID**: 4
- **Codes**: HOPxxx, H1Pxxx, H2Pxxx, H3Pxxx
- **Subtypen**: hp1a, hp1b, hp1c, hp2a, hp2b, hp2c, hp3a, hp3b, hp3c
- **Workflow**: Lager → Fahrzeug → Fahrscheinautomat

### 3. Fahrkartenrollen (FR)
- **Typ-ID**: 7
- **Codes**: FRxxx
- **Subtypen**: fra
- **Workflow**: Lager → Fahrzeug → Fahrscheinautomat

### 4. Safebags (SB)
- **Typ-ID**: 5
- **Workflow**: Versorgungsstelle → Geldinstitut

### 5. Abfallbehälter (ABS)
- **Typ-ID**: 9
- **Workflow**: Versorgungsstelle → Dienststelle

### 6. Container (CNTR)
- **Typ-ID**: ?
- **Subtypen**: cntra (Geldinstitut), cntrb (Dienststelle)
- **Workflow**: Sammlung mehrerer Objekte

## Zustände (States)

### Hauptzustände
```
unknown → to_delivery → delivery → station → in_fa
                                            ↓
                    ┌───────────────────────┼───────────────────────┐
                    ↓                       ↓                       ↓
                 ret_gi                 ret_fail                 ret_ds
                    ↓                       ↓                       ↓
               ret_gi_fzg              ret_fail_fzg              ret_ds_fzg
                    ↓                       ↓                       ↓
                fin_gi                ret_fail_stk              ret_ds_stk
                                            ↓                       ↓
                                      fin_ds_fail                fin_ds
```

### Zustandsbeschreibungen

| State | Beschreibung | Farbe |
|-------|-------------|-------|
| `unknown` | Unbekannt/Neu | Weiß |
| `to_delivery` | Zum Fahrzeug | Grau |
| `delivery` | Im Fahrzeug | Grau |
| `station` | An Station | Gelb |
| `in_fa` | Im Fahrscheinautomat | Grün |
| `in_vs` | In Versorgungsstelle | Gelb |
| `ret_fail` | Fehlerhaft zur Dienststelle | Rot |
| `ret_fail_fzg` | Fehlerhaft im Fahrzeug | Rot |
| `ret_fail_stk` | Fehlerhaft in Dienststelle | Rot |
| `ret_gi` | Zum Geldinstitut | Hellblau |
| `ret_gi_fzg` | Zum Geldinstitut (Fzg) | Hellblau |
| `ret_gi_stk` | Zum Geldinstitut (Stk) | Hellblau |
| `fin_gi` | Abgeschlossen im Geldinstitut | Blau |
| `ret_ds` | Zur Dienststelle | Hellblau |
| `ret_ds_fzg` | Zur Dienststelle (Fzg) | Hellblau |
| `ret_ds_stk` | Zur Dienststelle (Stk) | Hellblau |
| `ret_ds_err` | Fehlerhaft zur Dienststelle | Hellblau |
| `fin_ds` | Abgeschlossen in Dienststelle | Blau |
| `fin_ds_fail` | Fehlerhaft abgeschlossen | Blau |
| `fin_ds_err` | Fehlerhaft abgeschlossen | Blau |
| `hdl` | Handel | Grau |
| `ret_ds_empty` | Leer zur Dienststelle | Hellblau |

## Tour-Stationen

### Stationstypen

| Type | Beschreibung | Icon |
|------|-------------|------|
| `stock_start` | Lager - Beladung | Lager |
| `stock` | Lager | Lager |
| `stock_end` | Lager - Rückgabe | Lager |
| `start` | Dienststelle - Start | Dienststelle |
| `end` | Dienststelle - Ende | Dienststelle |
| `st` | Haltestelle | Haltestelle |
| `hls` | Hochbahnstation | HLS |
| `fsa` | Fahrscheinautomat | FSA |
| `vs` | Versorgungsstelle | VS |
| `gi` | Geldinstitut | Bank |
| `veh_start` | Fahrzeug - Beladung | Fahrzeug |
| `veh` | Fahrzeug | Fahrzeug |
| `veh_bulk` | Fahrzeug - Massenladung | Fahrzeug |
| `veh_vs` | Fahrzeug - Versorgung | Fahrzeug |
| `veh_end` | Fahrzeug - Entladung | Fahrzeug |

### Seiten (Pages)
Jede Tour hat mehrere Seiten, die bestimmte Aktionen definieren:
- **Page-ID**: Eindeutige Identifikation
- **Code**: Barcode zum Aktivieren der Seite
- **Label**: Anzeigename
- **Pickup**: Objekte, die aufgenommen werden sollen
- **Swap**: Objekte, die ausgetauscht werden sollen

## State Machines

### 1. Stock Start State Machine
```
unknown → to_delivery (Auf Fahrzeug laden)
fin_gi_tmp → ret_gi (Rückgabe an Geldinstitut)
```

### 2. Vehicle Start State Machine
```
to_delivery → delivery (Bestätigung Ladung)
ret_gi → ret_gi_fzg (Übernahme vom Geldinstitut)
```

### 3. Vehicle State Machine
```
delivery → station (An Haltestelle ausgeben)
ret_fail → ret_fail_fzg (Fehlerhafte übernehmen)
ret_gi → ret_gi_fzg (Geldinstitut-Objekte übernehmen)
ret_ds → ret_ds_fzg (Dienststellen-Objekte übernehmen)
station → delivery (Rücknahme)
in_fa → hdl (Handel)
```

### 4. FSA (Fahrscheinautomat) State Machine

#### Geldkassette (GK)
```
station → in_fa (Einbau)
in_fa → ret_fail (Fehlerhaft ausbauen)
unknown → ret_gi (Neue unbekannte Kassette)
```

#### HP Patrone
```
station → in_fa (Einbau)
in_fa → station (Ausbau)
unknown → ret_ds (Neue unbekannte Patrone)
```

#### Fahrkartenrolle
```
station → in_fa (Einbau)
in_fa → station (Ausbau)
```

### 5. Versorgungsstelle (VS) State Machine
```
Container Type A (cntra):
  - SB (Safebag) in_vs → ret_gi
  
Container Type B (cntrb):
  - ABS (Abfall) in_vs → ret_ds

Container Barcode:
  - cntra → Container A aktivieren
  - cntrb → Container B aktivieren
```

### 6. Geldinstitut (GI) State Machine
```
ret_gi_fzg → fin_gi (Übergabe an Bank)
unknown → ret_ds_empty (Leere Kassette)
```

### 7. Vehicle End State Machine
```
ret_fail_fzg → ret_fail_stk
ret_ds_fzg → ret_ds_stk
delivery → ret_ds_stk
ret_ds_empty → ret_ds_stk
ret_gi_fzg → ret_gi_stk
```

### 8. Stock End State Machine
```
ret_fail_stk → fin_ds_fail
ret_ds_stk → fin_ds
ret_ds_err → fin_ds_err
ret_gi_stk → fin_gi_tmp
```

## API-Endpunkte

### Initialisierung
```
GET /hha?init={"update":<version>, "imei":<imei>}
```

### Status-Update
```
GET /hha?set_obj_state={"obj":[...], "imei":<imei>}
```

### Tour abschließen
```
GET /hha?fin_tour={"id":<tour_id>, "time":<timestamp>, "imei":<imei>}
```

### Neues Objekt
```
GET /hha?new_obj={"type":<type>, "man":true, "code":<code>, ...}
```

### Quittung
```
GET /hha?new_receipt={"data":<barcode>, "time":<timestamp>, ...}
```

### Neuer Safebag
```
GET /hha?new_safebag={"code":<code>, "time":<timestamp>, ...}
```

## Datenbank-Schema

### Tabellen

#### tour
- id, job_id, tour_id, version, state, type, sort
- loc_id, loc_code, loc_code2, rem, menu, modified, del_code

#### object
- id, object_id, type, version, loc_id, code, rem, state, subtype
- origin, manual, last_modified

#### location
- id, location_id, version, name, street, num, zip, city, lat, long, rem

#### page
- id, tour_id, page_number, page_id, type, code, label

#### page_swap_count / page_pickup_count
- id, tour_id, page_id, object_type, object_count

#### sendqueue
- id, url (Base64-kodiert)

#### receipt
- id, code

#### container_objects
- id, container_id, type, object_id

## Besonderheiten

### Counter-Labels
Die App zeigt Zähler für verschiedene Objekttypen an:
- **MEK**: Münzgeldkassette
- **BEK**: Bargeldentnahmekassette
- **H1, H2, H3**: HP Patronen
- **P**: Fahrkartenrolle
- **SB**: Safebag
- **ABS**: Abfallbehälter

### Beladezähler
- SST: Sonder-Sonder-Tour
- CR: Collection-Route
- HADAG: Fährverbindung

### Quittungen
Für Geldkassetten müssen Quittungen gescannt werden:
- 2D-Barcode enthält: FA-#, GK-#, Betrag, Datum, Zeit
- Keine Quittung = Warnhinweis

### Manueller Modus
- Neue Objekte können manuell angelegt werden
- Server-Validierung des Barcodes
- Automatische Typ-Erkennung über Präfix

### Container-Logik
- Container werden über Barcode aktiviert
- Mehrere Objekte können einem Container zugeordnet werden
- Container-Abschluss überträgt Status auf alle enthaltenen Objekte

## Offline-Verhalten

1. **Daten werden lokal gespeichert** (SQLite)
2. **API-Aufrufe werden in Queue eingereiht**
3. **Automatische Synchronisation** bei Verbindung
4. **Konfliktauflösung** über Versionsnummern

## Synchronisation

### Trigger
- App-Start
- Manueller Refresh
- Intervall (60 Sekunden)
- Tour-Abschluss

### Daten
- Metadaten (Objekttypen)
- Standorte
- Objekte
- Jobs & Touren
- Page-Counts

## Sicherheit

- Geräte-Authentifizierung über IMEI
- Keine Passwörter im Code
- HTTPS für API-Kommunikation
- Lokale Daten verschlüsselt (SQLite)

## Flutter-Implementierung

### Architektur-Mapping

| Lua | Flutter |
|-----|---------|
| ASUIStackLayout | Column/Row |
| ASUILabel | Text |
| ASUIButton | ElevatedButton |
| ASUIScrollView | SingleChildScrollView |
| database:Query | Repository Pattern |
| BarcodeScanned | MobileScanner |
| State Machine | BLoC Pattern |

### UI-Vergleich

| Lua-UI | Flutter-UI |
|--------|-----------|
| Hintergrund #220220220 | Colors.grey.shade200 |
| HHA Rot | Color(0xFFE3001B) |
| Grüner Header #188230165 | Color(0xFFBCA6A5) |
| Status-Farben | ObjectStateInfo.getColorForState |

### State-Management

Die komplexen Lua-State-Machines wurden in BLoC-Pattern überführt:
- `ScanBloc` verwaltet Barcode-Scanning
- `TourBloc` verwaltet Touren und Synchronisation
- Zustandsübergänge sind explizit und testbar

### Vorteile der Flutter-Implementierung

1. **Type Safety**: Dart's Typisierung verhindert Laufzeitfehler
2. **Hot Reload**: Schnellere Entwicklung
3. **Moderne UI**: Material Design 3, Animationen
4. **Wartbarkeit**: Klare Architektur, Trennung von Concerns
5. **Testbarkeit**: Unit-Tests für Business-Logik
6. **Offline-First**: SQFlite mit Repository-Pattern
7. **State Management**: BLoC für vorhersagbare Zustände

## Fazit

Die Lua-App implementiert einen ausgereiften, komplexen Workflow für die Logistik der Hamburger Hochbahn. Die Flutter-Neuimplementierung behält die komplette fachliche Logik bei, verbessert jedoch:
- Architektur und Wartbarkeit
- UI/UX mit modernem Design
- Offline-Fähigkeiten
- Testbarkeit und Qualität
- Zukunftssicherheit und Erweiterbarkeit