quality_app/py_app/app/static/docs/fg_scan.md

Modulul FG Scan - Fluxul de Scanare Produse Finite

Prezentare generală

Modulul FG Scan (Finish Good Scan) este interfața de scanare în timp real pentru înregistrarea produselor finite prin punctele de control de calitate. Sistemul permite o înregistrare rapidă și validare automată a produselor cu capabilități avansate de urmărire și asignare la cutii de depozitare.

Descriere generală a sistemului

Fluxul de lucru se bazează pe scannarea codurilor de bare în ordine specifică, cu validări în timp real și înregistrare automată a datelor. Sistemul suportă:

• Înregistrarea rapidă a produselor scannate
• Validarea automată a calității prin coduri de defecte
• Urmărirea operatorilor care efectuează controalele
• Asignarea produselor la cutii de depozitare (opțional)
• Crearea și tiparirea etichetelor pentru cutii

---

1. Interfața de Scanare - Fluxul Principal

Structura Formularului

Formularul de scanare conține 5 câmpuri de intrare obligatorii care trebuie completate în ordine:

┌─────────────────────────────────┐
│ MODULUL FG SCAN - FORMULAR      │
├─────────────────────────────────┤
│ 1. Operator Code (OP)       ← Prima validare
│    ├─ Exemplu: OP001
│    └─ Format: OP + 2-3 caractere
│
│ 2. CP Code (Produs)         ← A doua validare
│    ├─ Exemplu: CP123456
│    └─ Format: CP + numere/litere
│
│ 3. OC1 Code (Control Op. 1) ← A treia validare
│    ├─ Exemplu: OC001
│    └─ Format: OC + numere
│
│ 4. OC2 Code (Control Op. 2) ← A patra validare
│    ├─ Exemplu: OC002
│    └─ Format: OC + numere
│
│ 5. Defect Code (3 cifre)    ← Trigger de submit
│    ├─ Exemplu: 000 (OK) sau 001 (Defect)
│    └─ Format: Exact 3 cifre
│
│ ☐ Enable Scan-to-Boxes      [Opțional]
└─────────────────────────────────┘

Descrierea Câmpurilor

Camp	Format	Descriere	Exemplu	Notă
Operator Code	OP + 2-3 caractere	Codul operatorului de calitate care scanează	OP001, OP123	Se salvează local după validare
CP Code	CP + numere/litere	Codul produsului finit	CP123456	Produsul trebuie să existe în bază
OC1 Code	OC + numere	Primul operator de control	OC001	Validație în bază de date
OC2 Code	OC + numere	Al doilea operator de control	OC002	Validație în bază de date
Defect Code	3 cifre exacte	Codul defectului (000=OK, 001-999=defect)	000, 001, 123	Trigger pentru submit automat

---

2. Etapele Detaliate de Scanare

Etapa 1: Introducerea Codului Operator

ACTION: Scannează sau introducă codul operator
INPUT:  OP001
VALIDARE: 
  ✓ Trebuie să înceapă cu "OP"
  ✓ Lungime: 4-6 caractere
  ✓ Se acceptă doar caractere alfanumerice
REZULTAT: 
  ✓ Acceptat - Focusul merge la CP Code
  ✗ Eroare - Mesaj roșu: "Please scan Quality Operator code (must start with OP)"
SALVARE: Codul se salvează local (localStorage) pentru utilizări viitoare

Etapa 2: Scanarea Codului Produs (CP)

ACTION: Scannează codul produsului finit
INPUT:  CP123456
VALIDARE:
  ✓ Trebuie să înceapă cu "CP"
  ✓ Produsul trebuie să existe în baza de date
  ✓ Se acceptă numere și litere după "CP"
REZULTAT:
  ✓ Acceptat - Focusul merge la OC1 Code
  ✗ Eroare - Mesaj roșu: "Please scan a valid CP"

Etapa 3: Scanarea Operatorului de Control 1 (OC1)

ACTION: Scannează primul operator de control
INPUT:  OC001
VALIDARE:
  ✓ Trebuie să înceapă cu "OC"
  ✓ Trebuie să fie valid în baza de date
  ✓ Diferit de OC2 (pot fi aceiași oameni)
REZULTAT:
  ✓ Acceptat - Focusul merge la OC2 Code
  ✗ Eroare - Mesaj roșu: "Please scan a valid OC (must start with OC)"

Etapa 4: Scanarea Operatorului de Control 2 (OC2)

ACTION: Scannează al doilea operator de control
INPUT:  OC002
VALIDARE:
  ✓ Trebuie să înceapă cu "OC"
  ✓ Trebuie să fie valid în baza de date
REZULTAT:
  ✓ Acceptat - Focusul merge la Defect Code
  ✗ Eroare - Mesaj roșu: "Please scan a valid OC (must start with OC)"

Etapa 5: Introducerea Codului de Defect

ACTION: Introduceți/scannați codul de defect (3 cifre)
INPUT:  000 (pentru OK) sau 001-999 (pentru defecte)
VALIDARE:
  ✓ Exact 3 cifre
  ✓ Numai caractere numerice
  ✓ Valori valide: 000 (OK) sau 001-999 (defect)
REZULTAT:
  ✓ Acceptat la 3 cifre - SUBMIT AUTOMAT
  ✗ Eroare - Mesaj roșu: "Defect code must be a 3-digit number (e.g., 000, 001, 123)"

Etapa 6: Înregistrare Automată și Feedback

ACTION: Sistemul finalizează scanarea automat
PROCES:
  1. Salvează datele în baza de date
  2. Afișează notificare de succes
  3. Resetează formularul (minus Operator Code)
  4. Focusul merge la CP Code pentru următoarea scanare

FEEDBACK UTILIZATOR:
  ✅ Notificare verde: "✅ Scan recorded successfully!"
  ⏱️  Durata: 4 secunde (apoi dispare)
  🔄 Formularul se resetează automat

---

3. Fluxul de Asignare la Cutii (Save to Box)

Condiții de Declanșare a Modalului

Modalul de asignare la cutie apare automat și obligatoriu atunci când sunt SIMULTAN îndeplinite:

1. ✅ Opțiunea "Enable Scan-to-Boxes" este BIFATĂ
2. ✅ Codul de defect este EXACT 000 (Produs fără defecte)
3. ✅ Scanarea s-a FINALIZAT cu SUCCES

IF (scanToBoxesEnabled == TRUE) AND (defectCode == "000") THEN
  SHOW box_assignment_modal
ELSE
  RELOAD page normally
END IF

Structura Modalului

┌────────────────────────────────────────┐
│  ASIGNARE PRODUS LA CUTIE             │
├────────────────────────────────────────┤
│ CP Code: CP123456                      │
│                                        │
│ Opțiuni:                              │
│  [🔲] Create New Box                   │
│  [📥] Scan Existing Box Label          │
│                                        │
│ Input: "Scan the printed label now..." │
│        [________________]              │
│                                        │
│  [Anulare]  [Salvare]                 │
└────────────────────────────────────────┘

Etapa 1: Deschiderea Modalului

TRIGGER: După scanarea cu defect code = 000
AFIȘARE:
  - Modalul se deschide centrat pe ecran
  - Se afișează codul produsului (CP123456)
  - Focusul este pe câmpul de input pentru cutie
  - Placeholder: "Scan the printed label now..."
OPȚIUNI:
  a) Create New Box - Creează o nouă cutie
  b) Scan Box - Scannează o cutie existentă

Etapa 2: Crearea Unei Noi Cutii

ACTION: Apasă butonul "Create New Box"
PROCES:
  1. Sistemul crează o nouă cutie în baza de date
  2. Generează automat un cod unic (ex: BOX12345)
  3. Conectează la serviciul QZ Tray
  4. Generează etichetă în format ZPL (Zebra)

ETICHETĂ GENERATĂ:
  ┌──────────────────┐
  │ Box: BOX12345    │
  │                  │
  │  ║│││┌─┐    │  │
  │  ║│ │ │ │    │  │  ← Cod de bare generat
  │  ║│ │ │ │    │  │
  │  ║││ │ │    │  │
  │  BOX12345         │
  └──────────────────┘

FORMAT: ZPL (Zebra Programming Language)
CONȚINUT:
  - Textul "Box: BOX12345"
  - Cod de bare 1D (CODE128 sau similar)
  - Copie text cod box pentru scanare manuală

Etapa 3: Tipărirea Automată a Etichetei

ACTION: Etichetă generată → Tipărire automată
CERINȚE SISTEM:
  ✓ QZ Tray instalat și activ
  ✓ Imprimantă configurată și conectată
  ✓ Hârtie de etichetă (de obicei 4x6 inch)

PROCES TIPĂRIRE:
  1. Conectare la QZ Tray
  2. Detectare imprimantă disponibilă
  3. Trimitere job tipărire în format ZPL
  4. Imprimantă primește și procesează comanda
  5. Se tipărește eticheta

FEEDBACK UTILIZATOR:
  ✅ Notificare: "✅ Box 12345 created and label printed!"
  ⏱️  Durata: 3-5 secunde
  📥 Câmpul de input devine activ pentru scannare etichetă
  Placeholder se schimbă în: "Scan the printed label now..."

Etapa 4: Scannarea Etichetei Tipărite

ACTION: Scannează eticheta nou tipărită
PROCES:
  1. Scaneaza codul de bare de pe etichetă
  2. Sistemul validează: BOX12345
  3. Asociază produsul (CP123456) la cutie (BOX12345)
  4. Setează status "Packed" pentru produs
  5. Salvează relația în baza de date

VALIDĂRI:
  ✓ Codul scanned trebuie să coincidă cu BOX generat
  ✓ Produsul nu trebuie să fie deja asignat
  ✓ Cutia trebuie să existe în baza de date

FEEDBACK UTILIZATOR:
  ✅ Notificare verde: "✅ CP123456 assigned to Box BOX12345!"

Etapa 5: Finalizare și Revenire

ACTION: După scannare validă a etichetei
PROCES:
  1. Modalul se închide automat
  2. Pagina se reîncarcă complet
  3. Se resetează formularul
  4. Se prepară pentru următoarea scanare

REZULTAT FINAL:
  ✅ Produs înregistrat în sistem
  ✅ Produs asignat la cutie
  ✅ Etichetă tipărită și validată
  🔄 Sistem gata pentru următoarea scanare

---

4. Situații Speciale și Comportament

Scenariul 1: Produs OK - Cu Asignare la Cutie ✅

SECVENȚĂ COMPLETĂ:
┌─────────────────────────────────────────────────┐
│ 1. Scannează OP001                → ✓ Valid    │
│ 2. Scannează CP123456             → ✓ Valid    │
│ 3. Scannează OC001                → ✓ Valid    │
│ 4. Scannează OC002                → ✓ Valid    │
│ 5. Introduceți 000                → ✓ Valid    │
│                                                 │
│    ✅ "Scan recorded successfully!"            │
│    🎬 MODAL APARE: "Scan-to-Boxes enabled"     │
│                                                 │
│ 6. Click "Create New Box"         → BOX12345   │
│    ✅ "Box created and label printed!"         │
│    🖨️  Etichetă tipărită                       │
│                                                 │
│ 7. Scannează eticheta BOX12345    → ✓ Valid    │
│    ✅ "CP123456 assigned to Box 12345!"        │
│                                                 │
│ 🔄 Pagina se reîncarcă                         │
│    → Gata pentru următoarea scanare            │
└─────────────────────────────────────────────────┘

Scenariul 2: Produs cu Defect - Fără Modal ⚠️

SECVENȚĂ CU DEFECT:
┌─────────────────────────────────────────────────┐
│ 1. Scannează OP001                → ✓ Valid    │
│ 2. Scannează CP789999             → ✓ Valid    │
│ 3. Scannează OC001                → ✓ Valid    │
│ 4. Scannează OC002                → ✓ Valid    │
│ 5. Introduceți 001                → ✓ Valid    │
│                                                 │
│    ✅ "Scan recorded successfully!"            │
│    ⚠️  Defect code detected                    │
│    ❌ NO BOX MODAL (porque defect ≠ 000)      │
│                                                 │
│ 🔄 Pagina se reîncarcă automat după 1s        │
│    → Produs înregistrat cu defect              │
│    → Fără asignare la cutie                    │
│    → Gata pentru următoarea scanare            │
└─────────────────────────────────────────────────┘

Scenariul 3: Eroare de Validare ❌

SECVENȚĂ CU EROARE:
┌─────────────────────────────────────────────────┐
│ 1. Scannează XX001                → ❌ EROARE  │
│    "Must start with OP"                        │
│    🔴 Mesajul apare în roșu                    │
│    👆 Focusul revine la Operator Code          │
│                                                 │
│ 2. Reîncercați scannarea          → ✓ Valid    │
│    Mesajul de eroare dispare                   │
│                                                 │
│ (Continuă fluxul normal...)                   │
└─────────────────────────────────────────────────┘

Scenariul 4: QZ Tray Inactiv - La Tipărire ❌

SITUAȚIE: Utilizatorul apasă "Create New Box" 
         dar QZ Tray nu este conectat

REZULTAT:
  ❌ Eroare: "QZ Tray not connected. 
              Please ensure QZ Tray is running."
  
  🔘 Butonul "Create New Box" devine inactiv
  
SOLUȚIE:
  1. Pornește serviciul QZ Tray pe computer
  2. Verifică conexiunea la imprimantă
  3. Reîncarcă pagina
  4. Încearcă din nou

---

5. Configurația - Opțiunea "Enable Scan-to-Boxes"

Activarea/Dezactivarea Funcției

UI ELEMENT:
┌────────────────────────────────┐
│ ☐ Enable Scan-to-Boxes         │
│   ← Click pentru a activa       │
└────────────────────────────────┘

Comportament Comparativ

Stare	Comportament	Rezultat
❌ DEZACTIVAT	După scanare, formular se resetează	Fără modal; Produs doar înregistrat
✅ ACTIVAT	După scanare cu defect=000, apare modal	Modal pentru asignare la cutie

Persistență și Salvare

COMPORTAMENT:
  1. Starea opțiunii este salvată LOCAL (în browser)
  2. Folosește localStorage pentru persistență
  3. Rămâne activă după reîncărcarea paginii
  4. Se resetează la ștergerea cache-ului

SETARE: localStorage.setItem('scan_to_boxes_enabled', true/false)

IMPLICAȚII:
  ✓ Fiecare utilizator poate avea preferințe diferite
  ✓ Preferințele se salvează per computer/browser
  ✗ Se pierd dacă se șterge localStorage

---

6. Validări în Timp Real

Mesajele de Eroare Înroșite

┌─────────────────────────────────────────────────┐
│ MESAJE DE VALIDARE - Display în Timp Real      │
├─────────────────────────────────────────────────┤
│ 🔴 Operator Code:                               │
│    "Please scan Quality Operator code            │
│     (must start with OP)"                       │
│                                                 │
│ 🔴 CP Code:                                     │
│    "Please scan a valid CP"                    │
│                                                 │
│ 🔴 OC1 Code:                                    │
│    "Please scan a valid OC                      │
│     (must start with OC)"                       │
│                                                 │
│ 🔴 OC2 Code:                                    │
│    "Please scan a valid OC                      │
│     (must start with OC)"                       │
│                                                 │
│ 🔴 Defect Code:                                 │
│    "Defect code must be a 3-digit number        │
│     (e.g., 000, 001, 123)"                      │
└─────────────────────────────────────────────────┘

Auto-Advance între Câmpuri

MECANISMUL DE AUTO-ADVANCE:
  1. Operator Code: După 4 caractere valide → Auto-advance la CP Code
  2. CP Code: După scanare validă → Auto-advance la OC1 Code
  3. OC1 Code: După scanare validă → Auto-advance la OC2 Code
  4. OC2 Code: După scanare validă → Auto-advance la Defect Code
  5. Defect Code: După 3 cifre valide → AUTO-SUBMIT FORMULAR

COMPORTAMENT:
  ✓ Crește viteza de lucru
  ✓ Eliminate nevoia de click manual
  ✓ Reduce erori de introducere
  ✓ Optimizat pentru scanere barcode

---

7. Salvare și Persistență de Date

Ce se Salvează Local

LOCALSTORAGE ITEMS:
  1. fg_scan_operator_code
     - Salvează: Codul operator valid
     - Scop: Reîncarcă codul la revenire pe pagină
     - Trigger: După validare OP Code
     - Durata: Persistent (până la ștergere manuală)

  2. scan_to_boxes_enabled
     - Salvează: TRUE/FALSE
     - Scop: Ține minte preferința utilizatorului
     - Trigger: La click bifă
     - Durata: Persistent (până la ștergere manuală)

  3. fg_scan_clear_after_submit
     - Salvează: TRUE (flag)
     - Scop: Semnalizează dacă să reseteze după reload
     - Trigger: Înainte de submit
     - Durata: Temporară (se șterge după reload)

Comportament După Reîncărcare

SCENARIUL: Utilizatorul reîncarcă pagina
REZULTAT:
  1. Se restaurează Operator Code din localStorage
  2. Se restaurează starea "Enable Scan-to-Boxes"
  3. Alte câmpuri rămân goale (din motive de securitate)
  4. Focusul merge pe CP Code
  5. Sistemul este gata pentru scanare

---

8. Coduri și Format Special

Coduri de Prefix Obligatorii

┌──────────────────────────────────────────┐
│ CODURI SPECIALE - Format Strict          │
├──────────────────────────────────────────┤
│ OP = Operator Code (Calitate)            │
│      Format: OP + 2-3 caractere          │
│      Ex: OP001, OP123, OPA01             │
│      Lungime totală: 4-6 caractere       │
│                                          │
│ CP = Cod Produs (Product Code)           │
│      Format: CP + numere/litere          │
│      Ex: CP123456, CP-ABC-999            │
│      Lungime variabilă (min 4)           │
│                                          │
│ OC = Operator Control (Calitate)         │
│      Format: OC + numere                 │
│      Ex: OC001, OC999                    │
│      Lungime: 5-6 caractere              │
│                                          │
│ 000 = Status OK (Fără defecte)           │
│ 001-999 = Coduri de defecte specifice    │
└──────────────────────────────────────────┘

Numerele de Cutie

GENERARE AUTOMATĂ:
  Format: BOX + numere incrementale
  Exemplu: BOX00001, BOX00002, BOX12345
  
ETICHETA TIPĂRITĂ:
  - Conținut: "Box: BOX12345"
  - Cod de bare: 1D barcode (scanabil)
  - Format: ZPL (Zebra Programming Language)

---

9. Tastele Rapid și Navigare

Comenzi Tastatură

Tasta	Funcție
Tab	Navigare între câmpuri (în ordine)
Enter	Avansare la câmpul următor (dacă valid)
Backspace	Ștergere caractere
Scan Barcode	Completează câmpul și avansează automat
Escape	Închide modalul (nu-l recomand)

Flux Recomandat

1. Scannez barcode operator
   ↓ (automat cu 4 char)
2. Scannez barcode produs
   ↓ (automat după validare)
3. Scannez barcode operator 1
   ↓ (automat după validare)
4. Scannez barcode operator 2
   ↓ (automat după validare)
5. Scannez/introduc cod defect (3 cifre)
   ↓ (automat la 3 cifre)
6. SUBMIT AUTOMAT
   ↓
7. [Dacă Enable Scan-to-Boxes] MODAL APARE
   └→ Asignare la cutie

---

10. Troubleshooting și Rezolvare Probleme

Problemă: "Scan not submitted"

Cauze:

• Operator Code nu începe cu OP
• CP Code nu începe cu CP
• OC1/OC2 Code nu încep cu OC
• Defect code nu are exact 3 cifre

Soluție:

1. Verificați formatul fiecărui cod
2. Asigurați-vă că codurile încep cu literele corecte
3. Pentru defect, introduceți EXACT 3 cifre (001, nu 1 sau 0001)
4. Resetați formularul și reîncercați

---

Problemă: "QZ Tray not connected"

Cauze:

• QZ Tray nu este instalat
• QZ Tray nu este activ/pornit
• Firewall blochează conexiunea

Soluție:

1. Descărcați și instalați QZ Tray de la qz.io
2. Porniți serviciul QZ Tray (din tasktray)
3. Verificați conexiunea la localhost:8383
4. Reîncărcați pagina
5. Încercați din nou "Create New Box"

---

Problemă: "No printers found"

Cauze:

• Nicio imprimantă conectată
• Imprimantă nu este configurată
• Driver-ul imprimantei este defect

Soluție:

1. Conectați imprimanta fizic (USB sau rețea)
2. Instalați driver-ii necesari
3. Configurați imprimanta în setările sistemului
4. Testați tipărirea din alt program
5. Reîncărcați pagina FG Scan
6. Încercați din nou

---

Problemă: "Defect code must be 3 digits"

Cauze:

• Introdusă mai puțin de 3 cifre (ex: 00, 1)
• Introdusă mai mult de 3 cifre (ex: 0000)
• Introduse caractere non-numerice

Soluție:

Introduceți EXACT 3 CIFRE NUMERICE:
  ✓ CORECT: 000, 001, 123, 999
  ✗ GREȘIT: 00, 1, 0001, 12a, defect

---

Problemă: Etichetele nu se tipăresc

Verificări:

1. QZ Tray conectat?           → Verificați status
2. Imprimanta selectată?       → Setări sistem
3. Hârtie în imprimantă?       → Reîncărcați hârtie
4. Driver corect?              → Reinstalați driver
5. Format ZPL acceptat?        → Imprimanta suportă ZPL?

---

11. Cerințe Sistem și Configurație

Hardware Necesar

✓ Computer/Server cu browser modern
✓ Imprimantă etichetă (cu suport ZPL de preferință)
✓ Scannere barcode (pentru eficiență)
✓ Conexiune rețea (pentru baza de date)

Software Necesar

✓ Browser: Chrome, Firefox, Edge (versiuni recente)
✓ QZ Tray: v2.2.0 sau mai nou (pentru tipărire)
✓ Java Runtime Environment (pentru QZ Tray)
✓ Driver imprimantă compatibil

Setări Browser

✓ JavaScript activat
✓ LocalStorage activat
✓ Pop-ups dezblocate pentru QZ Tray
✓ Certificate SSL valid (dacă HTTPS)

---

12. Informații Suplimentare

Integrare Bază de Date

TABELE IMPLICITE:
  1. fg_scans - Înregistrează scanări
  2. boxes - Stochează cutii create
  3. cp_to_box - Relații produs-cutie
  4. operators - Informații operatori
  5. products - Informații produse

Fluxul Datelor

INPUT (Barcode/Tastatură)
    ↓
VALIDARE (în client + server)
    ↓
SALVARE DB (fg_scans table)
    ↓
[IF Scan-to-Boxes AND defect=000]
    ├→ CREATE BOX (boxes table)
    ├→ PRINT LABEL (QZ Tray)
    ├→ SCAN LABEL (verficare)
    └→ CREATE RELATION (cp_to_box table)
    ↓
CONFIRMAȚIE (notificare utilizator)
    ↓
RESET & READY (pentru următoarea scanare)

---

13. Suport și Contact

Pentru probleme sau întrebări:

• Administrator Sistem: Contactați dept. IT
• Documentație QZ Tray: https://qz.io
• Report Bug: Contactați manager-ul modulului
• Training: Consultați alte pagini de ajutor din aplicație

---

Document: Ghid Utilizare FG Scan Module
Versiune: 1.0
Dată Actualizare: 4 Ianuarie 2026
Limbă: Română
Status: Activ