# Requirements: Data Entry - Bonuri Fiscale (Faza 1)

## Obiectiv

Sistem de introducere bonuri fiscale cu:
- **OCR automat** pentru extragerea datelor din poze bonuri (100% local, fara costuri)
- **Upload poze** bonuri de la utilizatori
- **Generare automata** note contabile (staging area)
- **Aprobare de contabil** inainte de finalizare
- SQLite + ORM (SQLModel) + Migrari (Alembic)
- Pregatit pentru integrare Oracle in Faza 2

## Cerinte Functionale

### 1. Gestiune Bonuri Fiscale

#### 1.1 Creare Bon cu OCR
- Utilizatorul uploadeaza poza bonului fiscal
- **OCR extrage automat**: suma, data, furnizor, CUI, numar bon
- Utilizatorul verifica si corecteaza datele extrase
- Campuri obligatorii: tip document, directie, data, suma, furnizor, casa/banca
- Campuri optionale: numar bon, serie, descriere
- Tipuri document: Bon Fiscal, Chitanta
- Directii: Cheltuiala (plata), Incasare

#### 1.2 Upload Atasamente
- Suport pentru imagini (JPEG, PNG) si PDF
- Limita dimensiune: 10MB per fisier
- Multiple atasamente per bon
- Previzualizare imagine in UI

#### 1.3 Workflow Aprobare
```
DRAFT → PENDING_REVIEW → APPROVED/REJECTED → (Faza 2: SYNCED)
```

- **DRAFT**: Utilizator completeaza datele
- **PENDING_REVIEW**: Trimis spre aprobare, sistem genereaza note contabile
- **APPROVED**: Contabil a aprobat
- **REJECTED**: Contabil a respins (cu motiv)
- **SYNCED**: (Faza 2) Sincronizat in Oracle

### 2. Note Contabile

#### 2.1 Generare Automata
- La trimiterea spre aprobare, sistemul genereaza propuneri note contabile
- Logica bazata pe tip cheltuiala selectat
- Include calcul TVA automat (19%)

#### 2.2 Editare de Contabil
- Contabilul poate modifica conturile propuse
- Poate adauga/sterge linii
- Modificarile sunt logate

#### 2.3 Tipuri Cheltuieli Predefinite

| Tip Cheltuiala | Cont Debit | TVA | Descriere |
|----------------|------------|-----|-----------|
| Combustibil | 6022 | 4426 (19%) | Benzina, motorina |
| Materiale consumabile | 6028 | 4426 (19%) | Diverse materiale |
| Rechizite birou | 6024 | 4426 (19%) | Papetarie, toner |
| Telefonie | 626 | 4426 (19%) | Telefon, internet |
| Parcare | 6022 | 4426 (19%) | Taxe parcare |
| Alimentatie | 6028 | - | Fara TVA deductibila |
| Transport | 624 | 4426 (19%) | Taxi, transport |
| Altele | 628 | 4426 (19%) | Alte cheltuieli |

### 3. Roluri si Permisiuni

#### 3.1 Utilizator Standard
- Creare bonuri noi (DRAFT)
- Editare bonuri proprii in DRAFT
- Trimitere spre aprobare
- Vizualizare status bonuri proprii

#### 3.2 Contabil (Rol Aprobare)
- Toate permisiunile utilizator
- Vizualizare toate bonurile in asteptare
- Aprobare/Respingere bonuri
- Editare note contabile propuse
- Aprobare in masa

### 4. Nomenclatoare

Preluate din Oracle (read-only):
- **Parteneri**: Furnizori si clienti
- **Conturi**: Plan conturi sintetice
- **Case/Banci**: Registre casa si conturi bancare
- **Firme**: Lista firme disponibile

## Cerinte Non-Functionale

### Performance
- Timp raspuns API < 200ms (fara upload)
- Upload fisiere < 5s pentru 10MB
- Paginare pentru liste > 50 elemente

### Securitate
- Autentificare JWT (shared cu Reports module)
- Validare MIME type pentru fisiere
- Sanitizare nume fisiere
- Acces bazat pe rol

### Scalabilitate
- Arhitectura pregatita pentru Oracle (Faza 2)
- Separare clara intre storage local si DB
- API design RESTful consistent

## API Endpoints

### Bonuri
```
POST   /api/receipts/                    # Creare bon
GET    /api/receipts/                    # Lista bonuri
GET    /api/receipts/{id}                # Detalii bon
PUT    /api/receipts/{id}                # Modificare bon (DRAFT)
DELETE /api/receipts/{id}                # Stergere bon (DRAFT)
```

### Workflow
```
POST   /api/receipts/{id}/submit         # DRAFT → PENDING
POST   /api/receipts/{id}/approve        # PENDING → APPROVED
POST   /api/receipts/{id}/reject         # PENDING → REJECTED
POST   /api/receipts/{id}/resubmit       # REJECTED → PENDING
```

### Note Contabile
```
GET    /api/receipts/{id}/entries        # Lista note
PUT    /api/receipts/{id}/entries        # Modificare note
POST   /api/receipts/{id}/entries/regenerate  # Re-generare
```

### Atasamente
```
POST   /api/receipts/{id}/attachments    # Upload
GET    /api/receipts/{id}/attachments    # Lista
GET    /api/attachments/{id}/download    # Download
DELETE /api/attachments/{id}             # Stergere
```

### Nomenclatoare
```
GET    /api/receipts/partners            # Furnizori/Clienti
GET    /api/receipts/accounts            # Conturi
GET    /api/receipts/cash-registers      # Case/Banci
GET    /api/receipts/expense-types       # Tipuri cheltuieli
```

### OCR
```
GET    /api/ocr/status                   # Verifica disponibilitate OCR
POST   /api/ocr/extract                  # Extrage date din imagine uploadata
POST   /api/ocr/extract-attachment/{id}  # Re-proceseaza atasament existent
```

## OCR - Specificatii Tehnice

### Cerinte OCR
- **100% local** - fara costuri externe, fara API-uri cloud
- **Full-auto** - completeaza formularul automat
- **Input**: doar imagini (JPG/PNG/PDF)
- **On-premise** - datele sensibile raman locale

### Campuri Extrase Automat

| Camp | Tip | Acuratete Estimata |
|------|-----|-------------------|
| Suma (TOTAL) | Decimal | 90-95% |
| Data bon | Date | 85-90% |
| Numar bon | String | 80-85% |
| Furnizor | String | 70-80% |
| CUI | String | 85-90% |
| Tip document | Enum | 95%+ |

### Stack Tehnic OCR

| Component | Solutie | Justificare |
|-----------|---------|-------------|
| **OCR Engine** | PaddleOCR (primar) | 85-92% acuratete, pip install, CPU-friendly |
| **Fallback OCR** | Tesseract + ron | Suport excelent diacritice romanesti |
| **Extractie** | Regex/rules-based | Zero dependente extra, rapid (<100ms) |
| **Preprocessing** | OpenCV | Deskew, binarizare, denoise |
| **PDF → Image** | pdf2image + Poppler | Standard, fiabil |

### Dependente Sistem (Linux)

```bash
apt-get install -y \
    tesseract-ocr tesseract-ocr-ron tesseract-ocr-eng \
    poppler-utils libgl1-mesa-glx libglib2.0-0
```

### User Flow OCR

```
1. User deschide "Bon Fiscal Nou"
2. User trage/selecteaza poza bonului
3. Click "Proceseaza cu OCR"
4. [Spinner 2-3 sec] "Se proceseaza imaginea..."
5. Apare preview cu date extrase + indicatori incredere
6. User click "Aplica datele" sau corecteaza manual
7. Formularul se completeaza automat
8. User selecteaza tip cheltuiala, casa de marcat
9. User salveaza draft sau trimite pentru aprobare
```

## Criterii de Succes (Faza 1)

- [x] Utilizator poate uploada poza bon + date de baza
- [x] **OCR extrage automat date din poza bonului**
- [x] **Indicatori de incredere pentru date extrase**
- [x] Sistem genereaza automat note contabile
- [x] Contabil poate vedea, edita si aproba note
- [x] Bonurile aprobate sunt vizibile in lista
- [x] Migrarile Alembic functioneaza corect
- [x] Poze bonuri se salveaza si se afiseaza corect
