Phase 1k.1e — QL-Series Tape Geometry (QL820 62mm — Samla-Category)

[strausmann]

Kontext

Phase 1k.1a hat die TAPE_GEOMETRY-Tabelle in backend/app/schemas/tape_geometry.py eingeführt — aktuell mit 7 Einträgen, alle aus der PT-Series (Brother P-touch TZe-Tapes): 3.5mm, 6mm, 9mm, 12mm, 18mm, 24mm sowie die Samla-Sondergrößen.

Die QL-Series (Brother QL820NWB, DK-Endlos-Etiketten) wurde in Phase 1k.1a bewusst out-of-scope gelassen, weil sie nicht laminiert ist, nur 62mm Endlos-Default braucht und andere Druckmechanik nutzt (Endlos statt geschnitten).

Auslöser

Im Rahmen von Phase 1k.1b (Hangar API-Migration) wurde festgestellt: die Category Samla (heute aktiv im Hangar-Generator print_ql820.go als Samla-Stirntag + Samla-Deckel-Tag) braucht eine TAPE_GEOMETRY-Entry für QL820 62mm. Ohne Geometry-Entry:

• Hub rendert keine Preview für QL820-Templates
• LayoutEngine.render() schlägt mit UnsupportedTapeError fehl
• Hangar-Category Samla ist nicht mehr druckbar

Workaround in Phase 1k.1b: Samla wird strukturell migriert (template_id → content_type), nutzt aber weiter die existierenden Render-Pfade samla-stirntag-62mm/samla-deckel-62mm. Hub-Erweiterung um 62mm steht noch aus.

Faktencheck-Korrektur (2026-06-06)

Frühere Annahme: Möbel-Hauptschild AK läuft auf QL820 62mm. Das war falsch.

Verifikation gegen Live-YAML /docker/stacks/hangar-print-hub/config/hub-layouts.yaml auf hhdocker03:

Category	Live-Printer	Live-Tape
Möbel-Hauptschild AK	brother-p750w	hangar-furniture-18mm
Möbel-Hauptschild VK	brother-p750w	hangar-furniture-18mm
Samla-Deckel-Tag	brother-ql820nwb	samla-deckel-62mm
Samla-Stirntag	brother-ql820nwb	samla-stirntag-62mm

Möbel-Hauptschild AK ist nicht auf QL820 — der Cut für Phase 1k.1e betrifft nur die Samla-Category. AK wird in Phase 1k.1b normal auf qr_two_lines (P750W 18mm) migriert.

Zu klärende Fragen

1. Welche QL-DK-Größen sind relevant?

   • DK-22205 (62mm Endlos, weiß) — primärer Use-Case für Samla
   • DK-22113 (62mm Endlos, transparent)
   • DK-11201 (29×90mm Address)
   • DK-11209 (29×62mm Standard Address)
   • Weitere?

2. Endlos-Etiketten ContentType:

   • QL-Tapes haben keine feste Länge (im Gegensatz zu PT). qr_with_listing mit dynamischer Länge ist der naheliegende Use-Case für 62mm Endlos. Wie passt das in das tape-unabhängige Layout-Engine-Modell?
   • Braucht es einen neuen ContentType (z.B. qr_endless)?
   • Oder erweitern wir bestehende ContentTypes um endlos-Variante?
   • Heutige Samla-Templates: samla-stirntag-62mm (qr+text) und samla-deckel-62mm (qr+text+secondary[0]) — beide passen auf qr_two_lines bzw. qr_three_lines nach einer 62mm-Geometry-Erweiterung.

3. Druckbreite vs. physische Tape-Breite:

   • QL820 62mm hat ~58mm bedruckbare Höhe (Marge)
   • DPI: 300 (vs. PT-P750W 180dpi)
   • Endlos-Länge: variabel

4. Hangar-Integration:

   • Samla-Category wird in 1k.1b als unified Eintrag (Stirntag + Deckel) migriert
   • Eventuell neue Use-Cases: Adressetiketten, Versandlabel, größere QR-Codes (1k.1e Folge-Scope)

Implementation-Skizze

# backend/app/schemas/tape_geometry.py — Erweiterung

TAPE_GEOMETRY: dict[int, TapeGeometry] = {
    # ... bestehende PT-Series ...
    62: TapeGeometry(
        tape_mm=62,
        print_width_px=696,    # 58mm bei 300dpi
        dpi=300,
        printer_series="QL",
        is_endless=True,       # NEU
        # ...
    ),
}

Mögliche neue Felder im TapeGeometry:

• printer_series: Literal["PT", "QL"]
• is_endless: bool
• max_length_mm: int | None (für endlos = None, sonst feste Länge)

Abhängigkeiten

• Phase 1k.1b (Hangar API-Migration) muss gemerged sein
• Brother QL820NWB physisch verfügbar für Hardware-Smoke-Test
• DK-Tape-Sortiment im HomeLab vorhanden (DK-22205 für Samla bestätigt)

DoD (vorläufig)

• Spec für QL-Series Geometry erstellt (brainstorming + writing-plans)
• TapeGeometry-Schema um QL-Felder erweitert
• TAPE_GEOMETRY um mindestens 62mm DK-22205 ergänzt
• LayoutEngine.render() rendert QL-Use-Cases (mindestens qr_two_lines 62mm für Samla)
• Hardware-Smoke-Test auf QL820NWB bestanden
• Hangar example-layouts.yaml Samla-Category geht über LayoutEngine statt Legacy-Template-Pfad

Referenzen

• Phase 1k.1a Spec: docs/superpowers/specs/2026-06-05-phase-1k1-layout-engine-design.md
• Phase 1k.1b Spec (Hangar): https://git.strausmann.de/strausmann/hangar/-/merge_requests/152
• Phase 1k Umbrella: Phase 1k: Layout-Engine + Multi-Label-Batch + Online Template-Editor (Umbrella) #101
• Phase 1k.1a Hub-Implementation: PR feat(1k.1a): Hub Layout-Engine — replaces 21 templates with semantic engine #109 (merged + deployed 2026-06-06)

Priorität

Niedrig — Samla ist der einzige produktive QL820-Use-Case. In 1k.1b wird Samla strukturell auf content_type migriert, nutzt aber weiter den Legacy-Template-Pfad (samla-*-62mm). Hub-Geometry-Erweiterung blockiert nichts Akutes, aber ohne sie kann Samla nicht über LayoutEngine gerendert werden.