Territory Manager

Sistema di gestione territori per cartoline della città. Web application PHP semplice, moderna e facilmente manutenibile.

Caratteristiche

• ✅ Gestione completa territori (CRUD)
• ✅ Sistema di assegnazioni con tracking
• ✅ Link temporanei per condivisione territori
• ✅ Dashboard con liste automatiche:
  • Territori da assegnare
  • Territori prioritari
  • Territori da riconsegnare
• ✅ Statistiche in tempo reale
• ✅ Media percorrenza mensile e annuale
• ✅ Upload immagini piantine territori
• ✅ Export PDF delle liste
• ✅ Sistema di autenticazione
• ✅ Pannello amministrazione
• ✅ Design moderno e responsive

Requisiti

• PHP 7.4 o superiore
• MySQL 5.7 o superiore
• Web Server (Apache/Nginx)
• Estensioni PHP:
  • PDO
  • pdo_mysql
  • GD (per gestione immagini)

Installazione

1. Copia i file

Copia tutti i file nella cartella del tuo web server (es. htdocs, www, public_html).

2. Crea il database

Accedi a phpMyAdmin o dalla riga di comando MySQL:

CREATE DATABASE territory_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Importa lo schema del database:

mysql -u root -p territory_manager < database.sql

Oppure copia il contenuto di database.sql ed eseguilo in phpMyAdmin.

3. Configura la connessione

Modifica il file config.php con i tuoi dati:

define('DB_HOST', 'localhost');
define('DB_NAME', 'territory_manager');
define('DB_USER', 'tuo_utente');
define('DB_PASS', 'tua_password');

4. Crea la cartella uploads

Assicurati che la cartella uploads esista e abbia i permessi corretti:

mkdir uploads
chmod 755 uploads

5. Accedi al sistema

Apri il browser e vai all'URL della tua installazione:

http://tuosito.com/territory-manager/

Credenziali di default:

• Username: admin
• Password: admin123

⚠️ IMPORTANTE: Cambia immediatamente la password dopo il primo accesso!

Struttura File

territory-manager/
├── config.php              # Configurazione applicazione
├── db.php                  # Gestione database
├── functions.php           # Funzioni helper
├── database.sql            # Schema database
├── index.php               # Dashboard principale
├── login.php               # Pagina login
├── logout.php              # Logout
├── header.php              # Template header
├── footer.php              # Template footer
├── territories.php         # Gestione territori
├── assignments.php         # Gestione assegnazioni
├── statistics.php          # Statistiche
├── settings.php            # Impostazioni (admin)
├── export_pdf.php          # Export PDF
├── view_territory.php      # Visualizzazione pubblica territorio
├── style.css               # Stili CSS
├── script.js               # JavaScript
├── uploads/                # Cartella immagini (da creare)
└── README.md               # Questo file

Utilizzo

Dashboard

La dashboard mostra tre liste principali:

• Territori da Assegnare: Territori in reparto da più di X giorni
• Territori Prioritari: Territori in reparto da più di Y giorni
• Territori da Riconsegnare: Territori assegnati da più di Z giorni

I tempi sono configurabili nelle Impostazioni.

Gestione Territori

1. Vai su "Territori" nel menu
2. Clicca "+ Nuovo Territorio"
3. Compila i campi:
   • Numero territorio
   • Zona
   • Tipologia
   • Carica piantina (opzionale)
   • Note (opzionale)

Assegnazione Territorio

1. Dalla dashboard, clicca "Assegna" su un territorio disponibile
2. Oppure vai su "Assegnazioni" → "+ Nuova Assegnazione"
3. Compila:
   • Seleziona territorio
   • Nome assegnatario
   • Data assegnazione
   • Priorità (opzionale)
4. Viene generato automaticamente un link temporaneo

Link Temporanei

Quando assegni un territorio, viene creato un link unico che permette di visualizzare il territorio senza login.

Il link scade dopo X giorni (configurabile) e mostra:

• Dettagli territorio
• Piantina
• Informazioni assegnazione

Riconsegna

1. Vai su "Assegnazioni"
2. Clicca "Riconsegna" sul territorio da restituire
3. Conferma la data di restituzione

Statistiche

La pagina Statistiche mostra:

• Totale territori
• Territori assegnati/disponibili
• Attività ultimi 7 giorni
• Media percorrenza mensile
• Media percorrenza annuale
• Statistiche per zona
• Top 10 territori più assegnati
• Top 10 persone
• Territori mai assegnati

Export PDF

Puoi esportare in PDF:

• Lista territori da assegnare
• Lista territori prioritari
• Lista territori da riconsegnare

Clicca sul pulsante "📄 Export PDF" nella dashboard.

Impostazioni (Solo Admin)

Configura:

• Giorni validità link: Durata dei link temporanei
• Giorni territori da assegnare: Soglia per "da assegnare"
• Giorni territori prioritari: Soglia per "prioritari"
• Giorni da riconsegnare: Soglia per "da riconsegnare"

Gestisci anche:

• Cambio password
• Utenti del sistema

Manutenzione

Backup Database

Esegui regolarmente backup del database:

mysqldump -u root -p territory_manager > backup_$(date +%Y%m%d).sql

Backup File

Copia periodicamente la cartella uploads con le immagini.

Pulizia Link Scaduti

I link scaduti vengono controllati automaticamente. Non è necessaria pulizia manuale.

Log Errori

Gli errori PHP vengono salvati nel log del server. In produzione, disattiva la visualizzazione errori in config.php:

ini_set('display_errors', 0);
error_reporting(0);

Personalizzazione

Modificare i Colori

Modifica le variabili CSS in style.css:

:root {
    --primary: #3498db;      /* Colore principale */
    --success: #27ae60;      /* Verde */
    --danger: #e74c3c;       /* Rosso */
    --warning: #f39c12;      /* Arancione */
}

Aggiungere Campi ai Territori

1. Modifica la tabella territories in MySQL:

ALTER TABLE territories ADD COLUMN nuovo_campo VARCHAR(100);

2. Aggiungi il campo nei form in territories.php

3. Aggiorna le query di INSERT/UPDATE

Modificare Template Email

Attualmente non ci sono notifiche email. Per aggiungerle:

1. Installa PHPMailer o usa mail()
2. Crea funzioni in functions.php
3. Chiama le funzioni dopo assegnazioni/riconsegne

Risoluzione Problemi

Errore connessione database

• Verifica credenziali in config.php
• Controlla che MySQL sia avviato
• Verifica che il database esista

Upload immagini non funziona

• Controlla permessi cartella uploads (755)
• Verifica upload_max_filesize in php.ini
• Controlla post_max_size in php.ini

Sessione scade troppo presto

• Modifica SESSION_LIFETIME in config.php
• Controlla session.gc_maxlifetime in php.ini

Link temporanei non funzionano

• Verifica che HTTP_HOST sia configurato correttamente
• Controlla che view_territory.php sia accessibile

Sicurezza

• ✅ Password criptate con bcrypt
• ✅ Protezione SQL injection (prepared statements)
• ✅ Sanitizzazione input
• ✅ Validazione file upload
• ✅ Controllo sessioni
• ✅ Token CSRF non implementato (da aggiungere se necessario)

Raccomandazioni:

1. Cambia password admin dopo installazione
2. Usa HTTPS in produzione
3. Limita accesso alla cartella uploads
4. Aggiorna PHP regolarmente

Supporto e Contributi

Questo è un progetto semplice e facilmente estendibile. Puoi:

• Modificare il codice secondo le tue esigenze
• Aggiungere nuove funzionalità
• Migliorare la grafica

Licenza

Questo progetto è fornito "così com'è" per uso personale e interno.

Versione

v1.0.0 - 6 dicembre 2025

---

Buona gestione dei territori! 🗺️