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:
234
docs/MICROSERVICES_GUIDE.md
Normal file
234
docs/MICROSERVICES_GUIDE.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# ROA2WEB Microservices Guide
|
||||
|
||||
🚀 **Ghid pentru Adăugarea de Module Noi în Ecosistemul ROA2WEB**
|
||||
|
||||
## 📋 Conceptul Microserviciilor
|
||||
|
||||
ROA2WEB folosește o arhitectură microservicii care permite adăugarea ușoară de module noi fără a afecta funcționalitatea existentă.
|
||||
|
||||
### 🏗️ Structura unui Microserviciu
|
||||
|
||||
```
|
||||
new-app/
|
||||
├── backend/ # FastAPI Backend
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # Entry point
|
||||
│ │ ├── models/ # Pydantic models
|
||||
│ │ ├── routers/ # API endpoints
|
||||
│ │ ├── services/ # Business logic
|
||||
│ │ └── schemas/ # Response schemas
|
||||
│ ├── requirements.txt
|
||||
│ ├── Dockerfile
|
||||
│ └── .env.example
|
||||
├── frontend/ # Vue.js Frontend (opțional)
|
||||
│ ├── src/
|
||||
│ │ ├── main.js
|
||||
│ │ ├── App.vue
|
||||
│ │ ├── router/
|
||||
│ │ ├── stores/
|
||||
│ │ ├── views/
|
||||
│ │ └── components/
|
||||
│ ├── package.json
|
||||
│ ├── vite.config.js
|
||||
│ └── Dockerfile
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 🔧 Shared Components
|
||||
|
||||
Toate microserviciile folosesc componentele comune din directorul `shared/`:
|
||||
|
||||
### Database Pool
|
||||
```python
|
||||
from shared.database.oracle_pool import oracle_pool
|
||||
|
||||
async with oracle_pool.get_connection() as conn:
|
||||
# Database operations
|
||||
```
|
||||
|
||||
### Authentication
|
||||
```python
|
||||
from shared.auth.jwt_handler import jwt_handler
|
||||
from shared.auth.middleware import require_auth
|
||||
|
||||
@require_auth
|
||||
async def protected_endpoint():
|
||||
# Protected logic
|
||||
```
|
||||
|
||||
## 🚀 Pași pentru Adăugare Microserviciu Nou
|
||||
|
||||
### 1. Creare Structură
|
||||
|
||||
```bash
|
||||
mkdir -p new-app/{backend/app/{models,routers,services,schemas},frontend/src/{router,stores,views,components}}
|
||||
```
|
||||
|
||||
### 2. Backend Setup
|
||||
|
||||
**`new-app/backend/app/main.py`**:
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
import sys
|
||||
import os
|
||||
|
||||
# Add shared path
|
||||
sys.path.append(os.path.join(os.path.dirname(__file__), '../../../shared'))
|
||||
|
||||
from database.oracle_pool import oracle_pool
|
||||
from auth.jwt_handler import jwt_handler
|
||||
|
||||
app = FastAPI(title="New App API")
|
||||
|
||||
@app.on_event("startup")
|
||||
async def startup():
|
||||
await oracle_pool.initialize()
|
||||
|
||||
@app.on_event("shutdown")
|
||||
async def shutdown():
|
||||
await oracle_pool.close_pool()
|
||||
```
|
||||
|
||||
### 3. Frontend Setup (Opțional)
|
||||
|
||||
Dacă microserviciul necesită UI:
|
||||
|
||||
**`new-app/frontend/package.json`**:
|
||||
```json
|
||||
{
|
||||
"name": "new-app-frontend",
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "vite build"
|
||||
},
|
||||
"dependencies": {
|
||||
"vue": "^3.3.0",
|
||||
"primevue": "^3.0.0",
|
||||
"pinia": "^2.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Docker Configuration
|
||||
|
||||
**`new-app/backend/Dockerfile`**:
|
||||
```dockerfile
|
||||
FROM python:3.9-slim
|
||||
|
||||
WORKDIR /app
|
||||
COPY requirements.txt .
|
||||
RUN pip install -r requirements.txt
|
||||
|
||||
COPY . .
|
||||
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||
```
|
||||
|
||||
### 5. Nginx Routing
|
||||
|
||||
Adaugă în `nginx/nginx.conf`:
|
||||
|
||||
```nginx
|
||||
location /new-app/ {
|
||||
proxy_pass http://new-app-backend:8000/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Docker Compose Integration
|
||||
|
||||
Adaugă în `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
new-app-backend:
|
||||
build: ./new-app/backend
|
||||
networks:
|
||||
- roa-network
|
||||
environment:
|
||||
- ORACLE_USER=${ORACLE_USER}
|
||||
- ORACLE_PASSWORD=${ORACLE_PASSWORD}
|
||||
- ORACLE_DSN=${ORACLE_DSN}
|
||||
```
|
||||
|
||||
## 📊 Exemple de Microservicii
|
||||
|
||||
### 1. Invoicing App
|
||||
- Gestionare facturi
|
||||
- Generare PDF
|
||||
- Email notifications
|
||||
|
||||
### 2. Inventory App
|
||||
- Gestiune stocuri
|
||||
- Mișcări de marfă
|
||||
- Rapoarte inventar
|
||||
|
||||
### 3. CRM App
|
||||
- Gestionare clienți
|
||||
- Istoric interacțiuni
|
||||
- Pipeline vânzări
|
||||
|
||||
## 🔐 Securitate
|
||||
|
||||
### Autentificare
|
||||
Toate microserviciile folosesc JWT tokens din `shared/auth/`.
|
||||
|
||||
### Autorizare
|
||||
Implementează middleware pentru verificarea permisiunilor per modul.
|
||||
|
||||
### Database Access
|
||||
Folosește doar `shared/database/oracle_pool.py` pentru acces la baza de date.
|
||||
|
||||
## 📋 Best Practices
|
||||
|
||||
### 1. Naming Convention
|
||||
- **Directoare**: `kebab-case` (ex: `invoicing-app`)
|
||||
- **API Endpoints**: `/api/v1/resource`
|
||||
- **Database**: Schema separată per modul
|
||||
|
||||
### 2. Error Handling
|
||||
```python
|
||||
from shared.utils.exceptions import ROAException
|
||||
|
||||
@app.exception_handler(ROAException)
|
||||
async def roa_exception_handler(request, exc):
|
||||
return {"error": str(exc)}
|
||||
```
|
||||
|
||||
### 3. Logging
|
||||
```python
|
||||
import logging
|
||||
logger = logging.getLogger(f"roa.{__name__}")
|
||||
```
|
||||
|
||||
### 4. Testing
|
||||
```bash
|
||||
# Unit tests
|
||||
pytest new-app/backend/tests/
|
||||
|
||||
# Integration tests
|
||||
pytest tests/integration/test_new_app.py
|
||||
```
|
||||
|
||||
## 🔄 Deployment
|
||||
|
||||
### Development
|
||||
```bash
|
||||
docker-compose up new-app-backend new-app-frontend
|
||||
```
|
||||
|
||||
### Production
|
||||
Folosește orchestratoare precum Kubernetes pentru scalare automată.
|
||||
|
||||
## 📞 Support
|
||||
|
||||
Pentru întrebări despre dezvoltarea de microservicii:
|
||||
|
||||
1. Consultă documentația shared components
|
||||
2. Urmărește pattern-urile din `reports-app/`
|
||||
3. Testează integrarea cu componentele comune
|
||||
|
||||
---
|
||||
|
||||
*Arhitectura microservicii permite creșterea organică a platformei ROA2WEB* 🚀
|
||||
Reference in New Issue
Block a user