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
394 lines
21 KiB
Markdown
394 lines
21 KiB
Markdown
# 📊 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
|
|
|
|
```powershell
|
|
# 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
|
|
```bash
|
|
cd /mnt/d/PROIECTE/roa-flask/roa2web
|
|
./ssh_tunnel.sh start
|
|
```
|
|
|
|
### Backend Development
|
|
```bash
|
|
cd reports-app/backend/
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
### Frontend Development
|
|
```bash
|
|
cd reports-app/frontend/
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
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.* |