Questa raccolta raccoglie i tutorial della piattaforma LCA Lightning. Ogni guida descrive una feature reale dell'interfaccia utente o del backend, con i passi da seguire, i prerequisiti, gli endpoint API e le tabelle DB coinvolte. I contenuti sono allineati al codice sorgente corrente: nessuna funzione fittizia, nessun placeholder.
Autenticazione e Isolamento Tenant
Keycloak OIDC, NextAuth, Google OAuth broker, criteri RLS (Row-Level Security), schemi tenant vs schema condiviso, isolamento sub-account.
Il flusso di autenticazione è: Browser → NextAuth → Keycloak OIDC → JWT con claim tenant_schema e current_user_role. Il daemon imposta search_path a "<client_id>, impact_analytics, ..." per ogni richiesta. Il connettore usa la colonna tenant_id per l'isolamento a livello di riga nello schema condiviso. I criteri RLS applicano tenant + ruolo su sku_mappings, bom_components, paid_invoice_products, impact_records e altre tabelle.
Prerequisiti
Stack avviato (vedi Getting Started)Keycloak configurato con realm lca-ecosystem
Passi per l'esecuzione
PASSO 1
Login
Browser → NextAuth → Keycloak OIDC → JWT con i claim tenant_schema e current_user_role
PASSO 2
Isolamento del daemon
search_path impostato su "<client_id>, impact_analytics, ..." per ogni richiesta tramite engine.py
PASSO 3
Isolamento del connettore
Colonna tenant_id in impact_analytics.sku_mappings; nessun search_path; resolve_tenant_id() da user_subscriptions
PASSO 4
Applicazione RLS
I GUC app.current_tenant e app.current_user_role sono impostati per richiesta; i criteri sono attivi su sku_mappings, bom_components, paid_invoice_products, impact_records
Il BOM Designer permette di creare prodotti con componenti, categoria (settore Exiobase per calcolo monetario o entità LCA per calcolo fisico), prezzo, quantità e unità di misura. Salvando un prodotto, composition_pct (monetario) o unit_amount + unit (fisico) vengono scritti in bom_components. Al momento della fatturazione, InvoiceImpactWriter alloca amount_eur tra gli SKU sulla base di price × qty. I componenti fisici aggiungono kg absoluti; i componenti monetari allougono spend. REGOLA IMPATTI: se il prodotto ha componenti (ricetta BOM), il suo impatto è la somma degli impatti dei figli (allocata per valore per i monetari, per massa per i fisici). Se non ha componenti, l'impatto è calcolato sul record del padre stesso (prezzo × fattore settore). Un componente monetario senza price_eur né composition_pct non contribuisce (peso 0, gli altri vengono rinormalizzati) e il salvataggio è bloccato; un componente fisico senza unit_amount/unit viene rifiutato.
Prerequisiti
Stack avviatoUtente autenticato con tenant attivo
Passi per l'esecuzione
PASSO 1
Seleziona la categoria
Usa SearchableCategorySelect — settore Exiobase (monetario) o entità LCA (fisico)
PASSO 2
Salva il prodotto
composition_pct (monetario) oppure unit_amount + unit (fisico) scritto in bom_components
PASSO 3
Settola la fattura
InvoiceImpactWriter alloca amount_eur tra gli SKU con la logica price × qty
Esistono tre pipeline di ingestione dati ERP. Simple (Tier 0-1): inserimento diretto in sku_mappings e bom_components, senza SemanticMapper, senza LLM, senza grafo ontologico. Ontologia (Tier 2-3): matching semantico con i grafi Oxigraph urn:ontology:source e urn:ontology:mapped. bCLEARer (Tier 4): ricostruzione ERP completa — fatture, payroll, CRM, abbonamenti, e-commerce, spedizioni, produzione, utilities, dogana. L'endpoint universale è POST /api/v1/ingest/{tenant}/{component}. Il parametro meta_sector è stato rimosso da tutte le rotte.
I lotti di ingestione separati sono accettabili — il sink usa ON CONFLICT (tenant_id, sku) DO UPDATE
L'endpoint corretto per Tier4 è /api/v1/ingest/{tenant}/full_erp (non /ui_bom/product che non esiste)
Scenario A produce risultati identici al 100% a Simple/Ontologia con lo stesso input
Fonti Dati Ambientali LCA
Exiobase, USLCI, Agribalyse, eLCI, USEEIO, CPC, ISIC, TianGong — inventario sorgente, licenze, formati, tassonomie e come vengono abbinate ai prodotti.
I dati Exiobase IOT_*_pxp.zip si trovano in var/data/exiobase/. Il file impacts/F.txt contiene gli impatti pre-caratterizzati LCIA, da normalizzare con x.txt output (M.EUR). Attenzione critica: ogni impatto appare in MOLTEPLICI metodi LCIA (CML, ILCD, AR5) — sceglierne UNO per indicatore, mai sommare (climate_change si gonfia circa 2,9x). Trappole unità: acqua = Mm3, suolo = km2. I prodotti vengono normalizzati (minuscolo, rimuovi rumore marca/spec), classificati su CPC 2.1/NAICS 2022/ISIC Rev 4 tramite grafo ontologico, quindi abbinati via alias SKOS o matching semantico (≥0.70). reference_unit determina il tracciato: kg/kWh/item → fisico; M.EUR/USD → monetario.
La bacheca Kanban (/kanban) mostra ticket, assegnazioni ed eventi calendario in cinque colonne: open, bot_processing, in_progress, requires_human, closed. I ticket usano numeri #TKT-xxx, le assegnazioni #ASN-xxx, i sottocomponenti #TSK-xxx. Ogni elemento ha estimated_hours (visualizzabile come badge arancione), priorità, assegnatario, creatore e stato. L'editore inline consente di modificare titolo, descrizione, categoria, priorità, assegnatario e ore stimate. Le assegnazioni richiedono un assegnatario obbligatorio (stesso tenant).
Prerequisiti
Stack avviatoUtente autenticato
Passi per l'esecuzione
PASSO 1
Apri la bacheca Kanban
Vai su /kanban per vedere ticket, assegnazioni ed eventi calendario
PASSO 2
Crea un'assegnazione
Usa !create_assignment o la modale UI per definire titolo, priorità e membri del team assegnati
PASSO 3
Aggiungi sottocomponenti nidificati
Aggiungi sottocomponenti granulari con riferimenti a tag (#TKT-101, #TSK-202)
PASSO 4
Escalona allo staff
Quando un bot incontra problemi complessi, l'esecuzione segnala requires_human = TRUE
PASSO 5
Esegui il takeover umano
I membri dello staff eseguono !takeover_ticket per ottenere il controllo esclusivo della chat live
Sincronizza thread di email fornitori tramite Himalaya CLI gateway, analizza automaticamente allegati PDF fatture e programma eventi di audit collaborativo nelle stanze Matrix.
Prerequisiti
Credenziali IMAP/SMTP del provider email
Passi per l'esecuzione
PASSO 1
Configura IMAP/SMTP
Vai su Impostazioni Chat → Impostazioni Email per inserire host IMAP (porta 993) e host SMTP (porta 465/587)
PASSO 2
Sincronizzazione automatica fatture
Esegui !email sync o lascia che i worker in background analizzino gli allegati fattura in arrivo
PASSO 3
Programma evento calendario di squadra
Crea eventi di calendario collegati a ticket di supporto specifici (#TKT-xxx) o assegnazioni (#ASN-xxx)
PASSO 4
Invita sub-account
Tagga membri del team (@user) per popolare automaticamente le loro aree Kanban e Calendario
PASSO 5
Esporta feed iCal
Sincronizza eventi di squadra con client esterni Outlook, Google Calendar o Apple Calendar
Consigli e Best Practice
Gli allegati email caricati tramite Himalaya vengono indicizzati automaticamente nella ricerca vector RAG
Gli eventi calendario si collegano automaticamente agli assegnamenti e alle fatture fornitori genitore
Chiavi API dei Provider LLM
Collega le tue chiavi API dei provider AI per l'assistente LCAgent.
Nelle impostazioni della chat, aggiungi la tua chiave API per qualsiasi provider supportato (OpenAI, Anthropic, Gemini, xAI, OpenRouter, DeepSeek, Groq, Mistral, Together, Fireworks, Cohere, Nous, Cerebras, SambaNova o Ollama locale). Le chiavi sono memorizzate nel tuo profilo tenant isolato e usate da LCAgent per rispondere in linguaggio naturale. La piattaforma spedisce con un modello OpenRouter predefinito; aggiungi la tua chiave per usare un provider o modello diverso.
Prerequisiti
Chiave API del provider scelto
Passi per l'esecuzione
PASSO 1
Apri le impostazioni della chat
Vai alla pagina Chat e apri il pannello impostazioni
PASSO 2
Scegli un provider
Scegli un provider dalla lista (OpenAI, Anthropic, Gemini, xAI, OpenRouter, DeepSeek, Groq, Mistral, Together, Fireworks, Cohere, Nous, Cerebras, SambaNova o Ollama)
PASSO 3
Incolla la tua chiave API
Incolla la chiave dalla console del provider. Ogni provider collega alla sua pagina chiavi
PASSO 4
Ollama (opzionale)
Per Ollama locale la chiave è opzionale — esegui Ollama in locale e LCAgent può usarlo
PASSO 5
Salva
Salva le impostazioni. Solo i provider con chiave configurata sono offerti a LCAgent
Consigli e Best Practice
La piattaforma spedisce con un modello OpenRouter predefinito; aggiungi la tua chiave per usare un provider o modello diverso
Ogni profilo tenant è isolato — le tue chiavi non vengono mai condivise con altri tenant
Usa Ollama locale quando vuoi tenere i prompt completamente sulla tua infrastruttura
Trascrizioni Vocali e Sintesi Audio Istantanee
Trasforma registrazioni audio/video e note vocali in trascrizioni con timestamp e sintesi automatiche di azioni CSRD.
Carica registrazioni audio/video (MP3, WAV, M4A, MP4) oppure parla nel microfono per ottenere trascrizioni con timestamp ed estrazione automatica di elementi d'azione ESG.
Prerequisiti
File audio/video (MP3, WAV, M4A, MP4) o microfono
Passi per l'esecuzione
PASSO 1
Apri l'ingestione audio
Vai su Chat (/chat) o Admin Document Ingestion
PASSO 2
Registra o trascina il file
Clicca l'icona Microfono o trascina una registrazione MP3/WAV/MP4
PASSO 3
Rilevamento automatico lingua
Whisper rileva automaticamente inglese, tedesco, italiano, francese o spagnolo
PASSO 4
Rivedi la trascrizione con timestamp
Ispeziona la scomposizione altoparlante riga per riga con ancoraggi timestamp
PASSO 5
Genera sintesi esecutiva
Estrazione con un clic che inserisce elementi attivi direttamente nei tuoi ticket Kanban
Consigli e Best Practice
Le trascrizioni isolano automaticamente termini di sostenibilità (kWh, diesel, dati fornitori Scope 3)
Allega le sintesi direttamente ai componenti BOM per piste di conformità ISO 14040
Upload Documenti e Scoperta Semantica Vector
Trasforma fatture, fogli di calcolo e bollette in conoscenza verificabile con citazioni.
Connetti il tuo agente Hermes a qualsiasi server MCP (solo HTTP — il trasporto stdio NON è supportato) per strumenti personalizzati. Dopo aver aggiunto o aggiornato un server, digita !mcp reload in chat per applicare le modifiche.
Prerequisiti
URL server MCP (HTTP)Profilo Hermes configurato
Passi per l'esecuzione
PASSO 1
Apri le impostazioni del profilo
Vai su Chat → Impostazioni → Server MCP (o modifica ~/.hermes/profiles/@user/settings.json)
PASSO 2
Aggiungi configurazione server MCP
Aggiungi una voce sotto "mcp_servers" con "url" (solo HTTP), più header opzionali per token di autenticazione
PASSO 3
Salva la configurazione
Salva il file impostazioni. Il gateway lo legge alla richiesta successiva
PASSO 4
Ricarica MCP in chat
Digita !mcp reload in qualsiasi chat con @lcagent. Il gateway si riconnette a tutti i server configurati e riscopre gli strumenti
PASSO 5
Usa gli strumenti MCP naturalmente
Chiedi all'agente di usare i nuovi strumenti — appaiono come mcp_{server}_{tool} e vengono chiamati automaticamente dall'LLM
Consigli e Best Practice
Usa !mcp status per vedere tutti i server configurati, stato connessione e numero strumenti scoperti
I server HTTP supportano header per richiesta (es. token autenticazione). Il trasporto stdio NON è supportato — solo server MCP HTTP possono essere connessi
Dopo qualsiasi modifica alle impostazioni, esegui sempre !mcp reload in chat — il gateway non fa hot-reload della configurazione MCP
Installa il Server MCP LLCA sui Tuoi Client
Connetti Claude Desktop, Cursor, VS Code o qualsiasi client MCP alla piattaforma LLCA.
La piattaforma spedisce il proprio server MCP (llca-mcp). Punta qualsiasi client MCP compatibile ad esso per interrogare dati impatto LCA, preventivi spedizioni e stato ingestione direttamente dai tuoi strumenti — senza copia-incolla tra app.
Prerequisiti
Chiave API profilo (Chat → Impostazioni → API Auth)Client MCP (Claude Desktop, Cursor, VS Code, Windsurf)
Passi per l'esecuzione
PASSO 1
Ottieni l'URL dell'endpoint
Il server MCP LLCA è esposto dal reverse proxy all'indirizzo https://dt.tail8b188d.ts.net/mcp (HTTPS, stesso host della dashboard)
PASSO 2
Ottieni una chiave API
In Chat → Impostazioni → API Auth, copia la chiave API del tuo profilo. Ogni richiesta MCP deve portarla nell'header X-API-Key così il server può risolvere a quale tenant appartiene la query
PASSO 3
Aggiungi il server al tuo client
Incolla il snippet JSON per il tuo client (Claude Desktop, Cursor, VS Code, Windsurf) dal blocco di configurazione sottostante. Tutti prendono la stessa forma: nome server, url e mappa header con la tua chiave API
PASSO 4
Riavvia il client
La maggior parte dei client legge la configurazione MCP solo all'avvio, quindi esci completamente e riapri l'app. Il server LLCA dovrebbe allora apparire nell'elenco strumenti del client
PASSO 5
Verifica la connessione
Chiedi al client di "elenca gli strumenti disponibili dal server llca". Dovresti vedere gli strumenti della piattaforma (a partire da estimate_freight_quote, con altri aggiunti nel tempo)
PASSO 6
Usalo in linguaggio naturale
Chiedi al client una domanda normale, es. "stima spedizione per 12 kg da IT a DE". Il client sceglie lo strumento LLCA, lo chiama tramite JSON-RPC e ti mostra la risposta della piattaforma
Endpoint API
https://dt.tail8b188d.ts.net/mcp
Consigli e Best Practice
Solo il trasporto HTTP è supportato dal server MCP LLCA. I client che richiedono un comando stdio locale non funzioneranno direttamente — usa un client capace HTTP o un ponte HTTP-to-stdio
Tieni segreta la tua chiave API: identifica il tuo tenant. Chiunque la possieda può interrogare i tuoi dati della piattaforma tramite il server MCP
Il server parla JSON-RPC 2.0 su POST /mcp e annuncia la versione protocollo 2024-11-05 durante initialize
Connetti i Tuoi Client MCP a LCA
Genera una chiave API di sola lettura e incolla la configurazione client pronta.
Genera una chiave API di sola lettura e incolla la configurazione client pronta. Il ponte MCP valida la tua chiave contro il daemon e inoltra strumenti di sola letturaScoped strettamente al tuo tenant.
Prerequisiti
Tier 2+ per generare chiavi APIChiave API generata (mostrata una sola volta)
Passi per l'esecuzione
PASSO 1
Genera una chiave API
Apri Impostazioni → Chiavi API, clicca Genera chiave e copia la chiave grezza una volta (richiesto Tier 2+)
PASSO 2
Copia la tua configurazione client
Scegli il tuo client (Cursor, VS Code, Claude Code, Claude Desktop) e copia lo snippet pronto-da-incollare con la tua chiave
PASSO 3
Incolla nel tuo client
Incolla lo snippet nel file di configurazione del client (es. ~/.cursor/mcp.json) e riavvia il client
PASSO 4
Verifica con tools/list
Il tuo client dovrebbe elencare sei strumenti; un errore 401 significa che la chiave manca, è malformata o è stata revocata
PASSO 5
Rivedi il set di strumenti
Strumenti di sola lettura: ricerca/impatto catalogo, pagamenti, spedizioni, ticket, settori — tuttiScoped al tuo tenant
Consigli e Best Practice
Le chiavi sono di sola lettura per default e limitate al tuo tier — una chiave leakata non può scrivere né superare il tuo piano
Revoca una chiave da Impostazioni → Chiavi API; il ponte smette di accettarla entro ~45 secondi
Website Builder e Generatore Storefront Istantaneo
Distribuisci storefront custom su sottodominio tenant con badge impronta carbonio prodotto integrata e checkout Lightning sEUR.
Costruisci e lancia storefront custom sul tuo sottodominio tenant dedicato con badge impronta carbonio prodotto automatizzata e pagamento WebLN sub-secondo.
Prerequisiti
Stack avviatoCatalogo prodotti ERP sincronizzato
Passi per l'esecuzione
PASSO 1
Apri il Website Builder
Vai su /website-builder
PASSO 2
Personalizza il branding
Imposta titolo store, tagline, immagini di sfondo, font e colori
PASSO 3
Sincronizza il catalogo BOM
Importa articoli del catalogo direttamente dagli assemblaggi ERP
PASSO 4
Imposta flag spedizione fisica
Attiva "Richiede Spedizione Fisica" per articoli che necessitano preventivi logistici
PASSO 5
Distribuisci live
Clicca "Distribuis su Sottodominio" per lanciare il tuo store con WebLN e pagamenti QR
Consigli e Best Practice
Ogni prodotto mostra automaticamente badge impronta carbonio Scope 1-3 verificati
I clienti possono pagare in satoshi Lightning sub-secondo o rails sEUR stablecoin
Hub Merci e Spedizioni (Scoperta Vettore MCP)
Connetti server MCP vettore (DHL, Freightos) per preventivi spedizione dinamici e documenti di trasporto.
Interroga server MCP vettore (DHL, Freightos) tramite strumenti JSON-RPC tools/list per preventivi acquirente in tempo reale, validazione indirizzo internazionale e manifest PDF.
Prerequisiti
Server MCP vettore configuratoIndirizzo acquirente
Passi per l'esecuzione
PASSO 1
Configura origine e URL MCP
Imposta indirizzo commerciante ed endpoint RPC server vettore nel Website Builder
PASSO 2
Scoperta capacità automatica
Il demone interroga il server MCP tramite JSON-RPC tools/list
PASSO 3
Validazione indirizzo acquirente
Gli acquirenti inseriscono l'indirizzo stradale nella barra anteprima store per preventivi istantanei
PASSO 4
Visualizza registro spedizioni Hub
Traccia bundle multi-SKU fattura e peso volumetrico aggregato (kg) e volume (m^3) in /shipments
PASSO 5
Spedisci e genera documento di trasporto
Clicca "Spedisci e Genera Etichetta" per emettere numeri di tracciamento e manifest PDF vettore
Consigli e Best Practice
Ordini multi-SKU sotto lo stesso hash pagamento Lightning vengono raggruppati in singoli colli vettore
Il registro prodotti spediti si sincronizza live con la tabella PostgreSQL shipped_products
Wallet Lightning e Motore Fiscale EU Automatizzato
Connetti nodi LND/Breez Lightning, gestisci saldi sEUR, traccia lo stato 0% imposta carbonio e esporta report XML SAF-T.
La pagina Target Loans (/target-loans) confronta due periodi (baseline e corrente) sugli stressor ambientali selezionati. Le categorie di impatto da confrontare sono caricate dinamicamente da /api/v1/bom/target-loans/categories, che legge le chiavi stressor distinte da paid_invoice_products.impact_data.satellite_per_eur. Non c'è più una lista hardcoded.
Prerequisiti
Fatture pagate con impact_data satellitare
Passi per l'esecuzione
PASSO 1
Configura periodi baseline e corrente
Imposta date inizio/fine per entrambi i periodi di confronto
PASSO 2
Seleziona stressor da confrontare
Scegli tra le categorie caricate dinamicamente dal server (CO2, CH4, N2O, NOx, SOx, PM10, PM2.5 e altri presenti nei dati)
PASSO 3
Esegui calcolo
Clicca Compute per ottenere delta assoluto e % riduzione per categoria
PASSO 4
Esamina risultati
Tabella con baseline, corrente, riduzione assoluta e % riduzione per ogni stressor
Endpoint API
GET /api/v1/bom/target-loans/categoriesPOST /api/v1/bom/target-loans
Tabelle DB coinvolte
impact_analytics.paid_invoice_products
Consigli e Best Practice
Le categorie sono tratte dai dati reali in Postgres (sku_mappings / paid_invoice_products), non da una lista fissa
Se nessuna categoria è abilitata, il sistema chiede di selezionarne almeno una
Pagina Log di Sistema
Visualizza, filtra e cerca i log dei container Docker spediti da Vector in TimescaleDB (observability.container_logs).
La pagina Logs (/logs) mostra i log dei container raccolti da Vector e inseriti in TimescaleDB. I filtri disponibili sono: service, node, container, level, date_range (dragbar 6 mesi) e search testuale. I filtri service/node/container usano matching fuzzy (ILIKE con wildcard) così puoi digitare ad esempio "dashboard" invece del nome esatto "lca-dashboard". Le date passate all'API vengono convertite in oggetti datetime (non stringhe ISO grezze) per evitare errori asyncpg.
Prerequisiti
Vector in esecuzione e DB TimescaleDB popolato
Passi per l'esecuzione
PASSO 1
Apri la pagina Logs
Vai su /logs
PASSO 2
Seleziona periodo
Usa la dragbar per scegliere l'intervallo temporale (max 6 mesi)
PASSO 3
Filtra per servizio/nodo/contenitore
Digita testo parziale (matching fuzzy) nei campi Service, Node, Container
PASSO 4
Filtra per livello
Scegli all/debug/info/warn/error/fatal
PASSO 5
Cerca nei messaggi
Usa il campo di ricerca testuale per filtrare il campo message
Endpoint API
GET /api/v1/analytics/logsGET /api/v1/analytics/logs/graph
Tabelle DB coinvolte
observability.container_logs
Consigli e Best Practice
I log della dashboard potrebbero non apparire di default perché servizi ad alto volume (lca-daemon, lca-erp-connector) occupano le prime 200 righe — usa il filtro Service name "dashboard"
I log lca-dashboard sono presenti nel DB (servizio lca-dashboard, tenant platform e 123)
I log sono tenant-scoped tramite RLS: vedrai solo quelli del tuo tenant o tenant_id = platform