territory-assigner/LOG_SYSTEM.md

Sistema di Logging - Territory Manager

Panoramica

Il sistema di logging è stato implementato per tracciare tutte le azioni eseguite dagli utenti all'interno dell'applicazione Territory Manager.

Funzionalità Implementate

1. Database

• Tabella activity_logs: Memorizza tutti i log delle attività
  • user_id: ID dell'utente che ha eseguito l'azione
  • username: Nome utente per riferimento rapido
  • action_type: Tipo di azione (login, logout, create, update, delete, assign, return, export)
  • action_description: Descrizione dettagliata dell'azione
  • entity_type: Tipo di entità coinvolta (territory, assignment, user, config, auth)
  • entity_id: ID dell'entità coinvolta
  • ip_address: Indirizzo IP dell'utente
  • user_agent: User agent del browser
  • created_at: Timestamp dell'azione

2. Funzioni di Logging (functions.php)

logActivity($action_type, $action_description, $entity_type, $entity_id)

Registra un'attività nel log. Cattura automaticamente:

• Utente corrente dalla sessione
• Indirizzo IP
• User Agent del browser

getActivityLogs($filters, $page, $per_page)

Recupera i log con filtri e paginazione. Supporta filtri per:

• Utente
• Tipo di azione
• Tipo di entità
• Intervallo di date
• Ricerca testuale

3. Pagina Visualizzazione Log (logs.php)

Accesso: Solo amministratori

Funzionalità:

• Visualizzazione log con tabella paginata
• Filtri multipli:
  • Ricerca testuale
  • Utente
  • Tipo di azione
  • Tipo di entità
  • Data da/a
• Paginazione (50 log per pagina)
• Badge colorati per tipo di azione
• Link per esportazione PDF

4. Esportazione PDF (export_logs_pdf.php)

Accesso: Solo amministratori

Funzionalità:

• Esporta tutti i log filtrati in formato PDF
• Include gli stessi filtri della pagina di visualizzazione
• Genera report con:
  • Elenco completo dei log
  • Riepilogo per tipo di azione
  • Riepilogo per utente
  • Timestamp di generazione
  • Informazioni sui filtri applicati

5. Azioni Tracciate

Autenticazione

• login: Accesso al sistema
• logout: Uscita dal sistema

Territori

• create: Creazione nuovo territorio
• update: Modifica territorio esistente
• delete: Eliminazione territorio

Assegnazioni

• assign: Assegnazione territorio a un proclamatore
• return: Riconsegna territorio

Utenti

• create: Creazione nuovo utente
• update: Modifica password
• delete: Eliminazione utente

Configurazioni

• update: Modifica configurazioni di sistema

Log

• export: Esportazione log in PDF

Integrazione

Il logging è stato integrato in tutte le operazioni principali:

• login.php: Log di accesso
• logout.php: Log di uscita
• territories.php: Log di creazione, modifica ed eliminazione territori
• assignments.php: Log di assegnazione e riconsegna
• settings.php: Log di modifiche configurazioni e gestione utenti
• export_logs_pdf.php: Log di esportazione

Menu di Navigazione

Il link "Log" è stato aggiunto nel menu principale, visibile solo agli amministratori.

Utilizzo

Visualizzare i Log

1. Accedere come amministratore
2. Cliccare su "Log" nel menu
3. Utilizzare i filtri per trovare log specifici

Esportare i Log

1. Dalla pagina Log, applicare eventuali filtri
2. Cliccare su "Esporta PDF"
3. Si aprirà una nuova finestra con il report
4. Utilizzare il pulsante "Stampa / Salva come PDF" del browser

Note Tecniche

• Il sistema cattura automaticamente IP e User Agent per tracciabilità
• I log sono legati agli utenti tramite foreign key (cascade on delete)
• La paginazione limita il carico sul database
• L'export PDF è ottimizzato per la stampa (orientamento landscape)
• I filtri sono persistenti durante la navigazione

Sicurezza

• Solo gli amministratori possono accedere ai log
• I log non possono essere modificati o eliminati dall'interfaccia
• Tutte le operazioni sensibili vengono registrate
• Gli IP vengono tracciati per audit trail

Manutenzione

Per pulire vecchi log (da eseguire manualmente nel database):

-- Elimina log più vecchi di 1 anno
DELETE FROM activity_logs WHERE created_at < DATE_SUB(NOW(), INTERVAL 1 YEAR);

Database Migration

Per applicare le modifiche al database esistente:

-- Eseguire lo script SQL aggiornato
SOURCE database.sql;

O solo la parte relativa ai log:

CREATE TABLE IF NOT EXISTS activity_logs (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    username VARCHAR(50) NOT NULL,
    action_type VARCHAR(50) NOT NULL,
    action_description TEXT NOT NULL,
    entity_type VARCHAR(50),
    entity_id INT,
    ip_address VARCHAR(45),
    user_agent TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    INDEX idx_user (user_id),
    INDEX idx_action_type (action_type),
    INDEX idx_created_at (created_at),
    INDEX idx_entity (entity_type, entity_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;