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

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

### 2. Modelli Pydantic (`schemas/models.py`)

- [x] `LoginRequest` - badge + password
- [x] `EntryRequest` - user_badge + validator_password
- [x] `UserResponse` - dati utente + warning opzionale
- [x] `RoomInfoResponse` - nome sala + meeting_id + **server_start_time**
- [x] `LoginResponse` - success + message + token
- [x] `EntryResponse` - success + message (SENZA welcome_message)
- [x] Spostare modelli in file dedicato

### 3. Dati Mock (`data/*.json`)

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

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

**TODO (da concordare con committenti):**

- Valutare se `login-validate` debba ricevere e verificare anche il badge del validatore

### 4. Routes API (`api/routes.py`)

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

### 5. Entry Point (`main.py`)

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

### 6. Invalidazione Sessioni

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

---

## Schema File JSON Dati

```json
{
  "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)

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

### Manuale

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

---

## Test Rapidi

```bash
# 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