Floor Plan Service (Servizio Planimetrie)

Un microservizio visuale che mostra planimetrie di edifici e piani specifici, progettato per essere visualizzato su display dedicati.

---

Indice

• Panoramica del Progetto
• Diagramma dell'Architettura
• Caratteristiche Principali
• Tecnologie Utilizzate
• Struttura della Directory
• Struttura delle Immagini
• Prerequisiti
• Guida all'Installazione
• Accesso e Link Utili
• Variabili d'Ambiente
• Esecuzione dei Test
• Come Contribuire
• Licenza

---

Panoramica del Progetto

Il floorplan-service fornisce un contesto visuale all'interno della Digital Signage Suite. Il suo scopo è mostrare una specifica immagine (planimetria, mappa, indicazione) a schermo intero, determinata dinamicamente dai parametri passati nell'URL. Questo permette di avere display dedicati a mostrare mappe di piani o percorsi specifici.

---

Diagramma dell'Architettura

L'architettura di questo servizio è più semplice rispetto agli altri, poiché non interagisce con API esterne ma serve file locali in modo intelligente.

graph TD
    subgraph "Client (Browser del Display)"
        A[Richiesta HTTP per una planimetria]
    end

    subgraph "Digital Signage Suite (Rete Docker)"
        B{Proxy Nginx}
        C[Container floorplan-service]
        D[(Volume: ui/assets/...)]
    end

    A -- 1. /floorplan/A/floor0/A-S-1 --> B;
    B -- 2. Inoltra la richiesta a --> C;
    C -- 3. Cerca e trova l'immagine in --> D;
    C -- 4. Renderizza il template HTML --> B;
    B -- 5. Invia la pagina al client --> A;

Loading

1. Un display richiede un URL specifico al Proxy Nginx.
2. Nginx inoltra la richiesta al floorplan-service.
3. Il servizio Flask cerca l'immagine richiesta nel volume locale dove sono salvate le planimetrie.
4. Flask renderizza la pagina HTML, inserendo l'URL dell'immagine trovata come sfondo.
5. La pagina completa viene restituita al display.

---

Caratteristiche Principali

• ✅ Visualizzazione Dinamica: Mostra un'immagine diversa in base ai parametri edificio, piano e nome_immagine nell'URL.
• ⚙️ Configurazione Flessibile: La mappatura tra sigle degli edifici e nomi delle cartelle è gestita da variabili d'ambiente.
• 🛡️ Sicurezza: Include estensioni come Talisman e CORS e una Content Security Policy configurata.
• ❤️ Health Check: Endpoint /health per un facile monitoraggio dello stato del servizio.
• 📄 Pagina di Errore Personalizzata: Mostra una pagina 404 coerente con la grafica del sistema.
• 🐳 Containerizzato: Completamente gestito tramite Docker e Docker Compose.
• 🧪 Testato: Include una suite di test di integrazione con pytest per garantire l'affidabilità.

---

Tecnologie Utilizzate

• Backend: Python 3.11, Flask, Gunicorn
• Containerizzazione: Docker, Docker Compose
• Sicurezza: Flask-Talisman, Flask-Cors
• Configurazione: Python-dotenv
• Testing: Pytest

---

Struttura della Directory

floorplan-service/
├── app/
│   ├── __init__.py       # Application factory (crea l'app Flask)
│   ├── config.py         # Carica e processa la configurazione da .env
│   └── routes.py         # Definisce tutte le rotte e la logica
│
├── tests/                # Test automatici
│   ├── __init__.py
│   └── test_floorplan_api.py
│
├── ui/
│   ├── assets/           # Immagini delle planimetrie e assets comuni
│   ├── static/           # File CSS e JavaScript
│   ├── 404.html
│   └── index.html
│
├── .env.example
├── Dockerfile
├── requirements.txt
└── run.py

---

Struttura delle Immagini (Importante!)

Perché il servizio funzioni, le immagini devono essere organizzate in una struttura specifica all'interno di ui/assets/.

ui/
└── assets/
    ├── building_A/
    │   ├── floor0/
    │   │   └── A-S-6.png
    │   └── floor_1/
    │       └── A-1-6.jpg
    │
    ├── building_B/
    │   └── ...

---

Prerequisiti

• Docker Engine
• Docker Compose V2

---

Guida all'Installazione

1. Clona il Repository.
2. Configura le Variabili d'Ambiente: In floorplan-service, copia .env.example in .env.
3. Prepara la Struttura delle Immagini: Crea le cartelle in ui/assets/ e inserisci le immagini.
4. Avvia lo Stack Docker: Dalla cartella principale, esegui docker compose up --build -d.

---

Accesso e Link Utili 🔗

• Link Planimetrie: http://<IP_SERVER>/floorplan/{EDIFICIO}/{PIANO}/{IMMAGINE}

  • Esempio: http://localhost/floorplan/A/floor_1/A-1-6

• Health Check: http://localhost/floorplan/health

---

Variabili d'Ambiente

• BUILDINGS: Lista di sigle di edifici e nomi di cartelle (es. A:building_A,B:building_B).
• ALLOWED_FLOORS: Lista di numeri di piano permessi (es. -1,0,1,2,3).

---

Esecuzione dei Test

I test di integrazione verificano che gli endpoint principali si comportino come previsto.

Prerequisiti: Lo stack Docker deve essere in esecuzione.

Per lanciare i test, esegui questo comando dalla cartella principale DigitalSignageSuite:

cd floorplan-service
pytest

L'output dovrebbe mostrare che tutti i test sono stati superati (... passed).

---

Come Contribuire

I contributi sono sempre i benvenuti! Per contribuire:

1. Fai un fork del repository.
2. Crea un nuovo branch (git checkout -b feature/nome-feature).
3. Fai le tue modifiche e assicurati che i test passino (pytest).
4. Fai il commit delle tue modifiche (git commit -am 'Aggiungi nuova feature').
5. Fai il push sul tuo branch (git push origin feature/nome-feature).
6. Apri una Pull Request.

---

Licenza

Questo progetto è rilasciato sotto la Licenza MIT.