ORE
App per la timbratura ore dei dipendenti e il calcolo automatico degli stipendi. Due accessi separati nella stessa app: griglia dipendenti con PIN per timbrare i turni di oggi, e un'Area Titolare protetta da un codice a 6 cifre con dashboard, gestione dipendenti, richieste e riepiloghi. React + Vite, dati su Supabase, installabile come PWA da un semplice link.
1. Sviluppo locale
npm install
cp .env.example .env.local # poi inserisci URL e anon key del tuo progetto Supabase
npm run dev
2. Creare il progetto Supabase
- Vai su supabase.com, crea un account gratuito e un nuovo progetto (scegli una regione vicina, es. Frankfurt).
- Nel progetto, apri SQL Editor → New query, incolla tutto il contenuto di
supabase/schema.sql e premi Run. Questo crea le tabelle (employees, shifts, payments, edit_requests, absence_requests, settings), le policy di sicurezza, le funzioni RPC e il codice Titolare iniziale (123456). Il file è pensato per essere rieseguito in sicurezza: se lo lanci di nuovo su un progetto già impostato in precedenza (es. dopo un aggiornamento dell'app che aggiunge colonne o funzioni), non perdi i dati già presenti.
- Vai su Project Settings → API: copia Project URL e la chiave anon public.
- Incollali in
.env.local (in locale) e più avanti nelle variabili d'ambiente di Vercel (vedi sotto).
- Appena l'app è online, vai in Area Titolare → icona ingranaggio e cambia subito il codice
123456 con uno tuo.
Per aggiungere i primi dipendenti: Area Titolare (codice 123456 finché non lo cambi) → tab Dipendenti → Nuovo dipendente.
3. Pubblicare su Vercel (accesso via link, PWA)
- Vai su vercel.com e accedi con GitHub.
- Add New → Project, seleziona questo repository.
- Vercel riconosce automaticamente Vite: lascia i comandi di default (
npm run build, output dist).
- In Environment Variables aggiungi:
VITE_SUPABASE_URL = il Project URL di SupabaseVITE_SUPABASE_ANON_KEY = la chiave anon public
- Premi Deploy. Al termine ottieni un link pubblico (es.
https://tuoapp.vercel.app).
Da quel link:
- i dipendenti aprono la home (
/) e timbrano da lì;
- il Titolare apre
/titolare (link raggiungibile anche dal pulsante "Area Titolare" in fondo alla home).
Su iPhone: Safari → icona Condividi → Aggiungi a Home. Su Android: Chrome → menu → Installa app. L'app si comporta come un'app installata (icona propria, schermo intero).
4. Come funziona
Lato dipendente (/): sceglie il proprio nome dalla griglia, inserisce il PIN a 4 cifre. In cima vede subito un riquadro con le proprie ore da conteggiare (dall'ultimo pagamento registrato ad oggi, o "da sempre" se non è mai stato pagato) — solo le ore, mai il costo orario, che resta visibile solo al Titolare — e sotto i turni di oggi. Può registrare un nuovo turno (bloccato non appena salvato: non è più modificabile né cancellabile da lì), o toccare "Turno di un giorno passato": sceglie una data da un calendario a comparsa (mesi in italiano, giorni futuri disabilitati), e se quel giorno ha già un turno lo seleziona per correggerlo (motivo obbligatorio); se invece è vuoto (tipicamente tutti i giorni prima di iniziare a usare l'app) propone gli orari lavorati (nota facoltativa) — utile per compilare rapidamente lo storico arretrato. Entrambe restano "in attesa" finché il Titolare non decide; se accetta una proposta di giorno vuoto, il turno viene creato automaticamente. Può anche richiedere un'assenza: sceglie il periodo toccando il primo e l'ultimo giorno sullo stesso calendario (o lo stesso giorno due volte per un'assenza di un giorno solo), poi indica se è giornata intera o solo una fascia oraria di quel giorno (motivo facoltativo). Quando il Titolare accetta o rifiuta una richiesta, al successivo accesso col PIN il dipendente vede un avviso con l'esito e l'eventuale nota lasciata dal Titolare; una volta letto (pulsante "Ho capito") non ricompare più. Se invece il Titolare gli propone un turno (es. una sostituzione), al successivo accesso col PIN il dipendente vede subito la proposta (data, orario, nota) e deve accettarla o rifiutarla (motivo obbligatorio in caso di rifiuto) prima di continuare.
Lato Titolare (/titolare, codice a 6 cifre): tab Richieste (modifiche turno + assenze, con contatore, nota facoltativa e pulsanti accetta/rifiuta — la nota, se scritta, arriva al dipendente insieme all'esito; in cima, il pulsante Proponi turno apre invece il flusso opposto: il Titolare sceglie dipendente, data, orario e una nota facoltativa — es. il motivo di una sostituzione — e il turno proposto appare tra "Turni proposti da te" in attesa che il dipendente lo accetti o lo rifiuti; se accetta, il turno viene creato automaticamente; in entrambi i casi il Titolare riceve un'email con l'esito, se le notifiche sono configurate), Da pagare (ore non ancora pagate per dipendente, calcolate dall'ultimo pagamento registrato in poi — se il dipendente ha un giorno di paga impostato, mostra anche la prossima data prevista; cliccando su un dipendente (anche a 0h) si apre l'elenco dei turni che compongono il totale, modificabili o eliminabili sul posto, e l'elenco dei pagamenti registrati per lui, ciascuno modificabile (cambia la data "pagato fino al") o annullabile del tutto — utile se un pagamento è stato segnato per errore o su un periodo sbagliato: correggendolo o annullandolo, le ore coinvolte tornano subito visibili come da pagare; "Segna come pagato" salva solo la data fino a cui si è pagato, non un elenco dettagliato — se il dipendente ha un giorno di paga impostato, la data proposta di default non è "oggi" ma l'ultima scadenza già passata: così pagando in ritardo non si include per sbaglio nel pagamento anche il lavoro dei giorni successivi alla scadenza, che resta da pagare al periodo dopo; resta comunque modificabile; se un periodo è scaduto senza essere stato pagato, il totale viene mostrato spaccato in due — "Scaduto" fino all'ultima scadenza e "In corso" da lì ad oggi — così non restano mescolati in un'unica cifra), Dipendenti (nome, PIN, costo orario — mai visibile al dipendente — giorno di paga previsto, email facoltativa per le notifiche, attivo/disattivato), Turni (apre, modifica o elimina qualsiasi turno di qualsiasi dipendente, anche passato, o ne aggiunge uno dimenticato), Riepilogo (vista mensile navigabile avanti/indietro, ore e costo per dipendente — cliccando su un dipendente si apre e modifica l'elenco dei turni del mese — resta consultabile anche dopo il pagamento, esportabile in PDF/Excel per singolo dipendente o aggregato).
Le ore vengono calcolate al minuto esatto (nessun arrotondamento). Le date "di oggi" e la soglia chiaro/scuro automatica usano sempre il fuso orario Europe/Rome, indipendentemente dal fuso del dispositivo.
5. Notifiche email (facoltativo)
Al Titolare, ogni volta che un dipendente invia una richiesta (modifica turno, nuovo turno passato, assenza):
- Crea un account gratuito su resend.com (fino a 3000 email/mese gratis, nessuna carta richiesta).
- Nella dashboard di Resend, vai su API Keys → Create API Key e copiala (inizia con
re_...).
- Nell'app: Area Titolare → icona ingranaggio → sezione Notifiche email → inserisci la tua email e incolla la chiave → Salva notifiche.
Al dipendente, quando il Titolare accetta o rifiuta una sua richiesta: basta impostargli un'email nel modulo Dipendenti (campo facoltativo). Chi non ha un'email impostata continua a vedere l'esito solo in-app al prossimo accesso col PIN, come sempre.
Il mittente delle email è impostato nel file schema.sql (funzione send_email, riga con 'ORE <[email protected]>'): con il mittente di test di Resend ([email protected]) si può mandare solo alla propria email dell'account Resend, non a indirizzi esterni come quelli dei dipendenti — per quello serve verificare un dominio proprio su Resend (Domains → Add Domain, poi aggiungere i record DNS indicati) e aggiornare quella riga con l'indirizzo scelto sul proprio dominio. Se non configuri nulla, l'app funziona esattamente come prima: è tutto opzionale e non blocca mai l'invio/risoluzione di una richiesta anche se l'email non parte.
6. Note sulla sicurezza dei PIN e del codice Titolare
Come nel progetto Scontrino, l'accesso è tramite PIN/codice condiviso (non ci sono account personali): pensato per un uso interno, non equivalente ad account personali con permessi differenziati.
- Nessuna tabella (
employees, shifts, edit_requests, absence_requests, payments, settings) ha mai una policy di lettura o scrittura pubblica: nulla è raggiungibile con una query diretta dal browser.
- Ogni funzione riservata del database (gestione dipendenti, turni, richieste, pagamenti, impostazioni) verifica da sé il codice Titolare o il PIN del dipendente a ogni chiamata, non solo una volta dall'interfaccia: chi conoscesse l'URL pubblico del progetto Supabase e provasse a chiamare quelle funzioni direttamente, scavalcando l'app, verrebbe comunque respinto senza il codice/PIN giusto.
- L'app tiene il codice/PIN già verificato in
sessionStorage del browser (si perde chiudendo la scheda) e lo ripresenta da sola a ogni chiamata successiva: per chi usa l'app non cambia nulla, si inserisce una volta sola come sempre.
- PIN dei dipendenti, costo orario e codice Titolare non sono mai leggibili con una query diretta: la griglia dipendenti usa una vista pubblica (
employees_public) che espone solo id e nome, e la verifica di PIN/codice avviene tramite funzioni RPC che restituiscono solo "corretto/sbagliato".
- La chiave API di Resend (se configurata) segue lo stesso principio: si scrive tramite una funzione RPC ma non è mai restituita in chiaro — l'interfaccia sa solo dire "impostata" o "non impostata". L'invio email stesso non è richiamabile dall'esterno: lo usano solo i trigger interni dell'app, mai una chiamata diretta.
- Per cambiare il codice Titolare serve conoscere quello attuale (non basta più indovinarne uno nuovo).
Cosa non copre questo modello, da tenere presente:
- È un codice condiviso, non un account personale: chi conosce il PIN di un collega può usarlo come se fosse lui. Per permessi differenziati per persona servirebbe Supabase Auth, un'estensione possibile in futuro ma non necessaria per l'uso interno attuale.
- Non c'è un limite ai tentativi di PIN/codice (nessun blocco dopo N tentativi sbagliati): un PIN a 4 cifre resta in teoria indovinabile da uno script che ne provi tanti di seguito, molto lentamente nel tempo.
Se cambi dominio Supabase o rigeneri la chiave anon, nessuna di queste protezioni cambia comportamento: restano valide a prescindere da chi conosce l'URL del progetto.
Struttura del progetto
src/App.jsx — instradamento minimale tra / (dipendente) e /titolare (Titolare).src/pages/EmployeeSide.jsx — griglia, PIN, turni di oggi, richieste.src/pages/OwnerSide.jsx — login Titolare, tab della dashboard.src/components/owner/ — Dipendenti, Turni, Richieste, Da pagare, Riepilogo mensile.src/context/ThemeContext.jsx — tema chiaro/scuro automatico (fuso Europe/Rome) + override manuale.src/lib/api.js — tutte le letture/scritture verso Supabase (aggiunge automaticamente codice/PIN a ogni chiamata riservata).src/lib/session.js — tiene in sessionStorage il codice Titolare o il PIN appena verificati, per la durata della scheda del browser.src/lib/time.js — date/ore sempre in fuso Europe/Rome, formattazioni.src/lib/export.js — esportazione riepiloghi in PDF/Excel.supabase/schema.sql — schema del database da eseguire una sola volta su Supabase.
