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
├── .gitignore
├── api/
│   ├── __init__.py
│   └── routes.py        # Definizione endpoint
├── schemas/
│   ├── __init__.py
│   └── models.py        # Modelli Pydantic
└── data/
    ├── users_default.json    # Dataset utenti default (badge reali)
    └── 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 + server_start_time
• LoginResponse - success + message (senza token)
• EntryResponse - success + message (SENZA welcome_message)
• Spostare modelli in file dedicato

3. Dati Mock (data/*.json)

• Password validatore (solo password, badge gestito dal frontend)
• Lista utenti mock con badge reali:
  • 0008988288 - Marco Bianchi (Convocato, ammesso)
  • 0007399575 - Laura Rossi (Invitato, ammessa)
  • 0000514162 - Giuseppe Verdi (Tecnico, NON ammesso)
  • 0006478281 - NON nel DB (per test "non trovato")
• Estrarre dati in file JSON separato
• Creare dataset alternativo per test (users_test.json)
• Caricare dati dinamicamente all'avvio

Nota: I messaggi di benvenuto multilingua sono gestiti dal frontend con carosello.

Ruoli Supportati:

Ruolo	Descrizione
Convocato	Con diritto di voto
Invitato	Senza diritto di voto
Tecnico	Staff tecnico
Staff	Personale organizzativo

Logica Login-Validate:

• Il backend DEVE verificare la password
• Il backend PUÒ opzionalmente verificare anche il badge (whitelist validatori)
• Risposta 401 = password errata
• Risposta 403 = badge non in whitelist (se implementato)

4. Routes API (api/routes.py)

• GET /info-room - info sala + server_start_time per invalidare sessioni
• POST /login-validate - verifica solo password validatore
• GET /anagrafica/{badge_code} - ricerca utente
  • Pulizia caratteri sentinel dal badge
  • Confronto ESATTO come stringa (zeri iniziali significativi)
  • Warning automatico se non ammesso
• POST /entry-request - registrazione ingresso
  • Verifica password validatore
  • Verifica utente ammesso
  • Risposta asettica (solo success + message)
• Spostare routes in file dedicato

5. Entry Point (main.py)

• Blocco if __name__ == "__main__"
• Configurazione uvicorn (host, port)
• Messaggi console all'avvio
• 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)
• Caricamento dinamico dati da JSON
• Import routes da modulo api

6. Invalidazione Sessioni

• SERVER_START_TIME generato all'avvio del server
• Restituito in /info-room per permettere al frontend di invalidare sessioni vecchie
• Se il server riparte, tutte le sessioni frontend vengono invalidate

---

Schema File JSON Dati

{
  "validator_password": "focolari",
  "room": {
    "room_name": "Sala Assemblea",
    "meeting_id": "VOT-2024"
  },
  "users": [
    {
      "badge_code": "0008988288",
      "nome": "Marco",
      "cognome": "Bianchi",
      "url_foto": "https://...",
      "ruolo": "Votante",
      "ammesso": true
    }
  ]
}

---

Comandi Esecuzione

Via Script (consigliato)

./dev.sh server           # Avvia server con frontend su /badge
./dev.sh server -p 9000   # Porta custom
./dev.sh backend          # Solo API, no frontend

Manuale

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

---

Test Rapidi

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

# Info sala (include server_start_time)
curl http://localhost:8000/info-room

# Ricerca utente reale
curl http://localhost:8000/anagrafica/0008988288

# Badge non trovato
curl http://localhost:8000/anagrafica/0006478281

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

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

---

✅ BACKEND COMPLETATO

Tutti i task sono stati implementati e testati.

📄 Documentazione API

Per le specifiche complete da implementare nel backend reale, vedere: backend-mock/API_SPECIFICATION.md

Questo documento contiene:

• Descrizione completa di tutti gli endpoint
• Schema request/response JSON
• Codici di errore e gestione
• Meccanismo invalidazione sessioni (server_start_time)
• Considerazioni di sicurezza
• Struttura database suggerita
• Casi di test minimi