TerManager2

Applicazione web per la gestione dell'assegnazione e rientro di territori (cartoline), statistiche di percorrenza e campagne speciali per congregazioni.

---

Indice

• Panoramica
• Stack tecnologico
• Requisiti di sistema
• Installazione rapida
• Configurazione
• Struttura del progetto
• Funzionalità principali
• Ruoli e permessi (RBAC)
• Sicurezza e GDPR
• Modello dati
• Regole di business
• Pagine dell'applicazione
• Comandi utili
• Produzione
• Licenza

---

Panoramica

TerManager2 gestisce:

• Territori (cartoline) con PDF allegato, stato dinamico (in reparto / assegnato / da rientrare / prioritario / inattivo), zona e tipologia.
• Proclamatori (assegnatari) con dati personali cifrati a livello di colonna nel database (AES-256-CBC tramite APP_KEY).
• Assegnazioni con data assegnazione/rientro, anno teocratico, conteggio opzionale in campagna.
• Campagne (periodi speciali) con percentuali di percorrenza in tempo reale.
• Dashboard con media mensile di percorrenza, campagna attiva, e tre liste rapide (da assegnare, prioritari, da rientrare).
• Registro delle assegnazioni filtrabile per anno teocratico, zona, stato.
• Audit Log completo di tutte le azioni utente con diff before/after.

---

Stack tecnologico

Componente	Tecnologia
Framework	Laravel 11.x
PHP	8.3-FPM
UI	Livewire 3.5 + TailwindCSS 4.0 + Alpine.js
Database	MariaDB 11
Cache/Session	Redis 7 (Alpine)
Web Server	Nginx 1.25 (Alpine)
Auth	Laravel Breeze 2.0
RBAC	spatie/laravel-permission 6.4
Audit Trail	spatie/laravel-activitylog 4.8
Asset Build	Vite 6.0 + @tailwindcss/vite
Node.js	20 LTS (nel container PHP)
Mail (dev)	Mailpit
Container	Docker Compose (5 servizi)

---

Requisiti di sistema

• Docker >= 24.0 e Docker Compose >= 2.20
• Oppure, senza Docker:
  • PHP >= 8.3 con estensioni: pdo_mysql, mbstring, gd, intl, zip, bcmath, redis, opcache
  • Composer >= 2.7
  • Node.js >= 20 LTS + npm
  • MariaDB >= 11 (o MySQL 8)
  • Redis >= 7

---

Installazione

Prerequisiti

• Docker e Docker Compose (v2) installati
• Porte libere: 8080 (app), 3306 (MariaDB), 6379 (Redis), 8025 (Mailpit)

Procedura

# 1. Clona il repository
git clone <repository-url> termanager2
cd termanager2

# 2. Configura l'ambiente
cp .env.example .env

# 3. Imposta i permessi dei file (UID 1000 = appuser nel container)
chown -R 1000:1000 .
mkdir -p storage/app/public storage/framework/{cache/data,sessions,views} storage/logs bootstrap/cache
chmod -R 775 storage bootstrap/cache

# 4. Avvia i container (build al primo avvio)
docker compose up -d --build

Il codice applicativo e montato direttamente dal filesystem host, quindi ogni modifica locale e immediatamente visibile nel container (senza rebuild ad ogni edit).

Al primo avvio del container app vengono eseguiti automaticamente:

• setup .env e APP_KEY
• install/build dipendenze
• php artisan migrate --force
• php artisan db:seed --force solo al primo avvio (marker persistente)

Nota: La APP_KEY viene generata automaticamente al primo avvio se assente nel .env.

Al termine l'applicazione sarà disponibile su: http://localhost:8080

Reset completo

Per ripartire da zero (elimina database e volumi):

docker compose down -v --remove-orphans
docker compose up -d --build
# Ripetere i passaggi dal punto 4 in poi

---

Configurazione

Variabili d'ambiente principali (.env)

Variabile	Default	Descrizione
APP_KEY	(generata)	Chiave AES-256 per cifratura. Mai condividere
APP_PORT	8080	Porta host per l'applicazione
SEED_DEV_DATA	false	Se true, php artisan db:seed include anche i dati demo
RUN_DB_SEED_ON_FIRST_START	true	Se true, esegue il seed automatico solo al primo avvio container
DB_DATABASE	termanager2	Nome database MariaDB
DB_USERNAME	termanager2	Utente database
DB_PASSWORD	secret	Password database
DB_ROOT_PASSWORD	rootsecret	Password root MariaDB
REDIS_PASSWORD	redissecret	Password Redis
MAIL_PORT	1025	Porta SMTP Mailpit
MAILPIT_UI_PORT	8025	UI Mailpit per debug email
USER_ID / GROUP_ID	1000	UID/GID container (match con host)

Configurazione iniziale

La configurazione viene gestita dalla sezione Impostazioni (menu amministrazione), senza wizard iniziale.

Utenti di sviluppo (DevSeeder)

Ruolo	Email	Password
Amministratore	admin@termanager2.local	password
Assistente	assistente@termanager2.local	password
Operatore	operatore@termanager2.local	password

Attenzione: cambiare le password prima di qualsiasi uso in produzione.

---

Struttura del progetto

TerManager2/
├── app/
│   ├── Console/Commands/          # AuditCleanup (pulizia log schedulata)
│   ├── Http/Middleware/           # Middleware HTTP applicativi
│   ├── Livewire/
│   │   ├── Assegnazioni/         # Assegna, Rientra
│   │   ├── Auth/                 # Login
│   │   ├── Campagne/             # Index, Create, Edit, Show
│   │   ├── Proclamatori/         # Index, Create, Edit, Show, Cestino
│   │   ├── Settings/             # SettingsEdit, ZoneIndex, TipologieIndex
│   │   ├── Territori/            # Index, Create, Edit, Show, Cestino
│   │   ├── AuditLog.php          # Log attività (filtri, diff)
│   │   ├── Home.php              # Dashboard
│   │   └── Registro.php          # Registro assegnazioni
│   ├── Models/                   # 8 modelli Eloquent
│   └── Providers/                # AppServiceProvider (Gate admin)
├── bootstrap/                    # app.php (middleware), providers.php
├── config/                       # app, auth, database, session
├── database/
│   ├── migrations/               # 10 migrazioni ordinate
│   └── seeders/                  # Roles, Dev, Database seeders
├── docker/
│   ├── nginx/default.conf        # Vhost con security headers
│   └── php/
│       ├── Dockerfile            # PHP 8.3-FPM + estensioni + Composer + Node 20
│       └── php.ini               # 64M upload, opcache, Europe/Rome
├── public/index.php              # Entry point Laravel
├── resources/
│   ├── css/app.css               # TailwindCSS 4 import
│   ├── js/                       # app.js, bootstrap.js (Axios)
│   └── views/
│       ├── components/layouts/   # app.blade.php (sidebar), guest.blade.php
│       └── livewire/             # Tutte le viste dei componenti
├── routes/
│   ├── web.php                   # Tutte le rotte con permessi
│   └── console.php               # Schedule audit:cleanup daily
├── .env.example                  # Template configurazione
├── artisan                       # CLI Laravel
├── composer.json                 # Dipendenze PHP
├── docker-compose.yml            # 5 servizi (app, nginx, mariadb, redis, mailpit)
├── package.json                  # Dipendenze Node (Vite, TailwindCSS)
└── vite.config.js                # Vite + Laravel plugin + TailwindCSS plugin

---

Funzionalità principali

Dashboard (Home)

• Anno teocratico corrente (auto-creato se mancante, Set→Ago)
• Media mensile di percorrenza (territori rientrati / mesi trascorsi)
• Campagna attiva con barra di progresso percentuale
• Tre liste rapide con azione diretta:
  • Da assegnare: territori in reparto, ordinati per priorità
  • Prioritari: flag manuale O soglia automatica (la soglia vince sempre)
  • Da rientrare: assegnazioni oltre la soglia giorni configurata

Territori

• CRUD completo con upload/sostituzione PDF
• Filtri per zona, tipologia, stato (in_reparto, assegnato, da_rientrare, inattivo)
• Badge di stato colorati + indicatore priorità (Manuale/Automatico)
• Dettaglio con PDF viewer inline e storico assegnazioni per anno teocratico
• Toggle attivo/inattivo e prioritario
• Soft delete con cestino (ripristino o eliminazione definitiva)

Proclamatori

• CRUD con campi nome/cognome cifrati nel DB (AES-256-CBC)
• Ricerca in-memory (necessaria per campi cifrati, ottimizzata per < 200 record)
• Conteggio territori attualmente assegnati
• Toggle attivo/inattivo
• Anonimizzazione GDPR (sostituzione dati con placeholder irreversibile)
• Soft delete con cestino

Assegnazione / Rientro

• Selezione territorio disponibile + proclamatore attivo
• Data assegnazione con auto-detection anno teocratico
• Validazione: territorio non già assegnato, entrambi attivi
• Rientro con calcolo automatico giorni
• Prompt retroattivo campagna: se l'assegnazione ricade nel range di una campagna, viene chiesto se conteggiare il rientro

Campagne

• CRUD con date inizio/fine e descrizione
• Stato automatico (Attiva/Futura/Conclusa)
• Percentuale percorrenza in tempo reale (conteggiati / totali assegnati nel range)
• Dettaglio con lista territorio-per-territorio dei conteggiati

Registro Assegnazioni

• Filtri: anno teocratico, zona, stato (aperte/chiuse), ricerca testo
• Colonne: territorio, proclamatore, date, giorni, campagna

Audit Log

• Log automatico su tutti i modelli (spatie/laravel-activitylog)
• Log manuale per eventi di flusso (assign, return, login, logout)
• Filtri per utente, tipo evento, ricerca testo
• Dettaglio con diff before/after (properties JSON espanso)
• Pulizia automatica schedulata (audit:cleanup — retention configurabile)

Impostazioni

• Nome congregazione
• Soglia mesi priorità automatica
• Soglia giorni per "da rientrare"
• Retention giorni audit log

Zone e Tipologie

• CRUD inline (aggiungi, rinomina, attiva/disattiva, elimina)
• Protezione: non eliminabile se ha territori associati

---

Ruoli e permessi (RBAC)

Tre ruoli con permessi granulari gestiti da spatie/laravel-permission:

Permesso	Amministratore	Assistente	Operatore
settings.manage	✅
territori.manage	✅
proclamatori.manage	✅	✅
campagne.manage	✅	✅
territori.assign	✅	✅	✅
territori.return	✅	✅	✅
registro.view	✅	✅
registro.export	✅
audit.view	✅
audit.export	✅

L'amministratore ha un bypass completo via Gate::before nel AppServiceProvider.

Il menu sidebar mostra solo le voci per cui l'utente ha permesso.

---

Sicurezza e GDPR

Sicurezza

• Cifratura a riposo: nome e cognome proclamatori cifrati con encrypted cast (AES-256-CBC via APP_KEY)
• Password: hash bcrypt (standard Laravel)
• RBAC: middleware permission: su ogni rotta
• CSRF: token integrato in tutti i form Livewire
• Rate limiting: login con throttle configurabile
• Security headers: X-Frame-Options, X-Content-Type-Options, X-XSS-Protection (via Nginx)
• Sessioni: Redis con cookie termanager2_session (httpOnly, secure in produzione)

GDPR

• Minimizzazione: solo nome, cognome e stato attivo per i proclamatori
• Cifratura a riposo: dati illeggibili con accesso diretto al DB
• Audit trail: log completo di tutte le operazioni sui dati
• Diritto all'oblio: metodo anonimizza() sul Proclamatore (sostituisce dati con placeholder)
• Retention: pulizia automatica dei log audit oltre il periodo configurato
• Ruoli e autorizzazioni: accesso ai dati solo per chi ha permessi specifici
• No log di dati sensibili: l'audit log registra proclamatore_id ma non nome/cognome in chiaro nei properties

---

Modello dati

Tabelle principali (10 migrazioni)

Tabella	Descrizione
users	Utenti app con auth standard Laravel
settings	Configurazione singleton (congregazione, soglie, retention)
zone	Zone territoriali (id, nome, attivo)
tipologie	Tipologie territorio (id, nome, attivo)
proclamatori	Assegnatari con nome/cognome cifrati, soft delete
territori	Cartoline con zona, tipologia, PDF, soft delete
anni_teocratici	Periodi Set→Ago con label univoca
campagne	Periodi speciali con date e descrizione
assegnazioni	Join territorio↔proclamatore con date, anno, campagna
activity_log	Audit trail (spatie/laravel-activitylog)

Indici e vincoli

• territori.numero — UNIQUE
• anni_teocratici.label — UNIQUE
• assegnazioni(territorio_id, returned_at) — INDEX composito
• assegnazioni(proclamatore_id, returned_at) — INDEX composito
• assegnazioni(anno_teocratico_id) — INDEX
• FK con RESTRICT su territorio e proclamatore (protezione integrità)

---

Regole di business

Anno teocratico

• Settembre → Agosto: se mese ≥ 9 → anno = corrente/corrente+1; se mese ≤ 8 → anno = corrente-1/corrente
• Creato automaticamente se non esiste (metodo AnnoTeocratico::perData())
• L'assegnazione conta per l'anno determinato dalla data di assegnazione

Stato territorio (calcolato dinamicamente)

• in_reparto: attivo, nessuna assegnazione aperta
• assegnato: ha assegnazione con returned_at = null
• da_rientrare: assegnato da più giorni della soglia configurata
• inattivo: attivo = false

Priorità

• Manuale: flag prioritario = true impostato dall'admin
• Automatica: nessuna assegnazione negli ultimi N mesi (soglia configurabile)
• La soglia automatica vince sempre sul flag manuale (l'admin può aggiungere ma non rimuovere se la soglia scatta)

Campagne — percentuale percorrenza

• Denominatore: tutti i territori assegnati nel range della campagna
• Numeratore: assegnazioni conteggiate in campagna (counted_in_campaign = true)
• Il prompt retroattivo appare al rientro se l'assegnazione è nel range di una campagna

---

Comandi utili

# Avviare i container
docker compose up -d

# Fermare i container
docker compose down

# Shell nel container app
docker compose exec app bash

# Eseguire migrazioni
docker compose exec app php artisan migrate

# Seed dati di sviluppo
docker compose exec app php artisan db:seed

# Compilare asset (dev con hot reload)
docker compose exec app npm run dev

# Compilare asset (produzione)
docker compose exec app npm run build

# Pulizia manuale audit log
docker compose exec app php artisan audit:cleanup

# Cache configurazione (produzione)
docker compose exec app php artisan config:cache
docker compose exec app php artisan route:cache
docker compose exec app php artisan view:cache

# Svuotare cache
docker compose exec app php artisan optimize:clear

---

Produzione

Per il deploy in produzione:

1. Variabili d'ambiente:

   • APP_ENV=production
   • APP_DEBUG=false
   • Password sicure per DB e Redis (non i default)
   • APP_KEY generata e conservata come secret

2. HTTPS: configurare un reverse proxy (Traefik, Nginx) con certificato SSL/TLS e HSTS

3. Immagini Docker: build senza volume codice montato, asset pre-compilati

4. Backup: backup cifrati del database con rotazione automatica

5. Segreti: gestire APP_KEY, password DB/Redis con Docker secrets o secret manager

6. Performance:

   • php artisan config:cache && route:cache && view:cache
   • OPcache abilitato (già configurato in php.ini)
   • Redis per cache, sessioni e code

7. Monitoraggio: configurare health checks e log aggregation

---

Licenza

Progetto privato — tutti i diritti riservati.