Documentazione di Fulgoria

Fulgoria estrae dati strutturati da documenti che sono stati progettati per essere letti, non analizzati. Gli insegni un layout una sola volta marcando le colonne; da quel momento legge ogni documento di quel tipo e ti restituisce CSV pulito. Tutto ciò che segue avviene nel tuo browser.

Il flusso

1. Apri un documento

Fai clic su Apri PDF o immagine e scegli un file, oppure seleziona Vedi un esempio per caricare un estratto conto di prova. Sono accettati sia PDF digitali sia scansioni o foto. Scansioni e immagini vengono lette con OCR locale (Tesseract.js), così anche un’immagine di un estratto conto diventa testo senza lasciare la tua macchina.

2. Marca le colonne

Fulgoria rileva automaticamente le colonne come primo passaggio. Le rifinisci trascinando sul documento per indicare dove si trova ciascun dato. Poi assegna un ruolo a ciascuna colonna:

date — la data della transazione
description — il concetto o il beneficiario
debit / credit / amount with sign — il valore del movimento
balance — il saldo progressivo
text — qualsiasi altra colonna che desideri conservare

Puoi anche applicare una formattazione libera, in stile Excel per colonna (pattern di date e numeri, WYSIWYG) e impostare regole di esclusione in base al contenuto per saltare intestazioni ripetute, righe “TOTALI” e rumore simile.

3. Modifica prima di esportare

Un editor in stile foglio di calcolo ti permette di correggere qualsiasi cella, con il saldo ricalcolato in tempo reale. Supporta trova e sostituisci, aggiunta ed eliminazione di righe, incolla da Excel, annulla/ripeti, riempimento verso il basso, categorizzazione assistita, flag di qualità, e valori di apertura/chiusura modificabili.

4. Esporta

Quando i dati sono puliti, esportali:

CSV — i movimenti, pronti per un foglio di calcolo o il tuo strumento di contabilità.
Modello — la geometria come file riutilizzabile .ext.json o .ext.yaml (vedi sotto).
Invia a Escriba — passa il risultato pulito al tuo Escriba locale.

Formati supportati

Ingresso

PDF digitali e scansioni / immagini (PNG, JPG e simili). Documenti multi-pagina e PDF multi-conto — per esempio pesos e dollari in un unico file — producono una scheda per conto.

Uscita

CSV per i movimenti, e file modello in .ext.json o .ext.yaml per il layout. Un passaggio “Invia a Escriba” trasferisce il risultato al resto della suite.

Modelli riutilizzabili

La prima volta che marchi l’estratto conto di una banca, Fulgoria può salvare quel layout come modello. La volta successiva che apri un documento dello stesso tipo, viene riconosciuto automaticamente e le colonne sono già al loro posto — nessuna nuova marcatura.

I modelli possono essere caricati da un file .json scaricato o scelti tra i tuoi modelli salvati all’interno dell’app.

Privacy: local-first per progettazione

Tutto viene eseguito nel tuo browser. Il PDF viene aperto, letto ed elaborato dentro la tua macchina, e non c’è nemmeno una singola richiesta esterna — font e librerie sono incorporati nell’app. La privacy non è una funzionalità aggiunta; è l’architettura.

Quando Fulgoria è self-hosted, il server leggero continua a non ricevere mai il documento. Si limita a servire i file statici e a gestire il login opzionale. Applica una CSP rigorosa e header di sicurezza, e non espone mai .env, server.js o alcun campione privato.

Per la produzione, Fulgoria include un server leggero (server.js, Node/Express) i cui unici compiti sono servire l’app statica e proteggerla dietro un login opzionale letto da .env.

Con login
Senza login

Imposta AUTH_ENABLED=true e configura AUTH_USER e AUTH_PASSWORD. Le sessioni sono firmate con SESSION_SECRET e durano SESSION_TTL_HOURS ore. Dietro HTTPS, mantieni COOKIE_SECURE=true.

Imposta AUTH_ENABLED=false per servire l’app senza password — comodo per l’uso locale o una rete privata fidata.

Genera un hash bcrypt della password e un segreto di sessione così:

node server.js --hash 'your-password'   # → AUTH_PASSWORD
openssl rand -hex 32                     # → SESSION_SECRET

Riferimento di configurazione

Tutte le impostazioni risiedono in .env:

Variabile	Predefinito	Scopo
`PORT`	`3000`	Porta del server.
`AUTH_ENABLED`	`true`	Attiva o disattiva il login.
`AUTH_USER`	`diego`	Nome utente di login.
`AUTH_PASSWORD`	(vuoto)	Password in testo in chiaro o hash bcrypt.
`SESSION_SECRET`	(vuoto)	Firma il cookie di sessione.
`SESSION_TTL_HOURS`	`12`	Durata della sessione in ore.
`COOKIE_SECURE`	`true`	`true` dietro HTTPS, `false` per `http://` locale.
`ESCRIBA_URL`	(vuoto)	Destinazione di “Invia a Escriba”; se vuoto, ripiega su `/`.