roa2web-service-auto/reports-app/backend/README.md

# ROA Reports Backend API

FastAPI backend pentru aplicația de rapoarte ROA2WEB.

## 🚀 Funcționalități

### 📊 API Endpoints Implementate

#### Authentication (`/auth`)
- `POST /auth/login` - Autentificare utilizator
- `POST /auth/logout` - Deconectare utilizator
- `GET /auth/me` - Informații utilizator curent
- `GET /auth/validate` - Validare token JWT

#### Companies (`/companies`)
- `GET /companies/` - Lista firmelor utilizatorului
- `GET /companies/{company_code}` - Detalii firmă
- `GET /companies/{company_code}/validate` - Validare acces firmă

#### Invoices (`/invoices`)
- `GET /invoices/` - Lista facturi cu filtrare și paginare
- `GET /invoices/summary` - Rezumat facturi pentru dashboard
- `GET /invoices/{invoice_number}` - Detalii factură specifică
- `GET /invoices/export/{format}` - Export facturi (planned)

#### Payments (`/payments`)
- `GET /payments/` - Lista încasări/plăți cu filtrare și paginare
- `GET /payments/summary` - Rezumat încasări pentru dashboard
- `GET /payments/{payment_number}` - Detalii încasare specifică
- `POST /payments/` - Creare încasare nouă (planned)
- `PUT /payments/{payment_number}` - Actualizare încasare (planned)
- `GET /payments/export/{format}` - Export încasări (planned)

#### Health Check
- `GET /` - Status API
- `GET /health` - Health check complet cu database

## 🏗️ Arhitectură

### Shared Components Integration
- **Database Pool**: Folosește `roa2web/shared/database/oracle_pool.py`
- **JWT Authentication**: Folosește `roa2web/shared/auth/` pentru validare token-uri
- **Middleware**: Authentication middleware cu rate limiting

### Structură Aplicație
```
app/
├── main.py                 # FastAPI entry point
├── models/                 # Pydantic models
│   ├── invoice.py          # Modele pentru facturi
│   └── payment.py          # Modele pentru încasări
├── routers/                # API endpoints
│   ├── auth.py             # Authentication endpoints
│   ├── companies.py        # Companies management
│   ├── invoices.py         # Invoices API
│   └── payments.py         # Payments API
├── services/               # Business logic
│   ├── invoice_service.py  # Serviciu facturi cu Oracle queries
│   └── payment_service.py  # Serviciu încasări cu Oracle queries
└── schemas/                # Response schemas (reserved)
```

## 🔧 Instalare și Rulare

### Development Local

1. **Install dependencies**:
```bash
pip install -r requirements.txt
```

2. **Environment Variables**:
```bash
cp .env.example .env
# Editează .env cu configurările tale
```

3. **Run development server**:
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

4. **Access API**:
- API: http://localhost:8000
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### Docker

```bash
# Build image
docker build -t roa-reports-backend .

# Run container
docker run -p 8000:8000 --env-file .env roa-reports-backend
```

## 📝 Configurație

### 🔐 Oracle Database Setup

**IMPORTANT**: Conectare la schema **CONTAFIN_ORACLE** pentru authentication!

#### Arhitectura Bazei de Date
- **Schema CONTAFIN_ORACLE**: Conține utilizatorii și procedura `pack_drepturi.verificautilizator`
- **Scheme separate pentru firme**: Fiecare firmă are propria schemă cu date (ROMFAST, EUROLEVIS, etc.)

#### Flow-ul de Autentificare
1. **Conectare**: La schema `CONTAFIN_ORACLE`
2. **Verificare**: User/pass prin `pack_drepturi.verificautilizator(username, password)`
3. **Drepturi**: Citire firme din `vdef_util_grup WHERE id_util = user_id`
4. **Selecție**: User selectează firma/schema pentru acces la date

### Environment Variables

```bash
# Oracle Database (prin SSH tunnel)
ORACLE_USER=CONTAFIN_ORACLE
ORACLE_PASSWORD=your_oracle_password
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SID=ROA

# SSH Tunnel Setup Required:
# ./ssh_tunnel.sh start
# Server: 83.103.197.79:22122 -> 10.0.20.36:1521

# Test User Credentials (pentru dezvoltare):
# Username: "MARIUS M" (cu spațiu în nume!)
# Password: "PAROLA81"
# Are acces la 66+ firme/scheme Oracle

# JWT Settings
JWT_SECRET_KEY=your-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30

# API Settings
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=True

# CORS
FRONTEND_URLS=http://localhost:3000,http://localhost:5173
```

## 🔐 Autentificare

API-ul folosește JWT Bearer tokens pentru autentificare:

1. **Login**: `POST /auth/login` cu username/password
2. **Token Usage**: Include `Authorization: Bearer <token>` în header
3. **Company Access**: Fiecare request verifică dacă utilizatorul are acces la firma specificată

## 📊 Models și Filtrare

### Invoice Filter Parameters
- `company`: Codul firmei (obligatoriu)
- `partner_type`: CLIENTI sau FURNIZORI
- `date_from`, `date_to`: Filtrare după dată
- `partner_name`: Filtrare după numele partenerului
- `only_unpaid`: Doar facturile neachitate
- `min_amount`, `max_amount`: Filtrare după sumă
- `page`, `page_size`: Paginare

### Response Models
- **InvoiceListResponse**: Lista paginată cu metadata
- **InvoiceSummary**: Statistici pentru dashboard
- **PaymentListResponse**: Lista încasări cu metadata
- **PaymentSummary**: Statistici încasări

## 🚀 Următorii Pași

1. **Export Functionality**: Implementare export Excel, PDF, CSV
2. **CRUD Operations**: Operațiuni complete pentru încasări
3. **Advanced Filtering**: Filtre avansate și sortare
4. **Caching**: Redis cache pentru performance
5. **Rate Limiting**: Advanced rate limiting
6. **Audit Logging**: Logging complet pentru operațiuni

## 🧪 Testing

```bash
# Unit tests (când vor fi implementate)
pytest tests/ -v

# Health check manual
curl http://localhost:8000/health

# API testing
# Vezi documentația Swagger la /docs pentru toate endpoint-urile
```

## 📚 Compatibilitate

API-ul este compatibil 100% cu query-urile și datele din aplicația Flask existentă:
- Stesso schema de date Oracle
- Aceleași view-uri (`vireg_parteneri`)
- Aceleași calcule pentru statusul facturilor
- Aceleași validări pentru acces utilizatori

---

**Status**: ✅ COMPLET - Ready for Frontend Integration
**Next Phase**: Frontend Vue.js Development