roa2web-service-auto/tasks/prd-bulk-receipt-upload.md

PRD: Bulk Receipt Upload & Auto-Processing

1. Introducere

Sistemul actual permite upload-ul și procesarea unui singur bon la un moment dat, cu intervenție manuală la editare/salvare. Această funcționalitate adaugă o pagină separată pentru upload multiple bonuri (PDF/PNG/JPG) care sunt procesate automat prin OCR și salvate direct în baza de date, fără intervenție manuală.

Context tehnic: Există deja infrastructura de job queue (SQLite) și worker pool pentru procesare paralelă OCR. Această funcționalitate va extinde sistemul existent.

2. Obiective

Obiectiv Principal

• Permiterea upload-ului bulk de bonuri (10-50 fișiere) cu procesare automată end-to-end

Obiective Secundare

• Reducerea timpului de introducere date cu 90%+ pentru batch-uri mari
• Vizibilitate în timp real asupra progresului procesării
• Separare clară între flow-ul manual (editare) și automat (bulk)

Metrici de Succes

• Timp mediu per bon < 10 secunde (vs. 2-3 minute manual)
• Rata de succes OCR > 80% (bonuri procesate fără erori)
• Upload batch 50 bonuri în < 10 minute

3. User Stories

US-001: Upload Multiple Fișiere

Ca utilizator data-entry Vreau să selectez/trag multiple fișiere (PDF/PNG/JPG) într-o zonă de upload Pentru că vreau să procesez un lot întreg de bonuri dintr-o dată

Acceptance Criteria:

• Drag & drop zone acceptă multiple fișiere simultan
• Click pe zonă deschide file picker cu multi-select activat
• Fișierele acceptate: PDF, PNG, JPG (max 10MB/fișier)
• Fișierele invalide sunt ignorate cu mesaj de avertizare
• Lista fișierelor selectate apare sub zona de upload
• Buton "Șterge" per fișier pentru eliminare din batch
• npm run typecheck passes
• Verify in browser that files appear in list after selection
• CSS: Drop zone folosește var(--surface-card) background, var(--surface-border) border
• CSS: Drop zone hover/active folosește var(--blue-50) background
• CSS: Spacing între elemente folosește tokens (--space-md, --space-lg)
• CSS: Testează în dark mode - drop zone vizibilă și contrastantă

US-002: Vizualizare Batch Înainte de Submit

Ca utilizator Vreau să văd lista fișierelor selectate cu preview Pentru că vreau să verific că am selectat fișierele corecte înainte de procesare

Acceptance Criteria:

• Lista arată: thumbnail (pentru imagini), nume fișier, mărime
• Pentru PDF-uri se arată icon generic PDF
• Counter total: "X fișiere selectate (Y MB)"
• Buton "Golește lista" pentru resetare completă
• Buton "Adaugă fișiere" pentru a adăuga la selecție existentă
• npm run typecheck passes
• Verify in browser that thumbnails render correctly
• CSS: Lista folosește pattern .card din cards.css
• CSS: Thumbnail cu border-radius: var(--radius-md)
• CSS: File size text cu color: var(--color-text-secondary), font-size: var(--text-sm)
• CSS: Butoane folosesc clasele .btn .btn-secondary și .btn .btn-primary
• CSS: Testează în dark mode - thumbnails și text lizibile

US-003: Submit Batch pentru Procesare

Ca utilizator Vreau să trimit toate fișierele pentru procesare cu un singur click Pentru că vreau să declanșez procesarea automată a întregului lot

Acceptance Criteria:

• Buton "Procesează X bonuri" submit-ează batch-ul
• La submit, toate fișierele se uploadează și se creează câte un OCR job per fișier
• După submit, UI-ul trece în modul "progres" (nu mai permite adăugare fișiere)
• Dacă un upload individual eșuează (network error), se reîncearcă automat (max 3 retry)
• npm run typecheck passes
• Verify in browser that submit disables file addition

US-004: Progres Real-Time per Fișier

Ca utilizator Vreau să văd progresul fiecărui fișier în timp real Pentru că vreau să știu câte bonuri s-au procesat și câte mai sunt în așteptare

Acceptance Criteria:

• Fiecare fișier din listă arată status: "În așteptare" / "Se procesează..." / "Completat" / "Eroare"
• Status vizual diferențiat: badge/icon color-coded (gri/albastru/verde/roșu)
• La completare se arată confidence score overall (ex: "87% confidence")
• Progress bar global: "15/50 procesate"
• Timpul estimat rămas bazat pe average processing time
• npm run typecheck passes
• Verify in browser that status updates in real-time without page refresh
• CSS: Status badges folosesc culorile din tabel (vezi secțiunea 6):
  • Pending: background: var(--surface-hover), color: var(--color-text-secondary)
  • Processing: background: var(--blue-50), color: var(--blue-600) + spinner
  • Success: background: var(--green-50), color: var(--green-600)
  • Error: background: var(--red-50), color: var(--red-600)
• CSS: Progress bar folosește PrimeVue ProgressBar (stilizat global)
• CSS: Confidence score cu font-family: var(--font-mono) pentru numere
• CSS: Testează în dark mode - badges vizibile și contrastate

US-005: Salvare Automată a Bonurilor Procesate

Ca sistem Vreau să salvez automat bonurile procesate cu succes în baza de date Pentru că utilizatorul dorește procesare 100% automată fără intervenție

Acceptance Criteria:

• După OCR completat cu succes, se creează automat un receipt în DB
• Receipt-ul primește status "DRAFT" (poate fi editat ulterior dacă e nevoie)
• Se atașează automat fișierul original la receipt
• Se salvează toate câmpurile extrase: vendor, CUI, dată, sumă, TVA
• Se generează automat accounting entries (ca la flow-ul manual)
• npm run typecheck passes
• Verify that receipts appear in receipt list after bulk processing

US-006: Gestionare Erori OCR

Ca utilizator Vreau ca bonurile cu erori OCR să fie marcate pentru review manual Pentru că vreau să procesez restul batch-ului fără blocaj, dar să nu pierd bonurile problematice

Acceptance Criteria:

• La eroare OCR, fișierul primește status "Eroare" cu mesaj explicativ
• Bonurile cu erori rămân în lista vizibilă, nu sunt șterse
• Buton "Deschide în editor" pentru fiecare bon cu eroare (redirect la pagina de editare manuală)
• Procesarea celorlalte bonuri continuă independent
• La final se arată sumar: "45 procesate cu succes, 5 cu erori"
• npm run typecheck passes
• Verify in browser that error files show retry/edit options
• CSS: Error row cu background: var(--red-50), border-left: 3px solid var(--red-500)
• CSS: Error message cu color: var(--red-600), font-size: var(--text-sm)
• CSS: Action buttons în error row folosesc .btn .btn-sm pattern
• CSS: Testează în dark mode - erori vizibile dar nu agresive

US-007: Rezumat Final Batch

Ca utilizator Vreau să văd un rezumat la finalul procesării batch-ului Pentru că vreau să știu câte bonuri s-au salvat și ce acțiuni mai am de făcut

Acceptance Criteria:

• Modal/panel de rezumat cu statistici: procesate OK, erori, total sumă
• Link direct la lista de receipts filtrat pe batch-ul curent (by date/user)
• Opțiune "Încarcă alt batch" pentru a începe de la zero
• Opțiune "Vezi bonurile cu erori" pentru review rapid
• npm run typecheck passes
• Verify in browser that summary modal shows correct counts
• CSS: Modal folosește PrimeVue Dialog (stilizat global) sau pattern .card
• CSS: Statistici success cu color: var(--green-600), errors cu color: var(--red-600)
• CSS: Total sumă cu font-size: var(--text-2xl), font-weight: var(--font-bold), font-family: var(--font-mono)
• CSS: Spacing consistent: padding: var(--space-lg), gap: var(--space-md)
• CSS: Testează în dark mode - modal și conținut lizibile

US-008: Backend - Endpoint Batch Upload

Ca developer Vreau un endpoint optimizat pentru upload multiple fișiere Pentru că upload-ul secvențial ar fi prea lent pentru 50+ fișiere

Acceptance Criteria:

• POST /api/data-entry/bulk/upload acceptă multipart cu multiple fișiere
• Returnează lista de job_id-uri pentru tracking
• Validare: max 100 fișiere per batch, max 10MB per fișier
• Jobs se creează atomic (toate sau niciunul)
• Returnează și un batch_id pentru grouping
• pytest tests pass
• API returns correct response schema

US-009: Backend - Auto-Save Receipt din OCR Result

Ca developer Vreau un service care creează automat receipt-uri din rezultatele OCR Pentru că flow-ul bulk trebuie să fie end-to-end fără intervenție UI

Acceptance Criteria:

• ReceiptAutoCreateService.create_from_ocr_result(job_id, ocr_result, user)
• Mapare completă OCR fields → Receipt fields
• Creare attachment cu fișierul original
• Generare accounting entries via existing logic
• Validare minimă: suma > 0, dată validă
• Return receipt_id sau error message
• pytest tests pass

US-010: Backend - Batch Status Endpoint

Ca developer Vreau un endpoint pentru status-ul întregului batch Pentru că frontend-ul trebuie să poll-eze eficient pentru toate fișierele

Acceptance Criteria:

• GET /api/data-entry/bulk/batches/{batch_id}/status
• Returnează status agregat: pending_count, processing_count, completed_count, failed_count
• Include lista de job_id + status pentru fiecare fișier
• Include receipt_id pentru jobs completate cu succes
• Suportă long-polling (wait param) pentru eficiență
• pytest tests pass

4. Cerințe Funcționale

1. [REQ-001] Sistemul trebuie să accepte upload simultan de până la 100 fișiere
2. [REQ-002] Fiecare fișier trebuie să fie max 10MB
3. [REQ-003] Formatele acceptate: PDF, PNG, JPG, JPEG
4. [REQ-004] Procesarea trebuie să fie paralelă (max N workers din config)
5. [REQ-005] Bonurile procesate cu succes se salvează automat cu status DRAFT
6. [REQ-006] Bonurile cu erori rămân disponibile pentru retry/editare manuală
7. [REQ-007] Fișierele originale se atașează automat la receipt-uri
8. [REQ-008] Se generează automat accounting entries pentru fiecare receipt
9. [REQ-009] Batch-urile trebuie să fie tracked per user (nu se văd batch-urile altora)
10. [REQ-010] Job files se curăță automat după 24h (cleanup existing)

5. Non-Goals (Ce NU facem)

• NU facem aprobare automată (bonurile rămân DRAFT, nu APPROVED)
• NU facem machine learning pentru îmbunătățirea OCR-ului
• NU facem procesare pe server extern (totul rămâne local)
• NU facem notificări (email/push) la finalizare batch
• NU facem preview/editare în bulk page - pentru asta există pagina individuală
• NU facem undo/rollback batch (bonurile create pot fi șterse individual)
• NU facem scheduling (procesare imediată, nu amânată)
• NU facem duplicate detection (poate fi adăugat ulterior)

6. Considerații Tehnice

Stack/Tehnologii

• Frontend: Vue 3 Composition API, PrimeVue (FileUpload, ProgressBar, DataTable)
• Backend: FastAPI, SQLite (job queue existent), SQLModel (receipts)
• State: Pinia store pentru batch progress tracking

Patterns de Urmat

• Folosește OCRJobQueue existent pentru job management
• Extinde job_worker.py pentru auto-save la completare
• Folosește pattern-ul de polling din OCRUploadZone.vue existent

⚠️ REGULI CSS OBLIGATORII

CITEȘTE ÎNTÂI: docs/ONBOARDING_CSS.md și docs/DESIGN_TOKENS.md

Golden Rules

✅ Folosește DOAR design tokens - NICIODATĂ valori hardcodate
✅ Verifică CSS_PATTERNS.md înainte de a scrie CSS nou
✅ Testează în AMBELE teme (light + dark mode)
❌ NICIODATĂ :deep() în componente (PrimeVue → vendor/)
❌ NICIODATĂ duplicate CSS (write once, use everywhere)

Design Tokens Obligatorii

Categorie	❌ GREȘIT	✅ CORECT
Spacing	padding: 8px	padding: var(--space-sm)
Spacing	margin: 16px	margin: var(--space-md)
Spacing	gap: 24px	gap: var(--space-lg)
Font size	font-size: 14px	font-size: var(--text-sm)
Font weight	font-weight: 500	font-weight: var(--font-medium)
Font weight	font-weight: 600	font-weight: var(--font-semibold)
Colors	color: #111827	color: var(--color-text)
Colors	color: #6b7280	color: var(--color-text-secondary)
Colors	background: #ffffff	background: var(--surface-card)
Colors	background: #f0fdf4	background: var(--green-50)
Colors	border: #e5e7eb	border-color: var(--surface-border)
Radius	border-radius: 8px	border-radius: var(--radius-md)
Shadow	box-shadow: 0 4px 6px...	box-shadow: var(--shadow-md)
Transition	transition: 0.2s	transition: var(--transition-fast)

Spacing Scale Reference

Token	Value	Use Case
--space-xs	4px	Icon gaps, badges
--space-sm	8px	Between related items
--space-md	16px	Component padding
--space-lg	24px	Section padding, cards
--space-xl	32px	Page margins

Status Colors (pentru progres/erori)

Status	Background	Text/Icon
Pending	var(--surface-hover)	var(--color-text-secondary)
Processing	var(--blue-50)	var(--blue-600)
Success	var(--green-50)	var(--green-600)
Error	var(--red-50)	var(--red-600)
Warning	var(--yellow-50)	var(--yellow-600)

Dark Mode - OBLIGATORIU

• Folosește --surface-* tokens pentru backgrounds (auto-switch în dark mode)
• Testează cu theme toggle din header (auto → light → dark)
• NU folosi culori hardcodate care nu se schimbă în dark mode

Patterns Existente de Folosit

Pattern	File	Use Case
.card	cards.css	Container principal
.btn, .btn-primary	buttons.css	Butoane
.form-group, .form-label	forms.css	Formulare
.spinner	spinners.css	Loading states
.trend, .trend-up	trends.css	Indicators
Utility classes	utilities/	gap-md, text-center, etc.

PrimeVue Components

• FileUpload, ProgressBar, DataTable, Tag, Badge - toate sunt stilizate global
• NU adăuga :deep() în componente
• Modificări PrimeVue → src/assets/css/vendor/primevue-overrides.css

Dependențe

• Job Queue existent: backend/modules/data_entry/services/ocr/job_queue.py
• Worker Pool existent: backend/modules/data_entry/services/ocr/ocr_worker_pool.py
• Receipt CRUD: backend/modules/data_entry/db/crud/receipt.py
• Attachment CRUD: backend/modules/data_entry/db/crud/attachment.py

Riscuri Tehnice

• Memory pressure: Upload simultan de 100 fișiere × 10MB = 1GB potențial
  • Mitigare: Upload secvențial intern, buffer 5 fișiere max în memorie
• Queue overflow: 100 jobs noi pot încetini procesarea existentă
  • Mitigare: Worker pool deja limitează concurența
• Browser crash: Tab închis pierde tracking progress
  • Mitigare: Jobs persistă în DB, refresh poate recupera status

7. Considerații UI/UX

Layout

1. Header: Titlu "Upload Bulk Bonuri" + link înapoi la lista principală
2. Drop Zone: Mare, centrată, cu icon și text instructiv
3. File List: Tabel/listă sub drop zone cu progres per fișier
4. Actions Bar: Butoane "Procesează", "Golește lista" - sticky la bottom

Layout CSS Structure

.bulk-upload-page
├── .page-header (pattern existent)
│   └── h1 + breadcrumb
├── .card (drop zone container)
│   └── .upload-zone (dashed border, centered)
├── .card (file list container)
│   └── DataTable sau custom list
└── .form-actions (sticky footer cu butoane)

Stări UI cu CSS

Stare	Background	Border	Elements
Empty	var(--surface-card)	2px dashed var(--surface-border)	Icon mare + text instructiv
Drag Over	var(--blue-50)	2px dashed var(--blue-500)	Border evidențiat
Files Selected	var(--surface-card)	1px solid var(--surface-border)	Lista + action buttons
Processing	var(--surface-card)	-	Spinner global + per-file status
Complete	var(--green-50) subtle	-	Summary card
Has Errors	-	-	Error items highlighted

Status Badge Styles

/* Folosește PrimeVue Tag sau custom badges */
.status-pending    { background: var(--surface-hover); color: var(--color-text-secondary); }
.status-processing { background: var(--blue-50); color: var(--blue-600); }
.status-success    { background: var(--green-50); color: var(--green-600); }
.status-error      { background: var(--red-50); color: var(--red-600); }

Accesibilitate

• Keyboard navigation pentru file list
• Screen reader announcements la status changes
• Focus management la modal rezumat
• WCAG contrast ratios respectate (toate token-urile sunt compliant)

8. Success Metrics

• Upload Success Rate: > 99% (fișierele ajung în queue)
• OCR Success Rate: > 80% (bonuri procesate fără erori)
• Average Processing Time: < 8 secunde/bon
• User Satisfaction: Reducere timp introducere date cu 90%

9. Open Questions

• Limita de 100 fișiere este suficientă sau trebuie mărită?
• Dorim să afișăm preview al datelor extrase înainte de save (ar contrazice "100% automat")?
• Ce facem cu bonurile duplicate detectate ulterior (același număr bon + dată)?
• Trebuie un "dry run" mode care procesează dar nu salvează?

---

10. Dependențe între User Stories

US-001 (Upload Files)
   ↓
US-002 (Preview List) ← independent
   ↓
US-003 (Submit Batch) → US-008 (Backend Upload Endpoint)
   ↓
US-004 (Progress) ← US-010 (Backend Status Endpoint)
   ↓
US-005 (Auto-Save) ← US-009 (Backend Auto-Create Service)
   ↓
US-006 (Error Handling)
   ↓
US-007 (Summary)

Ordine recomandată de implementare:

1. US-008: Backend - Batch Upload Endpoint
2. US-010: Backend - Batch Status Endpoint
3. US-009: Backend - Auto-Save Service
4. US-001: Frontend - Upload Zone
5. US-002: Frontend - File Preview
6. US-003: Frontend - Submit Batch
7. US-004: Frontend - Progress Tracking
8. US-005: Integration - Auto-Save Flow
9. US-006: Frontend - Error Handling
10. US-007: Frontend - Summary Modal

---

Last Updated: 2026-01-09 Author: Claude Code Status: Draft - Pending Review