ScommettiApp/backend-node/IMPLEMENTATION_GUIDE.md

# Guida all'Implementazione - Miglioramenti Tecnici

## ✅ Implementazione Completata

Tutti i miglioramenti tecnici proposti nel CHANGELOG.md sono stati implementati:

1. ✅ Separazione logica business dai controller (service layer)
2. ✅ Dependency injection container (Awilix)
3. ✅ Request/Response DTOs (Joi validation)
4. ✅ Standardizzazione formato risposte API
5. ✅ Error handling centralizzato
6. ✅ Constants file per magic numbers/strings
7. ⏭️ Type checking con TypeScript - SKIPPED (come pianificato)
8. ✅ Code linting (ESLint) e formatting (Prettier)

## 🚀 Prossimi Passi per Avviare il Backend

### 1. Installare le Dipendenze

```bash
cd /home/claude/scomettiapp/backend-node

# Installare dipendenze di produzione
npm install awilix@^10.0.2 joi@^17.12.1

# Installare dipendenze di sviluppo
npm install --save-dev eslint@^8.56.0 eslint-config-airbnb-base@^15.0.0 eslint-plugin-import@^2.29.1 prettier@^3.2.4 eslint-config-prettier@^9.1.0 eslint-plugin-prettier@^5.1.3
```

### 2. Verificare Linting

```bash
# Controllare errori di linting
npm run lint

# Fixare automaticamente errori di linting
npm run lint:fix

# Formattare tutto il codice
npm run format
```

### 3. Avviare il Server

```bash
npm start
```

Output atteso:
```
Connected to MongoDB
Connected to PostgreSQL
PostgreSQL models synchronized
Server is running on http://localhost:3000
Environment: development
API v1 endpoints available at /api/v1/
Legacy endpoints available at /api/legacy/
Health check available at /health
```

## 🧪 Testing dell'Implementazione

### Test 1: Health Check

```bash
curl http://localhost:3000/health
```

Risposta attesa:
```json
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "services": {
    "postgres": "connected",
    "mongodb": "connected"
  }
}
```

### Test 2: Creare un Gruppo (v1 API)

```bash
curl -X POST http://localhost:3000/api/v1/groups \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Group",
    "members": [1, 2]
  }'
```

Risposta attesa (formato standardizzato):
```json
{
  "success": true,
  "message": "Group created successfully",
  "data": {
    "id": 3,
    "name": "Test Group",
    "members": [...]
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### Test 3: Validazione Errore

```bash
curl -X POST http://localhost:3000/api/v1/groups \
  -H "Content-Type: application/json" \
  -d '{
    "name": "",
    "members": []
  }'
```

Risposta attesa (errore standardizzato):
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {"field": "name", "message": "Group name is required"},
    {"field": "members", "message": "At least one member is required"}
  ],
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### Test 4: Not Found Error

```bash
curl http://localhost:3000/api/v1/groups/999
```

Risposta attesa:
```json
{
  "success": false,
  "message": "Group not found",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### Test 5: Verificare Compatibilità Legacy

```bash
# Legacy route (vecchio formato, dovrebbe ancora funzionare)
curl http://localhost:3000/api/legacy/groups
```

### Test 6: Initial Data

```bash
curl http://localhost:3000/api/v1/initial-data
```

Risposta attesa:
```json
{
  "success": true,
  "message": "Initial data retrieved successfully",
  "data": {
    "currentUser": {...},
    "users": [...],
    "friends": [...],
    "friendRequests": [...],
    "groups": [...],
    "userBets": [...],
    "publicBets": [...]
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

## 📋 Checklist Verifica Completa

- [ ] Server si avvia senza errori
- [ ] PostgreSQL connesso
- [ ] MongoDB connesso
- [ ] Health check risponde correttamente
- [ ] Routes v1 rispondono con formato standardizzato
- [ ] Validation errors catturati e formattati
- [ ] Not found errors ritornano 404 consistente
- [ ] Routes legacy funzionano ancora (backward compatibility)
- [ ] ESLint passa senza errori critici
- [ ] Nessuna logica business nei controllers (solo nei services)

## 🎯 Endpoints API v1

### Groups
- `GET /api/v1/groups` - Lista tutti i gruppi
- `GET /api/v1/groups/:id` - Dettaglio gruppo
- `POST /api/v1/groups` - Crea gruppo (validato)
- `PUT /api/v1/groups/:id` - Aggiorna gruppo (validato)
- `DELETE /api/v1/groups/:id` - Elimina gruppo
- `PUT /api/v1/groups/:id/members` - Aggiungi membri (validato)
- `DELETE /api/v1/groups/:id/members/:userId` - Rimuovi membro

### Bets
- `GET /api/v1/bets` - Lista tutte le scommesse
- `GET /api/v1/bets/:id` - Dettaglio scommessa
- `POST /api/v1/bets` - Crea scommessa (validato)
- `PUT /api/v1/bets/:id` - Aggiorna scommessa (validato)
- `DELETE /api/v1/bets/:id` - Elimina scommessa

### Friend Requests
- `GET /api/v1/friend-requests` - Lista amici
- `GET /api/v1/friend-requests/pending` - Richieste pending
- `POST /api/v1/friend-requests` - Invia richiesta (validato)
- `POST /api/v1/friend-requests/:id/accept` - Accetta richiesta
- `DELETE /api/v1/friend-requests/:id` - Rifiuta richiesta

### Users
- `PUT /api/v1/users/current` - Aggiorna profilo (validato)

### Initial Data
- `GET /api/v1/initial-data` - Carica dati iniziali

### Health
- `GET /health` - Status database

## 🏗️ Architettura Implementata

```
Request → Routes → Validation → Controller → Service → Repository → Database
                       ↓                         ↓
                  Joi Schema              Business Logic
                       ↓
              Custom Errors (ValidationError, etc.)
                       ↓
            Global Error Handler Middleware
                       ↓
              Standardized Response (ResponseHandler)
```

## 📊 Benefici dell'Architettura

1. **Separation of Concerns**: Ogni layer ha responsabilità ben definite
2. **Testability**: Services e repositories facilmente testabili con mock
3. **Maintainability**: Business logic centralizzata
4. **Consistency**: Formato risposte e errori standardizzati
5. **Scalability**: Facile aggiungere nuove feature
6. **Type Safety**: Validation layer previene dati inconsistenti
7. **Backward Compatibility**: Routes legacy funzionano ancora
8. **Flexibility**: DI container permette sostituzioni facili

## 🔧 Troubleshooting

### Errore: "Cannot find module 'awilix'"
Eseguire `npm install` per installare tutte le dipendenze.

### Errore: Database connection failed
Verificare che PostgreSQL e MongoDB siano in esecuzione e accessibili.

### Errore: ESLint errors
Eseguire `npm run lint:fix` per correggere automaticamente i problemi di formattazione.

### Routes legacy non funzionano
Le routes legacy sono state spostate su `/api/legacy/*` per mantenere compatibilità.

## 📝 Note Importanti

- **TypeScript**: Non implementato in questa fase (come pianificato)
- **Testing automatici**: Da implementare in fase successiva
- **Logging strutturato**: Opzionale, non implementato
- **Production**: Richiede ulteriori configurazioni (migrations, real auth, etc.)

## 🎉 Prossimi Step Consigliati

1. Installare dipendenze con npm
2. Testare tutti gli endpoint v1
3. Migrare frontend da `/api/*` a `/api/v1/*`
4. Eventualmente deprecare `/api/legacy/*`
5. Aggiungere test automatici (Jest)
6. Implementare logging strutturato (Winston)
7. Considerare migrazione a TypeScript in futuro