Focolari-Voting-System/ai-prompts/01-backend-plan.md

📋 Piano Sviluppo Backend Mock

Obiettivo

Server FastAPI mock per simulare il backend del sistema di controllo accessi. Struttura modulare con separazione tra API, modelli e dati.

---

Struttura Target

backend-mock/
├── main.py              # Entry point con argparse
├── Pipfile              # Dipendenze pipenv
├── requirements.txt     # Backup dipendenze
├── .gitignore
├── api/
│   ├── __init__.py
│   └── routes.py        # Definizione endpoint
├── schemas/
│   ├── __init__.py
│   └── models.py        # Modelli Pydantic
└── data/
    ├── users_default.json    # Dataset utenti default
    └── users_test.json       # Dataset per test

---

Checklist Sviluppo

1. Setup Progetto

• Creare cartella backend-mock/
• Creare Pipfile per pipenv
• Configurare .gitignore per Python
• Creare struttura cartelle (api/, schemas/, data/)

2. Modelli Pydantic (schemas/models.py)

• LoginRequest - badge + password
• EntryRequest - user_badge + validator_password
• UserResponse - dati utente + warning opzionale
• RoomInfoResponse - nome sala + meeting_id
• LoginResponse - success + message + token
• EntryResponse - success + message (SENZA welcome_message)
• DA FARE: Spostare modelli in file dedicato

3. Dati Mock (data/*.json)

• Costanti validatore (badge 999999, password focolari)
• Lista utenti mock (7 utenti con dati realistici)
  • Mix di ruoli: Votante, Tecnico, Ospite
  • Alcuni con ammesso: false per test
  • URL foto placeholder (randomuser.me)
• DA FARE: Estrarre dati in file JSON separato
• DA FARE: Creare dataset alternativo per test
• DA FARE: Caricare dati dinamicamente all'avvio

Nota: I messaggi di benvenuto multilingua sono stati RIMOSSI dal backend. Il frontend gestirà autonomamente la visualizzazione internazionale con carosello.

4. Routes API (api/routes.py)

• GET /info-room - info sala
• POST /login-validate - autenticazione validatore
• GET /anagrafica/{badge_code} - ricerca utente
  • Pulizia caratteri sentinel dal badge
  • Confronto con e senza zeri iniziali
  • Warning automatico se non ammesso
• POST /entry-request - registrazione ingresso
  • Verifica password validatore
  • Verifica utente ammesso
  • Risposta asettica (solo success + message)
• DA FARE: Spostare routes in file dedicato

5. Entry Point (main.py)

• Blocco if __name__ == "__main__"
• Configurazione uvicorn (host, port)
• Messaggi console all'avvio
• DA FARE: Implementare argparse con opzioni:
  • --port / -p : porta server (default: 8000)
  • --data / -d : path file JSON dati (default: data/users_default.json)
  • --host : host binding (default: 0.0.0.0)
• DA FARE: Caricamento dinamico dati da JSON
• DA FARE: Import routes da modulo api

6. Struttura Base FastAPI

• Import FastAPI e dipendenze
• Configurazione app con titolo e descrizione
• Middleware CORS (allow all origins)
• Endpoint root / per health check
• DA FARE: Refactor in struttura modulare

---

Schema File JSON Dati

{
  "validator": {
    "badge": "999999",
    "password": "focolari"
  },
  "room": {
    "room_name": "Sala Assemblea",
    "meeting_id": "VOT-2024"
  },
  "users": [
    {
      "badge_code": "000001",
      "nome": "Maria",
      "cognome": "Rossi",
      "url_foto": "https://...",
      "ruolo": "Votante",
      "ammesso": true
    }
  ]
}

---

Comandi Esecuzione

Avvio Standard

cd backend-mock
pipenv install
pipenv run python main.py

Avvio con Parametri Custom

# Porta diversa
pipenv run python main.py --port 9000

# Dataset test
pipenv run python main.py --data data/users_test.json

# Combinato
pipenv run python main.py -p 9000 -d data/users_test.json

---

Test Rapidi

# Health check
curl http://localhost:8000/

# Info sala
curl http://localhost:8000/info-room

# Ricerca utente
curl http://localhost:8000/anagrafica/000001

# Login validatore
curl -X POST http://localhost:8000/login-validate \
  -H "Content-Type: application/json" \
  -d '{"badge": "999999", "password": "focolari"}'

# Richiesta ingresso (risposta asettica)
curl -X POST http://localhost:8000/entry-request \
  -H "Content-Type: application/json" \
  -d '{"user_badge": "000001", "validator_password": "focolari"}'

---

Note Implementative

• Gli endpoint puliscono automaticamente i caratteri ;, ?, ò, _ dai badge
• Il confronto badge avviene sia con che senza zeri iniziali
• Le risposte seguono lo standard HTTP (200 OK, 401 Unauthorized, 404 Not Found, 403 Forbidden)
• La documentazione OpenAPI è auto-generata su /docs
• Risposta /entry-request: JSON asettico { success: true, message: "..." } senza messaggi multilingua