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
```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* 🚀