HHA/app/ANALYSE.md

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