Gestione Soci ANCR

Applicazione web per la gestione dei soci dell'Associazione Nazionale Combattenti e Reduci (ANCR).

🚀 Installazione Rapida: Per una guida di installazione semplificata, consulta INSTALLAZIONE_RAPIDA.md 📝 Release Notes: Consulta le novità della versione v1.3.0

Funzionalità

👥 Gestione Soci

Gestione completa dei soci (aggiunta, modifica, eliminazione)
Possibilità di eliminare soci anche se hanno tessere associate
Gestione delle tessere associative
Gestione degli utenti con diversi livelli di accesso (amministratore, segretario, operatore)

📧 Sistema Email

Sistema di comunicazione email integrato
Invio email personalizzate ai soci (singole e multiple)
Invio email agli utenti del sistema (solo per amministratori e segretari)
Personalizzazione messaggi con placeholder automatici
Firma automatica dell'associazione e informazioni GDPR

📊 Reporting e Export

Esportazione dei dati in formato CSV ed Excel (solo soci con tessere valide)
Dashboard con statistiche

🌐 Accesso Pubblico

Modulo di iscrizione pubblico accessibile senza login
Accessibile dalla pagina di login tramite link dedicato
Calcolo automatico del codice fiscale
Protezione anti-spam con CAPTCHA
Generazione automatica di immagini CAPTCHA per prevenire iscrizioni automatizzate
Notifiche email all'amministratore per nuove richieste di iscrizione
Configurabili tramite le impostazioni email nel file .env

🏛️ Gestione Patrimonio

Sistema completo di gestione beni patrimoniali
Gestione cessioni, prestiti e donazioni
Registrazione restituzioni con stato del bene
Generazione documenti PDF per cessioni

📋 NUOVO: Passaggio di Consegne e Storicizzazione

Storicizzazione completa del patrimonio: Snapshot immutabile di tutti i beni al momento del passaggio
Documenti ufficiali: Generazione automatica di PDF professionali per passaggi di consegne
Tracciabilità storica: Ogni passaggio mantiene i dati esatti del momento della consegna
Ristampa fedele: I PDF storici riflettono sempre la situazione originale del patrimonio
Gestione responsabilità: Documentazione ufficiale per trasferimenti tra amministrazioni
Conformità normativa: Supporto per audit, controlli e verifiche amministrative

📱 NUOVO: Sistema QR Code

Generazione schede QR: Crea schede stampabili con QR code per ogni bene
Visualizzazione pubblica: Accesso ai dettagli del bene tramite QR code senza login
Design responsive: Template ottimizzato per dispositivi mobili e desktop
Tracciabilità completa: Ogni bene ha un QR code univoco per accesso rapido
PDF professionale: Schede generate automaticamente con layout professionale

Requisiti

Python 3.8 o superiore
Pip (gestore pacchetti Python)
SQLite (database predefinito) o altro database supportato da SQLAlchemy

Installazione

🚀 Installazione Automatica (Consigliato)

Per una nuova installazione rapida e senza problemi:

bash ./install.sh

Lo script automatico gestisce: - ✅ Creazione ambiente virtuale - ✅ Installazione dipendenze compatibili - ✅ Configurazione file .env - ✅ Inizializzazione database - ✅ Creazione utente admin - ✅ Setup sistema migrazioni

Tempo stimato: 2-3 minuti

📋 Installazione Manuale

Se preferisci il controllo manuale:

Ambiente virtuale ```bash python3 -m venv venv source venv/bin/activate # macOS/Linux

oppure venv\Scripts\activate # Windows

```

Dipendenze essenziali bash pip install flask flask-sqlalchemy flask-migrate flask-login flask-mail flask-wtf wtforms werkzeug python-dotenv reportlab markdown qrcode[pil]
Dipendenze opzionali (per Excel) bash pip install pandas openpyxl
Configurazione ```bash cp .env.sample .env

Modifica .env con le tue impostazioni se necessario

```

Inizializzazione database e admin bash python -c "from app import app, db; app.app_context().push(); db.create_all()" python -c " from app import app, db from models.utente import Utente from werkzeug.security import generate_password_hash app.app_context().push() admin = Utente(username='admin', email='admin@example.com', password_hash=generate_password_hash('admin'), ruolo='admin') db.session.add(admin) db.session.commit() print('Admin creato') "

Configurazione

Il file .env viene creato automaticamente con configurazioni funzionanti. Per personalizzazioni avanzate:

```env

Configurazione applicazione

SECRET_KEY=la-tua-chiave-segreta-molto-lunga-e-sicura DATABASE_URL=sqlite:///gest_2025.db

Configurazione server Flask

FLASK_RUN_HOST=0.0.0.0 FLASK_RUN_PORT=5000

Configurazione email (opzionale per sviluppo)

MAIL_SERVER=smtp.example.com MAIL_PORT=587 MAIL_USE_TLS=True MAIL_USE_SSL=False MAIL_USERNAME=tuo-indirizzo@example.com MAIL_PASSWORD=tua-password MAIL_DEFAULT_SENDER=tuo-indirizzo@example.com ADMINS=admin@example.com

Configurazioni Associazione

ASSOCIATION_FEDERATION=FEDERAZIONE POTENZA MATERA ASSOCIATION_NAME=ANCR - Sezione di Avigliano ASSOCIATION_URL=https://gestionale.ancravigliano.it/ ASSOCIATION_TITLE=Bartolo Gianturco ASSOCIATION_ADDRESS=Via Roma, 1 - 85021 Avigliano (PZ) ASSOCIATION_PHONE=+39 0971 123456 ASSOCIATION_EMAIL=info@ancravigliano.it ```

Note importanti:

Il file .env è obbligatorio per il corretto funzionamento
Utilizza il file .env.sample come punto di partenza
In produzione, cambia sempre SECRET_KEY
Le configurazioni email sono opzionali per lo sviluppo

Avvio dell'applicazione

bash python -m flask run

L'applicazione sarà disponibile all'indirizzo http://127.0.0.1:5000/

Accesso

Credenziali predefinite per l'amministratore:

Username: admin
Password: admin
URL: http://127.0.0.1:5000

⚠️ Importante: Cambiare la password dopo il primo accesso!

📱 Utilizzo Sistema QR Code

Generazione Schede QR

Accedi al sistema e vai alla sezione "Patrimonio"
Seleziona un bene dalla lista
Nel dettaglio del bene, clicca su "Scheda con QR Code"
Verrà generato un PDF stampabile con:
Dettagli completi del bene
QR code per accesso rapido
Layout professionale per stampa

Visualizzazione Pubblica

Scansiona il QR code con qualsiasi smartphone/tablet
Accesso immediato ai dettagli del bene senza login
Visualizzazione ottimizzata per dispositivi mobili
Informazioni complete: nome, categoria, ubicazione, valutazione, stato

Casi d'uso

Inventario fisico: Applica etichette QR sui beni per identificazione rapida
Controlli periodici: Verifica stato e ubicazione tramite scansione
Trasferimenti: Documenta spostamenti e cessioni
Audit: Accesso rapido alle informazioni durante verifiche

📋 Utilizzo Sistema Passaggio di Consegne

Creazione Passaggio di Consegne

Accedi al sistema con credenziali di Amministratore o Segretario
Vai alla sezione "Patrimonio" dal menu principale
Clicca su "Passaggio di Consegne" per iniziare il processo
Compila i dati del consegnante:
Nome e cognome dell'amministratore uscente
Ruolo (es. Presidente, Tesoriere, Segretario)
Data di consegna
Compila i dati del ricevente:
Nome e cognome del nuovo amministratore
Ruolo nella nuova amministrazione
Data di ricevimento
Aggiungi note (opzionale): Osservazioni o annotazioni particolari
Clicca "Genera Passaggio di Consegne"

Cosa Succede Automaticamente

Snapshot completo: Il sistema salva istantaneamente tutti i beni patrimoniali
Calcolo statistiche: Numero totale beni e valore complessivo
Generazione PDF: Documento ufficiale pronto per la stampa e firma
Archiviazione permanente: I dati vengono salvati in modo immutabile

Visualizzazione Storico

Dalla sezione "Patrimonio", clicca su "Storico Passaggi"
Visualizza l'elenco di tutti i passaggi effettuati con:
Data del passaggio
Nomi di consegnante e ricevente
Numero beni e valore totale al momento del passaggio
Scarica PDF storici cliccando su "Scarica PDF"

Caratteristiche Chiave

Immutabilità: I dati storici non possono essere modificati
Fedeltà temporale: Ogni PDF riflette esattamente la situazione del momento
Tracciabilità completa: Audit trail per ogni trasferimento di responsabilità
Conformità legale: Documentazione ufficiale per controlli e verifiche

Casi d'Uso Tipici

Elezioni: Passaggio tra vecchia e nuova amministrazione
Cambio cariche: Trasferimento responsabilità specifiche
Audit annuali: Documentazione periodica del patrimonio
Controlli esterni: Supporto per verifiche di enti di controllo

Struttura del progetto

app.py: File principale dell'applicazione
config.py: Configurazioni dell'applicazione (legge dal file .env)
.env: File di configurazione con variabili d'ambiente
.env.sample: Template di esempio per la configurazione
models/: Modelli del database
database.py: Configurazione del database
socio.py: Modello per i soci
tessera.py: Modello per le tessere
utente.py: Modello per gli utenti
bene_patrimoniale.py: Modello per i beni patrimoniali
passaggio_consegne.py: Modello per i passaggi di consegne
bene_passaggio_snapshot.py: Modello per la storicizzazione dei beni
codice_fiscale.py: Utility per il calcolo del codice fiscale
templates/: Template HTML
static/: File statici (CSS, JavaScript, immagini)
data/: Dati dell'applicazione
uploads/: Cartella per i file caricati

🆘 Risoluzione Problemi

Problemi Comuni

Errore Pandas/Excel ```bash

L'app funziona comunque, solo l'export Excel sarà limitato

pip install openpyxl # Per supporto Excel base ```

Errore Werkzeug/url_parse bash pip install werkzeug==2.3.7 # Versione compatibile

Database Locked ```bash rm gest_2025.db # Rimuovi database esistente

Poi riesegui l'inizializzazione

```

Credenziali non accettate ```bash

Resetta password admin

python -c " from app import app, db from models.utente import Utente from werkzeug.security import generate_password_hash app.app_context().push() admin = Utente.query.filter_by(username='admin').first() admin.password_hash = generate_password_hash('admin') db.session.commit() " ```

Backup del database

Per effettuare un backup del database SQLite:

bash sqlite3 gest_2025.db .dump > backup.sql

Per ripristinare il database da un backup:

bash sqlite3 gest_2025.db < backup.sql

Aggiornamenti

Per aggiornare l'applicazione:

bash git pull # Se usi git source venv/bin/activate pip install -r requirements.txt # Nuove dipendenze flask db upgrade # Aggiorna database

Licenza

Questo progetto è rilasciato sotto licenza MIT.