Documentazione AletheIA

🌟 Panoramica

AletheIA è un sistema completo per la rassegna stampa automatica che aggrega notizie da diverse fonti, analizza il sentiment e fornisce strumenti avanzati per la gestione e la distribuzione dei contenuti.

📰 Rassegna Stampa

La homepage di AletheIA mostra tutte le notizie aggregate in tempo reale con filtri avanzati e ricerca.

Funzionalità Principali

• Visualizzazione Notizie: Lista completa di tutte le notizie con titolo, fonte, data e sentiment
• Filtri per Fonte: Filtra le notizie per testata giornalistica o fonte
• Filtri per Sentiment: Visualizza solo notizie positive, negative o neutre
• Ricerca: Cerca notizie per parole chiave nel titolo o contenuto
• Aggiornamento Manuale: Pulsante per aggiornare manualmente le notizie
• Aggiornamento Automatico: Le notizie si aggiornano automaticamente in background

Accesso

La rassegna stampa è accessibile dalla homepage principale all'URL /

📡 Gestione Feed RSS

Gestisci tutte le fonti RSS, web scraping e API per l'aggregazione delle notizie.

Come Accedere

1. Accedi al pannello admin di AletheIA
2. Nella sidebar sinistra, clicca su "Feed RSS"
3. Oppure vai direttamente all'URL: /admin/rss-management/

Tipi di Feed Supportati

• RSS Feed: Feed RSS standard (formato XML)
• Web Scraping: Estrazione automatica da siti web
• API: Integrazione con API esterne (JSON/XML)

Come Aggiungere un Nuovo Feed RSS

1. Nella pagina "Gestione Feed RSS", clicca sul pulsante "Crea" o "Nuovo Feed"
2. Compila il form con i seguenti campi:
   • Nome: Nome descrittivo del feed (es: "TarantoToday")
   • URL: URL completo del feed RSS (es: https://www.tarantotoday.it/tag/kyma-mobilita.xml)
   • Tipo Feed: Seleziona "RSS Feed" dal menu a tendina
   • Parole Chiave: Inserisci parole chiave separate da virgola per filtrare le notizie (es: kyma,mobilità,taranto)
   • Attivo: Spunta questa casella per attivare il feed immediatamente
3. Clicca su "Salva" per creare il feed
4. Il sistema inizierà automaticamente ad aggregare notizie da questo feed

Come Modificare un Feed Esistente

1. Nella lista dei feed, trova il feed che vuoi modificare
2. Clicca sul pulsante "Modifica" (icona matita) accanto al feed
3. Modifica i campi desiderati (nome, URL, keywords, stato attivo/inattivo)
4. Clicca su "Salva" per applicare le modifiche

Come Disattivare/Attivare un Feed

1. Nella lista dei feed, trova il feed da attivare/disattivare
2. Clicca sul pulsante "Modifica"
3. Spunta o deseleziona la casella "Attivo"
4. Salva le modifiche
5. Nota: I feed disattivati non vengono più aggiornati automaticamente

Come Eliminare un Feed

1. Nella lista dei feed, trova il feed da eliminare
2. Clicca sul pulsante "Elimina" (icona cestino)
3. Conferma l'eliminazione nel popup di conferma
4. Attenzione: L'eliminazione è permanente e rimuoverà anche le notizie già aggregate da questo feed

Esempi di URL Feed RSS

Configurazione Parole Chiave

Le parole chiave permettono di filtrare le notizie che vengono aggregate dal feed:

• Formato: Parole separate da virgola (es: kyma,mobilità,taranto,trasporti)
• Case-insensitive: Le parole chiave non sono sensibili a maiuscole/minuscole
• Filtro automatico: Solo le notizie contenenti almeno una delle parole chiave verranno salvate

Monitoraggio e Stato

Nella lista dei feed puoi vedere:

• Nome: Nome del feed
• URL: Indirizzo del feed
• Tipo: RSS, Web o API
• Stato: Attivo o Inattivo
• Data Creazione: Quando il feed è stato aggiunto

📄 Fonti PDF

Gestisci fonti PDF che vengono scaricate, processate e analizzate automaticamente.

Funzionalità

• Download Automatico: Scarica PDF da URL configurati
• Estrazione Testo: Estrae il testo da ogni pagina del PDF
• Analisi Sentiment: Analizza il sentiment di ogni pagina
• Scheduling: Configura download giornalieri, settimanali o mensili
• Visualizzazione: Visualizza i PDF direttamente nel browser

Tipi di Scheduling

• Giornaliero: Download ogni giorno all'orario specificato
• Settimanale: Download una volta a settimana
• Mensile: Download una volta al mese

Accesso

Menu Admin → Fonti PDF oppure URL: /admin/ → Sezione "Fonti PDF"

📱 Account Social

Monitora e analizza i post dai principali social network.

Piattaforme Supportate

• Facebook: Pagine, profili e gruppi
• Instagram: Profili e account business
• LinkedIn: Pagine aziendali e profili
• YouTube: Canali e video

Tipi di Account

• Pagina: Pagine Facebook o LinkedIn
• Profilo: Profili personali o aziendali
• Gruppo: Gruppi Facebook
• Canale: Canali YouTube

Funzionalità

• Monitoraggio automatico dei post
• Analisi sentiment dei contenuti
• Tracciamento metriche (like, commenti, condivisioni)
• Filtri per tipo di post (post, commento, menzione, storia)

Accesso

Menu Admin → Account Social oppure URL: /admin/social-accounts-management/

🔑 Come Ottenere i Token per i Social Network

Per monitorare i post dai social network, è necessario ottenere i token di accesso dalle rispettive piattaforme. Di seguito le istruzioni per ogni piattaforma supportata.

📘 Facebook

Passo 1: Crea un'App Facebook

1. Vai su Facebook Developers
2. Clicca su "Le Mie App" → "Crea App"
3. Seleziona il tipo di app: "Business" o "Altro"
4. Compila i dati richiesti (nome app, email di contatto)
5. Clicca su "Crea App"

Passo 2: Configura l'App

1. Nella dashboard dell'app, vai su "Impostazioni" → "Base"
2. Aggiungi una "Piattaforma" se necessario
3. Vai su "Strumenti" → "Graph API Explorer"

Passo 3: Genera l'Access Token

1. Nel Graph API Explorer, seleziona la tua app dal menu a tendina
2. Seleziona i permessi necessari:
   • pages_read_engagement - Per leggere i post delle pagine
   • pages_manage_posts - Per gestire i post (opzionale)
   • pages_show_list - Per elencare le pagine
3. Clicca su "Genera Token di Accesso"
4. Autorizza l'app quando richiesto
5. Copia il token generato

Passo 4: Ottieni il Token Permanente (per Pagine)

1. Per monitorare una pagina, devi ottenere un token permanente per quella pagina
2. Vai su "Strumenti" → "Graph API Explorer"
3. Seleziona la tua app e i permessi pages_read_engagement
4. Genera un token utente
5. Usa questo token per ottenere il token della pagina con una chiamata API:

   GET /me/accounts?access_token=TUO_TOKEN_UTENTE

6. Il token della pagina sarà nel campo access_token della risposta

📷 Instagram

Passo 1: Crea un'App Facebook (richiesto)

Instagram usa il sistema di autenticazione di Facebook. Segui i passi per Facebook sopra.

Passo 2: Aggiungi il Prodotto Instagram

1. Nella dashboard della tua app Facebook, vai su "Aggiungi Prodotto"
2. Cerca e aggiungi "Instagram"
3. Configura le impostazioni base

Passo 3: Genera il Token Instagram

1. Vai su "Strumenti" → "Graph API Explorer"
2. Seleziona la tua app
3. Seleziona i permessi:
   • instagram_basic
   • instagram_content_publish (se necessario)
4. Genera il token e copialo

💼 LinkedIn

Passo 1: Crea un'App LinkedIn

1. Vai su LinkedIn Developers
2. Clicca su "Create app"
3. Compila il form:
   • Nome app
   • URL del sito web
   • Logo (opzionale)
   • Privacy Policy URL
   • Terms of Service URL
4. Accetta i termini e clicca su "Create app"

Passo 2: Configura i Permessi

1. Nella dashboard dell'app, vai su "Auth"
2. Nella sezione "OAuth 2.0 scopes", seleziona:
   • r_liteprofile - Per leggere il profilo base
   • r_organization_social - Per leggere i post delle organizzazioni
   • w_organization_social - Per pubblicare (opzionale)
3. Salva le modifiche

Passo 3: Genera il Token

1. Nella sezione "Auth", trova "Client credentials"
2. Copia Client ID e Client Secret
3. Per ottenere un access token, usa OAuth 2.0:
   • Usa l'URL di autorizzazione: https://www.linkedin.com/oauth/v2/authorization
   • Dopo l'autorizzazione, ottieni il token dall'endpoint: https://www.linkedin.com/oauth/v2/accessToken

📺 YouTube

Passo 1: Crea un Progetto in Google Cloud

1. Vai su Google Cloud Console
2. Crea un nuovo progetto o seleziona uno esistente
3. Vai su "API e servizi" → "Libreria"
4. Cerca "YouTube Data API v3" e abilitala

Passo 2: Crea le Credenziali

1. Vai su "API e servizi" → "Credenziali"
2. Clicca su "Crea credenziali" → "Chiave API"
3. Copia la chiave API generata
4. Opzionalmente, limita la chiave API al solo YouTube Data API v3 per sicurezza

Passo 3: Usa la Chiave API

La chiave API di YouTube può essere usata direttamente nel campo "Access Token" di AletheIA per monitorare i canali pubblici.

📝 Note Generali

• Sicurezza: I token sono informazioni sensibili. Non condividerli pubblicamente.
• Scadenza: Molti token hanno una scadenza. Configura i refresh token quando disponibili.
• Permessi: Richiedi solo i permessi minimi necessari per la funzionalità richiesta.
• Rate Limits: Ogni piattaforma ha limiti di richieste API. Consulta la documentazione ufficiale.

😊 Analisi Sentiment

Sistema avanzato per l'analisi del sentiment delle notizie e dei post social.

Come Accedere

1. Accedi al pannello admin
2. Nella sidebar, clicca su "Filtri Sentiment" o "Regole Sentiment"
3. Oppure vai direttamente agli URL:
   • Filtri: /admin/sentiment-filters-management/
   • Regole: /admin/sentiment-rules-management/

Filtri Sentiment - Come Creare un Filtro

I filtri sentiment permettono di includere o escludere notizie basandosi su parole chiave.

Passo 1: Crea un Nuovo Filtro

1. Vai su "Filtri Sentiment" nel menu admin
2. Clicca sul pulsante "Crea" o "Nuovo Filtro"
3. Compila il form con i seguenti campi:

Passo 2: Configura i Campi del Filtro

• Nome Filtro: Nome descrittivo (es: "Filtro Spam", "Parole Tecnologia")
• Tipo Filtro: Seleziona dal menu a tendina:
  • Escludi: Rimuove notizie contenenti queste parole
  • Includi: Mostra SOLO notizie contenenti queste parole
  • Richiesto: Le notizie DEVONO contenere queste parole
  • Peso: Applica un peso per il ranking
• Parole Chiave: Inserisci parole separate da virgola (es: spam,pubblicità,offerta speciale)
• Descrizione: Descrizione opzionale del filtro
• Modalità: Seleziona "Escludi" o "Obbligatorio"
• Peso: Valore numerico (solo per filtri di tipo "Peso")
• Attivo: Spunta per attivare il filtro

Passo 3: Salva il Filtro

1. Clicca su "Salva"
2. Il filtro verrà applicato automaticamente alle nuove notizie

Esempi di Filtri

Regole Sentiment - Come Creare una Regola

Le regole sentiment analizzano il contenuto e assegnano un sentiment e un punteggio.

Passo 1: Crea una Nuova Regola

1. Vai su "Regole Sentiment" nel menu admin
2. Clicca sul pulsante "Crea" o "Nuova Regola"
3. Compila il form con i seguenti campi:

Passo 2: Configura i Campi della Regola

• Nome Regola: Nome descrittivo (es: "Molto Positivo - Successo")
• Pattern/Testo: Testo o pattern da cercare nelle notizie (es: successo,vittoria,trionfo)
• Sentiment: Seleziona dal menu:
  • Positivo: Per contenuti positivi
  • Negativo: Per contenuti negativi
  • Neutrale: Per contenuti neutri
  • Misto: Per contenuti misti
• Punteggio: Valore da -1.0 (molto negativo) a +1.0 (molto positivo)
  • Esempio: 0.9 per molto positivo
  • Esempio: -0.5 per leggermente negativo
• Priorità: Numero intero (valori più alti = maggiore priorità)
  • Esempio: 10 per regole molto importanti
  • Esempio: 5 per regole normali
• Attivo: Spunta per attivare la regola

Passo 3: Salva la Regola

1. Clicca su "Salva"
2. La regola verrà applicata automaticamente alle nuove notizie

Esempi di Regole

Come Funziona il Sistema di Priorità

Quando una notizia corrisponde a più regole:

• La regola con priorità più alta viene applicata per prima
• Se due regole hanno la stessa priorità, viene usata quella con punteggio più estremo
• Le regole con priorità 0 o negativa vengono applicate per ultime

Modifica ed Eliminazione

1. Nella lista dei filtri/regole, trova quello da modificare
2. Clicca su "Modifica" (icona matita)
3. Modifica i campi desiderati
4. Clicca su "Salva"
5. Per eliminare, clicca su "Elimina" (icona cestino) e conferma

📊 Report Programmabili

Crea e programma report automatici da inviare via email con template personalizzabili.

Come Accedere

1. Accedi al pannello admin
2. Nella sidebar, clicca su "Report Programmabili"
3. Oppure vai direttamente all'URL: /admin/reports

Passo 1: Configura un Server SMTP

Prima di creare un report, devi configurare almeno un server SMTP per l'invio delle email.

Come Configurare SMTP

1. Nella pagina "Report Programmabili", clicca sulla tab "SMTP"
2. Clicca sul pulsante "Nuova Configurazione"
3. Compila il form con i seguenti dati:
   • Nome: Nome descrittivo (es: "Gmail SMTP", "Server Aziendale")
   • Server SMTP: Indirizzo del server (es: smtp.gmail.com, smtp.example.com)
   • Porta: Porta SMTP (es: 587 per TLS, 465 per SSL, 25 per non crittografato)
   • Username: Username per l'autenticazione (spesso l'indirizzo email)
   • Password: Password per l'autenticazione
   • Usa TLS: Spunta se il server richiede TLS
   • Usa SSL: Spunta se il server richiede SSL
   • Email Mittente: Indirizzo email che apparirà come mittente (es: noreply@example.com)
4. Clicca su "Salva"

Esempi di Configurazione SMTP

Passo 2: Crea un Template

I template definiscono come verrà formattato il report inviato via email.

Come Creare un Template

1. Nella pagina "Report Programmabili", clicca sulla tab "Template"
2. Clicca sul pulsante "Nuovo Template"
3. Compila il form:
   • Nome: Nome del template (es: "Report Settimanale", "Report Giornaliero")
   • Oggetto Email: Oggetto dell'email (puoi usare variabili come )
   • Template HTML: HTML per il corpo dell'email (opzionale, per email formattate)
   • Template Testo: Testo semplice per il corpo dell'email (usato se HTML non è presente)
4. Clicca su "Salva"

Variabili Disponibili nei Template

Esempio di Template HTML

Passo 3: Crea un Report Programmabile

Ora puoi creare il report che utilizzerà il template e la configurazione SMTP.

Come Creare un Report

1. Nella pagina "Report Programmabili", clicca sulla tab "Report"
2. Clicca sul pulsante "Nuovo Report"
3. Compila il form con i seguenti campi:
   • Nome: Nome del report (es: "Report Settimanale KYMA")
   • Descrizione: Descrizione opzionale
   • Template: Seleziona il template creato in precedenza
   • Configurazione SMTP: Seleziona la configurazione SMTP
   • Tipo Scheduling: Seleziona:
     • Giornaliero: Ogni giorno
     • Settimanale: Una volta a settimana
     • Mensile: Una volta al mese
     • Personalizzato: Usa espressione cron
   • Destinatari: Inserisci email separate da virgola (es: admin@example.com,manager@example.com)
   • CC: Email in copia (opzionale)
   • BCC: Email in copia nascosta (opzionale)
   • Filtri:
     • Keywords: Parole chiave per filtrare notizie (separate da virgola)
     • Sentiment: Filtra per sentiment (Positivo, Negativo, Neutrale, Tutti)
     • Fonti: Seleziona fonti specifiche (opzionale)
     • Giorni di Dati: Numero di giorni di dati da includere (es: 7 per ultima settimana)
   • Attivo: Spunta per attivare il report
4. Clicca su "Salva"

Come Eseguire Manualmente un Report

1. Nella lista dei report, trova il report da eseguire
2. Clicca sul pulsante "Esegui Ora" o "Execute"
3. Il report verrà generato e inviato immediatamente
4. Puoi verificare l'esito nella tab "Log"

Monitoraggio e Log

Nella tab "Log" puoi vedere:

• Data e ora di ogni invio
• Stato (Successo, Errore, In esecuzione)
• Numero di destinatari
• Numero di articoli inclusi
• Eventuali errori

Modifica ed Eliminazione

1. Nella lista dei report, trova quello da modificare
2. Clicca su "Modifica"
3. Modifica i campi desiderati
4. Clicca su "Salva"
5. Per disattivare temporaneamente, deseleziona "Attivo" e salva
6. Per eliminare, clicca su "Elimina" e conferma

🔗 Genera Embed

Crea codice embed personalizzabile per integrare la rassegna stampa in altri siti web.

Funzionalità

• Filtri Personalizzabili: Filtra per fonte, sentiment, keywords
• Dimensioni Personalizzate: Configura larghezza e altezza
• Stile Personalizzato: Applica colori e stili personalizzati
• Aggiornamento Automatico: L'embed si aggiorna automaticamente

Come Usare

1. Vai su Genera Embed nel menu admin
2. Configura i filtri desiderati
3. Copia il codice iframe generato
4. Incolla il codice nel tuo sito web

Accesso

Menu Admin → Genera Embed oppure URL: /admin/embed

🎨 Branding

Personalizza completamente l'aspetto e l'identità visiva di AletheIA.

Come Accedere

1. Accedi al pannello admin
2. Nella sidebar, clicca su "Branding"
3. Oppure vai direttamente all'URL: /admin/branding/

Come Caricare il Logo

1. Nella pagina Branding, trova la sezione "Loghi e Immagini Frontend"
2. Clicca su "Scegli File" accanto a "Logo Frontend"
3. Seleziona il file immagine del tuo logo (formati supportati: PNG, JPG, SVG)
4. Raccomandazioni:
   • Dimensione consigliata: almeno 200x200 pixel
   • Formato: PNG con sfondo trasparente (preferito)
   • Peso file: sotto 2MB per prestazioni ottimali
5. L'anteprima del logo apparirà automaticamente
6. Clicca su "Salva Branding" per applicare le modifiche

Come Personalizzare i Colori

1. Nella sezione "Colori Frontend", troverai tre selettori colore:
2. Colore Primario: Colore principale dell'interfaccia (bottoni, link, elementi principali)
   • Clicca sul selettore colore
   • Scegli un colore o inserisci il codice esadecimale (es: #28a745 per verde)
3. Colore Secondario: Colore per elementi secondari
   • Esempio: #dc3545 per rosso
4. Colore Accent: Colore per evidenziare elementi importanti
   • Esempio: #0066cc per blu
5. Clicca su "Salva Branding" per applicare i colori

Come Modificare Testi e Contenuti

1. Nella sezione "Testo e Contenuti", modifica i seguenti campi:
2. Nome Azienda: Nome della tua azienda/organizzazione (es: "KYMA Mobilità")
3. Titolo Applicazione Frontend: Titolo mostrato nella homepage (es: "Rassegna Stampa")
4. Descrizione Frontend: Descrizione dell'applicazione (appare nella homepage)
5. Testo Footer Frontend: Testo mostrato nel footer (es: "© 2025 AletheIA - Rassegna Stampa Automatica")
6. Clicca su "Salva Branding"

Come Caricare Favicon

1. Nella sezione "Loghi e Immagini Frontend", trova "Favicon Frontend"
2. Clicca su "Scegli File"
3. Seleziona un file immagine (formato: ICO, PNG, SVG)
4. Raccomandazioni:
   • Dimensione: 32x32 o 16x16 pixel
   • Formato: ICO (preferito) o PNG
5. Salva le modifiche

Come Configurare Meta Tags SEO

1. Nella sezione "Meta Tags SEO", compila:
2. Meta Title: Titolo della pagina per i motori di ricerca (max 60 caratteri)
3. Meta Description: Descrizione per i motori di ricerca (max 160 caratteri)
4. Meta Keywords: Parole chiave separate da virgola (es: rassegna,notizie,news,monitoraggio)
5. Salva le modifiche

Impostazioni Avanzate

Nella sezione "Impostazioni Avanzate" puoi configurare:

• Font Family: Scegli il font (es: "Inter", "Arial", "Helvetica")
• Border Radius: Dimensione degli angoli arrotondati (Small, Medium, Large)
• Dark Mode: Attiva/disattiva la modalità scura
• Animazioni: Attiva/disattiva le animazioni dell'interfaccia
• Modalità Compatta: Riduce lo spazio tra gli elementi

Come Caricare Immagine di Sfondo

1. Nella sezione "Loghi e Immagini Frontend", trova "Immagine di Sfondo Frontend"
2. Clicca su "Scegli File"
3. Seleziona un'immagine di sfondo (formato: JPG, PNG)
4. Raccomandazioni:
   • Risoluzione: almeno 1920x1080 pixel
   • Peso: sotto 1MB per prestazioni ottimali
   • Considera immagini con bassa opacità per non interferire con il testo
5. Salva le modifiche

Anteprima e Test

Dopo aver salvato le modifiche:

1. Vai alla homepage principale (/)
2. Verifica che logo, colori e testi siano stati applicati correttamente
3. Se qualcosa non appare, controlla:
   • Che i file siano stati caricati correttamente
   • Che i formati dei file siano supportati
   • Che non ci siano errori nella console del browser (F12)

Reset Branding

Per ripristinare il branding di default:

1. Clicca sul pulsante "Reset Branding" (se disponibile)
2. Conferma l'operazione
3. Tutte le impostazioni torneranno ai valori di default di AletheIA

🗄️ Configurazione Database

Gestisci la configurazione del database e migra tra diversi sistemi di database.

Database Supportati

• SQLite: Database locale (default)
• PostgreSQL: Database relazionale avanzato
• MySQL: Database relazionale popolare
• MariaDB: Fork open source di MySQL

Funzionalità

• Configurazione connessione database
• Test connessione in tempo reale
• Migrazione automatica dei dati
• Backup e ripristino
• Storico migrazioni

Accesso

Menu Admin → CONFIGURAZIONI → Database oppure URL: /database-config

🔗 AletheIA Central

Collega il tuo sistema AletheIA ad AletheIA Central per accedere al marketplace delle fonti PDF condivise.

Funzionalità

• Connessione a Central: Configura e testa la connessione al server Central
• Registrazione Sistema: Registra il tuo sistema e ottieni credenziali API
• Marketplace PDF: Sfoglia e sincronizza fonti PDF condivise
• Sync Automatica: Aggiornamenti programmati giornalieri/settimanali
• Gestione Licenze: Gestisci le licenze e i dispositivi connessi

Tipi di Licenza

• Basic: 3 dispositivi
• Standard: 5 dispositivi
• Enterprise: 10 dispositivi

Accesso

Menu Admin → CONFIGURAZIONI → AletheIA Central oppure URL: /central-config

💾 Import/Export

Importa ed esporta i dati del sistema per backup, migrazione o sincronizzazione.

Dati Esportabili

• Feed RSS
• Account Social
• Filtri e Regole Sentiment
• Fonti PDF
• Configurazioni Branding
• Utenti e permessi

Formati Supportati

• JSON: Formato standard per dati strutturati
• CSV: Per dati tabellari

Funzionalità

• Export completo o selettivo
• Import con validazione
• Merge intelligente dei dati
• Backup automatici

Accesso

Menu Admin → Import/Export oppure URL: /admin/import-export/

👥 Gestione Utenti

Gestisci utenti, amministratori e permessi del sistema.

Tipi di Utente

• Utente: Accesso base alla rassegna stampa
• Moderatore: Permessi avanzati per la moderazione
• Amministratore: Accesso completo a tutte le funzionalità

Funzionalità

• Creazione, modifica ed eliminazione utenti
• Gestione ruoli e permessi
• Attivazione/disattivazione account
• Reset password
• Tracciamento ultimo accesso

Admin Users

Gli Admin Users hanno accesso completo al pannello di amministrazione con tutte le funzionalità avanzate.

Accesso

Menu Admin → Utenti oppure Admin Users oppure URL: /admin/ → Sezioni dedicate

🔌 Integrazioni

Collega AletheIA con servizi esterni per estendere le funzionalità e automatizzare i processi.

Come Accedere

1. Accedi al pannello admin di AletheIA
2. Nel menu laterale, clicca su INTEGRAZIONI
3. Vedrai la lista di tutte le integrazioni disponibili

Integrazioni Disponibili

Integrazioni Attive

• Google Analytics: Analizza come il sentiment delle notizie influenza le visite al sito. Richiede Property ID e credenziali JSON.
• Telegram: Invia report aggregati sul sentiment delle notizie a cadenza programmabile via Telegram Bot. Richiede Bot Token e Chat ID.
• Mattermost: Invia report aggregati sul sentiment delle notizie a cadenza programmabile su Mattermost. Richiede Webhook URL.
• Webhooks: Invia eventi e notifiche a endpoint web personalizzati. Configura più webhook per diversi eventi.
• Shopify: Analizza come il sentiment delle notizie influenza le vendite nel tuo e-commerce Shopify. Include previsioni con Prophet.
• WooCommerce: Analizza come il sentiment delle notizie influenza le vendite nel tuo e-commerce WooCommerce. Include previsioni con Prophet.
• PrestaShop: Analizza come il sentiment delle notizie influenza le vendite nel tuo e-commerce PrestaShop. Include previsioni con Prophet.
• Microsoft Teams: Invia notifiche e report su Microsoft Teams. Richiede Webhook URL.

Integrazioni Coming Soon

• Google Ads: Scopri come il sentiment delle notizie influisce sulle campagne pubblicitarie
• Facebook Insights: Analizza come il sentiment influisce sulla tua pagina Facebook
• Stripe: Analizza come il sentiment influisce sulle vendite online
• PayPal: Analizza come il sentiment influisce sulle vendite online
• GitHub: Integrazione per gestione repository e issues
• Trello: Sincronizzazione con board Trello per gestione progetti
• ClickUp: Integrazione per gestione task e progetti
• Monday.com: Sincronizzazione per workflow e progetti
• OpenAI: Integrazione con i modelli GPT per automazioni e generazione contenuti
• Anthropic Claude: Integrazione con i modelli Claude per analisi e copywriting avanzato
• Google AI Studio: Integrazione con i modelli Gemini per generazione e classificazione dei contenuti

Integrazioni Enterprise

• Nielsen Data: Dati e insights da Nielsen per analisi approfondite di mercato. Disponibile solo con licenza Enterprise.

Come Configurare un'Integrazione

1. Vai alla sezione Integrazioni nel menu admin
2. Trova l'integrazione che vuoi configurare nella lista
3. Clicca sul pulsante "Configura" accanto all'integrazione
4. Compila i campi richiesti nel modal di configurazione:
   • Per Google Analytics: Property ID e credenziali JSON (puoi caricare il file o incollare il contenuto)
   • Per Telegram: Bot Token (da @BotFather) e Chat ID
   • Per Mattermost: Webhook URL
   • Per Webhooks: Aggiungi uno o più webhook con nome e URL
   • Per Shopify: Shop Domain (es: "mystore") e Access Token
   • Per WooCommerce: Store URL, Consumer Key e Consumer Secret
   • Per PrestaShop: Store URL e API Key
   • Per Microsoft Teams: Webhook URL
5. Clicca su "Salva Configurazione"
6. Attiva l'integrazione usando il toggle switch
7. Usa il pulsante "Test Connessione" per verificare che tutto funzioni

Marketing Overview - Vista Integrata

Quando hai attive integrazioni marketing (Google Analytics, Shopify, WooCommerce, PrestaShop) o hai configurato parole chiave competitor, la visuale del "Sentiment Globale" si trasforma automaticamente in "AletheIA Marketing Overview" con una navigazione a schede.

Come Funziona

1. La prima scheda mostra sempre il Sentiment Globale delle Notizie
2. Le schede aggiuntive appaiono automaticamente per ogni integrazione marketing attiva:
   • Google Analytics: Correlazione sentiment-visite
   • Shopify/WooCommerce/PrestaShop: Analisi vendite, correlazione con sentiment, previsioni Prophet
   • Competitor: Confronto del sentiment tra il tuo brand e i competitor, grazie al monitoraggio di keyword dedicate
3. Se non ci sono integrazioni marketing attive e non è attivo il monitoraggio competitor, la visuale rimane come "Sentiment Globale delle Notizie"

Funzionalità E-commerce

Le integrazioni e-commerce (Shopify, WooCommerce, PrestaShop) forniscono:

• Statistiche Vendite: Ricavo totale, ordini totali, ricavo medio giornaliero
• Correlazione Sentiment: Analisi di come il sentiment delle notizie influenza le vendite
• Previsioni Prophet: Previsioni delle vendite per i prossimi 30 giorni usando l'algoritmo Prophet di Facebook
• Insights Automatici: Suggerimenti basati sulla correlazione rilevata

Report Sentiment Programmabili (Telegram, Mattermost e Teams)

Le integrazioni Telegram, Mattermost e Teams supportano l'invio automatico di report aggregati sul sentiment delle notizie.

Come Configurare i Report Automatici

1. Configura l'integrazione base (Bot Token/Chat ID per Telegram, Webhook URL per Mattermost)
2. Nel modal di configurazione, attiva "Abilita Report Automatici"
3. Configura la frequenza:
   • Ogni N ore: Invia il report ogni N ore (1-168)
   • Giornaliero: Invia il report ogni giorno a un'ora specifica (0-23)
   • Settimanale: Invia il report una volta a settimana in un giorno specifico
   • Cron Personalizzato: Usa un'espressione cron per scheduling avanzato
4. Imposta il Periodo di Analisi (giorni da analizzare, default: 7)
5. Opzionalmente, specifica Keywords per filtrare le notizie (una per riga, lascia vuoto per usare le keywords di default)
6. Salva la configurazione
7. Usa "Invia Report Test" per testare immediatamente l'invio

Contenuto dei Report

I report includono:

• Statistiche aggregate sul sentiment (conteggi e percentuali per positive, negative, neutre, miste)
• Totale notizie analizzate nel periodo
• Top 3 notizie positive (per sentiment score)
• Top 3 notizie negative (per sentiment score)
• Periodo di analisi e keywords utilizzate

Google Analytics - Come Ottenere le Credenziali

Passo 1: Crea un Progetto in Google Cloud

1. Vai su Google Cloud Console
2. Crea un nuovo progetto o seleziona uno esistente
3. Annota il Project ID (lo troverai nella dashboard del progetto)

Passo 2: Abilita l'API Google Analytics

1. Nel menu, vai su "API e servizi" → "Libreria"
2. Cerca "Google Analytics Data API"
3. Clicca su "Abilita"

Passo 3: Crea un Account di Servizio

1. Vai su "API e servizi" → "Credenziali"
2. Clicca su "Crea credenziali" → "Account di servizio"
3. Compila i dati:
   • Nome: Es. "AletheIA Analytics"
   • ID account di servizio: Generato automaticamente
   • Descrizione: Opzionale
4. Clicca su "Crea e continua"
5. Nella sezione "Concedi all'account di servizio l'accesso al progetto", puoi saltare questo passo per ora
6. Clicca su "Fatto"

Passo 4: Genera la Chiave JSON

1. Nella lista degli account di servizio, clicca sull'account appena creato
2. Vai alla tab "Chiavi"
3. Clicca su "Aggiungi chiave" → "Crea nuova chiave"
4. Seleziona "JSON" come formato
5. Clicca su "Crea"
6. Il file credentials.json verrà scaricato automaticamente

Passo 5: Ottieni il Property ID

1. Vai su Google Analytics
2. Seleziona la proprietà (property) che vuoi monitorare
3. Vai su "Amministrazione" (icona ingranaggio in basso a sinistra)
4. Nella colonna "Proprietà", clicca su "Impostazioni proprietà"
5. Trova il "ID proprietà" (formato: G-XXXXXXXXXX)
6. Copia questo ID

Passo 6: Concedi Permessi all'Account di Servizio

1. Torna in Google Analytics, nella stessa pagina delle impostazioni proprietà
2. Scorri fino a "Accesso alla proprietà"
3. Clicca su "Aggiungi utente"
4. Incolla l'email dell'account di servizio (formato: nome@progetto.iam.gserviceaccount.com)
5. Seleziona il ruolo "Visualizzatore" (o superiore se necessario)
6. Clicca su "Aggiungi"

Passo 7: Configura in AletheIA

Ora hai tutto il necessario per configurare Google Analytics in AletheIA:

1. Property ID: L'ID copiato da Google Analytics (es: G-XXXXXXXXXX)
2. Credenziali JSON: Il file credentials.json scaricato

In AletheIA, hai due opzioni per inserire le credenziali:

• Carica il file JSON: Clicca su "Scegli file" e seleziona il file credentials.json
• Incolla il contenuto JSON: Apri il file con un editor di testo, copia tutto il contenuto e incollalo nel campo di testo

Nota: Il sistema valida automaticamente che il JSON sia valido prima di salvare.

Stati delle Integrazioni

• ✅ Attiva: Integrazione configurata e abilitata
• ⚠️ Non Configurata: Integrazione abilitata ma mancano campi obbligatori
• Inattiva: Integrazione disabilitata
• 🔜 Coming Soon: Integrazione in arrivo, non ancora disponibile
• 🔒 Richiede Enterprise: Integrazione disponibile solo con licenza Enterprise
• ❌ Errore: Problema nella configurazione o connessione

Accesso

Menu Admin → INTEGRAZIONI oppure URL: /admin/integrations

🔐 Come Ottenere le Credenziali per le Integrazioni

Guida dettagliata per ottenere le credenziali necessarie per configurare le integrazioni attive di AletheIA.

✈️ Telegram

Passo 1: Crea un Bot con BotFather

1. Apri Telegram e cerca @BotFather
2. Avvia una conversazione e invia il comando /newbot
3. Segui le istruzioni:
   • Inserisci un nome per il bot (es: "AletheIA Notifiche")
   • Inserisci un username per il bot (deve terminare con "bot", es: "aletheia_notifiche_bot")
4. BotFather ti fornirà il Bot Token (formato: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
5. Salva questo token - non potrai visualizzarlo di nuovo

Passo 2: Ottieni il Chat ID

Hai diverse opzioni per ottenere il Chat ID:

Metodo 1: Usa @userinfobot

1. Cerca @userinfobot su Telegram
2. Avvia una conversazione
3. Il bot ti mostrerà il tuo ID (formato numerico, es: 123456789)
4. Copia questo ID

Metodo 2: Usa @getidsbot

1. Cerca @getidsbot su Telegram
2. Avvia una conversazione
3. Il bot ti mostrerà il tuo User ID

Metodo 3: Per Gruppi o Canali

1. Aggiungi il bot al gruppo/canale
2. Usa @getidsbot nel gruppo/canale
3. Il bot mostrerà l'ID del gruppo/canale
4. Nota: Per i canali, l'ID inizia con -100

Passo 3: Configura in AletheIA

1. Vai su Integrazioni → Telegram
2. Incolla il Bot Token nel campo corrispondente
3. Incolla il Chat ID nel campo corrispondente
4. Salva la configurazione
5. Usa "Test Connessione" per verificare che tutto funzioni

💬 Mattermost

Passo 1: Accedi a Mattermost

1. Accedi al tuo workspace Mattermost
2. Vai su "Menu" (icona hamburger in alto a sinistra) → "Integrazioni"
3. Oppure vai direttamente a: https://tuo-workspace.mattermost.com/integrations/incoming_webhooks

Passo 2: Crea un Webhook Incoming

1. Nella sezione "Webhook Incoming", clicca su "Aggiungi webhook incoming"
2. Compila il form:
   • Titolo: Es. "AletheIA Report"
   • Descrizione: Opzionale
   • Canale: Seleziona il canale dove inviare i messaggi
3. Clicca su "Crea"

Passo 3: Copia l'URL del Webhook

1. Dopo la creazione, vedrai l'URL del Webhook
2. Formato: https://tuo-workspace.mattermost.com/hooks/xxxxxxxxxxxxxxxxxxxxxx
3. Copia questo URL - non potrai visualizzarlo di nuovo
4. Se lo perdi, dovrai creare un nuovo webhook

Passo 4: Configura in AletheIA

1. Vai su Integrazioni → Mattermost
2. Incolla l'URL del Webhook nel campo corrispondente
3. Salva la configurazione
4. Usa "Test Connessione" per verificare che tutto funzioni

🔗 Webhooks

I webhook sono endpoint personalizzati che ricevono eventi da AletheIA. Non è necessario ottenere credenziali esterne, ma devi avere un endpoint web pronto a ricevere i dati.

Come Configurare un Webhook

1. Prepara un endpoint web che accetti richieste POST con JSON
2. L'endpoint deve essere accessibile pubblicamente (o tramite VPN/tunnel)
3. In AletheIA, vai su Integrazioni → Webhooks
4. Clicca su "Aggiungi Webhook"
5. Inserisci:
   • Nome: Un nome descrittivo (es: "Server Produzione")
   • URL: L'URL completo del tuo endpoint (es: https://example.com/webhook/aletheia)
6. Salva il webhook
7. Usa "Test" per verificare che l'endpoint risponda correttamente

Formato dei Dati Inviati

I webhook ricevono dati in formato JSON con questa struttura:

{
    "event_type": "tipo_evento",
    "timestamp": "2025-01-01T12:00:00Z",
    "data": {
        // Dati specifici dell'evento
    }
}

Esempi di Endpoint

• Node.js/Express:

  app.post('/webhook/aletheia', (req, res) => {
      const event = req.body;
      console.log('Evento ricevuto:', event);
      res.status(200).json({ received: true });
  });

• Python/Flask:

  @app.route('/webhook/aletheia', methods=['POST'])
  def webhook():
      event = request.json
      print('Evento ricevuto:', event)
      return jsonify({'received': True}), 200

📊 Google Analytics

Le istruzioni dettagliate per Google Analytics sono già presenti nella sezione principale delle Integrazioni. Vedi sopra per i passaggi completi.

Riepilogo rapido:

1. Crea un progetto in Google Cloud Console
2. Abilita Google Analytics Data API
3. Crea un account di servizio
4. Scarica il file JSON delle credenziali
5. Ottieni il Property ID da Google Analytics
6. Concedi i permessi all'account di servizio
7. Configura in AletheIA (carica file o incolla JSON)

🛒 Shopify

Passo 1: Crea un'App Privata

1. Accedi al tuo Shopify Admin
2. Vai su "Impostazioni" → "App e canali di vendita"
3. Scorri fino a "Sviluppo app" e clicca su "Consenti lo sviluppo" (se non già fatto)
4. Clicca su "Crea app"
5. Inserisci un nome per l'app (es: "AletheIA Integration")
6. Clicca su "Crea app"

Passo 2: Configura i Permessi

1. Nella pagina dell'app, vai su "Configurazione API Admin"
2. Nella sezione "Scopes Admin API", abilita:
   • read_orders - Per leggere gli ordini
   • read_analytics - Per leggere le analisi (opzionale)
3. Clicca su "Salva"

Passo 3: Installa l'App e Ottieni il Token

1. Nella pagina dell'app, clicca su "Installa app"
2. Autorizza l'app quando richiesto
3. Dopo l'installazione, vedrai il "Token di accesso Admin API"
4. Copia questo token - non potrai visualizzarlo di nuovo

Passo 4: Ottieni il Shop Domain

1. Il Shop Domain è la parte prima di .myshopify.com del tuo store
2. Esempio: se il tuo store è https://mystore.myshopify.com, il domain è mystore

Passo 5: Configura in AletheIA

1. Vai su Integrazioni → Shopify
2. Inserisci il Shop Domain (senza .myshopify.com)
3. Inserisci l'Access Token copiato
4. Salva la configurazione

🛍️ WooCommerce

Passo 1: Abilita l'API REST

1. Accedi al tuo WordPress Admin
2. Vai su "WooCommerce" → "Impostazioni" → "Avanzate" → "REST API"
3. Clicca su "Aggiungi chiave"

Passo 2: Crea le Credenziali API

1. Compila il form:
   • Descrizione: Es. "AletheIA Integration"
   • Utente: Seleziona un utente amministratore
   • Permessi: Seleziona "Lettura" (per leggere gli ordini)
2. Clicca su "Genera chiave API"
3. Copia e salva:
   • Consumer Key
   • Consumer Secret

Passo 3: Configura in AletheIA

1. Vai su Integrazioni → WooCommerce
2. Inserisci lo Store URL (URL completo del tuo sito WordPress, es: https://example.com)
3. Inserisci la Consumer Key
4. Inserisci la Consumer Secret
5. Salva la configurazione

🛍️ PrestaShop

Passo 1: Abilita il Web Service

1. Accedi al tuo PrestaShop Back Office
2. Vai su "Parametri avanzati" → "Web Service"
3. Assicurati che "Abilita PrestaShop Web Service" sia attivo
4. Clicca su "Salva"

Passo 2: Crea una Chiave API

1. Nella stessa pagina, scorri fino a "Aggiungi nuovo Web Service key"
2. Compila il form:
   • Chiave: Genera una chiave univoca (o lascia generare automaticamente)
   • Descrizione: Es. "AletheIA Integration"
   • Stato: "Abilitato"
3. Nella sezione "Permessi", abilita:
   • orders - GET (per leggere gli ordini)
4. Clicca su "Aggiungi"
5. Copia la chiave API generata

Passo 3: Configura in AletheIA

1. Vai su Integrazioni → PrestaShop
2. Inserisci lo Store URL (URL completo del tuo store PrestaShop, es: https://example.com)
3. Inserisci l'API Key copiata
4. Salva la configurazione

👥 Microsoft Teams

Passo 1: Crea un Webhook Incoming

1. Apri Microsoft Teams
2. Vai al canale dove vuoi ricevere le notifiche
3. Clicca sui "..." (tre puntini) accanto al nome del canale
4. Seleziona "Connettori"
5. Cerca "Webhook Incoming" e clicca su "Configura"

Passo 2: Configura il Webhook

1. Inserisci un nome per il webhook (es: "AletheIA Notifiche")
2. Opzionalmente, carica un'immagine per il webhook
3. Clicca su "Crea"

Passo 3: Copia l'URL del Webhook

1. Dopo la creazione, vedrai l'URL del Webhook
2. Formato: https://outlook.office.com/webhook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/IncomingWebhook/xxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
3. Copia questo URL - non potrai visualizzarlo di nuovo
4. Se lo perdi, dovrai creare un nuovo webhook

Passo 4: Configura in AletheIA

1. Vai su Integrazioni → Microsoft Teams
2. Incolla l'URL del Webhook nel campo corrispondente
3. Salva la configurazione
4. Usa "Test Connessione" per verificare che tutto funzioni

🔒 Sicurezza e Best Practices

• Non condividere mai token o credenziali pubblicamente
• Usa token con permessi minimi necessari per la funzionalità
• Ruota i token periodicamente se possibile
• Monitora l'uso dei token per rilevare attività sospette
• Usa HTTPS per tutti gli endpoint webhook
• Valida i dati ricevuti dai webhook prima di processarli

🔄 Migrazioni Database Automatiche

AletheIA include un sistema automatico di migrazioni che verifica e applica le modifiche al database ad ogni avvio.

Come Funziona

Ad ogni avvio del software, il sistema:

1. Verifica se ci sono nuove tabelle da creare
2. Controlla se ci sono nuove colonne da aggiungere alle tabelle esistenti
3. Crea gli indici mancanti
4. Applica automaticamente tutte le modifiche necessarie

Vantaggi

• Aggiornamenti Automatici: Non devi eseguire manualmente script di migrazione
• Sicurezza: Il sistema non elimina mai dati esistenti, aggiunge solo ciò che manca
• Compatibilità: Gestisce correttamente SQLite e le sue limitazioni
• Log Dettagliati: Mostra un riepilogo delle operazioni eseguite all'avvio

Cosa Viene Controllato

• Tabelle: Crea automaticamente le tabelle mancanti definite nei modelli
• Colonne: Aggiunge colonne mancanti alle tabelle esistenti
• Indici: Crea gli indici mancanti per ottimizzare le query

Gestione Errori

Il sistema è progettato per essere resiliente:

• Se una colonna esiste già, viene ignorata (non genera errori)
• Se una tabella esiste già, viene ignorata
• Gli errori vengono loggati ma non bloccano l'avvio del sistema
• In caso di errori critici, il sistema mostra un avviso ma continua l'esecuzione

Output all'Avvio

Quando avvii il software, vedrai messaggi come:

• ✅ Tabelle database inizializzate
• ✅ Migrazioni applicate: X tabelle create
• ✅ Migrazioni applicate: X colonne aggiunte
• ✅ Migrazioni applicate: X indici creati
• ✅ Database già aggiornato, nessuna migrazione necessaria

Note Tecniche

• Il sistema è compatibile con SQLite e gestisce correttamente le limitazioni di ALTER TABLE
• Per colonne NOT NULL senza default, SQLite le crea come NULL (compatibilità)
• I default callable (come datetime.utcnow) vengono gestiti correttamente
• Le migrazioni vengono eseguite dopo la creazione iniziale delle tabelle con db.create_all()

Quando Vengono Eseguite

Le migrazioni vengono eseguite automaticamente:

• Ad ogni avvio del software
• Prima che l'applicazione inizi a servire richieste
• Dopo l'inizializzazione del database

Non è richiesta alcuna azione manuale - il sistema gestisce tutto automaticamente.