# 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

![Interfața de Scanare - Pasul 1](images/fg_scan_interface_step1.png)

### 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)

![Modal de Asignare la Cutii - Pasul 2](images/fg_scan_box_assignment_step2.png)

### 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