GASS Pagamenti

Sistema di gestione finanziaria per gruppi di acquisto solidale (GAS).

Panoramica

GASS Pagamenti è un'applicazione web completa per la gestione di:

• Registrazione consegne e transazioni
• Tracciamento saldi partecipanti (crediti e debiti)
• Storico completo delle operazioni
• Calcolo automatico cassa e compensazioni
• Audit trail completo delle modifiche

Caratteristiche

• Responsive Design: Interfaccia ottimizzata per mobile e desktop
• Calcoli Automatici: Cassa e compensazioni gestiti automaticamente
• Sicurezza: Autenticazione con sessioni, password cifrate
• Tracciabilità: Registrazione di tutte le modifiche (chi, quando)
• Database Locale: SQLite, nessuna dipendenza cloud
• Deploy Semplice: Container Docker ready

Documentazione

• Manuale Utente - Guida completa per utilizzatori
• Documentazione Tecnica - Riferimento per sviluppatori
• Guida Deploy - Istruzioni per installazione e configurazione

Quick Start

Requisiti

• Node.js v20 o superiore
• Docker (opzionale, consigliato per produzione)

Installazione Locale

# Clona il repository
git clone <repository-url>
cd gass

# Installa dipendenze
npm install

# Avvia in modalità sviluppo
npm run dev

L'applicazione sarà disponibile su http://localhost:3000

Credenziali predefinite:

• Username: admin
• Password: admin

⚠️ IMPORTANTE: Cambiare la password predefinita al primo accesso.

Deploy con Docker

# Build immagine
docker-compose build

# Avvia il servizio
docker-compose up -d

Il database sarà persistito in ./data/gass.db.

Per dettagli completi, vedere DEPLOYMENT.md.

Gestione Utenti

Utility completa per la gestione degli utenti da linea di comando:

Comandi disponibili:

# Elencare tutti gli utenti
node manage-users.js list

# Aggiungere nuovo utente
node manage-users.js add <username> <password> "<Nome Completo>"

# Cambiare password
node manage-users.js password <username> <nuova-password>

# Eliminare utente
node manage-users.js delete <username>

# Aiuto
node manage-users.js help

Esempi Docker:

# Elencare utenti
docker exec gass node manage-users.js list

# Aggiungere utente
docker exec gass node manage-users.js add john MyPass123 "John Smith"

# Cambiare password admin
docker exec gass node manage-users.js password admin NuovaPassword123

# Eliminare utente
docker exec gass node manage-users.js delete john

Caratteristiche:

• Validazione utenti esistenti
• Hash bcrypt sicuro (12 rounds)
• Protezione eliminazione ultimo utente
• Tabella formattata per listing utenti
• Messaggi di conferma chiari

⚠️ Sicurezza: Utilizzare sempre password forti in produzione (minimo 4 caratteri).

Stack Tecnologico

Backend

• Runtime: Node.js 20
• Framework: Express.js
• Database: SQLite3 (better-sqlite3)
• Autenticazione: express-session + bcrypt
• Architettura: MVC pattern

Frontend

• Linguaggio: Vanilla JavaScript (ES6+)
• Design: CSS responsive (mobile-first)
• Pattern: Component-based senza framework

Struttura Progetto

gass/
├── server/
│   ├── config/          # Database e configurazione
│   ├── routes/          # API endpoints
│   ├── services/        # Business logic
│   └── middleware/      # Auth, user agent detection
├── public/
│   ├── js/
│   │   ├── shared/      # Codice condiviso
│   │   ├── consegna.js  # Mobile views
│   │   └── *-desktop.js # Desktop views
│   ├── *.html           # Pagine HTML
│   └── style*.css       # Fogli di stile
├── docs/                # Documentazione
├── data/                # Database SQLite (gitignored)
└── server.js            # Entry point

Sviluppo

Comandi Disponibili

npm run dev        # Sviluppo con auto-restart (nodemon)
npm start          # Produzione
npm test           # Esegui test (se configurati)

Convenzioni

• I campi cassa sono sempre readonly - valori calcolati automaticamente
• I campi compensazione sono system-managed - no override manuale
• Sviluppare sempre per mobile E desktop contemporaneamente
• Test su viewports mobile (412px) e desktop (1920px)

Sicurezza

• ✅ Password cifrate con bcrypt (12 rounds)
• ✅ Sessioni sicure (httpOnly, secure in produzione)
• ✅ Audit trail completo (created_by, updated_by, timestamps)
• ✅ Protezione API con middleware autenticazione
• ✅ Gestione transazioni database per integrità dati

⚠️ Mai committare:

• data/ (database con dati sensibili)
• update-admin-password.js (script con password in chiaro)
• Credenziali o secrets

Contribuire

Per contribuire al progetto:

1. Leggere TECHNICAL.md per l'architettura
2. Seguire le convenzioni di sviluppo in CLAUDE.md
3. Testare su mobile e desktop
4. Commit con messaggi semantici: feat:, fix:, docs:, refactor:

Versione

Versione Corrente: 2.5.5

Changelog Recente:

• v2.5.5 (Feb 2026): Aggiornamento documentazione, visualizzazione transazioni aperta a tutti gli utenti
• v2.5.3 (Feb 2026): Storico transazioni per partecipante nella pagina Saldi
• v2.5.0 (Feb 2026): Tracking consegna_id nei log di attività
• v2.4.0 (Gen 2026): Pagina log attività per amministratori

Licenza

[Specificare licenza]

Supporto

Per problemi o domande:

• Consultare Manuale Utente
• Vedere Documentazione Tecnica
• Aprire una issue su GitHub