roa2web-service-auto/tasks/prd-bulk-upload-realtime-progress.md

# PRD: Bulk Upload - Progres Real-Time în Listă

## 1. Introducere

Sistemul actual de bulk upload afișează fișierele în lista de bonuri **doar după** ce procesarea OCR se finalizează. Utilizatorul nu poate vedea ce fișiere a încărcat și în ce stadiu se află fiecare. Această funcționalitate va afișa toate fișierele imediat după upload, direct în tabelul de bonuri, cu actualizare în timp real a statusului pe măsură ce sunt procesate.

### Context Dezvoltare

| Aspect | Valoare |
|--------|---------|
| **Branch** | `ralph/bulk-receipt-upload` (continuare branch existent) |
| **Bază** | Sistemul bulk upload implementat anterior (US-001 → US-013) |
| **NU crea branch nou** | Toate modificările se fac în branch-ul existent |

## 2. Obiective

### Obiectiv Principal
- Vizibilitate completă a tuturor fișierelor încărcate, de la momentul upload-ului până la finalizare

### Obiective Secundare
- Feedback vizual clar pentru progresul procesării
- Posibilitatea de a anula fișiere individuale sau întreg batch-ul
- Identificarea rapidă a fișierelor cu erori

### Metrici de Succes
- Utilizatorul vede fișierele în tabel în <2 secunde de la upload
- Status-ul se actualizează în timp real fără refresh manual
- Rata de abandon a bulk upload scade (utilizatorii înțeleg ce se întâmplă)

## 3. User Stories

### US-001: Afișare Fișiere Imediat După Upload
**Ca** utilizator care încarcă bonuri în bulk
**Vreau** să văd toate fișierele selectate în tabel imediat după upload
**Pentru că** vreau să știu că fișierele mele au fost primite și sunt în procesare

**Acceptance Criteria:**
- [ ] După drag-drop sau selectare fișiere, rândurile apar în tabel în <2 secunde
- [ ] Fiecare fișier are un rând propriu în tabelul de bonuri
- [ ] Rândurile sunt grupate în batch-ul corespunzător (BatchGroupHeader)
- [ ] Coloanele de date (Data, Sumă, Furnizor, Tip) afișează '-' pentru fișiere neprocesate
- [ ] Coloana "Fișier" afișează numele fișierului original
- [ ] Coloana "Status Procesare" afișează "În așteptare" (pending)
- [ ] npm run typecheck passes
- [ ] Verify in browser: upload 3 fișiere și confirmă că apar instant în tabel

### US-002: Actualizare Status în Timp Real
**Ca** utilizator
**Vreau** să văd statusul fiecărui fișier actualizându-se automat
**Pentru că** vreau să urmăresc progresul fără să dau refresh

**Acceptance Criteria:**
- [ ] Statusul se schimbă de la "În așteptare" → "Se procesează..." → "Procesat" / "Eroare"
- [ ] Tranziția status include animație fade subtilă (CSS transition 300ms)
- [ ] Badge-ul "Se procesează..." include spinner animat
- [ ] Când procesarea se termină cu succes, coloanele se populează cu date extrase (Data, Sumă, etc.)
- [ ] Când procesarea eșuează, coloana Status afișează "Eroare" cu tooltip pentru mesajul de eroare
- [ ] Rândul rămâne în aceeași poziție în grup (nu se mută)
- [ ] npm run typecheck passes
- [ ] Verify in browser: urmărește un fișier din pending → processing → completed

### US-003: Animație la Schimbarea Statusului
**Ca** utilizator
**Vreau** o indicație vizuală când un fișier își schimbă statusul
**Pentru că** vreau să observ ușor progresul când am multe fișiere

**Acceptance Criteria:**
- [ ] Badge-ul de status se schimbă cu CSS transition (opacity fade)
- [ ] Când trece la "Procesat", rândul primește un highlight verde subtil pentru 2s
- [ ] Când trece la "Eroare", rândul primește un highlight roșu subtil pentru 2s
- [ ] Animațiile folosesc design tokens (`--green-50`, `--red-50`)
- [ ] Animațiile nu sunt distragătoare (subtile, nu flashy)
- [ ] npm run typecheck passes
- [ ] Verify in browser: testează tranziția vizuală pentru success și error

### US-004: Cancel Fișier Individual
**Ca** utilizator
**Vreau** să pot anula procesarea unui singur fișier
**Pentru că** poate am încărcat din greșeală un fișier

**Acceptance Criteria:**
- [ ] Fișierele cu status "În așteptare" sau "Se procesează" au buton/icon Cancel (×)
- [ ] Click pe Cancel afișează confirmare: "Anulezi procesarea pentru {filename}?"
- [ ] După confirmare, fișierul este eliminat din coadă și dispare din tabel
- [ ] Fișierele deja procesate NU au buton Cancel (sunt bonuri valide)
- [ ] Fișierele cu eroare au buton Retry, nu Cancel
- [ ] Cancel individual nu afectează alte fișiere din batch
- [ ] npm run typecheck passes
- [ ] Verify in browser: anulează un fișier pending și confirmă că dispare

### US-005: Cancel Tot Batch-ul
**Ca** utilizator
**Vreau** să pot anula toate fișierele dintr-un batch
**Pentru că** poate am încărcat batch-ul greșit

**Acceptance Criteria:**
- [ ] BatchGroupHeader pentru batch-uri în procesare are buton "Anulează tot"
- [ ] Click pe "Anulează tot" afișează confirmare cu numărul de fișiere afectate
- [ ] Confirmarea menționează că fișierele deja procesate rămân ca bonuri
- [ ] După confirmare, toate fișierele pending/processing sunt eliminate
- [ ] Fișierele deja procesate (completed) rămân în sistem ca bonuri valide
- [ ] Dacă toate fișierele sunt completed/failed, butonul nu apare
- [ ] npm run typecheck passes
- [ ] Verify in browser: anulează un batch și confirmă că doar pending/processing dispar

### US-006: Checkbox Disabled pentru Fișiere în Procesare
**Ca** utilizator
**Vreau** să nu pot selecta fișierele în procesare pentru acțiuni bulk
**Pentru că** nu are sens să validez/șterg un fișier care nu e încă procesat

**Acceptance Criteria:**
- [ ] Checkbox-ul este disabled pentru rânduri cu status pending/processing
- [ ] Hover pe checkbox disabled afișează tooltip: "Fișierul se procesează"
- [ ] "Select All" nu include fișierele în procesare
- [ ] Acțiunile bulk (Validează, Șterge) funcționează doar pe fișiere completed/failed
- [ ] npm run typecheck passes
- [ ] Verify in browser: încearcă să selectezi un fișier pending - checkbox disabled

### US-007: Backend - Endpoint pentru Cancel Job
**Ca** sistem
**Vreau** un endpoint API pentru anularea job-urilor de procesare
**Pentru că** frontend-ul trebuie să poată cancela fișiere

**Acceptance Criteria:**
- [ ] POST /api/data-entry/bulk/cancel/{job_id} - anulează un job specific
- [ ] POST /api/data-entry/bulk/cancel-batch/{batch_id} - anulează tot batch-ul (pending/processing)
- [ ] Endpoint-urile returnează lista de job-uri anulate
- [ ] Job-urile cu status completed/failed nu pot fi anulate (return 400)
- [ ] Dacă receipt-ul a fost deja creat, nu se șterge (rămâne în sistem)
- [ ] Endpoint-urile actualizează status în job_queue la 'cancelled'
- [ ] npm run typecheck passes (Python)
- [ ] Testează cu curl: cancel job pending returnează 200

### US-008: Frontend - Integrare Store pentru Cancel
**Ca** dezvoltator
**Vreau** acțiuni în store pentru cancel
**Pentru că** componentele trebuie să poată apela cancel

**Acceptance Criteria:**
- [ ] batchProgressStore.cancelJob(jobId) - apelează endpoint cancel individual
- [ ] batchProgressStore.cancelBatch(batchId) - apelează endpoint cancel batch
- [ ] După cancel, job-ul dispare din Map-ul de jobs
- [ ] După cancel batch, toate job-urile pending/processing dispar
- [ ] Polling-ul continuă pentru job-urile rămase (completed)
- [ ] Erori la cancel sunt afișate utilizatorului (toast)
- [ ] npm run typecheck passes
- [ ] Verify in browser: cancel + verifică că store se actualizează

### US-009: Afișare Fișiere în Tabel - Componenta Row
**Ca** dezvoltator
**Vreau** să pot randa un rând pentru un job neprocesar încă
**Pentru că** trebuie să afișez fișierele înainte de a deveni Receipt-uri

**Acceptance Criteria:**
- [ ] Tabelul poate randa atât Receipt-uri cât și BatchJob-uri (pending files)
- [ ] Pentru BatchJob: afișează filename în coloana Fișier
- [ ] Pentru BatchJob: coloanele Data, Sumă, Furnizor, Tip afișează '-'
- [ ] Pentru BatchJob: ProcessingStatusCell afișează status corect
- [ ] Pentru BatchJob: acțiunile din meniu sunt disabled (doar Cancel disponibil)
- [ ] Stilul rândului indică vizual că e în procesare (ușor muted/opacity)
- [ ] npm run typecheck passes
- [ ] Verify in browser: rândul pentru job pending arată corect

### US-010: Sincronizare Job Status cu Receipt
**Ca** sistem
**Vreau** să asociez job-urile cu receipt-urile create
**Pentru că** când OCR termină, rândul trebuie să se transforme în receipt

**Acceptance Criteria:**
- [ ] Când OCR termină cu succes, job-ul primește receipt_id
- [ ] Frontend-ul detectează receipt_id și înlocuiește rândul de job cu receipt-ul real
- [ ] Coloanele se populează cu datele din receipt (Data, Sumă, Furnizor)
- [ ] Tranziția e smooth - nu dispare/reapare rândul
- [ ] Dacă OCR eșuează, job-ul rămâne cu status 'failed' și error_message
- [ ] npm run typecheck passes
- [ ] Verify in browser: urmărește un fișier cum devine receipt cu date populate

## 4. Cerințe Funcționale

1. **[REQ-001]** Sistemul trebuie să creeze rânduri vizuale în tabel imediat după upload, înainte de procesare OCR
2. **[REQ-002]** Fiecare fișier încărcat trebuie să aibă vizibil: nume fișier, status procesare, acțiune cancel
3. **[REQ-003]** Status-ul trebuie să se actualizeze în timp real via long-polling existent
4. **[REQ-004]** Utilizatorul poate anula fișiere individuale sau tot batch-ul
5. **[REQ-005]** Anularea afectează doar fișierele pending/processing, nu cele deja procesate
6. **[REQ-006]** Rândurile pentru fișiere neprocesate au coloane de date goale ('-')
7. **[REQ-007]** Checkbox-urile sunt disabled pentru fișiere în procesare
8. **[REQ-008]** Animațiile de tranziție folosesc design tokens CSS

## 5. Non-Goals (Ce NU facem)

- **NU** implementăm preview/thumbnail pentru fișiere - doar nume + status
- **NU** implementăm progress bar procentual per fișier - doar status discret
- **NU** implementăm reordonare/prioritizare a cozii de procesare
- **NU** implementăm pause/resume pentru procesare
- **NU** ștergem receipt-urile deja create când se anulează un batch
- **NU** permitem editarea fișierelor în timpul procesării

## 6. Considerații Tehnice

### Git Branch
- **Branch:** `ralph/bulk-receipt-upload` - **CONTINUĂ în acest branch**
- **NU crea branch nou** - această funcționalitate extinde bulk upload-ul existent
- Commit messages: `feat(bulk-upload-realtime): US-XXX - Descriere`

### Stack/Tehnologii
- **Frontend:** Vue 3, Pinia stores, PrimeVue components
- **Backend:** FastAPI, SQLite (data-entry module), job_queue table
- **Polling:** Long-polling existent în batchProgressStore

### Patterns de Urmat
- ProcessingStatusCell pentru afișare status (extinde pentru cancel)
- BatchGroupHeader pentru grupare (adaugă buton cancel all)
- batchProgressStore pentru state management (adaugă cancel actions)
- Design tokens din `docs/DESIGN_TOKENS.md` pentru culori/spacing

### Dependențe
- Sistemul de bulk upload existent (US-001 până la US-013 anterioare)
- Long-polling pentru status updates
- BatchJob model din backend

### Riscuri Tehnice
- **Race condition:** Job poate termina între request cancel și procesare - handle gracefully
- **Performance:** Multe rânduri în tabel cu polling - optimizează re-renders cu Vue keys
- **UX:** Rânduri care "dispar" pot fi confuze - animație clear pentru cancel

## 7. Considerații UI/UX

### Layout și Flow
```
┌─────────────────────────────────────────────────────────────────────┐
│ BatchGroupHeader: "Batch B-abc123" - 5 fișiere  [Anulează tot]      │
├─────────────────────────────────────────────────────────────────────┤
│ □ │ bon1.pdf     │ -       │ -      │ -    │ În așteptare    │ [×] │
│ □ │ bon2.pdf     │ -       │ -      │ -    │ Se procesează...│ [×] │
│ ☑ │ bon3.pdf     │ 15 Ian  │ 125.50 │ LIDL │ ✓ Procesat      │     │
│ □ │ bon4.pdf     │ -       │ -      │ -    │ ✗ Eroare        │ [↻] │
│ ☑ │ bon5.pdf     │ 15 Ian  │ 89.00  │ Mega │ ✓ Procesat      │     │
└─────────────────────────────────────────────────────────────────────┘
```

### Stări (loading, error, empty, success)
- **Pending:** Badge gri "În așteptare", checkbox disabled, buton Cancel
- **Processing:** Badge albastru cu spinner "Se procesează...", checkbox disabled, buton Cancel
- **Completed:** Badge verde "✓ Procesat", checkbox enabled, fără Cancel
- **Failed:** Badge roșu "✗ Eroare" cu tooltip, checkbox disabled, buton Retry
- **Cancelled:** Rândul dispare cu animație fade-out

### Accesibilitate
- Buton Cancel are aria-label descriptiv
- Tooltip-urile de eroare sunt accesibile cu keyboard
- Animațiile respectă `prefers-reduced-motion`

## 8. Success Metrics

- **Time to visibility:** Fișierele apar în tabel în <2s de la upload
- **Real-time accuracy:** Status-ul reflectă starea reală în <1s de la schimbare
- **Cancel success rate:** 100% din cancel-uri pentru pending jobs funcționează
- **User satisfaction:** Utilizatorii înțeleg ce se întâmplă cu fișierele lor

## 9. Open Questions

- [ ] Dacă utilizatorul navighează away și revine, cum se restaurează rândurile pentru jobs pending? (Probabil din localStorage + API call)
- [ ] Limită maximă de fișiere afișate simultan în tabel? (Performance consideration)
- [ ] Notificare sonoră/vizuală când tot batch-ul e procesat?

---

## Appendix: Ordine Implementare Recomandată

1. **US-007** - Backend endpoints pentru cancel (independent)
2. **US-008** - Store actions pentru cancel (depinde de US-007)
3. **US-009** - Componenta row pentru jobs (independent)
4. **US-001** - Afișare fișiere în tabel (depinde de US-009)
5. **US-002** - Actualizare status real-time (depinde de US-001)
6. **US-010** - Sincronizare job→receipt (depinde de US-002)
7. **US-003** - Animații tranziție (depinde de US-002)
8. **US-004** - Cancel individual (depinde de US-008)
9. **US-005** - Cancel batch (depinde de US-008)
10. **US-006** - Checkbox disabled (depinde de US-009)