Initial commit: ROA2WEB - FastAPI + Vue.js + Telegram Bot
Modern ERP Reports Application with microservices architecture Tech Stack: - Backend: FastAPI + python-oracledb (Oracle DB integration) - Frontend: Vue.js 3 + PrimeVue + Vite - Telegram Bot: python-telegram-bot + SQLite - Infrastructure: Shared database pool, JWT authentication, SSH tunnel Features: - FastAPI backend with async Oracle connection pool - Vue.js 3 responsive frontend with PrimeVue components - Telegram bot alternative interface - Microservices architecture with shared components - Complete deployment support (Linux Docker + Windows IIS) - Comprehensive testing (Playwright E2E + pytest) Repository Structure: - reports-app/ - Main application (backend, frontend, telegram-bot) - shared/ - Shared components (database pool, auth, utils) - deployment/ - Deployment scripts (Linux & Windows) - docs/ - Project documentation - security/ - Security scanning and git hooks
This commit is contained in:
204
reports-app/backend/README.md
Normal file
204
reports-app/backend/README.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user