📦 Kiosk – Material Master Flow¶

This page documents the Material Master workflow in the Qt kiosk, including:

Create new material
Edit existing material
Display material details
Label capture
OCR integration (Google Vision + OpenAI)
Mapping popup logic
Backend validation & persistence

1. Overview¶

A Material represents a wine definition in the system.

It is independent from stock quantity. Stock records reference materials, but materials can exist without stock.

The Material Master page supports:

Create
Edit
Display
Label capture via camera
Structured OCR extraction
Field mapping confirmation

1.1 Responsibilities¶

Layer	Responsibility
Qt Kiosk	Collect input, show OCR popup, validate basic fields
FastAPI	Validate payloads, route to service layer
Service Layer	Enforce business rules, persist data
MariaDB	Store materials and related references
Google Vision	Raw OCR text extraction
OpenAI	Structured field extraction from OCR text

2. Material Lifecycle¶

2.1 Create Material Flow¶

sequenceDiagram
    participant UI
    participant API
    participant Service
    participant DB

    UI->>API: POST /materials
    API->>Service: create_material()
    Service->>DB: insert material row
    DB-->>Service: commit
    Service-->>API: success
    API-->>UI: 200 OK

Validation Before Create¶

UI blocks submission if: - Ref missing or invalid - Description empty - Storage bin invalid - Duplicate ref detected (backend enforced)

Backend enforces: - Unique ref constraint - Valid st_bin reference - Required fields integrity

2.2 Edit Material Flow¶

sequenceDiagram
    participant UI
    participant API
    participant Service
    participant DB

    UI->>API: PUT /materials/{ref}
    API->>Service: update_material()
    Service->>DB: update row
    DB-->>Service: commit
    Service-->>API: success
    API-->>UI: 200 OK

Behavior¶

Editing preserves label filename unless replaced.
Ref is immutable once created.
Validation identical to create.

3. Label Capture & OCR¶

Material page integrates camera capture via get_label.py.

3.1 Label Capture Flow¶

sequenceDiagram
    participant UI
    participant Camera
    participant FS as FileSystem
    participant API

    UI->>Camera: capture frame
    Camera-->>UI: image frame
    UI->>FS: save NNNN_label.jpg
    UI->>API: upload image for OCR

Image stored in LABEL_PICTURES_DIR
Filename format: incremental prefix + suffix
DB stores filename only (not binary)

3.2 OCR Processing Flow (Dedicated Diagram)¶

sequenceDiagram
    participant UI
    participant API
    participant Google as Google Vision
    participant OpenAI
    participant DB

    UI->>API: POST /label/ocr (image)
    API->>Google: extract raw text
    Google-->>API: OCR text
    API->>OpenAI: structure fields (JSON extraction)
    OpenAI-->>API: structured fields
    API-->>UI: OCR result payload
    UI->>UI: show mapping popup
    UI->>API: confirm selected fields
    API->>DB: update material fields

After structured OCR is returned:

Scrollable (touch optimized)
One row per detected field
Columns:
Field name
Extracted value
Checkbox (apply)
Discard option
Tap-to-expand raw OCR text
Larger line spacing for readability

User Options¶

User may: - Accept selected fields - Discard unwanted fields - Manually adjust values before saving

Validation Rules¶

Ref cannot be overwritten if already existing.
Year must be numeric.
Region free text allowed.
Empty values ignored.

5. Display Mode¶

When browsing existing material:

All fields read-only until Edit pressed.
Label image displayed (scaled).
No OCR triggered automatically.

6. Error Handling & Safeguards¶

6.1 Client-side¶

Blocks empty required fields.
Prevents posting without ref.
Disables save during active worker thread.

6.2 Backend¶

May reject: - Duplicate ref - Invalid bin - Invalid year - Malformed payload

UI displays error without clearing current form.

7. Operational Guarantees¶

Materials are independent from stock.
OCR never auto-commits changes.
User confirmation required before DB update.
Label images are persistent and not deleted automatically.
Create/Edit operations are transactional.

This document defines the authoritative behavior of the Material Master page, including OCR integration with Google Vision and OpenAI structured extraction.