Marius Mutu
6b13ffa183
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
21 KiB
21 KiB
📊 ROA2WEB - SCHEMĂ GRAFICĂ ARHITECTURĂ
Această schemă prezintă arhitectura completă a aplicației ROA2WEB, incluzând frontend-ul Vue.js, backend-ul FastAPI, middleware-ul de autentificare și conexiunea la baza de date Oracle.
🏗️ ARHITECTURA GENERALĂ
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🌐 CLIENT │
└─────────────────┬───────────────────────────────────────────────────────────────┘
│ HTTP Requests
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🖥️ FRONTEND │
│ Vue.js 3 + PrimeVue + Vite │
│ Port: 5173 (dev) / 3000 (prod) │
│ │
│ 📁 Components: 📦 Stores (Pinia): │
│ • LoginView.vue • auth.js (JWT tokens) │
│ • DashboardView.vue • companies.js │
│ • InvoicesView.vue • dashboard.js │
│ • BankCashRegisterView.vue • invoices.js │
│ • treasury.js │
│ 🔧 Services: │
│ • api.js (Axios HTTP client) │
│ • JWT token management │
└─────────────────┬───────────────────────────────────────────────────────────────┘
│ API Calls (axios)
│ Authorization: Bearer <JWT>
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🚀 BACKEND API │
│ FastAPI + Uvicorn │
│ Port: 8000 │
│ │
│ 🛡️ MIDDLEWARE LAYER: │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 1. CORSMiddleware (Frontend communication) │ │
│ │ 2. AuthenticationMiddleware (JWT validation) │ │
│ │ • Token extraction from Authorization header │ │
│ │ • JWT verification & user data injection │ │
│ │ • Rate limiting (5 req/5min per IP) │ │
│ │ • Security headers injection │ │
│ │ • Excluded paths: ["/", "/docs", "/health", "/api/auth/login"] │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 🛤️ API ROUTES: │
│ • /api/auth/login (POST) - User authentication │
│ • /api/companies (GET) - Company list │
│ • /api/dashboard (GET) - Dashboard data │
│ • /api/invoices (GET) - Invoice reports │
│ • /api/treasury (GET) - Treasury/Bank data │
│ • /health (GET) - Health check │
│ │
│ 📊 SERVICES: │
│ • invoice_service.py │
│ • dashboard_service.py │
│ • treasury_service.py │
└─────────────────┬───────────────────────────────────────────────────────────────┘
│ Database Queries
│ SSH Tunnel Required
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🔐 SSH TUNNEL LAYER │
│ ./ssh_tunnel.sh (Local port forwarding) │
│ Local: localhost:1526 ➜ Remote: oracle_server:1521 │
└─────────────────┬───────────────────────────────────────────────────────────────┘
│ Encrypted connection
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🏛️ ORACLE DATABASE │
│ Schema: CONTAFIN_ORACLE │
│ Port: 1521 (remote) / 1526 (local via tunnel) │
│ │
│ 📋 Main Tables/Views: │
│ • UTILIZATORI (Users) │
│ • V_NOM_FIRME (Companies) │
│ • VDEF_UTIL_FIRME (User-Company relations) │
│ • Financial data tables (invoices, payments, etc.) │
│ │
│ 🔧 Stored Procedures: │
│ • pack_drepturi.verificautilizator (Authentication) │
└─────────────────────────────────────────────────────────────────────────────────┘
🔄 FLUX DE AUTENTIFICARE
1. User Login (Frontend)
↓
2. POST /api/auth/login (Backend)
↓
3. Oracle Authentication via SSH Tunnel
• pack_drepturi.verificautilizator(username, password)
↓
4. JWT Token Generation (Backend)
• Access Token (30 min)
• Refresh Token (7 days)
• User data + companies + permissions
↓
5. Token Storage (Frontend - Pinia Store)
↓
6. Subsequent API Requests
• Authorization: Bearer <token>
• AuthenticationMiddleware validation
• User data injection in request.state
🚦 MIDDLEWARE AUTHENTICATION FLOW
Incoming Request
↓
┌─────────────────┐
│ Rate Limiting │ → 429 if exceeded (5 req/5min per IP)
└─────┬───────────┘
↓
┌─────────────────┐
│ Path Exclusion │ → Skip auth for /docs, /health, /api/auth/login
└─────┬───────────┘
↓
┌─────────────────┐
│ Token Extract │ → 401 if missing Authorization header
└─────┬───────────┘
↓
┌─────────────────┐
│ JWT Validation │ → 401 if invalid/expired/malformed
└─────┬───────────┘
↓
┌─────────────────┐
│ User Injection │ → request.state.user = CurrentUser
└─────┬───────────┘ → request.state.is_authenticated = True
↓ → request.state.token_data = TokenData
┌─────────────────┐
│ Security Headers│ → X-Content-Type-Options, X-Frame-Options
└─────┬───────────┘ → X-XSS-Protection, X-Process-Time
↓
┌─────────────────┐
│ Route Handler │
└─────────────────┘
🗂️ STRUCTURA DE FIȘIERE
Frontend (Vue.js)
frontend/
├── src/
│ ├── components/
│ │ ├── dashboard/
│ │ ├── layout/
│ │ ├── reports/
│ │ └── ui/
│ ├── stores/ (Pinia)
│ │ ├── auth.js
│ │ ├── companies.js
│ │ ├── dashboard.js
│ │ ├── invoices.js
│ │ └── treasury.js
│ ├── services/
│ │ └── api.js
│ ├── views/
│ │ ├── LoginView.vue
│ │ ├── DashboardView.vue
│ │ ├── InvoicesView.vue
│ │ └── BankCashRegisterView.vue
│ └── router/
└── tests/ (Playwright E2E)
Backend (FastAPI)
backend/
├── app/
│ ├── main.py
│ ├── routers/
│ │ ├── auth.py
│ │ ├── companies.py
│ │ ├── dashboard.py
│ │ ├── invoices.py
│ │ └── treasury.py
│ ├── services/
│ │ ├── invoice_service.py
│ │ ├── dashboard_service.py
│ │ └── treasury_service.py
│ └── models/
└── shared/
├── auth/
│ ├── middleware.py
│ ├── jwt_handler.py
│ ├── auth_service.py
│ └── models.py
└── database/
└── oracle_pool.py
🔧 TEHNOLOGII UTILIZATE
Frontend Stack
- Vue.js 3 - Framework JavaScript reactiv
- PrimeVue - UI Component Library
- Pinia - State Management
- Vite - Build Tool & Dev Server
- Axios - HTTP Client
- Vue Router - Client-side routing
- Chart.js - Data visualization
- Playwright - E2E Testing
Backend Stack
- FastAPI - Python Web Framework
- Uvicorn - ASGI Server
- PyJWT - JWT Token handling
- cx_Oracle - Oracle Database driver
- Pydantic - Data validation
- Python-dotenv - Environment variables
Database & Infrastructure
- Oracle Database - Persistent data storage
- SSH Tunnel - Secure database connection (Linux/development)
- Docker - Containerization (Linux production)
- Nginx - Reverse proxy & static files (Linux production)
- Windows Server + IIS - Windows production deployment
- NSSM - Windows service manager
🪟 ARHITECTURA WINDOWS SERVER/IIS
Deployment pe Windows Server
ROA2WEB poate fi deployment pe Windows Server folosind IIS și Windows Services, fără Docker:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🌐 CLIENT │
└─────────────────┬───────────────────────────────────────────────────────────────┘
│ HTTP/HTTPS Requests
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🪟 IIS WEB SERVER │
│ Port: 80/443 (HTTPS with SSL certificate) │
│ │
│ 📁 Static Files Serving: 🔀 URL Rewrite Module: │
│ • Frontend (Vue.js build) • /api/* → Backend Service │
│ • web.config configuration • /* → index.html (SPA routing) │
│ • Compression & Caching • Application Request Routing (ARR) │
│ │
│ ⚙️ Application Pool: │
│ • ROA2WEB-AppPool (.NET not required) │
│ • Integrated pipeline mode │
└─────────────────┬───────────────────────────────────────────────────────────────┘
│ Reverse Proxy to Backend
│ http://localhost:8000/api/*
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🔧 WINDOWS SERVICE │
│ Service Name: ROA2WEB-Backend │
│ Manager: NSSM (Non-Sucking Service Manager) │
│ Port: 8000 (localhost only) │
│ │
│ 📊 Backend Components: │
│ • FastAPI + Uvicorn (Python 3.11+) │
│ • Auto-start on Windows boot │
│ • Auto-restart on failure (5 sec delay) │
│ • Logging to file (stdout/stderr) │
│ │
│ 📁 Installation Location: │
│ • C:\inetpub\wwwroot\roa2web\backend\ │
└─────────────────┬───────────────────────────────────────────────────────────────┘
│ Direct Database Connection
│ No SSH Tunnel Required
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🏛️ ORACLE DATABASE (Local/Network) │
│ Connection: Direct TCP/IP (localhost:1521 or network) │
│ Schema: CONTAFIN_ORACLE │
│ │
│ 📋 Same Tables/Views as Linux deployment │
│ 🔧 Same Stored Procedures │
└─────────────────────────────────────────────────────────────────────────────────┘
Diferențe între Linux și Windows Deployment
| Aspect | Linux (Docker) | Windows (IIS) |
|---|---|---|
| Web Server | Nginx (container) | IIS (native) |
| Backend Runtime | Docker container | Windows Service (NSSM) |
| Database Access | SSH Tunnel required | Direct connection |
| SSL/TLS | Let's Encrypt (certbot) | IIS SSL certificates |
| Service Management | Docker Compose | PowerShell + Services.msc |
| Deployment | ./scripts/deploy.sh |
Deploy-ROA2WEB.ps1 |
| Logs | Docker logs | Windows Event Log + Files |
| Auto-start | Docker restart policies | Windows Service auto-start |
Structura Fișiere Windows Deployment
C:\inetpub\wwwroot\roa2web\
├── backend\ # FastAPI application
│ ├── app\
│ │ ├── main.py
│ │ ├── routers\
│ │ ├── services\
│ │ └── models\
│ ├── shared\ # Shared components
│ │ ├── auth\
│ │ ├── database\
│ │ └── utils\
│ ├── requirements.txt
│ ├── .env # Production config
│ └── logs\
│
├── frontend\ # Vue.js build output
│ ├── index.html
│ ├── assets\
│ ├── web.config # IIS configuration
│ └── ...
│
├── logs\ # Service logs
│ ├── backend-stdout.log
│ └── backend-stderr.log
│
└── backups\ # Deployment backups
└── backup-YYYYMMDD-HHMMSS\
Comenzi Windows Deployment
# Instalare inițială
.\Install-ROA2WEB.ps1
# Deployment actualizări
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\path\to\deploy-package"
# Management serviciu
.\Start-ROA2WEB.ps1
.\Stop-ROA2WEB.ps1
.\Restart-ROA2WEB.ps1
# Verificare status
Get-Service ROA2WEB-Backend
Get-Website ROA2WEB
# Logs
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stdout.log -Tail 50 -Wait
Pentru detalii complete despre deployment pe Windows, consultați:
/deployment/windows/docs/WINDOWS_DEPLOYMENT.md/deployment/windows/README.md
⚙️ COMENZI DE DEZVOLTARE
Start SSH Tunnel
cd /mnt/d/PROIECTE/roa-flask/roa2web
./ssh_tunnel.sh start
Backend Development
cd reports-app/backend/
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Frontend Development
cd reports-app/frontend/
npm install
npm run dev
Testing
cd shared/
python -m pytest -v
🛡️ SECURITATE
Middleware de Autentificare
- JWT Token Validation - Verificare automată pentru toate endpoint-urile protejate
- Rate Limiting - Protecție împotriva atacurilor brute force
- Security Headers - X-Content-Type-Options, X-Frame-Options, X-XSS-Protection
- CORS Protection - Configurare restrictivă pentru frontend-uri autorizate
Baza de Date
- SSH Tunnel - Conexiune criptată la Oracle
- Schema Dedicată - CONTAFIN_ORACLE pentru izolare
- Stored Procedures - Validare securizată de utilizatori
Această schemă oferă o vedere de ansamblu asupra arhitecturii ROA2WEB și poate fi utilizată pentru documentare, onboarding și planificarea dezvoltării viitoare.