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

- [x] Creare cartella `backend-mock/`
- [x] Creare `Pipfile` per pipenv
- [x] Configurare `.gitignore` per Python
- [ ] 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
- [x] `LoginResponse` - success + message + token
- [x] `EntryResponse` - success + message (SENZA welcome_message)
- [ ] **DA FARE:** Spostare modelli in file dedicato

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

- [x] Costanti validatore (badge `999999`, password `focolari`)
- [x] Lista utenti mock (7 utenti con dati realistici)
    - [x] Mix di ruoli: Votante, Tecnico, Ospite
    - [x] Alcuni con `ammesso: false` per test
    - [x] 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`)

- [x] `GET /info-room` - info sala
- [x] `POST /login-validate` - autenticazione validatore
- [x] `GET /anagrafica/{badge_code}` - ricerca utente
    - [x] Pulizia caratteri sentinel dal badge
    - [x] Confronto con e senza zeri iniziali
    - [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)
- [ ] **DA FARE:** 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
- [ ] **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

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

---

## Schema File JSON Dati

```json
{
  "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
```bash
cd backend-mock
pipenv install
pipenv run python main.py
```

### Avvio con Parametri Custom
```bash
# 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

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