Skip to content

📍 Kiosk – Bins Flow

This page documents the Bins workflow in the Qt kiosk. It covers:

  • Listing bins with capacity / fill indicator
  • Filtering + sorting
  • Expanding a bin to load wines (aggregated by ref)
  • Selecting a wine line (radio button)
  • Navigation actions (Inventory, Movements, Create Material)
  • Refresh behaviour, caching, and missing-data controls

1. Overview

The Bins page is a touch-first operational view of storage bins. It shows:

  • Bin summary (qty + capacity bar + empty highlight)
  • Expandable bin cards that lazily load wine lines from backend
  • Multi-wine per bin (aggregated by ref)
  • Direct navigation into related operations:
  • Inventory page filtered by this bin
  • Movements page pre-filled with selected wine + bin
  • Material creation page

1.1 Key UX Characteristics

  • Bins are displayed as cards with:
  • Header (bin code + quick info)
  • Fill bar (empty / normal / full state)
  • Collapsible body (actions + wine table)
  • Wine lines inside a bin use radio selection (not row selection).
  • Wines are loaded on-demand (when card expands) and cached per bin.
  • Refresh can reload:
  • bin summary list
  • wines list for an individual bin

1.2 Backend Interaction (High Level)

sequenceDiagram
    participant UI as Qt Kiosk (Bins Page)
    participant API as FastAPI Client (api.*)
    participant BE as Backend (FastAPI)
    participant DB as MariaDB

    UI->>API: GET /bins/summary
    API->>BE: bins_summary()
    BE->>DB: query bin qty + capacity
    DB-->>BE: results
    BE-->>API: summary list
    API-->>UI: bins list

    UI->>API: GET /bins/{st_bin}/wines
    API->>BE: wines_in_bin(st_bin)
    BE->>DB: query stocks/materials in bin
    DB-->>BE: rows
    BE-->>API: wine lines
    API-->>UI: lines (aggregated by ref in UI)

Notes

  • Wine lines are aggregated client-side (_aggregate_by_ref(...)) so each ref appears once with summed qty.
  • Loading runs in background workers to keep UI responsive.

2. Functions (User Guide Style)

This section is control-by-control and includes missing-data controls and what the user sees.

2.1 Filter Input

Purpose: Narrow down the bin list by bin code substring.

User Action

  • Type into: “Filter bins (e.g. 02_02)…”

System Behavior

  • Filtering is live (on every change).
  • Filter is case/format tolerant (normalized string compare).
  • Only bins whose code contains the typed text remain visible.

Missing-Data Handling

  • Empty filter shows all bins (subject to “only empty” and sort controls).

2.2 Clear Button

Purpose: Reset filters and return to default view.

User Action

  • Press Clear.

System Behavior

  • Clears filter text.
  • Unchecks “Show only empty bins”.
  • Re-renders list.
  • Focus returns to the filter input.

2.3 “Show only empty bins” Checkbox

Purpose: Display only bins with no stock.

User Action

  • Check or uncheck Show only empty bins.

System Behavior

  • When enabled, UI only shows bins where is_empty == True (or qty == 0).
  • Updates status message with number of bins shown and count of empty bins.

2.4 Sort Dropdown

Purpose: Control bin ordering.

User Action

  • Choose a sort mode:

  • Bin (A→Z)

  • Bin (Z→A)
  • Qty (high→low)
  • Qty (low→high)
  • Fill % (high→low)
  • Fill % (low→high)

System Behavior

  • Reorders the bin list immediately.
  • Fill % is derived from qty / max_capa when capacity is available.

2.5 Bin Card (Tap to Expand / Collapse)

Each bin is displayed as a card. The header is tappable.

User Action

  • Tap the bin header (bin code row).

System Behavior

  • Expands (shows action buttons + wines table) or collapses.
  • When expanding:
  • If bin is empty: shows “Empty bin.” and no wine table rows.
  • If wines have not been loaded yet: starts loading wines.

Missing-Data Handling

  • If user taps while already loading wines for that bin, the card shows “Already loading…”
  • If a bin is empty, wines are never requested.

2.6 “Refresh wines” Button (inside a bin card)

Purpose: Force refresh of: - bin summary (qty/fill) - wines list for this bin

User Action

  • Expand a bin card
  • Press Refresh wines

System Behavior

  • If empty bin: remains “Empty bin.” and clears the table.
  • Otherwise:
  • Marks wines as “not loaded” (bypasses cache)
  • Triggers:
    • refresh of bin summaries
    • reload of wines for this bin
  • UI shows “Reloading…” while requests are in flight.

2.7 Wine Table (Radio Selection)

Inside an expanded bin card, wines are shown in a table with columns:

  • Select (radio)
  • Ref
  • Description
  • Year
  • Region
  • Qty

User Action

  • Select exactly one wine line using the radio button.

System Behavior

  • Radio buttons are the only selection mechanism (row selection is disabled).
  • First line is auto-selected when wines load (convenience).
  • Qty is displayed as integer (safe conversion from backend value).

Missing-Data Handling

  • If no wines exist, table remains empty and hint text explains the state.
  • If label thumbnails cannot be loaded, the row still works (thumbnail is optional).

2.8 “Open Full Inventory (filtered)” Button

Purpose: Open the Inventory page already filtered to this bin.

User Action

  • Expand a bin card
  • Press Open Full Inventory (filtered)

System Behavior

  • Navigates to the inventory page with parameter:
  • st_bin = <this bin>

Error Handling

  • If navigation fails, status shows: “Open inventory failed: …”

2.9 “Open Goods Movement (selected)” Button

Purpose: Jump directly into Movements for the chosen wine line in this bin.

User Action

  1. Expand a bin card
  2. Select a wine line via radio
  3. Press Open Goods Movement (selected)

System Behavior

  • Validates selection:
  • If no radio is selected → status warning: “Select a wine line first (radio button).”
  • If selection exists:
  • Uses AppShell standard navigation:
    • AppShell.open_movements_prefill(ref, st_bin)
  • Ref comes from the selected radio’s property("ref").
  • Bin comes from the card bin code.

Fallback Behavior

  • If shell cannot be found (should not happen if wired correctly), it falls back to opening Movements without prefill.

2.10 “Create Material” Button

Purpose: Open Material Master in create mode.

User Action

  • Expand a bin card
  • Press Create Material

System Behavior

  • Navigates to Materials page with:
  • mode="create"

Error Handling

  • If navigation fails, status shows: “Open materials failed: …”

3. Operational Notes (for maintainers)

3.1 Background Workers (Responsiveness)

  • Loading bins and wines uses background workers (thread pool).
  • UI remains responsive during network calls.

3.2 Caching & In-flight Protection

  • Wines are cached per bin in wines_cache.
  • In-flight requests tracked in _wines_inflight to prevent duplicate loads.
  • “Refresh wines” bypasses cache by setting wines_loaded = False and evicting cache entry.

3.3 Multi-wine per Bin

  • Backend may return multiple rows per ref/material.
  • UI aggregates by ref so the operator sees one line per wine.

This document defines the authoritative behaviour of the Bins page in wine_platform.