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:

pip install -r requirements.txt

2. Environment Variables:

cp .env.example .env
# Editează .env cu configurările tale

3. Run development server:

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

# 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

# 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

# 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