org-parking/README.md

Org-Parking

Un'applicazione leggera gestionale per i parcheggi aziendali, progettata per le organizzazioni. Offre un algoritmo di assegnazione equa, tracciamento delle presenze ed è ottimizzata per basse risorse.

Funzionalità

• Modello Centrato sull'Ufficio: I posti auto appartengono agli Uffici, non ai Manager o agli Utenti.
• Algoritmo di Assegnazione Equa: Gli utenti con il rapporto parcheggi/presenze più basso hanno la priorità.
• Tracciamento Presenze: Marcatura delle presenze basata su calendario (presente/remoto/assente).
• Regole di Chiusura Flessibili: Supporto per chiusure in date specifiche e chiusure settimanali ricorrenti per ufficio.
• Garanzie ed Esclusioni: Regole di parcheggio per utente gestite dagli amministratori dell'ufficio.
• Accesso Basato sui Ruoli:
  • Admin: Controllo completo del sistema, creazione uffici, gestione utenti.
  • Manager: Gestisce le impostazioni del proprio ufficio e il team.
  • Impiegato: Segna presenza, visualizza calendario, controlla stato parcheggio.
• Basso Consumo di Memoria: Ottimizzato per piccoli server (<500MB RAM).
• Autenticazione: Auth JWT integrata o integrazione SSO con Authelia.

Architettura

app/
├── routes/          # API endpoints
│   ├── auth.py      # Autenticazione
│   ├── users.py     # Gestione utenti
│   ├── offices.py   # Gestione uffici (quote, regole)
│   ├── presence.py  # Marcatura presenze
│   └── parking.py   # Logica di assegnazione
└── config.py        # Configurazione
database/
├── models.py        # Modelli SQLAlchemy ORM
└── connection.py    # Setup Database
frontend/            # Frontend Vanilla JS pulito
├── pages/           # Viste HTML
├── js/              # Moduli logici
└── css/             # Stili

Guida Rapida

Sviluppo Locale

1. Setup Ambiente:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

2. Avvio Server:

   python main.py
   

   Accedi a http://localhost:8000

Deployment Docker (Consigliato)

Questa applicazione è ottimizzata per ambienti con risorse limitate (es. Raspberry Pi, piccoli VPS).

1. Build:

   docker compose build
   

2. Run:

   docker compose up -d
   

   Nota sull'Uso della Memoria: Il Dockerfile è configurato per eseguire uvicorn con --workers 1 per minimizzare l'uso della memoria (~50MB in idle). Se in esecuzione su un server più grande, puoi rimuovere questo flag nel Dockerfile.

Configurazione

Copia .env.example in .env e configura:

Variabile	Descrizione	Default
SECRET_KEY	Richiesto. Chiave cripto per JWT.	"" (Esce se mancante)
DATABASE_URL	Vedi docs SQLAlchemy.	sqlite:///data/parking.db
AUTHELIA_ENABLED	Abilita supporto header SSO.	false
SMTP_ENABLED	Abilita notifiche email.	false
LOG_LEVEL	Verbosità log.	INFO

Algoritmo di Equità

I posti auto vengono assegnati giornalmente basandosi su un rapporto di equità:

Rapporto = (Giorni Parcheggiati con successo) / (Giorni di Presenza in ufficio)

• Gli utenti Garantiti vengono assegnati per primi.
• I posti Rimanenti sono distribuiti agli utenti presenti iniziando da chi ha il rapporto più basso.
• Gli utenti Esclusi non ricevono mai un posto.

API Endpoints

Di seguito la lista delle chiamate API disponibili suddivise per modulo.

Auth (/api/auth)

Gestione autenticazione e sessione.

• POST /register: Registrazione nuovo utente (Disabilitato se Authelia è attivo).
• POST /login: Login con email e password (ritorna token JWT/cookie).
• POST /logout: Logout e invalidazione sessione.
• GET /me: Ritorna informazioni sull'utente corrente.
• GET /config: Ritorna la configurazione pubblica di autenticazione.
• GET /holidays/{year}: Ritorna i giorni festivi per l'anno specificato.

Users (/api/users)

Gestione utenti e profili.

• GET /: Lista di tutti gli utenti (Solo Admin).
• POST /: Crea un nuovo utente (Solo Admin).
• GET /{user_id}: Dettaglio di un utente specifico (Solo Admin).
• PUT /{user_id}: Aggiorna dati di un utente (Solo Admin).
• DELETE /{user_id}: Elimina un utente (Solo Admin).
• GET /me/profile: Ottieni il proprio profilo.
• PUT /me/profile: Aggiorna il proprio profilo.
• GET /me/settings: Ottieni le proprie impostazioni.
• PUT /me/settings: Aggiorna le proprie impostazioni.
• POST /me/change-password: Modifica la propria password.
• GET /me/exclusion: Lista delle proprie auto-esclusioni.
• POST /me/exclusion: Crea una nuova auto-esclusione.
• PUT /me/exclusion/{exclusion_id}: Modifica una auto-esclusione.
• DELETE /me/exclusion/{exclusion_id}: Elimina una auto-esclusione.

Offices (/api/offices)

Gestione uffici, regole di chiusura e quote.

• GET /: Lista di tutti gli uffici.
• POST /: Crea un nuovo ufficio (Solo Admin).
• GET /{office_id}: Dettagli di un ufficio.
• PUT /{office_id}: Aggiorna configurazione ufficio (Solo Admin).
• DELETE /{office_id}: Elimina un ufficio (Solo Admin).
• GET /{office_id}/users: Lista utenti assegnati all'ufficio.
• GET /{office_id}/closing-days: Lista giorni di chiusura specifici.
• POST /{office_id}/closing-days: Aggiungi giorno di chiusura.
• DELETE /{office_id}/closing-days/{id}: Rimuovi giorno di chiusura.
• GET /{office_id}/weekly-closing-days: Lista giorni di chiusura settimanali (es. Sabato/Domenica).
• POST /{office_id}/weekly-closing-days: Aggiungi giorno di chiusura settimanale.
• DELETE /{office_id}/weekly-closing-days/{id}: Rimuovi giorno di chiusura settimanale.
• GET /{office_id}/guarantees: Lista utenti con posto garantito.
• POST /{office_id}/guarantees: Aggiungi garanzia posto.
• DELETE /{office_id}/guarantees/{id}: Rimuovi garanzia.
• GET /{office_id}/exclusions: Lista utenti esclusi dal parcheggio.
• POST /{office_id}/exclusions: Aggiungi esclusione.
• DELETE /{office_id}/exclusions/{id}: Rimuovi esclusione.

Presence (/api/presence)

Gestione presenze giornaliere.

• POST /mark: Segna la propria presenza per una data (Presente/Remoto/Assente).
• GET /my-presences: Lista delle proprie presenze.
• DELETE /{date}: Rimuovi la propria presenza per una data.
• POST /admin/mark: Segna presenza per un altro utente (Manager/Admin).
• DELETE /admin/{user_id}/{date}: Rimuovi presenza di un altro utente (Manager/Admin).
• GET /team: Visualizza presenze e stato parcheggio del team.
• GET /admin/{user_id}: Storico presenze di un utente (Manager/Admin).
• POST /admin/clear-office-presence: Pulisce presenze e parcheggi di un ufficio per un range di date (Test/Admin).

Parking (/api/parking)

Gestione assegnazioni posti auto.

• POST /init-office-pool: Inizializza i posti disponibili per un giorno.
• GET /assignments/{date}: Lista assegnazioni per una data.
• GET /my-assignments: Le mie assegnazioni parcheggio.
• POST /run-allocation: Esegui manualmente l'algoritmo di assegnazione per una data.
• POST /clear-assignments: Cancella tutte le assegnazioni per una data.
• POST /manual-assign: Assegna manualmente un posto a un utente.
• POST /reassign-spot: Riassegna o libera un posto già assegnato.
• POST /release-my-spot/{id}: Rilascia il proprio posto assegnato.
• GET /eligible-users/{id}: Lista utenti idonei a ricevere un posto riassegnato.
• POST /test-email: Invia email di test (Test Tool).

Reports (/api/reports)

Esportazione dati.

• GET /team-export: Esporta dati presenze e parcheggi del team in Excel.

Utilizzo con AUTHELIA

Org-Parking supporta l'integrazione nativa con Authelia (o altri provider SSO compatibili con Forward Auth). Questo permette il Single Sign-On (SSO) e la gestione centralizzata degli utenti.

Configurazione

1. Abilita Authelia: Nel file .env, imposta AUTHELIA_ENABLED=true.

2. Configura gli Header del Proxy: Assicurati che il tuo reverse proxy (es. Traefik, Nginx) passi i seguenti header all'applicazione dopo l'autenticazione:

   • Remote-User: Username dell'utente (spesso uguale all'email).
   • Remote-Email: Email dell'utente.
   • Remote-Name: Nome completo dell'utente (Opzionale).
   • Remote-Groups: Gruppi di appartenenza (separati da virgola).

3. Gestione Admin: L'applicazione assegna automaticamente il ruolo di Admin agli utenti che appartengono al gruppo specificato nella variabile AUTHELIA_ADMIN_GROUP (default: parking_admins).

   • Se un utente viene rimosso da questo gruppo su Authelia, perderà i privilegi di admin al login successivo.
   • Gli altri ruoli (Manager, Employee) e l'assegnazione agli uffici vengono gestiti manualmente all'interno di Org-Parking da un amministratore.

Comportamento

• Creazione Utenti: Gli utenti vengono creati automaticamente nel database di Org-Parking al loro primo accesso riuscito tramite Authelia.
• Login/Logout: Le pagine di login e registrazione interne vengono disabilitate o reindirizzano al portale SSO.
• Password: Org-Parking non gestisce le password in questa modalità; l'autenticazione è interamente delegata al provider esterno.
• Sicurezza: L'applicazione si fida degli header Remote-* solo se AUTHELIA_ENABLED è attivo. Assicurarsi che il container non sia esposto direttamente a internet senza passare per il proxy di autenticazione.

Note di Deployment

• Database: SQLite è usato di default per semplicità e basso overhead. I dati persistono in ./data/parking.db.
• Sicurezza:
  • Rate limiting è attivo sugli endpoint sensibili (Login/Register).
  • Le password sono hashate con Bcrypt.
  • L'autenticazione via cookie è sicura di default.

Risoluzione Problemi Comuni

Errore: "Il reindirizzamento è stato determinato per essere non sicuro"

Questo errore appare se si tenta di accedere all'applicazione tramite HTTP (es. http://lvh.me:8000) mentre Authelia è su HTTPS. Authelia blocca i reindirizzamenti verso protocolli non sicuri. Soluzione: Accedere all'applicazione tramite il Reverse Proxy (Caddy) usando HTTPS, ad esempio https://parking.lvh.me. Assicurarsi che Caddy sia configurato per gestire il dominio e l'autenticazione.

Licenza

MIT