roa2web-service-auto/docs/MICROSERVICES_GUIDE.md

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

from shared.database.oracle_pool import oracle_pool

async with oracle_pool.get_connection() as conn:
    # Database operations

Authentication

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ă

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:

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:

{
  "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:

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:

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:

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

from shared.utils.exceptions import ROAException

@app.exception_handler(ROAException)
async def roa_exception_handler(request, exc):
    return {"error": str(exc)}

3. Logging

import logging
logger = logging.getLogger(f"roa.{__name__}")

4. Testing

# Unit tests
pytest new-app/backend/tests/

# Integration tests
pytest tests/integration/test_new_app.py

🔄 Deployment

Development

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 🚀